{ "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "pixeldosa", "homepage": "https://pixeldosa.akshayjayan.com", "items": [ { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "activity-trail", "title": "Activity Trail", "description": "What the agent did, why it was allowed to, and what came of it. Takes `entries` (each with a pre-formatted `time`, an `actor` of `agent`, `person` or `system` with an `actorName`, an `action` phrased as its consequence, an optional `target`, an `authority` line naming what permitted it, a `result`, and `undoable`), plus `onUndo` and `onExport`. The `authority` field is the one audit logs leave out and the one people actually ask about: \"who let it do that?\" — an approval, an autonomy level, a schedule someone set. Compliance logging is becoming mandatory for high-risk systems under the EU AI Act, with months of retention expected in regulated industries, but those records are built for auditors; this is the readable version for the person whose inbox the agent used, and `onExport` hands the same records to your compliance process so the two never drift apart. Purely presentational. Use it under a run, in an agent's settings, or on a record the agent touched. Not a developer event log, and not a chat transcript.", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/activity-trail/activity-trail.tsx", "target": "components/ui/activity-trail.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. Write `action` as the consequence (\"Emailed the summary to 3 people\"), never as a function name.", "meta": { "engineeringNotes": "Entries are newest last, the order a story is read in, rather than the newest-first order of a log — this surface is meant to be reconstructed rather than monitored, and reversing it makes causation read backwards. `authority` is a required-shaped optional: nothing enforces it, but its absence in a row is visible, which pushes teams to record what permitted an action at the moment they render it rather than reconstructing it later from three systems. Undo is per entry and driven by the caller's `undoable` flag, because only the caller knows whether a specific action is still reversible; the component never infers reversibility from the action's words. Export exists so the human-readable trail and the compliance record come from one array instead of two implementations that disagree.", "motionNotes": "Nothing animates. Every row describes something that already happened, and this system reserves motion for a machine that is still busy; an entry that slid or faded in would imply the record was still being written. Only the standard instant colour change on Undo, dropped under `prefers-reduced-motion`.", "schema": { "component": "ActivityTrail", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ActivityTrail", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "title": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/$defs/TrailEntry" }, "description": "Newest last, the way a person reads a story." }, "exportLabel": { "type": "string" }, "emptyLabel": { "type": "string" } }, "required": [ "entries" ], "$defs": { "TrailEntry": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "string", "description": "Formatted by you: \"14:02\", \"Yesterday 09:15\". Never recomputed here." }, "actor": { "enum": [ "agent", "person", "system" ] }, "actorName": { "type": "string", "description": "Who exactly: \"Research agent\", \"Dana\", \"Scheduler\"." }, "action": { "type": "string", "description": "The consequence, in the user's words: \"Emailed the summary to 3 people\"." }, "target": { "type": "string", "description": "What it touched: a file, a record, a recipient list." }, "authority": { "type": "string", "description": "Why it was allowed to do this: \"You approved it\", \"Autonomy: acts on low-risk\nthings\", \"Scheduled by Dana\". The question every log leaves out." }, "result": { "type": "string", "description": "What came of it: \"Sent\", \"3 rows changed\", \"No matches\"." }, "undoable": { "type": "boolean", "description": "Set when this specific action can still be reversed." } }, "required": [ "id", "time", "actor", "action" ] } } }, "events": [ { "name": "onUndo", "required": false, "params": [ { "name": "id", "type": "string" } ] }, { "name": "onExport", "required": false, "params": [], "description": "Hands the whole trail to your export: CSV, JSON, a compliance system." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-ask", "title": "Agent Ask", "description": "A structured question from an agent that needs input before it can continue — the UI surface for MCP elicitation. Takes a targeted `question`, a required `source` naming who is asking, a `fields` array describing what is needed (`text`, `number`, `confirm`, or `select` with concrete options and hints), an optional `explanation` giving the context that makes the question answerable, and three separate outcomes: `onRespond` with the collected values, `onDecline` to refuse this particular question and continue without the information, and `onCancel` to abandon the whole operation. Decline and cancel are deliberately distinct answers rather than one dismiss action, and both are rendered as visible first-class controls rather than hidden behind an overflow. `source` is required rather than optional because MCP's elicitation specification obliges a client to show which server is requesting input — 'some software wants your data' is not a question a user can safely answer without knowing the asker. The component prefers concrete options over free text: a select renders as labelled radio cards with optional hints, and a confirm renders as explicit Yes/No controls, because a question with buttons is answerable in a second where the same question in a text box is a small piece of homework. Submit stays disabled until every required field is answered. Holds perfectly still, since it is the user's turn under the system's turn-taking grammar — pair it with Agent Presence in the `asking` state. Purely presentational: it does not call a model and does not own the paused run. Use it for disambiguation between plausible matches and for missing parameters the agent cannot safely guess. Not for approving a consequential action the agent has already decided on (use AI Approval Gate), and not for a general chat input.", "type": "registry:ui", "categories": [ "ai-assisted", "forms", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/agent-ask/agent-ask.tsx", "target": "components/ui/agent-ask.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. MCP's elicitation spec requires that a client show which server is asking and offer both decline and cancel — `source` is therefore a required prop, and you should wire `onDecline` and `onCancel` rather than omitting them, even though the component tolerates their absence for non-MCP uses.", "meta": { "engineeringNotes": "Three decisions separate this from a chat prompt asking the same question. First, provenance is a required prop rather than an optional nicety: MCP obliges a client to show which server is requesting input, and it is also the only basis a user has for judging whether the question is safe to answer at all. Second, refusal is modelled as two distinct outcomes instead of one dismissal — declining answers 'not this information' while cancelling answers 'not this operation', and collapsing them would silently convert a narrow refusal into an abort. Third, the field types deliberately bias toward concrete options: `select` renders as labelled radio cards carrying optional hints (the disambiguation case, which is what elicitation is mostly used for, is far better served by 'Q3 Revenue Final.xlsx — edited 3 days ago' than by a text box), and `confirm` renders explicit Yes/No buttons rather than a checkbox, since a checkbox's unchecked state is ambiguous between 'no' and 'not answered'. That ambiguity matters here because submit is gated on required fields actually being answered. The component deliberately does not compose AI Action Toolbar for its actions despite the system's compose-don't-reinvent rule: the primary control is a real form submit button, and wrapping form submission inside a `role=\"toolbar\"` would misreport the semantics to assistive technology for the sake of visual consistency. Text inputs are 16px on small viewports because anything smaller makes iOS Safari zoom the page on focus.", "motionNotes": "Almost none, and that is the design. This is a user-turn surface under the turn-taking grammar (DESIGN.md §3a), which means it holds perfectly still — the absence of motion is precisely what signals that nothing proceeds until the user acts, and animating it would put it back in the same visual register as the machine's own busy states. The only motion present is the shared colour transition on hover, press and focus at `--pd-duration-instant`, matching every other control in the system, and it is dropped entirely under `prefers-reduced-motion` while the selected-state border and background still communicate which option is chosen. Entrance animation belongs to whatever surface reveals this component, not to the component itself — the same rule Confidence Meter and AI Action Toolbar hold.", "schema": { "component": "AgentAsk", "element": "form", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentAsk", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "question": { "type": "string", "description": "The actual question. Targeted and answerable — never \"can you provide more information?\"." }, "source": { "type": "string", "description": "Who is asking. Required, not optional: MCP's elicitation spec obliges a client to\nshow which server is requesting input, because \"some software wants your data\" is\nnot a question a user can safely answer without knowing the asker." }, "fields": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "const": "text" }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "type", "label" ] }, { "type": "object", "properties": { "name": { "type": "string" }, "type": { "const": "number" }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "type", "label" ] }, { "type": "object", "properties": { "name": { "type": "string" }, "type": { "const": "confirm" }, "label": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "type", "label" ] }, { "type": "object", "properties": { "name": { "type": "string" }, "type": { "const": "select" }, "label": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/$defs/AskFieldOption" } }, "required": { "type": "boolean" } }, "required": [ "name", "type", "label", "options" ] } ] } }, "explanation": { "type": "string", "description": "Why it's asking. Short context that makes the question answerable." }, "submitLabel": { "type": "string" } }, "required": [ "question", "source", "fields" ], "$defs": { "AskFieldOption": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "value", "label" ] } } }, "events": [ { "name": "onRespond", "required": true, "params": [ { "name": "values", "type": "Record" } ] }, { "name": "onDecline", "required": false, "params": [], "description": "Answer refused, continue without it. Distinct from cancelling the run." }, { "name": "onCancel", "required": false, "params": [], "description": "Abandon the whole operation. MCP requires this be offered alongside decline." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-console", "title": "Agent Console", "description": "The screen a person comes back to after leaving agents running, assembled from Run Inbox, Agent Plan, Activity Trail, Human Handoff and Agent Schedule. Takes a `briefing` (what changed since they were last here, as counts plus one sentence of what to do first), `runs` for the inbox, a `detail` for the selected run (its steps, its trail, and a handoff when a person is involved), and optional `triggers` for what runs on its own. The briefing is the design: two products shipped agent dashboards this year, and the part still treated as an afterthought is the return itself — research on agentic interfaces puts the moment someone comes back after four hours as where trust is won or lost, and says it should read as a briefing rather than a list the user reconstructs one from. Beneath it the inbox groups by what a run needs rather than when it happened, and the detail answers the two questions people actually ask: where did it get to, and who let it do that. Presentational: you own the runs, the selection and the history. Use it as the home screen of a product that runs background or scheduled agents. Not for a single agent run inside a chat — that is Thinking Experience.", "type": "registry:block", "categories": [ "ai-assisted", "application", "block" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme", "@pixeldosa/run-inbox", "@pixeldosa/agent-plan", "@pixeldosa/activity-trail", "@pixeldosa/human-handoff", "@pixeldosa/agent-schedule" ], "files": [ { "path": "../../packages/ui/src/registry/agent-console/agent-console.tsx", "target": "components/blocks/agent-console.tsx", "type": "registry:block" } ], "docs": "Requires `cn` at `@/lib/utils`. Write `briefing.nextUp` as the one thing worth doing first, not a summary — it is the sentence that has to survive being read on a phone at a bus stop. Times and counts are formatted by you.", "meta": { "engineeringNotes": "The briefing sits above everything and is written in words rather than badges, because the failure of a returned-to surface is that it hands back a pile and makes the person do the triage that the system already has the data to do. It turns the waiting colour only when something actually needs a person, so the colour means the same thing here as it does on a single approval. Zero is stated rather than hidden: 'Nothing changed while you were away' is a useful answer, and an empty space is not. The two-pane split puts the inbox at a fixed width and the detail fluid, because the detail is where the reading happens; the selected row is marked with `aria-current` as well as a background, so the pairing survives without colour. A person being involved is rendered above the machine's account of itself — the handoff comes before the plan and the trail — since a run waiting on somebody is not primarily a story about what the agent did.", "motionNotes": "Motion means the machine is busy, and a console is where that rule earns its keep: on a screen showing six runs, a plan, a trail and three schedules at once, only genuinely running things move — a running row's dot, a running step's mark. Everything waiting on a person is completely still in the waiting colour, so the eye lands on the one place work is actually happening and the stillness of everything else is itself information. The briefing never animates; a summary that moves reads as still arriving. Under `prefers-reduced-motion` every part of that stops and each state is carried by colour, position and words.", "schema": { "component": "AgentConsole", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentConsole", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4 ], "description": "Level of the console's own headings. Defaults to 2, to sit under a page `h1`." }, "briefing": { "$ref": "#/$defs/ConsoleBriefing", "description": "What changed since the user was last here. The return moment, in four numbers." }, "runs": { "type": "array", "items": { "$ref": "#/$defs/AgentRun" }, "description": "Every run, grouped by what it needs." }, "selectedId": { "type": "string" }, "inboxEmptyLabel": { "type": "string" }, "detail": { "$ref": "#/$defs/ConsoleRunDetail", "description": "The selected run, opened out." }, "detailEmptyLabel": { "type": "string", "description": "Shown when nothing is selected." }, "triggers": { "type": "array", "items": { "$ref": "#/$defs/ScheduleTrigger" }, "description": "When the agent runs on its own. Omit the section entirely by leaving this out." } }, "required": [ "runs" ], "$defs": { "ConsoleBriefing": { "type": "object", "properties": { "since": { "type": "string", "description": "When the user was last here, in words: \"since yesterday at 6pm\"." }, "needsYou": { "type": "number", "description": "Counts of what changed while they were away. Zero is fine and says so." }, "finished": { "type": "number" }, "failed": { "type": "number" }, "nextUp": { "type": "string", "description": "The one thing worth doing first, in a sentence." } }, "required": [ "needsYou", "finished", "failed" ] }, "AgentRun": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "description": "What it was asked to do, in the user's words." }, "state": { "enum": [ "needsYou", "running", "scheduled", "done", "failed" ] }, "agent": { "type": "string", "description": "Which agent, if you run more than one." }, "note": { "type": "string", "description": "Why it needs you, what it's doing, or what it produced. One line." }, "time": { "type": "string", "description": "Formatted by you: \"2 minutes ago\", \"Tomorrow at 9:00\"." }, "unread": { "type": "boolean", "description": "Not looked at yet." } }, "required": [ "id", "title", "state" ] }, "ConsoleRunDetail": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "description": "What was asked for, in the user's words." }, "steps": { "type": "array", "items": { "$ref": "#/$defs/PlanStep" }, "description": "Where the run got to. Each step carries its own status." }, "runStatus": { "type": "string", "description": "What's happening right now, beside the progress count." }, "trail": { "type": "array", "items": { "$ref": "#/$defs/TrailEntry" }, "description": "What the agent did, who allowed it, and what came of it." }, "handoff": { "type": "object", "properties": { "stage": { "enum": [ "agentHandling", "waitingForPerson", "personHandling", "returnedToAgent" ] }, "reason": { "type": "string" }, "context": { "type": "array", "items": { "$ref": "#/$defs/HandoffFact" } }, "person": { "type": "string" }, "waitingFor": { "type": "string" } }, "required": [ "stage" ], "description": "Present only when a person is involved, or is being asked to be." } }, "required": [ "id", "title" ] }, "PlanStep": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "needsApproval": { "type": "boolean", "description": "The step has an external effect and will stop for approval when it runs." }, "status": { "enum": [ "running", "done", "failed", "pending", "waiting", "skipped" ] }, "note": { "type": "string", "description": "What happened, for a step that's running, waiting, failed or skipped." } }, "required": [ "id", "title" ] }, "TrailEntry": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "string", "description": "Formatted by you: \"14:02\", \"Yesterday 09:15\". Never recomputed here." }, "actor": { "enum": [ "agent", "person", "system" ] }, "actorName": { "type": "string", "description": "Who exactly: \"Research agent\", \"Dana\", \"Scheduler\"." }, "action": { "type": "string", "description": "The consequence, in the user's words: \"Emailed the summary to 3 people\"." }, "target": { "type": "string", "description": "What it touched: a file, a record, a recipient list." }, "authority": { "type": "string", "description": "Why it was allowed to do this: \"You approved it\", \"Autonomy: acts on low-risk\nthings\", \"Scheduled by Dana\". The question every log leaves out." }, "result": { "type": "string", "description": "What came of it: \"Sent\", \"3 rows changed\", \"No matches\"." }, "undoable": { "type": "boolean", "description": "Set when this specific action can still be reversed." } }, "required": [ "id", "time", "actor", "action" ] }, "HandoffFact": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "description": "\"Customer\", \"Order\", \"Tried already\"." }, "value": { "type": "string" } }, "required": [ "id", "label", "value" ] }, "ScheduleTrigger": { "type": "object", "properties": { "id": { "type": "string" }, "when": { "type": "string", "description": "When it runs, in plain words: \"Every weekday at 9:00\", \"When an invoice arrives\nfrom a new supplier\". Never a cron string." }, "does": { "type": "string", "description": "What it will do, phrased as the consequence." }, "enabled": { "type": "boolean" }, "nextRun": { "type": "string", "description": "Formatted by you: \"Tomorrow at 9:00\". Left out when it's off." }, "lastRun": { "type": "string", "description": "How the last one went: \"Ran yesterday · 3 invoices matched\"." }, "lastFailed": { "type": "boolean", "description": "Set when the last run had a problem, so an off-schedule failure is visible." }, "asksFirst": { "type": "boolean", "description": "Set when a run of this will pause for approval." } }, "required": [ "id", "when", "does", "enabled" ] } } }, "events": [ { "name": "onSelect", "required": true, "params": [ { "name": "id", "type": "string" } ] }, { "name": "onStopRun", "required": false, "params": [ { "name": "id", "type": "string" } ] }, { "name": "onStopSelected", "required": false, "params": [] }, { "name": "onRetryStep", "required": false, "params": [ { "name": "stepId", "type": "string" } ] }, { "name": "onUndo", "required": false, "params": [ { "name": "entryId", "type": "string" } ] }, { "name": "onExportTrail", "required": false, "params": [] }, { "name": "onTakeOver", "required": false, "params": [] }, { "name": "onReturnToAgent", "required": false, "params": [] }, { "name": "onTriggerEnabledChange", "required": false, "params": [ { "name": "id", "type": "string" }, { "name": "enabled", "type": "boolean" } ] }, { "name": "onRunTriggerNow", "required": false, "params": [ { "name": "id", "type": "string" } ] }, { "name": "onEditTrigger", "required": false, "params": [ { "name": "id", "type": "string" } ] } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-figure", "title": "Agent Figure", "description": "A hand-drawn agent character whose pose shows what a run is doing, how sure it is, and when it needs the person. Takes a `pose` from a fourteen-value vocabulary: work poses (`listening`, `thinking`, `planning`, `searching`, `reading`, `comparing`, `working`), hand-off poses (`idle`, `asking`, `blocked`, `done`), and three result poses (`confident`, `probable`, `unsure`) that must be driven by the system's real confidence. `variant` is `figure` (the whole character) or `mark` (the head alone, for inline status and avatars); `size` is `sm`, `md` or `lg`. A visible `label` sits beside or below the figure by default, because the words are the real signal; `hideLabel` turns the drawing into a labelled image instead, and `announce` adds a polite live region. Motion follows the turn-taking grammar: on the agent's turn the pen lines re-draw slightly (a line boil) and small parts move in steps; on the person's turn every line holds still. Drawn in code as seeded SVG strokes, coloured only by theme tokens (ink, card, muted ink and the four agent markers), so it themes, stays small and renders identically on server and client. Use it for onboarding, empty states, run panels and consumer products where an agent should feel present. Not a replacement for status text (pair it with Live Status Line or a label), and not for dense tables — use Agent Presence's `line` form there.", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/agent-figure/agent-figure.tsx", "target": "components/ui/agent-figure.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils` and the agent marker colours (`--agent-working`, `--agent-waiting`, `--agent-blocked`, `--agent-done` and their `-soft` fills) from @pixeldosa/pixeldosa-theme.", "meta": { "engineeringNotes": "The character is generated, not illustrated: each stroke is a polyline pushed off its true path by a seeded wobble and smoothed with Catmull-Rom curves. Seeds come from the pose, the stroke name and the frame, so the server and client render byte-identical paths and there is no hydration mismatch, and a new pose costs a few coordinates rather than an asset. Every colour is a theme token, so the figure follows light and dark mode and a host's palette. Poses map to things a run actually does, never to feelings: 'blocked' is a state, 'sad' is not, and the three result poses exist so confidence can be shown honestly rather than always looking pleased. The frame clock runs only while the pose is on the agent's turn, the figure is on screen (IntersectionObserver), and the tab is visible; otherwise nothing ticks.", "motionNotes": "Two kinds of motion, both stepped at 280ms rather than eased, so the figure reads as drawn rather than rendered: the line boil (strokes re-seed every second frame) and a few discrete prop movements — eyes scanning a page, a key press, the thought bubble filling in. Both stop completely when the pose is the person's turn (`idle`, `asking`, `blocked`, `done` and the result poses), which is the system's rule that stillness means it's your turn. `still` holds the lines on the agent's turn too. Under `prefers-reduced-motion` nothing animates and each pose remains a distinct static drawing, so no information is lost.", "schema": { "component": "AgentFigure", "element": "span", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentFigure", "type": "object", "properties": { "pose": { "enum": [ "done", "idle", "listening", "thinking", "planning", "searching", "reading", "comparing", "working", "asking", "blocked", "confident", "probable", "unsure" ] }, "variant": { "enum": [ "figure", "mark" ], "description": "`figure` is the whole character; `mark` is the head alone, for inline status and avatars." }, "size": { "enum": [ "sm", "md", "lg" ] }, "label": { "type": "string", "description": "What the pose means, in words. Defaults to the pose's own label. Read by assistive\ntechnology, and shown beside the figure unless `hideLabel` is set." }, "hideLabel": { "type": "boolean" }, "labelPosition": { "enum": [ "end", "below" ], "description": "Where the visible label sits." }, "announce": { "type": "boolean", "description": "Announce label changes through a polite live region. Off by default: most products\nalready announce status elsewhere (Live Status Line, Agent Presence), and two\nchannels saying the same thing is worse than one." }, "still": { "type": "boolean", "description": "Hold the pen lines still even while the agent is busy." } }, "required": [ "pose" ] }, "events": [] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-memory", "title": "Agent Memory", "description": "What an agent remembers about someone, where they can read it, correct it, or make it forget. Takes `memories`, each with `text`, an `origin` of 'stated' (the user said it) or 'inferred' (the agent picked it up) and an optional `source` ('Noticed across 6 conversations'). Handlers are `onEdit`, `onForget`, and optionally `onRestore`, `onForgetAll`, plus `paused` with `onPausedChange`. What the user said and what the agent guessed are listed separately, and inferred memories are framed as guesses worth checking, because a wrong inference quietly skews every later answer. Edits happen inline (Enter saves, Escape cancels). Forget fires immediately, while the row stays in place, struck through, with Undo, and focus moves to it. Pausing is described exactly: it stops new memories and doesn't erase old ones. Forget all needs a second confirming step that says it can't be undone. Use it in agent settings or a 'what do you know about me' panel. Not a chat history or a data export.", "type": "registry:ui", "categories": [ "ai-assisted", "forms", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/agent-memory/agent-memory.tsx", "target": "components/ui/agent-memory.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. `onForget` should really delete. The component keeps its own copy for Undo. When a user edits an inferred memory, store it as `stated`, because they have now said it.", "meta": { "engineeringNotes": "Built around the difference between stated and inferred memory. From the model side, an inferred preference that is wrong is worse than no memory, because it shapes answers without the user ever seeing why. So origin is a required field, the two kinds are listed in separate sections (the inferred list has a dashed border and reads 'Guesses from how you work'), and each memory can carry its source. Forgetting is honest about timing. `onForget` fires at once, so the caller can really delete it, and the component keeps a local snapshot with the original position so the row stays in place, struck through, with Undo. Focus moves to Undo after a forget and back to Forget after a restore, so keyboard users never lose their place. Pausing uses a real `role=\"switch\"`, and its note says exactly what pausing does and doesn't do, because 'paused' is widely misread as 'deleted'. Forget all is the only irreversible action. It opens an inline confirmation with focus on Cancel and uses the destructive intent. A polite live region announces forgets and restores by content.", "motionNotes": "Still, apart from direct feedback. It is the user's turn, so nothing moves unless the user acts. The pause switch thumb slides and its track colour changes at `--pd-duration-fast` on the standard curve. Hover colour changes run at `--pd-duration-instant`. Forgetting doesn't collapse or fade the row. It swaps to its struck-through state instantly and keeps its height, so the list doesn't shift under the pointer and Undo appears exactly where the user clicked. Everything is instant under prefers-reduced-motion.", "schema": { "component": "AgentMemory", "element": "div", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentMemory", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "memories": { "type": "array", "items": { "$ref": "#/$defs/MemoryItem" } }, "paused": { "type": "boolean", "description": "Whether new things are being remembered. Pausing never forgets what's already here." } }, "required": [ "memories" ], "$defs": { "MemoryItem": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string", "description": "One remembered thing, in plain words: \"Prefers metric units\"." }, "origin": { "enum": [ "stated", "inferred" ], "description": "`stated` — the user said it. `inferred` — the agent picked it up from how they work." }, "source": { "type": "string", "description": "Where it came from: \"From your chat on 3 Sep\", \"Noticed across 4 conversations\"." } }, "required": [ "id", "text", "origin" ] } } }, "events": [ { "name": "onEdit", "required": true, "params": [ { "name": "id", "type": "string" }, { "name": "text", "type": "string" } ] }, { "name": "onForget", "required": true, "params": [ { "name": "id", "type": "string" } ], "description": "Called immediately. Forget for real — the component keeps its own copy for Undo." }, { "name": "onRestore", "required": false, "params": [ { "name": "memory", "type": "MemoryItem" } ], "description": "Enables Undo on a forgotten row. Receives the memory as it was." }, { "name": "onForgetAll", "required": false, "params": [] }, { "name": "onPausedChange", "required": false, "params": [ { "name": "paused", "type": "boolean" } ] } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-plan", "title": "Agent Plan", "description": "An agent's plan laid out for agreement before anything runs — the user can reorder steps, remove one, or add their own, then run the plan as edited. The same component follows the run: give each step a `status` (`pending`, `running`, `waiting`, `done`, `failed`, `skipped`) and an optional `note`, and editing gives way to progress — the running step is marked and moves, a step waiting on the user holds still in the waiting colour, finished steps get a check, a failed step offers `onRetryStep`, `runStatus` names what's happening now, and `onStop` stays visible for the whole run. Takes `steps` (each with a `title`, optional `detail`, and an optional `needsApproval` flag for steps with external effects), an optional `title`, `onRun`, which receives the final ordered steps, an optional `onCancel`, and `allowAdd` to permit user-added steps. Steps that will stop for approval are labelled 'Asks for approval', and the header counts them, so the user knows before running where the agent will pause. Removing a step never deletes it outright: it stays in place struck through with an Undo, because a plan edit that cannot be seen or reversed is exactly the silent change the system exists to prevent. Reordering uses explicit move-up and move-down controls rather than drag, so it works identically by keyboard, touch and pointer, and every edit is announced through a live region. The run button reads 'Run edited plan' once anything changed. Plans are where an agent's misunderstanding becomes visible while it is still free to fix — once execution starts, a wrong step costs a tool call, a side effect, or a cancel and restart. This component is the agreement; execution belongs to Task Plan Runner. Composes AI Action Toolbar. Holds still, since it is the user's turn. Use it before multi-step runs, especially ones that touch external systems. Not for showing progress through a running plan.", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme", "@pixeldosa/ai-action-toolbar" ], "files": [ { "path": "../../packages/ui/src/registry/agent-plan/agent-plan.tsx", "target": "components/ui/agent-plan.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. Mark any step with an external effect as `needsApproval` so the user sees where the run will pause before it starts. This component does not execute steps — it hands the agreed plan to `onRun`.", "meta": { "engineeringNotes": "Separates agreeing on a plan from executing it, because the two need opposite designs: agreement is a still, editable surface where the user is in control, while execution is a moving status surface where the machine is. Merging them produces the common pattern where a plan is shown only as it starts running, which is too late to change it cheaply. Removal is modelled as a reversible state rather than a deletion — the step remains in place, struck through, numbered out of the sequence, with Undo — so an edit is always visible and never destructive. Reordering deliberately uses explicit up and down buttons instead of drag and drop: drag is pointer-first, hard to make accessible, and ambiguous on touch, while buttons behave identically across every input method and announce the resulting position through a live region (counting only steps that remain). The icon buttons are 32 pixels with hit areas extended vertically to 44, not horizontally, because the three controls sit side by side and overlapping hit areas would turn a near-miss into the wrong edit. Steps flagged `needsApproval` are labelled and counted in the header, so where the run will pause is known before it starts rather than discovered during it. The running view lives in this component rather than a separate runner because the plan people agreed to is the thing they want to watch; a second surface would make them re-read a list they had already accepted. The switch is derived, not configured: the first step carrying a status past `pending` ends editing, so a caller cannot show edit controls over a plan that is already executing. Progress is counted from finished steps, never an invented percentage, and each step announces itself once as its status changes, tracked against the previous value so a re-render with unchanged statuses stays silent.", "motionNotes": "Still, as a user-turn surface: nothing moves on its own and nothing shimmers. Removed steps drop to reduced opacity with a strikethrough rather than animating out, so an edit reads as a changed state instead of a disappearance and remains reversible in place. Reordering changes position immediately without a sliding animation — a swap that animates on every press would slow repeated keyboard moves and add motion to what is a precise, deliberate edit. The remaining motion is the shared colour transition on hover and focus at `--pd-duration-instant`, which drops to instant under prefers-reduced-motion. In the running view only the current step moves: its mark pulses on the working colour. A step waiting on the person holds completely still in the waiting colour, which is the turn-taking grammar applied per row instead of per panel. The progress bar animates its width over `--pd-duration-slow` because it tracks a real, discrete change, and under reduced motion the pulse stops while colour and words continue to carry every state.", "schema": { "component": "AgentPlan", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentPlan", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "steps": { "type": "array", "items": { "$ref": "#/$defs/PlanStep" }, "description": "The agent's proposed plan, in order." }, "title": { "type": "string" }, "allowAdd": { "type": "boolean", "description": "Let the user add their own steps." }, "runStatus": { "type": "string", "description": "Shown while the plan runs, beside the progress count — the one thing happening right\nnow, in the caller's words (\"Reading pricing pages\")." } }, "required": [ "steps" ], "$defs": { "PlanStep": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "needsApproval": { "type": "boolean", "description": "The step has an external effect and will stop for approval when it runs." }, "status": { "enum": [ "running", "done", "failed", "pending", "waiting", "skipped" ] }, "note": { "type": "string", "description": "What happened, for a step that's running, waiting, failed or skipped." } }, "required": [ "id", "title" ] } } }, "events": [ { "name": "onRun", "required": true, "params": [ { "name": "steps", "type": "PlanStep[]" } ], "description": "Runs the plan as the user left it — reordered, trimmed, or extended." }, { "name": "onCancel", "required": false, "params": [] }, { "name": "onStop", "required": false, "params": [], "description": "Shown throughout the run, never hidden behind a hover." }, { "name": "onRetryStep", "required": false, "params": [ { "name": "stepId", "type": "string" } ], "description": "Offered on a failed step." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-presence", "title": "Agent Presence", "description": "An agent's live state, expressed visually rather than described in text. Takes a `state` from an eleven-value vocabulary grounded in real protocol events — eight machine states (`queued`, `thinking`, `deciding`, `working`, `streaming`, `done`, `failed`, `cancelled`) and three hand-off states (`suggesting`, `asking`, `awaitingApproval`) — plus an optional `label` that overrides the state's default text, and an `onCancel` shown throughout the machine's turn. The organising rule is a turn-taking grammar: motion means the machine is busy, stillness means it is the user's turn. Machine states animate; hand-off states stop completely and sit brighter and heavier, so a user learns to read 'am I needed?' without reading a word. The forms share the one vocabulary: `figure` draws the agent with Agent Figure (each state maps to a pose, and person's-turn poses hold still), `mark` draws only its head for inline use, `field` renders a cell matrix, `line` renders three inline dots for status bars and table rows, and the deprecated `orb` (a CSS 3D sphere, kept only so existing screens keep working; use Agent Figure for a visible agent). The text label is the real signal and is announced through an `aria-live` region; the indicator itself is `aria-hidden` and supplementary. Purely presentational: it does not fetch, does not own the agent run, and does not interpret protocol events for you — map your stream's events to a state and pass it in. Use it anywhere an agent's activity needs to be visible in ordinary product UI. Not for showing the reasoning text itself (that is Reasoning Stream), not for a per-artifact generation progress bar (that is Generation Placeholder), and not for the post-result action strip (that is AI Action Toolbar).", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme", "@pixeldosa/agent-figure" ], "files": [ { "path": "../../packages/ui/src/registry/agent-presence/agent-presence.tsx", "target": "components/ui/agent-presence.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`, @pixeldosa/agent-figure for the `figure` and `mark` forms (installed automatically), and the `pd-orb-spin` / `pd-cell-pulse` keyframes supplied by @pixeldosa/pixeldosa-theme's css block. The state vocabulary maps directly onto AG-UI events, OpenAI Responses lifecycle events, AI SDK stream parts, LangGraph interrupts and MCP elicitation — see the docs page for the mapping table.", "meta": { "engineeringNotes": "The load-bearing decision is that the eleven states split into two classes with opposite visual treatments rather than into eleven variations of one treatment. Every surveyed implementation renders 'thinking' and 'waiting for your approval' in the same register — something moving plus a line of text — but those are opposites: one means relax, the other means nothing proceeds until you act. Encoding that as motion-versus-stillness makes the most important question on the surface ('is it my turn?') answerable pre-attentively. The vocabulary itself is taken from protocol events rather than invented: `deciding` exists because AG-UI streams TOOL_CALL_ARGS before execution, so choosing an action is distinguishable from performing it; `queued` exists because OpenAI Responses emits it and accepted-but-not-started is not the same as working; `asking` maps to MCP elicitation and `awaitingApproval` to LangGraph's interrupt(). The orb uses a Fibonacci spiral distribution rather than the flat ring of dots most AI orbs use, which is what makes it read as a volume rather than a circle, and it is rendered with CSS 3D transforms inside a preserve-3d container so perspective supplies depth scaling for free — no per-frame JavaScript and no canvas. All three forms animate via CSS keyframes with per-element negative delays rather than a requestAnimationFrame loop; an earlier component in this system was rebuilt for exactly this reason, since re-rendering hundreds of React nodes per frame to nudge a transform is what makes these indicators stutter.", "motionNotes": "Rotation speed is the state: 24s per revolution when queued, 12s thinking, 7s deciding, 4s working — so the same object communicates urgency through tempo rather than through a different animation per state, which is what lets states morph rather than cut. Terminal machine states (`done`, `failed`, `cancelled`) drop rotation entirely and settle to a smaller resting scale. Hand-off states stop dead: no keyframe is applied at all, and the dots transition to full scale and full opacity over `--pd-duration-slow`, so the arrival of the user's turn is a settling rather than a switch. Only `transform` and `opacity` animate, so every form composites on the GPU regardless of point count. Under `prefers-reduced-motion` every keyframe is disabled and each state still holds a visually distinct static configuration — differing scale and opacity per state — so the grammar survives with zero movement; the reduced-motion state is the same information without the motion, not a removal of the signal.", "schema": { "component": "AgentPresence", "element": "div", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentPresence", "type": "object", "properties": { "state": { "enum": [ "done", "failed", "thinking", "working", "asking", "queued", "deciding", "streaming", "cancelled", "suggesting", "awaitingApproval" ] }, "form": { "enum": [ "figure", "mark", "line", "field", "orb" ] }, "size": { "enum": [ "sm", "lg", "default" ] }, "label": { "type": "string", "description": "Overrides the state's default label. For `working`, name the actual tool." }, "hideLabel": { "type": "boolean", "description": "Hide the text label and show only the indicator. The label is still announced." } }, "required": [ "state" ] }, "events": [ { "name": "onCancel", "required": false, "params": [], "description": "Shown while it is the machine's turn. Never hidden behind a hover." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-schedule", "title": "Agent Schedule", "description": "When the agent runs on its own, in words anyone can check. Takes `triggers` (each a plain-words `when` — \"Every weekday at 9:00\", \"When an invoice arrives from a new supplier\", never a cron string — a `does` line phrased as the consequence, `enabled`, a pre-formatted `nextRun`, a `lastRun` summary with `lastFailed`, and `asksFirst` when a run will stop for approval), plus `onEnabledChange`, `onEdit` and `onRunNow`. Scheduled agents are where trust quietly breaks: the thing that runs at 9:00 every morning is the thing nobody is watching, and a schedule that has been failing for a week usually looks identical to one that is fine. So the last run's outcome sits on the row in the blocked colour when it failed, the next run is stated, and turning a trigger off is one control. Purely presentational: you own the scheduling, and you write the sentences. Use it in an agent's settings, or beside a Run Inbox. Not a cron editor, and not a calendar.", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/agent-schedule/agent-schedule.tsx", "target": "components/ui/agent-schedule.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. Write `when` as a sentence a non-technical colleague could check, and keep the cron expression in your backend.", "meta": { "engineeringNotes": "Every trigger is caller-written prose rather than a structure the component renders into English, which is a deliberate trade: generated sentences from a rule object read fluently for simple cases and become nonsense at the first compound condition, and the person this surface protects is the one who has to verify that the sentence matches what the system does. The failed last run is rendered inline in the blocked colour rather than behind a status filter, because the state this component exists to prevent is a silent schedule failing unnoticed for a week. `asksFirst` is shown on the row so the approval behaviour of an unattended run is visible while it is being switched on, not discovered later. The switch is a real `role=\"switch\"` with an accessible name that includes the trigger's own sentence, so a screen-reader user hears which schedule they are turning off.", "motionNotes": "Only the switch moves, sliding its thumb over `--pd-duration-fast` so flipping one reads as a physical change rather than a repaint. Nothing else animates: this is a settings surface, and a schedule row that pulsed would imply the agent is running right now. Under `prefers-reduced-motion` the slide is dropped and the state is carried by position, colour and the accessible name.", "schema": { "component": "AgentSchedule", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentSchedule", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "title": { "type": "string" }, "triggers": { "type": "array", "items": { "$ref": "#/$defs/ScheduleTrigger" } }, "emptyLabel": { "type": "string" } }, "required": [ "triggers" ], "$defs": { "ScheduleTrigger": { "type": "object", "properties": { "id": { "type": "string" }, "when": { "type": "string", "description": "When it runs, in plain words: \"Every weekday at 9:00\", \"When an invoice arrives\nfrom a new supplier\". Never a cron string." }, "does": { "type": "string", "description": "What it will do, phrased as the consequence." }, "enabled": { "type": "boolean" }, "nextRun": { "type": "string", "description": "Formatted by you: \"Tomorrow at 9:00\". Left out when it's off." }, "lastRun": { "type": "string", "description": "How the last one went: \"Ran yesterday · 3 invoices matched\"." }, "lastFailed": { "type": "boolean", "description": "Set when the last run had a problem, so an off-schedule failure is visible." }, "asksFirst": { "type": "boolean", "description": "Set when a run of this will pause for approval." } }, "required": [ "id", "when", "does", "enabled" ] } } }, "events": [ { "name": "onEnabledChange", "required": true, "params": [ { "name": "id", "type": "string" }, { "name": "enabled", "type": "boolean" } ] }, { "name": "onEdit", "required": false, "params": [ { "name": "id", "type": "string" } ] }, { "name": "onRunNow", "required": false, "params": [ { "name": "id", "type": "string" } ], "description": "Runs one now, without waiting for its schedule." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-steer", "title": "Agent Steer", "description": "Redirect a running agent without stopping it — 'not that file, this one'. Takes `running`, the `currentStep` the agent is on (so a redirect has something to be relative to), a caller-owned `steers` list where each redirect carries a real status — pending (sent, not yet acknowledged), queued (accepted, applies after the current step), applied, or declined with a reason — plus optional `suggestions` that fill the input for editing but never send, `onSteer(text, mode)`, and `onWithdraw(id)` for redirects the agent has not applied yet. Enter steers after the current step; interrupting mid-step is a separate, deliberate control, because stopping a tool call halfway can leave partial side effects. Status is never inferred from the key press: a redirect reads 'waiting for the agent' until the agent says otherwise, so it cannot look applied when it isn't. Use it beside a Live Status Line or Thinking Experience during long runs. Not a replacement for Stop, which stays visible, and not a chat composer.", "type": "registry:ui", "categories": [ "ai-assisted", "forms", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/agent-steer/agent-steer.tsx", "target": "components/ui/agent-steer.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. The steers list is yours: set each status from what the agent actually reports. Keep a Stop control visible next to it — steering is not a replacement for stopping.", "meta": { "engineeringNotes": "Built for the gap between Stop and wait: in real use, people change their minds mid-run, and today's agent UIs make them throw away the work so far to say so. Two decisions carry the trust. First, the component owns no status. Each redirect's status comes from the caller, meaning from the agent: it shows 'Sent — waiting for the agent' until the agent acknowledges, so pressing Enter never makes a redirect look like it has taken effect. Declined redirects show the agent's reason rather than disappearing. Second, the default applies at the next step boundary, where the agent can re-plan cleanly. Interrupting is a separate, secondary control, because abandoning a tool call mid-flight can leave half-written files or half-sent requests, and that risk should be chosen rather than triggered by the Enter key. Redirects that haven't been applied can be withdrawn. Suggestions fill the input rather than sending, so a one-tap redirect is still the user's sentence. The live region announces status changes to the latest redirect in words that match the visible text.", "motionNotes": "Almost still. The agent's motion belongs to the status surface beside it, such as Live Status Line, not to the steer control. The one moving element is the shared `pd-shimmer` on a pending redirect's status. Under the turn-taking grammar that is the only state where work is genuinely happening on the machine's side for that redirect; queued, applied and declined are settled facts and hold still. Colour transitions on hover and focus run at `--pd-duration-instant`, and the shimmer falls back to static text under prefers-reduced-motion and where background-clip text is unsupported.", "schema": { "component": "AgentSteer", "element": "div", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AgentSteer", "type": "object", "properties": { "running": { "type": "boolean", "description": "Whether the agent is working. Steering only exists while there is a run to steer." }, "currentStep": { "type": "string", "description": "What the agent is doing now, so a redirect has something to be relative to." }, "steers": { "type": "array", "items": { "$ref": "#/$defs/SteerMessage" } }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "One-tap redirects that fill the input for editing — never sent without the user." }, "placeholder": { "type": "string" } }, "required": [ "running" ], "$defs": { "SteerMessage": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "mode": { "enum": [ "next", "now" ] }, "status": { "enum": [ "pending", "queued", "applied", "declined" ] }, "note": { "type": "string", "description": "Agent-supplied context: when it will apply, or why it couldn't." } }, "required": [ "id", "text", "mode", "status" ] } } }, "events": [ { "name": "onSteer", "required": true, "params": [ { "name": "text", "type": "string" }, { "name": "mode", "type": "SteerMode" } ] }, { "name": "onWithdraw", "required": false, "params": [ { "name": "id", "type": "string" } ], "description": "Take back a steer the agent hasn't applied yet." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ai-action-toolbar", "title": "AI Action Toolbar", "description": "A keyboard-navigable toolbar of the standard post-generation actions on an AI-produced result — apply, explain, retry, regenerate, undo, report. Takes an `actions` array of `{ id, label, icon?, intent?, disabled?, busy? }` plus a single `onAction(actionId)` callback, and renders them as a row of real buttons with three levels of visual weight: `intent=\"primary\"` is filled (the recommended action, e.g. Apply), `secondary` is bordered (reversible alternatives, e.g. Regenerate), and `quiet` is underline-only (meta actions that don't change the result, e.g. Explain, Report, Undo). An optional `message` renders leading status text before the actions, which is how confirmation rows like 'Changes applied. Undo' are expressed. Implements the ARIA toolbar pattern properly — the whole strip is one tab stop with arrow keys, Home and End moving within it and skipping disabled actions — rather than the natural-tab-order approximation most implementations use. Busy state is a per-action prop owned by the caller, not internal state, so it reflects the caller's real in-flight request; while any action is busy the others disable, since two concurrent actions on one result is never a coherent request. Purely presentational otherwise: it does not fetch, does not own an undo timer, and does not own the result it acts on. Use it attached to any AI output the user must now decide about. Not for a selection-triggered floating toolbar (use Selection Actions), a text diff needing per-hunk accept/reject (use Diff Accept), or a single whole-field proposal (use Smart Field) — this is the shared control strip those patterns compose, not a replacement for them.", "type": "registry:ui", "categories": [ "ai-assisted", "actions", "application" ], "dependencies": [ "class-variance-authority" ], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/ai-action-toolbar/ai-action-toolbar.tsx", "target": "components/ui/ai-action-toolbar.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils` and `class-variance-authority`. No icon set is bundled — pass your own `size-4` icons via each action's optional `icon` prop, matching how Smart Field and Selection Actions already take icons. Exactly one action should carry `intent=\"primary\"`; the component does not enforce this, because a confirmation-only row (a lone quiet Undo) legitimately has none.", "meta": { "engineeringNotes": "An extraction, not new design: three already-shipped components had independently hand-rolled the same control strip. Smart Field renders Retry, Reject/Accept and an 'Value accepted. Undo' row; Diff Accept renders 'Changes applied. Undo' and a Regenerate-on-conflict button; Selection Actions renders Retry and Dismiss. Across those seven call sites exactly three button treatments recur verbatim — filled primary, bordered secondary, underline quiet — along with a character-for-character duplicated spinner SVG and a duplicated message+Undo confirmation row. Those three treatments became the CVA `intent` variants rather than being re-derived a fourth time. Two deliberate boundaries: (1) `busy` is a per-action prop rather than internal state, because every existing call site already holds the request and its AbortController, so owning a second copy here would let the toolbar's idea of 'in flight' drift from the caller's; (2) the undo *timer* stays with the consumer — Smart Field and Diff Accept both already run it inside their own status state machines, and absorbing it here would fight those machines rather than simplify them, so the toolbar renders the undo affordance while the consumer owns when it exists. The roving tabindex is kept as an action id rather than an index so the tab stop survives the actions array changing between renders, and it falls back to the first enabled action whenever the focused one becomes disabled — otherwise a toolbar whose focused action just disabled would have no tab stop at all and become unreachable by keyboard.", "motionNotes": "Deliberately minimal, and the restraint is the decision. Colour-only transitions on hover and focus at `--pd-duration-instant` (100ms) with `--pd-ease-standard`, matching every other control in the system. There is no entrance animation, on purpose: this toolbar is always revealed by a container that already animates — Smart Field's proposal panel owns a grid-template-rows expand, Selection Actions owns a fade-and-scale — so a second entrance here would double-animate the same appearance. That mirrors Confidence Meter's rule that motion belongs to what wraps a primitive, not the primitive itself. The one continuous animation is the busy spinner, which is honest: it maps to a real in-flight request and stops when that request settles. Under prefers-reduced-motion the colour transitions drop to instant via `motion-reduce:transition-none`, while the spinner deliberately keeps rotating — removing it would leave a busy state with no visible indication at all, and the reduced-motion contract is a fallback that preserves legibility, not a removal.", "schema": { "component": "AIActionToolbar", "element": "div", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AIActionToolbar", "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/$defs/AIAction" } }, "message": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" } ] } } ], "x-react": "ReactNode", "description": "Leading status text, e.g. \"Changes applied.\" Renders before the actions." }, "label": { "type": "string", "description": "Accessible name for the toolbar." } }, "required": [ "actions" ], "$defs": { "AIAction": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "icon": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" } ] } } ], "x-react": "ReactNode", "description": "Optional leading icon. No icon set is bundled — pass your own `size-4` icon." }, "intent": { "enum": [ "primary", "secondary", "quiet", "destructive" ], "description": "Visual weight. Exactly one action should be `primary`. Defaults to `secondary`." }, "disabled": { "type": "boolean" }, "busy": { "type": "boolean", "description": "Owned by the consumer, not this component: the caller already holds the request\n(and usually its AbortController), so the toolbar reflects that state rather than\nkeeping a second copy that can drift out of sync with it." } }, "required": [ "id", "label" ] }, "UINode": { "type": "object", "description": "A nested component: a name from this catalogue, and the props to give it.", "required": [ "component" ], "properties": { "component": { "type": "string", "description": "The component's exported name, e.g. \"MediaResult\"." }, "props": { "type": "object", "description": "That component's own props, matching its entry in this catalogue." } } } } }, "events": [ { "name": "onAction", "required": true, "params": [ { "name": "actionId", "type": "string" } ] } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ai-approval-gate", "title": "AI Approval Gate", "description": "A checkpoint before a consequential agent action — the human-in-the-loop surface for LangGraph's interrupt() and any equivalent pause. Takes an `action` phrased as a consequence the user can evaluate ('Send the Q3 summary to 243 contacts', never 'Execute send_email'), a `risk` level, a required `reversible` boolean, an optional `impact` list of countable facts describing the blast radius, optional `confidence` and `provenance`, optional `explanation` and `sources`, and three outcomes: `onApprove`, `onReject` and an optional `onEdit` for when the payload can genuinely be changed before it runs. `reversible` is required rather than optional because whether an action can be taken back is the single most decision-relevant fact on the surface and almost nothing surfaces it; it renders as a plain sentence rather than an icon. A `high` risk action renders its Approve control with the destructive treatment rather than the primary one, so a dangerous action never looks identical to a harmless confirmation. Composes this system's existing trust primitives rather than re-deriving them: Confidence Meter for certainty, AI Context Surface for the reasoning behind the proposal, and AI Action Toolbar for the decision strip — which means the decision controls inherit correct ARIA toolbar semantics, roving tabindex and busy handling for free. Holds perfectly still, since it is the user's turn under the turn-taking grammar; pair it with Agent Presence in the `awaitingApproval` state. Purely presentational: it does not execute the action or own the paused run. Use it before any external side effect — sending messages, spending money, publishing, deleting, or changing permissions. Not for disambiguating between options the agent cannot choose between (use Agent Ask), and not for reviewing a text rewrite hunk by hunk (use Diff Accept).", "type": "registry:ui", "categories": [ "ai-assisted", "actions", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme", "@pixeldosa/ai-action-toolbar", "@pixeldosa/ai-context-surface", "@pixeldosa/confidence-meter" ], "files": [ { "path": "../../packages/ui/src/registry/ai-approval-gate/ai-approval-gate.tsx", "target": "components/ui/ai-approval-gate.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. Installing this pulls in AI Action Toolbar, AI Context Surface and Confidence Meter, which it composes. Phrase `action` as the consequence rather than the tool call — the whole component is worthless if the user cannot evaluate what they are approving.", "meta": { "engineeringNotes": "This is the payoff component for the system's trust thesis, and it is deliberately a composition rather than a new implementation: Confidence Meter, AI Context Surface and AI Action Toolbar are all consumed as-is, which is the 'compose existing trust primitives' rule (DESIGN.md §3.6) applied at the scale it was written for. Composing the toolbar rather than hand-rolling three buttons also means the decision strip inherits the real ARIA toolbar pattern — roving tabindex, arrow navigation, disabled-action skipping, busy handling — none of which a bespoke approval widget would have got right. Building it surfaced a genuine gap in that toolbar: it had no `destructive` intent, because nothing had needed one until an approval could be dangerous. Adding it there rather than special-casing here is the correct direction, since the house rule that a destructive action must never look identical to a harmless primary one applies system-wide. Two content decisions carry most of the value. `reversible` is a required prop rather than an optional flag: whether something can be undone determines how carefully the rest of the surface deserves to be read, and it renders as a plain sentence ('This cannot be undone') rather than an icon, because an icon is exactly the wrong weight for the most consequential fact present. The `impact` list exists because an approval without a scope is a yes/no question with the information removed — '243 recipients' is what makes the decision reviewable, and it uses tabular figures so the numbers align down the column.", "motionNotes": "Deliberately still. This is a user-turn surface under the turn-taking grammar (DESIGN.md §3a): motion means the machine is busy, and animating an approval gate would put it in the same visual register as the agent's own working states — precisely backwards, since nothing here proceeds until the user acts. The only motion is inherited: the composed AI Action Toolbar's colour transitions on hover and focus at `--pd-duration-instant`, and its busy spinner while an approve or reject is in flight, which maps to a real request rather than decorating a wait. AI Context Surface brings its own grid-template-rows disclosure transition when expanded. Nothing animates on entrance — that belongs to whatever surface reveals this gate, the same rule Confidence Meter and AI Action Toolbar hold. Under prefers-reduced-motion every inherited transition drops to instant and the component loses nothing, because it never carried information in movement to begin with.", "schema": { "component": "AIApprovalGate", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AIApprovalGate", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "action": { "type": "string", "description": "What will happen, in consequence terms the user can evaluate — \"Send the Q3\nsummary to 243 contacts\", never \"Execute send_email\"." }, "risk": { "enum": [ "low", "medium", "high" ] }, "reversible": { "type": "boolean", "description": "Whether this can be taken back. Stated plainly because it is the single most\ndecision-relevant fact on the surface, and almost nothing surfaces it." }, "impact": { "type": "array", "items": { "$ref": "#/$defs/ApprovalImpact" }, "description": "The blast radius as countable facts. This is what makes the action reviewable." }, "confidence": { "enum": [ "low", "medium", "high" ] }, "provenance": { "type": "string" }, "explanation": { "type": "string", "description": "Passed through to AI Context Surface — why the agent proposed this." }, "sources": { "type": "array", "items": { "$ref": "#/$defs/ProvenanceSource" } }, "busy": { "enum": [ "approve", "reject" ], "description": "Which action is in flight, owned by the caller as everywhere else in this system." } }, "required": [ "action", "reversible" ], "$defs": { "ApprovalImpact": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] }, "ProvenanceSource": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } }, "required": [ "label" ] } } }, "events": [ { "name": "onApprove", "required": true, "params": [] }, { "name": "onReject", "required": true, "params": [] }, { "name": "onEdit", "required": false, "params": [], "description": "Offer only when the action's payload is genuinely editable before it runs." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ai-chat-experience", "title": "AI Chat Experience", "description": "A complete assistant conversation, orchestrated from shipped PixelDosa UI components: Message Scroller, Message, Prompt Composer, Suggestions, Code Block, Reasoning Stream, Tool Call Group, Inline Citations, Agent Presence and AI Action Toolbar. Takes `turns` as data. Each turn has a `role`, `text` (fenced code becomes Code Blocks) or custom `content`, and for assistant turns a caller-owned `status`, `reasoning`, `toolCalls`, `sources`, `suggestions` and `error`. Handlers are `onSend`, `onStop`, `onRetry`, `onContinue`, `onRegenerate` and `onApplyCode`, with an optional `renderText` for your markdown renderer, an `empty` state with starter suggestions, composer `controls` and attachments. The value is the orchestration a team would otherwise re-derive. Only one busy signal shows at a time: Agent Presence until reasoning or a tool call appears, then that trace, then the streaming cursor once text arrives. Reasoning stops streaming when the answer starts. Send becomes Stop exactly while the latest turn streams, and the composer stays editable. Follow-ups show only on the latest finished answer, and in `fill` mode they land in the composer. Unclosed code fences stream safely. Finished answers are announced once. Failed and stopped turns keep their content with Retry or Continue. Use it as the main assistant screen of a product.", "type": "registry:block", "categories": [ "ai-assisted", "application", "block" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme", "@pixeldosa/message", "@pixeldosa/message-scroller", "@pixeldosa/prompt-composer", "@pixeldosa/suggestions", "@pixeldosa/code-block", "@pixeldosa/reasoning-stream", "@pixeldosa/tool-call-card", "@pixeldosa/inline-citations", "@pixeldosa/agent-presence", "@pixeldosa/ai-action-toolbar", "@pixeldosa/agent-figure" ], "files": [ { "path": "../../packages/ui/src/registry/ai-chat-experience/ai-chat-experience.tsx", "target": "components/blocks/ai-chat-experience.tsx", "type": "registry:block" } ], "docs": "Requires `cn` at `@/lib/utils`. Installs the whole chat stack it composes. Keep `turns` in your state and update the latest assistant turn as your stream reports reasoning, tool calls, text and completion. Pass your markdown renderer as `renderText`.", "meta": { "engineeringNotes": "A Block, so an orchestration rather than new UI: every element is an existing component, and the contribution is the rules for combining them. Busy signals are exclusive. `presenceFor` shows Agent Presence only in the gaps where nothing else reports progress (before reasoning or tools exist, or between the last tool and the first token). A streaming reasoning trace or running tool call already says what is happening, and once text exists the Message's quantized cursor takes over, because two simultaneous 'working' indicators read as noise and make neither trustworthy. Reasoning is forced to stop streaming once answer text arrives, regardless of what the reasoning data says, since a ticking trace under a streaming answer misreports what the model is doing. `busy` derives from the latest assistant turn alone, so Send becomes Stop for exactly that window. The composer is controlled by the block, which lets a `fill` suggestion write into it while the user keeps editing during a stream. Suggestions render only on the latest assistant turn in 'done' status, and older turns' suggestions are hidden, so stale follow-ups never compete with current ones. Text goes through `splitCodeFences`, so an unclosed fence streams as a Code Block. Screen reader announcements are derived by diffing each turn's previous status: a transition out of 'streaming' produces one message (replied with a summary, failed, or stopped) and never a token stream. Turn data is plain objects, so it maps from any runtime (AI SDK, LangGraph, a custom SSE stream) without a dependency.", "motionNotes": "Inherited, not invented. The block adds no motion of its own. Agent Presence's line form moves while the agent thinks or works. Reasoning Stream and Tool Call Group shimmer only their verbs while running. The Message cursor pulses on the shared cell keyframe while text streams. Suggestions arrive with their staggered fade once an answer is done. The Message Scroller follows instantly while pinned and scrolls smoothly only on 'Jump to latest'. Because each part applies the same tokens and the turn-taking grammar, the whole screen has one rhythm: motion while the machine works, stillness when it's the user's turn. Every part handles prefers-reduced-motion itself, so the block needs no separate fallback.", "schema": { "component": "AIChatExperience", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AIChatExperience", "type": "object", "properties": { "turns": { "type": "array", "items": { "$ref": "#/$defs/ChatTurn" } }, "suggestionMode": { "enum": [ "fill", "send" ], "description": "How follow-up suggestions behave. `fill` (default) puts them in the composer." }, "assistantName": { "type": "string" }, "empty": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "suggestions": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "id", "label" ] } ] } } }, "required": [ "title" ], "description": "Shown when there are no turns yet." }, "controls": { "type": "array", "items": { "$ref": "#/$defs/ComposerControl" } }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/ComposerAttachment" } }, "placeholder": { "type": "string" }, "headingLevel": { "enum": [ 2, 3, 4, 5 ], "description": "Level of the empty-state title and of the Sources headings in answers (the title is gone once a conversation exists, so they share the level). Defaults to 2." }, "expression": { "enum": [ "full", "subtle", "off" ], "description": "How much of the agent shows. `full` adds its drawn head as the assistant's avatar,\nwith a face that follows the turn; `subtle` (default) shows the head only beside\n\"Thinking\"; `off` uses plain dots." } }, "required": [ "turns" ], "$defs": { "ChatTurn": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "enum": [ "user", "assistant" ] }, "text": { "type": "string", "description": "Markdown-ish text. Fenced code becomes Code Blocks; the rest goes through `renderText`." }, "content": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" } ] } } ], "x-react": "ReactNode", "description": "Custom content instead of `text` — e.g. an answer marked up with ``." }, "status": { "enum": [ "done", "failed", "streaming", "stopped" ], "description": "Assistant turns. Defaults to \"done\"." }, "error": { "type": "string" }, "reasoning": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "string" } }, "streaming": { "type": "boolean" }, "durationMs": { "type": "number" } }, "required": [ "steps" ] }, "toolCalls": { "type": "array", "items": {} }, "sources": { "type": "array", "items": { "$ref": "#/$defs/CitationSource" }, "description": "Sources behind the answer. Rendered as a reference list; use `content` + `` for inline markers." }, "suggestions": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "id", "label" ] } ] }, "description": "Follow-ups. Only shown on the latest assistant turn, once it's done." } }, "required": [ "id", "role" ] }, "UINode": { "type": "object", "description": "A nested component: a name from this catalogue, and the props to give it.", "required": [ "component" ], "properties": { "component": { "type": "string", "description": "The component's exported name, e.g. \"MediaResult\"." }, "props": { "type": "object", "description": "That component's own props, matching its entry in this catalogue." } } }, "CitationSource": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string", "description": "Who published it: \"Reuters\", \"Internal wiki\", \"Q3 board deck\"." }, "date": { "type": "string" } }, "required": [ "id", "title" ] }, "ComposerControl": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "description": "Short label shown on the pill: \"Tone\", \"Length\", \"For\"." }, "options": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } ] } }, "defaultValue": { "type": "string" } }, "required": [ "id", "label", "options", "defaultValue" ] }, "ComposerAttachment": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "detail": { "type": "string", "description": "e.g. \"PDF · 2.4 MB\"." }, "status": { "enum": [ "failed", "uploading", "ready" ] } }, "required": [ "id", "name" ] } } }, "events": [ { "name": "onSend", "required": true, "params": [ { "name": "submission", "type": "ComposerSubmission" } ] }, { "name": "onStop", "required": false, "params": [] }, { "name": "onRetry", "required": false, "params": [ { "name": "turnId", "type": "string" } ] }, { "name": "onContinue", "required": false, "params": [ { "name": "turnId", "type": "string" } ] }, { "name": "onRegenerate", "required": false, "params": [ { "name": "turnId", "type": "string" } ] }, { "name": "onApplyCode", "required": false, "params": [ { "name": "code", "type": "string" }, { "name": "language", "type": "string | undefined" } ], "description": "Called on Apply in a code block." }, { "name": "renderText", "required": false, "params": [ { "name": "text", "type": "string" } ], "description": "Your markdown renderer. Defaults to paragraphs split on blank lines." }, { "name": "onAttachFiles", "required": false, "params": [ { "name": "files", "type": "File[]" } ] }, { "name": "onRemoveAttachment", "required": false, "params": [ { "name": "id", "type": "string" } ] }, { "name": "onLoadOlder", "required": false, "params": [], "description": "Called near the top of the history." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ai-context-surface", "title": "AI Context / Provenance Surface", "description": "A collapsed-by-default 'Why this?' disclosure showing an AI-produced value's explanation, sources, and model metadata — the folded-together answer to Citation Card, Source Viewer, and Thinking Indicator, none of which make sense without a chat thread. Takes optional explanation (plain-language reasoning text), sources (an array of { label, url?, snippet? }, rendered as a numbered list, each a link when a url is supplied), model (a string name), and generatedAt (a string or Date, formatted as a relative time within 24 hours or an absolute date otherwise). Renders nothing if none of these props are supplied. The trigger is a small, muted button; expanding it reveals a quiet bg-muted panel with the explanation first, sources second, and a model/timestamp footer line last. Use anywhere an AI-influenced value needs transparency available on demand without competing with the content it explains — a Smart Field proposal, a table cell, a classification result from Selection Actions. Not for a full chat/conversation transcript, and not for a single short provenance caption (Smart Field already has its own inline provenance prop for that).", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/ai-context-surface/ai-context-surface.tsx", "target": "components/ui/ai-context-surface.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. `generatedAt` is formatted internally (relative within 24 hours via Intl.RelativeTimeFormat, an absolute locale date otherwise) rather than left to the consumer, since every consumer would otherwise reimplement the same relative-or-absolute decision. Renders `null` entirely when none of `explanation`/`sources`/`model`/`generatedAt` are supplied — a trigger with nothing behind it is worse than no component.", "meta": { "engineeringNotes": "Deliberately a disclosure (collapsed by default), not an always-visible panel: provenance detail is important to have available but wrong to force onto every view, since it would compete with the actual content for attention the moment it's always open — the same restraint Smart Field's inline `via {provenance}` caption already established, applied here at a larger, richer scale. Folds three previously-separate roadmap ideas (Citation Card, Source Viewer, Thinking Indicator) into one component because all three share the same real constraint this system cares about: working with zero chat thread present, unlike Vercel AI Elements' `Reasoning`/citation components, which are chat-message-scoped and excellent at that job specifically — competing with them there would be a bad trade, per the roadmap's own Reconciliation table. Timestamp formatting uses native `Intl.RelativeTimeFormat` rather than a date-formatting dependency, keeping this primitive dependency-free like every other component in the registry.", "motionNotes": "Expand/collapse reuses the same CSS grid-template-rows (0fr to 1fr) technique Smart Field's proposal panel and Diff Accept's conflict banner already use — a proven, token-free way to animate a height that depends on variable content, on --pd-duration-fast/--pd-ease-standard. The trigger's chevron rotates 90 degrees on open using --pd-duration-instant, matching Button's press-feedback timing, since it's an immediate state confirmation rather than content arriving. Under prefers-reduced-motion, both the panel's height transition and the chevron rotation drop via motion-reduce:transition-none, leaving the open/closed state instant but fully legible — aria-expanded already communicates the state to assistive technology regardless of the icon's rotation.", "schema": { "component": "AIContextSurface", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AIContextSurface", "type": "object", "properties": { "explanation": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/$defs/ProvenanceSource" } }, "model": { "type": "string" }, "generatedAt": { "anyOf": [ { "type": "string" }, { "x-type": "Date" } ] }, "triggerLabel": { "type": "string", "description": "Accessible label and visible text for the collapsed trigger." } }, "$defs": { "ProvenanceSource": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } }, "required": [ "label" ] } } }, "events": [] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ai-disclosure", "title": "AI Disclosure", "description": "What the AI did, what it used, and — when it matters — asking first. Two shapes in one component. `variant=\"notice\"` states a fact (\"Written by AI, from your project\") with the specifics one click away, so a label never becomes a wall of policy text; `variant=\"consent\"` asks before anything happens, shows the specifics up front, and gives both answers equal weight: same size, same prominence, nothing preselected, no styling that makes declining look like a mistake. Takes a `title`, a one-sentence `summary`, `facts` as label-and-value pairs (\"What it used\", \"How long it's kept\", \"Who can see it\"), an optional `learnMoreHref`, `onAllow` and `onDecline` for consent, and `onDismiss` for a notice. Purely presentational: it states what you tell it and reports the decision back. Use it on AI-written content, on recording or memory features, and anywhere a person should know or be asked. Not a cookie banner, and not a replacement for AI Approval Gate, which is about one consequential action rather than what the system does in general.", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/ai-disclosure/ai-disclosure.tsx", "target": "components/ui/ai-disclosure.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. Write the `facts` as specifics about this feature, not policy boilerplate.", "meta": { "engineeringNotes": "Notice and consent are one component because they share a sentence, a set of facts and a visual home; splitting them produced two surfaces that drifted apart in wording, which is how products end up disclosing one thing and asking about another. What differs is only what the variant does with the facts: a notice hides them behind a disclosure button so the common case stays a single line, while consent renders them open, because a decision taken without the specifics is not consent and an expander is an easy thing to skip. Both consent buttons carry identical styling by construction rather than by convention — there is no primary variant available to the caller — so a product cannot make \"Allow\" the obvious answer. The consent variant intentionally offers no dismiss: a question you can close is a question that gets closed.", "motionNotes": "Nothing animates in either variant. Consent is the user's turn at its most consequential, and a notice is a statement of fact, so neither has anything to express through motion; the only transitions are the standard instant colour changes on buttons, disabled under `prefers-reduced-motion`.", "schema": { "component": "AIDisclosure", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AIDisclosure", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "variant": { "enum": [ "notice", "consent" ], "description": "`notice` states what happened or is happening. `consent` asks first and nothing\nproceeds until the person answers." }, "title": { "type": "string", "description": "\"Written by AI\", \"This call will be recorded and summarised\"." }, "summary": { "type": "string", "description": "One sentence in the user's words." }, "facts": { "type": "array", "items": { "$ref": "#/$defs/DisclosureFact" }, "description": "The specifics, shown on demand for a notice and up front for consent." }, "learnMoreHref": { "type": "string", "description": "Your policy page." }, "learnMoreLabel": { "type": "string" }, "allowLabel": { "type": "string" }, "declineLabel": { "type": "string" } }, "required": [ "title" ], "$defs": { "DisclosureFact": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "description": "\"What it used\", \"Who can see it\", \"How long it's kept\"." }, "value": { "type": "string", "description": "\"Your last 20 messages in this project.\"" } }, "required": [ "id", "label", "value" ] } } }, "events": [ { "name": "onAllow", "required": false, "params": [], "description": "Consent only. Both answers are equally available; neither is preselected." }, { "name": "onDecline", "required": false, "params": [] }, { "name": "onDismiss", "required": false, "params": [], "description": "Notice only. Lets the reader dismiss it once they've read it." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ai-form-fill", "title": "AI Form Fill", "description": "An agent filling out a form the user is already looking at — the embedded-in-product case rather than a chat. Takes a `fields` array describing each field and how to resolve its proposal, a controlled `values` record with `onValueChange`, an optional `onFill` hook that runs once per request so the whole batch can be fetched in a single round trip, and a required `triggerIcon` since no icon set is bundled. One action proposes values for every field at once, but every field is still reviewed on its own terms: each renders a Smart Field carrying its own confidence tier, provenance caption, explicit accept and reject, and one-step undo. The bulk request is the only thing that is bulk. There is deliberately no 'Accept all' control — per-field review is the entire point of the primitive underneath, and a button that let someone take twelve AI-proposed values in a single click would quietly undo the guarantee the whole AI tier is built on. Composes Smart Field, Field, AI Action Toolbar and Live Status Line, which transitively pulls Confidence Meter and Agent Presence. Fields propose together through a single token the block bumps, so no field gives up ownership of its own proposal state, undo window or in-flight request. Use it for enrichment and autofill inside real product forms — CRM records, onboarding, invoice details. Not for a single field, which is Smart Field used directly, and not for approving a consequential action, which is AI Approval Gate.", "type": "registry:block", "categories": [ "ai-assisted", "forms", "block" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme", "@pixeldosa/smart-field", "@pixeldosa/field", "@pixeldosa/ai-action-toolbar", "@pixeldosa/live-status-line" ], "files": [ { "path": "../../packages/ui/src/registry/ai-form-fill/ai-form-fill.tsx", "target": "components/blocks/ai-form-fill.tsx", "type": "registry:block" } ], "docs": "Requires `cn` at `@/lib/utils`. Installing this pulls in Smart Field, Field, AI Action Toolbar and Live Status Line, plus Confidence Meter and Agent Presence transitively. Fetch the whole batch once in `onFill` and have each field's `fetchProposal` read from that result — otherwise a five-field form makes five round trips for one user action.", "meta": { "engineeringNotes": "The load-bearing decision is what this block refuses to add. Bulk filling makes an 'Accept all' control feel obvious, and it is exactly wrong: Smart Field exists so that a proposed value is reviewed with its confidence and source before it becomes real data, and a single click that accepts twelve values with three different confidence tiers silently discards that. So the request is bulk and the review stays per-field — which is the honest reading of the system's 'nothing commits silently' rule rather than a convenience compromise. Making fields propose together required a small, consumer-driven addition to Smart Field rather than a workaround here: a `proposeToken` prop whose change requests a proposal. The alternatives were worse — remounting each field to re-fire `autoPropose` would have destroyed focus and in-flight requests, and hoisting proposal state into this block would have taken ownership of confidence, undo and abort away from the component that already does all of it correctly. The token deliberately ignores its first render, so mounting fields with a token present is not a request; that keeps unannounced fetching opt-in behind `autoPropose`, which is the posture the AI tier holds. `onFill` exists so the whole batch is one round trip: without it, a five-field form would make five separate model calls for a single user action, which is both slow and expensive in a way the user never asked for.", "motionNotes": "Almost nothing belongs to this block. Every moving part is inherited: Smart Field's proposal panel expands via the house grid-template-rows transition, Live Status Line swaps its status text and carries Agent Presence's indicator, and AI Action Toolbar supplies the fill button's colour transitions and its busy spinner during the batch request. The block itself adds no entrance animation and no motion of its own, which is the correct outcome for a composition — one rhythm, set once in the motion tokens, applied by the parts rather than re-stated by the whole. The one motion decision made here is that the status line appears only while a fill is actually in flight, so the surface is completely still whenever the agent is not working and the user is reviewing. Under prefers-reduced-motion every inherited transition drops to instant and each composed component handles its own fallback.", "schema": { "component": "AIFormFill", "element": "div", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AIFormFill", "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/$defs/FormFillField" } }, "values": { "type": "object", "additionalProperties": { "type": "string" } }, "triggerIcon": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/$defs/UINode" } ] } } ], "x-react": "ReactNode", "description": "No bundled icon set — supply your own `size-4` icon for each field's trigger." }, "fillLabel": { "type": "string" }, "status": { "type": "string" } }, "required": [ "fields", "values", "triggerIcon" ], "$defs": { "FormFillField": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "placeholder": { "type": "string" }, "fetchProposal": { "x-function": true, "x-host": true, "description": "Resolves this field's proposal. Usually reads from one batch the parent fetched." } }, "required": [ "name", "label", "fetchProposal" ] }, "UINode": { "type": "object", "description": "A nested component: a name from this catalogue, and the props to give it.", "required": [ "component" ], "properties": { "component": { "type": "string", "description": "The component's exported name, e.g. \"MediaResult\"." }, "props": { "type": "object", "description": "That component's own props, matching its entry in this catalogue." } } } } }, "events": [ { "name": "onValueChange", "required": true, "params": [ { "name": "name", "type": "string" }, { "name": "value", "type": "string" } ] }, { "name": "onFill", "required": false, "params": [], "description": "Called once per fill request, before the fields propose. Use it to fetch the whole\nbatch in a single round trip — each field's `fetchProposal` then resolves from it." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ai-triage-table", "title": "AI Triage Table", "description": "Reviews many AI-proposed changes at once, organised around where human attention is needed rather than the order the AI produced them. Takes an `items` array of proposed changes — each with a `label`, an optional `before` value, the proposed `after` value, a `confidence` tier and an optional `provenance` — an optional `unchanged` list of things the AI examined and left alone, and an `onApply` callback that receives the ids the user accepted. Changes are grouped by confidence in attention order: low-confidence changes open first because they most need a human, medium follows, and high-confidence changes start collapsed to a count. Items the AI left unchanged collapse to a single line ('40 checked and left unchanged') so nobody scans forty rows to confirm nothing happened. Every row has its own Accept and Reject with a one-step Undo, before values are shown struck through beside the proposed value, and decisions are staged — nothing is written until Apply, which states how many changes it will commit and that unreviewed items stay as they are. It does not become an Accept-all: bulk acceptance exists only for the high-confidence group, and only after that group has been opened; low and medium changes must be decided individually. Composes AI Action Toolbar and Confidence Meter. Use it when AI output arrives in volume — enrichment across many records, bulk categorisation, data cleanup, batch corrections. Not for one field (use Smart Field), a single form (use AI Form Fill), or a text rewrite (use Diff Accept).", "type": "registry:ui", "categories": [ "ai-assisted", "content", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme", "@pixeldosa/ai-action-toolbar", "@pixeldosa/confidence-meter" ], "files": [ { "path": "../../packages/ui/src/registry/ai-triage-table/ai-triage-table.tsx", "target": "components/ui/ai-triage-table.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. Installing this pulls in AI Action Toolbar and Confidence Meter. Pass `unchanged` whenever you have it — showing what the AI deliberately left alone is half of what makes review cheap.", "meta": { "engineeringNotes": "Built in direct response to the audit burden: AI now produces changes faster than people can check them, and every earlier component in this system enables review without reducing it, which at volume turns the user into a full-time auditor. Triage reduces review in three ways. It orders by attention rather than by arrival — low confidence first, high confidence collapsed — so effort lands where errors are likely. It collapses what the AI left unchanged into a count, since confirming that nothing happened is otherwise the most tedious part of reviewing a batch. And it states consequences at the point of commitment ('Apply 5', 'not reviewed will stay as they are'). The hard boundary is that it must not become Accept-all by another name. Bulk acceptance is limited to the high-confidence group, and gated on that group having been opened — tracked as an explicit inspected set, with the reason stated in text rather than hidden behind a disabled button. Decisions are staged rather than committed, so every row's Undo is simply removing a staged decision, with no undo timer to manage. Collapsed groups use the house grid-template-rows pattern with overflow-hidden, and are marked inert while closed: a 0fr row hides content visually but otherwise leaves its buttons focusable and exposed to assistive technology.", "motionNotes": "Deliberately quiet: this is a user-turn surface, so nothing moves on its own and nothing shimmers. Groups expand and collapse through the house grid-template-rows transition at `--pd-duration-fast`, the disclosure chevrons rotate at `--pd-duration-instant`, and a decided row fades to reduced opacity over `--pd-duration-fast` so the eye moves on to what remains without the row disappearing — its Undo stays reachable. Action colours transition through the composed AI Action Toolbar. There is no entrance animation and no motion tied to counts changing, since numbers updating in a review surface should read as information rather than event. Under prefers-reduced-motion every transition drops to instant and the grouping, counts and decided-state opacity still carry all the information.", "schema": { "component": "AITriageTable", "element": "section", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AITriageTable", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "items": { "type": "array", "items": { "$ref": "#/$defs/TriageItem" } }, "unchanged": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "label" ] }, "description": "Items the AI examined and chose not to change. Shown collapsed, so nobody scans for them." }, "title": { "type": "string" } }, "required": [ "items" ], "$defs": { "TriageItem": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "description": "What is being changed — a record, a field, a row." }, "before": { "type": "string", "description": "The current value, shown struck through when present." }, "after": { "type": "string", "description": "The AI's proposed value." }, "confidence": { "enum": [ "low", "medium", "high" ] }, "provenance": { "type": "string" } }, "required": [ "id", "label", "after", "confidence" ] } } }, "events": [ { "name": "onApply", "required": true, "params": [ { "name": "acceptedIds", "type": "string[]" } ], "description": "Commits the accepted items. Nothing is written before this." } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "autonomy-control", "title": "Autonomy Control", "description": "How much an agent may do without asking, as a setting people can actually read. Takes a `level`: 'ask' (propose everything), 'balanced' (handle small reversible things, ask before bigger ones) or 'act' (act, then report). It also takes the agent's real `actions`, each with a `risk` of low, medium or high, and optional `alwaysAsk` ids with `onAlwaysAskChange`. Instead of an abstract cautious-to-autonomous slider, each level is explained through those actions, and every row reads 'Asks first' or 'Does it, tells you', so choosing a level means choosing concrete outcomes. Risk sets a floor the user can raise but never lower: any action can be pinned to 'Always ask', and high-risk actions ask at every level. A live count ('Does 2 of 5 without asking') announces what a level change did. Use it in agent settings and onboarding. Not an approval prompt — that's AI Approval Gate, which this decides when to show.", "type": "registry:ui", "categories": [ "ai-assisted", "forms", "application" ], "dependencies": [], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/autonomy-control/autonomy-control.tsx", "target": "components/ui/autonomy-control.tsx", "type": "registry:ui" } ], "docs": "Requires `cn` at `@/lib/utils`. List real actions in the user's words, and put anything irreversible or external at `risk: \"high\"`. Enforce the same rule server-side: this control shows the policy, it doesn't enforce it.", "meta": { "engineeringNotes": "Research on agent products keeps finding people asking for lower automation and an off switch, while the 'match autonomy to risk' principle has no UI anywhere. Most autonomy settings fail because they are abstract. A slider labelled cautious-to-autonomous doesn't tell anyone what will happen to their inbox. So each level is explained through the agent's actual actions, with the outcome for each in words. The policy is a pure function of level and risk: 'ask' asks for everything, 'balanced' acts only on low risk, 'act' acts on low and medium. High risk asks at every level, and that is deliberately not configurable, because a setting that can turn off the approval for an irreversible send is a trap with a friendly label. User overrides only move in the safe direction: 'Always ask' pins an action to asking, and nothing un-pins the floor. Levels are native radios in a fieldset, so arrow keys, labels and form semantics come for free. The 'Does N of M without asking' count sits in a polite live region, because changing the level silently changes every row below it.", "motionNotes": "Still. This is a settings surface and the user's turn, so nothing animates on its own. Selection and hover change background and border colour at `--pd-duration-instant`. Row outcomes swap text instantly when the level changes, not with a transition, so the new policy can be read the moment it applies. The focus ring follows the radio via `has-[:focus-visible]`. Under prefers-reduced-motion the colour transitions become instant.", "schema": { "component": "AutonomyControl", "element": "div", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AutonomyControl", "type": "object", "properties": { "headingLevel": { "enum": [ 2, 3, 4, 5, 6 ], "description": "Level of the title heading, so it fits the outline of the page it's placed in. Defaults to 3." }, "level": { "enum": [ "ask", "balanced", "act" ] }, "actions": { "type": "array", "items": { "$ref": "#/$defs/AutonomyAction" }, "description": "The agent's real actions. The level is explained through these, not in the abstract." }, "alwaysAsk": { "type": "array", "items": { "type": "string" }, "description": "Action ids the user has pinned to \"Asks first\" regardless of level." }, "label": { "type": "string" } }, "required": [ "level", "actions" ], "$defs": { "AutonomyAction": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string", "description": "A concrete action, in the user's words: \"Send an email\", \"Edit a draft\"." }, "risk": { "enum": [ "low", "medium", "high" ] } }, "required": [ "id", "label", "risk" ] } } }, "events": [ { "name": "onLevelChange", "required": true, "params": [ { "name": "level", "type": "AutonomyLevel" } ] }, { "name": "onAlwaysAskChange", "required": false, "params": [ { "name": "ids", "type": "string[]" } ] } ] } } }, { "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "button", "title": "Button", "description": "A clickable control that triggers an action. Renders a native button element, or any element via the asChild prop when the trigger must be a link. Supports six visual variants (default, secondary, outline, ghost, destructive, link), four sizes including a square icon size, and a loading state that blocks interaction while announcing itself as busy to assistive technology. Use for actions such as submitting, saving or opening a dialog; use a plain anchor for navigation that changes the URL.", "type": "registry:ui", "categories": [ "actions", "forms" ], "dependencies": [ "@radix-ui/react-slot", "class-variance-authority", "clsx", "tailwind-merge" ], "registryDependencies": [ "@pixeldosa/pixeldosa-theme" ], "files": [ { "path": "../../packages/ui/src/registry/button/button.tsx", "target": "components/ui/button.tsx", "type": "registry:ui" } ], "cssVars": { "theme": { "--pd-duration-instant": "100ms", "--pd-ease-standard": "cubic-bezier(0.4, 0, 0.2, 1)" } }, "docs": "Requires `cn` at `@/lib/utils`, which `npx shadcn init` creates. The press-feedback transition reads --pd-duration-instant and --pd-ease-standard; these are installed with this component, and the full token set arrives with the pixeldosa-theme item. When using asChild the rendered child receives aria-disabled rather than the disabled attribute, since non-button elements do not support it — handle click suppression in your own handler if the child is interactive.", "meta": { "engineeringNotes": "Variants are declared with CVA rather than conditional className strings so that the full variant matrix is a single serialisable object: it can be type-derived (VariantProps), documented from source, and extended by consumers via buttonVariants() without forking the component. The loading state disables the button but deliberately keeps it mounted and in the tab order — swapping a button for a spinner element moves focus to the document body mid-interaction, which is the most common accessibility regression in loading buttons. asChild uses Radix Slot instead of a render-prop so that ref forwarding and event composition are handled by the primitive rather than reimplemented here.", "motionNotes": "The only motion is a 2% active-state scale, driven by CSS transition rather than Motion — a button appears dozens of times per page and forcing a JS animation runtime into it would be a bundle cost with no interaction benefit. Duration (instant, 100ms) and easing come from CSS custom properties generated from the motion tokens, so the press feedback stays in step with the rest of the system. The motion solves one problem: confirming that a press registered before the resulting state change lands. Under prefers-reduced-motion the transform is dropped entirely and the state remains legible through the background and focus-ring changes, which is a fallback rather than a silent removal.", "schema": { "component": "Button", "element": "button", "props": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Button", "type": "object", "properties": { "asChild": { "type": "boolean", "description": "Render the child element instead of a `