@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/agent-card.json

@@ -0,0 +1,120 @@
+{
+  "name": "AgentCard",
+  "slug": "agent-card",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Who you are about to talk to: its skills, its model, and the endpoint behind it.",
+  "props": [
+    {
+      "name": "name",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Display name of the agent."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What it does, in one or two sentences."
+    },
+    {
+      "name": "provider",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Who publishes it."
+    },
+    {
+      "name": "version",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Card version, printed next to the name."
+    },
+    {
+      "name": "model",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Model the agent runs on."
+    },
+    {
+      "name": "endpoint",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Where it is reached. Truncates rather than wraps."
+    },
+    {
+      "name": "skills",
+      "type": "readonly AgentSkill[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Named capabilities the card advertises."
+    },
+    {
+      "name": "connected",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the action for a settled Connected state and disables it."
+    },
+    {
+      "name": "onConnect",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the agent is added."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"name\"\n  | \"description\"\n  | \"provider\"\n  | \"version\"\n  | \"model\"\n  | \"endpoint\"\n  | \"skills\"\n  | \"connected\"\n  | \"onConnect\"\n> & {\n  /** Display name of the agent. */\n  name: string;\n  /** What it does, in one or two sentences. */\n  description: string;\n  /** Who publishes it. */\n  provider: string;\n  /** Card version, printed next to the name. */\n  version: string;\n  /** Model the agent runs on. */\n  model: string;\n  /** Where it is reached. Truncates rather than wraps. */\n  endpoint: string;\n  /** Named capabilities the card advertises. */\n  skills: readonly AgentSkill[];\n  /** Swaps the action for a settled Connected state and disables it. */\n  connected: boolean;\n  /** Called when the agent is added. */\n  onConnect?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Who you are about to talk to: its skills, its model, and the endpoint behind it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentCard } from \"@cueplusplus/ui/elements\";\n\n<AgentCard\n  name=\"Maintainer\"\n  description=\"Reproduces the report, writes the fix, opens the PR.\"\n  provider=\"assistant-ui\"\n  version=\"1.4.0\"\n  model=\"opus\"\n  endpoint=\"https://agents.example.com/a2a\"\n  skills={skills}\n  connected={false}\n  onConnect={connect}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-card",
+  "mdUrl": "/docs/components/agent-card.md",
+  "jsonUrl": "/r/components/agent-card.json",
+  "specimens": [
+    {
+      "title": "AgentCard",
+      "group": "elements-agents",
+      "components": [
+        "AgentCard"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"not connected\">\n    <AgentCard\n      name=\"Patch\"\n      description=\"Assigns fixtures to universes and addresses, then redraws the plot to match. It will not touch a live desk.\"\n      provider=\"cue++ internal\"\n      version=\"2.4\"\n      model=\"Opus 5\"\n      endpoint=\"agents.cue.internal/patch\"\n      skills={SKILLS}\n      connected={connected}\n      onConnect={() => setConnected(true)}\n    />\n  </Specimen>\n  <Specimen label=\"connected\">\n    <AgentCard\n      name=\"Patch\"\n      description=\"Assigns fixtures to universes and addresses, then redraws the plot to match.\"\n      provider=\"cue++ internal\"\n      version=\"2.4\"\n      model=\"Opus 5\"\n      endpoint=\"agents.cue.internal/patch\"\n      skills={SKILLS.slice(0, 2)}\n      connected\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Who you are about to talk to, before you talk to it: the name and who publishes it, one paragraph on what it is for, the skills it advertises, and — in mono along the bottom — the model and the endpoint actually behind it. Those last two are the line that separates a card from a marketing tile.",
+      "interaction": "the action is the only control. Connected disables it and swaps the ink button for a settled field row with a tick, rather than greying out a button that still looks pressable."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-handoff.json

@@ -0,0 +1,87 @@
+{
+  "name": "AgentHandoff",
+  "slug": "agent-handoff",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Control passing between agents, with the reason and what came along.",
+  "props": [
+    {
+      "name": "from",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Agent giving up control."
+    },
+    {
+      "name": "to",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Agent taking it."
+    },
+    {
+      "name": "reason",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why the baton moved. Without it a handoff reads as an unexplained jump."
+    },
+    {
+      "name": "carried",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Context that travelled across. Pass an empty array to hide the section."
+    },
+    {
+      "name": "settled",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Cools the arrow and the receiving badge once the new agent is underway."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"from\" | \"to\" | \"reason\" | \"carried\" | \"settled\"\n> & {\n  /** Agent giving up control. */\n  from: string;\n  /** Agent taking it. */\n  to: string;\n  /** Why the baton moved. Without it a handoff reads as an unexplained jump. */\n  reason: string;\n  /** Context that travelled across. Pass an empty array to hide the section. */\n  carried: readonly string[];\n  /** Cools the arrow and the receiving badge once the new agent is underway. */\n  settled: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-stream",
+    "--cue-text-ui"
+  ],
+  "summary": "Control passing between agents, with the reason and what came along.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentHandoff } from \"@cueplusplus/ui/elements\";\n\n<AgentHandoff from=\"Triage\" to=\"Maintainer\" reason={reason} carried={carried} settled />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-handoff",
+  "mdUrl": "/docs/components/agent-handoff.md",
+  "jsonUrl": "/r/components/agent-handoff.json",
+  "specimens": [
+    {
+      "title": "AgentHandoff",
+      "group": "elements-agents",
+      "components": [
+        "AgentHandoff"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"live\" wide>\n    <AgentHandoff\n      from=\"Patch\"\n      to=\"Plot\"\n      reason=\"Addresses are assigned; redrawing the hanging plot needs the drawing agent.\"\n      carried={[\n        \"Universe 3, channels 1–48\",\n        \"Six ESPRITEs on 3.2 m centres\",\n        \"Front truss at 8.4 m trim\",\n      ]}\n      settled={false}\n    />\n  </Specimen>\n  <Specimen label=\"settled, nothing carried\" wide>\n    <AgentHandoff\n      from=\"Plot\"\n      to=\"Check\"\n      reason=\"Plot is redrawn. The walk-the-rig pass starts from the file, not from this thread.\"\n      carried={[]}\n      settled\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The baton moving, with the reason attached. Two badges and an arrow: while the handoff is live the receiving agent and the arrow take the streaming hue, and `settled` cools both once the new agent is actually underway. What travelled across is listed under it against a rule — a handoff with no carried context is a handoff you cannot audit.",
+      "interaction": "none. It is a record of something that happened, not a control; the only thing that moves is the colour, over half a second."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-mode-badge.json

@@ -0,0 +1,84 @@
+{
+  "name": "AgentModeBadge",
+  "slug": "agent-mode-badge",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "What the run is allowed to do, said in one chip and one attribute.\n\nAgent authority is the fact a person most needs from the corner of their eye\nand the one every catalogue leaves to prose. This is the readout: a glyph, a\nword, and `data-agent-mode` on the element. The attribute is the part that\ntravels — `@cueplusplus/ui/elements.css` declares four custom properties\nunder it, so putting the same attribute on a composer tints its focus ring,\nits send button and its rail from one place, and a console adds a\nmode-aware surface by reading a property rather than by threading a prop:\n\n```css\n.composer:focus-within { border-color: var(--cue-elements-mode-icon); }\n.send-button { background: var(--cue-elements-mode-icon); color: var(--cue-elements-mode-background); }\n.turn-rail { background: var(--cue-elements-mode-border); }\n```\n\nThe ladder is four rungs and the mode set is open. Every product in the study\npaints six, seven or nine modes in exactly four accents — will it ask me, is\nit writing, is it only planning, are the guardrails off — so the rung is what\n`mode` carries and the product's own word is what `label` carries.\n\nThe properties resolve against the *element that carries the attribute*, not\nagainst the page: a badge inside an `<AgentSurface skin=\"aui\">` takes the\nisland's palette, because the quadruple is declared on `[data-agent-mode]`\nrather than at `:root` where a `var()` would have been substituted before it\never reached the island.",
+  "props": [
+    {
+      "name": "mode",
+      "type": "\"manual\" | \"auto-edit\" | \"plan\" | \"unsafe\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "How much authority the run is holding: `manual`, `auto-edit`, `plan` or\n`unsafe`. Stamped as `data-agent-mode`, which is what the quadruple in\n`@cueplusplus/ui/elements.css` is keyed on."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The product's own word for it — `Agent`, `Build`, `YOLO`, `Bypass\npermissions`. Defaults to `AGENT_MODE_LABELS[mode]`, and it is the reason\na nine-mode product needs no more than these four rungs."
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the mode actually does, as the badge's `title`. Defaults to\n`AGENT_MODE_DESCRIPTIONS[mode]`. Pass `\"\"` for no tooltip at all."
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop) — `render={<button\ntype=\"button\" onClick={cycle} />}` for a picker that cycles, which is what\nevery product with more than two modes ships."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-elements-mode-background",
+    "--cue-elements-mode-border",
+    "--cue-elements-mode-icon",
+    "--cue-elements-mode-text",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-surface-2",
+    "--cue-text-ui"
+  ],
+  "summary": "What the run is allowed to do, said in one chip and one attribute.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentModeBadge } from \"@cueplusplus/ui/elements\";\n\n<AgentModeBadge mode=\"plan\" />\n// A product's own word on cue's rung, and a chip that cycles.\n<AgentModeBadge\n  mode=\"unsafe\"\n  label=\"YOLO\"\n  render={<button type=\"button\" onClick={cycle} />}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-mode-badge",
+  "mdUrl": "/docs/components/agent-mode-badge.md",
+  "jsonUrl": "/r/components/agent-mode-badge.json",
+  "specimens": [
+    {
+      "title": "AgentModeBadge",
+      "group": "elements",
+      "components": [
+        "AgentModeBadge"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the four rungs\">\n    <span className=\"flex flex-wrap items-center gap-(--cue-space-2)\">\n      {AGENT_MODES.map((rung) => (\n        <AgentModeBadge key={rung} mode={rung} />\n      ))}\n    </span>\n  </Specimen>\n  <Specimen label={`one attribute, four surfaces · ${AGENT_MODE_LABELS[mode]}`} wide>\n    <div\n      data-agent-mode={mode}\n      className=\"flex w-full max-w-md items-center gap-(--cue-space-3) rounded-(--radius-surface) border bg-surface-1 p-(--cue-space-3)\"\n      style={{ borderColor: \"var(--cue-elements-mode-border)\" }}\n    >\n      <span\n        aria-hidden\n        className=\"h-9 w-0.5 shrink-0 rounded-full\"\n        style={{ background: \"var(--cue-elements-mode-icon)\" }}\n      />\n      <span className=\"flex min-w-0 flex-1 flex-col gap-(--cue-space-1)\">\n        <AgentModeBadge\n          mode={mode}\n          className=\"self-start\"\n          render={\n            <button\n              type=\"button\"\n              onClick={() =>\n                setMode(\n                  AGENT_MODES[\n                    (AGENT_MODES.indexOf(mode) + 1) % AGENT_MODES.length\n                  ] as AgentMode,\n                )\n              }\n            />\n          }\n        />\n        <span className=\"text-fg-muted truncate text-(length:--cue-text-ui)\">\n          Patch the front truss and write cue 1\n        </span>\n      </span>\n      <button\n        type=\"button\"\n        className=\"shrink-0 rounded-full px-(--cue-space-3) py-(--cue-space-1) text-(length:--cue-text-label) font-medium\"\n        style={{\n          background: \"var(--cue-elements-mode-icon)\",\n          color: \"var(--cue-bg)\",\n        }}\n      >\n        Send\n      </button>\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "How much authority the run is holding, which is the fact a person most needs from the corner of their eye and the one every catalogue leaves to prose. The ladder is four rungs — will it ask me, is it writing, is it only planning, are the guardrails off — because that is how many accents every product in the study paints, whatever it calls its six or seven or nine modes. The chip is the readout; `data-agent-mode` is the part that travels.",
+      "interaction": "press the chip to cycle the rung. The second specimen is the whole point: one attribute on the box, and the rail, the border and the send button all re-derive from `var(--cue-elements-mode-icon)` with no prop threading and no branch in any component. Colour is never alone — each rung has its own glyph and its own word, so the ladder survives a monochrome screenshot."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-plan.json

@@ -0,0 +1,67 @@
+{
+  "name": "AgentPlan",
+  "slug": "agent-plan",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A checklist the agent works through, with progress you can glance.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Checklist items the agent works through in order."
+    },
+    {
+      "name": "activeIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Index of the step currently running. Values past the end mark every step done, and\nvalues before the start mark none."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"steps\" | \"activeIndex\"> & {\n  /** Checklist items the agent works through in order. */\n  steps: readonly string[];\n  /**\n   * Index of the step currently running. Values past the end mark every step done, and\n   * values before the start mark none.\n   */\n  activeIndex: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body"
+  ],
+  "summary": "A checklist the agent works through, with progress you can glance.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentPlan } from \"@cueplusplus/ui/elements\";\n\n<AgentPlan\n  steps={[\"Read the file\", \"Draft the fix\", \"Run tests\"]}\n  activeIndex={1}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-plan",
+  "mdUrl": "/docs/components/agent-plan.md",
+  "jsonUrl": "/r/components/agent-plan.json",
+  "specimens": [
+    {
+      "title": "AgentPlan",
+      "group": "elements",
+      "components": [
+        "AgentPlan"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"step 1\" wide>\n    <AgentPlan steps={PLAN} activeIndex={0} />\n  </Specimen>\n  <Specimen label=\"step 3\" wide>\n    <AgentPlan steps={PLAN} activeIndex={2} />\n  </Specimen>\n  <Specimen label=\"finished\" wide>\n    <AgentPlan steps={PLAN} activeIndex={PLAN.length} />\n  </Specimen>\n</Specimens>",
+      "note": "The checklist the agent published before it started, with one index driving the whole thing: steps before it are done, the step at it is running, steps after it are waiting. An index past the end marks every step done.",
+      "interaction": "none. A plan is a readout; the agent moves it, not the reader."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-status.json

@@ -0,0 +1,73 @@
+{
+  "name": "AgentStatus",
+  "slug": "agent-status",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One pill that always answers: what is it doing, and for how long.",
+  "props": [
+    {
+      "name": "state",
+      "type": "\"done\" | \"working\" | \"waiting\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Visual mode of the pill: working, waiting, or done with a check."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Short status line describing what the agent is doing."
+    },
+    {
+      "name": "elapsed",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Elapsed time shown in mono when provided."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"state\" | \"label\" | \"elapsed\"> & {\n  /** Visual mode of the pill: working, waiting, or done with a check. */\n  state: AgentState;\n  /** Short status line describing what the agent is doing. */\n  label: string;\n  /** Elapsed time shown in mono when provided. */\n  elapsed?: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-stream",
+    "--cue-surface-3",
+    "--cue-text-ui"
+  ],
+  "summary": "One pill that always answers: what is it doing, and for how long.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentStatus } from \"@cueplusplus/ui/elements\";\n\n<AgentStatus state=\"working\" label=\"Editing composer.tsx\" elapsed=\"8s\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-status",
+  "mdUrl": "/docs/components/agent-status.md",
+  "jsonUrl": "/r/components/agent-status.json",
+  "specimens": [
+    {
+      "title": "AgentStatus",
+      "group": "elements",
+      "components": [
+        "AgentStatus"
+      ],
+      "code": "<Specimens>\n  {PILLS.map((pill) => (\n    <Specimen key={pill.state} label={pill.state}>\n      <AgentStatus state={pill.state} label={pill.label} elapsed={pill.elapsed} />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "One pill that always answers the two questions a run raises: what is it doing, and for how long. Working shimmers, waiting is still and marked, done carries a check and the elapsed total.",
+      "interaction": "the trailing control is a labelled icon button that pauses a run and offers to run it again once it is done."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-surface.json

@@ -0,0 +1,78 @@
+{
+  "name": "AgentSurface",
+  "slug": "agent-surface",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The supersede island: one subtree, painted by a different set of values.\n\nRenders a plain `<div data-slot=\"agent-surface\" data-cue-skin=\"…\"\ndata-cue-fidelity=\"…\">` and publishes the same pair on React context. The attributes do the work —\n`@cueplusplus/ui/elements.css` re-declares, under them, the `--cue-*` tokens\nthe whole elements family reads, and custom properties inherit, so every\nelement inside repaints with no prop threading and no branch in any\ncomponent. The context exists for the one place that cannot see the DOM: an\noverlay portaled to `<body>` from inside the island, which\n{@link useCuePortalProps } stamps from the same values.\n\nTwo things this is not. It is not a theme — `data-theme`, `data-mode` and\n`data-density` are untouched, and a light app keeps a light island. And it is\nnot needed for cue mode: the elements were rewritten onto cue's tokens by the\nvendoring codemod, so `skin=\"cue\"` is what they already do. Reach for this to\nshow an element the way assistant-ui drew it, or to hand a chat panel back to\nupstream's design language inside a console that is otherwise cue's.\n\nWhat an `aui` island re-points is this family's own vocabulary rather than the\nwhole token contract: `--cue-busy`, `--cue-info`, `--cue-selection`,\n`--cue-focus`, `--cue-scrim` and every derived `*-soft` / `*-border` stay on\nthe console's theme. Nothing in the elements group reads them, so the island\nis complete for what it is for — but a *cue* component placed inside one (a\n`Chip tone=\"busy\"`, a `Toast`) paints half in each palette, and the\nderivations cannot be made to follow at all: they are `color-mix()` values\nresolved on the theme block and inherited as answers. `elements.css` carries\nthe full accounting beside the values themselves.\n\n`elements.css` is a consumer import: `@import \"@cueplusplus/ui/elements.css\";`\nafter the main stylesheet. Without it a `skin=\"aui\"` island simply stays in\ncue's palette.",
+  "props": [
+    {
+      "name": "skin",
+      "type": "\"cue\" | \"aui\"",
+      "required": false,
+      "defaultValue": "cue",
+      "description": "Which value-set paints the subtree: `cue` (the default) or `aui`, which\ninstalls assistant-ui's own inks, grounds and hues."
+    },
+    {
+      "name": "fidelity",
+      "type": "\"upstream\" | \"cue-metrics\"",
+      "required": false,
+      "defaultValue": "cue-metrics",
+      "description": "How much a supersede island re-points: `cue-metrics` (the default, colour\nonly) or `upstream`, which also pins assistant-ui's radii, literal type\nsizes and spacing so the density ladder stops at the island edge."
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<section />}` — or a function returning one."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The subtree that paints with this island's values."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-busy",
+    "--cue-focus",
+    "--cue-info",
+    "--cue-scrim",
+    "--cue-selection"
+  ],
+  "summary": "The supersede island: one subtree, painted by a different set of values.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AgentSurface skin=\"aui\" fidelity=\"upstream\">\n  <ToolCall label=\"Searched\" activeLabel=\"Searching\" query=\"composer\" … />\n</AgentSurface>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-surface",
+  "mdUrl": "/docs/components/agent-surface.md",
+  "jsonUrl": "/r/components/agent-surface.json",
+  "specimens": [
+    {
+      "title": "AgentSurface",
+      "group": "elements",
+      "components": [
+        "AgentSurface"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"skin=cue (the default)\" wide>\n    <AgentSurface className=\"flex w-full flex-col gap-(--cue-space-3) rounded-(--radius-surface) border border-border bg-bg p-(--cue-space-4)\">\n      <IslandCalls scope=\"cue\" open={open} onOpenChange={opener} />\n    </AgentSurface>\n  </Specimen>\n  <Specimen label=\"aui · cue-metrics\" wide>\n    <AgentSurface\n      skin=\"aui\"\n      fidelity=\"cue-metrics\"\n      className=\"flex w-full flex-col gap-(--cue-space-3) rounded-(--radius-surface) border border-border bg-bg p-(--cue-space-4)\"\n    >\n      <IslandCalls scope=\"aui-metrics\" open={open} onOpenChange={opener} />\n    </AgentSurface>\n  </Specimen>\n  <Specimen label=\"aui · upstream\" wide>\n    <AgentSurface\n      skin=\"aui\"\n      fidelity=\"upstream\"\n      className=\"flex w-full flex-col gap-(--cue-space-3) rounded-(--radius-surface) border border-border bg-bg p-(--cue-space-4)\"\n    >\n      <IslandCalls scope=\"aui-upstream\" open={open} onOpenChange={opener} />\n    </AgentSurface>\n  </Specimen>\n</Specimens>",
+      "note": "One DOM, three paint jobs. The same three tool calls sit in all three specimens; the only difference is the pair of attributes on the box around them. skin='aui' re-points the colour set to assistant-ui's own inks and grounds, and fidelity='upstream' re-points the metrics too, which is what stops cue's density ladder at the island edge. Without @cueplusplus/ui/elements.css imported, all three would look alike.",
+      "interaction": "none of its own. The island is a values-set, not a control: everything inside keeps the behaviour it has outside."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/alert-dialog.json

@@ -119,7 +119,7 @@
       "props": [
         {
           "name": "tone",
-          "type": "\"accent\" | \"danger\"",
+          "type": "\"danger\" | \"accent\"",
           "required": false,
           "defaultValue": "accent",
           "description": "Which answer this is. `\"danger\"` for anything destructive, `\"accent\"` for a\nconfirmation that merely proceeds. Defaults to `\"accent\"`."

package/manifest/components/animated-number.json

@@ -0,0 +1,67 @@
+{
+  "name": "AnimatedNumber",
+  "slug": "animated-number",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A number that counts to its new value instead of jumping to it.\n\nThe smallest element in the canon and the one that touches the most rows: a\ntoken count, a cost, a duration, a file tally. Two rules, both from the same\nteardown. Tween, because a value that steps reads as a new fact while a value\nthat counts reads as the same fact moving — and a transcript's numbers are\nalmost always the second thing. And `tabular-nums`, because a proportional\n`1` is narrower than a `0`, so a stepping counter nudges everything to its\nright on every update.\n\nIt holds the only state in the canon, and it is a tween rather than a fact:\n`value` is still a prop, every tween ends exactly on it, and a replay that\nsets the prop paints the same number at every frame it rests on.\n\n**Reduced motion is answered by arriving, not by stopping.** A reader who has\nasked for stillness gets the value immediately and no frames are ever\nscheduled — the number is information, and the animation was only ever how it\ngot there.\n\nWhile a tween is in flight the digits on screen are `aria-hidden` and the\nsettled value is carried beside them for a screen reader, so an assistive\ntechnology reads the number the run actually reported rather than whichever\nframe it happened to land on. Once the tween ends there is one node again and\nnothing is duplicated.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The number to show. Every change eases from whatever is on screen to this,\nincluding a change that arrives mid-tween — which is the case a live\ncounter is actually made of.\n\nA non-finite value paints `0` rather than the word `NaN`: these arrive from\na caller's arithmetic over a stream that may not have started."
+    },
+    {
+      "name": "duration",
+      "type": "number",
+      "required": false,
+      "defaultValue": "400",
+      "description": "How long one tween lasts, in milliseconds. Defaults to `400` — long enough\nto read as counting, short enough that a counter updated every second is\nnever behind the run it is describing. `0` steps."
+    },
+    {
+      "name": "format",
+      "type": "((value: number) => string)",
+      "required": false,
+      "defaultValue": "(value: number): string => value.toLocaleString(\"en-US\")",
+      "description": "How to write the number. Defaults to grouped digits in `en-US`\n(`1,240`), which is deterministic across a server render and a client one;\n{@link formatCompactNumber} is the other one this family uses (`1.2k`).\n\nCalled on every frame, so keep it cheap."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted"
+  ],
+  "summary": "A number that counts to its new value instead of jumping to it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AnimatedNumber } from \"@cueplusplus/ui/elements\";\n\n<AnimatedNumber value={tokens} />\n// The reference's own readout: compact, inline, in the status line.\n<span className=\"text-fg-muted\">\n  · <AnimatedNumber value={tokens} format={formatCompactNumber} /> tokens\n</span>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/animated-number",
+  "mdUrl": "/docs/components/animated-number.md",
+  "jsonUrl": "/r/components/animated-number.json",
+  "specimens": [
+    {
+      "title": "AnimatedNumber",
+      "group": "elements",
+      "components": [
+        "AnimatedNumber"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"compact, in a status line\" wide>\n    <span className=\"flex items-center gap-(--cue-space-3)\">\n      <span className=\"text-fg-muted text-(length:--cue-text-ui)\">\n        Thinking · <AnimatedNumber value={tokens} format={formatCompactNumber} /> tokens\n      </span>\n      <Button size=\"sm\" onClick={() => setTokens((was) => was + 3400)}>\n        Read more\n      </Button>\n    </span>\n  </Specimen>\n  <Specimen label=\"grouped, as a stat\">\n    <span className=\"text-(length:--cue-text-emphasis) font-medium\">\n      <AnimatedNumber value={tokens} />\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "A number that counts to its new value instead of jumping to it, in tabular numerals so the digits do not jitter on the way. Both halves are one teardown's: the reference eases its live token estimate from the previous value to the new one and paints it in font-variant-numeric tabular-nums, because a proportional 1 is narrower than a 0 and a stepping counter nudges everything to its right on every update. A value that steps reads as a new fact; a value that counts reads as the same fact moving, which is what a token, a cost and a duration actually are.",
+      "interaction": "press the button and watch the digits rather than the box — nothing to the right of the number moves. Under prefers-reduced-motion the new value simply arrives: stillness for a counter has to mean landing on the number, because a readout that stopped where it was would be wrong rather than still. Mid-tween the digits are aria-hidden and the settled value is carried beside them, so a screen reader reads what the run reported and never a frame of the animation."
+    }
+  ],
+  "todo": true
+}