@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/log-viewer.json

@@ -0,0 +1,139 @@
+{
+  "name": "LogViewer",
+  "slug": "log-viewer",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui/instruments/log-viewer",
+  "peerDependencies": [
+    "@tanstack/react-virtual",
+    "anser"
+  ],
+  "clientOnly": true,
+  "description": "A virtualised log tail: ANSI colour, level filters, and stick-to-bottom.\n\nThe four things a log pane has to get right, and the reasons each one is not\noptional:\n\n- **Virtualised.** Five thousand DOM rows is a frozen tab. Rows are fixed at\n  the short control rung so the virtualiser never has to measure, which is\n  also what keeps the scrollbar honest while lines stream in.\n- **ANSI as data, never as HTML.** `anser` will happily hand back a markup\n  string, and the moment that reaches `dangerouslySetInnerHTML` any process\n  that prints a `<script>` owns the console watching it. Colour arrives here\n  as spans of *text* with resolved token colours (see `_ansi.ts`).\n- **Following is a mode, not a scroll.** While pinned to the bottom the view\n  follows; scroll up and it stops and starts counting, so reading something\n  is never fought by the stream. The count comes back as a pill, not as a\n  jump.\n- **A cap.** An unbounded buffer is a memory leak with a progress bar. The\n  head is dropped past `maxLines`.\n\nShips from `@cueplusplus/ui/instruments/log-viewer`: it needs\n`@tanstack/react-virtual` and `anser`, both optional peers, and neither\nbelongs in the bundle of an app that renders no logs.",
+  "props": [
+    {
+      "name": "lines",
+      "type": "readonly LogLine[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The buffer, oldest first."
+    },
+    {
+      "name": "follow",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Stick to the bottom as lines arrive. Defaults to `true`."
+    },
+    {
+      "name": "filters",
+      "type": "false | readonly LogLevel[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which levels get a filter chip. Defaults to the levels present in `lines`;\n`false` hides the strip entirely. Levels with no chip are always shown."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Viewer height in px at the 16px root."
+    },
+    {
+      "name": "rowHeight",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Row height in px. Defaults to the short control rung at the ambient density."
+    },
+    {
+      "name": "maxLines",
+      "type": "number",
+      "required": false,
+      "defaultValue": "5000",
+      "description": "Cap on retained lines; the oldest are dropped. Defaults to `5000`."
+    },
+    {
+      "name": "formatTimestamp",
+      "type": "((ts: number) => string)",
+      "required": false,
+      "defaultValue": "defaultTimestamp",
+      "description": "Render a line's timestamp. Defaults to a local `HH:MM:SS`."
+    },
+    {
+      "name": "emptyLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "No output",
+      "description": "What to say when there is nothing to show. Defaults to `\"No output\"`."
+    },
+    {
+      "name": "newLinesLabel",
+      "type": "((count: number) => string)",
+      "required": false,
+      "defaultValue": "(count) => `${count} new line${count === 1 ? \"\" : \"s\"}`",
+      "description": "Label for the catch-up pill. Defaults to `\"3 new lines\"`."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the log region. Required in practice — name the stream."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onScroll\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-pad-row-x",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-sunken",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "A virtualised log tail: ANSI colour, level filters, and stick-to-bottom.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<LogViewer aria-label=\"Build output\" height={320} lines={lines} />\n<LogViewer aria-label=\"Worker\" height={200} follow={false} filters={[\"warn\", \"error\"]} lines={lines} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/log-viewer",
+  "mdUrl": "/docs/components/log-viewer.md",
+  "jsonUrl": "/r/components/log-viewer.json",
+  "specimens": [
+    {
+      "title": "LogViewer",
+      "group": "instruments",
+      "components": [
+        "LogViewer"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-5)\">\n  <LogViewer lines={LOG_LINES} height={220} follow />\n  <LogViewer lines={[]} height={120} emptyLabel={COPY.empty.title} />\n</div>",
+      "note": "Virtualised rows at the small control height, ANSI decoded to text nodes (never innerHTML), level filter chips, and a stick-to-bottom scroller that offers a `N new lines` pill once you scroll away.",
+      "interaction": "the filter chips are toggles; the new-lines pill is a button that returns you to the tail."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/menubar.json

@@ -0,0 +1,157 @@
+{
+  "name": "Menubar",
+  "slug": "menubar",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The desktop-application menu bar: a row of words, each dropping a menu.\n\nWraps Base UI's `Menubar` around the same `Menu` parts {@link DropdownMenu}\nuses, so the rows here *are* the dropdown's rows — one menu language across\nthe whole system — and the bar-level behaviour (hover to switch menus once one\nis open, arrow keys across the bar, typeahead inside a menu) is the\nprimitive's.\n\nUse it for an application shell that genuinely has a dozen-plus commands to\nfile away. A view with six actions wants a `Toolbar`; a menubar with two words\non it is a toolbar wearing a costume.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Menu",
+    "Trigger",
+    "Content"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Menubar.Root",
+      "description": "The bar itself: chrome-toolbar tall, hairline underneath, surface fill.\n\nSized from `--cue-chrome-toolbar` rather than the control ladder, exactly like\n`Toolbar` and `TitleBar` — a menubar is window furniture, and window furniture\nkeeps its own rung of the density scale so it stays legible when the controls\ninside the view shrink.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the bar."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseMenubar.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Menu",
+      "usage": "Menubar.Menu",
+      "description": "One menu of the bar — its trigger and its content. Renders no element.\n\nBase UI reads the enclosing menubar from context: once one menu is open,\nhovering a sibling trigger switches to it without a second click, and the\narrow keys walk the bar. None of that needs wiring here.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Menubar.Trigger",
+      "description": "A top-level word on the bar: `Show`, `Edit`, `View`.\n\nOpen is `accent-soft` plus full-strength ink, not a solid accent fill — the\nsame ruling as the active tab and the highlighted menu row. A filled block on\na bar of five words reads as a button someone left pressed.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the trigger."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseMenu.Trigger.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Menubar.Content",
+      "description": "One menu's portal, positioner and popup.\n\nAlways drops from the bottom of its word — a menubar menu that flipped\nupward would break the one spatial promise the pattern makes — and is\nportalled through {@link useCuePortalProps} so it renders at the caller's\ntheme and density.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\"",
+          "required": false,
+          "defaultValue": "start",
+          "description": "Alignment along the bottom of the trigger. Defaults to `\"start\"`."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed."
+        },
+        {
+          "name": "positionerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the positioner that places the popup."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": "4",
+          "description": "Gap in px between trigger and popup. Defaults to `4`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseMenu.Popup.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-chrome-toolbar",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The desktop-application menu bar: a row of words, each dropping a menu.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Menubar.Root>\n  <Menubar.Menu>\n    <Menubar.Trigger>Show</Menubar.Trigger>\n    <Menubar.Content>\n      <Menubar.Item onClick={newShow}>New show</Menubar.Item>\n      <Menubar.Separator />\n      <Menubar.Item trailing={<Kbd>⌘S</Kbd>} onClick={save}>Save</Menubar.Item>\n    </Menubar.Content>\n  </Menubar.Menu>\n</Menubar.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/menubar",
+  "mdUrl": "/docs/components/menubar.md",
+  "jsonUrl": "/r/components/menubar.json",
+  "specimens": [
+    {
+      "title": "Menubar",
+      "group": "overlays",
+      "components": [
+        "Menubar"
+      ],
+      "code": "<Menubar.Root>\n  <Menubar.Menu>\n    <Menubar.Trigger>File</Menubar.Trigger>\n    <Menubar.Content>\n      <Menubar.Item trailing={<Kbd>⌘N</Kbd>}>New show</Menubar.Item>\n      <Menubar.Item trailing={<Kbd>⌘O</Kbd>}>Open</Menubar.Item>\n      <Menubar.Separator />\n      <Menubar.Item trailing={<Kbd>⌘S</Kbd>}>Save</Menubar.Item>\n    </Menubar.Content>\n  </Menubar.Menu>\n  <Menubar.Menu>\n    <Menubar.Trigger>View</Menubar.Trigger>\n    <Menubar.Content>\n      <Menubar.CheckboxItem checked={follow} onCheckedChange={setFollow}>\n        Follow playhead\n      </Menubar.CheckboxItem>\n      <Menubar.Item>Reset zoom</Menubar.Item>\n    </Menubar.Content>\n  </Menubar.Menu>\n</Menubar.Root>",
+      "note": "The desktop bar: once one menu is open, hovering the next one opens it.",
+      "interaction": "left and right arrows move between menus, up and down move inside one."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/message-list.json

@@ -0,0 +1,100 @@
+{
+  "name": "MessageList",
+  "slug": "message-list",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The transcript scroller: sticks to the bottom, and stops fighting you the\nmoment you scroll up.\n\nFollowing is a *mode*, not a scroll position. While pinned to the bottom the\nview follows new turns; scroll up to read something and it lets go and offers\na \"jump to latest\" pill instead — because a stream that yanks the viewport\nmid-sentence is the single most common reason people stop reading a chat\npane. Coming back to the bottom re-arms it.\n\nDeliberately **not** virtualised. A virtualiser needs a measurable row height\nand chat turns are variable-height by nature; the cost of getting that wrong\n(jumping scrollbars) is worse than the cost of a few hundred DOM nodes. When\na thread really is unbounded, page it — do not virtualise it.",
+  "props": [
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The turns, oldest first — normally {@link Message }s."
+    },
+    {
+      "name": "follow",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Stick to the bottom as turns arrive. Defaults to `true`."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Fixed height in px at the 16px root, emitted as rem. Omit to fill the parent."
+    },
+    {
+      "name": "jumpLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Jump to latest",
+      "description": "Label on the catch-up pill. Defaults to `\"Jump to latest\"`."
+    },
+    {
+      "name": "emptyLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "No messages yet",
+      "description": "What to say before the first turn. Defaults to `\"No messages yet\"`."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the transcript. Required in practice — name the thread."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onScroll\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border-overlay",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The transcript scroller: sticks to the bottom, and stops fighting you the moment you scroll up.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<MessageList aria-label=\"Thread\" height={480}>\n  {turns.map((t) => <Message key={t.id} agent={t.agent}>{t.text}</Message>)}\n</MessageList>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/message-list",
+  "mdUrl": "/docs/components/message-list.md",
+  "jsonUrl": "/r/components/message-list.json",
+  "specimens": [
+    {
+      "title": "MessageList",
+      "group": "chat",
+      "components": [
+        "MessageList"
+      ],
+      "code": "<MessageList height={220} follow className=\"w-full max-w-[42rem]\">\n  {Array.from({ length: 14 }, (_, index) => (\n    <Message\n      key={index}\n      role={index % 2 === 0 ? \"user\" : \"agent\"}\n      agent={index % 2 === 0 ? undefined : \"patcher\"}\n      author={index % 2 === 0 ? \"Criss\" : \"Patcher\"}\n    >\n      Frame {index}: 512 slots at 44 Hz.\n    </Message>\n  ))}\n</MessageList>",
+      "note": "A stick-to-bottom scroller. Scroll away and it offers to jump back to the latest rather than yanking you there.",
+      "interaction": "the jump control is a button, and it appears only once you have actually scrolled off the tail."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/message.json

@@ -0,0 +1,116 @@
+{
+  "name": "Message",
+  "slug": "message",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One turn in a conversation.\n\nContent is rendered as React nodes, verbatim: there is no markdown or HTML\npath here on purpose. Model output is untrusted text, and a component that\nquietly parsed it would make every consumer of this library one prompt away\nfrom an injection. Callers that want rich text pass their own renderer as\nchildren and own that decision.\n\nThe author line is mono micro and inked in the agent's own colour, so a\nmulti-agent thread is scannable by hue before it is readable by name.\n\nStatic markup — no `\"use client\"`; a transcript renders on the server.",
+  "props": [
+    {
+      "name": "role",
+      "type": "\"agent\" | \"user\" | \"system\"",
+      "required": false,
+      "defaultValue": "agent",
+      "description": "Who is speaking. Defaults to `\"agent\"`."
+    },
+    {
+      "name": "agent",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The speaking agent's slug. Names the turn and inks the author line and the\n`--agent-color` custom property, which anything nested reads."
+    },
+    {
+      "name": "rootAgent",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the orchestrator, so its turns take the theme accent."
+    },
+    {
+      "name": "author",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Author line override. Defaults to `\"You\"` for the user and to `agent` otherwise."
+    },
+    {
+      "name": "timestamp",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rendered opposite the author — pass a formatted time, not a `Date`."
+    },
+    {
+      "name": "pending",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "The turn is still streaming: shows a caret and announces it."
+    },
+    {
+      "name": "footer",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slot under the body — attachments, warnings, retry actions."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The turn itself."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"role\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-scale",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-micro"
+  ],
+  "summary": "One turn in a conversation.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Message agent=\"researcher\" timestamp=\"14:02\">Found three references.</Message>\n<Message role=\"user\">Patch universe 3.</Message>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/message",
+  "mdUrl": "/docs/components/message.md",
+  "jsonUrl": "/r/components/message.json",
+  "specimens": [
+    {
+      "title": "Message",
+      "group": "chat",
+      "components": [
+        "Message"
+      ],
+      "code": "<div className=\"flex w-full max-w-[42rem] flex-col gap-(--cue-space-4)\">\n  <Message role=\"user\" author=\"Criss\" timestamp=\"18:04\">\n    Patch the front truss on universe 1 and write a cue for house-to-half.\n  </Message>\n  <Message role=\"agent\" agent=\"patcher\" author=\"Patcher\" timestamp=\"18:04\">\n    6 fixtures patched to channels 1 to 48. Cue 1 written with a 3.0s fade.\n  </Message>\n  <Message role=\"agent\" agent=\"reviewer\" author=\"Reviewer\" pending>\n    Checking the patch against the plot.\n  </Message>\n  <Message role=\"system\" timestamp=\"18:05\">\n    Run paused: waiting on an answer.\n  </Message>\n  <Message\n    role=\"agent\"\n    agent=\"cue-writer\"\n    author=\"Cue writer\"\n    footer={<Chip tone=\"ok\">applied</Chip>}\n  >\n    Cue 2 follows cue 1 automatically.\n  </Message>\n</div>",
+      "note": "Three roles. The bubble radii are asymmetric and mirrored by role, and the author line is mono micro. Nothing here parses markdown: model output is an untrusted string, and a component that rendered it as markup would make every consumer one prompt away from an injection.",
+      "interaction": "none. A message is a record."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/meter.json

@@ -0,0 +1,114 @@
+{
+  "name": "Meter",
+  "slug": "meter",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A quota bar that shows **pace**, not just fill.\n\nA bare percentage answers \"how much is gone\" but not the question that\nactually matters: *will it last*. 93% used is fine in the last hour of a\nweekly window and an emergency on the first day. So the meter carries a\nsecond mark — how far through the window we are in time — and reads the two\ntogether: fill ahead of the tick is burning faster than the window refills.\n\nThe tick is deliberately quiet: a 1px rule, not a second bar. It annotates\nthe fill and stays ignorable when someone only wants the number.\n\nSeverity is never invented here — `tone` comes from whoever owns the\nthresholds. Likewise `provenance`: the bar changes its own texture rather\nthan letting an estimate or a missing denominator look like a measurement.\n\nThe over-pace pulse stills under `prefers-reduced-motion`; the state stays\nreadable as `data-over-pace`.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "percent",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How full, 0–100. Clamped; a non-finite value reads as 0."
+    },
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"busy\" | \"ok\" | \"warn\"",
+      "required": false,
+      "defaultValue": "ok",
+      "description": "Status colour for the fill. Defaults to `\"ok\"`."
+    },
+    {
+      "name": "paceTick",
+      "type": "number | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "How far through the window we are *by time*, 0–1. Drawn as a 1px rule\nacross the bar so the fill can be read against its pace: fill ahead of the\ntick means burning faster than the window refills. Pass `null` when there\nis no window."
+    },
+    {
+      "name": "empty",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render the striped \"no data\" treatment instead of a level."
+    },
+    {
+      "name": "provenance",
+      "type": "\"none\" | \"vendor\" | \"estimated\" | \"unbounded\"",
+      "required": false,
+      "defaultValue": "vendor",
+      "description": "Where the ceiling came from. Defaults to `\"vendor\"`."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "4",
+      "description": "Bar height in px at the 16px root, emitted as `rem`. Defaults to `4`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Usage",
+      "description": "The accessible name. A meter is nearly always a usage readout, so that is\nthe default; override it for anything else. When there is no level to\nreport (`empty`, or an unbounded ceiling) the state is appended to it, as\nin `\"Usage: No data\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-ok",
+    "--cue-surface-3",
+    "--cue-warn"
+  ],
+  "summary": "A quota bar that shows pace, not just fill.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Meter percent={72} tone=\"warn\" paceTick={0.5} />\n<Meter percent={0} empty label=\"Requests this month\" />\n<Meter percent={40} provenance=\"estimated\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/meter",
+  "mdUrl": "/docs/components/meter.md",
+  "jsonUrl": "/r/components/meter.json",
+  "whenToUse": [
+    "A bounded quantity against a ceiling: quota used, storage, a dimmer level.",
+    "When the reader needs to know whether usage is ahead of the clock. Pass `paceTick`."
+  ],
+  "whenNotToUse": [
+    "How far a task has got. Use `Progress`.",
+    "A number with no ceiling. Use `Stat`.",
+    "A value over time. Use `Sparkline` or `UsageChart`."
+  ],
+  "commonMistakes": [
+    "Passing a fraction. `percent` is 0-100, not 0-1.",
+    "Leaving `provenance` at `vendor` for a ceiling somebody typed. `estimated` hatches the bar, which is what keeps a guess from wearing the authority of a reported number."
+  ],
+  "specimens": [
+    {
+      "title": "Meter",
+      "group": "instruments",
+      "components": [
+        "Meter"
+      ],
+      "code": "<Panel className=\"w-full max-w-[36rem]\">\n  {CHANNELS.map((channel) => (\n    <Row key={channel.name} className=\"gap-(--cue-space-4)\">\n      <span className=\"w-[7rem] shrink-0 truncate\">{channel.name}</span>\n      <Meter percent={channel.level} tone={channel.tone} className=\"flex-1\" />\n      <span className=\"w-[3rem] shrink-0 text-right font-mono tabular-nums\">\n        {channel.level}%\n      </span>\n    </Row>\n  ))}\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Pace tick</span>\n    <Meter percent={64} paceTick={50} className=\"flex-1\" label=\"64% used, 50% of period elapsed\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Estimated</span>\n    <Meter percent={40} provenance=\"estimated\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Unbounded</span>\n    <Meter percent={0} provenance=\"unbounded\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">No data</span>\n    <Meter percent={0} empty className=\"flex-1\" />\n  </Row>\n</Panel>",
+      "note": "Never invents a number: an unbounded meter draws no percentage, an empty one draws stripes rather than a zero, and an estimated ceiling is hatched so it cannot pass for a measurement.",
+      "interaction": "the over-pace pulse stills under prefers-reduced-motion and stays readable as a data attribute."
+    }
+  ]
+}