altitude-design 0.3.2 → 0.4.1

package/dist/guidance/components/CommandPalette/README.md

@@ -0,0 +1,204 @@
+# CommandPalette
+
+Finds and runs anything in the product from one field: the summit, at level 5, opened with ⌘K or Ctrl+K.
+
+**Why the summit.** A command palette takes over the screen for a moment: whatever you were doing waits until you've chosen. That is what level 5 means (focus of the moment), so it sits where Dialog sits and uses the same machinery: the page recedes 1.5% and desaturates, the `scrim` veils it, and the palette rises 16px from 96% scale while its shadow grows from `elev-1` to `elev-5` (`dur-travel-5`). It's anchored 12vh from the top rather than centred, so the field stays put while the results below it grow and shrink. There is one summit: ⌘K does nothing while a Dialog is open, and choosing an item closes the palette before its action runs, so an action may open a Dialog.
+
+**The field is an opening.** It's a real `Input`. An empty query is a hole in the palette with its back wall showing (focus never leaves it, so it never needs the rim a field you tab to gets); the first character raises its floor flush with the palette. Here that floor is `surface-modal`, the surface it sits on, rather than Input's usual `surface-raised`, which in dark schemes is darker than level 5 and would leave a filled query looking sunk.
+
+**Results.** Groups with labels; each row has an icon, a label, an optional description and its shortcut as `Kbd` keys. The letters that matched are drawn in `accent-ink`. One `accent-soft` highlight (`critical-soft` on a destructive item) is carried to the active row on `ease-settle`, as in DropdownMenu.
+
+- **Best match on top.** Items rank by score within their group and groups rank by their best item, so the best match is always the first row and is already active: Enter runs it.
+- **Carried, not reshuffled.** When the results change, rows that stay travel to their new places (FLIP, `dur-travel-2`, `ease-glide`) instead of blinking, and the list's height glides to fit. New rows rise 4px into place, but rises spend attention: only rows near the top rise, at most four begin together (the rest follow 90ms apart), and everything further down cross-fades.
+- **Predicted first.** On opening, items marked `predicted` (or a whole group, such as Recent) are there at once while the rest fade in over `dur-onset` (500ms): ephemeral adaptation, as in DropdownMenu. Once you type, everything shows at once.
+
+**Carrying a query in.** By default the field is empty each time the palette opens. Pass `defaultQuery` to open it on a query (the page's current filter, a deep link), or control it with `query` and `onQueryChange` when something else already holds the text: a persistent search field on the page can open the palette on its first keystroke and hand over what was typed, and a controlled query isn't cleared on opening. Either way the caret lands after the carried text, so typing continues it and the results filter as usual. Focus moves to the palette's field as it rises; keep the outer field controlled by the same state so nothing typed in between is lost. An IME composition in progress can't move between fields, so it ends in the field where it started.
+
+**Keyboard and screen readers.** The field is a `combobox` that controls a `listbox` through `aria-activedescendant` (the WAI-ARIA combobox pattern), so focus stays in the field. ↑ and ↓ move and wrap, Enter chooses, Escape closes, and ⌘K / Ctrl+K toggles. Groups are named by their labels, the active option is `aria-selected`, disabled items are skipped, and the number of results is announced once typing pauses. Focus goes back where it was when the palette closes. Under reduced motion nothing travels; rows fade.
+
+**On touch.** `hints="auto"` (the default) shows the footer, the item shortcuts and the field's esc where there's likely a keyboard, and hides them on a touch-only device until a key is pressed, so a phone's palette isn't crowded with keys it can't press. `true` or `false` forces them. The shortcuts still work either way.
+
+**You provide:** `items`, a list of groups (`label`, `items`, optional `predicted`), each item with a `label` and usually an `icon`, `onSelect`, `shortcut` (display only: bind the key yourself), `keywords` and `description`; `open`/`onOpenChange` when you also open it from a button or a field; `query`/`onQueryChange` or `defaultQuery` when it should open on a query. Optionally `filter` (return 0 to hide, higher to rank nearer the top; `commandScore` is the default), `empty`, `placeholder`, and `shortcut` (another letter, or `false`).
+
+- Do start actions with a verb ("Invite people") and name places plainly ("Northwind").
+- Do mark items `predicted` only when you'd be right most of the time; a wrong prediction costs a moment.
+- Don't render two palettes, and don't open a Sheet from one: one summit, and a level-4 sheet can't sit on it.
+
+The palette and Dialog share one summit per document, including across providers. Its shortcut cannot take an occupied summit. A simultaneous controlled request is rejected with a development warning; set it to `false` before trying again. Rejected requests do not queue. A selected command can close the palette and open a Dialog synchronously: callback ordering is unchanged, the exiting palette retires, and scroll/isolation ownership transfers without unlocking the page. Only the active modal has `aria-modal`; composition Enter and Escape remain with the input method.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`CommandPalette` as first used in its preview:
+
+```tsx
+import { CommandPalette } from 'altitude-design';
+
+<CommandPalette
+  open={open}
+  onOpenChange={onOpenChange}
+  query={text}
+  onQueryChange={setText}
+  items={groups}
+  onSelect={(item) => setLast(item.label)}
+/>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`app`, `bar`, `find`, `grid`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Badge, Card, CommandPalette, Input, Kbd } from 'altitude-design';
+
+const I = {
+  up: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  strokeLinejoin="round"
+>
+  <path d="M7 17L17 7M9 7h8v8" />
+</svg>,
+  folder: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinejoin="round"
+>
+  <path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+</svg>,
+  plus: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+>
+  <path d="M12 5v14M5 12h14" />
+</svg>,
+  user: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+>
+  <circle cx="12" cy="8" r="4" />
+  <path d="M4 20c1.5-4 4.5-6 8-6s6.5 2 8 6" />
+</svg>,
+  key: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  strokeLinejoin="round"
+>
+  <circle cx="8" cy="15" r="4" />
+  <path d="M11 12l9-9M17 6l3 3" />
+</svg>,
+  trash: <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  strokeLinejoin="round"
+>
+  <path d="M4 7h16M9 7V4h6v3M6 7l1 13h10l1-13" />
+</svg>
+};
+const groups = [
+  { label: "Recent", predicted: true, items: [
+    { label: "Deploy to production", icon: I.up, shortcut: ["\u2318", "D"], keywords: ["ship", "release"] },
+    { label: "Open Northwind", icon: I.folder, description: "Marketing site" }
+  ] },
+  { label: "Actions", items: [
+    { label: "New project", icon: I.plus, shortcut: ["\u2318", "N"] },
+    { label: "Invite people", icon: I.user, keywords: ["team", "member"] },
+    { label: "Deploy preview", icon: I.up, description: "main@8dc01b2" },
+    { label: "Delete project\u2026", icon: I.trash, tone: "critical" }
+  ] },
+  { label: "Projects", items: [
+    { label: "Northwind", icon: I.folder, description: "acme.dev" },
+    { label: "Beacon", icon: I.folder, description: "Internal dashboard" },
+    { label: "Cinder", icon: I.folder, description: "API gateway" }
+  ] },
+  { label: "Settings", items: [
+    { label: "Environment variables", icon: I.key, keywords: ["env", "secrets", "dependencies"] },
+    { label: "Billing", icon: I.key, disabled: true }
+  ] }
+];
+const searchIcon = <svg
+  width="16"
+  height="16"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  strokeWidth="1.75"
+  strokeLinecap="round"
+  aria-hidden="true"
+>
+  <circle cx="11" cy="11" r="7" />
+  <path d="M20 20l-3.5-3.5" />
+</svg>;
+export default function App() {
+  const [open, setOpen] = React.useState(true);
+  const [text, setText] = React.useState("");
+  const [last, setLast] = React.useState(null);
+  const onOpenChange = (v) => {
+    setOpen(v);
+    if (!v) setText("");
+  };
+  return <div className="app">
+  <div className="bar">
+    <b>Northwind</b>
+    <Badge tone="positive">Operational</Badge>
+    <Input
+      className="find"
+      aria-label="Search or run a command"
+      placeholder="Search or run a command"
+      value={text}
+      leading={searchIcon}
+      trailing={<span aria-hidden="true"><Kbd>⌘</Kbd><Kbd>K</Kbd></span>}
+      onChange={(e) => {
+    setText(e.target.value);
+    if (e.target.value) setOpen(true);
+  }}
+    />
+  </div>
+  <div className="grid" data-tells-ignore="LA4 placeholder page behind the overlay">
+    <Card />
+    <Card />
+    <Card />
+  </div>
+  <p className="cap">
+    {last ? `Chose \u201C${last}\u201D.` : "Type \u201Cdep\u201D: the best match moves to the top and the rows that stay travel there. Close it and type in the search field: the palette opens with what you typed."}
+  </p>
+  <CommandPalette
+    open={open}
+    onOpenChange={onOpenChange}
+    query={text}
+    onQueryChange={setText}
+    items={groups}
+    onSelect={(item) => setLast(item.label)}
+  />
+</div>;
+}
+```
+<!-- /example -->

package/dist/guidance/components/CommentThread/README.md

@@ -0,0 +1,81 @@
+# CommentThread
+
+Comments on a task, a document, a design or a deal: write with @mentions, post, retry a failed post, delete your own, and resolve the thread.
+
+**Elevation.**
+- **Posted comments are the record**, flush on the ground, each with its author, `RelativeTime` and body. Mentions are flush `accent-soft` plates in the text.
+- **The composer is an opening**, an `Input` well that fills as you write.
+- **A comment being posted is a pending write**: it hovers ("Posting…") until it lands and settles. If it fails, it drops to a trench ("Couldn't post"), keeping its text, with Retry.
+- **"Done is pressed into the record": a resolved thread is stamped.** It's muted and collapsed to one line ("Resolved by Maya"), kept in place rather than removed, like a done `Checklist` item, with Show comments and Reopen.
+- **A deleted comment** leaves its result in its slot ("Comment deleted"), with Undo.
+- **Someone typing** shows their `presence` colour and name. Other people, live, is where presence belongs.
+
+**Mentions.** Type `@` and a name: a listbox (level 3) offers people from `mentionable(query)`. Arrows move, Enter or Tab chooses, and Escape closes the list. The body stays plain text with "@Name", and `onPost(body, mentions)` receives the people still mentioned in it.
+
+**Accessibility.** Comments are articles in a list. The composer is a [combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) textarea while mentioning (`aria-activedescendant`). ⌘Enter or Ctrl+Enter posts. New comments from others are announced politely and batched ("2 new comments"). Typing indicators aren't announced. Under forced colours the composer is dashed, a pending comment dotted and a failed one dashed thick. Under reduced motion the typing dots don't pulse.
+
+**Props:** `comments` (`{ id, author: { name, avatar? }, body, createdAt, status?, mentions?, mine?, deleted? }[]`); `resolved` (`{ by }` or false); `onPost`; `onResolve`; `onReopen`; `onRetry`; `onDelete`; `onUndoDelete`; `mentionable`; `typing` (names); `aria-label`.
+
+**You provide:** the comments and their states (your app adds a pending comment when it posts, and marks it failed or posted), and who can be mentioned. Rich text is out of scope; a rich editor plugs in through the editor adapter.
+
+```tsx
+<CommentThread comments={comments} resolved={thread.resolved}
+  onPost={(body, mentions) => post(body, mentions)} onResolve={resolve} onReopen={reopen}
+  mentionable={(q) => searchPeople(q)} typing={othersTyping} />
+```
+
+- Do keep a failed comment's text where it was.
+- Do keep a resolved thread in place, stamped.
+- Don't announce typing.
+- Don't post on Enter alone; people write several lines.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`CommentThread` as first used in its preview:
+
+```tsx
+import { CommentThread } from 'altitude-design';
+
+<CommentThread comments={comments} resolved={resolved ? { by: 'You' } : false} onPost={post}
+  onResolve={() => setResolved(true)} onReopen={() => setResolved(false)}
+  onRetry={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, status: undefined } : x)))}
+  onDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: true } : x)))}
+  onUndoDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: false } : x)))}
+  mentionable={(q) => people.filter((p) => p.name.toLowerCase().includes(q.toLowerCase()))} typing={resolved ? [] : ['Ada Obi']} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `ct` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { CommentThread, Switch } from 'altitude-design';
+
+const people = [{ id: 'maya', name: 'Maya Chen' }, { id: 'theo', name: 'Theo Marsh' }, { id: 'ada', name: 'Ada Obi' }];
+const ago = (m) => new Date(Date.now() - m * 60000);
+export default function App() {
+  const [comments, setComments] = React.useState([
+    { id: 'c1', author: { name: 'Theo Marsh' }, body: 'Can we ship this before the release freeze on Friday?', createdAt: ago(90) },
+    { id: 'c2', author: { name: 'Maya Chen' }, body: '@Theo Marsh yes, if QA signs off by Thursday.', mentions: ['Theo Marsh'], createdAt: ago(40) },
+  ]);
+  const [resolved, setResolved] = React.useState(false);
+  const [failNext, setFailNext] = React.useState(false);
+  const post = (body, mentions) => {
+    const id = 'n' + Date.now(), fail = failNext;
+    setComments((xs) => [...xs, { id, author: { name: 'You' }, body, mentions: mentions.map((m) => m.name), createdAt: new Date(), status: 'pending', mine: true }]);
+    setTimeout(() => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, status: fail ? 'failed' : undefined } : x))), 900);
+  };
+  return (
+    <div className="col ct">
+      <CommentThread comments={comments} resolved={resolved ? { by: 'You' } : false} onPost={post}
+        onResolve={() => setResolved(true)} onReopen={() => setResolved(false)}
+        onRetry={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, status: undefined } : x)))}
+        onDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: true } : x)))}
+        onUndoDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: false } : x)))}
+        mentionable={(q) => people.filter((p) => p.name.toLowerCase().includes(q.toLowerCase()))} typing={resolved ? [] : ['Ada Obi']} />
+      <Switch label="Make the next post fail" checked={failNext} onCheckedChange={setFailNext} />
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Confirmation/README.md

@@ -0,0 +1,94 @@
+# Confirmation
+
+Approve or reject an action an agent proposes, before anything happens: "Send 214 emails to Pro customers", "Delete 3 stale branches". Human-in-the-loop for tool calls (the AI SDK's `approval-requested` state).
+
+**Elevation: proposed is raised, not pending.** A pending write hovers because it's already in flight. A proposal hasn't been dispatched, so drawing it hovering would tell the person being asked for permission that it's already happening.
+- **Requested:** a raised card (level 1, `Alert`'s rule for status that asks for action): "Approval needed", what's proposed, **the concrete consequence in words**, optional details (a `DiffView`, a list), "The assistant is asking", and Reject and Approve. Approve names the verb and outcome ("Send 214 emails").
+- **Approved / running:** now it's a write, so it hovers as pending ("Sending…").
+- **Done:** lands with the afterglow ("Sent · approved by you · now").
+- **Failed:** drops to a trench ("Couldn't send"), with Retry.
+- **Rejected / expired:** flush and muted, kept in the record ("Rejected by Maya · 2 minutes ago", "No longer needed").
+
+**Escalation.** Consequential proposals use the `consequential-action` contract: `escalate="hold"` makes Approve a `HoldButton`; `escalate="dialog"` asks again in a stationary `Dialog` for irreversible actions.
+
+**Accessibility.** A labelled `section` (its title) described by the consequence. Not a dialog unless escalated. **There's no default action**: nothing is approved by an accidental Enter, and nothing is focused automatically. Outcomes are announced ("Send campaign email: Sent."). Under forced colours the card has a 1px border, pending is dotted and failed dashed thick. Under `contrast="more"` the requested card gets a hard slab.
+
+**Props:** `state` (`'requested' | 'approved' | 'running' | 'done' | 'failed' | 'rejected' | 'expired'`); `title`; `consequence`; `details`; `approveLabel`, `rejectLabel`, `runningLabel`, `doneLabel`, `failedLabel`; `escalate`; `resolvedBy`, `resolvedAt`; `requestedBy`; `onApprove`, `onReject`, `onRetry`.
+
+**Scopes.** For an action that comes up again and again ("Run npm test"), give `scopes`: Approve becomes a SplitButton whose face approves once and whose menu, "More ways to approve", holds the wider scopes ("Allow npm test for this session", "Always allow npm test · Saved to this project's settings"). `onApprove` gets `'once'` or the scope's value; pass it back as `resolvedScope` and the resolved line says it: "Ran · allowed for this session by you". With `escalate`, scopes are ignored: an action that needs a hold or a dialog is never pre-approved.
+
+**Editing the proposal.** Give `edit` (fields, e.g. `Field` + `Input`) and the card offers Edit: the fields open in place inside it, as `EditRegion` does, focusing the first. Keep `consequence` and `approveLabel` following the edited values so Approve always names what will happen, and set `edited` when they differ: "Edited" shows by the title, and once done the line reads "Sent · edited and approved by you". Escape or Cancel edit closes the fields and calls `onEditCancel` (put the values back); it doesn't reject the proposal. Reject stays available while editing.
+
+**You provide:** the state from your tool call, the consequence in words, and what approving and rejecting do.
+
+```tsx
+<Confirmation state={call.state} title="Send campaign email"
+  consequence="214 Pro customers will receive “October product update”."
+  approveLabel="Send 214 emails" rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent"
+  onApprove={() => respond(call.id, true)} onReject={() => respond(call.id, false)} />
+```
+
+- Do state the consequence concretely: who, how many, what.
+- Do name the outcome on Approve.
+- Don't draw a proposal as pending.
+- Don't remove a rejected proposal; keep it in the record.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Confirmation` as first used in its preview:
+
+```tsx
+import { Confirmation } from 'altitude-design';
+
+<Confirmation state={state} title={title} consequence={consequence} escalate={escalate} approveLabel={approveLabel} rejectLabel={rejectLabel}
+runningLabel={runningLabel} doneLabel={doneLabel} failedLabel={failedLabel} resolvedBy="you" resolvedAt={at} scopes={scopes} resolvedScope={scope}
+onApprove={approve} onReject={() => { setState('rejected'); setAt(new Date()); }} onRetry={() => { setState('running'); setTimeout(() => { setState('done'); setAt(new Date()); }, 1000); }} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Confirmation, Field, Input, Select } from 'altitude-design';
+
+function Proposal({ escalate, title, consequence, approveLabel, rejectLabel, runningLabel, doneLabel, failedLabel, fails, scopes }) {
+  const [state, setState] = React.useState('requested');
+  const [scope, setScope] = React.useState();
+  const [at, setAt] = React.useState();
+  const approve = (s) => { setScope(s); setState('running'); setTimeout(() => { setState(fails ? 'failed' : 'done'); setAt(new Date()); }, 1400); };
+  return <Confirmation state={state} title={title} consequence={consequence} escalate={escalate} approveLabel={approveLabel} rejectLabel={rejectLabel}
+    runningLabel={runningLabel} doneLabel={doneLabel} failedLabel={failedLabel} resolvedBy="you" resolvedAt={at} scopes={scopes} resolvedScope={scope}
+    onApprove={approve} onReject={() => { setState('rejected'); setAt(new Date()); }} onRetry={() => { setState('running'); setTimeout(() => { setState('done'); setAt(new Date()); }, 1000); }} />;
+}
+// Edit what's proposed before approving: the consequence and the button follow the edited values.
+function EditableProposal() {
+  const original = { subject: 'October product update', segment: 'Pro customers', n: 214 };
+  const [v, setV] = React.useState(original);
+  const [state, setState] = React.useState('requested');
+  const [at, setAt] = React.useState();
+  const counts = { 'Pro customers': 214, 'All customers': 1180, 'Trial users': 96 };
+  const edited = v.subject !== original.subject || v.segment !== original.segment;
+  return <Confirmation state={state} title="Send campaign email" consequence={`${v.n} ${v.segment} will receive “${v.subject}”.`}
+    approveLabel={`Send ${v.n} emails`} rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent" resolvedBy="you" resolvedAt={at} edited={edited}
+    edit={<>
+      <Field label="Subject"><Input value={v.subject} onChange={(e) => setV({ ...v, subject: e.target.value })} /></Field>
+      <Field label="Segment"><Select value={v.segment} onValueChange={(segment) => setV({ ...v, segment, n: counts[segment] })} items={Object.keys(counts).map((k) => ({ value: k, label: k }))} /></Field>
+    </>}
+    onEditCancel={() => setV(original)}
+    onApprove={() => { setState('running'); setTimeout(() => { setState('done'); setAt(new Date()); }, 1200); }} onReject={() => { setState('rejected'); setAt(new Date()); }} />;
+}
+export default function App() {
+  return (
+    <div className="col">
+      <Proposal title="Send campaign email" consequence="214 Pro customers will receive “October product update”." approveLabel="Send 214 emails" rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent" failedLabel="Couldn't send" />
+      <Proposal title="Delete 3 stale branches" consequence="release/2.3, spike/maps and fix/old-auth will be deleted from the repository." approveLabel="Delete 3 branches" rejectLabel="Keep them" runningLabel="Deleting…" doneLabel="Deleted" escalate="hold" />
+      <Proposal title="Archive the Atlas workspace" consequence="12 people lose access; it can't be restored after 30 days." approveLabel="Archive workspace" rejectLabel="Don't archive" runningLabel="Archiving…" failedLabel="Couldn't archive" escalate="dialog" fails />
+      <Proposal title="Run npm test" consequence="Runs the test suite in this workspace." approveLabel="Run once" rejectLabel="Don't run" runningLabel="Running…" doneLabel="Ran"
+        scopes={[{ value: 'session', label: 'Allow npm test for this session' }, { value: 'always', label: 'Always allow npm test', description: 'Saved to this project’s settings' }]} />
+      <EditableProposal />
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/ContextMenu/README.md

@@ -0,0 +1,81 @@
+# ContextMenu
+
+Actions on a thing (a file, a row, a board card, a tree node, a canvas object), opened where you right-click or long-press it, or at it with Shift+F10 or the Menu key.
+
+**Elevation.** The menu is `DropdownMenu`'s own (both use one implementation): a floating surface at level 3, with the highlight that glides between items, `predicted` items first, and `critical` items in words. **The thing shows it's the subject with a 2px `accent-ink` outline**, a ring and never a height, so a flush table row doesn't lift out of its table.
+
+**No submenus.** "Don't stack floating on floating": a menu inside a menu loses the reading of height. Put the choices in the menu (a few) or open a `Dialog` ("Move to…").
+
+**Every action needs another way.** A right-click is invisible until you know it's there, and long-press is easy to miss. Put the same actions behind a visible button on the thing (a row's "⋯" `DropdownMenu`), as the preview does.
+
+**Accessibility.** The [menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/). The thing gets `aria-haspopup="menu"` and `aria-expanded`, and must be focusable (`tabIndex={0}`) so Shift+F10 and the Menu key can open the menu at it. That opens with the first item active. Arrows, Home, End and Enter work in the menu, and Escape (or choosing) returns focus to the thing. A long press on touch is 500ms without moving more than 10px. The menu stays inside the viewport, flipping left or up at an edge, and closes on scroll, resize or a click outside. Under forced colours the outline is `Highlight`.
+
+**Props:** `items` (`DropdownMenu` entries, or a function called each time it opens); `children` (one element: the thing); `aria-label`; `onOpenChange`.
+
+**You provide:** the thing (focusable), its actions, and another way to reach them.
+
+```tsx
+<ContextMenu items={() => [
+  { label: 'Rename', onSelect: () => rename(file) },
+  { type: 'separator' },
+  { label: 'Delete file', tone: 'critical', onSelect: () => remove(file) },
+]}>
+  <div role="listitem" tabIndex={0}>{file.name} <RowActions file={file} /></div>
+</ContextMenu>
+```
+
+- Do make the thing focusable, so the keyboard can open its menu.
+- Do offer the same actions in a visible menu.
+- Don't nest menus; open a `Dialog` for a long choice.
+- Don't raise the thing while its menu is open; it's outlined.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`ContextMenu` as first used in its preview:
+
+```tsx
+import { Button, ContextMenu, DropdownMenu, Icons } from 'altitude-design';
+
+<ContextMenu key={f} items={() => actions(f)}>
+  <div className="file" role="listitem" tabIndex={0}>
+    <span className="name">{f}</span><span className="meta">Edited 2 days ago</span>
+    <DropdownMenu align="end" items={actions(f)} trigger={<Button variant="ghost" size="sm" square aria-label={`Actions for ${f}`}><Icons.More /></Button>} />
+  </div>
+</ContextMenu>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `cm2`, `file`, `name`, `meta`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, ContextMenu, DropdownMenu, Icons } from 'altitude-design';
+
+export default function App() {
+  const [files, setFiles] = React.useState(['Q3 board deck.pdf', 'Invoices 2026.xlsx', 'Brand guidelines.fig']);
+  const [said, setSaid] = React.useState('');
+  const actions = (f) => [
+    { label: 'Open', onSelect: () => setSaid(`Opened ${f}.`) },
+    { label: 'Rename', onSelect: () => setSaid(`Renaming ${f}…`) },
+    { label: 'Duplicate', onSelect: () => setSaid(`Duplicated ${f}.`) },
+    { type: 'separator' },
+    { label: 'Delete file', tone: 'critical', onSelect: () => { setFiles((xs) => xs.filter((x) => x !== f)); setSaid(`Deleted ${f}.`); } },
+  ];
+  return (
+    <div className="col">
+      <div className="cm2" role="list" aria-label="Files">
+        {files.map((f) => (
+          <ContextMenu key={f} items={() => actions(f)}>
+            <div className="file" role="listitem" tabIndex={0}>
+              <span className="name">{f}</span><span className="meta">Edited 2 days ago</span>
+              <DropdownMenu align="end" items={actions(f)} trigger={<Button variant="ghost" size="sm" square aria-label={`Actions for ${f}`}><Icons.More /></Button>} />
+            </div>
+          </ContextMenu>
+        ))}
+      </div>
+      <p className="cap" role="status">{said || 'Right-click a file (or long-press, or focus it and press Shift+F10). The same actions are behind each row\'s ⋯ button, because a context menu is never the only way.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Conversation/README.md

@@ -0,0 +1,169 @@
+# Conversation
+
+The thread between a person and an assistant: their messages, the assistant's answers (often streamed), copy, regenerate, feedback, versions, and "Jump to latest" once you've scrolled up. Pair it with `PromptInput`.
+
+**Elevation: how settled is a streamed answer?** Settled messages are the record.
+- **A person's message** is a flush `accent-soft` sheet on the right.
+- **An assistant's complete message** is flush with no bubble and no shadow, with a quiet `line` rule down its left edge.
+- **A streaming answer isn't the record yet**, and it isn't a pending write either: nothing you sent is in flight, so it mustn't hover. It rests on the ground with the treatment charts use for data still being counted: **a dashed `line-control` rule**, "Generating…" and a caret. It's `aria-busy`.
+- **When it completes**, the rule goes solid and the message settles with one afterglow. The arrival signal is held until the answer is whole, because lifting it for the seconds it takes to stream would be a prolonged rise.
+- **Stopped or failed** answers are kept, with "Stopped" or "Couldn't finish" (and a `critical` rule) and Retry.
+- **Message actions** are ghost buttons that lift when pointed at. Feedback is a pair of toggles; regenerated answers are versions ("Version 2 of 2"), because a previous answer is a record and isn't overwritten.
+- **"Jump to latest message"** floats at level 3 once you've scrolled up. The thread follows new text to the bottom until you scroll up, then lets go.
+
+**Motion.** Text arrives without per-word animation. Completion: one afterglow. Under reduced motion the caret doesn't blink.
+
+**Accessibility.** A `log` region of articles, each headed by who's speaking ("You" visually hidden). **Streamed text isn't announced token by token**: the log's own announcements are off, and each answer is announced once, when it completes ("Assistant: Last week the team shipped…", up to 280 characters). Stopping is announced politely, a failure assertively. The log is focusable so it can be scrolled by keyboard. Under forced colours the streaming rule is dotted and a complete one solid. Under `contrast="more"` the rule is `line-control`.
+
+**Parts:** `Conversation` (`aria-label`); `ConversationContent`; `ConversationScrollButton`; `Message` (`from`, `status` (`'streaming' | 'complete' | 'stopped' | 'error'`), `name`, `onRetry`); `MessageAttachments` (`items`: `{ name, type?, size?, url?, alt?, href?, onOpen?, unavailable? }`), before the content: what was sent with the message, images as 64px thumbnails and other files as settled Tag plates with type and size, acting when they have `href` or `onOpen`; `MessageContent`; `MessageActions` (`onCopy`, `onRegenerate`, `onFeedback`, `feedback`, `versions`, `onEdit`); `Message edited`.
+
+**Editing a sent message.** Give a person's message `MessageActions onEdit`: Edit opens it in place (the text stays where it is while a Textarea well opens around it), with Cancel and "Send edit"; Escape cancels, Ctrl/⌘+Enter sends. Sending calls `onEdit(text)`: start a new branch from that message, keep the earlier one, and show its `versions` ("Version 2 of 2") and `edited` ("Edited"). Switching versions is announced; render the turns of the branch shown. Nothing is deleted.
+
+**The queue.** `ConversationQueue` (`items`, `onSendNow`, `onEdit`, `onRemove`) goes between the thread and the composer and lists messages queued while the agent works (`PromptInput onQueue`), in order, each with Send now (stop the turn and send it), Edit (in place) and Remove. A queued message is written but not dispatched, so it doesn't hover: it's the person's sheet, flush, with a dashed rim and "Queued · 1 of 2". When the turn ends, send the first; it becomes an ordinary message in the log.
+
+**Checkpoints.** `ConversationCheckpoint` (`label`, `at`, `consequence`, `onRestore`, `onReturn`) marks a point between messages to go back to: a divider reading "Checkpoint · Before editing 6 files · 2:14 PM" with Restore, described by the consequence. It follows the consequential-action contract: with `onReturn` (real recovery), Restore runs at once and leaves "Return to where you were"; without it, Restore asks in a Dialog. Restoring hovers as pending, settles once when done, and sinks into a trench with Retry if it fails; the outcome is announced. Set the later turns aside as a branch rather than deleting them.
+
+**You provide:** the messages and their status as your stream reports it. Code inside an answer goes in `CodeBlock`.
+
+```tsx
+<Conversation aria-label="Assistant">
+  <ConversationContent>
+    {messages.map((m) => (
+      <Message key={m.id} from={m.role} status={m.status}>
+        <MessageContent>{m.content}</MessageContent>
+        <MessageActions onCopy onRegenerate={() => regen(m.id)} onFeedback={(v) => rate(m.id, v)} />
+      </Message>
+    ))}
+  </ConversationContent>
+  <ConversationScrollButton />
+</Conversation>
+```
+
+- Do pass the stream's status, so a finished answer settles and is announced.
+- Do keep earlier versions when regenerating.
+- Don't fade in text word by word or glow a streaming answer.
+- Don't make a streaming answer hover; it isn't a pending write.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Conversation` as first used in its preview:
+
+```tsx
+import { Conversation, ConversationCheckpoint, ConversationContent, ConversationScrollButton, Message, MessageActions, MessageAttachments, MessageContent } from 'altitude-design';
+
+<Conversation aria-label="Assistant">
+  <ConversationContent>
+    {msgs.map((m) => m.kind === 'checkpoint' ? (
+      <ConversationCheckpoint key={m.id} label={m.label} at={m.at} onRestore={() => restore(m.id)} onReturn={giveBack}
+        consequence="The messages after this will be set aside. You can return to them." />
+    ) : (
+      <Message key={m.id} from={m.from} status={m.status} edited={m.v > 0} onRetry={m.status === 'stopped' ? () => { setStatus('streaming'); stream(m.id); } : undefined}>
+        {m.files && <MessageAttachments items={m.files} />}
+        <MessageContent>{m.text}</MessageContent>
+        {m.from === 'assistant' ? <MessageActions onCopy onRegenerate={() => {}} onFeedback={() => {}} />
+          : <MessageActions onEdit={(t) => edit(m.id, t)} versions={m.versions && { index: m.v + 1, total: m.versions.length, onChange: (k) => showVersion(m.id, k - 1) }} />}
+      </Message>
+    ))}
+  </ConversationContent>
+  <ConversationScrollButton />
+</Conversation>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`cv` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Conversation, ConversationCheckpoint, ConversationContent, ConversationQueue, ConversationScrollButton, Message, MessageActions, MessageAttachments, MessageContent, PromptInput, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar } from 'altitude-design';
+
+const answer = 'Last week the team shipped 14 changes. Two risks are open: the billing migration is two days behind, and the EU data residency review needs a decision from legal by Friday.';
+export default function App() {
+  const [msgs, setMsgs] = React.useState([
+    { id: 1, from: 'user', text: 'What changed in the Atlas workspace this month?', files: [
+      { name: 'atlas-usage.png', type: 'image/svg+xml', url: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='64'%3E%3Crect width='120' height='64' fill='%23e8edf5'/%3E%3Cpath d='M8 52 L32 36 L56 42 L80 20 L112 12' stroke='%233b6fd8' stroke-width='3' fill='none'/%3E%3C/svg%3E", onOpen: () => {} },
+      { name: 'Atlas changelog.pdf', type: 'application/pdf', size: 482113, href: '#changelog' },
+    ] },
+    { id: 'cp1', kind: 'checkpoint', label: 'Before the Atlas summary', at: '2026-10-30T14:14:00' },
+    { id: 2, from: 'assistant', text: 'Atlas moved to the new permission model on 3 October, and its storage limit was raised to 2 TB. Three people joined: Maya, Theo and Ada.', status: 'complete' },
+  ]);
+  const [status, setStatus] = React.useState('ready');
+  const timer = React.useRef();
+  // Messages written while the assistant works wait in the queue; the first is sent when the turn ends.
+  const [queued, setQueued] = React.useState([]);
+  const queuedRef = React.useRef(queued); queuedRef.current = queued;
+  const sendRef = React.useRef();
+  const stream = (id) => {
+    let n = 0;
+    const tick = () => {
+      n += 6;
+      setMsgs((ms) => ms.map((m) => (m.id === id ? { ...m, text: answer.slice(0, n), status: n >= answer.length ? 'complete' : 'streaming' } : m)));
+      if (n < answer.length) timer.current = setTimeout(tick, 60);
+      else {
+        setStatus('ready');
+        const next = queuedRef.current[0];
+        if (next) { setQueued((q) => q.slice(1)); setTimeout(() => sendRef.current({ text: next.text }), 0); }
+      }
+    };
+    tick();
+  };
+  const enqueue = ({ text }) => setQueued((q) => [...q, { id: String(Date.now()), text }]);
+  const send = ({ text }) => {
+    const id = Date.now();
+    setMsgs((ms) => [...ms, { id: id - 1, from: 'user', text }, { id, from: 'assistant', text: '', status: 'streaming' }]);
+    setStatus('streaming');
+    stream(id);
+  };
+  // Editing a sent message starts a branch from it; the earlier exchange is kept as version 1.
+  const edit = (id, text) => {
+    const i = msgs.findIndex((m) => m.id === id), m = msgs[i];
+    const versions = (m.versions ?? [{ text: m.text, files: m.files }]).map((v, k) => (k === (m.v ?? 0) ? { ...v, rest: msgs.slice(i + 1) } : v));
+    const aid = Date.now();
+    setMsgs([...msgs.slice(0, i), { ...m, text, files: undefined, versions: [...versions, { text }], v: versions.length }, { id: aid, from: 'assistant', text: '', status: 'streaming' }]);
+    setStatus('streaming');
+    stream(aid);
+  };
+  const showVersion = (id, k) => {
+    const i = msgs.findIndex((m) => m.id === id), m = msgs[i];
+    const versions = m.versions.map((v, j) => (j === m.v ? { ...v, rest: msgs.slice(i + 1) } : v));
+    setMsgs([...msgs.slice(0, i), { ...m, text: versions[k].text, files: versions[k].files, versions, v: k }, ...(versions[k].rest ?? [])]);
+  };
+  const sendNow = (id) => {
+    const q = queued.find((x) => x.id === id);
+    setQueued((qs) => qs.filter((x) => x.id !== id));
+    stop();
+    setTimeout(() => sendRef.current({ text: q.text }), 0);
+  };
+  // Restoring a checkpoint sets the turns after it aside; returning brings them back.
+  const aside = React.useRef([]);
+  const restore = (id) => new Promise((done) => setTimeout(() => { setMsgs((ms) => { const i = ms.findIndex((m) => m.id === id); aside.current = ms.slice(i + 1); return ms.slice(0, i + 1); }); done(); }, 900));
+  const giveBack = () => { setMsgs((ms) => [...ms, ...aside.current]); aside.current = []; };
+  const stop = () => { clearTimeout(timer.current); setStatus('ready'); setMsgs((ms) => ms.map((m) => (m.status === 'streaming' ? { ...m, status: 'stopped' } : m))); };
+  sendRef.current = send;
+  return (
+    <div className="cv">
+      <Conversation aria-label="Assistant">
+        <ConversationContent>
+          {msgs.map((m) => m.kind === 'checkpoint' ? (
+            <ConversationCheckpoint key={m.id} label={m.label} at={m.at} onRestore={() => restore(m.id)} onReturn={giveBack}
+              consequence="The messages after this will be set aside. You can return to them." />
+          ) : (
+            <Message key={m.id} from={m.from} status={m.status} edited={m.v > 0} onRetry={m.status === 'stopped' ? () => { setStatus('streaming'); stream(m.id); } : undefined}>
+              {m.files && <MessageAttachments items={m.files} />}
+              <MessageContent>{m.text}</MessageContent>
+              {m.from === 'assistant' ? <MessageActions onCopy onRegenerate={() => {}} onFeedback={() => {}} />
+                : <MessageActions onEdit={(t) => edit(m.id, t)} versions={m.versions && { index: m.v + 1, total: m.versions.length, onChange: (k) => showVersion(m.id, k - 1) }} />}
+            </Message>
+          ))}
+        </ConversationContent>
+        <ConversationScrollButton />
+      </Conversation>
+      <ConversationQueue items={queued} onSendNow={sendNow} onEdit={(id, text) => setQueued((qs) => qs.map((q) => (q.id === id ? { ...q, text } : q)))} onRemove={(id) => setQueued((qs) => qs.filter((q) => q.id !== id))} />
+      <PromptInput onSubmit={send} status={status} onStop={stop} onQueue={enqueue}>
+        <PromptInputTextarea placeholder="Ask about this workspace" />
+        <PromptInputToolbar><PromptInputSubmit /></PromptInputToolbar>
+      </PromptInput>
+    </div>
+  );
+}
+```
+<!-- /example -->