@cueplusplus/ui 0.2.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-pile.json

@@ -0,0 +1,116 @@
+{
+  "name": "AgentPile",
+  "slug": "agent-pile",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The roster of agents working on a thread, stacked into one object.\n\nThree states ride on each avatar, and none of them is colour-only: the\norchestrator wears a crown, a working agent gets a spinning arc, and an agent\nwaiting on the user gets a `?` badge — each of them also spelled into the\navatar's accessible name, so a screen reader hears \"Researcher · working\"\nrather than nothing at all.\n\nAvatars are outlined in the agent's colour rather than filled with it. A fill\nwould put arbitrary-hue ink on an arbitrary-hue ground at 20px; the outline\ntreatment is the same tinted-chip recipe the rest of the system uses and\nstays legible on every theme.",
+  "props": [
+    {
+      "name": "agents",
+      "type": "readonly AgentPileEntry[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The roster, in the order it should read. Renders nothing when empty."
+    },
+    {
+      "name": "root",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the orchestrator: takes the theme accent and wears the crown."
+    },
+    {
+      "name": "selected",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the lane currently open — that avatar gets a ring."
+    },
+    {
+      "name": "onSelect",
+      "type": "((slug: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with a slug when an avatar is pressed. Omit for a read-only pile."
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Show at most this many; the rest collapse into a `+N` chip."
+    },
+    {
+      "name": "fanned",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Force the fan open or shut. Omit to let hover and focus decide."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the group. Required in practice — name the roster."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The roster of agents working on a thread, stacked into one object.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AgentPile aria-label=\"Agents\" agents={roster} root=\"chief\" onSelect={openLane} />\n<AgentPile aria-label=\"Agents\" agents={roster} max={5} fanned />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-pile",
+  "mdUrl": "/docs/components/agent-pile.md",
+  "jsonUrl": "/r/components/agent-pile.json",
+  "specimens": [
+    {
+      "title": "AgentPile",
+      "group": "chat",
+      "components": [
+        "AgentPile"
+      ],
+      "code": "<Specimens>\n  {([\"sm\", \"md\", \"lg\"] as const).map((size) => (\n    <Specimen key={size} label={size}>\n      <AgentPile agents={AGENTS} root=\"orchestrator\" size={size} />\n    </Specimen>\n  ))}\n  <Specimen label=\"max 4\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" max={4} />\n  </Specimen>\n  <Specimen label=\"not fanned\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" fanned={false} />\n  </Specimen>\n  <Specimen label=\"selected\">\n    <AgentPile agents={AGENTS} root=\"orchestrator\" selected=\"patcher\" />\n  </Specimen>\n</Specimens>",
+      "note": "Faces at −12px overlap, fanning to +4px on hover. The crown marks the orchestrator, an arc marks work in flight and a `?` marks an agent waiting on an answer.",
+      "interaction": "every face is a button with the agent's name; the pile is one tab stop and arrow keys move inside it."
+    }
+  ],
+  "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
+}