@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/theme-configurator.json

@@ -0,0 +1,124 @@
+{
+  "name": "ThemeConfigurator",
+  "slug": "theme-configurator",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "The floating theme configurator: the panel that edits the design system it is\ndrawn with.\n\nIt is a **component**, not a devtool bolted onto the kitchensink — mount it in\nany app behind a flag and a designer can retune that app's theme in place. The\nwhole thing rests on one rule, and the rule is what keeps it from being a toy:\n*everything it does is a `--cue-*` declaration in one stylesheet.* No inline\nstyles on the root, no parallel token vocabulary, no runtime theme engine. The\nCSS it exports is byte for byte the CSS the page is wearing, which is the only\nreason the export dialog can promise a round trip at all.\n\nWhat it owns:\n\n- **Preset, mode and density** are the provider's, driven through `useTheme()`\n  so a switch restamps `<html>`, every portal, and the persisted preference.\n- **Colour, type and geometry overrides** go into\n  `<style id=\"cue-configurator-overrides\">`, scoped so they win where they\n  have to and lose where they should — the cascade reasoning is in\n  `_overrides.ts`, and it is the interesting part of this group.\n- **Text scale and root zoom**, the two relief valves the density ladder is\n  paired with.\n- **Its own placement**, furled state and every override, in `localStorage`\n  under one key.\n\nRenders in place as a `position: fixed` region, so mount it inside the\nprovider — it needs the theme context — but outside any transformed ancestor,\nwhich would turn `fixed` into `absolute` and take the panel with the page.",
+  "props": [
+    {
+      "name": "position",
+      "type": "\"floating\" | \"docked-right\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Placement, controlled. Pair with `onPositionChange`."
+    },
+    {
+      "name": "defaultPosition",
+      "type": "\"floating\" | \"docked-right\"",
+      "required": false,
+      "defaultValue": "floating",
+      "description": "Initial placement. A stored one wins. Defaults to `\"floating\"`."
+    },
+    {
+      "name": "onPositionChange",
+      "type": "((position: ConfiguratorPosition) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user docks or floats the panel."
+    },
+    {
+      "name": "defaultCollapsed",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Start furled to the title bar. A stored value wins. Defaults to `false`."
+    },
+    {
+      "name": "storageKey",
+      "type": "string",
+      "required": false,
+      "defaultValue": "cue-configurator",
+      "description": "`localStorage` key holding the overrides, the placement and the zoom.\nDefaults to `\"cue-configurator\"`."
+    },
+    {
+      "name": "onChange",
+      "type": "((tokens: Record<string, string>) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the full resolved `--cue-*` map — never a diff — whenever the\noverrides, the theme or the mode change, and once on mount."
+    },
+    {
+      "name": "zoomShortcuts",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Bind ⌘/Ctrl with `+`, `-` and `0` to the zoom valve. Defaults to `true`."
+    },
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Theme",
+      "description": "Panel heading. Defaults to `\"Theme\"`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the panel."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-lg",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-font-pairing-mono",
+    "--cue-font-sans",
+    "--cue-font-scale",
+    "--cue-font-theme-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-scale",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The floating theme configurator: the panel that edits the design system it is drawn with.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ThemeProvider>\n  <App />\n  {devMode ? <ThemeConfigurator /> : null}\n</ThemeProvider>\n<ThemeConfigurator position=\"docked-right\" onChange={(tokens) => report(tokens)} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/theme-configurator",
+  "mdUrl": "/docs/components/theme-configurator.md",
+  "jsonUrl": "/r/components/theme-configurator.json",
+  "todo": true
+}

package/manifest/components/theme-provider.json

@@ -0,0 +1,134 @@
+{
+  "name": "ThemeProvider",
+  "slug": "theme-provider",
+  "group": "system",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`\nso the token layer resolves, puts `data-font` on `<html>`, publishes\n`--cue-font-scale`, and owns the persisted user preference.\n\nRendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`\n(or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are\n*initial* values — the provider holds the state so `setTheme` and friends can\ndrive it — but a changed prop is adopted after mount, so a controlling parent\nstill works.\n\nThe font pairing is the one axis that never lands on this element: it has no\nisland form, `<html>` is its only home, and restating it here would shadow the\npre-paint stamp for the whole page on the first frame. See the `stamp` object\nbelow.\n\nPersistence and the pre-paint contract: setters write\n`{ theme, density, font, mode }` to `localStorage[storageKey]`, which is exactly what\n{@link prepaintScript } reads to stamp `<html>` before the first paint. The\noutermost provider keeps `<html>` in sync while the app runs (and restores the\nprevious stamp on unmount) so the page ground, UA scrollbars and form controls\nfollow the theme; nested providers never touch `<html>`, and never own the\nfont pairing — `useTheme().font` and `setFont` inside one are the root's.",
+  "props": [
+    {
+      "name": "theme",
+      "type": "\"terminal\" | \"cue\" | \"signal\" | \"venu\" | \"hivehub\" | \"dusk\" | \"luma\" | \"snuffle\" | \"requestport\" | \"quotamate\"",
+      "required": false,
+      "defaultValue": "cue",
+      "description": "Initial theme preset. Defaults to `\"cue\"`. Changing it after mount adopts the new value."
+    },
+    {
+      "name": "density",
+      "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
+      "required": false,
+      "defaultValue": "compact",
+      "description": "Initial density level. Defaults to `\"compact\"`."
+    },
+    {
+      "name": "mode",
+      "type": "\"system\" | \"dark\" | \"light\"",
+      "required": false,
+      "defaultValue": "dark",
+      "description": "Initial mode. Defaults to `\"dark\"`; `\"system\"` tracks `prefers-color-scheme`."
+    },
+    {
+      "name": "font",
+      "type": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\"",
+      "required": false,
+      "defaultValue": "DEFAULT_FONT",
+      "description": "Initial font pairing. Defaults to `\"system\"` — the platform's own faces,\nnothing downloaded, and the theme keeps whatever monospace it authored.\n\nA pairing that needs delivering is a set of *names*: this library ships no\nfont files, and a pairing nobody delivers falls through its stack to the\nplatform rather than failing. See `FONT_PAIRINGS[font].faces` for the\ncustom properties an app assigns to make one resolve.\n\n**Root-level only.** There is no font island: a nested provider forwards\nthis axis to the root, ignores this prop, and its `setFont` drives the root.\nA page that changed face halfway down is a page with a bug, and a specimen\nthat genuinely wants one — a picker row, a docs page showing all eight —\nneeds nothing from this library but `data-font` on a `<div>`."
+    },
+    {
+      "name": "fontScale",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`."
+    },
+    {
+      "name": "fontFamilies",
+      "type": "FontFamilies",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional app-owned font stacks, published as inline CUE font custom properties."
+    },
+    {
+      "name": "storageKey",
+      "type": "string",
+      "required": false,
+      "defaultValue": "cue-ui",
+      "description": "localStorage key holding `{ theme, density, font, mode }`. Defaults to `\"cue-ui\"`.\nOnly the outermost provider reads or writes it — a nested provider is an\nisland whose explicit props are the point, not a second preference store."
+    },
+    {
+      "name": "persistPreferences",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Restore and write root preferences in localStorage. Defaults to `true`."
+    },
+    {
+      "name": "asChild",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Stamp the single child element instead of rendering a wrapper `<div>`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the provider root."
+    },
+    {
+      "name": "style",
+      "type": "CSSProperties",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline styles for the provider root, merged after the token style."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The application subtree."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-font-mono",
+    "--cue-font-sans",
+    "--cue-font-scale"
+  ],
+  "summary": "The root that stamps theme, density and mode, and publishes the setters.",
+  "examples": [
+    {
+      "title": "The document root",
+      "code": "<html lang=\"en\" suppressHydrationWarning>\n  <head>\n    <script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />\n  </head>\n  <body>\n    <ThemeProvider theme=\"terminal\" density=\"normal\">\n      {children}\n    </ThemeProvider>\n  </body>\n</html>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<ThemeProvider theme=\"terminal\" density=\"ultra-compact\" font=\"plex\" mode=\"system\">\n  <App />\n</ThemeProvider>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/theme-provider",
+  "mdUrl": "/docs/components/theme-provider.md",
+  "jsonUrl": "/r/components/theme-provider.json",
+  "whenToUse": [
+    "Once at the root of an app, around everything that renders a component.",
+    "Around a subtree that has to render in a fixed preset, such as a theme preview pane."
+  ],
+  "whenNotToUse": [
+    "Changing geometry for one region. Use `Density`, which stamps the density attribute and leaves colour alone.",
+    "Holding app state. It owns theme, density and mode, and nothing else."
+  ],
+  "commonMistakes": [
+    "Leaving `prepaintScript()` out of the document head, which paints the default theme for one frame and then flips.",
+    "Mounting two providers on the same `storageKey`, which makes them fight over the stored preference."
+  ]
+}

package/manifest/components/thinking-indicator.json

@@ -0,0 +1,63 @@
+{
+  "name": "ThinkingIndicator",
+  "slug": "thinking-indicator",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A live status line that names what the agent is doing right now, with elapsed time.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the agent is doing right now. Swapping it replays the entrance animation."
+    },
+    {
+      "name": "elapsed",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Elapsed time rendered in mono next to the label. Omit to hide the timer."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"label\" | \"elapsed\"> & {\n  /** What the agent is doing right now. Swapping it replays the entrance animation. */\n  label: string;\n  /** Elapsed time rendered in mono next to the label. Omit to hide the timer. */\n  elapsed?: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-stream",
+    "--cue-text-body"
+  ],
+  "summary": "A live status line that names what the agent is doing right now, with elapsed time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ThinkingIndicator } from \"@cueplusplus/ui/elements\";\n\n<ThinkingIndicator label=\"Reading thread.tsx\" elapsed=\"12s\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/thinking-indicator",
+  "mdUrl": "/docs/components/thinking-indicator.md",
+  "jsonUrl": "/r/components/thinking-indicator.json",
+  "specimens": [
+    {
+      "title": "ThinkingIndicator",
+      "group": "elements-thread",
+      "components": [
+        "ThinkingIndicator"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"reading\" wide>\n    <ThinkingIndicator label=\"Reading front-truss.gdtf\" elapsed=\"0:04\" />\n  </Specimen>\n  <Specimen label=\"patching, no clock\" wide>\n    <ThinkingIndicator label=\"Patching universe 3\" />\n  </Specimen>\n</Specimens>",
+      "note": "One line that says what is happening right now, with the elapsed clock beside it. The label is keyed, so replacing it re-runs the entrance and the change reads as a change rather than as a re-render.",
+      "interaction": "none. It is a status line, not a control — the dot pulses and the label sweeps, and both stop for a reduced-motion reader."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/thread-list.json

@@ -0,0 +1,76 @@
+{
+  "name": "ThreadList",
+  "slug": "thread-list",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Conversation history with unread marks and actions that wait for hover.",
+  "props": [
+    {
+      "name": "threads",
+      "type": "readonly ThreadItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Conversation rows with title, time, and optional unread mark."
+    },
+    {
+      "name": "activeIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Index of the currently selected thread. An index outside the list selects nothing."
+    },
+    {
+      "name": "onActiveIndexChange",
+      "type": "((index: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks a thread row."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"threads\" | \"activeIndex\" | \"onActiveIndexChange\"\n> & {\n  /** Conversation rows with title, time, and optional unread mark. */\n  threads: readonly ThreadItem[];\n  /** Index of the currently selected thread. An index outside the list selects nothing. */\n  activeIndex: number;\n  /** Called when the user clicks a thread row. */\n  onActiveIndexChange?: (index: number) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Conversation history with unread marks and actions that wait for hover.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ThreadList } from \"@cueplusplus/ui/elements\";\n\n<ThreadList\n  threads={[\n    { title: \"Composer polish\", time: \"2m\", unread: true },\n    { title: \"Runtime migration\", time: \"1h\" },\n  ]}\n  activeIndex={activeIndex}\n  onActiveIndexChange={setActiveIndex}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/thread-list",
+  "mdUrl": "/docs/components/thread-list.md",
+  "jsonUrl": "/r/components/thread-list.json",
+  "specimens": [
+    {
+      "title": "ThreadList",
+      "group": "elements-composer",
+      "components": [
+        "ThreadList"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"one open\">\n    <ThreadList threads={THREADS} activeIndex={thread} onActiveIndexChange={setThread} />\n  </Specimen>\n  <Specimen label=\"nothing open\">\n    <ThreadList threads={THREADS} activeIndex={-1} />\n  </Specimen>\n</Specimens>",
+      "note": "Conversation history at its smallest: a title, how long ago, and an unread dot. The row's actions replace the timestamp on hover rather than sitting beside it, which is what keeps a 240px rail from becoming a toolbar — and the active row never shows an unread mark, because reading it is what cleared it.",
+      "interaction": "the selected row carries `aria-current`; the rename and delete affordances appear on hover in the space the time was using, so nothing moves when they arrive."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/thread-search.json

@@ -0,0 +1,90 @@
+{
+  "name": "ThreadSearch",
+  "slug": "thread-search",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "History you can actually get back into: pinned first, then grouped by when.",
+  "props": [
+    {
+      "name": "threads",
+      "type": "readonly SearchableThread[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "All threads. Filtering matches title and preview together."
+    },
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current search text."
+    },
+    {
+      "name": "activeId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which thread is open."
+    },
+    {
+      "name": "onQueryChange",
+      "type": "((query: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the search is typed."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a thread is opened."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"threads\" | \"query\" | \"activeId\" | \"onQueryChange\" | \"onSelect\"\n> & {\n  /** All threads. Filtering matches title and preview together. */\n  threads: readonly SearchableThread[];\n  /** Current search text. */\n  query: string;\n  /** Which thread is open. */\n  activeId: string;\n  /** Called as the search is typed. */\n  onQueryChange?: (query: string) => void;\n  /** Called when a thread is opened. */\n  onSelect?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "History you can actually get back into: pinned first, then grouped by when.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ThreadSearch } from \"@cueplusplus/ui/elements\";\n\n<ThreadSearch\n  threads={threads}\n  query={query}\n  activeId={activeId}\n  onQueryChange={setQuery}\n  onSelect={setActiveId}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/thread-search",
+  "mdUrl": "/docs/components/thread-search.md",
+  "jsonUrl": "/r/components/thread-search.json",
+  "specimens": [
+    {
+      "title": "ThreadSearch",
+      "group": "elements-composer",
+      "components": [
+        "ThreadSearch"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"grouped\" wide>\n    <ThreadSearch\n      threads={SEARCHABLE}\n      query={threadQuery}\n      activeId={threadId}\n      onQueryChange={setThreadQuery}\n      onSelect={setThreadId}\n    />\n  </Specimen>\n  <Specimen label=\"filtered\" wide>\n    <ThreadSearch threads={SEARCHABLE} query=\"truss\" activeId=\"t-truss\" />\n  </Specimen>\n  <Specimen label=\"nothing matches\" wide>\n    <ThreadSearch threads={SEARCHABLE} query=\"haze\" activeId=\"\" />\n  </Specimen>\n</Specimens>",
+      "note": "History you can actually get back into: pinned first, then grouped by when. Filtering matches the title and the preview together, so a thread found by something said inside it still shows the line that found it. The pinned section is a lift out of the date groups rather than a copy — a pinned thread appears once.",
+      "interaction": "arrows walk the flattened order across group boundaries, which is the order the eye reads rather than the order the data is in."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/threshold-rail.json

@@ -0,0 +1,160 @@
+{
+  "name": "ThresholdRail",
+  "slug": "threshold-rail",
+  "group": "midi",
+  "importPath": "@cueplusplus/ui/midi",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The trigger level, set by dragging it along the signal it triggers on.\n\nA threshold is a number, and a number field would hold it perfectly well —\nbut a threshold is only ever chosen *relative to a signal*, and this control\nis the one place both are visible at once: the live level fills the rail, the\npeak-hold needle marks how far it got, and the handle sits where the trigger\nfires. Unified from ableton-sync's three near-identical threshold editors.\n\nTwo thresholds make it a window rather than a floor: supply `lower` and the\nrail arms *between* the handles, which is how a band-triggered cue avoids\nfiring on a peak it was never meant to catch.\n\nWhat the ports did not have is a keyboard. Their handles moved on `mousedown`\nplus a document listener, so a threshold could not be set by anyone not using\na mouse, and no screen reader was ever told what the number was. Here each\nhandle is a `role=\"slider\"` announcing a percentage, arrow keys step, page\nkeys jump, and Home/End go to the limits — the drag is the fast path, not the\nonly path.\n\nThe `onChange`/`onCommit` split is the same undo-coalescing contract as\n`Slider` and `ScrubInput`: one drag is one undo entry.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The (upper) threshold, `0`–`1`. Always controlled."
+    },
+    {
+      "name": "onChange",
+      "type": "(value: number) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the next upper threshold."
+    },
+    {
+      "name": "lower",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The lower threshold. Supplying it turns the rail into a window."
+    },
+    {
+      "name": "onLowerChange",
+      "type": "((value: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the next lower threshold."
+    },
+    {
+      "name": "onCommit",
+      "type": "((thresholds: { upper: number; lower?: number; }) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called once per finished gesture with both thresholds: pointer-up after a\ndrag, or each key step. Hang undo entries and network writes here —\n`onChange` fires on every frame of a drag."
+    },
+    {
+      "name": "level",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Live signal level, `0`–`1`, drawn as a fill. Absent draws no fill."
+    },
+    {
+      "name": "peak",
+      "type": "number | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Peak-hold position, `0`–`1`. `null` or absent draws no needle."
+    },
+    {
+      "name": "step",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0.01",
+      "description": "Grid the handles snap to. Defaults to `0.01`."
+    },
+    {
+      "name": "minGap",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0.01",
+      "description": "Closest the two handles may get. Defaults to `0.01`."
+    },
+    {
+      "name": "belowTone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "danger",
+      "description": "Ink for the zones outside the window. Defaults to `\"danger\"`."
+    },
+    {
+      "name": "aboveTone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "ok",
+      "description": "Ink for the armed zone. Defaults to `\"ok\"`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse every gesture."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Threshold",
+      "description": "What is being thresholded. Names the handles. Defaults to `\"Threshold\"`."
+    },
+    {
+      "name": "formatValue",
+      "type": "((value: number) => string)",
+      "required": false,
+      "defaultValue": "(fraction) => `${Math.round(fraction * 100)}%`",
+      "description": "Format a value for the handle's spoken text. Defaults to `\"62%\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"defaultValue\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-busy-soft",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-danger-soft",
+    "--cue-fg",
+    "--cue-info",
+    "--cue-info-soft",
+    "--cue-ok",
+    "--cue-ok-soft",
+    "--cue-sunken",
+    "--cue-warn",
+    "--cue-warn-soft"
+  ],
+  "summary": "The trigger level, set by dragging it along the signal it triggers on.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ThresholdRail value={threshold} onChange={setThreshold} level={rms} peak={peak} />\n<ThresholdRail value={high} lower={low} onChange={setHigh} onLowerChange={setLow} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/threshold-rail",
+  "mdUrl": "/docs/components/threshold-rail.md",
+  "jsonUrl": "/r/components/threshold-rail.json",
+  "specimens": [
+    {
+      "title": "ThresholdRail",
+      "group": "midi",
+      "components": [
+        "ThresholdRail"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-6)\">\n  <ThresholdRail\n    value={upper}\n    onChange={setUpper}\n    lower={lower}\n    onLowerChange={setLower}\n    level={0.58}\n    peak={0.81}\n    label=\"Trigger thresholds\"\n  />\n  <ThresholdRail\n    value={upper}\n    onChange={setUpper}\n    level={0.34}\n    belowTone=\"info\"\n    aboveTone=\"danger\"\n    label=\"Single threshold\"\n  />\n  <ThresholdRail value={0.6} onChange={() => {}} disabled label=\"Threshold, locked\" />\n</div>",
+      "note": "A dual-handle rail with tone zones below and above, a level bar and a peak-hold needle.",
+      "interaction": "each handle is a slider with its own name; both scale up while dragging, and `onCommit` fires once on release."
+    }
+  ],
+  "todo": true
+}