@cueplusplus/ui 0.13.0

package/manifest/components/thread-search.json

@@ -0,0 +1,108 @@
+{
+  "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.",
+      "control": {
+        "kind": "array",
+        "fixture": "composer.searchable"
+      }
+    },
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current search text.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "activeId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which thread is open.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onQueryChange",
+      "type": "((query: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the search is typed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a thread is opened.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "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,223 @@
+{
+  "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.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onChange",
+      "type": "(value: number) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the next upper threshold.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "lower",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The lower threshold. Supplying it turns the rail into a window.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onLowerChange",
+      "type": "((value: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the next lower threshold.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "level",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Live signal level, `0`–`1`, drawn as a fill. Absent draws no fill.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "peak",
+      "type": "number | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Peak-hold position, `0`–`1`. `null` or absent draws no needle.",
+      "control": {
+        "kind": "number",
+        "nullable": true
+      }
+    },
+    {
+      "name": "step",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0.01",
+      "description": "Grid the handles snap to. Defaults to `0.01`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "minGap",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0.01",
+      "description": "Closest the two handles may get. Defaults to `0.01`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "belowTone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "danger",
+      "description": "Ink for the zones outside the window. Defaults to `\"danger\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "danger",
+          "accent",
+          "busy",
+          "ok",
+          "warn",
+          "info"
+        ]
+      }
+    },
+    {
+      "name": "aboveTone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "ok",
+      "description": "Ink for the armed zone. Defaults to `\"ok\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "danger",
+          "accent",
+          "busy",
+          "ok",
+          "warn",
+          "info"
+        ]
+      }
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse every gesture.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Threshold",
+      "description": "What is being thresholded. Names the handles. Defaults to `\"Threshold\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "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%\"`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "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
+}

package/manifest/components/time-boundary.json

@@ -0,0 +1,68 @@
+{
+  "name": "TimeBoundary",
+  "slug": "time-boundary",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The rule that says the day changed: a label centred between two hairlines.\n\nOne row, placed by the caller. That is the difference between this and\n`DaySeparator`, which takes a whole message list and inserts its own rules:\na transcript assembled from a row union — the shape every shipping agent UI\nconverged on — needs the boundary as a *member of that union*, not as a\ncomponent that owns the list around it.\n\nIt is a `role=\"separator\"` carrying its label as an accessible name, and the\ntext inside it is `aria-hidden`. A reader hears \"Today, separator\" once\nrather than twice, and the hairlines are never announced at all.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The label, pre-formatted: `Today`, `Yesterday`, `14 March`. This family\ndoes no date arithmetic and owns no locale — the caller knows which one the\nconsole is in, and `DaySeparator` next door takes its days the same way.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "dateTime",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The machine-readable instant, rendering the label inside a `<time>`. Worth\ngiving: it is what lets a test, a scraper or a deep link find the boundary\nwithout parsing the words a human reads.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg-subtle"
+  ],
+  "summary": "The rule that says the day changed: a label centred between two hairlines.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TimeBoundary } from \"@cueplusplus/ui/elements\";\n\n<TimeBoundary label=\"Today\" dateTime=\"2026-08-22\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/time-boundary",
+  "mdUrl": "/docs/components/time-boundary.md",
+  "jsonUrl": "/r/components/time-boundary.json",
+  "specimens": [
+    {
+      "title": "TimeBoundary",
+      "group": "elements-thread",
+      "components": [
+        "TimeBoundary"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"today\" wide>\n    <div className=\"w-full max-w-md\">\n      <TimeBoundary label=\"Today\" dateTime=\"2026-08-22\" />\n    </div>\n  </Specimen>\n  <Specimen label=\"a date\" wide>\n    <div className=\"w-full max-w-md\">\n      <TimeBoundary label=\"14 March\" dateTime=\"2026-03-14\" />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "One row, placed by the caller — which is the difference between this and DaySeparator, which takes a whole message list and inserts its own. A transcript assembled from a row union needs the boundary as a member of that union. It is a role=separator carrying its label as its name, with the text inside aria-hidden so a reader hears 'Today' once rather than twice, and the caller pre-formats the words because this family owns no locale.",
+      "interaction": "none. It is a rule with a word on it, and nothing here takes focus."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/time-field.json

@@ -0,0 +1,93 @@
+{
+  "name": "TimeField",
+  "slug": "time-field",
+  "group": "date",
+  "importPath": "@cueplusplus/ui/date",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "A typed time of day, segment by segment.\n\nThe sibling of {@link DateField } on the same React Aria part, for the half of\na schedule a calendar cannot express. Pass `hourCycle={24}` for a show clock —\na control room runs on 24-hour time, and the AM/PM segment is one more thing\nto tab through.\n\nValues are `@internationalized/date` `Time` objects.\n\n`react-aria-components` is an **optional peer**: import this from\n`@cueplusplus/ui/date`.",
+  "props": [
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    },
+    {
+      "name": "inputClassName",
+      "type": "ClassNameOrFunction<DateInputRenderProps>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the segment group itself.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<AriaTimeFieldProps<T>, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A typed time of day, segment by segment.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TimeField aria-label=\"Go time\" hourCycle={24} value={time} onChange={setTime} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/time-field",
+  "mdUrl": "/docs/components/time-field.md",
+  "jsonUrl": "/r/components/time-field.json",
+  "specimens": [
+    {
+      "title": "TimeField",
+      "group": "date",
+      "components": [
+        "TimeField"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"minutes\">\n    <TimeField aria-label=\"House open\" defaultValue={new Time(19, 30)} />\n  </Specimen>\n  <Specimen label=\"seconds\">\n    <TimeField\n      aria-label=\"Timecode start\"\n      granularity=\"second\"\n      defaultValue={new Time(19, 30, 5)}\n    />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <TimeField aria-label=\"House open, disabled\" isDisabled defaultValue={new Time(19, 30)} />\n  </Specimen>\n</Specimens>",
+      "note": "The same field, for a clock time. Granularity decides how many segments there are.",
+      "interaction": "same segment stepping; 24-hour or 12-hour follows the locale, not a prop."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/timeline-ruler.json

@@ -0,0 +1,178 @@
+{
+  "name": "TimelineRuler",
+  "slug": "timeline-ruler",
+  "group": "midi",
+  "importPath": "@cueplusplus/ui/midi",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The bar ruler over an arrangement: zoom-adaptive, culled, and deliberately\nfaint.\n\nPorted from ableton-sync's arrangement view, with its two performance\nproblems fixed. The first is density: the original picked from a ladder of\nmusical intervals and then multiplied by four, so its ruler was four times\nsparser than the one centimetre it aimed for. The second is culling: it kept\nfifty *beats* of margin either side of the viewport, which at a tight zoom is\na thousand pixels of hidden DOM and at a loose zoom is nothing. Both now live\nin `_ruler.ts`, are pure, and are tested without a DOM.\n\n**The horizontal axis is in CSS pixels, not `rem`** — the one place in this\nsystem that is true. `pxPerBeat` is not a size, it is a coordinate system the\nruler shares with whatever the caller draws underneath it: clips, automation,\na playhead overlay. Converting it to `rem` here would silently shear the\nruler away from the tracks at any root font size other than 16. The ruler's\n*height* is a size, and is in `rem` like everything else.\n\nThe ticks are painted at 10–15% opacity on purpose. A ruler is read by\nglancing, and the material under it — the clips — is what the eye is actually\non; a ruler drawn at full contrast becomes a fence across the arrangement.",
+  "props": [
+    {
+      "name": "totalBeats",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Length of the song, in quarter-note beats.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "pxPerBeat",
+      "type": "number",
+      "required": false,
+      "defaultValue": "20",
+      "description": "Zoom, in px per quarter-note beat. Defaults to `20`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "viewport",
+      "type": "RulerViewport",
+      "required": false,
+      "defaultValue": null,
+      "description": "What is on screen, in the same pixel coordinates.\n\nSupply it when the host already tracks its own scroll — a timeline usually\ndoes, and one source of truth scrolls in step. Omitted, the ruler watches\nits own scroll parent instead.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "timeSignature",
+      "type": "TimeSignature",
+      "required": false,
+      "defaultValue": "{ numerator: 4, denominator: 4 }",
+      "description": "The signature the bars are counted in. Defaults to 4/4.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "tempo",
+      "type": "number | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Tempo in BPM. Only used for the readout and the accessible name.",
+      "control": {
+        "kind": "number",
+        "nullable": true
+      }
+    },
+    {
+      "name": "playhead",
+      "type": "number | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Transport position in quarter-note beats. `null` or absent draws no playhead.",
+      "control": {
+        "kind": "number",
+        "nullable": true
+      }
+    },
+    {
+      "name": "loop",
+      "type": "LoopRegion | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "The loop bracket, if there is one.",
+      "control": {
+        "kind": "opaque",
+        "nullable": true
+      }
+    },
+    {
+      "name": "markers",
+      "type": "readonly RulerMarker[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Cue points to pin along the ruler.",
+      "control": {
+        "kind": "array"
+      }
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "40",
+      "description": "Ruler height in px at the 16px root, emitted as `rem`. Defaults to `40`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "targetPx",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Pixel spacing the ticks aim for. Defaults to one centimetre.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "bufferPx",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How far past the viewport to keep ruling, in px. Defaults to `120`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Timeline",
+      "description": "What this timeline is. Defaults to `\"Timeline\"`.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-surface-1",
+    "--cue-text-micro",
+    "--cue-warn"
+  ],
+  "summary": "The bar ruler over an arrangement: zoom-adaptive, culled, and deliberately faint.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TimelineRuler totalBeats={512} pxPerBeat={zoom} viewport={viewport} playhead={position} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/timeline-ruler",
+  "mdUrl": "/docs/components/timeline-ruler.md",
+  "jsonUrl": "/r/components/timeline-ruler.json",
+  "specimens": [
+    {
+      "title": "TimelineRuler",
+      "group": "midi",
+      "components": [
+        "TimelineRuler"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  {[6, 16, 44].map((pxPerBeat) => (\n    <Panel key={pxPerBeat} className=\"overflow-hidden\">\n      <PanelHeader\n        title={`${pxPerBeat} px per beat`}\n        actions={\n          <Chip tone=\"neutral\">interval {chooseInterval(pxPerBeat, 4)} beats</Chip>\n        }\n      />\n      <TimelineRuler\n        totalBeats={128}\n        pxPerBeat={pxPerBeat}\n        viewport={{ offset: 0, width: 720 }}\n        playhead={37.5}\n        loop={{ start: 32, length: 16, enabled: true }}\n        markers={MARKERS}\n        tempo={124}\n        label={`Ruler at ${pxPerBeat} pixels per beat`}\n      />\n    </Panel>\n  ))}\n</div>",
+      "note": "Zoom-adaptive tick density, targeting roughly one tick per centimetre. The interval choice is a pure exported function, so it can be tested without a DOM.",
+      "interaction": "none itself; it is the coordinate system a track editor draws under. `pxPerBeat` stays in pixels on purpose."
+    }
+  ],
+  "todo": true
+}