@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/composer-person-item.json

@@ -0,0 +1,79 @@
+{
+  "name": "ComposerPersonItem",
+  "slug": "composer-person-item",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A mentionable person in the menu: their initial, their name, and whether they are an\nagent or a human.",
+  "props": [
+    {
+      "name": "person",
+      "type": "ComposerPerson",
+      "required": true,
+      "defaultValue": null,
+      "description": "The person this row would mention."
+    },
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether this is the row Enter would pick."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** The person this row would mention. */\n  person: ComposerPerson;\n  /** Whether this is the row Enter would pick. */\n  active: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "A mentionable person in the menu: their initial, their name, and whether they are an agent or a human.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-person-item",
+  "mdUrl": "/docs/components/composer-person-item.md",
+  "jsonUrl": "/r/components/composer-person-item.json",
+  "specimens": [
+    {
+      "title": "ComposerMenu / useSlashMatches / useMentionMatches",
+      "group": "elements-composer",
+      "components": [
+        "ComposerMenu",
+        "ComposerMenuItem",
+        "ComposerCommandItem",
+        "ComposerPersonItem",
+        "useSlashMatches",
+        "useMentionMatches"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"slash commands\" wide>\n    <div className=\"flex min-h-64 w-full max-w-lg items-end\">\n      <ElementsComposer>\n        <ComposerMenu open={slashMatches.length > 0} align=\"start\">\n          {slashMatches.map((command, index) => (\n            <ComposerCommandItem\n              key={command.name}\n              command={command}\n              active={index === 0}\n              onClick={() => setSlash(`/${command.name} `)}\n            />\n          ))}\n          <ComposerMenuItem onClick={() => setSlash(\"\")}>\n            Browse every command\n          </ComposerMenuItem>\n        </ComposerMenu>\n        <ComposerBar>\n          <ComposerInput\n            aria-label=\"Run a slash command\"\n            value={slash}\n            placeholder=\"Type / for commands\"\n            onChange={(event) => setSlash(event.target.value)}\n          />\n        </ComposerBar>\n      </ElementsComposer>\n    </div>\n  </Specimen>\n\n  <Specimen label=\"mentions\" wide>\n    <div className=\"flex min-h-64 w-full max-w-lg items-end\">\n      <ElementsComposer>\n        <ComposerMenu open={mentionMatches.length > 0} align=\"end\">\n          {mentionMatches.map((person, index) => (\n            <ComposerPersonItem\n              key={person.name}\n              person={person}\n              active={index === 0}\n              onClick={() => setMention(applyMention(mention, person.name))}\n            />\n          ))}\n        </ComposerMenu>\n        <ComposerBar>\n          <ComposerInput\n            aria-label=\"Mention an agent or a person\"\n            value={mention}\n            placeholder=\"Type @ to hand this to somebody\"\n            onChange={(event) => setMention(event.target.value)}\n          />\n        </ComposerBar>\n      </ElementsComposer>\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
+      "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-send.json

@@ -0,0 +1,80 @@
+{
+  "name": "ComposerSend",
+  "slug": "composer-send",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Send, which becomes stop while the model is streaming. Dim when the input is empty\nand there is nothing to send; the arrow and the square cross-fade rather than swap.",
+  "props": [
+    {
+      "name": "streaming",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the arrow for a stop square."
+    },
+    {
+      "name": "idle",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the input is empty. Dims the button when there is nothing to send."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** Swaps the arrow for a stop square. */\n  streaming: boolean;\n  /** Whether the input is empty. Dims the button when there is nothing to send. */\n  idle: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "Send, which becomes stop while the model is streaming.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-send",
+  "mdUrl": "/docs/components/composer-send.md",
+  "jsonUrl": "/r/components/composer-send.json",
+  "specimens": [
+    {
+      "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
+      "group": "elements-composer",
+      "components": [
+        "ElementsComposer",
+        "ComposerBar",
+        "ComposerInput",
+        "ComposerToolbar",
+        "ComposerActions",
+        "ComposerAttachButton",
+        "ComposerSend"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"empty\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Ask about the rig\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming={false} idle />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"typed\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value={message}\n          placeholder=\"Ask about the rig\"\n          onChange={(event) => setMessage(event.target.value)}\n          onSubmit={() => setMessage(\"\")}\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n            <ComposerModelTrigger model={model} open={false} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerContext usage={USAGE} />\n            <ComposerVoiceButton active={false} />\n            <ComposerSend streaming={false} idle={message === \"\"} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"streaming, file over the bar\" wide>\n    <ElementsComposer>\n      <ComposerBar dragActive>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Drop the truss drawing here\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming idle={false} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n</Specimens>",
+      "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
+      "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-toolbar.json

@@ -0,0 +1,65 @@
+{
+  "name": "ComposerToolbar",
+  "slug": "composer-toolbar",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The row under the input, which holds the two `ComposerActions` clusters.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The row under the input, which holds the two `ComposerActions` clusters.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-toolbar",
+  "mdUrl": "/docs/components/composer-toolbar.md",
+  "jsonUrl": "/r/components/composer-toolbar.json",
+  "specimens": [
+    {
+      "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
+      "group": "elements-composer",
+      "components": [
+        "ElementsComposer",
+        "ComposerBar",
+        "ComposerInput",
+        "ComposerToolbar",
+        "ComposerActions",
+        "ComposerAttachButton",
+        "ComposerSend"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"empty\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Ask about the rig\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming={false} idle />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"typed\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value={message}\n          placeholder=\"Ask about the rig\"\n          onChange={(event) => setMessage(event.target.value)}\n          onSubmit={() => setMessage(\"\")}\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n            <ComposerModelTrigger model={model} open={false} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerContext usage={USAGE} />\n            <ComposerVoiceButton active={false} />\n            <ComposerSend streaming={false} idle={message === \"\"} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"streaming, file over the bar\" wide>\n    <ElementsComposer>\n      <ComposerBar dragActive>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Drop the truss drawing here\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming idle={false} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n</Specimens>",
+      "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
+      "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-voice-button.json

@@ -0,0 +1,68 @@
+{
+  "name": "ComposerVoiceButton",
+  "slug": "composer-voice-button",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The microphone, which becomes a filled stop while recording.",
+  "props": [
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the microphone is open."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** Whether the microphone is open. */\n  active: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The microphone, which becomes a filled stop while recording.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-voice-button",
+  "mdUrl": "/docs/components/composer-voice-button.md",
+  "jsonUrl": "/r/components/composer-voice-button.json",
+  "specimens": [
+    {
+      "title": "ComposerVoice / ComposerVoiceButton",
+      "group": "elements-composer",
+      "components": [
+        "ComposerVoice",
+        "ComposerVoiceButton"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"recording\" wide>\n    <ComposerVoice recording seconds={14} />\n  </Specimen>\n  <Specimen label=\"transcribing\" wide>\n    <ComposerVoice recording={false} seconds={14} />\n  </Specimen>\n  <Specimen label=\"idle button\">\n    <ComposerVoiceButton active={false} />\n  </Specimen>\n  <Specimen label=\"live button\">\n    <ComposerVoiceButton active />\n  </Specimen>\n</Specimens>",
+      "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
+      "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-voice.json

@@ -0,0 +1,75 @@
+{
+  "name": "ComposerVoice",
+  "slug": "composer-voice",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "What replaces the input while the microphone is open: a level meter, a running clock\nwhile recording, and a shimmering `Transcribing` once it stops.",
+  "props": [
+    {
+      "name": "recording",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the microphone is open. False is the transcribing state, not the resting one."
+    },
+    {
+      "name": "seconds",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How long it has been recording. Drives both the clock and the meter, so the caller\nowns the tick."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\"> & {\n  /** Whether the microphone is open. False is the transcribing state, not the resting one. */\n  recording: boolean;\n  /**\n   * How long it has been recording. Drives both the clock and the meter, so the caller\n   * owns the tick.\n   */\n  seconds: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "What replaces the input while the microphone is open: a level meter, a running clock while recording, and a shimmering `Transcribing` once it stops.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-voice",
+  "mdUrl": "/docs/components/composer-voice.md",
+  "jsonUrl": "/r/components/composer-voice.json",
+  "specimens": [
+    {
+      "title": "ComposerVoice / ComposerVoiceButton",
+      "group": "elements-composer",
+      "components": [
+        "ComposerVoice",
+        "ComposerVoiceButton"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"recording\" wide>\n    <ComposerVoice recording seconds={14} />\n  </Specimen>\n  <Specimen label=\"transcribing\" wide>\n    <ComposerVoice recording={false} seconds={14} />\n  </Specimen>\n  <Specimen label=\"idle button\">\n    <ComposerVoiceButton active={false} />\n  </Specimen>\n  <Specimen label=\"live button\">\n    <ComposerVoiceButton active />\n  </Specimen>\n</Specimens>",
+      "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
+      "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer.json

@@ -0,0 +1,176 @@
+{
+  "name": "Composer",
+  "slug": "composer",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The thing you type into: an auto-growing textarea, a send affordance, and\nslots for everything a host wants to hang off them.\n\nThree decisions worth stating:\n\n- **It grows, it does not scroll.** A one-line box that hides the second half\n  of what you wrote is the most-complained-about part of every chat UI. The\n  box starts at the tall control rung and grows to `maxRows` before it gives\n  up and scrolls.\n- **The submit gesture is a setting.** Enter-to-send is right for a chat lane\n  and wrong for a prompt editor where every draft is three paragraphs, so\n  both are first-class and the *other* key always inserts a newline.\n- **Stop is never disabled.** While a run is in flight the composer is\n  `disabled`, but the button that ends the run cannot inherit that — a stop\n  you cannot press is not a stop.\n\nThe ref lands on the textarea rather than the form: focusing the composer is\nthe thing hosts actually reach for.",
+  "props": [
+    {
+      "name": "onSend",
+      "type": "(value: string) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Fired with the trimmed draft. Never fired with an empty string."
+    },
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Draft when the host owns it. Pass with `onValueChange`."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "required": false,
+      "defaultValue": "",
+      "description": "Initial draft when uncontrolled."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called on every keystroke with the new draft."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Message",
+      "description": "Placeholder for the empty box. Defaults to `\"Message\"`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Block sending — a closed thread, a failed connection."
+    },
+    {
+      "name": "busy",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "A run is in flight. With `onStop`, swaps Send for Stop."
+    },
+    {
+      "name": "onStop",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Abort the in-flight run. Renders the Stop button while `busy`."
+    },
+    {
+      "name": "submitKey",
+      "type": "\"enter\" | \"mod+enter\"",
+      "required": false,
+      "defaultValue": "enter",
+      "description": "Which gesture submits. Defaults to `\"enter\"`."
+    },
+    {
+      "name": "maxRows",
+      "type": "number",
+      "required": false,
+      "defaultValue": "8",
+      "description": "Rows the box may grow to before it scrolls. Defaults to `8`."
+    },
+    {
+      "name": "sendLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Send",
+      "description": "Label on the send button. Defaults to `\"Send\"`."
+    },
+    {
+      "name": "stopLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Stop",
+      "description": "Label on the stop button. Defaults to `\"Stop\"`."
+    },
+    {
+      "name": "attachments",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Tray above the input — attachment chips, a reply-to quote."
+    },
+    {
+      "name": "toolbar",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Controls beside the send button — an attach button, a model picker."
+    },
+    {
+      "name": "hint",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Quiet strip under the input — a keyboard hint, a character count."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Message",
+      "description": "Accessible name for the input. Defaults to `\"Message\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"form\">, \"onSubmit\" | \"onChange\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The thing you type into: an auto-growing textarea, a send affordance, and slots for everything a host wants to hang off them.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Composer onSend={send} />\n<Composer submitKey=\"mod+enter\" busy={running} onStop={abort} onSend={send} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/composer",
+  "mdUrl": "/docs/components/composer.md",
+  "jsonUrl": "/r/components/composer.json",
+  "specimens": [
+    {
+      "title": "Composer",
+      "group": "chat",
+      "components": [
+        "Composer"
+      ],
+      "code": "<div className=\"flex w-full max-w-[42rem] flex-col gap-(--cue-space-5)\">\n  <Composer\n    value={draft}\n    onValueChange={setDraft}\n    onSend={(value) => {\n      setSent(value);\n      setDraft(\"\");\n    }}\n    placeholder=\"Ask the swarm\"\n    hint={<span>Enter sends. Shift+Enter starts a line.</span>}\n  />\n  <Composer\n    onSend={() => {}}\n    submitKey=\"mod+enter\"\n    busy\n    onStop={() => {}}\n    defaultValue=\"Patching universe 2\"\n    hint=\"Busy: the send control becomes Stop.\"\n  />\n  <Composer onSend={() => {}} disabled placeholder=\"Disabled\" />\n  {sent === null ? null : <Chip tone=\"accent\">sent: {sent}</Chip>}\n</div>",
+      "note": "An auto-growing textarea at the large control height, with an attachment slot, a toolbar slot and a Stop that reports rather than decides.",
+      "interaction": "Enter sends by default, mod+Enter when configured the other way; Shift+Enter always inserts a newline."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/computer-use.json

@@ -0,0 +1,84 @@
+{
+  "name": "ComputerUse",
+  "slug": "computer-use",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The screen the agent is driving, with a cursor trail and what it is doing right now.",
+  "props": [
+    {
+      "name": "url",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the session is pointed at."
+    },
+    {
+      "name": "steps",
+      "type": "readonly ComputerStep[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Actions taken, in order. Each carries the coordinates the cursor moved to."
+    },
+    {
+      "name": "activeIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which step is happening now. The two before it stay as a fading trail."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The viewport being driven: a video stream, a screenshot, an iframe."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"url\" | \"steps\" | \"activeIndex\" | \"children\"> & {\n  /** What the session is pointed at. */\n  url: string;\n  /** Actions taken, in order. Each carries the coordinates the cursor moved to. */\n  steps: readonly ComputerStep[];\n  /** Which step is happening now. The two before it stay as a fading trail. */\n  activeIndex: number;\n  /** The viewport being driven: a video stream, a screenshot, an iframe. */\n  children: React.ReactNode;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-text-body",
+    "--cue-warn"
+  ],
+  "summary": "The screen the agent is driving, with a cursor trail and what it is doing right now.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ComputerUse } from \"@cueplusplus/ui/elements\";\n\n<ComputerUse url=\"github.com/...\" steps={steps} activeIndex={2}>\n  <iframe title=\"Session\" src={streamUrl} />\n</ComputerUse>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/computer-use",
+  "mdUrl": "/docs/components/computer-use.md",
+  "jsonUrl": "/r/components/computer-use.json",
+  "specimens": [
+    {
+      "title": "ComputerUse",
+      "group": "elements-agents",
+      "components": [
+        "ComputerUse"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"mid-session\" wide>\n    <ComputerUse\n      url=\"desk.local/show/patch\"\n      steps={CLICKS}\n      activeIndex={2}\n    >\n      <div className=\"flex h-40 flex-col gap-(--cue-space-2) bg-surface-1 p-(--cue-space-4)\">\n        <span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">\n          UNIVERSE 3 — PATCH\n        </span>\n        <span className=\"text-(length:--cue-text-body) text-fg-muted\">\n          6 fixtures selected · start address 1\n        </span>\n      </div>\n    </ComputerUse>\n  </Specimen>\n  <Specimen label=\"first step\" wide>\n    <ComputerUse url=\"desk.local/show/patch\" steps={CLICKS} activeIndex={0}>\n      <div className=\"flex h-40 items-center justify-center bg-surface-1\">\n        <span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">\n          SHOW FILE — OVERVIEW\n        </span>\n      </div>\n    </ComputerUse>\n  </Specimen>\n</Specimens>",
+      "note": "The screen the agent is driving, with a cursor trail behind it and the current action named underneath. The two steps before the live one stay as fading dots, which is what turns a jumping pointer into a path you can follow. The viewport is `children` — a screenshot, a video stream, a sandboxed iframe — so the element frames it and isolates nothing of its own.",
+      "interaction": "none, and deliberately: this is a view of a session, not a remote control. The cursor and its trail are `aria-hidden`; the action row underneath is what a screen reader gets."
+    }
+  ],
+  "todo": true
+}