design

type AliasViolation struct {
	// Token is the dotted path of the token whose alias is broken
	// (e.g. "color.brand.text").
	Token string
	// Path is the workspace-relative slash path of the source document the
	// token lives in (design/tokens/color.tokens.json).
	Path string
	// Line is the 1-based source line of the token leaf's value.
	Line int
	// Rule is the validator rule id (token_alias_dangling or
	// token_alias_cycle), so the refusal uses the same vocabulary as
	// design_validate.
	Rule string
	// Kind is a short human label: "dangling" or "cycle".
	Kind string
	// Message is the validator's finding message (already names the token
	// and, for cycles, the member loop).
	Message string
}

type AssetRow struct {
	Path    string `json:"path"`
	Kind    string `json:"kind"`
	Name    string `json:"name"`
	Status  string `json:"status,omitempty"`
	Summary string `json:"summary,omitempty"`
}

type BriefFeedback struct {
	// Path is the feedback file (workspace-relative) when one exists.
	Path string `json:"path,omitempty"`
	// Status is the §4d top-level status ("changes-requested", "resolved", …).
	Status string `json:"status,omitempty"`
	// Open is the number of annotations with `resolved: false`.
	Open int `json:"open"`
	// Total is the total annotation count in the file.
	Total int `json:"total"`
	// Pending reports whether the file still needs the agent's attention
	// (status changes-requested or at least one unresolved annotation, §4d).
	Pending bool `json:"pending"`
	// Resolution is the agent's closing note, when present.
	Resolution string `json:"resolution,omitempty"`
	// Notes are the open annotations' notes ("[area] note"), in file order.
	// Populated at full depth only.
	Notes []string `json:"notes,omitempty"`
}

type BriefFlowEdge struct {
	// Flow is the flow file (workspace-relative, e.g. design/flows/sign-up.mmd).
	Flow string `json:"flow"`
	// FlowName is the flow's stem (e.g. "sign-up").
	FlowName string `json:"flowName"`
	// Source / Target are the edge endpoints (node ids == wireframe stems).
	Source string `json:"source"`
	Target string `json:"target"`
	// Direction is "in" (the screen is the target), "out" (the screen is the
	// source), or "both" (a self-edge). It is the §5g "in/out" split.
	Direction string `json:"direction"`
	// Trigger is the edge label, i.e. what causes the transition (§5g
	// "triggers"). "" when the edge carries no label.
	Trigger string `json:"trigger,omitempty"`
	// OtherStem is the far endpoint of the edge (the node the screen moves to,
	// or comes from). "" for a self-edge.
	OtherStem string `json:"otherStem,omitempty"`
	// OtherLabel is the far endpoint's node label, when the flow declared one.
	OtherLabel string `json:"otherLabel,omitempty"`
}

type BriefTokenRef struct {
	// Path is the dotted token path (e.g. "color.brand.primary").
	Path string `json:"path"`
	// Known is true when the reference resolves to a DTCG leaf in
	// design/tokens/.
	Known bool `json:"known"`
}

type Confidence = string

type ContentReader interface {
	ReadFile(path string) ([]byte, error)
}

type DeltaBasis = deltaBasis

type DeltaKind = string

type DirtyAliasError struct {
	// Violations are the offending aliases, one per (rule, token) pair.
	Violations []AliasViolation
}

type DriftDirectionRow struct {
	// Direction is design-ahead | code-ahead (the stable row id).
	Direction string `json:"direction"`
	// Ahead is true when this direction actually holds (there is drift here).
	Ahead bool `json:"ahead"`
	// Synced is true when this direction has nothing ahead — the complement of
	// Ahead, explicit so a model reads "no drift" without a negation.
	Synced bool `json:"synced"`
	// Count is the concrete magnitude of the drift: screens ahead of the build
	// (design-ahead) or semantic deltas to import (code-ahead). 0 when Synced
	// or when nothing countable was found.
	Count int `json:"count"`
	// Summary is the one-line description of what is ahead ("2 screens ahead
	// of the exported theme"). Empty when Synced.
	Summary string `json:"summary,omitempty"`
	// Remedy is the run-me pointer for this direction (§5c): regenerate the
	// theme (design-ahead) or run design_sync (code-ahead). Empty when Synced.
	Remedy string `json:"remedy,omitempty"`
	// NextStep is the tool-level pointer the remedy names (the design_export_tokens
	// or design_sync call), stable so a consumer can route on it. Empty when Synced.
	NextStep string `json:"nextStep,omitempty"`
	// Advisory is the severity class: info (nothing to do) or warn (a remedy to
	// run). Drift is signal, never an error (§5c), so this is never "error".
	Advisory string `json:"advisory"`
}

type DriftReport struct {
	// Rows are the two direction rows, design-ahead then code-ahead.
	Rows []DriftDirectionRow `json:"rows"`
	// DesignAheadCount / CodeAheadCount mirror the rows for a reader that does
	// not want to index Rows.
	DesignAheadCount int `json:"designAheadCount"`
	CodeAheadCount   int `json:"codeAheadCount"`
	// Synced is true when neither direction is ahead.
	Synced bool `json:"synced"`
	// Evidence carries how each count was computed (the generated provenance
	// hash basis, the touched-file basis, or the offline fallback), so a model
	// can judge the confidence of a count. Deterministic order.
	Evidence []string `json:"evidence,omitempty"`
}

type ExportTarget struct {
	Name string
	File string
}

type ExportedArtifact struct {
	// Target is the exporter that produced it (css, ts, ...).
	Target string
	// RelPath is the workspace-relative slash path (design/generated/<file>).
	RelPath string
	// Content is the exact byte content written.
	Content []byte
	// Hash is the deterministic content hash (see tokenExportArtifactHash).
	Hash string
}

type ExportedToken struct {
	// Name is the dotted token path (e.g. "color.brand.primary").
	Name string
	// Type is the leaf's $type (one of the nine DTCG types).
	Type string
	// Value is the raw (unresolved) $value.
	Value any
	// Resolved is the transitive alias resolution of Value. For a whole-value
	// alias it is the final non-alias $value; for a plain value it is Value
	// itself; for a value with no final scalar (an alias to a group, an alias
	// chain that cannot end at a string, or a non-string structured value) it
	// is nil and ResolvedOK is false.
	Resolved any
	// ResolvedOK reports whether Resolved is usable.
	ResolvedOK bool
	// HasAlias is true when Value (or any link in its alias chain) is a
	// whole-value alias reference. Targets use it to decide between a literal
	// and a var()/token() reference.
	HasAlias bool
	// AliasPath is the dotted path of the first whole-value alias in the
	// chain (from Value itself, or the deepest resolvable link), used for
	// cross-token references. "" when HasAlias is false.
	AliasPath string
}

type FSScanner struct{}

type FeedbackFileState struct {
	// Path is the workspace-relative slash path of the feedback file
	// (e.g. "design/feedback/login.json").
	Path string `json:"path"`
	// Target is the §4d target (e.g. "design/wireframes/login.svg"); empty
	// when the file is invalid or omits it.
	Target string `json:"target,omitempty"`
	// Status is the §4d top-level status ("changes-requested", "resolved",
	// …); empty when absent.
	Status string `json:"status,omitempty"`
	// Resolution is the agent's closing note; empty while the loop is open.
	Resolution string `json:"resolution,omitempty"`
	// Annotations is the total annotation count.
	Annotations int `json:"annotations"`
	// Resolved is the count of annotations with `resolved: true`.
	Resolved int `json:"resolved"`
	// Pending is the count of annotations with `resolved: false` (i.e.
	// Annotations - Resolved); it is the count the agent must address.
	Pending int `json:"pending"`
	// Valid reports whether the file parsed as the §4d document shape.
	Valid bool `json:"valid"`
}

type Finding struct {
	// File is the design workspace path the finding applies to.
	File string

	// Line is the 1-based source line; 0 means the line was not
	// derivable.
	Line int

	Severity Severity
	Message  string
	Rule     string
}

type FlowCounts struct {
	Path  string `json:"path"`
	Name  string `json:"name"`
	Nodes int    `json:"nodes"`
	Edges int    `json:"edges"`
}

type FlowEdge struct {
	Source   string
	Target   string
	HasArrow bool
}

type FlowNode struct {
	ID    string
	Label string
}

type Flowchart struct {
	Direction    string
	Declarations int // number of flowchart/graph declaration lines
	Nodes        map[string]FlowNode
	Edges        []FlowEdge
	NodeOrder    []string // first-seen order of node ids
	BadLines     []int    // 1-based line numbers of statements that could not be parsed
}

type Frame struct {
	Name   string
	Width  int
	Height int
}

type Inventory struct {
	Assets      []AssetRow        `json:"assets"`
	TokenGroups []TokenGroupCount `json:"tokenGroups"`
	Flows       []FlowCounts      `json:"flows"`
	Manifest    ManifestSummary   `json:"manifest"`
	Findings    []Finding         `json:"findings"`
	BySeverity  map[string]int    `json:"bySeverity"`
}

type ManifestSummary struct {
	Exists bool     `json:"exists"`
	Frames []Frame  `json:"frames"`
	Status []string `json:"status"`
}

type ProviderWordHit struct {
	File string
	Line int
	Text string
}

type Scanner interface {
	// HasAnyDir reports whether any of the given filesystem paths exists and
	// is a directory.
	HasAnyDir(roots ...string) bool
	// HasAnyFile reports whether any of the given filesystem paths exists and
	// is a regular file.
	HasAnyFile(paths ...string) bool
	// WalkDir visits every regular, non-hidden file under root, honoring
	// SkipDir results. The callback receives the full path and the directory
	// entry so the caller can inspect the mode and control descent.
	WalkDir(root string, fn func(path string, d os.DirEntry, err error) error) error
}

type ScreenBrief struct {
	// ScreenName is the requested wireframe stem.
	ScreenName string `json:"screenName"`
	// Depth is the depth the brief was rendered at (summary|full).
	Depth string `json:"depth"`
	// Found reports whether the screen exists in the design tree (a wireframe
	// with that stem, or a feedback file targeting it). An unknown screen
	// yields Found=false with Guidance, never an error.
	Found bool `json:"found"`

	// Purpose is the screen's purpose from the README Screens listing (§5g
	// "README purpose"). "" when the README lists no entry for the screen.
	Purpose string `json:"purpose,omitempty"`
	// Status is the README status marker (draft|review|ready). "" when the
	// README declares none.
	Status string `json:"status,omitempty"`
	// ListedInReadme reports whether the README Screens listing names the
	// screen (the §4b inventory signal: an unlisted wireframe is an orphan).
	ListedInReadme bool `json:"listedInReadme"`

	// Wireframe is the wireframe path (design/wireframes/<stem>.svg). It is
	// always set: the brief names where the wireframe *would* live, so a
	// not-found brief still points the agent at the right file.
	Wireframe string `json:"wireframe"`
	// WireframeExists reports whether that file exists.
	WireframeExists bool `json:"wireframeExists"`

	// FlowsIn / FlowsOut are the flow edges touching the screen, split by
	// direction (§5g "flows in/out with triggers"). A self-edge appears in
	// both. Both are always non-nil.
	FlowsIn  []BriefFlowEdge `json:"flowsIn"`
	FlowsOut []BriefFlowEdge `json:"flowsOut"`

	// TokenPaths are the DTCG tokens the wireframe refers to, sorted by path
	// (§5g "token paths to consume").
	TokenPaths []BriefTokenRef `json:"tokenPaths"`
	// TokenGroups are the top-level token groups available to consume, sorted
	// by group — the tree's token vocabulary, so the agent knows what exists
	// even when the wireframe refers to nothing yet.
	TokenGroups []TokenGroupCount `json:"tokenGroups"`

	// Feedback is the §4d pending-feedback view for the screen (§5g "open
	// feedback annotations"). The matching feedback file is the one whose §4d
	// target resolves to the screen's stem, or — when no target matches — the
	// one whose own file name (stem) equals the screen; the first match by
	// path order wins (ScanFeedbackDir sorts by path).
	Feedback BriefFeedback `json:"feedback"`

	// ScreenFile is the delivered design/screens/<stem>.html path, when one
	// exists (full depth only when it differs from the wireframe).
	ScreenFile string `json:"screenFile,omitempty"`

	// Guidance is a not-found helper: what to do when the screen is unknown
	// ("" when the screen exists).
	Guidance string `json:"guidance,omitempty"`

	// Notes carry run-level caveats (e.g. a tree with no README).
	Notes []string `json:"notes,omitempty"`

	// WritesNothing states the §5g contract explicitly: the brief is read-only
	// advisory context, never a generator. Always true.
	WritesNothing bool `json:"writesNothing"`
}

type ScreenBriefInput struct {
	// Root is the workspace root (the parent of design/).
	Root string
	// ScreenName is the wireframe stem to brief.
	ScreenName string
	// Depth is summary|full; "" defaults to summary.
	Depth string
}

type Severity string

type SyncApplyPlan struct {
	// Mode is always "apply" (this is the apply half's plan).
	Mode string `json:"mode"`
	// Report is the analyze report the plan was derived from, so a consumer can
	// see the full delta set behind a partial apply.
	Report *SyncReport `json:"report"`
	// Writes is the ordered safe-subset write set (deterministic, design/-only).
	Writes []SyncApplyWrite `json:"writes"`
	// Proposals are the deltas apply deliberately left unwritten (inferred
	// proposals, plus any unsafe/unplannable delta).
	Proposals []SyncApplyProposal `json:"proposals"`
	// Refused are design-file writes that were suppressed because a write would
	// have escaped design/ (§5e). Always empty in a plan produced by
	// PlanSyncApply, which drops such writes; kept so a consumer can distinguish
	// "nothing to apply" from "something was refused".
	Refused []string `json:"refused,omitempty"`
	// AppliedCount / ProposalCount are the write and proposal tallies.
	AppliedCount  int `json:"appliedCount"`
	ProposalCount int `json:"proposalCount"`
	// WritePaths is the sorted set of distinct design/ paths the plan writes,
	// surfaced so a caller can assert design/-confinement without walking Writes.
	WritePaths []string `json:"writePaths"`
	// Notes carries run-level caveats (e.g. a malformed token file a write
	// could not be planned from).
	Notes []string `json:"notes,omitempty"`
}

type SyncApplyProposal struct {
	// Delta is the semantic delta description.
	Delta string `json:"delta"`
	// Kind is the delta kind.
	Kind DeltaKind `json:"kind"`
	// Basis is literal|structural|inferred.
	Basis deltaBasis `json:"basis"`
	// Reason is why apply left it alone: "inferred" (§5b proposal),
	// "outside-design" (§5e refusal), or a specific refusal message.
	Reason string `json:"reason"`
	// ProposalKind / Proposed carry the §5b proposal fields when the delta is
	// an inferred proposal.
	ProposalKind string `json:"proposalKind,omitempty"`
	Proposed     string `json:"proposed,omitempty"`
	// CodeFiles are the touched code files the delta came from.
	CodeFiles []string `json:"codeFiles"`
}

type SyncApplyWrite struct {
	// Path is the design/ file to write, workspace-relative.
	Path string `json:"path"`
	// Op is the planning operation that produced this write.
	Op SyncPlanningOp `json:"op"`
	// Kind is the delta kind (token|wireframe|flow) this write serves, so a
	// consumer can group the run by the §5b vocabulary.
	Kind DeltaKind `json:"kind"`
	// Delta is the semantic delta description this write applies.
	Delta string `json:"delta"`
	// Token is the DTCG token path the write concerns ("" otherwise).
	Token string `json:"token,omitempty"`
	// Stem is the wireframe stem the write concerns ("" otherwise).
	Stem string `json:"stem,omitempty"`
	// Edge is the flow edge the write adds ("" otherwise).
	Edge string `json:"edge,omitempty"`
	// Status is the status marker the artifact carries (draft for §5b-created
	// artifacts; "" for a token revalue).
	Status string `json:"status,omitempty"`
	// Created is true when the write creates a file that did not exist.
	Created bool `json:"created"`
	// Content is the full new file bytes. It is deliberately JSON-omitted:
	// the plan's JSON shape names *what* will be written, and the handler is
	// the one that writes it; a consumer needing the bytes reads the file
	// after apply.
	Content []byte `json:"-"`
}

type SyncDelta struct {
	// Delta is the one-line description of the detected change.
	Delta string `json:"delta"`
	// Kind is token|wireframe|flow|feedback.
	Kind DeltaKind `json:"kind"`
	// Basis is literal|structural|inferred.
	Basis deltaBasis `json:"basis"`
	// Confidence is high|medium|low.
	Confidence Confidence `json:"confidence"`
	// DesignFiles are the design/ paths this delta would touch, sorted and
	// slash-separated, workspace-relative. Always non-nil (possibly empty) so
	// the JSON shape is stable; empty means "the semantic layer has no
	// counterpart yet" (apply's job to create one, subject to basis).
	DesignFiles []string `json:"designFiles"`
	// SafeToApply is the automation gate: true for literal and structural
	// deltas, false for inferred (and for any delta whose basis could not be
	// established). Redundant with Basis but explicit for a model reading the
	// report.
	SafeToApply bool `json:"safeToApply"`
	// Proposal marks an inferred delta: a proposal (new token, or switch to an
	// existing one), never auto-applied.
	Proposal bool `json:"proposal,omitempty"`
	// ProposalKind is new-token|switch-to-existing for an inferred delta.
	ProposalKind string `json:"proposalKind,omitempty"`
	// Proposed is the proposed new token path (inferred, new token) or the
	// design/ path proposal ("" otherwise).
	Proposed string `json:"proposed,omitempty"`
	// Candidate is the existing DTCG token path an inferred delta could switch
	// to, when one matches the literal value ("" otherwise).
	Candidate string `json:"candidate,omitempty"`
	// Token is the DTCG token path a token delta concerns ("" otherwise).
	Token string `json:"token,omitempty"`
	// TokenFile is the design/tokens/*.tokens.json the token lives in
	// ("" otherwise), from the token export machinery.
	TokenFile string `json:"tokenFile,omitempty"`
	// TokenEntry is the DTCG entry key as it appears in TokenFile: the
	// dotted token path for new/revalued entries, or the pre-change alias
	// target for a literal rename ("" otherwise).
	TokenEntry string `json:"tokenEntry,omitempty"`
	// WireframeStem is the proposed wireframe stem for a structural delta
	// ("" otherwise).
	WireframeStem string `json:"wireframeStem,omitempty"`
	// FlowEdge is the proposed flow edge ("login --> home") for a structural
	// delta ("" otherwise).
	FlowEdge string `json:"flowEdge,omitempty"`
	// FlowFile is the design/flows/*.mmd the edge would be added to
	// ("" otherwise).
	FlowFile string `json:"flowFile,omitempty"`
	// Status is the status a created artifact would carry (draft for
	// §5b-created wireframes/edges).
	Status string `json:"status,omitempty"`
	// CodeFiles are the touched code files this delta was detected in, sorted
	// and slash-separated.
	CodeFiles []string `json:"codeFiles"`
	// Evidence is the offending code snippet/line, trimmed (best-effort).
	Evidence string `json:"evidence,omitempty"`
}

type SyncFileInput struct {
	Path    string
	Content []byte
}

type SyncFileReader func(rel string) ([]byte, bool)

type SyncInput struct {
	// Root is the workspace root (the parent of design/).
	Root string
	// Touched are the code files to analyse. Paths may be absolute or
	// workspace-relative; Contents maps each path (as given) to its bytes.
	// A path with no content entry is skipped (advisory, named in Skipped).
	Touched []SyncFileInput
}

type SyncPlanningOp = string

type SyncReport struct {
	// Mode is the mode the report was produced in ("" for a bare analyze
	// call; apply mode is item 5.4). It is advisory metadata for a stored
	// report.
	Mode string `json:"mode,omitempty"`
	// TokensPath / WireframeDir / FlowsDir are the design-tier directories the
	// run cross-referenced, slash-separated and workspace-relative. They are
	// always present so the report reads as a design-tree lookup rather than a
	// bag of deltas.
	TokensPath   string `json:"tokensPath"`
	WireframeDir string `json:"wireframesPath"`
	FlowsDir     string `json:"flowsPath"`
	// TouchedCount is the number of touched code files analysed.
	TouchedCount int `json:"touchedCount"`
	// DeltaCount is the number of deltas; also broken out by Basis and Kind
	// so a model reads the automation split without counting.
	DeltaCount int            `json:"deltaCount"`
	ByBasis    map[string]int `json:"byBasis"`
	ByKind     map[string]int `json:"byKind"`
	// Deltas is the ordered semantic-delta work list (deterministic).
	Deltas []SyncDelta `json:"deltas"`
	// WritesNothing states the §5e invariant explicitly: analyze mode writes
	// no files, and apply (5.4) is confined to design/. Always true here.
	WritesNothing bool `json:"writesNothing"`
	// NextStep is a one-line pointer to the apply half / the skill loop, so a
	// model knows analyze is the first half.
	NextStep string `json:"nextStep"`
	// Skipped are touched paths the analysis could not read (missing on disk,
	// a directory, or not a recognised UI file). Advisory.
	Skipped []string `json:"skipped,omitempty"`
	// Notes carries human-readable caveats (e.g. "no design/ tree, so
	// literal deltas have no DTCG counterpart"). Deterministic order.
	Notes []string `json:"notes,omitempty"`
}

type TokenExport struct {
	Leaves []ExportedToken
	// InputHash is the §5f provenance hash of the token source documents this
	// projection was built from (see TokenExportInputHash). Every generated
	// artifact's header records it, so the artifact can be verified against
	// design/tokens/ at any checkout, offline.
	InputHash string
}

type TokenExportSource struct {
	// Path is the workspace-relative slash path of the source document.
	Path string
	// Name is the source document's base name (color.tokens.json); it is the
	// stable sort key, so the hash does not depend on the workspace root.
	Name string
	// Content is the document's exact bytes.
	Content []byte
}

type TokenGroupCount struct {
	Group  string `json:"group"`
	Tokens int    `json:"tokens"`
}