@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/generation-loader.json

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

package/manifest/components/generative-ui.json

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

package/manifest/components/guardrail-notice.json

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

package/manifest/components/hover-card.json

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

package/manifest/components/image-generation.json

@@ -0,0 +1,67 @@
+{
+  "name": "ImageGeneration",
+  "slug": "image-generation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A dot grid holds the frame while the image resolves out of a blur.",
+  "props": [
+    {
+      "name": "prompt",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Prompt text shown under the image frame."
+    },
+    {
+      "name": "generating",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the frame holds a pulsing dot grid; otherwise the image resolves."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"prompt\" | \"generating\"> & {\n  /** Prompt text shown under the image frame. */\n  prompt: string;\n  /** When true the frame holds a pulsing dot grid; otherwise the image resolves. */\n  generating: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-ui"
+  ],
+  "summary": "A dot grid holds the frame while the image resolves out of a blur.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ImageGeneration } from \"@cueplusplus/ui/elements\";\n\n<ImageGeneration prompt=\"A calm blue abstract\" generating={false} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/image-generation",
+  "mdUrl": "/docs/components/image-generation.md",
+  "jsonUrl": "/r/components/image-generation.json",
+  "specimens": [
+    {
+      "title": "ImageGeneration",
+      "group": "elements-agents",
+      "components": [
+        "ImageGeneration"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"generating\">\n    <ImageGeneration prompt=\"Pre-vis: front wash at 8.4 m trim\" generating />\n  </Specimen>\n  <Specimen label=\"resolved\">\n    <ImageGeneration prompt=\"Pre-vis: front wash at 8.4 m trim\" generating={false} />\n  </Specimen>\n</Specimens>",
+      "note": "A dot grid holds the square while the image resolves out of a blur — the frame is the right size from the first frame, so nothing below it moves when the picture lands. While generating, the prompt is replaced by a shimmering label; when it settles, the prompt is what is left under the image.",
+      "interaction": "regenerate is a labelled icon button. The grid and the image are both `aria-hidden`: the prompt underneath is the description, and a decorative placeholder should not be announced as a picture."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/info-tip.json

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

package/manifest/components/inline-citation.json

@@ -0,0 +1,77 @@
+{
+  "name": "InlineCitation",
+  "slug": "inline-citation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Numbered references inside a sentence, each with a hover preview of its source.",
+  "props": [
+    {
+      "name": "sources",
+      "type": "CitationSource[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Sources attached to the numbered reference markers in the sentence."
+    },
+    {
+      "name": "openIndex",
+      "type": "number | null",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which citation preview is open, or null when none is open."
+    },
+    {
+      "name": "onOpenIndexChange",
+      "type": "(index: number | null) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when a citation marker opens or closes its preview."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"p\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro"
+  ],
+  "summary": "Numbered references inside a sentence, each with a hover preview of its source.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { InlineCitation } from \"@cueplusplus/ui/elements\";\n\n<InlineCitation\n  sources={[\n    {\n      domain: \"docs.example.com\",\n      title: \"Optimistic updates\",\n      snippet: \"Confirm writes after paint.\",\n    },\n  ]}\n  openIndex={0}\n  onOpenIndexChange={setOpenIndex}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/inline-citation",
+  "mdUrl": "/docs/components/inline-citation.md",
+  "jsonUrl": "/r/components/inline-citation.json",
+  "specimens": [
+    {
+      "title": "InlineCitation",
+      "group": "elements-knowledge",
+      "components": [
+        "InlineCitation"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the first marker open\" wide>\n    <InlineCitation\n      sources={CITED}\n      openIndex={citation}\n      onOpenIndexChange={setCitation}\n    />\n  </Specimen>\n  <Specimen label=\"both closed\" wide>\n    <InlineCitation\n      sources={CITED}\n      openIndex={null}\n      onOpenIndexChange={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The marker inside the sentence, rather than the list under it: a numbered chip the paragraph flows around, and behind each one the page it stands on. `Sources` is the bibliography; this is the footnote, and the two are meant to be read together — the chip says a claim is attributable without spending a clause saying so.",
+      "interaction": "each marker is a button, so the preview is reachable from a keyboard as well as a pointer; the open one inverts to the accent fill. The card is the family's one portal, and it carries the island stamp — opened inside an `AgentSurface`, it paints in that island's values rather than the document's."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/job-progress.json

@@ -0,0 +1,96 @@
+{
+  "name": "JobProgress",
+  "slug": "job-progress",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Work measured in minutes: weighted stages, an ETA, and a way out.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the job is doing."
+    },
+    {
+      "name": "stages",
+      "type": "readonly JobStage[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Stages with relative weights, so a long install does not read the same as a fast\nclone."
+    },
+    {
+      "name": "stageIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which stage is running. Passing stages.length marks the job finished, and the bar\nnever runs past its track."
+    },
+    {
+      "name": "stageProgress",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Progress inside the current stage, 0 to 1."
+    },
+    {
+      "name": "eta",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted estimate. Replaced by done once finished."
+    },
+    {
+      "name": "onCancel",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to stop the job. Hidden once it finishes."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"title\"\n  | \"stages\"\n  | \"stageIndex\"\n  | \"stageProgress\"\n  | \"eta\"\n  | \"onCancel\"\n> & {\n  /** What the job is doing. */\n  title: string;\n  /**\n   * Stages with relative weights, so a long install does not read the same as a fast\n   * clone.\n   */\n  stages: readonly JobStage[];\n  /**\n   * Which stage is running. Passing stages.length marks the job finished, and the bar\n   * never runs past its track.\n   */\n  stageIndex: number;\n  /** Progress inside the current stage, 0 to 1. */\n  stageProgress: number;\n  /** Pre-formatted estimate. Replaced by done once finished. */\n  eta: string;\n  /** Called to stop the job. Hidden once it finishes. */\n  onCancel?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Work measured in minutes: weighted stages, an ETA, and a way out.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { JobProgress } from \"@cueplusplus/ui/elements\";\n\n<JobProgress\n  title=\"Verify the fix on CI\"\n  stages={stages}\n  stageIndex={1}\n  stageProgress={0.6}\n  eta=\"about 3 min\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/job-progress",
+  "mdUrl": "/docs/components/job-progress.md",
+  "jsonUrl": "/r/components/job-progress.json",
+  "specimens": [
+    {
+      "title": "JobProgress",
+      "group": "elements-agents",
+      "components": [
+        "JobProgress"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"rendering\" wide>\n    <JobProgress\n      title=\"Overnight patch and pre-vis\"\n      stages={STAGES}\n      stageIndex={2}\n      stageProgress={0.42}\n      eta=\"4m left\"\n      onCancel={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"done\" wide>\n    <JobProgress\n      title=\"Overnight patch and pre-vis\"\n      stages={STAGES}\n      stageIndex={STAGES.length}\n      stageProgress={1}\n      eta=\"4m left\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Work measured in minutes rather than steps. The stages are weighted, so a six-minute render does not read the same length as a one-second export, and the bar is filled from those weights plus the fraction of the current stage — which is why it never jumps backwards when a short stage ends.",
+      "interaction": "cancel is a labelled icon button and disappears once the job finishes: there is nothing left to stop, and a dead X beside a green tick reads as an error."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/launcher-bubble.json

@@ -0,0 +1,105 @@
+{
+  "name": "LauncherBubble",
+  "slug": "launcher-bubble",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The floating entry point, and the panel it opens into.",
+  "props": [
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the panel is showing. The trigger icon crossfades either way."
+    },
+    {
+      "name": "unread",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Badge count on the closed bubble. Hidden at zero and while open."
+    },
+    {
+      "name": "greeting",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Opening line in the panel."
+    },
+    {
+      "name": "prompts",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Ways in, so the first message does not have to be invented."
+    },
+    {
+      "name": "onToggle",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the bubble is pressed."
+    },
+    {
+      "name": "onPick",
+      "type": "((prompt: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a starter prompt is chosen."
+    },
+    {
+      "name": "onStart",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the Start a conversation action, for opening an empty thread."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"open\"\n  | \"unread\"\n  | \"greeting\"\n  | \"prompts\"\n  | \"onToggle\"\n  | \"onPick\"\n  | \"onStart\"\n> & {\n  /** Whether the panel is showing. The trigger icon crossfades either way. */\n  open: boolean;\n  /** Badge count on the closed bubble. Hidden at zero and while open. */\n  unread: number;\n  /** Opening line in the panel. */\n  greeting: string;\n  /** Ways in, so the first message does not have to be invented. */\n  prompts: readonly string[];\n  /** Called when the bubble is pressed. */\n  onToggle?: () => void;\n  /** Called when a starter prompt is chosen. */\n  onPick?: (prompt: string) => void;\n  /** Called from the Start a conversation action, for opening an empty thread. */\n  onStart?: () => 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",
+    "--cue-text-ui"
+  ],
+  "summary": "The floating entry point, and the panel it opens into.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { LauncherBubble } from \"@cueplusplus/ui/elements\";\n\n<LauncherBubble\n  open={open}\n  unread={2}\n  greeting=\"Need a hand?\"\n  prompts={prompts}\n  onToggle={toggle}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/launcher-bubble",
+  "mdUrl": "/docs/components/launcher-bubble.md",
+  "jsonUrl": "/r/components/launcher-bubble.json",
+  "specimens": [
+    {
+      "title": "LauncherBubble",
+      "group": "elements-composer",
+      "components": [
+        "LauncherBubble"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"open\" wide>\n    <LauncherBubble\n      open={launcher}\n      unread={2}\n      greeting=\"Ask us about the venue\"\n      prompts={[\"What is the rig?\", \"Can I bring my own desk?\", \"Who is the LX contact?\"]}\n      onToggle={() => setLauncher((open) => !open)}\n      onPick={() => setLauncher(false)}\n      onStart={() => setLauncher(false)}\n    />\n  </Specimen>\n  <Specimen label=\"closed, two waiting\" wide>\n    <LauncherBubble\n      open={false}\n      unread={2}\n      greeting=\"Ask us about the venue\"\n      prompts={[\"What is the rig?\"]}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The floating entry point and the panel it opens into — the shape an assistant takes on somebody else's site. The badge counts unread and disappears the moment the panel is open, because a count of things you are currently looking at is noise. The starter prompts exist so the first message does not have to be invented by a visitor who has no idea what this thing knows.",
+      "interaction": "the bubble carries `aria-expanded` and its label changes with it (`Open the assistant` / `Close the assistant`); the two icons cross-fade in one grid cell so nothing reflows."
+    }
+  ],
+  "todo": true
+}