@cueplusplus/ui 0.13.0

package/manifest/components/checkbox-group.json

@@ -0,0 +1,70 @@
+{
+  "name": "CheckboxGroup",
+  "slug": "checkbox-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Shared state for a set of {@link Checkbox}es: one `value` array in, one out.\n\nGive it an accessible name (`aria-label`, or a {@link FieldLabel } inside a\n{@link Field }) — a group of checkboxes with no name is a list of unrelated\ntoggles as far as a screen reader is concerned.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the vertical stack defaults.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseCheckboxGroup.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-sunken",
+    "--cue-text-ui"
+  ],
+  "summary": "Shared state for a set of {@link Checkbox}es: one `value` array in, one out.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<CheckboxGroup aria-label=\"Attributes\" value={attrs} onValueChange={setAttrs}>\n  <Checkbox value=\"pan\" label=\"Pan\" />\n  <Checkbox value=\"tilt\" label=\"Tilt\" />\n</CheckboxGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/checkbox-group",
+  "mdUrl": "/docs/components/checkbox-group.md",
+  "jsonUrl": "/r/components/checkbox-group.json",
+  "specimens": [
+    {
+      "title": "Checkbox / CheckboxGroup",
+      "group": "forms",
+      "components": [
+        "Checkbox",
+        "CheckboxGroup"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Specimens>\n    <Specimen label=\"checked\">\n      <Checkbox label=\"Art-Net\" defaultChecked />\n    </Specimen>\n    <Specimen label=\"unchecked\">\n      <Checkbox label=\"sACN\" />\n    </Specimen>\n    <Specimen label=\"indeterminate\">\n      <Checkbox label=\"All protocols\" indeterminate />\n    </Specimen>\n    <Specimen label=\"disabled\">\n      <Checkbox label=\"Timecode\" disabled />\n    </Specimen>\n    <Specimen label=\"sm\">\n      <Checkbox label=\"Small\" size=\"sm\" defaultChecked />\n    </Specimen>\n  </Specimens>\n  <CheckboxGroup\n    aria-label=\"Output protocols\"\n    defaultValue={[\"artnet\"]}\n    className=\"flex flex-col gap-(--cue-space-3)\"\n  >\n    <Checkbox name=\"artnet\" label=\"Art-Net\" />\n    <Checkbox name=\"sacn\" label=\"sACN\" />\n    <Checkbox name=\"osc\" label=\"OSC\" />\n  </CheckboxGroup>\n</div>",
+      "note": "Two sizes and a real indeterminate state, wired as a parent of its group.",
+      "interaction": "Space toggles; the group's parent box drives and reflects its children."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/checkbox.json

@@ -0,0 +1,106 @@
+{
+  "name": "Checkbox",
+  "slug": "checkbox",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A square, two- or three-state checkbox.\n\nSized from the density *icon* tokens rather than the control ladder: a\ncheckbox is a glyph, not a control chassis, and at ultra-compact density a\ncontrol-height box would dwarf the row it sits in. Checked fills with the\naccent and inks the tick in `accent-fg`, so it reads on every theme without\nper-theme branching.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline label rendered beside the box and wrapped with it in a `<label>`, so\nthe text is both the accessible name and part of the hit target. Omit it and\npass `aria-label`, or let a {@link Field } name the control instead.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the box defaults.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density icon ladder for the box. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md"
+        ]
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseCheckbox.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-sunken",
+    "--cue-text-ui"
+  ],
+  "summary": "A square, two- or three-state box, sized from the density icon tokens.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Checkbox label=\"Enable notifications\" defaultChecked />\n<Checkbox aria-label=\"Select row\" size=\"sm\" checked={selected} onCheckedChange={setSelected} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/checkbox",
+  "mdUrl": "/docs/components/checkbox.md",
+  "jsonUrl": "/r/components/checkbox.json",
+  "whenToUse": [
+    "Boolean values in a form, and row selection in a table.",
+    "Several related values at once. Wrap them in `CheckboxGroup`, which owns one array."
+  ],
+  "whenNotToUse": [
+    "State that applies immediately. Use `Switch`.",
+    "One value out of several. Use `RadioGroup`."
+  ],
+  "commonMistakes": [
+    "Leaving a `CheckboxGroup` without an accessible name, which turns it into a pile of unrelated toggles for a screen reader.",
+    "Using the indeterminate state as a third value. It means \"some of the children are checked\", nothing else."
+  ],
+  "specimens": [
+    {
+      "title": "Checkbox / CheckboxGroup",
+      "group": "forms",
+      "components": [
+        "Checkbox",
+        "CheckboxGroup"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Specimens>\n    <Specimen label=\"checked\">\n      <Checkbox label=\"Art-Net\" defaultChecked />\n    </Specimen>\n    <Specimen label=\"unchecked\">\n      <Checkbox label=\"sACN\" />\n    </Specimen>\n    <Specimen label=\"indeterminate\">\n      <Checkbox label=\"All protocols\" indeterminate />\n    </Specimen>\n    <Specimen label=\"disabled\">\n      <Checkbox label=\"Timecode\" disabled />\n    </Specimen>\n    <Specimen label=\"sm\">\n      <Checkbox label=\"Small\" size=\"sm\" defaultChecked />\n    </Specimen>\n  </Specimens>\n  <CheckboxGroup\n    aria-label=\"Output protocols\"\n    defaultValue={[\"artnet\"]}\n    className=\"flex flex-col gap-(--cue-space-3)\"\n  >\n    <Checkbox name=\"artnet\" label=\"Art-Net\" />\n    <Checkbox name=\"sacn\" label=\"sACN\" />\n    <Checkbox name=\"osc\" label=\"OSC\" />\n  </CheckboxGroup>\n</div>",
+      "note": "Two sizes and a real indeterminate state, wired as a parent of its group.",
+      "interaction": "Space toggles; the group's parent box drives and reflects its children."
+    }
+  ]
+}

package/manifest/components/checkpoint-history.json

@@ -0,0 +1,91 @@
+{
+  "name": "CheckpointHistory",
+  "slug": "checkpoint-history",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Points you can fall back to, with what each one would give back.",
+  "props": [
+    {
+      "name": "checkpoints",
+      "type": "readonly Checkpoint[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Points in the run you can fall back to, oldest first.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.checkpoints"
+      }
+    },
+    {
+      "name": "currentId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Where the run stands. Everything after it dims, since restoring would discard it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onRestore",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the checkpoint to return to.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"checkpoints\" | \"currentId\" | \"onRestore\"\n> & {\n  /** Points in the run you can fall back to, oldest first. */\n  checkpoints: readonly Checkpoint[];\n  /** Where the run stands. Everything after it dims, since restoring would discard it. */\n  currentId: string;\n  /** Called with the checkpoint to return to. */\n  onRestore?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-label"
+  ],
+  "summary": "Points you can fall back to, with what each one would give back.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { CheckpointHistory } from \"@cueplusplus/ui/elements\";\n\n<CheckpointHistory checkpoints={checkpoints} currentId=\"3\" onRestore={restore} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/checkpoint-history",
+  "mdUrl": "/docs/components/checkpoint-history.md",
+  "jsonUrl": "/r/components/checkpoint-history.json",
+  "specimens": [
+    {
+      "title": "CheckpointHistory",
+      "group": "elements-agents",
+      "components": [
+        "CheckpointHistory"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"mid-run\" wide>\n    <CheckpointHistory\n      checkpoints={CHECKPOINTS}\n      currentId={checkpoint}\n      onRestore={setCheckpoint}\n    />\n  </Specimen>\n  <Specimen label=\"at the head, nothing to discard\" wide>\n    <CheckpointHistory checkpoints={CHECKPOINTS} currentId=\"c-plot\" />\n  </Specimen>\n</Specimens>",
+      "note": "Points the run can be put back to, oldest first, each with what a fallback would cost in files. Everything after the current point dims, because restoring would discard it — the list is the undo stack drawn as a place rather than a count.",
+      "interaction": "each row carries a labelled restore button (`Restore to …`), so the control is named even though it draws as a glyph."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chip.json

@@ -0,0 +1,174 @@
+{
+  "name": "Chip",
+  "slug": "chip",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A compact status/label pill: mono, uppercase, wide-tracked, one line tall.\n\n`tone` uses the shared status vocabulary (`ok | busy | warn | danger | info`)\nplus `neutral` and `accent`, so a chip, a `StatusDot` and a `Meter` always\nagree on what \"warn\" looks like.\n\n`variant` sets how loudly it says it. `tinted` is the chip proper — a tone\ntint behind tone ink. `outline` drops the fill and keeps the voice, for a\nchip on an already-busy ground. `tag` drops both: a hairline rim, micro type\nand closed tracking, for the facts that sit *beside* a row's name — a kind, a\nlifecycle, a scope — where a row full of tinted chips would read as a row of\nbuttons. All three keep `h-chip`, so a mixed row still has one baseline.",
+  "props": [
+    {
+      "name": "interactive",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render as a `<button>` with hover feedback instead of a static `<span>`.\nUse for filter pills and other clickable tags; leave off for pure labels.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Disable the interactive form. Ignored when `interactive` is not set.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Chip content — normally one or two words, or a short count.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "neutral",
+      "description": "",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "neutral",
+          "accent",
+          "ok",
+          "busy",
+          "warn",
+          "danger",
+          "info"
+        ]
+      }
+    },
+    {
+      "name": "variant",
+      "type": "\"outline\" | \"tinted\" | \"tag\"",
+      "required": false,
+      "defaultValue": "tinted",
+      "description": "",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "tinted",
+          "outline",
+          "tag"
+        ]
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.HTMLAttributes<HTMLElement>",
+    "VariantProps<typeof chipVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "tone": [
+      "neutral",
+      "accent",
+      "ok",
+      "busy",
+      "warn",
+      "danger",
+      "info"
+    ],
+    "variant": [
+      "tinted",
+      "outline",
+      "tag"
+    ],
+    "interactive": [
+      "true",
+      "false"
+    ]
+  },
+  "defaultVariants": {
+    "tone": "neutral",
+    "variant": "tinted",
+    "interactive": "false"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-busy",
+    "--cue-chip-h",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-hair-strong",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-warn"
+  ],
+  "summary": "The status pill, at three volumes: tinted fill, bare outline, or a hairline tag.",
+  "examples": [
+    {
+      "title": "A row's tags",
+      "code": "<Chip variant=\"tag\">mcp</Chip>\n<Chip tone=\"accent\" variant=\"tag\">beta</Chip>\n<Chip tone=\"danger\" variant=\"tag\">needs auth</Chip>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Chip tone=\"ok\">online</Chip>\n<Chip tone=\"accent\" variant=\"outline\" interactive onClick={toggle}>dimmer</Chip>\n<Chip variant=\"tag\">mcp</Chip>\n<Chip tone=\"danger\" variant=\"tag\">needs auth</Chip>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/chip",
+  "mdUrl": "/docs/components/chip.md",
+  "jsonUrl": "/r/components/chip.json",
+  "whenToUse": [
+    "A state, a tag or a short count sitting beside the thing it describes.",
+    "Filter pills, with `interactive` for the button semantics.",
+    "`variant=\"tag\"` for the flat facts beside a row's name — a kind, a lifecycle, a scope, a permission. A list of them stays a list."
+  ],
+  "whenNotToUse": [
+    "A single live state where a dot carries it. Use `StatusDot`.",
+    "A message the user has to read and act on. Use `Toast` or `FieldError`.",
+    "Anything that runs something. Use `Button`.",
+    "Tokens the user typed and can remove. That is `TagsInput`, which owns the editing and the keyboard."
+  ],
+  "commonMistakes": [
+    "Writing a sentence in a chip. One or two words, or a count.",
+    "Picking a tone for decoration. Tones are the status vocabulary shared with `StatusDot`, `Meter` and `Toast`.",
+    "Reaching for `tag` because the chip looked too big. It is the quiet reading, not the small one — the height is still `h-chip`, so a mixed row keeps one baseline.",
+    "Putting three tinted chips on every row of a list. Repeat a fill thirty times and the list reads as thirty buttons. That is what `tag` is for."
+  ],
+  "specimens": [
+    {
+      "title": "Chip",
+      "group": "primitives",
+      "components": [
+        "Chip"
+      ],
+      "code": "<Specimens>\n  {CHIP_TONES.map((tone) => (\n    <Specimen key={tone} label={tone}>\n      <Chip tone={tone}>{tone}</Chip>\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  {CHIP_TONES.map((tone) => (\n    <Specimen key={tone} label={`${tone} outline`}>\n      <Chip tone={tone} variant=\"outline\">\n        {tone}\n      </Chip>\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  {CHIP_TONES.map((tone) => (\n    <Specimen key={tone} label={`${tone} tag`}>\n      <Chip tone={tone} variant=\"tag\">\n        {tone}\n      </Chip>\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"a row's tags\">\n    <span className=\"inline-flex items-center gap-(--cue-space-2)\">\n      <Chip variant=\"tag\">mcp</Chip>\n      <Chip tone=\"accent\" variant=\"tag\">\n        beta\n      </Chip>\n      <Chip tone=\"danger\" variant=\"tag\">\n        needs auth\n      </Chip>\n    </span>\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"interactive\">\n    <Chip tone=\"accent\" interactive>\n      Universe 1\n    </Chip>\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Chip tone=\"accent\" interactive disabled>\n      Universe 9\n    </Chip>\n  </Specimen>\n  <Specimen label=\"interactive tag\">\n    <Chip tone=\"accent\" variant=\"tag\" interactive>\n      beta only\n    </Chip>\n  </Specimen>\n</Specimens>",
+      "note": "The tinted-chip recipe: a tone tint at low alpha, tone ink, tone border. Seven tones, three variants — `tag` drops the fill and the type size for the facts that sit beside a row's name.",
+      "interaction": "static by default; pass `interactive` and it takes a hover ground and a focus ring. An interactive tag brightens its rim instead."
+    }
+  ]
+}

package/manifest/components/clamp.json

@@ -0,0 +1,125 @@
+{
+  "name": "Clamp",
+  "slug": "clamp",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Long content, cut to a height, dissolving at the cut, with a way back.\n\nThe truncation trio as one element. Everything a transcript truncates —\ncommand output, a pasted file, a reasoning trace, a quoted message — wants\nexactly these three things, and a family that leaves them to each component\ngets five slightly different cuts and one of them hard-coded to a colour that\nbreaks in light mode.\n\nThe fade is a **mask**, not an overlay: it fades the content rather than\npainting a gradient of the surface colour over it, so it needs no idea of\nwhat is behind it and cannot drift when the theme changes. The height and the\ndepth are published as custom properties on the root, so a console can retune\na clamp from CSS — and because the mask is expressed in terms of them, a\nheight overridden in a stylesheet moves the fade with it.\n\nThe reveal is the part this element does not copy exactly. The reference\nshows its `Show more` chip on hover only, which is unreachable for anyone\nwho is not holding a mouse; here the control is always in the DOM and always\nfocusable, and hover and focus only decide how loudly it is drawn. Once the\ncontent is open, `Show less` is drawn at full strength — a long expansion you\ncannot close without hunting for the control is a real defect.\n\nOpen state is a prop, like everything else in this family: a scripted replay\nof this component is a caller changing `open`.",
+  "props": [
+    {
+      "name": "height",
+      "type": "string | number",
+      "required": false,
+      "defaultValue": "250",
+      "description": "How tall the content may be before it is cut, as a number of pixels or any\nCSS length. Defaults to `250` — the reference's own default, with `60` the\nvalue it uses for a quoted user message.\n\nPublished as `--cue-elements-clamp-height` on the root, so a console can\nretune one clamp from a stylesheet without a prop.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "fade",
+      "type": "number",
+      "required": false,
+      "defaultValue": "50",
+      "description": "How deep the dissolve at the cut is, in pixels. Defaults to `50`, the\nreference's most-used depth.\n\nFixed pixels rather than a fraction, deliberately: a percentage fade is a\ndifferent effect on a short row than on a long one. Published as\n`--cue-elements-clamp-fade`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the content is showing in full.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the reveal is used. Omit it and the clamp is a hard cut with a\nfade and no promise of more — which is the reference's own tool-result row,\nwhere the full text opens somewhere else entirely.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "overflows",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Whether the content is taller than `height`, when the caller already knows.\nLeft out, the clamp measures itself and re-measures as the content and the\nbox change.\n\nThe measurement is the right default and the override is for the cases it\ncannot serve: a virtualised row that knows its own text, a replay frame\nthat must paint the same way on every mount, a server render.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "labels",
+      "type": "Partial<ClampLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The two words on the reveal. Defaults to {@link CLAMP_LABELS} — `Show more`\nand `Show less`, which is the reference's copy verbatim.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The content being clamped.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onToggle\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-elements-clamp-fade",
+    "--cue-elements-clamp-height",
+    "--cue-elements-clamp-mask",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-radius-control",
+    "--cue-text-ui"
+  ],
+  "summary": "Long content, cut to a height, dissolving at the cut, with a way back.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Clamp } from \"@cueplusplus/ui/elements\";\n\n<Clamp open={open} onOpenChange={setOpen}>\n  <pre>{output}</pre>\n</Clamp>\n// The reference's tool-result row: 60px of output, a 10px dissolve, and no\n// reveal at all — the full text opens in an editor tab instead.\n<Clamp height={60} fade={10} open={false} overflows onClick={openInEditor}>\n  {result}\n</Clamp>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/clamp",
+  "mdUrl": "/docs/components/clamp.md",
+  "jsonUrl": "/r/components/clamp.json",
+  "specimens": [
+    {
+      "title": "Clamp",
+      "group": "elements",
+      "components": [
+        "Clamp"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"clamped, with a way back\" wide>\n    <div className=\"w-full max-w-md\">\n      <Clamp\n        height={120}\n        fade={40}\n        open={shownInFull}\n        onOpenChange={setShownInFull}\n      >\n        <pre className=\"font-mono text-(length:--cue-text-ui) whitespace-pre-wrap text-fg-muted\">\n          {PATCH_REPORT}\n        </pre>\n      </Clamp>\n    </div>\n  </Specimen>\n  <Specimen label=\"a hard cut, and the full text opens elsewhere\" wide>\n    <div className=\"w-full max-w-md\">\n      <Clamp height={60} fade={10} open={false} overflows>\n        <pre className=\"font-mono text-(length:--cue-text-ui) whitespace-pre-wrap text-fg-muted\">\n          {PATCH_REPORT}\n        </pre>\n      </Clamp>\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The truncation trio as one element: a height, a dissolve of a fixed number of pixels at the cut, and a way back. The fixed depth is the part worth copying — ten pixels of dissolve is the same cut over a two-line row and a forty-line one, which is why the reference's five different truncations read as one idea. The fade is a mask rather than a gradient of the surface colour, which is the bug the reference shipped: its diff variant hard-codes a dark grey and smears on a light theme. A mask fades the content itself, so it has no colour to get wrong in any theme, either mode, or inside the island.",
+      "interaction": "the reveal is always present and always focusable; hover and focus decide only how loudly it is drawn, and Show less is never dimmed at all. That is the one place this does not copy the reference, whose Show more chip appears on hover only and is unreachable for anyone not holding a pointer. The height and the fade are published as custom properties on the root, and the mask is written in terms of them, so a height overridden in a stylesheet moves the dissolve with it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/cli-tool-icon.json

@@ -0,0 +1,46 @@
+{
+  "name": "CliToolIcon",
+  "slug": "cli-tool-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A CLI tool in the registry: a thing that runs in a terminal.\n\nA window with a prompt in it, rather than a bare chevron. A chevron on its\nown is a disclosure everywhere else in this library, and a navigation row\nthat appeared to expand and then navigated instead is a worse failure than a\nslightly busier glyph at 10px.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "A CLI tool in the registry: a thing that runs in a terminal.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/cli-tool-icon",
+  "mdUrl": "/docs/components/cli-tool-icon.md",
+  "jsonUrl": "/r/components/cli-tool-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}