@cueplusplus/ui 0.20.0 → 0.21.0

package/manifest/components/composer-input.json

@@ -7,7 +7,7 @@
     "lucide-react"
   ],
   "clientOnly": true,
-  "description": "The text field. Enter submits, guarded against IME composition so accepting a\ncandidate does not send the message.",
+  "description": "The text field: a textarea that grows with what it holds, to a cap. Enter sends and\nShift+Enter breaks the line, both guarded against IME composition so accepting a\ncandidate does not send the message.",
   "props": [
     {
       "name": "onSubmit",
@@ -19,10 +19,24 @@
         "kind": "callback",
         "fixture": "callback.log"
       }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "`md` (the default) or `sm`: the smaller rung, a 36px floor with body type, for a\ncompact console.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md"
+        ]
+      }
     }
   ],
   "typeReferences": [
-    "Omit<ComponentProps<\"input\">, \"onSubmit\"> & {\n  /**\n   * Called on Enter, guarded against IME composition so accepting a candidate does not\n   * send.\n   */\n  onSubmit?: () => void;\n}"
+    "Omit<ComponentProps<\"textarea\">, \"onSubmit\"> & {\n  /**\n   * Called on Enter, guarded against IME composition so accepting a candidate does not\n   * send.\n   */\n  onSubmit?: () => void;\n  /**\n   * `md` (the default) or `sm`: the smaller rung, a 36px floor with body type, for a\n   * compact console.\n   */\n  size?: \"sm\" | \"md\";\n}"
   ],
   "subcomponents": [],
   "parts": [],

package/manifest/components/elicitation-form.json

@@ -76,10 +76,25 @@
         "kind": "callback",
         "fixture": "callback.log"
       }
+    },
+    {
+      "name": "delivery",
+      "type": "\"failed\" | \"sending\" | \"sent\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where the answer has got to: `sending`, `sent` or `failed`. While it is on its way\nand once it has arrived, the form offers nothing to press. `failed` offers Decline\nand Send again. An outcome `state` wins over it.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "failed",
+          "sending",
+          "sent"
+        ]
+      }
     }
   ],
   "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}"
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"server\"\n  | \"message\"\n  | \"fields\"\n  | \"state\"\n  | \"onAccept\"\n  | \"onDecline\"\n  | \"delivery\"\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  /**\n   * Where the answer has got to: `sending`, `sent` or `failed`. While it is on its way\n   * and once it has arrived, the form offers nothing to press. `failed` offers Decline\n   * and Send again. An outcome `state` wins over it.\n   */\n  delivery?: RequestDelivery;\n}"
   ],
   "subcomponents": [],
   "parts": [],

package/manifest/components/event-feed.json

@@ -0,0 +1,171 @@
+{
+  "name": "EventFeed",
+  "slug": "event-feed",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A filterable activity feed: timestamped, typed records with a one-line\npreview, and a selection the detail pane follows (#103).\n\nThe chips are built from the kinds present, in the order each first\nappears, each with its count, so a feed never offers a filter that keeps\nnothing. The rows are a listbox: j and k, or the arrows, move the selection\nthrough the rows the filter keeps, and Home and End jump to the ends. The\nselection follows the keyboard, so the detail beside it follows too.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The feed's accessible name: `Run events`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "events",
+      "type": "readonly FeedEvent[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The records, oldest first or newest first: the feed keeps the order given.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.feed"
+      }
+    },
+    {
+      "name": "filter",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The kind the feed keeps, or `all`, when the caller holds it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "defaultFilter",
+      "type": "string",
+      "required": false,
+      "defaultValue": "all",
+      "description": "The kind to start on when nothing controls it. Defaults to `all`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onFilterChange",
+      "type": "((filter: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the kind, or `all`, when a chip is pressed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "selectedId",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": "null",
+      "description": "The selected event's `id`, or `null` for none.",
+      "control": {
+        "kind": "string",
+        "nullable": true
+      }
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with an event's `id` when a row is clicked or the keyboard moves to it.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "formatTime",
+      "type": "((timestamp: string | number | Date) => string)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Formats the time column. Defaults to a time of day for a `Date` or a number.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "labels",
+      "type": "Partial<EventFeedLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace any of the feed's own copy.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-focus-ring",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-stream",
+    "--cue-style-focus-width",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "A filterable activity feed: typed, timestamped records with a one-line preview and a selection.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "const [selected, setSelected] = React.useState<string | null>(null);\n\n<EventFeed\n  label=\"Run events\"\n  events={events}\n  selectedId={selected}\n  onSelect={setSelected}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/event-feed",
+  "mdUrl": "/docs/components/event-feed.md",
+  "jsonUrl": "/r/components/event-feed.json",
+  "whenToUse": [
+    "Inspecting a run beside its transcript: tool calls, permission asks, compactions, errors.",
+    "Any stream of typed records outside agents: MCP logs, device heartbeats, billing events, CI steps."
+  ],
+  "whenNotToUse": [
+    "The conversation itself. Tool calls in the transcript are `ToolGroup`'s; this is the list beside it.",
+    "Raw log lines with ANSI colour. `LogViewer`, from `@cueplusplus/ui/instruments/log-viewer`, reads those."
+  ],
+  "commonMistakes": [
+    "Drawing the detail inside the feed. The feed reports a selection; put the detail in `SplitPane`'s `detail` slot.",
+    "Kinds that are sentences. Each kind becomes a chip, so keep them to a word: `tool`, `permission`, `error`.",
+    "Formatting time strings and also passing `formatTime`. A string timestamp is drawn as given; pass a `Date` or a number to have it formatted."
+  ],
+  "specimens": [
+    {
+      "title": "EventFeed",
+      "group": "elements",
+      "components": [
+        "EventFeed"
+      ],
+      "code": "<div className=\"w-full max-w-md\">\n  <EventFeed\n    label=\"Patch run events\"\n    events={RUN_EVENTS}\n    selectedId={runEvent}\n    onSelect={setRunEvent}\n  />\n</div>",
+      "note": "The inspector beside a transcript: typed records, each a time, a toned dot, a kind, a title and a one-line preview. The chips are built from the kinds present, each with its count, so no chip keeps nothing. The detail is the host's: in a console it goes in SplitPane's detail slot.",
+      "interaction": "press a chip to keep one kind. Tab into the list, then j and k, or the arrows, move the selection through the rows the filter keeps, and Home and End jump to the ends."
+    }
+  ]
+}

package/manifest/components/event-row.json

@@ -0,0 +1,116 @@
+{
+  "name": "EventRow",
+  "slug": "event-row",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "One event, as a feed row: time, a toned dot, kind, title, and a one-line\npreview under the title. Exported for a list of the caller's own.\n\nInside an {@link EventFeed} it is an `option` of the feed's listbox. Drawn\nalone it claims no role, and in a listbox of the caller's it takes\n`role=\"option\"` from its props; either way `aria-selected` follows `selected`\nonly when the row is an option.",
+  "props": [
+    {
+      "name": "event",
+      "type": "FeedEvent",
+      "required": true,
+      "defaultValue": null,
+      "description": "The record this row draws.",
+      "control": {
+        "kind": "opaque",
+        "fixture": "agents.feed-event"
+      }
+    },
+    {
+      "name": "selected",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Whether this row is the selected one.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the event's `id` when the row is clicked.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "formatTime",
+      "type": "((timestamp: string | number | Date) => string)",
+      "required": false,
+      "defaultValue": "formatTimestamp",
+      "description": "Formats the time column. Defaults to a time of day for a `Date` or a number.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-focus-ring",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-stream",
+    "--cue-style-focus-width",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "One event as an activity feed draws it, for a list of your own.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<div role=\"listbox\" aria-label=\"Recent\">\n  <EventRow role=\"option\" event={event} selected={event.id === id} onSelect={setId} />\n</div>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/event-row",
+  "mdUrl": "/docs/components/event-row.md",
+  "jsonUrl": "/r/components/event-row.json",
+  "whenToUse": [
+    "A custom list of typed records that should look like `EventFeed`'s rows: grouped by run, virtualised, or interleaved with headings."
+  ],
+  "whenNotToUse": [
+    "A plain filterable feed. `EventFeed` draws these rows with chips and a keyboard already."
+  ],
+  "commonMistakes": [
+    "Rows in a listbox of your own without `role=\"option\"`. Outside an `EventFeed` a row claims no role, so pass it, and the row then says whether it is selected.",
+    "Expecting the row to move the selection from the keyboard. `EventFeed` owns that; a list of your own must too."
+  ],
+  "specimens": [
+    {
+      "title": "EventRow",
+      "group": "elements",
+      "components": [
+        "EventRow"
+      ],
+      "code": "<div role=\"listbox\" aria-label=\"Two run events\" className=\"flex w-full max-w-md flex-col\">\n  <EventRow role=\"option\" event={RUN_EVENTS[0]} onSelect={setRunEvent} />\n  <EventRow role=\"option\" event={RUN_EVENTS[3]} selected onSelect={setRunEvent} />\n</div>",
+      "note": "One event as the feed draws it, for a list of your own: the time, the toned dot, the kind, the title and its preview. The second row is the selected one.",
+      "interaction": "click a row: it reports its id through onSelect. Inside an EventFeed the feed owns the keyboard."
+    }
+  ]
+}

package/manifest/components/generative-ui.json

@@ -5,7 +5,7 @@
   "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.",
+  "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## 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,\nCursor's under `skin=\"cursor\"`, and assistant-ui's under `skin=\"aui\"`, which\nis 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",
@@ -62,13 +62,14 @@
     },
     {
       "name": "skin",
-      "type": "\"cue\" | \"aui\"",
+      "type": "\"cursor\" | \"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.",
+      "description": "Which value-set paints this tree: `cue` (the default), `aui`, which\ninstalls assistant-ui's own surface language, or `cursor`, Cursor's\nagent-pane values. Leave it off inside an {@link AgentSurface }, which has\nstamped the subtree already.",
       "control": {
         "kind": "enum",
         "members": [
+          "cursor",
           "cue",
           "aui"
         ]

package/manifest/components/pane-seam.json

@@ -0,0 +1,171 @@
+{
+  "name": "PaneSeam",
+  "slug": "pane-seam",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "One accessible seam that resizes one pane, with no dependency (cue-ui-55).\n\n`Resizable` divides a frame between panel groups on `react-resizable-panels`,\nan optional peer. Most consoles need one thing less: a side pane whose edge a\nreader can drag, and move from the keyboard. This is that edge, and nothing\nelse. It owns a number, not a layout: apply `value` to the pane's width (or\nheight) and the seam supplies the rest.\n\nThe rest is the part a hand-written separator forgets. It is a focusable\n`role=\"separator\"` that says its size and its bounds (`aria-valuenow`,\n`-valuemin`, `-valuemax`), so the width is spoken as well as draggable. The\narrows move it by `step`, Shift by `largeStep`, and Home and End jump to the\nbounds. Every value is clamped, so the pane can never squeeze its neighbour\nout of use.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The name a screen reader lists the seam by: `Resize the inspector`. Required,\nbecause a separator nobody can name is one a keyboard user cannot find.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "value",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The pane's size in pixels, when the caller holds it.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "defaultValue",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The size to start from when nothing controls it. Defaults to `min`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with every new size, already clamped to `min` and `max`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "min",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The smallest the pane may become, in pixels.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The largest the pane may become, in pixels.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "step",
+      "type": "number",
+      "required": false,
+      "defaultValue": "16",
+      "description": "How far one arrow press moves the seam, in pixels. Defaults to 16.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "largeStep",
+      "type": "number",
+      "required": false,
+      "defaultValue": "64",
+      "description": "How far Shift with an arrow moves it, in pixels. Defaults to 64.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\"",
+      "required": false,
+      "defaultValue": "vertical",
+      "description": "`vertical`, the default, divides side-by-side panes and resizes a width;\n`horizontal` divides stacked panes and resizes a height.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "horizontal",
+          "vertical"
+        ]
+      }
+    },
+    {
+      "name": "edge",
+      "type": "\"end\" | \"start\"",
+      "required": false,
+      "defaultValue": "start",
+      "description": "Where the pane sits: `start`, the default, before the seam (left, or top),\nor `end`, after it. Moving the seam away from the pane grows it. A vertical\nseam reads the document's direction, so `start` is the right-hand pane\nunder `dir=\"rtl\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "end",
+          "start"
+        ]
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"defaultValue\" | \"onChange\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-focus",
+    "--cue-focus-ring",
+    "--cue-style-focus-width"
+  ],
+  "summary": "One accessible seam that resizes one pane, with no dependency.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "const [width, setWidth] = React.useState(320);\nconst inspector = { width };\n\n<div className=\"flex\">\n  <main className=\"min-w-0 flex-1\">…</main>\n  <PaneSeam\n    label=\"Resize the inspector\"\n    edge=\"end\"\n    min={240}\n    max={640}\n    value={width}\n    onValueChange={setWidth}\n  />\n  <aside style={inspector}>…</aside>\n</div>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/pane-seam",
+  "mdUrl": "/docs/components/pane-seam.md",
+  "jsonUrl": "/r/components/pane-seam.json",
+  "whenToUse": [
+    "A side pane whose edge a reader can drag and move from the keyboard: an inspector, a file tree, a thread beside a canvas.",
+    "Keeping the layout yours. The seam reports a size and you apply it, so it fits any flex or grid frame."
+  ],
+  "whenNotToUse": [
+    "Several panels that divide one frame by percentage. Use `Resizable`, from `@cueplusplus/ui/layout/resizable`.",
+    "A list beside a detail that should stack when narrow. `SplitPane` builds that on this seam."
+  ],
+  "commonMistakes": [
+    "Rendering the seam and not applying its `value`. It moves nothing by itself; put the value on the pane's width or height.",
+    "Setting `edge` for the wrong side. `edge=\"end\"` is a pane after the seam, which grows as the seam moves toward the start.",
+    "A `label` that names the seam rather than the pane. A screen reader lists it by name, so say what it resizes: `Resize the inspector`."
+  ],
+  "specimens": [
+    {
+      "title": "PaneSeam",
+      "group": "layout",
+      "components": [
+        "PaneSeam"
+      ],
+      "code": "<div className=\"flex h-[9rem] w-full max-w-[36rem] overflow-hidden rounded-(--radius-surface) border border-border\">\n  <div className=\"flex min-w-0 flex-1 items-center justify-center font-mono text-(length:--cue-text-ui) text-fg-muted\">\n    Patch\n  </div>\n  <PaneSeam\n    label=\"Resize the inspector\"\n    edge=\"end\"\n    min={160}\n    max={360}\n    value={inspector}\n    onValueChange={setInspector}\n  />\n  <div\n    className=\"flex shrink-0 items-center justify-center font-mono text-(length:--cue-text-ui) text-fg-muted\"\n    style={{ width: inspector }}\n  >\n    Inspector · {inspector}px\n  </div>\n</div>",
+      "note": "One seam that resizes one pane, with no dependency. It owns a number, not a layout: the inspector below takes the seam's value as its width, and the seam clamps it so the patch list always keeps its room.",
+      "interaction": "drag the seam, or tab to it: the arrows move it 16px, Shift+arrow 64px, and Home and End jump to the inspector's narrowest and widest. A screen reader hears the width and its bounds."
+    }
+  ]
+}