@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/message-actions.json

@@ -0,0 +1,99 @@
+{
+  "name": "MessageActions",
+  "slug": "message-actions",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Copy, rate, and regenerate. Each action confirms itself with a small state change.",
+  "props": [
+    {
+      "name": "copied",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the copy button shows a green check confirmation."
+    },
+    {
+      "name": "reaction",
+      "type": "Reaction",
+      "required": true,
+      "defaultValue": null,
+      "description": "Active thumbs reaction, or null when none is selected."
+    },
+    {
+      "name": "regenerating",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the regenerate icon spins to show work in progress."
+    },
+    {
+      "name": "onCopy",
+      "type": "() => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the copy control is pressed."
+    },
+    {
+      "name": "onReactionChange",
+      "type": "(reaction: Reaction) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the user toggles thumbs up or thumbs down."
+    },
+    {
+      "name": "onRegenerate",
+      "type": "() => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the regenerate control is pressed."
+    },
+    {
+      "name": "onMore",
+      "type": "() => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the overflow menu control is pressed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-ok",
+    "--cue-surface-2"
+  ],
+  "summary": "Copy, rate, and regenerate.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MessageActions } from \"@cueplusplus/ui/elements\";\n\n<MessageActions\n  copied={false}\n  reaction={null}\n  regenerating={false}\n  onCopy={() => {}}\n  onReactionChange={setReaction}\n  onRegenerate={() => {}}\n  onMore={() => {}}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/message-actions",
+  "mdUrl": "/docs/components/message-actions.md",
+  "jsonUrl": "/r/components/message-actions.json",
+  "specimens": [
+    {
+      "title": "MessageActions",
+      "group": "elements-thread",
+      "components": [
+        "MessageActions"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"resting\" wide>\n    <MessageActions\n      copied={copied}\n      reaction={reaction}\n      regenerating={regenerating}\n      onCopy={() => setCopied((current) => !current)}\n      onReactionChange={setReaction}\n      onRegenerate={() => setRegenerating((current) => !current)}\n      onMore={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"copied\" wide>\n    <MessageActions\n      copied\n      reaction={null}\n      regenerating={false}\n      onCopy={() => undefined}\n      onReactionChange={() => undefined}\n      onRegenerate={() => undefined}\n      onMore={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"rated, regenerating\" wide>\n    <MessageActions\n      copied={false}\n      reaction=\"up\"\n      regenerating\n      onCopy={() => undefined}\n      onReactionChange={() => undefined}\n      onRegenerate={() => undefined}\n      onMore={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The row under an answer: copy, rate it, run it again, or ask for more. Every action confirms itself in place — copy swaps to a check and turns green, a rating latches, regenerate spins while it is out — so nothing needs a toast to say it worked.",
+      "interaction": "all five are named icon buttons; the two ratings carry aria-pressed and toggle off when pressed again. The copy swap is a crossfade between two icons in one cell, not a re-mount."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/message-attachments.json

@@ -0,0 +1,63 @@
+{
+  "name": "MessageAttachments",
+  "slug": "message-attachments",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The files a turn carried, as received rather than as staged. An image gets a preview\ntile that opens; anything else gets a row with its size and, for a document, its\npage count.",
+  "props": [
+    {
+      "name": "attachments",
+      "type": "readonly MessageAttachmentItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Files carried by the message. Images render as a thumbnail row, everything else as\na chip."
+    },
+    {
+      "name": "onOpen",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when an attachment is opened for preview."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"attachments\" | \"onOpen\"> & {\n  /**\n   * Files carried by the message. Images render as a thumbnail row, everything else as\n   * a chip.\n   */\n  attachments: readonly MessageAttachmentItem[];\n  /** Called when an attachment is opened for preview. */\n  onOpen?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "The files a turn carried, as received rather than as staged.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/message-attachments",
+  "mdUrl": "/docs/components/message-attachments.md",
+  "jsonUrl": "/r/components/message-attachments.json",
+  "specimens": [
+    {
+      "title": "MessageAttachments",
+      "group": "elements-thread",
+      "components": [
+        "MessageAttachments"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"image, file, document\" wide>\n    <MessageAttachments attachments={ATTACHMENTS} onOpen={() => undefined} />\n  </Specimen>\n  <Specimen label=\"one document\" wide>\n    <MessageAttachments attachments={ATTACHMENTS.slice(2)} />\n  </Specimen>\n</Specimens>",
+      "note": "Files as received, not as staged: an image gets a preview tile that opens, a document gets its page count, anything else gets its size. Upstream's uploader lives in the composer — this is the read-only other end of it.",
+      "interaction": "every row is one button with its name as the label; the image tile grows very slightly under the pointer, and holds still under reduced motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/message-branches.json

@@ -0,0 +1,71 @@
+{
+  "name": "MessageBranches",
+  "slug": "message-branches",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Navigate between regenerated versions of the same answer without losing your place.",
+  "props": [
+    {
+      "name": "variants",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Alternate regenerated answers the user can step through."
+    },
+    {
+      "name": "index",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which variant is currently displayed."
+    },
+    {
+      "name": "onIndexChange",
+      "type": "(index: number) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the previous or next branch control is pressed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-text-body"
+  ],
+  "summary": "Navigate between regenerated versions of the same answer without losing your place.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MessageBranches } from \"@cueplusplus/ui/elements\";\n\n<MessageBranches\n  variants={[\"First answer.\", \"Second answer.\"]}\n  index={0}\n  onIndexChange={setIndex}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/message-branches",
+  "mdUrl": "/docs/components/message-branches.md",
+  "jsonUrl": "/r/components/message-branches.json",
+  "specimens": [
+    {
+      "title": "MessageBranches",
+      "group": "elements-thread",
+      "components": [
+        "MessageBranches"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two versions\" wide>\n    <MessageBranches variants={BRANCHES} index={branch} onIndexChange={setBranch} />\n  </Specimen>\n  <Specimen label=\"one version — nowhere to go\" wide>\n    <MessageBranches\n      variants={BRANCHES.slice(0, 1)}\n      index={0}\n      onIndexChange={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Two answers to the same question, and a way through them that does not lose your place. The counter is the whole affordance — `2 / 2` is what tells you a second version exists at all — and it wraps at both ends rather than dead-ending.",
+      "interaction": "both arrows are named and go disabled when there is only one version, which is the honest state for a turn nobody has regenerated."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/message-list.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "The transcript scroller: sticks to the bottom, and stops fighting you the\nmoment you scroll up.\n\nFollowing is a *mode*, not a scroll position. While pinned to the bottom the\nview follows new turns; scroll up to read something and it lets go and offers\na \"jump to latest\" pill instead — because a stream that yanks the viewport\nmid-sentence is the single most common reason people stop reading a chat\npane. Coming back to the bottom re-arms it.\n\nDeliberately **not** virtualised. A virtualiser needs a measurable row height\nand chat turns are variable-height by nature; the cost of getting that wrong\n(jumping scrollbars) is worse than the cost of a few hundred DOM nodes. When\na thread really is unbounded, page it — do not virtualise it.",
+  "description": "The transcript scroller: sticks to the bottom, and stops fighting you the\nmoment you scroll up.\n\nFollowing is a *mode*, not a scroll position. While pinned to the bottom the\nview follows new turns; scroll up to read something and it lets go and offers\na \"jump to latest\" pill instead — because a stream that yanks the viewport\nmid-sentence is the single most common reason people stop reading a chat\npane. Coming back to the bottom re-arms it.\n\nIt follows a turn that is still growing, too — the items container is watched\nfor growth, so a streaming bubble keeps the bottom in view without the host\nadding anything, while something merely collapsing leaves the view alone. And\nwhen you have scrolled up, a turn that grows offers the pill instead of\npulling you down.\n\nDeliberately **not** virtualised. A virtualiser needs a measurable row height\nand chat turns are variable-height by nature; the cost of getting that wrong\n(jumping scrollbars) is worse than the cost of a few hundred DOM nodes. When\na thread really is unbounded, page it — do not virtualise it.",
   "props": [
     {
       "name": "children",

package/manifest/components/message-pair.json

@@ -0,0 +1,86 @@
+{
+  "name": "MessagePair",
+  "slug": "message-pair",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A user bubble and a streaming assistant reply, with actions that appear on hover.",
+  "props": [
+    {
+      "name": "userMessage",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Text shown in the user bubble on the right."
+    },
+    {
+      "name": "words",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Assistant reply broken into words for streaming."
+    },
+    {
+      "name": "visibleWords",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many assistant words are currently visible."
+    },
+    {
+      "name": "streaming",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the newest assistant words tint blue as they arrive."
+    },
+    {
+      "name": "variant",
+      "type": "\"flat\" | \"bubble\"",
+      "required": false,
+      "defaultValue": "bubble",
+      "description": "bubble wraps the user message in a surface; flat renders it as plain right-aligned\ntext."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-text-body"
+  ],
+  "summary": "A user bubble and a streaming assistant reply, with actions that appear on hover.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MessagePair } from \"@cueplusplus/ui/elements\";\n\n<MessagePair\n  userMessage=\"Explain the composer.\"\n  words={[\"Here\", \"is\", \"a\", \"short\", \"reply.\"]}\n  visibleWords={5}\n  streaming={false}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/message-pair",
+  "mdUrl": "/docs/components/message-pair.md",
+  "jsonUrl": "/r/components/message-pair.json",
+  "specimens": [
+    {
+      "title": "MessagePair",
+      "group": "elements-thread",
+      "components": [
+        "MessagePair"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"bubble · streaming\" wide>\n    <MessagePair\n      userMessage=\"Plot's in. Front truss, universe 3.\"\n      words={SPOKEN}\n      visibleWords={5}\n      streaming\n    />\n  </Specimen>\n  <Specimen label=\"flat · settled\" wide>\n    <MessagePair\n      userMessage=\"Plot's in. Front truss, universe 3.\"\n      words={SPOKEN}\n      visibleWords={SPOKEN.length}\n      streaming={false}\n      variant=\"flat\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A whole turn in one element: what was asked, and the answer streaming under it with its actions waiting on hover. The two variants are the two house styles for a user turn — a bubble, or right-aligned text with no chrome at all.",
+      "interaction": "the action row is invisible until the turn is hovered *or* focused, which is what keeps a keyboard from losing it. Both buttons are named."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/message-queue.json

@@ -0,0 +1,74 @@
+{
+  "name": "MessageQueue",
+  "slug": "message-queue",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Turns you typed while a run was in flight, stacked and cancelable until it finishes.",
+  "props": [
+    {
+      "name": "running",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The turn currently in flight, shown above the queue."
+    },
+    {
+      "name": "queued",
+      "type": "readonly QueuedMessage[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Turns waiting to send, in the order they will drain once the run finishes."
+    },
+    {
+      "name": "onCancel",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a queued turn is removed before it ever sends."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"running\" | \"queued\" | \"onCancel\"\n> & {\n  /** The turn currently in flight, shown above the queue. */\n  running: string;\n  /** Turns waiting to send, in the order they will drain once the run finishes. */\n  queued: readonly QueuedMessage[];\n  /** Called when a queued turn is removed before it ever sends. */\n  onCancel?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-text-body"
+  ],
+  "summary": "Turns you typed while a run was in flight, stacked and cancelable until it finishes.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MessageQueue } from \"@cueplusplus/ui/elements\";\n\n<MessageQueue\n  running=\"Fix the converter and add a guard\"\n  queued={[{ id: \"a\", text: \"Also add a changeset\" }]}\n  onCancel={(id) => drop(id)}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/message-queue",
+  "mdUrl": "/docs/components/message-queue.md",
+  "jsonUrl": "/r/components/message-queue.json",
+  "specimens": [
+    {
+      "title": "MessageQueue",
+      "group": "elements-thread",
+      "components": [
+        "MessageQueue"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"one running, two queued\" wide>\n    <MessageQueue\n      running=\"Patching universe 3\"\n      queued={queue}\n      onCancel={(id) => setQueue((current) => current.filter((item) => item.id !== id))}\n    />\n  </Specimen>\n  <Specimen label=\"nothing queued\" wide>\n    <MessageQueue running=\"Patching universe 3\" queued={[]} />\n  </Specimen>\n</Specimens>",
+      "note": "What you typed while the last run was still out. The turn in flight pings at the top; everything behind it is numbered, cancellable and explicitly told when it will go. A queue that did not say 'sends when this finishes' would look like a list of failures.",
+      "interaction": "each row's × is a named button — the message text is in the label, so five rows do not all read as 'Remove'."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/message-timing.json

@@ -0,0 +1,62 @@
+{
+  "name": "MessageTiming",
+  "slug": "message-timing",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "What the turn cost: time to first token, throughput, tokens, money.",
+  "props": [
+    {
+      "name": "stats",
+      "type": "readonly TimingStat[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Label and value pairs, pre-formatted. Show fewer while streaming and the full set\nonce the turn settles."
+    },
+    {
+      "name": "streaming",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Tints the values blue while they are still moving."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"stats\" | \"streaming\"> & {\n  /**\n   * Label and value pairs, pre-formatted. Show fewer while streaming and the full set\n   * once the turn settles.\n   */\n  stats: readonly TimingStat[];\n  /** Tints the values blue while they are still moving. */\n  streaming?: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-stream"
+  ],
+  "summary": "What the turn cost: time to first token, throughput, tokens, money.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MessageTiming } from \"@cueplusplus/ui/elements\";\n\n<MessageTiming\n  stats={[\n    { label: \"ttft\", value: \"0.4s\" },\n    { label: \"total\", value: \"2.6s\" },\n  ]}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/message-timing",
+  "mdUrl": "/docs/components/message-timing.md",
+  "jsonUrl": "/r/components/message-timing.json",
+  "specimens": [
+    {
+      "title": "MessageTiming",
+      "group": "elements-thread",
+      "components": [
+        "MessageTiming"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"streaming\" wide>\n    <MessageTiming stats={TIMING.slice(0, 2)} streaming />\n  </Specimen>\n  <Specimen label=\"settled\" wide>\n    <MessageTiming stats={TIMING} />\n  </Specimen>\n</Specimens>",
+      "note": "What the turn cost, in the footer where a reader can ignore it. The values are strings the caller already formatted; while the turn is still streaming they sit in the live hue and settle into ink when it lands, so the row doubles as a state.",
+      "interaction": "none. It is four label/value pairs in mono, tabular so the numbers do not jitter as they update."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/mobile-composer.json

@@ -0,0 +1,126 @@
+{
+  "name": "MobileComposer",
+  "slug": "mobile-composer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The bottom sheet: keyboard-aware, quick actions above, thumb-sized targets.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current input. The field is 16px so iOS does not zoom on focus."
+    },
+    {
+      "name": "keyboardOpen",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Collapses the quick actions and the home indicator inset when the keyboard is up."
+    },
+    {
+      "name": "running",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps send for stop, and suppresses Return-to-send while a run is in flight."
+    },
+    {
+      "name": "actions",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Quick actions above the field, scrolled horizontally."
+    },
+    {
+      "name": "onAction",
+      "type": "((action: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a quick action is tapped. Omit it and the chips render disabled, since\nactions is required and the row would otherwise be inert."
+    },
+    {
+      "name": "onAttach",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the attachment control. Omit it and the control renders disabled."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the message is typed."
+    },
+    {
+      "name": "onSend",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to send."
+    },
+    {
+      "name": "onStop",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to stop a run in flight."
+    },
+    {
+      "name": "onFocus",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the field takes focus; drive keyboardOpen from it."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"value\"\n  | \"keyboardOpen\"\n  | \"running\"\n  | \"actions\"\n  | \"onAction\"\n  | \"onAttach\"\n  | \"onValueChange\"\n  | \"onSend\"\n  | \"onStop\"\n  | \"onFocus\"\n> & {\n  /** Current input. The field is 16px so iOS does not zoom on focus. */\n  value: string;\n  /** Collapses the quick actions and the home indicator inset when the keyboard is up. */\n  keyboardOpen: boolean;\n  /** Swaps send for stop, and suppresses Return-to-send while a run is in flight. */\n  running: boolean;\n  /** Quick actions above the field, scrolled horizontally. */\n  actions: readonly string[];\n  /**\n   * Called when a quick action is tapped. Omit it and the chips render disabled, since\n   * actions is required and the row would otherwise be inert.\n   */\n  onAction?: (action: string) => void;\n  /** Called from the attachment control. Omit it and the control renders disabled. */\n  onAttach?: () => void;\n  /** Called as the message is typed. */\n  onValueChange?: (value: string) => void;\n  /** Called to send. */\n  onSend?: () => void;\n  /** Called to stop a run in flight. */\n  onStop?: () => void;\n  /** Called when the field takes focus; drive keyboardOpen from it. */\n  onFocus?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "The bottom sheet: keyboard-aware, quick actions above, thumb-sized targets.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MobileComposer } from \"@cueplusplus/ui/elements\";\n\n<MobileComposer\n  value={value}\n  keyboardOpen={keyboardOpen}\n  running={false}\n  actions={actions}\n  onValueChange={setValue}\n  onSend={send}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/mobile-composer",
+  "mdUrl": "/docs/components/mobile-composer.md",
+  "jsonUrl": "/r/components/mobile-composer.json",
+  "specimens": [
+    {
+      "title": "MobileComposer",
+      "group": "elements-composer",
+      "components": [
+        "MobileComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"keyboard down\" wide>\n    <MobileComposer\n      value={phone}\n      keyboardOpen={false}\n      running={false}\n      actions={[\"Patch\", \"Plot\", \"Rig check\", \"Render pre-vis\"]}\n      onAction={(action) => setPhone(action)}\n      onAttach={() => undefined}\n      onValueChange={setPhone}\n      onSend={() => setPhone(\"\")}\n    />\n  </Specimen>\n  <Specimen label=\"keyboard up\" wide>\n    <MobileComposer\n      value=\"six ESPRITEs on universe 3\"\n      keyboardOpen\n      running={false}\n      actions={[\"Patch\", \"Plot\"]}\n      onValueChange={() => undefined}\n      onSend={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"running\" wide>\n    <MobileComposer\n      value=\"\"\n      keyboardOpen\n      running\n      actions={[\"Patch\", \"Plot\"]}\n      onStop={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The same composer on a phone: a bottom sheet with thumb-sized targets, quick actions scrolling above the field, and a 16px input so iOS does not zoom when it takes focus. `keyboardOpen` is the whole layout switch — the quick actions and the home-indicator inset both belong to the state where the keyboard is down.",
+      "interaction": "send becomes stop while a run is in flight, and Return stops sending — a second send during a stream is almost always a mistake, so the element refuses it rather than queueing it."
+    }
+  ],
+  "todo": true
+}