@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/model-picker.json

@@ -0,0 +1,76 @@
+{
+  "name": "ModelPicker",
+  "slug": "model-picker",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The full list rather than the rail: grouped by family, priced, with what each one\ncan do.",
+  "props": [
+    {
+      "name": "models",
+      "type": "readonly PickableModel[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every model on offer. Families are derived from the entries and keep their\nfirst-seen order."
+    },
+    {
+      "name": "selectedId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which model is active."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a model is picked."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"models\" | \"selectedId\" | \"onSelect\"\n> & {\n  /**\n   * Every model on offer. Families are derived from the entries and keep their\n   * first-seen order.\n   */\n  models: readonly PickableModel[];\n  /** Which model is active. */\n  selectedId: string;\n  /** Called when a model is picked. */\n  onSelect?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "The full list rather than the rail: grouped by family, priced, with what each one can do.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ModelPicker } from \"@cueplusplus/ui/elements\";\n\n<ModelPicker models={models} selectedId={selectedId} onSelect={setSelectedId} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/model-picker",
+  "mdUrl": "/docs/components/model-picker.md",
+  "jsonUrl": "/r/components/model-picker.json",
+  "specimens": [
+    {
+      "title": "ModelPicker",
+      "group": "elements-composer",
+      "components": [
+        "ModelPicker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two families\" wide>\n    <ModelPicker models={PICKABLE} selectedId={pickedModel} onSelect={setPickedModel} />\n  </Specimen>\n  <Specimen label=\"one family, nothing chosen\" wide>\n    <ModelPicker models={PICKABLE.slice(0, 3)} selectedId=\"\" />\n  </Specimen>\n</Specimens>",
+      "note": "The full list rather than the rail: grouped by family, priced, and carrying what each one can actually do. This is the screen `ComposerModelTrigger` is a shortcut to, and the split is the point — the toolbar menu is for switching between models you already chose between, and this is where that choosing happens.",
+      "interaction": "each row is `aria-pressed`, which is the honest role for a control that stays chosen rather than performing an action once."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/node-card.json

@@ -16,7 +16,7 @@
     },
     {
       "name": "state",
-      "type": "\"idle\" | \"selected\" | \"disabled\" | \"live\"",
+      "type": "\"disabled\" | \"idle\" | \"selected\" | \"live\"",
       "required": false,
       "defaultValue": null,
       "description": "What the node is doing right now. Outranks `tone`.\n\nPass React Flow's own `selected` through:\n`state={selected ? \"selected\" : \"idle\"}`."

package/manifest/components/node-handle.json

@@ -11,7 +11,7 @@
   "props": [
     {
       "name": "tone",
-      "type": "\"accent\" | \"danger\" | \"busy\" | \"muted\" | \"ok\" | \"warn\" | \"info\"",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"muted\" | \"ok\" | \"warn\" | \"info\"",
       "required": false,
       "defaultValue": "accent",
       "description": "What the connection carries. Defaults to `\"accent\"`."

package/manifest/components/number-ticker.json

@@ -0,0 +1,61 @@
+{
+  "name": "NumberTicker",
+  "slug": "number-ticker",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Digits that roll into place as a count updates in real time.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Numeric value whose digits roll into place as it changes."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Mono caption rendered under the rolling number."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"value\" | \"label\"> & {\n  /** Numeric value whose digits roll into place as it changes. */\n  value: number;\n  /** Mono caption rendered under the rolling number. */\n  label: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-text-title"
+  ],
+  "summary": "Digits that roll into place as a count updates in real time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { NumberTicker } from \"@cueplusplus/ui/elements\";\n\n<NumberTicker value={1284} label=\"tokens / sec\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/number-ticker",
+  "mdUrl": "/docs/components/number-ticker.md",
+  "jsonUrl": "/r/components/number-ticker.json",
+  "specimens": [
+    {
+      "title": "NumberTicker",
+      "group": "elements-knowledge",
+      "components": [
+        "NumberTicker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"channels patched\">\n    <NumberTicker value={48} label=\"channels patched\" />\n  </Specimen>\n  <Specimen label=\"a larger figure\">\n    <NumberTicker value={22300} label=\"lumens\" />\n  </Specimen>\n</Specimens>",
+      "note": "A count that rolls rather than jumps: each digit is a column of ten sliding into place, so 47 to 48 moves one wheel and leaves the other alone. The whole figure is announced once as text, which is what keeps ten rolling columns from being read out as ten numbers.",
+      "interaction": "none. The columns translate on a long ease and stop moving entirely under reduced motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/onboarding.json

@@ -0,0 +1,84 @@
+{
+  "name": "Onboarding",
+  "slug": "onboarding",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "First run: three moves that teach what this assistant is actually for.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "readonly OnboardingStep[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "What to teach, in order. Three is usually the limit before it is skipped."
+    },
+    {
+      "name": "index",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which step is showing. The final step's action reads Start instead of Next."
+    },
+    {
+      "name": "onNext",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to advance."
+    },
+    {
+      "name": "onSkip",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to dismiss. Always offer it."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"steps\" | \"index\" | \"onNext\" | \"onSkip\"\n> & {\n  /** What to teach, in order. Three is usually the limit before it is skipped. */\n  steps: readonly OnboardingStep[];\n  /** Which step is showing. The final step's action reads Start instead of Next. */\n  index: number;\n  /** Called to advance. */\n  onNext?: () => void;\n  /** Called to dismiss. Always offer it. */\n  onSkip?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "First run: three moves that teach what this assistant is actually for.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Onboarding } from \"@cueplusplus/ui/elements\";\n\n<Onboarding steps={steps} index={index} onNext={next} onSkip={skip} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/onboarding",
+  "mdUrl": "/docs/components/onboarding.md",
+  "jsonUrl": "/r/components/onboarding.json",
+  "specimens": [
+    {
+      "title": "Onboarding",
+      "group": "elements-composer",
+      "components": [
+        "Onboarding"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"walking it\" wide>\n    <Onboarding\n      steps={ONBOARDING}\n      index={step}\n      onNext={() => setStep((current) => Math.min(current + 1, ONBOARDING.length - 1))}\n      onSkip={() => setStep(0)}\n    />\n  </Specimen>\n  <Specimen label=\"last step\" wide>\n    <Onboarding steps={ONBOARDING} index={ONBOARDING.length - 1} />\n  </Specimen>\n</Specimens>",
+      "note": "First run: three moves that teach what this assistant is actually for, each with a prompt you could send verbatim. Showing beats describing, which is why every step carries an example rather than a screenshot. The dots are the progress and the final step's action reads `Start` instead of `Next`, so the end of the tour is visible from the second step.",
+      "interaction": "skip is always offered and always in the same place — a tour with no way out is a modal wearing a card."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/otp-field.json

@@ -28,13 +28,6 @@
       "defaultValue": null,
       "description": "Accessible name for the field. Names the group *and*, through a visually\nhidden `<label>`, the first slot — the ARIA pattern for a code field. Leave\nit off inside a {@link Field }, which supplies a real label."
     },
-    {
-      "name": "size",
-      "type": "\"sm\" | \"md\" | \"lg\"",
-      "required": false,
-      "defaultValue": "md",
-      "description": "Rung of the control ladder. Defaults to `\"md\"`."
-    },
     {
       "name": "separator",
       "type": "ReactNode",
@@ -42,6 +35,13 @@
       "defaultValue": "–",
       "description": "What sits between groups. Defaults to `\"–\"`. Always `aria-hidden`."
     },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
     {
       "name": "length",
       "type": "number",

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/popover.json

@@ -85,7 +85,7 @@
         },
         {
           "name": "side",
-          "type": "\"left\" | \"right\" | \"top\" | \"bottom\" | \"inline-end\" | \"inline-start\"",
+          "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
           "required": false,
           "defaultValue": null,
           "description": "Preferred side of the trigger. Defaults to `\"bottom\"`."

package/manifest/components/prompt-library.json

@@ -0,0 +1,99 @@
+{
+  "name": "PromptLibrary",
+  "slug": "prompt-library",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Prompts you saved, searchable, with their variables shown before you insert one.",
+  "props": [
+    {
+      "name": "prompts",
+      "type": "readonly SavedPrompt[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Everything saved. Filtering happens inside against the name."
+    },
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current search text."
+    },
+    {
+      "name": "selectedId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which prompt is previewed below the list."
+    },
+    {
+      "name": "onQueryChange",
+      "type": "((query: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the search is typed."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a prompt is highlighted."
+    },
+    {
+      "name": "onInsert",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called on double click, to drop the prompt into the composer."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"prompts\"\n  | \"query\"\n  | \"selectedId\"\n  | \"onQueryChange\"\n  | \"onSelect\"\n  | \"onInsert\"\n> & {\n  /** Everything saved. Filtering happens inside against the name. */\n  prompts: readonly SavedPrompt[];\n  /** Current search text. */\n  query: string;\n  /** Which prompt is previewed below the list. */\n  selectedId: string;\n  /** Called as the search is typed. */\n  onQueryChange?: (query: string) => void;\n  /** Called when a prompt is highlighted. */\n  onSelect?: (id: string) => void;\n  /** Called on double click, to drop the prompt into the composer. */\n  onInsert?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Prompts you saved, searchable, with their variables shown before you insert one.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { PromptLibrary } from \"@cueplusplus/ui/elements\";\n\n<PromptLibrary\n  prompts={prompts}\n  query={query}\n  selectedId={selectedId}\n  onQueryChange={setQuery}\n  onSelect={setSelectedId}\n  onInsert={insert}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/prompt-library",
+  "mdUrl": "/docs/components/prompt-library.md",
+  "jsonUrl": "/r/components/prompt-library.json",
+  "specimens": [
+    {
+      "title": "PromptLibrary",
+      "group": "elements-composer",
+      "components": [
+        "PromptLibrary"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"browsing\" wide>\n    <PromptLibrary\n      prompts={PROMPTS}\n      query={promptQuery}\n      selectedId={promptId}\n      onQueryChange={setPromptQuery}\n      onSelect={setPromptId}\n      onInsert={setPromptId}\n    />\n  </Specimen>\n  <Specimen label=\"nothing matches\" wide>\n    <PromptLibrary prompts={PROMPTS} query=\"haze\" selectedId=\"\" />\n  </Specimen>\n</Specimens>",
+      "note": "Prompts somebody saved, searchable, with the holes in them counted before you insert one — `3 vars` is the difference between a prompt you can send and a template you still have to fill. The preview underneath is the whole body, because a prompt library that hides the prompt is a list of file names.",
+      "interaction": "arrows walk the list and Enter inserts; a row also inserts on double-click, so the mouse has the same two gestures the keyboard does. An empty result says what it found nothing for rather than showing an empty box."
+    }
+  ],
+  "todo": true
+}