@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/empty-state-suggestion.json

@@ -0,0 +1,57 @@
+{
+  "name": "EmptyStateSuggestion",
+  "slug": "empty-state-suggestion",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One thing worth asking, as a pill. `index` staggers its entrance so the row arrives\nleft to right rather than all at once.",
+  "props": [
+    {
+      "name": "index",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Position in the row. Staggers the entrance so the pills arrive in order."
+    }
+  ],
+  "typeReferences": [
+    "ComponentProps<\"button\"> & {\n  /** Position in the row. Staggers the entrance so the pills arrive in order. */\n  index?: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "One thing worth asking, as a pill.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-suggestion",
+  "mdUrl": "/docs/components/empty-state-suggestion.md",
+  "jsonUrl": "/r/components/empty-state-suggestion.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-suggestions.json

@@ -0,0 +1,49 @@
+{
+  "name": "EmptyStateSuggestions",
+  "slug": "empty-state-suggestions",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The row the suggestion pills wrap in.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "The row the suggestion pills wrap in.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-suggestions",
+  "mdUrl": "/docs/components/empty-state-suggestions.md",
+  "jsonUrl": "/r/components/empty-state-suggestions.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/end-of-turn-summary.json

@@ -0,0 +1,77 @@
+{
+  "name": "EndOfTurnSummary",
+  "slug": "end-of-turn-summary",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "What the turn came to, in one line: `3 files changed +48 −12`.\n\nA rollup, not a control: it says what happened and offers nothing to do about\nit, because the things to do about it — review, keep, reject — belong to a\nbar above the composer that acts on the whole run, and a per-turn row with\nthose buttons on it is a row that can be pressed after the next turn has\nalready changed the same files.\n\nThe counts are drawn only when there are some. A turn that read four files\nand wrote nothing says `No files changed` and stops, rather than saying it\nwith two zeroes.",
+  "props": [
+    {
+      "name": "files",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many files the turn touched."
+    },
+    {
+      "name": "additions",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Lines added across them."
+    },
+    {
+      "name": "deletions",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Lines removed across them."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The whole line, replacing the one {@link formatChangeSummary} would build —\nfor a turn whose result is not a diff at all: `2 cues written`,\n`Nothing to change`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-ok",
+    "--cue-text-ui"
+  ],
+  "summary": "What the turn came to, in one line: `3 files changed +48 −12`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { EndOfTurnSummary } from \"@cueplusplus/ui/elements\";\n\n<EndOfTurnSummary files={3} additions={48} deletions={12} />\n<EndOfTurnSummary files={0} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/end-of-turn-summary",
+  "mdUrl": "/docs/components/end-of-turn-summary.md",
+  "jsonUrl": "/r/components/end-of-turn-summary.json",
+  "specimens": [
+    {
+      "title": "EndOfTurnSummary",
+      "group": "elements-thread",
+      "components": [
+        "EndOfTurnSummary"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three files\" wide>\n    <div className=\"w-full max-w-md\">\n      <EndOfTurnSummary files={3} additions={48} deletions={12} />\n    </div>\n  </Specimen>\n  <Specimen label=\"one file, additions only\" wide>\n    <div className=\"w-full max-w-md\">\n      <EndOfTurnSummary files={1} additions={6} />\n    </div>\n  </Specimen>\n  <Specimen label=\"nothing changed\" wide>\n    <div className=\"w-full max-w-md\">\n      <EndOfTurnSummary files={0} />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "What the turn came to, in one line. A rollup and not a control: review, keep and reject act on the whole run and belong above the composer, where they cannot be pressed after the next turn has already changed the same files. The + and − are CodeDiff's glyphs, so one transcript never shows two conventions for the same number, and a turn that changed nothing says so instead of saying it with two zeroes.",
+      "interaction": "none. It is a sentence with two tinted numbers in it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/error-state.json

@@ -0,0 +1,80 @@
+{
+  "name": "ErrorState",
+  "slug": "error-state",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A quiet failure banner with a retry path, not a modal in your face.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Primary failure headline shown in the banner."
+    },
+    {
+      "name": "detail",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Supporting detail under the title explaining what went wrong."
+    },
+    {
+      "name": "retrying",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the banner swaps to a spinning Retrying status instead of the error."
+    },
+    {
+      "name": "onRetry",
+      "type": "() => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the retry control is pressed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"role\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-radius-overlay",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A quiet failure banner with a retry path, not a modal in your face.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ErrorState } from \"@cueplusplus/ui/elements\";\n\n<ErrorState\n  title=\"Request failed\"\n  detail=\"The model timed out.\"\n  retrying={false}\n  onRetry={() => {}}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/error-state",
+  "mdUrl": "/docs/components/error-state.md",
+  "jsonUrl": "/r/components/error-state.json",
+  "specimens": [
+    {
+      "title": "ErrorState",
+      "group": "elements-agents",
+      "components": [
+        "ErrorState"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"failed\" wide>\n    <ErrorState\n      title=\"The desk refused the patch\"\n      detail=\"Universe 3 is not enabled on this show file. Enable it on the desk, or patch into universes 1 and 2.\"\n      retrying={false}\n      onRetry={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"retrying\" wide>\n    <ErrorState\n      title=\"The desk refused the patch\"\n      detail=\"Universe 3 is not enabled on this show file.\"\n      retrying\n      onRetry={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A failure banner, not a modal: it sits in the flow where the answer would have been, says what broke and what to do, and leaves the rest of the page alone. Retrying is a different element entirely rather than a disabled button — `role='alert'` while it is a failure, `role='status'` while it is trying again, which is the difference between interrupting a screen reader and not.",
+      "interaction": "Retry is a named button that tints on hover. The retrying state has no control at all, because there is nothing to press while it works."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/feedback-dialog.json

@@ -0,0 +1,107 @@
+{
+  "name": "FeedbackDialog",
+  "slug": "feedback-dialog",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A thumbs-down that asks why, so the signal arrives with a reason attached.",
+  "props": [
+    {
+      "name": "reasons",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The reason chips offered. Keep them short enough to scan in one line."
+    },
+    {
+      "name": "selected",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which reasons are currently picked. More than one is allowed."
+    },
+    {
+      "name": "note",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Free-text detail, always optional."
+    },
+    {
+      "name": "sent",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Replaces the whole form with an acknowledgement once the report is filed."
+    },
+    {
+      "name": "onToggleReason",
+      "type": "((reason: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a reason chip is picked or unpicked."
+    },
+    {
+      "name": "onNoteChange",
+      "type": "((note: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the free-text note is typed."
+    },
+    {
+      "name": "onSubmit",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the report is sent."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"reasons\"\n  | \"selected\"\n  | \"note\"\n  | \"sent\"\n  | \"onToggleReason\"\n  | \"onNoteChange\"\n  | \"onSubmit\"\n> & {\n  /** The reason chips offered. Keep them short enough to scan in one line. */\n  reasons: readonly string[];\n  /** Which reasons are currently picked. More than one is allowed. */\n  selected: readonly string[];\n  /** Free-text detail, always optional. */\n  note: string;\n  /** Replaces the whole form with an acknowledgement once the report is filed. */\n  sent: boolean;\n  /** Called when a reason chip is picked or unpicked. */\n  onToggleReason?: (reason: string) => void;\n  /** Called as the free-text note is typed. */\n  onNoteChange?: (note: string) => void;\n  /** Called when the report is sent. */\n  onSubmit?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A thumbs-down that asks why, so the signal arrives with a reason attached.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FeedbackDialog } from \"@cueplusplus/ui/elements\";\n\n<FeedbackDialog\n  reasons={[\"Not factual\", \"Too long\"]}\n  selected={selected}\n  note={note}\n  sent={sent}\n  onToggleReason={toggle}\n  onNoteChange={setNote}\n  onSubmit={send}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/feedback-dialog",
+  "mdUrl": "/docs/components/feedback-dialog.md",
+  "jsonUrl": "/r/components/feedback-dialog.json",
+  "specimens": [
+    {
+      "title": "FeedbackDialog",
+      "group": "elements-composer",
+      "components": [
+        "FeedbackDialog"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"collecting\" wide>\n    <FeedbackDialog\n      reasons={[\"Wrong universe\", \"Bad addressing\", \"Too slow\", \"Touched the desk\"]}\n      selected={reasons}\n      note={note}\n      sent={sent}\n      onToggleReason={(reason) =>\n        setReasons((current) =>\n          current.includes(reason)\n            ? current.filter((item) => item !== reason)\n            : [...current, reason],\n        )\n      }\n      onNoteChange={setNote}\n      onSubmit={() => setSent(true)}\n    />\n  </Specimen>\n  <Specimen label=\"sent\" wide>\n    <FeedbackDialog\n      reasons={[\"Wrong universe\", \"Bad addressing\"]}\n      selected={[\"Wrong universe\"]}\n      note=\"\"\n      sent\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A thumbs-down that asks why, so the signal arrives with a reason attached. The reasons are chips rather than a select because more than one is usually true, and the note is marked optional in the header — a feedback form that demands prose collects nothing. Sending replaces the whole form with an acknowledgement.",
+      "interaction": "each chip is `aria-pressed`. The acknowledgement lives in a `status` live region mounted from the start and empty until it is not — a region created together with its text is the case a screen reader is free to miss."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/file-tree.json

@@ -0,0 +1,83 @@
+{
+  "name": "FileTree",
+  "slug": "file-tree",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Everything a run touched, as a tree, with the churn spelled out per file.",
+  "props": [
+    {
+      "name": "nodes",
+      "type": "readonly FileTreeNode[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Flat list in display order. Nesting comes from each node's depth, not from\nchildren arrays."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many nodes have landed. Raise it as the run touches more files."
+    },
+    {
+      "name": "totalAdditions",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Added lines across the whole change."
+    },
+    {
+      "name": "totalDeletions",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Removed lines across the whole change."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"nodes\" | \"visibleCount\" | \"totalAdditions\" | \"totalDeletions\"\n> & {\n  /**\n   * Flat list in display order. Nesting comes from each node's depth, not from\n   * children arrays.\n   */\n  nodes: readonly FileTreeNode[];\n  /** How many nodes have landed. Raise it as the run touches more files. */\n  visibleCount: number;\n  /** Added lines across the whole change. */\n  totalAdditions: number;\n  /** Removed lines across the whole change. */\n  totalDeletions: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body"
+  ],
+  "summary": "Everything a run touched, as a tree, with the churn spelled out per file.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FileTree } from \"@cueplusplus/ui/elements\";\n\n<FileTree\n  nodes={nodes}\n  visibleCount={nodes.length}\n  totalAdditions={78}\n  totalDeletions={9}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/file-tree",
+  "mdUrl": "/docs/components/file-tree.md",
+  "jsonUrl": "/r/components/file-tree.json",
+  "specimens": [
+    {
+      "title": "FileTree",
+      "group": "elements",
+      "components": [
+        "FileTree"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"mid-run\" wide>\n    <FileTree nodes={TOUCHED} visibleCount={3} totalAdditions={12} totalDeletions={4} />\n  </Specimen>\n  <Specimen label=\"complete\" wide>\n    <FileTree\n      nodes={TOUCHED}\n      visibleCount={TOUCHED.length}\n      totalAdditions={60}\n      totalDeletions={6}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Everything a run touched, with the churn per file. The list is flat and the nesting is `depth`, which is what lets a row appear the moment the agent reports it rather than after its folder is complete.",
+      "interaction": "rows highlight on hover to keep the eye on one line; nothing here is clickable, because the tree reports rather than navigates."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/flow-graph.json

@@ -0,0 +1,75 @@
+{
+  "name": "FlowGraph",
+  "slug": "flow-graph",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Work as a graph rather than a list: branches that fan out and rejoin.",
+  "props": [
+    {
+      "name": "nodes",
+      "type": "readonly FlowNode[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every node with its grid position. Layout is explicit; the element runs no solver."
+    },
+    {
+      "name": "edges",
+      "type": "readonly FlowEdge[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Connections by node id. An edge dims until both of its ends are visible."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many nodes have been reached so far."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"nodes\" | \"edges\" | \"visibleCount\"\n> & {\n  /** Every node with its grid position. Layout is explicit; the element runs no solver. */\n  nodes: readonly FlowNode[];\n  /** Connections by node id. An edge dims until both of its ends are visible. */\n  edges: readonly FlowEdge[];\n  /** How many nodes have been reached so far. */\n  visibleCount: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-text-ui"
+  ],
+  "summary": "Work as a graph rather than a list: branches that fan out and rejoin.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FlowGraph } from \"@cueplusplus/ui/elements\";\n\n<FlowGraph nodes={nodes} edges={edges} visibleCount={nodes.length} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/flow-graph",
+  "mdUrl": "/docs/components/flow-graph.md",
+  "jsonUrl": "/r/components/flow-graph.json",
+  "specimens": [
+    {
+      "title": "FlowGraph",
+      "group": "elements-agents",
+      "components": [
+        "FlowGraph"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"partway\" wide>\n    <FlowGraph nodes={FLOW_NODES} edges={FLOW_EDGES} visibleCount={4} />\n  </Specimen>\n  <Specimen label=\"the whole graph\" wide>\n    <FlowGraph\n      nodes={FLOW_NODES.map((node) => ({ ...node, state: \"done\" as const }))}\n      edges={FLOW_EDGES}\n      visibleCount={FLOW_NODES.length}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Work as a graph rather than a list, for the runs that fan out and rejoin — here the two trusses are patched in parallel and the render waits for both. Layout is explicit: every node carries its own column and row and the element runs no solver, which is what keeps a re-render from rearranging a diagram somebody was reading.",
+      "interaction": "none. `visibleCount` is what makes the graph arrive a node at a time, and an edge stays dim until both of its ends have been reached."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/folder-icon.json

@@ -0,0 +1,52 @@
+{
+  "name": "FolderIcon",
+  "slug": "folder-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A folder somebody made: a shelf of bookmarks, filed by hand.\n\nThe tab is the whole glyph. A plain rounded box in this library is a panel,\na card or a dialog, and the one thing a folder has to say is that a person\nput these here on purpose rather than a query having returned them.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-icon-",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "A folder somebody made: a shelf of bookmarks, filed by hand.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/folder-icon",
+  "mdUrl": "/docs/components/folder-icon.md",
+  "jsonUrl": "/r/components/folder-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/frac.json

@@ -0,0 +1,59 @@
+{
+  "name": "Frac",
+  "slug": "frac",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A fraction inside an expression — numerator, rule, denominator — set inline and\naligned to the middle.",
+  "props": [
+    {
+      "name": "over",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Numerator."
+    },
+    {
+      "name": "under",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Denominator."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-emphasis"
+  ],
+  "summary": "A fraction inside an expression — numerator, rule, denominator — set inline and aligned to the middle.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/frac",
+  "mdUrl": "/docs/components/frac.md",
+  "jsonUrl": "/r/components/frac.json",
+  "specimens": [
+    {
+      "title": "MathBlock",
+      "group": "elements-knowledge",
+      "components": [
+        "MathBlock",
+        "Frac",
+        "Sub",
+        "Sup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
+      "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
+    }
+  ],
+  "todo": true
+}