@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/elicitation-form.json

@@ -0,0 +1,103 @@
+{
+  "name": "ElicitationForm",
+  "slug": "elicitation-form",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A server pausing mid-tool-call to ask you for the fields it still needs.",
+  "props": [
+    {
+      "name": "server",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which server paused to ask."
+    },
+    {
+      "name": "message",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why the input is needed, in the server's words."
+    },
+    {
+      "name": "fields",
+      "type": "readonly ElicitationField[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The schema the server sent, already resolved to display values."
+    },
+    {
+      "name": "state",
+      "type": "\"request\" | \"accepted\" | \"declined\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the action row for the outcome once the user answers."
+    },
+    {
+      "name": "onAccept",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the filled form is sent back."
+    },
+    {
+      "name": "onDecline",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the request is refused."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"server\"\n  | \"message\"\n  | \"fields\"\n  | \"state\"\n  | \"onAccept\"\n  | \"onDecline\"\n> & {\n  /** Which server paused to ask. */\n  server: string;\n  /** Why the input is needed, in the server's words. */\n  message: string;\n  /** The schema the server sent, already resolved to display values. */\n  fields: readonly ElicitationField[];\n  /** Swaps the action row for the outcome once the user answers. */\n  state: ElicitationState;\n  /** Called when the filled form is sent back. */\n  onAccept?: () => void;\n  /** Called when the request is refused. */\n  onDecline?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A server pausing mid-tool-call to ask you for the fields it still needs.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ElicitationForm } from \"@cueplusplus/ui/elements\";\n\n<ElicitationForm\n  server=\"github-mcp\"\n  message=\"Confirm where the release notes should be published.\"\n  fields={fields}\n  state=\"request\"\n  onAccept={send}\n  onDecline={decline}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elicitation-form",
+  "mdUrl": "/docs/components/elicitation-form.md",
+  "jsonUrl": "/r/components/elicitation-form.json",
+  "specimens": [
+    {
+      "title": "ElicitationForm",
+      "group": "elements-composer",
+      "components": [
+        "ElicitationForm"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"asking\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state={elicitation}\n      onAccept={() => setElicitation(\"accepted\")}\n      onDecline={() => setElicitation(\"declined\")}\n    />\n  </Specimen>\n  <Specimen label=\"answered\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state=\"accepted\"\n    />\n  </Specimen>\n  <Specimen label=\"refused\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state=\"declined\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A server pausing mid-tool-call to ask for the fields it still needs — MCP's elicitation, drawn. The fields arrive already resolved to display values, so the element renders a schema without ever having parsed one, and `state` swaps the two buttons for the outcome the moment the user answers. Declining is a first-class answer here, not a dismissal.",
+      "interaction": "each field's control is chosen by its `kind` — a value chip, a row of options, or a switch — and the required ones are marked on the label rather than announced only on failure."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-composer.json

@@ -0,0 +1,64 @@
+{
+  "name": "EmptyStateComposer",
+  "slug": "empty-state-composer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A composer-shaped invitation under the suggestions. It is a display rather than a\nworking input — the placeholder is a string and send takes a handler — for the\nscreen whose real composer is somewhere else.",
+  "props": [
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Resting text in the input bar."
+    },
+    {
+      "name": "onSend",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the send control. Omit it and the control renders disabled."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"placeholder\"> & {\n  /** Resting text in the input bar. */\n  placeholder: string;\n  /** Called from the send control. Omit it and the control renders disabled. */\n  onSend?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "A composer-shaped invitation under the suggestions.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-composer",
+  "mdUrl": "/docs/components/empty-state-composer.md",
+  "jsonUrl": "/r/components/empty-state-composer.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-greeting.json

@@ -0,0 +1,49 @@
+{
+  "name": "EmptyStateGreeting",
+  "slug": "empty-state-greeting",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The one line at the top of a blank thread. A heading, so a screen reader lands on it.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"h2\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "The one line at the top of a blank thread.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-greeting",
+  "mdUrl": "/docs/components/empty-state-greeting.md",
+  "jsonUrl": "/r/components/empty-state-greeting.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-suggestion.json

@@ -0,0 +1,57 @@
+{
+  "name": "EmptyStateSuggestion",
+  "slug": "empty-state-suggestion",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One thing worth asking, as a pill. `index` staggers its entrance so the row arrives\nleft to right rather than all at once.",
+  "props": [
+    {
+      "name": "index",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Position in the row. Staggers the entrance so the pills arrive in order."
+    }
+  ],
+  "typeReferences": [
+    "ComponentProps<\"button\"> & {\n  /** Position in the row. Staggers the entrance so the pills arrive in order. */\n  index?: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "One thing worth asking, as a pill.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-suggestion",
+  "mdUrl": "/docs/components/empty-state-suggestion.md",
+  "jsonUrl": "/r/components/empty-state-suggestion.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-suggestions.json

@@ -0,0 +1,49 @@
+{
+  "name": "EmptyStateSuggestions",
+  "slug": "empty-state-suggestions",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The row the suggestion pills wrap in.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "The row the suggestion pills wrap in.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-suggestions",
+  "mdUrl": "/docs/components/empty-state-suggestions.md",
+  "jsonUrl": "/r/components/empty-state-suggestions.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state.json

@@ -0,0 +1,90 @@
+{
+  "name": "EmptyState",
+  "slug": "empty-state",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The \"there is nothing here\" panel body.\n\nCentred and quiet: an empty state is a report, not an alarm, so it uses the\nmuted ramp throughout and gets its emphasis from position rather than colour.\nThe icon is decorative — the title carries the meaning, so a screen reader\nhears one sentence instead of a shrug emoji.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is missing. One short line: \"No cues yet\"."
+    },
+    {
+      "name": "hint",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "How to fix it. One sentence, muted."
+    },
+    {
+      "name": "action",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The way out — normally a single `Button`."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional glyph above the title (e.g. a lucide icon), drawn `aria-hidden`."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra content between the hint and the action — rarely needed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "The \"there is nothing here\" panel body.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Panel>\n  <EmptyState\n    icon={ListX}\n    title=\"No cues yet\"\n    hint=\"Record one from the live look, or import a show file.\"\n    action={<Button variant=\"primary\">Record cue</Button>}\n  />\n</Panel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state",
+  "mdUrl": "/docs/components/empty-state.md",
+  "jsonUrl": "/r/components/empty-state.json",
+  "specimens": [
+    {
+      "title": "EmptyState",
+      "group": "chrome",
+      "components": [
+        "EmptyState"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel>\n    <EmptyState\n      icon={List}\n      title={COPY.empty.title}\n      hint={COPY.empty.hint}\n      action={<Button variant=\"primary\">{COPY.empty.action}</Button>}\n    />\n  </Panel>\n  <Panel>\n    <EmptyState\n      icon={Eye}\n      title={COPY.error.title}\n      hint={COPY.error.hint}\n      action={<Button>{COPY.error.action}</Button>}\n    >\n      <StatusDot tone=\"danger\" label=\"No reply\" />\n    </EmptyState>\n  </Panel>\n</div>",
+      "note": "The standard empty copy, from lib/samples.tsx. Same words everywhere in the app.",
+      "interaction": "the action is an ordinary Button and behaves like one."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/end-of-turn-summary.json

@@ -0,0 +1,77 @@
+{
+  "name": "EndOfTurnSummary",
+  "slug": "end-of-turn-summary",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "What the turn came to, in one line: `3 files changed +48 −12`.\n\nA rollup, not a control: it says what happened and offers nothing to do about\nit, because the things to do about it — review, keep, reject — belong to a\nbar above the composer that acts on the whole run, and a per-turn row with\nthose buttons on it is a row that can be pressed after the next turn has\nalready changed the same files.\n\nThe counts are drawn only when there are some. A turn that read four files\nand wrote nothing says `No files changed` and stops, rather than saying it\nwith two zeroes.",
+  "props": [
+    {
+      "name": "files",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many files the turn touched."
+    },
+    {
+      "name": "additions",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Lines added across them."
+    },
+    {
+      "name": "deletions",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Lines removed across them."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The whole line, replacing the one {@link formatChangeSummary} would build —\nfor a turn whose result is not a diff at all: `2 cues written`,\n`Nothing to change`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-ok",
+    "--cue-text-ui"
+  ],
+  "summary": "What the turn came to, in one line: `3 files changed +48 −12`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { EndOfTurnSummary } from \"@cueplusplus/ui/elements\";\n\n<EndOfTurnSummary files={3} additions={48} deletions={12} />\n<EndOfTurnSummary files={0} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/end-of-turn-summary",
+  "mdUrl": "/docs/components/end-of-turn-summary.md",
+  "jsonUrl": "/r/components/end-of-turn-summary.json",
+  "specimens": [
+    {
+      "title": "EndOfTurnSummary",
+      "group": "elements-thread",
+      "components": [
+        "EndOfTurnSummary"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three files\" wide>\n    <div className=\"w-full max-w-md\">\n      <EndOfTurnSummary files={3} additions={48} deletions={12} />\n    </div>\n  </Specimen>\n  <Specimen label=\"one file, additions only\" wide>\n    <div className=\"w-full max-w-md\">\n      <EndOfTurnSummary files={1} additions={6} />\n    </div>\n  </Specimen>\n  <Specimen label=\"nothing changed\" wide>\n    <div className=\"w-full max-w-md\">\n      <EndOfTurnSummary files={0} />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "What the turn came to, in one line. A rollup and not a control: review, keep and reject act on the whole run and belong above the composer, where they cannot be pressed after the next turn has already changed the same files. The + and − are CodeDiff's glyphs, so one transcript never shows two conventions for the same number, and a turn that changed nothing says so instead of saying it with two zeroes.",
+      "interaction": "none. It is a sentence with two tinted numbers in it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/env-var-input.json

@@ -0,0 +1,150 @@
+{
+  "name": "EnvVarInput",
+  "slug": "env-var-input",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A config value that may be a literal *or* a reference to an environment\nvariable — and looks unmistakably different in each case.\n\nWhen the value matches `env(NAME)` the text box is replaced by a warn-toned\npill naming the variable. That swap is the entire point: a config screen full\nof identical text boxes gives no way to tell \"this is the key\" from \"this is\nwhere the key comes from\", and the difference decides whether the value is\nsafe to screenshot, commit or paste into a ticket. Warn is the system's amber,\nso the pill reads as \"resolved elsewhere — check the environment\" rather than\nas an error.\n\nPorted from supbuddy's config editor, where the pattern earned its keep.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The value — a literal, or an `env(NAME)` reference. Use with `onValueChange`."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial value for an uncontrolled field."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new value: on every keystroke in the literal state, and with\n`\"\"` when the variable pill is cleared. One argument, because the pill's\nclear button has no DOM change event to hand on."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Shown while the literal field is empty."
+    },
+    {
+      "name": "secret",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Mask the literal value. The reference is never masked — a name is not a secret."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Prevent editing and grey the control out."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name for the underlying input, when the field is part of a form."
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id forwarded to the underlying input."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the field, when no {@link FieldLabel } names it."
+    },
+    {
+      "name": "clearLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Clear environment variable",
+      "description": "Accessible name for the pill's clear button. Defaults to `\"Clear environment variable\"`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the wrapper."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"defaultValue\">"
+  ],
+  "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-icon-md",
+    "--cue-icon-sm",
+    "--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-ui",
+    "--cue-warn"
+  ],
+  "summary": "A config value that may be a literal *or* a reference to an environment variable — and looks unmistakably different in each case.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<EnvVarInput aria-label=\"Service key\" secret value={key} onValueChange={setKey} />\n<EnvVarInput aria-label=\"Project URL\" defaultValue={envReference(\"SUPABASE_URL\")} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/env-var-input",
+  "mdUrl": "/docs/components/env-var-input.md",
+  "jsonUrl": "/r/components/env-var-input.json",
+  "specimens": [
+    {
+      "title": "EnvVarInput",
+      "group": "forms",
+      "components": [
+        "EnvVarInput"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"literal\">\n    <EnvVarInput aria-label=\"Node address, literal\" defaultValue=\"10.0.0.42\" />\n  </Specimen>\n  <Specimen label=\"env reference\">\n    <EnvVarInput aria-label=\"Node address, reference\" defaultValue=\"env(ARTNET_HOST)\" />\n  </Specimen>\n  <Specimen label=\"secret\">\n    <EnvVarInput aria-label=\"API token\" defaultValue=\"env(CUE_API_TOKEN)\" secret />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <EnvVarInput aria-label=\"Locked reference\" defaultValue=\"env(ARTNET_HOST)\" disabled />\n  </Specimen>\n</Specimens>",
+      "note": "A literal value and an `env(NAME)` reference are different things, so they do not look the same: the reference swaps to an amber token pill.",
+      "interaction": "the mode switch is a button; typing `env(` in the field is enough to flip it."
+    }
+  ],
+  "todo": true
+}