@cueplusplus/ui 0.13.0

package/manifest/components/password-input.json

@@ -0,0 +1,171 @@
+{
+  "name": "PasswordInput",
+  "slug": "password-input",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A masked text field with a reveal control.\n\nThe reveal is a **toggle button carrying `aria-pressed`**, not a checkbox and\nnot a bare icon: a screen-reader user needs to know both what it does and\nwhich way it currently is, and `aria-pressed` is the one attribute that says\nboth. The label swaps with the state for the same reason.\n\nRevealing switches `type` between `password` and `text` rather than painting\nover the characters, so the browser's own autofill and password managers keep\nworking.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the group that wraps the input and the reveal button.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the input, when no `FieldLabel` names it. Declared here\nrather than left to the inherited attribute so the props table carries the\nrow: a bare input outside a `Field` has no other way to be named.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "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": "hideLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Hide password",
+      "description": "Accessible name while revealed. Defaults to `\"Hide password\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "An example of what goes in the field, shown while it is empty. Not a name:\nit disappears on the first keystroke, so pair it with `aria-label` or a\n`FieldLabel`. Declared for the props-table row, as `aria-label` is above.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "revealed",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Reveal the value. Use with `onRevealedChange` for a controlled toggle.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "defaultRevealed",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Initially revealed, for an uncontrolled toggle. Defaults to `false`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onRevealedChange",
+      "type": "((revealed: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new reveal state.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "showReveal",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Offer the reveal affordance at all. Defaults to `true`. Switch it off for a\nvalue the product must never re-display — a stored secret the user is\nreplacing rather than reading.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "revealLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Show password",
+      "description": "Accessible name while masked. Defaults to `\"Show password\"`.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<InputProps, \"type\" | \"size\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--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-icon-md",
+    "--cue-radius-control",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A masked text field with a reveal control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PasswordInput aria-label=\"Service key\" value={key} onValueChange={setKey} />\n<Field><FieldLabel>Token</FieldLabel><PasswordInput showReveal={false} /></Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/password-input",
+  "mdUrl": "/docs/components/password-input.md",
+  "jsonUrl": "/r/components/password-input.json",
+  "specimens": [
+    {
+      "title": "PasswordInput",
+      "group": "forms",
+      "components": [
+        "PasswordInput"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"hidden\">\n    <PasswordInput aria-label=\"Console password\" defaultValue=\"hunter2\" />\n  </Specimen>\n  <Specimen label=\"revealed\">\n    <PasswordInput aria-label=\"Console password, revealed\" defaultValue=\"hunter2\" defaultRevealed />\n  </Specimen>\n  <Specimen label=\"no toggle\">\n    <PasswordInput aria-label=\"Password, no reveal\" defaultValue=\"hunter2\" showReveal={false} />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <PasswordInput aria-label=\"Password, disabled\" defaultValue=\"hunter2\" disabled />\n  </Specimen>\n</Specimens>",
+      "note": "Input plus a reveal toggle carrying `aria-pressed`, so the state is spoken rather than implied by an icon swap.",
+      "interaction": "the toggle is in the tab order after the field."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/permission-grant.json

@@ -0,0 +1,115 @@
+{
+  "name": "PermissionGrant",
+  "slug": "permission-grant",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Granting a capability rather than approving one action, with the reach spelled out.",
+  "props": [
+    {
+      "name": "capability",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is being granted, named as a capability rather than an action.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "requester",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Who is asking.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "reach",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Exactly what the grant covers, and what it does not. Write the limits in too.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "scope",
+      "type": "\"pending\" | \"always\" | \"denied\" | \"session\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "pending shows the choices; anything else shows the settled outcome.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "pending",
+          "always",
+          "denied",
+          "session"
+        ]
+      }
+    },
+    {
+      "name": "onGrant",
+      "type": "((scope: GrantScope) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the scope the user chose.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"capability\" | \"requester\" | \"reach\" | \"scope\" | \"onGrant\"\n> & {\n  /** What is being granted, named as a capability rather than an action. */\n  capability: string;\n  /** Who is asking. */\n  requester: string;\n  /** Exactly what the grant covers, and what it does not. Write the limits in too. */\n  reach: readonly string[];\n  /** pending shows the choices; anything else shows the settled outcome. */\n  scope: GrantScope | \"pending\";\n  /** Called with the scope the user chose. */\n  onGrant?: (scope: GrantScope) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Granting a capability rather than approving one action, with the reach spelled out.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { PermissionGrant } from \"@cueplusplus/ui/elements\";\n\n<PermissionGrant\n  capability=\"Filesystem access\"\n  requester=\"filesystem-mcp\"\n  reach={reach}\n  scope=\"pending\"\n  onGrant={setScope}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/permission-grant",
+  "mdUrl": "/docs/components/permission-grant.md",
+  "jsonUrl": "/r/components/permission-grant.json",
+  "specimens": [
+    {
+      "title": "PermissionGrant",
+      "group": "elements",
+      "components": [
+        "PermissionGrant"
+      ],
+      "code": "<Specimens>\n  {SCOPES.map((scope) => (\n    <Specimen key={scope} label={scope} wide>\n      <PermissionGrant\n        capability=\"Write show files\"\n        requester=\"Patcher\"\n        reach={REACH}\n        scope={grants[scope] ?? scope}\n        onGrant={grant(scope)}\n      />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "The other half of the loop: granting a capability rather than approving one action. The reach is a list the caller writes, and the limits belong in it, because a grant a reader cannot bound is a grant they cannot give.",
+      "interaction": "the three answers are Deny, this session and Always. Answer any card and it settles into the scope you chose."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/permission-scopes.json

@@ -0,0 +1,184 @@
+{
+  "name": "PermissionScopes",
+  "slug": "permission-scopes",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Approval that says how far it reaches and where that is written down.\n\nEvery product in the study offers a scope at the moment of approval, and\nevery one of them labels it the same static way — `Always allow` — which is\nthe least informative string in an agent UI: it is the only control on the\nscreen whose consequences outlive the conversation, and it says nothing about\nwhat it grants or where the grant goes. So this one writes its own label.\n`Yes, allow Bash(git commit:*) for this project (just you)` names the rule\nand the reach; the line under it names the file, in a sentence, permanently\nvisible.\n\nNothing is shortened. Claude Code elides a long rule and strips the `:*` off\na prefix rule, and both cuts land on the part that says how much is being\ngranted, so the label here wraps instead. When there are more rules than the\nsentence can name, every one of them is listed under the answer — `and 3\nmore` is a count, and a count is not an account.\n\nThe three answers are numbered, and the numbers are real **while focus is\ninside the card**: `1`, `2` and `3` fire whichever answers are rendered,\nbuilt from the same list that draws them, so a card with no always-allow has\n`2` on its deny, and `Escape` denies. The handler is the card's own\n`onKeyDown` and nothing is ever bound to the document, so the keys answer for\na reader who has tabbed to an answer or been handed the card, and for nobody\nelse.\n\nThat is narrower than the reference, and the narrowing is the point. Claude\nCode disables its buttons for 500ms after mount and *then* takes focus, so\nits digits answer from anywhere; this card never claims focus at all, because\na card that arrives mid-sentence and starts answering keystrokes is the bug\nthat delay exists to prevent — and a row in a library cannot know whether the\nreader is halfway through typing `1` into a composer above it. A product that\nwants the digits to answer from anywhere has the information to decide that\nsafely and this element does not: it routes its own key handler to the same\nthree callbacks, or hands the card focus itself with a `ref` and a `tabIndex`\nof its own.\n\nThere is no settled state. An answered permission is not a card any more; the\nrow that survives is the tool call's own, with its status changed. Every\nproduct that modelled approval as an overlay ended up with the bug where the\nnext message hides the answer.",
+  "props": [
+    {
+      "name": "question",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The question, in the words of the thing being asked for: `Run this\ncommand?`, `Edit this file?`. One step up in size, as the reference sets\nit: it is the only sentence on the card that has to be read.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "subject",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The file, host or command the question is about, set in mono beside it.\nOmit for a question that names its own subject.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "input",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The exact input the call would run with, drawn in a recessed mono box —\nthe command, the patch, the URL. Shown verbatim and never parsed.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "rules",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": "[]",
+      "description": "The rules a standing grant would write, exactly as they will be written.\nThe always-allow answer's label is built from these; when there are more\nthan the label can name, all of them are listed under it.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "ruleKind",
+      "type": "\"directory\" | \"rule\"",
+      "required": false,
+      "defaultValue": "rule",
+      "description": "Whether `rules` are rules or directories, which changes the phrasing.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "directory",
+          "rule"
+        ]
+      }
+    },
+    {
+      "name": "scopes",
+      "type": "readonly PermissionScope[]",
+      "required": false,
+      "defaultValue": "[]",
+      "description": "Where a standing grant can be written, in the order they are offered.\n**No scopes means no always-allow answer**: a permanent grant that cannot\nsay where it is saved is not one this element will offer.",
+      "control": {
+        "kind": "array"
+      }
+    },
+    {
+      "name": "scope",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which scope is chosen, by `id`. Defaults to the first. Claude Code\npersists this choice across prompts and so should a console — which is why\nit is a prop here rather than state: this element never remembers anything.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onScopeChange",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the next scope's `id` when the destination is cycled.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onAllowOnce",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Yes, once. The answer exists only when this is given.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onAlwaysAllow",
+      "type": "((scope: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Yes, and write the rules to the chosen scope — reported by `id`. The\nanswer exists only when this **and** at least one scope are given.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onDeny",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "No. Also what `Escape` does, while focus is inside the card. The answer\nexists only when this is given.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "labels",
+      "type": "Partial<PermissionLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The card's own six strings, merged over `PERMISSION_LABELS`.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Approval that says how far it reaches and where that is written down.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { PermissionScopes, PERMISSION_SCOPE_LABELS } from \"@cueplusplus/ui/elements\";\n\n<PermissionScopes\n  question=\"Run this command?\"\n  subject=\"cue-cli\"\n  input='cue patch --universe 3 --fixtures 6'\n  rules={[\"Bash(cue patch:*)\"]}\n  scopes={[\n    { id: \"session\", label: PERMISSION_SCOPE_LABELS.session, writes: \"Not saved. Gone when this run ends.\" },\n    { id: \"project\", label: PERMISSION_SCOPE_LABELS.project, writes: \"Saves to .cue/settings.local.json (gitignored)\" },\n  ]}\n  scope={scope}\n  onScopeChange={setScope}\n  onAllowOnce={() => allow()}\n  onAlwaysAllow={(id) => remember(id)}\n  onDeny={() => deny()}\n/>\n// No scopes: the card asks, and the only answers are once and no.\n<PermissionScopes question=\"Delete this file?\" subject=\"cues/old.cue\" onAllowOnce={allow} onDeny={deny} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/permission-scopes",
+  "mdUrl": "/docs/components/permission-scopes.md",
+  "jsonUrl": "/r/components/permission-scopes.json",
+  "specimens": [
+    {
+      "title": "PermissionScopes",
+      "group": "elements",
+      "components": [
+        "PermissionScopes"
+      ],
+      "code": "<Specimens>\n  <Specimen label={answered === null ? \"asking\" : `answered: ${answered}`} wide>\n    <div className=\"flex w-full max-w-md flex-col gap-(--cue-space-2)\">\n      <PermissionScopes\n        question=\"Run this command?\"\n        subject=\"cue-cli\"\n        input=\"cue patch --universe 3 --fixtures 6 --start 1\"\n        rules={[\"Bash(cue patch:*)\"]}\n        scopes={SAVES_TO}\n        scope={saveTo}\n        onScopeChange={setSaveTo}\n        onAllowOnce={() => setAnswered(\"once\")}\n        onAlwaysAllow={(id) => setAnswered(`always · ${id}`)}\n        onDeny={() => setAnswered(\"denied\")}\n      />\n      <p className=\"text-(length:--cue-text-label) text-fg-subtle\">\n        last answer: {answered ?? \"none yet\"}\n      </p>\n    </div>\n  </Specimen>\n  <Specimen label=\"one destination, so no choice to make\" wide>\n    <div className=\"w-full max-w-md\">\n      <PermissionScopes\n        question=\"Write this file?\"\n        subject=\"shows/rig.cue\"\n        rules={[\"Write(shows/**)\"]}\n        scopes={[SAVES_TO[0] as PermissionScope]}\n        onAllowOnce={() => {}}\n        onAlwaysAllow={() => {}}\n        onDeny={() => {}}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"four rules, and all four named\" wide>\n    <div className=\"w-full max-w-md\">\n      <PermissionScopes\n        question=\"Read these paths?\"\n        rules={[\"Read(plots/**)\", \"Read(shows/**)\", \"Read(cues/**)\", \"Read(docs/**)\"]}\n        scopes={SAVES_TO}\n        scope=\"everywhere\"\n        onAlwaysAllow={() => {}}\n        onDeny={() => {}}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"one directory, and nowhere to break the line\" wide>\n    <div className=\"w-full max-w-md\">\n      <PermissionScopes\n        question=\"Allow access to this directory?\"\n        rules={[\n          \"/Users/kit/rig/shows/2026_midsummer_transfer_technical_rehearsal_moving_heads\",\n        ]}\n        ruleKind=\"directory\"\n        scopes={SAVES_TO}\n        scope=\"project\"\n        onAlwaysAllow={() => {}}\n        onDeny={() => {}}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"the destination is the long word this time\" wide>\n    <div className=\"flex w-full max-w-md flex-col gap-(--cue-space-2)\">\n      <PermissionScopes\n        question=\"Write this file?\"\n        subject=\"shows/2026_midsummer_transfer_technical_rehearsal_moving_heads.cue\"\n        rules={[\"Write(shows/**)\"]}\n        scopes={SAVES_TO_A_LONG_WAY}\n        scope={savedFar}\n        onScopeChange={setSavedFar}\n        onAlwaysAllow={() => {}}\n        onDeny={() => {}}\n      />\n      <PermissionScopes\n        question=\"Write this file?\"\n        subject=\"shows/2026_midsummer_transfer_technical_rehearsal_moving_heads.cue\"\n        rules={[\"Write(shows/**)\"]}\n        scopes={[SAVES_TO_A_LONG_WAY[1] as PermissionScope]}\n        onAlwaysAllow={() => {}}\n        onDeny={() => {}}\n      />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The one control in an agent UI whose label has to be computed, because what it grants is different every time it appears. `Yes, allow Bash(cue patch:*) for this project (just you)` is written from the rules it would add and the reach it would add them to, and the sentence under it names the file — permanently, not on hover. Nothing is shortened: the reference elides a long rule and strips the `:*` off a prefix rule, and both cuts land on the part that says how far the grant reaches, so this one wraps instead. When there are more rules than the sentence can name, every one of them is listed underneath, because `and 3 more` is a count and a count is not an account. The last card is what that costs: one directory of seventy-seven characters that a line breaker reads as a single word — it would take a hyphen if the name had one, and an underscored path has none — so the sentence breaks mid-path rather than running out of the card. It is also the card where the sentence is the whole account, since a grant naming one directory draws no rule list under it. The card after it moves the long word to the other two caller strings that can carry one — the subject beside the question, and the destination naming the file the grant is written into — and draws the destination both ways: the top card cycles it, so it is a button sized to its own text, and the bottom card has one destination and draws a span. Cycle the top one onto the project and the sentence breaks mid-path instead of leaving the card, which is the whole point of drawing where a permission is saved rather than hiding it behind a hover.",
+      "interaction": "tab into the card and the numbers work — 1, 2, 3 fire whichever answers are rendered, built from the same list that drew them, and Escape denies. They are the card's own keys, not the document's: nothing here answers a digit typed into a composer somewhere above it, and a console that wants them to answer from anywhere routes them there itself. Press the dotted line to move the grant to another destination and watch the answer above it change with it: there is one resolved scope behind the label, the sentence and the callback, so they cannot disagree about what is being granted."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/piano-keyboard.json

@@ -0,0 +1,149 @@
+{
+  "name": "PianoKeyboard",
+  "slug": "piano-keyboard",
+  "group": "midi",
+  "importPath": "@cueplusplus/ui/midi",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A piano keyboard as a range control: drag the markers, or arrow the edges.\n\nPorted from ableton-sync's note-range picker, geometry intact — 16px whites,\n10px blacks over the seams — and rebuilt around three things the original did\nnot have:\n\n1. **The edges are sliders.** The port moved its markers with `mousedown` and\n   a window listener, which means no keyboard, no screen reader and no touch.\n   Here each marker is a `role=\"slider\"` announcing its note by name, so\n   \"set the low end to C2\" is reachable without a pointer.\n2. **The board holds still while you drag.** The window is centred on the\n   selection, so moving an edge moves the window, which moves the note under\n   the cursor — the port's markers slid away from the pointer mid-drag. The\n   window is frozen for the length of a gesture instead.\n3. **It is drawn in console materials, not in white and black.** A photo of a\n   piano inverts in a light theme; a `surface-3` white key and a\n   `--cue-data-ground` black key read the same in both. The information — what\n   is in range, what is sounding — is carried by the accent, which is the only\n   thing here that a theme is allowed to move.",
+  "props": [
+    {
+      "name": "range",
+      "type": "NoteRange",
+      "required": false,
+      "defaultValue": null,
+      "description": "The selected range. Use with `onRangeChange` for a controlled widget.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "defaultRange",
+      "type": "NoteRange",
+      "required": false,
+      "defaultValue": "{ start: 48, end: 72 }",
+      "description": "Initial range for an uncontrolled widget. Defaults to C2–C4.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "onRangeChange",
+      "type": "((range: NoteRange) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the range each edit produces.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "octaves",
+      "type": "number",
+      "required": false,
+      "defaultValue": "3",
+      "description": "How many octaves to draw. Defaults to `3`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "highlight",
+      "type": "readonly number[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Notes sounding right now, painted solid.",
+      "control": {
+        "kind": "array",
+        "fixture": "chart.series"
+      }
+    },
+    {
+      "name": "keyHeight",
+      "type": "number",
+      "required": false,
+      "defaultValue": "48",
+      "description": "White-key height in px at the 16px root, emitted as `rem`. Defaults to `48`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Note range",
+      "description": "What the range is *of*. Names the group and both markers. Defaults to `\"Note range\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "readout",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Print the range and its size under the board. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse every edit. The board still draws.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onChange\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-data-ground",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-sunken",
+    "--cue-surface-3",
+    "--cue-text-micro"
+  ],
+  "summary": "A piano keyboard as a range control: drag the markers, or arrow the edges.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PianoKeyboard range={range} onRangeChange={setRange} highlight={sounding} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/piano-keyboard",
+  "mdUrl": "/docs/components/piano-keyboard.md",
+  "jsonUrl": "/r/components/piano-keyboard.json",
+  "specimens": [
+    {
+      "title": "PianoKeyboard",
+      "group": "midi",
+      "components": [
+        "PianoKeyboard"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <PianoKeyboard\n    range={range}\n    onRangeChange={setRange}\n    octaves={4}\n    label=\"Trigger range\"\n  />\n  <span className=\"font-mono text-(length:--cue-text-micro) text-fg-subtle\">\n    {noteName(range.start)} to {noteName(range.end)}\n  </span>\n  <PianoKeyboard\n    octaves={2}\n    highlight={[60, 64, 67]}\n    keyHeight={56}\n    readout={false}\n    label=\"Chord highlight\"\n  />\n  <PianoKeyboard octaves={2} disabled label=\"Keyboard, disabled\" />\n</div>",
+      "note": "Exact key geometry from the shared layout module, in-range tinting, and draggable start and end markers.",
+      "interaction": "each marker is a `role=slider` that announces the note it sits on, so the drag is a fast path rather than the only path."
+    }
+  ],
+  "todo": true
+}