@cueplusplus/ui 0.3.0 → 0.6.0

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
+}

package/manifest/components/generation-loader.json

@@ -0,0 +1,64 @@
+{
+  "name": "GenerationLoader",
+  "slug": "generation-loader",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The wait before there is anything to show. A nine-cell matrix keeps time under a\nshimmering label, driven by a `tick` the caller advances — so a paused replay pauses\nthe loader too.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Status copy shown under the pixel grid while the model has nothing else to show."
+    },
+    {
+      "name": "tick",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Animation clock that advances the pixel pattern and the elapsed seconds counter."
+    },
+    {
+      "name": "variant",
+      "type": "\"dots\" | \"squares\" | \"rounded\"",
+      "required": false,
+      "defaultValue": "dots",
+      "description": "Cell shape of the pixel matrix."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-radius-control",
+    "--cue-text-body"
+  ],
+  "summary": "The wait before there is anything to show.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/generation-loader",
+  "mdUrl": "/docs/components/generation-loader.md",
+  "jsonUrl": "/r/components/generation-loader.json",
+  "specimens": [
+    {
+      "title": "GenerationLoader",
+      "group": "elements-thread",
+      "components": [
+        "GenerationLoader"
+      ],
+      "code": "<Specimens>\n  {LOADER_VARIANTS.map((variant, index) => (\n    <Specimen key={variant} label={variant}>\n      <GenerationLoader label=\"Working on the patch\" tick={index * 4} variant={variant} />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "The wait before there is anything at all to show. Nine cells keep time under a shimmering label, driven by a tick the caller advances — so a paused replay pauses the loader too, which a CSS animation could never do. The three variants are three shapes for the same clock.",
+      "interaction": "none. The matrix is aria-hidden; the label is the only thing a screen reader gets, which is the right amount."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/generative-ui.json

@@ -0,0 +1,93 @@
+{
+  "name": "GenerativeUI",
+  "slug": "generative-ui",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements/generative",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The vocabulary a model composes at runtime.\n\nEvery other component in this library is handed props by a programmer, and a\nwrong one costs a type error at the call site. This one is handed a tree by a\nlanguage model over a network, so its whole contract is what it does with\ninput nobody checked. A model emits JSON — 27 intrinsic names, nested — and\n`GenerativeUI` turns it into elements. There is no compile step between the\ntwo and there cannot be one.\n\nThat reverses the usual priorities. The interesting question is not what a\ncorrect spec renders as, it is what an incorrect one does, and the answer is\nthree-fold and never an exception:\n\n- a `$type` from a newer catalogue draws an in-place notice and its siblings\n  still render;\n- a spec that is not a component tree at all draws a legible error state,\n  never a blank box that looks like a message still streaming;\n- a tree nested deeper than {@link GENERATIVE_MAX_DEPTH} stops and says so,\n  rather than exhausting the stack and taking the console with it.\n\nThe root is a plain `<div data-slot=\"generative-ui\" data-aui=\"root\">` and it\nis always there: an unreadable spec draws the error state *inside* it rather\nthan instead of it, so a caller's layout, `className` and ref hold whatever\nthe model sent.\n\n## Why it is not Tailwind\n\nThe stylesheet is plain `[data-aui]` CSS, and the tree it draws carries no\n`class` attribute anywhere. That is upstream's arrangement and it is worth\nkeeping precisely: a widget a model composed has to draw inside whatever\nconsole it was sent to, and a console is very often somebody else's app with\nno utility framework, no shadcn and no design system of its own. The\nconsequence runs all the way down — the icons are hand-drawn rather than\n`lucide-react`, the chart is 300 lines of SVG rather than `recharts`, and\n`./elements/generative` declares no optional peer at all. There is no package\nin the tree whose absence turns a weather card into a stack trace.\n\n```tsx\nimport { GenerativeUI } from \"@cueplusplus/ui/elements/generative\";\nimport \"@cueplusplus/ui/elements/generative.css\";\n```\n\n## Two skins\n\n`skin` and `fidelity` are the same two axes {@link AgentSurface } publishes,\nand for the same reason: the vocabulary has cue's values by default and\nassistant-ui's under `skin=\"aui\"`, which is upstream's own\n`data-aui-theme=\"elements\"` layer — a 20px card, a borderless 12px field, a\npill button. Pass them here when the tree is its own island; leave them off\ninside an `AgentSurface`, which has already stamped the subtree and whose\nvalues inherit through CSS with nothing threaded.",
+  "props": [
+    {
+      "name": "spec",
+      "type": "unknown",
+      "required": true,
+      "defaultValue": null,
+      "description": "The tree to draw, exactly as it arrived.\n\nTyped `unknown` rather than `GenerativeNode` on purpose. A caller who has\njust parsed a tool result holds a `JSON.parse` return, and a signature that\ndemanded a node would push every consumer into the same cast — which is a\nclaim about the bytes that nobody is in a position to make. The renderer\nreads what it was given and reports what it could not use."
+    },
+    {
+      "name": "onAction",
+      "type": "((action: GenerativeAction) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where a control's press goes: a button, a form submit, a list row, a\ncheckbox, a card's confirm.\n\nCalled with the `$action` string the model put on the node, the intrinsic\nthat fired it, and — where the control has one — its own value. Omit it and\nevery control is inert, which is the right default for a transcript that is\nbeing re-read rather than used."
+    },
+    {
+      "name": "onFault",
+      "type": "((fault: GenerativeFault) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Told about every node the renderer refused to guess at, after the render\nthat refused it.\n\nThe counterpart of never throwing. A fallback is legible on screen, but the\nperson who needs to know that this console is a version behind the model\ndriving it is usually not the person looking at it — so the faults are also\na stream, one call per refusal, suitable for a counter or a log line."
+    },
+    {
+      "name": "renderMarkdown",
+      "type": "((value: string) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Turns a `Markdown` node's source into elements.\n\nWithout it the source renders verbatim, as characters, because this subpath\nships no parser and will not acquire one: `@cueplusplus/ui/elements/markdown`\nis the sanitized renderer this prop is shaped for, and it carries two peers\nthat a console drawing a weather card should not have to install.\n\n```tsx\nimport { MarkdownText } from \"@cueplusplus/ui/elements/markdown\";\n\n<GenerativeUI spec={spec} renderMarkdown={(md) => <MarkdownText>{md}</MarkdownText>} />\n```"
+    },
+    {
+      "name": "maxDepth",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How many levels to walk before drawing the depth notice. Defaults to\n{@link GENERATIVE_MAX_DEPTH}; anything below one level is read as one,\nsince a tree with no levels is not a tree."
+    },
+    {
+      "name": "skin",
+      "type": "\"cue\" | \"aui\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which value-set paints this tree: `cue` (the default) or `aui`, which\ninstalls assistant-ui's own surface language. Leave it off inside an\n{@link AgentSurface }, which has stamped the subtree already."
+    },
+    {
+      "name": "fidelity",
+      "type": "\"upstream\" | \"cue-metrics\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Whether the density knobs follow cue's ladder (`cue-metrics`, the default)\nor pin assistant-ui's own numbers (`upstream`)."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "The vocabulary a model composes at runtime.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<GenerativeUI\n  spec={JSON.parse(toolResult)}\n  onAction={(action) => send({ type: \"ui-action\", ...action })}\n  onFault={(fault) => telemetry.warn(\"generative\", fault)}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/generative-ui",
+  "mdUrl": "/docs/components/generative-ui.md",
+  "jsonUrl": "/r/components/generative-ui.json",
+  "specimens": [
+    {
+      "title": "GenerativeUI",
+      "group": "elements-knowledge",
+      "components": [
+        "GenerativeUI"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"a composed dashboard\" wide>\n    <GenerativeUI spec={RIG_DASHBOARD} />\n  </Specimen>\n  <Specimen label=\"a form\" wide>\n    <GenerativeUI\n      spec={patchRequest(patchSent)}\n      onAction={(action) => {\n        if (action.action !== \"patch-request\") return;\n        const values = action.values ?? {};\n        setPatchSent(\n          values[\"fixture\"] === undefined\n            ? null\n            : `${values[\"fixture\"]} on ${values[\"universe\"] === \"\" ? \"no universe yet\" : values[\"universe\"]}, from ${values[\"from\"]}.`,\n        );\n      }}\n    />\n  </Specimen>\n  <Specimen label=\"a chart\" wide>\n    <GenerativeUI spec={DRAW_CHART} />\n  </Specimen>\n  <Specimen label=\"an unknown component\" wide>\n    <GenerativeUI spec={FROM_THE_FUTURE} />\n  </Specimen>\n  <Specimen label=\"a malformed spec\" wide>\n    <GenerativeUI spec={NOT_A_TREE} />\n  </Specimen>\n</Specimens>",
+      "note": "The one component here nobody wrote props for. A model emits a tree of 27 intrinsic names as JSON and this draws it, with no compile step in between and none possible, so the specimens are the spec objects themselves: a dashboard the model composed out of facts, a chart and a table; a patch form whose confirm hands back every named field at once; and a chart on its own. The last two are wrong on purpose. A $type from a newer catalogue draws an in-place notice and its siblings still render; a spec that is not a tree at all draws a legible error rather than the blank box that reads as a message still streaming. Neither throws, which is the whole contract. It draws from plain [data-aui] CSS with no utilities and no icon or chart package behind it, because the console a model is talking to is usually somebody else's app.",
+      "interaction": "every control is a real control and takes the house focus ring; text fires on blur rather than per keystroke, since $action is a message to the model. The form specimen is live: submit it and the model's own card gains a success alert with what the desk received."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/guardrail-notice.json

@@ -0,0 +1,91 @@
+{
+  "name": "GuardrailNotice",
+  "slug": "guardrail-notice",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A refusal in its own shape, with the nearest thing it can do instead.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The refusal in one line, stated plainly rather than apologetically."
+    },
+    {
+      "name": "explanation",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why, and where the line actually sits."
+    },
+    {
+      "name": "policy",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Short label for the rule that applied."
+    },
+    {
+      "name": "alternatives",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The nearest things it can do. Pass an empty array to hide the section."
+    },
+    {
+      "name": "onPick",
+      "type": "((alternative: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when an alternative is chosen."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"title\" | \"explanation\" | \"policy\" | \"alternatives\" | \"onPick\"\n> & {\n  /** The refusal in one line, stated plainly rather than apologetically. */\n  title: string;\n  /** Why, and where the line actually sits. */\n  explanation: string;\n  /** Short label for the rule that applied. */\n  policy: string;\n  /** The nearest things it can do. Pass an empty array to hide the section. */\n  alternatives: readonly string[];\n  /** Called when an alternative is chosen. */\n  onPick?: (alternative: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "A refusal in its own shape, with the nearest thing it can do instead.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { GuardrailNotice } from \"@cueplusplus/ui/elements\";\n\n<GuardrailNotice\n  title=\"I can't help with that\"\n  explanation=\"This asks for a working attack against infrastructure you don't own.\"\n  policy=\"policy\"\n  alternatives={alternatives}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/guardrail-notice",
+  "mdUrl": "/docs/components/guardrail-notice.md",
+  "jsonUrl": "/r/components/guardrail-notice.json",
+  "specimens": [
+    {
+      "title": "GuardrailNotice",
+      "group": "elements-agents",
+      "components": [
+        "GuardrailNotice"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three ways round it\" wide>\n    <GuardrailNotice\n      title=\"I will not write to the desk while the house is open.\"\n      explanation=\"The show is running and this patch changes fixtures that are live on stage. Outside show hours the same change is fine.\"\n      policy=\"live-desk\"\n      alternatives={[\n        \"Write the patch to a file for the LX crew\",\n        \"Queue it for the post-show window\",\n        \"Show me what would change\",\n      ]}\n      onPick={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"nothing else to offer\" wide>\n    <GuardrailNotice\n      title=\"I cannot open universe 4 on this desk.\"\n      explanation=\"The show file is licensed for three universes. This is a limit on the desk, not a policy I can waive.\"\n      policy=\"capability\"\n      alternatives={[]}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A refusal in its own shape: what it will not do, why, the rule that applied, and the nearest things it *can* do. The alternatives are the whole point — a refusal that ends at 'no' hands the work back with nothing attached, and this one hands back three next moves.",
+      "interaction": "each alternative is a button reporting its own text to `onPick`. With an empty list the section disappears rather than leaving an empty rule."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/hover-card.json

@@ -82,7 +82,7 @@
         },
         {
           "name": "side",
-          "type": "\"left\" | \"right\" | \"top\" | \"bottom\" | \"inline-end\" | \"inline-start\"",
+          "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
           "required": false,
           "defaultValue": null,
           "description": "Preferred side of the trigger. Defaults to `\"bottom\"`."