@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/permission-grant.json

@@ -0,0 +1,92 @@
+{
+  "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."
+    },
+    {
+      "name": "requester",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Who is asking."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "scope",
+      "type": "\"pending\" | \"always\" | \"denied\" | \"session\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "pending shows the choices; anything else shows the settled outcome."
+    },
+    {
+      "name": "onGrant",
+      "type": "((scope: GrantScope) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the scope the user chose."
+    }
+  ],
+  "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,139 @@
+{
+  "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "ruleKind",
+      "type": "\"directory\" | \"rule\"",
+      "required": false,
+      "defaultValue": "rule",
+      "description": "Whether `rules` are rules or directories, which changes the phrasing."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "onScopeChange",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the next scope's `id` when the destination is cycled."
+    },
+    {
+      "name": "onAllowOnce",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Yes, once. The answer exists only when this is given."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "labels",
+      "type": "Partial<PermissionLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The card's own six strings, merged over `PERMISSION_LABELS`."
+    }
+  ],
+  "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,120 @@
+{
+  "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."
+    },
+    {
+      "name": "defaultRange",
+      "type": "NoteRange",
+      "required": false,
+      "defaultValue": "{ start: 48, end: 72 }",
+      "description": "Initial range for an uncontrolled widget. Defaults to C2–C4."
+    },
+    {
+      "name": "onRangeChange",
+      "type": "((range: NoteRange) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the range each edit produces."
+    },
+    {
+      "name": "octaves",
+      "type": "number",
+      "required": false,
+      "defaultValue": "3",
+      "description": "How many octaves to draw. Defaults to `3`."
+    },
+    {
+      "name": "highlight",
+      "type": "readonly number[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Notes sounding right now, painted solid."
+    },
+    {
+      "name": "keyHeight",
+      "type": "number",
+      "required": false,
+      "defaultValue": "48",
+      "description": "White-key height in px at the 16px root, emitted as `rem`. Defaults to `48`."
+    },
+    {
+      "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\"`."
+    },
+    {
+      "name": "readout",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Print the range and its size under the board. Defaults to `true`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse every edit. The board still draws."
+    }
+  ],
+  "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
+}

package/manifest/components/plussie.json

@@ -0,0 +1,111 @@
+{
+  "name": "Plussie",
+  "slug": "plussie",
+  "group": "brand",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Plussie, the CUE++ character — the mark, with its eyes free to move.\n\nThe same circle and the same two \"+\" glyphs {@link CueMark } draws, out of the\nsame geometry module, because they are the same drawing: the mark's glyphs\n*are* the character's eyes. What this adds is that the eyes are their own\ngroups, so an `expression` can slide or shut them.\n\nStatic-first. The eight Remotion animations this character was rigged for\nstay in the site that renders video; a heavy, video-oriented peer has no\nbusiness in a component library, so what is ported here is the geometry and\nthe poses. Everything else a caller wants — a look that follows the cursor, a\nblink on a timer of their own — is a `expression` prop away, driven by their\nown runtime.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "expression",
+      "type": "\"default\" | \"blink\" | \"wink\" | \"look-left\" | \"look-right\" | \"look-up\" | \"look-down\"",
+      "required": false,
+      "defaultValue": "default",
+      "description": "Which pose to hold. Defaults to `\"default\"`, eyes open and level.\n\nEvery pose is a still from the character's own animations rather than a\nnew drawing, so a screen that holds one and a video that plays through it\nagree."
+    },
+    {
+      "name": "idle",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Blink every few seconds, on a CSS keyframe. Defaults to `false`.\n\nOff by default because a mark that moves in the corner of the eye is a\ndistraction on a console screen, and off again for a reader who has asked\nfor reduced motion — the rule that drives it is inside a\n`prefers-reduced-motion` guard, so there is no state to keep and nothing to\nturn off a second time.\n\nIt composes with `expression`: a winking Plussie blinks its open eye."
+    },
+    {
+      "name": "size",
+      "type": "number | BrandSize",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density control ladder to draw at, or an explicit height in px.\nDefaults to `\"md\"`.\n\nHeight, always — every asset here keeps its own aspect ratio, so the width\nfollows from the artwork rather than from the caller."
+    },
+    {
+      "name": "tone",
+      "type": "\"inherit\" | \"fg\" | \"accent\"",
+      "required": false,
+      "defaultValue": "inherit",
+      "description": "Where the ink comes from: `currentColor`, the foreground token, or the\naccent. Defaults to `\"inherit\"`."
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible name.\n\nOmit it and the asset is decorative — `aria-hidden`, announced by nothing.\nPass one only when the mark is the *only* thing naming what it sits on: a\nbare logo link, a splash screen with no heading."
+    }
+  ],
+  "typeReferences": [
+    "BrandAssetProps"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg"
+  ],
+  "summary": "Plussie, the CUE++ character: the mark with its eyes free to move.",
+  "examples": [
+    {
+      "title": "An empty state",
+      "code": "import { Plussie } from \"@cueplusplus/ui\";\n\n<div className=\"flex flex-col items-center gap-(--cue-space-4)\">\n  <Plussie size={96} expression=\"look-down\" />\n  <p>No cues yet.</p>\n</div>;",
+      "language": "tsx"
+    },
+    {
+      "title": "With the optional idle blink",
+      "code": "<Plussie size={96} idle title=\"Plussie\" />;",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Plussie size=\"lg\" title=\"Plussie\" />\n<Plussie expression=\"wink\" tone=\"accent\" />\n<Plussie size={96} idle />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/plussie",
+  "mdUrl": "/docs/components/plussie.md",
+  "jsonUrl": "/r/components/plussie.json",
+  "whenToUse": [
+    "An empty state, an onboarding step, an error page — somewhere a screen has room for a face.",
+    "A long-running job's companion, where `expression` says what the job is doing without a second sentence.",
+    "Anywhere you would have embedded the character's video and only needed one frame of it."
+  ],
+  "whenNotToUse": [
+    "In dense console chrome. A face in a toolbar is a distraction; use `CueMark`.",
+    "As a loading indicator. Use `Spinner` or `Progress`, which announce themselves.",
+    "For an animation with a script. The eight rigged animations live in the site that renders video, and this library will not take Remotion as a peer."
+  ],
+  "commonMistakes": [
+    "Inventing a pose by nudging the eyes with CSS. Every value `expression` holds is a still from a real animation, and a hand-tuned one will not match the video.",
+    "Turning `idle` on across a page. It is off by default because a mark moving in the corner of the eye is a distraction, and it is off again under `prefers-reduced-motion`.",
+    "Expecting `expression` to animate between poses. It sets a pose; transitions belong to the caller."
+  ],
+  "specimens": [
+    {
+      "title": "Plussie",
+      "group": "brand",
+      "components": [
+        "Plussie"
+      ],
+      "code": "<Specimens>\n  {EXPRESSIONS.map((expression) => (\n    <Specimen key={expression} label={expression}>\n      <Plussie size={56} expression={expression} />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`}>\n      <Plussie size={size} />\n    </Specimen>\n  ))}\n  <Specimen label=\"tone accent\">\n    <Plussie size={56} tone=\"accent\" expression=\"wink\" />\n  </Specimen>\n  <Specimen label=\"idle\">\n    <Plussie size={56} idle title=\"Plussie\" />\n  </Specimen>\n</Specimens>",
+      "note": "The same circle and the same two '+' the mark draws, out of the same geometry module, with the eyes in their own groups so a pose can move them. Every pose is a still from one of the character's own animations.",
+      "interaction": "none by default. Pass `idle` for a CSS-only blink, which stops for a reader who has asked for reduced motion."
+    }
+  ]
+}