@handamade/psi-react 0.20.0 → 0.21.0

package/dist/manifest.json

@@ -26,6 +26,13 @@
           "default": 32,
           "description": "Height in px (24 | 32 | 40 | 48)."
         },
+        {
+          "name": "type",
+          "type": "\"button\" | \"submit\" | \"reset\"",
+          "required": false,
+          "default": null,
+          "description": "Button type. Declared so the manifest lists it and a pattern can say\n`submit` (D87). No default is set: the platform's applies — `submit`\ninside a form, a plain button elsewhere."
+        },
         {
           "name": "href",
           "type": "string",
@@ -462,6 +469,13 @@
           "default": false,
           "description": "Renders the required marker and flows `required` to the control."
         },
+        {
+          "name": "requiredText",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "With `required`, the label shows this text — \"(Required)\", say — instead\nof the asterisk, so the requirement is stated in words and not by a glyph\nalone (D84). Visible and aria-hidden: the control carries the programmatic\nsignal (`required` / `aria-required`), and a screen reader that heard both\nwould say it twice. Without `required` it renders nothing."
+        },
         {
           "name": "group",
           "type": "boolean",
@@ -720,7 +734,7 @@
     },
     {
       "name": "Toolbar",
-      "description": "Horizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\".",
+      "description": "Horizontal grouping row for filter/search controls (D52). Wraps on overflow; zero JS. Deliberately NOT ARIA role=\"toolbar\" — that role contracts roving-tabindex arrow-key navigation, wrong for form controls. With aria-label it announces as role=\"group\"; as a form, as a named form landmark instead (D87).",
       "slots": [
         {
           "name": "body",
@@ -744,9 +758,23 @@
           "default": 8,
           "description": "Gap between controls in px."
         },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\"",
+          "required": false,
+          "default": "center",
+          "description": "Cross-axis alignment. `end` lines items up on their bottom edge, so\ncontrols under visible Field labels and a button without one share a\ncontrol line (D87). It lines up each item's *last* line: a Field in an\nend-aligned row must end on its control — no description or error line\nunder it; put a hint in the label."
+        },
+        {
+          "name": "as",
+          "type": "\"div\" | \"form\"",
+          "required": false,
+          "default": "div",
+          "description": "Root element. `form` renders a real `<form>`, so a submit Button\nsubmits it and Enter in a field does too; with `aria-label` it is a\nnamed form landmark, so it takes no `role=\"group\"` (D87). Wire\n`onSubmit`."
+        },
         {
           "name": "ref",
-          "type": "Ref<HTMLDivElement>",
+          "type": "Ref<HTMLDivElement | HTMLFormElement>",
           "required": false,
           "default": null,
           "description": "Forwarded ref to the root element."
@@ -791,7 +819,26 @@
     {
       "name": "NavBar",
       "description": "Top navigation bar with brand, nav-link, and trailing-action slots.",
-      "slots": [],
+      "slots": [
+        {
+          "name": "brand",
+          "accepts": {},
+          "cardinality": "0..*",
+          "order": 1
+        },
+        {
+          "name": "actions",
+          "accepts": {},
+          "cardinality": "0..*",
+          "order": 2
+        },
+        {
+          "name": "body",
+          "accepts": {},
+          "cardinality": "0..*",
+          "order": 3
+        }
+      ],
       "props": [
         {
           "name": "brand",
@@ -812,7 +859,21 @@
           "type": "ReactNode",
           "required": false,
           "default": null,
-          "description": "Nav links."
+          "description": "Nav links. The `<nav>` renders only when there are children, so a bar with\na brand and actions and no links has no empty landmark (D88)."
+        },
+        {
+          "name": "navLabel",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Accessible name of the links' `<nav>` (its `aria-label`). Rest props land\non the `<header>`, so this is the only way to label the `<nav>` (D88)."
+        },
+        {
+          "name": "fluid",
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Lay the row out at full width: it drops `psi-container` (the centred\nmax-width column) and keeps the `--psi-gutter` side padding. For an\napplication header over a full-width frame (D88)."
         },
         {
           "name": "ref",
@@ -831,30 +892,30 @@
       ]
     },
     {
-      "name": "AspectRatio",
-      "description": "Fixed-aspect-ratio box that sizes its child media.",
+      "name": "SkipLink",
+      "description": "A link to the page's main content, invisible until it takes keyboard focus and then fixed at the inline-start top corner on a surface, drawing the shared focus ring (D88). Render it first in the document. No script: native fragment navigation moves focus to a target that is focusable, so the next *Tab* continues from inside it. `AppShell`'s `main` is one (`tabIndex={-1}`); a bare `<main>` is not, so give it one. A modal `Dialog` makes the rest of the document inert, so the link never needs to beat one. A `ToastRegion` is on the native top layer, which paints above everything whatever its `z-index`: do not place one at `top-start` (its default is `bottom-end`) in an app with a skip link, or it covers the focused link.",
       "slots": [],
       "props": [
         {
-          "name": "children",
-          "type": "ReactNode",
-          "required": false,
+          "name": "href",
+          "type": "string",
+          "required": true,
           "default": null,
-          "description": "Content constrained to the ratio."
+          "description": "Fragment of the element to skip to, such as `\"#main\"`. The target must be\nfocusable (`tabIndex={-1}` is enough), or focus does not move."
         },
         {
-          "name": "ratio",
-          "type": "number",
+          "name": "children",
+          "type": "ReactNode",
           "required": true,
           "default": null,
-          "description": "Width/height ratio, e.g. 16/10 or 4/5."
+          "description": "Visible text, such as \"Skip to content\"."
         },
         {
           "name": "ref",
-          "type": "Ref<HTMLDivElement>",
+          "type": "Ref<HTMLAnchorElement>",
           "required": false,
           "default": null,
-          "description": "Forwarded ref to the frame element."
+          "description": "Forwarded ref to the anchor."
         },
         {
           "name": "className",
@@ -866,73 +927,84 @@
       ]
     },
     {
-      "name": "Menu",
-      "description": "Action menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.",
+      "name": "NavTree",
+      "description": "A navigation tree (D88): a `<nav aria-label>` around a `<ul>` of `NavItem`s and `NavGroup`s. Native elements only — *Tab* moves through the group buttons and the links of open groups; there is no roving focus and no `role=\"menu\"` or `role=\"tree\"`, because site navigation is a list of links, not a widget. Router-agnostic: pass your router's link inside each `NavItem`, with `aria-current=\"page\"` on the current one.",
       "slots": [
-        {
-          "name": "trigger",
-          "accepts": {
-            "contracts": [
-              "interactive"
-            ]
-          },
-          "cardinality": "1..1",
-          "order": 1
-        },
         {
           "name": "body",
           "accepts": {
             "components": [
-              "MenuItem",
-              "MenuSeparator"
+              "NavGroup",
+              "NavItem"
             ]
           },
           "cardinality": "1..*",
-          "order": 2
+          "order": 1
         }
       ],
       "props": [
         {
-          "name": "open",
-          "type": "boolean",
+          "name": "aria-label",
+          "type": "string",
           "required": true,
           "default": null,
-          "description": "Controlled open state; syncs to showPopover()/hidePopover()."
+          "description": "Accessible name of the navigation landmark, such as \"Main\". Required: an\napp has more than one `<nav>` (a header's, a sidebar's), and an unnamed\none is indistinguishable from the rest. Declared here rather than\ninherited so docgen keeps it in the manifest (D60)."
         },
         {
-          "name": "onClose",
-          "type": "(reason: \"item-select\" | \"esc\" | \"outside\") => void",
+          "name": "children",
+          "type": "ReactNode",
           "required": true,
           "default": null,
-          "description": "Called when a dismissal is *requested*; the consumer flips `open`.\n\nMenu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays\nopen until `open` becomes false (D50). `\"outside\"` is the one exception:\nlight dismiss is performed by the browser before it tells us, so by the\ntime that reason is reported the popover is already closed. Flipping\n`open` to false is still required, to keep React's state in step.\n\nInvariant (D58): a dismissal is only ever reported for a menu that is\ncurrently open according to its own `open` prop. The platform can close\nan auto popover before the consumer's state catches up — clicking another\nmenu's trigger light-dismisses this one before the consumer's click\nhandler runs — and a report for an already-closed menu would clear a\nselection that has since moved on."
+          "description": "`NavItem`s and `NavGroup`s — each renders an `<li>`."
         },
         {
-          "name": "trigger",
-          "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>>",
-          "required": true,
+          "name": "className",
+          "type": "string",
+          "required": false,
           "default": null,
-          "description": "The trigger element. Must be a single React element that spreads unknown\nprops onto a focusable node (a Psi `Button`, say): Menu clones it to add\n`aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates\nthe menu with the control users actually focus."
+          "description": "Additional CSS class name(s) merged onto the component's root element."
         },
         {
-          "name": "placement",
-          "type": "\"bottom-start\" | \"bottom-end\" | \"top-start\" | \"top-end\"",
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
           "required": false,
-          "default": "bottom-start",
-          "description": "Placement relative to the trigger."
+          "default": null,
+          "description": "Forwarded ref to the `<nav>`."
+        }
+      ]
+    },
+    {
+      "name": "NavGroup",
+      "description": "A collapsible group of `NavItem`s in a `NavTree` (D88). Controlled-only, like `Tabs` (D67): `open` and `onOpenChange` are required and nothing is remembered. Renders a native `<button aria-expanded aria-controls>` over a `<ul>` that is `hidden` when closed, so the items leave the layout and the accessibility tree while `aria-controls` keeps naming an element. The chevron turns with the state and is `aria-hidden`: the label and `aria-expanded` carry the meaning.",
+      "slots": [],
+      "props": [
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "The group's visible label, such as \"Reports\"."
         },
         {
-          "name": "aria-label",
-          "type": "string",
-          "required": false,
+          "name": "open",
+          "type": "boolean",
+          "required": true,
           "default": null,
-          "description": "Accessible name for the menu when there is no visible label."
+          "description": "Whether the group's items are shown. Controlled."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "(open: boolean) => void",
+          "required": true,
+          "default": null,
+          "description": "Called with the next state when the button is pressed. The group never\nchanges `open` itself."
         },
         {
           "name": "children",
           "type": "ReactNode",
           "required": true,
           "default": null,
-          "description": "MenuItem and MenuSeparator children."
+          "description": "`NavItem`s of the group."
         },
         {
           "name": "className",
@@ -940,19 +1012,12 @@
           "required": false,
           "default": null,
           "description": "Additional CSS class name(s) merged onto the component's root element."
-        },
-        {
-          "name": "ref",
-          "type": "Ref<HTMLDivElement>",
-          "required": false,
-          "default": null,
-          "description": "Forwarded ref to the popover element."
         }
       ]
     },
     {
-      "name": "MenuItem",
-      "description": "One action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).",
+      "name": "NavItem",
+      "description": "One entry of a `NavTree` (D88): an `<li>` that styles the single anchor inside it. Router apps pass their own link as the child, so it keeps its `href`, `aria-current` and handlers; `href` is for plain links and for presets, where the compose tree can hold only manifest components and a raw `<a>` is not one. The current page is never marked by colour alone: medium weight, a raised surface and a bar at the inline start.",
       "slots": [],
       "props": [
         {
@@ -960,116 +1025,135 @@
           "type": "ReactNode",
           "required": true,
           "default": null,
-          "description": "Item label."
+          "description": "Without `href`: one anchor, your router's link — put `aria-current=\"page\"`\non the current one. With `href`: the link's text."
         },
         {
-          "name": "onSelect",
-          "type": "() => void",
-          "required": true,
+          "name": "href",
+          "type": "string",
+          "required": false,
           "default": null,
-          "description": "Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50)."
+          "description": "Render the anchor yourself (D88), for a plain link or a preset: the\n`<li>` holds `<a href>` with `children` as its text. Router apps leave it\nout and pass their own link as the child, so the link keeps its own\nhandlers."
         },
         {
-          "name": "variant",
-          "type": "\"neutral\" | \"danger\"",
+          "name": "current",
+          "type": "boolean",
           "required": false,
-          "default": "neutral",
-          "description": "danger is for destructive actions only (house rule)."
+          "default": null,
+          "description": "Mark the link as the current page (`aria-current=\"page\"`). Only with\n`href`; a link you pass as a child carries its own `aria-current`."
         },
         {
-          "name": "disabled",
-          "type": "boolean",
+          "name": "className",
+          "type": "string",
           "required": false,
-          "default": false,
-          "description": ""
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLLIElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the `<li>`."
         }
       ]
     },
     {
-      "name": "MenuSeparator",
-      "description": "Hairline rule between Menu item groups. No props by design (D53).",
-      "slots": [],
-      "props": []
-    },
-    {
-      "name": "Table",
-      "description": "Data table on native table semantics. Holds no state: sorting, selection and pagination are the consumer's (D62, extending D50/D53).",
+      "name": "AppShell",
+      "description": "The frame of an application (D88): a header row over a sidebar and a `<main>` that each scroll on their own, filling the viewport (`100dvh`). Because the header has a row of its own and `main` is its own scroller, nothing scrolls under the header, so a focused element is never obscured by it (WCAG 2.2 *Focus Not Obscured*) without `scroll-padding`. `main` carries `id={mainId}` and `tabIndex={-1}`: the target of a `SkipLink`, not a tab stop; focused by the skip link it draws the shared focus ring inside its box. A closed sidebar is `hidden`, not narrowed to icons; there is no responsive drawer and no stored open state, so this is a desktop frame. A page whose document must scroll as a whole does not use `AppShell`. Mount it at the root of the page with no margin or padding around it: it is `100dvh` tall, so anything around it makes the document scroll and slides the frame. Do not place a `ToastRegion` at `top-start` in an app with a skip link: the native top layer paints over the focused link.",
       "slots": [
         {
-          "name": "body",
+          "name": "skipLink",
           "accepts": {
             "components": [
-              "TableHead",
-              "TableBody"
+              "SkipLink"
             ]
           },
-          "cardinality": "1..*",
+          "cardinality": "0..1",
           "order": 1
+        },
+        {
+          "name": "header",
+          "accepts": {
+            "components": [
+              "NavBar"
+            ]
+          },
+          "cardinality": "0..1",
+          "order": 2
+        },
+        {
+          "name": "sidebar",
+          "accepts": {
+            "components": [
+              "NavTree"
+            ]
+          },
+          "cardinality": "0..1",
+          "order": 3
+        },
+        {
+          "name": "body",
+          "accepts": {},
+          "cardinality": "0..*",
+          "order": 4
         }
       ],
       "props": [
         {
-          "name": "size",
-          "type": "32 | 40 | 48",
-          "required": false,
-          "default": 40,
-          "description": "Row height in px."
-        },
-        {
-          "name": "stickyHeader",
-          "type": "boolean",
+          "name": "skipLink",
+          "type": "ReactNode",
           "required": false,
           "default": null,
-          "description": "Pins the header while the body scrolls."
+          "description": "A `SkipLink` (D88), rendered first so it is the first tab stop. Point its\n`href` at `#` plus `mainId`."
         },
         {
-          "name": "sortable",
-          "type": "boolean",
+          "name": "header",
+          "type": "ReactNode",
           "required": false,
-          "default": false,
-          "description": "Enables the sort affordance on header cells that declare a `sortKey`."
+          "default": null,
+          "description": "The header row, usually a `NavBar` (D88). It sits in a row of its own\nabove the sidebar and `main`, so nothing scrolls under it."
         },
         {
-          "name": "sort",
-          "type": "TableSortState | null",
+          "name": "sidebar",
+          "type": "ReactNode",
           "required": false,
           "default": null,
-          "description": "Controlled sort state; `null` when nothing is sorted."
+          "description": "The sidebar's content, usually a `NavTree` (D88). The shell wraps it in a\n`<div>`, not an `<aside>`: a `NavTree` is already the landmark."
         },
         {
-          "name": "onSortChange",
-          "type": "((sort: TableSortState) => void)",
+          "name": "children",
+          "type": "ReactNode",
           "required": false,
           "default": null,
-          "description": "Called with the **next** sort state, already toggled — store it as given\nand do not toggle again. A fresh column arrives `\"asc\"`; an active `\"asc\"`\ncolumn emits `\"desc\"`; an active `\"desc\"` column emits `\"asc\"`.\n\nOptional in the type because `sortable` may be false; a discriminated union\nexpressing the real contract does not survive docgen's flat prop\nextraction, which would strip these props from the manifest entirely (D62)."
+          "description": "The page, rendered inside `<main>` (D88)."
         },
         {
-          "name": "selectable",
+          "name": "sidebarOpen",
           "type": "boolean",
           "required": false,
-          "default": false,
-          "description": "Renders the row-selection checkbox column."
+          "default": true,
+          "description": "Whether the sidebar is shown. Controlled: wire your Menu toggle's\n`aria-expanded` and this to one piece of state. Closed, the sidebar is\n`hidden`, so it leaves the layout and the accessibility tree, and stays in\nthe DOM so the toggle's `aria-controls` keeps naming an element (D88)."
         },
         {
-          "name": "selected",
-          "type": "ReadonlySet<string>",
+          "name": "sidebarTheme",
+          "type": "string",
           "required": false,
-          "default": "new Set<string>()",
-          "description": "Controlled selection, keyed by each `TableRow`'s `rowId`."
+          "default": null,
+          "description": "A theme name for the sidebar alone, such as `\"dark\"`: sets\n`data-psi-theme` on the sidebar element, so every token inside re-resolves\nunder that theme while the rest of the page keeps its own (D88). The\nsidebar paints `--psi-bg-primary` itself; a theme paints no background."
         },
         {
-          "name": "onSelectionChange",
-          "type": "((selected: ReadonlySet<string>) => void)",
+          "name": "sidebarId",
+          "type": "string",
           "required": false,
-          "default": null,
-          "description": "Called with the next selection. See `onSortChange` on why it is optional."
+          "default": "sidebar",
+          "description": "`id` of the sidebar element, which a toggle names with `aria-controls`\n(D88)."
         },
         {
-          "name": "children",
-          "type": "ReactNode",
-          "required": true,
-          "default": null,
-          "description": "TableHead and TableBody."
+          "name": "mainId",
+          "type": "string",
+          "required": false,
+          "default": "main",
+          "description": "`id` of `<main>`, which a `SkipLink`'s `href` names (D88)."
         },
         {
           "name": "className",
@@ -1080,22 +1164,280 @@
         },
         {
           "name": "ref",
-          "type": "Ref<HTMLTableElement>",
+          "type": "Ref<HTMLDivElement>",
           "required": false,
           "default": null,
-          "description": "Forwarded ref to the underlying `<table>` element."
+          "description": "Forwarded ref to the root `<div>`."
         }
       ]
     },
     {
-      "name": "TableHead",
-      "description": "`<thead>`. When the table is selectable, prepends the select-all cell to the FIRST header row so the header's column count matches the body's — the checkbox column is Table's, not the consumer's schema. Clones the row rather than rebuilding it, so the consumer's own props on that `TableRow` survive.",
+      "name": "AspectRatio",
+      "description": "Fixed-aspect-ratio box that sizes its child media.",
       "slots": [],
       "props": [
         {
           "name": "children",
           "type": "ReactNode",
-          "required": true,
+          "required": false,
+          "default": null,
+          "description": "Content constrained to the ratio."
+        },
+        {
+          "name": "ratio",
+          "type": "number",
+          "required": true,
+          "default": null,
+          "description": "Width/height ratio, e.g. 16/10 or 4/5."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the frame element."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        }
+      ]
+    },
+    {
+      "name": "Menu",
+      "description": "Action menu on the native Popover API top layer: the top layer and light dismiss come from the platform; Esc, roving keyboard, placement and dismissal reasons are Psi's (D53). Controlled-only, like Dialog (D50). Controlled-only means Menu does not change its own visibility. Esc and item-select *report* a dismissal via onClose(reason) and leave the popover open; only the consumer flipping `open` to false actually closes it. Esc calls preventDefault() to suppress the platform's own popover dismissal, which is what makes that possible. Light dismiss (outside click) is the one asymmetry, and it is forced by the platform: the browser hides the popover itself and the hide-side `beforetoggle` is not cancelable, so the popover is already closed by the time the resulting `toggle` lets us report onClose(\"outside\"). The consumer must still flip `open` to false so React's state matches the DOM. `toggle` therefore reports only that one reason. A close driven by the consumer (`open` true -> false) runs through the sync effect's own hidePopover(), which raises a `toggle` too — that one is suppressed, because a programmatic close is not a dismissal and must not call onClose.",
+      "slots": [
+        {
+          "name": "trigger",
+          "accepts": {
+            "contracts": [
+              "interactive"
+            ]
+          },
+          "cardinality": "1..1",
+          "order": 1
+        },
+        {
+          "name": "body",
+          "accepts": {
+            "components": [
+              "MenuItem",
+              "MenuSeparator"
+            ]
+          },
+          "cardinality": "1..*",
+          "order": 2
+        }
+      ],
+      "props": [
+        {
+          "name": "open",
+          "type": "boolean",
+          "required": true,
+          "default": null,
+          "description": "Controlled open state; syncs to showPopover()/hidePopover()."
+        },
+        {
+          "name": "onClose",
+          "type": "(reason: \"item-select\" | \"esc\" | \"outside\") => void",
+          "required": true,
+          "default": null,
+          "description": "Called when a dismissal is *requested*; the consumer flips `open`.\n\nMenu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays\nopen until `open` becomes false (D50). `\"outside\"` is the one exception:\nlight dismiss is performed by the browser before it tells us, so by the\ntime that reason is reported the popover is already closed. Flipping\n`open` to false is still required, to keep React's state in step.\n\nInvariant (D58): a dismissal is only ever reported for a menu that is\ncurrently open according to its own `open` prop. The platform can close\nan auto popover before the consumer's state catches up — clicking another\nmenu's trigger light-dismisses this one before the consumer's click\nhandler runs — and a report for an already-closed menu would clear a\nselection that has since moved on."
+        },
+        {
+          "name": "trigger",
+          "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>>",
+          "required": true,
+          "default": null,
+          "description": "The trigger element. Must be a single React element that spreads unknown\nprops onto a focusable node (a Psi `Button`, say): Menu clones it to add\n`aria-haspopup=\"menu\"` and `aria-expanded`, so assistive tech associates\nthe menu with the control users actually focus."
+        },
+        {
+          "name": "placement",
+          "type": "\"bottom-start\" | \"bottom-end\" | \"top-start\" | \"top-end\"",
+          "required": false,
+          "default": "bottom-start",
+          "description": "Placement relative to the trigger."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Accessible name for the menu when there is no visible label."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "MenuItem and MenuSeparator children."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the popover element."
+        }
+      ]
+    },
+    {
+      "name": "MenuItem",
+      "description": "One action in a Menu. Renders a real <button> so activation, Enter and Space come from the platform; the roving tabindex is applied by Menu's keyboard hook, which finds items via [data-psi-menu-item] (D53).",
+      "slots": [],
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "Item label."
+        },
+        {
+          "name": "onSelect",
+          "type": "() => void",
+          "required": true,
+          "default": null,
+          "description": "Fires on activation; Menu then reports the dismissal via onClose(\"item-select\") (D50)."
+        },
+        {
+          "name": "variant",
+          "type": "\"neutral\" | \"danger\"",
+          "required": false,
+          "default": "neutral",
+          "description": "danger is for destructive actions only (house rule)."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": ""
+        }
+      ]
+    },
+    {
+      "name": "MenuSeparator",
+      "description": "Hairline rule between Menu item groups. No props by design (D53).",
+      "slots": [],
+      "props": []
+    },
+    {
+      "name": "Table",
+      "description": "Data table on native table semantics. Holds no state: sorting, selection and pagination are the consumer's (D62, extending D50/D53).",
+      "slots": [
+        {
+          "name": "body",
+          "accepts": {
+            "components": [
+              "TableCaption",
+              "TableHead",
+              "TableBody"
+            ]
+          },
+          "cardinality": "1..*",
+          "order": 1
+        }
+      ],
+      "props": [
+        {
+          "name": "size",
+          "type": "32 | 40 | 48",
+          "required": false,
+          "default": 40,
+          "description": "Row height in px."
+        },
+        {
+          "name": "stickyHeader",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "Pins the header while the body scrolls."
+        },
+        {
+          "name": "sortable",
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Enables the sort affordance on header cells that declare a `sortKey`."
+        },
+        {
+          "name": "sort",
+          "type": "TableSortState | null",
+          "required": false,
+          "default": null,
+          "description": "Controlled sort state; `null` when nothing is sorted."
+        },
+        {
+          "name": "onSortChange",
+          "type": "((sort: TableSortState) => void)",
+          "required": false,
+          "default": null,
+          "description": "Called with the **next** sort state, already toggled — store it as given\nand do not toggle again. A fresh column arrives `\"asc\"`; an active `\"asc\"`\ncolumn emits `\"desc\"`; an active `\"desc\"` column emits `\"asc\"`.\n\nOptional in the type because `sortable` may be false; a discriminated union\nexpressing the real contract does not survive docgen's flat prop\nextraction, which would strip these props from the manifest entirely (D62)."
+        },
+        {
+          "name": "selectable",
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Renders the row-selection checkbox column."
+        },
+        {
+          "name": "selected",
+          "type": "ReadonlySet<string>",
+          "required": false,
+          "default": "new Set<string>()",
+          "description": "Controlled selection, keyed by each `TableRow`'s `rowId`."
+        },
+        {
+          "name": "onSelectionChange",
+          "type": "((selected: ReadonlySet<string>) => void)",
+          "required": false,
+          "default": null,
+          "description": "Called with the next selection. See `onSortChange` on why it is optional."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "TableHead and TableBody."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTableElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the underlying `<table>` element."
+        }
+      ]
+    },
+    {
+      "name": "TableHead",
+      "description": "`<thead>`. When the table is selectable, prepends the select-all cell to the FIRST header row so the header's column count matches the body's — the checkbox column is Table's, not the consumer's schema. Clones the row rather than rebuilding it, so the consumer's own props on that `TableRow` survive.",
+      "slots": [],
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
           "default": null,
           "description": "The header TableRow."
         },
@@ -1105,20 +1447,397 @@
           "required": false,
           "default": null,
           "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTableSectionElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the `<thead>`."
+        }
+      ]
+    },
+    {
+      "name": "TableBody",
+      "description": "`<tbody>` wrapper. Remaining attributes land on it (D85) — `aria-busy` while a page of rows loads, say.",
+      "slots": [],
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "The body TableRows."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTableSectionElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the `<tbody>`."
+        }
+      ]
+    },
+    {
+      "name": "TableRow",
+      "description": "`<tr>`. `rowId` is the key the `selected` set holds.",
+      "slots": [],
+      "props": [
+        {
+          "name": "rowId",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Stable identity for selection. Required for selectable tables (D62)."
+        },
+        {
+          "name": "selectLabel",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Accessible name for this row's selection checkbox."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "The row's cells."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTableRowElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the `<tr>`."
+        }
+      ]
+    },
+    {
+      "name": "TableHeaderCell",
+      "description": "`<th scope=\"col\">`. `aria-sort` belongs on the th, never on the inner button — assistive tech reads the sort state from the column header.",
+      "slots": [],
+      "props": [
+        {
+          "name": "sortKey",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Sort key this column emits. Enables the sort control when the table is `sortable`."
+        },
+        {
+          "name": "numeric",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "Right-aligns and renders tabular figures (D62)."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "Header label."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTableCellElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the `<th>`."
         }
       ]
     },
     {
-      "name": "TableBody",
-      "description": "`<tbody>` wrapper.",
+      "name": "TableCell",
+      "description": "`<td>`, or `<th scope=\"row\">` with `rowHeader`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose. Remaining attributes land on the cell (D85).",
+      "slots": [],
+      "props": [
+        {
+          "name": "numeric",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "Right-aligns and renders tabular figures (D62)."
+        },
+        {
+          "name": "colSpan",
+          "type": "number",
+          "required": false,
+          "default": null,
+          "description": "Columns the cell spans — an empty-state row spanning the table (D85)."
+        },
+        {
+          "name": "rowHeader",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "Renders `<th scope=\"row\">` instead of `<td>`: the cell that names its\nrow, an identifier say, so a screen reader reads it with every cell in\nthe row (D85). Styled as a cell, at medium weight."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "Cell content."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTableCellElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the cell element."
+        }
+      ]
+    },
+    {
+      "name": "TableCaption",
+      "description": "`<caption>` — the table's name, above it, and an optional detail line (D85). It names the table for assistive tech, which an `aria-label` on the `Table` would also do, but a caption is visible. A token-paged list has no page numbers to land on, so after a page change the consumer moves focus here: give it `tabIndex={-1}`, put the range in `detail`, and call `focus()` on the ref. The ring is the shared one (D82), drawn inside the caption's box. Remaining attributes land on the element.",
+      "slots": [],
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "The name line — what the table lists. Also the table's accessible name."
+        },
+        {
+          "name": "detail",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "An optional second line: the range shown, say — \"Rows 51–100 of more\nthan 100,000\"."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTableCaptionElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the `<caption>`, so focus can be moved to it."
+        }
+      ]
+    },
+    {
+      "name": "Pagination",
+      "description": "Numbered pager with ellipsis truncation (D63). Standalone rather than a Table family member: `table-pagination` composes it as a Toolbar sibling of the page-size Select.",
+      "slots": [],
+      "props": [
+        {
+          "name": "page",
+          "type": "number",
+          "required": true,
+          "default": null,
+          "description": "Current page, 1-based. A value outside `[1, pageCount]` (including\nnon-finite values like `NaN`) is clamped for rendering and logs a\n`console.warn` in development. `pageCount < 1` renders no page buttons."
+        },
+        {
+          "name": "pageCount",
+          "type": "number",
+          "required": true,
+          "default": null,
+          "description": "Total number of pages."
+        },
+        {
+          "name": "onPageChange",
+          "type": "(page: number) => void",
+          "required": true,
+          "default": null,
+          "description": "Called with the requested page. Required — unlike Table's `onSortChange`/\n`onSelectionChange`, which are optional because `sortable`/`selectable`\ngate whether they're meaningful, `Pagination` has no such gating boolean:\nthe prop is unconditionally meaningful, so a `Pagination` without it is a\ndead control (final review finding, D62)."
+        },
+        {
+          "name": "siblingCount",
+          "type": "number",
+          "required": false,
+          "default": 1,
+          "description": "Pages shown either side of the current one before truncating."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "default": "Pagination",
+          "description": "Accessible name for the nav landmark."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        }
+      ]
+    },
+    {
+      "name": "CursorPagination",
+      "description": "A pager for a list that pages by cursor (D85): a backend that returns a `nextPageToken` and no page count. Two `ghost` Buttons with visible words in a `<nav>`; the chevrons only reinforce them. A direction that is not available is disabled. It holds no state and knows nothing about pages — the consumer holds the tokens and answers `hasPrevious` / `hasNext`. A sibling of `Pagination`, not a mode of it: `Pagination`'s contract is a page count and numbers, and this one has neither.",
       "slots": [],
       "props": [
         {
-          "name": "children",
-          "type": "ReactNode",
-          "required": true,
+          "name": "hasPrevious",
+          "type": "boolean",
+          "required": true,
+          "default": null,
+          "description": "Whether a previous page exists — the consumer knows, from its tokens."
+        },
+        {
+          "name": "hasNext",
+          "type": "boolean",
+          "required": true,
+          "default": null,
+          "description": "Whether a next page exists."
+        },
+        {
+          "name": "onPrevious",
+          "type": "() => void",
+          "required": true,
+          "default": null,
+          "description": "Called when the user asks for the previous page."
+        },
+        {
+          "name": "onNext",
+          "type": "() => void",
+          "required": true,
+          "default": null,
+          "description": "Called when the user asks for the next page."
+        },
+        {
+          "name": "previousLabel",
+          "type": "string",
+          "required": false,
+          "default": "Previous",
+          "description": "Visible text of the previous button."
+        },
+        {
+          "name": "nextLabel",
+          "type": "string",
+          "required": false,
+          "default": "Next",
+          "description": "Visible text of the next button."
+        },
+        {
+          "name": "size",
+          "type": "32 | 40",
+          "required": false,
+          "default": 32,
+          "description": "Button height in px."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "default": "Pagination",
+          "description": "Accessible name for the nav landmark."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        }
+      ]
+    },
+    {
+      "name": "Toast",
+      "description": "A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. `politeness` (D83) only tells the region which wrapper to use. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.",
+      "slots": [
+        {
+          "name": "body",
+          "accepts": {},
+          "cardinality": "1..*",
+          "order": 1
+        },
+        {
+          "name": "action",
+          "accepts": {
+            "components": [
+              "Button"
+            ],
+            "contracts": [
+              "inline-content"
+            ]
+          },
+          "cardinality": "0..1",
+          "order": 2
+        }
+      ],
+      "props": [
+        {
+          "name": "variant",
+          "type": "\"neutral\" | \"success\" | \"warning\" | \"danger\"",
+          "required": false,
+          "default": "neutral",
+          "description": "Status variant."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "The message."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "Trailing affordance — a ghost Button (Undo, Retry, View)."
+        },
+        {
+          "name": "onDismiss",
+          "type": "(() => void)",
+          "required": false,
+          "default": null,
+          "description": "When provided, renders the dismiss button and calls this. Toast does not\nremove itself; the owner disposes."
+        },
+        {
+          "name": "politeness",
+          "type": "\"polite\" | \"assertive\"",
+          "required": false,
+          "default": null,
+          "description": "Which live wrapper ToastRegion routes this toast into (D83). Unset, the\nvariant decides: neutral and success are polite, warning and danger\nassertive. Set it when the kind of event, not its tone, decides — the\noutcome of the user's own action may interrupt even when it succeeded."
+        },
+        {
+          "name": "statusLabel",
+          "type": "string | null",
+          "required": false,
           "default": null,
-          "description": "The body TableRows."
+          "description": "The visually hidden status word (D83). A string replaces the default\n(\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null`\ndrops it. Unset keeps the default, and `neutral` has none."
         },
         {
           "name": "className",
@@ -1126,34 +1845,41 @@
           "required": false,
           "default": null,
           "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the underlying `<div>`."
         }
       ]
     },
     {
-      "name": "TableRow",
-      "description": "`<tr>`. `rowId` is the key the `selected` set holds.",
+      "name": "ToastRegion",
+      "description": "The positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `politeness`, then `variant`, off each child — the same Children.map technique Table uses for select-all injection. `politeness` wins (D83): the owner of an announcement knows what kind of event it is, and tone is only the default. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group. Remaining HTML attributes, `data-*` included, are spread onto the root element (D83). That is how an application marks the region `data-react-aria-top-layer`, so that a React Aria overlay — which hides everything outside itself with `aria-hidden` — leaves the two live regions exposed. The region's own attributes always win.",
       "slots": [],
       "props": [
         {
-          "name": "rowId",
-          "type": "string",
+          "name": "placement",
+          "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
           "required": false,
-          "default": null,
-          "description": "Stable identity for selection. Required for selectable tables (D62)."
+          "default": "bottom-end",
+          "description": "Corner the stack occupies."
         },
         {
-          "name": "selectLabel",
+          "name": "aria-label",
           "type": "string",
           "required": false,
-          "default": null,
-          "description": "Accessible name for this row's selection checkbox."
+          "default": "Notifications",
+          "description": "Accessible name for the region."
         },
         {
           "name": "children",
           "type": "ReactNode",
           "required": true,
           "default": null,
-          "description": "The row's cells."
+          "description": "The stack — `Toast` and `Announcement` elements, each routed to a live\nwrapper by its `politeness`, or by a Toast's variant when it names none."
         },
         {
           "name": "className",
@@ -1161,111 +1887,151 @@
           "required": false,
           "default": null,
           "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the region element."
         }
       ]
     },
     {
-      "name": "TableHeaderCell",
-      "description": "`<th scope=\"col\">`. `aria-sort` belongs on the th, never on the inner button — assistive tech reads the sort state from the column header.",
+      "name": "ToastProvider",
+      "description": "Owns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse.",
       "slots": [],
       "props": [
         {
-          "name": "sortKey",
-          "type": "string",
+          "name": "limit",
+          "type": "number",
           "required": false,
-          "default": null,
-          "description": "Sort key this column emits. Enables the sort control when the table is `sortable`."
+          "default": 3,
+          "description": "Max simultaneous toasts; the oldest is evicted first."
         },
         {
-          "name": "numeric",
-          "type": "boolean",
+          "name": "duration",
+          "type": "number",
           "required": false,
-          "default": null,
-          "description": "Right-aligns and renders tabular figures (D62)."
+          "default": 5000,
+          "description": "Auto-dismiss for toasts with no action, in ms."
         },
         {
-          "name": "children",
-          "type": "ReactNode",
+          "name": "actionDuration",
+          "type": "number",
           "required": false,
-          "default": null,
-          "description": "Header label."
+          "default": 10000,
+          "description": "Auto-dismiss for toasts carrying an action, in ms. An affordance that\nvanishes before it can be reached is not an affordance."
         },
         {
-          "name": "className",
-          "type": "string",
+          "name": "placement",
+          "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
           "required": false,
+          "default": "bottom-end",
+          "description": "Corner the stack occupies."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
           "default": null,
-          "description": "Additional CSS class name(s) merged onto the component's root element."
+          "description": "The subtree that may call `useToast()`. The region is rendered alongside it."
         }
       ]
     },
     {
-      "name": "TableCell",
-      "description": "`<td>`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose.",
+      "name": "Announcement",
+      "description": "Text for a screen reader only, spoken through ToastRegion (D83). **It is not a live region.** It renders no `role` and no `aria-live`, and outside a ToastRegion it announces nothing — the region's two persistent wrappers are the only live regions, and an Announcement is content for one of them. Do not use it as a second announcer. Use it where an event must be spoken and there is nothing to show: a state change of the object on screen, or field errors the form already displays. `politeness` is not read here. ToastRegion reads it off the element to pick a wrapper, the same way it reads a Toast's. Controlled, like Toast: it holds no state and never removes itself. Remove it once it has been spoken. To announce the same text again, remove it and render it again with a new `key` — a live region speaks changes, and an unchanged node is not one. It takes no `className`: the one thing a class could do to it is make it visible, and then it is a Toast.",
       "slots": [],
       "props": [
         {
-          "name": "numeric",
-          "type": "boolean",
+          "name": "politeness",
+          "type": "\"polite\" | \"assertive\"",
           "required": false,
-          "default": null,
-          "description": "Right-aligns and renders tabular figures (D62)."
+          "default": "\"polite\"",
+          "description": "Which of ToastRegion's two live wrappers speaks it."
         },
         {
           "name": "children",
           "type": "ReactNode",
-          "required": false,
-          "default": null,
-          "description": "Cell content."
-        },
-        {
-          "name": "className",
-          "type": "string",
-          "required": false,
+          "required": true,
           "default": null,
-          "description": "Additional CSS class name(s) merged onto the component's root element."
+          "description": "The text to announce."
         }
       ]
     },
     {
-      "name": "Pagination",
-      "description": "Numbered pager with ellipsis truncation (D63). Standalone rather than a Table family member: `table-pagination` composes it as a Toolbar sibling of the page-size Select.",
-      "slots": [],
+      "name": "Banner",
+      "description": "A full-width, page-level status message (D86). It is not a live region: it renders no `role` and no `aria-live`, so mounting one announces nothing, and announcing stays the application's — route the same event through a `ToastRegion` or an `Announcement` if it must be spoken. Controlled and presentational: it holds no state and never removes itself; `onDismiss` reports and the owner disposes. A tinted strip with no radius and no border, it is meant to span the page edge to edge, above the content. For the same message inside content, use `InlineAlert`.",
+      "slots": [
+        {
+          "name": "title",
+          "accepts": {},
+          "cardinality": "0..1",
+          "order": 1
+        },
+        {
+          "name": "body",
+          "accepts": {},
+          "cardinality": "1..*",
+          "order": 2
+        },
+        {
+          "name": "action",
+          "accepts": {
+            "components": [
+              "Button"
+            ],
+            "contracts": [
+              "inline-content"
+            ]
+          },
+          "cardinality": "0..1",
+          "order": 3
+        }
+      ],
       "props": [
         {
-          "name": "page",
-          "type": "number",
-          "required": true,
+          "name": "variant",
+          "type": "\"neutral\" | \"success\" | \"warning\" | \"danger\"",
+          "required": false,
+          "default": "neutral",
+          "description": "Status variant."
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": false,
           "default": null,
-          "description": "Current page, 1-based. A value outside `[1, pageCount]` (including\nnon-finite values like `NaN`) is clamped for rendering and logs a\n`console.warn` in development. `pageCount < 1` renders no page buttons."
+          "description": "A short heading, rendered before the body in the medium weight."
         },
         {
-          "name": "pageCount",
-          "type": "number",
+          "name": "children",
+          "type": "ReactNode",
           "required": true,
           "default": null,
-          "description": "Total number of pages."
+          "description": "The message."
         },
         {
-          "name": "onPageChange",
-          "type": "(page: number) => void",
-          "required": true,
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
           "default": null,
-          "description": "Called with the requested page. Required — unlike Table's `onSortChange`/\n`onSelectionChange`, which are optional because `sortable`/`selectable`\ngate whether they're meaningful, `Pagination` has no such gating boolean:\nthe prop is unconditionally meaningful, so a `Pagination` without it is a\ndead control (final review finding, D62)."
+          "description": "Trailing affordance — a ghost Button (Review, Retry, Learn more)."
         },
         {
-          "name": "siblingCount",
-          "type": "number",
+          "name": "onDismiss",
+          "type": "(() => void)",
           "required": false,
-          "default": 1,
-          "description": "Pages shown either side of the current one before truncating."
+          "default": null,
+          "description": "When provided, renders the dismiss button and calls this. Banner does not\nremove itself; the owner disposes."
         },
         {
-          "name": "aria-label",
-          "type": "string",
+          "name": "statusLabel",
+          "type": "string | null",
           "required": false,
-          "default": "Pagination",
-          "description": "Accessible name for the nav landmark."
+          "default": null,
+          "description": "The visually hidden status word (D83). A string replaces the default\n(\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null`\ndrops it. Unset keeps the default, and `neutral` has none."
         },
         {
           "name": "className",
@@ -1273,18 +2039,31 @@
           "required": false,
           "default": null,
           "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the underlying `<div>`."
         }
       ]
     },
     {
-      "name": "Toast",
-      "description": "A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.",
+      "name": "InlineAlert",
+      "description": "Not `role=\"alert\"`, despite its name. It is not a live region: it renders no `role` and no `aria-live`, so mounting one announces nothing, and announcing stays the application's — route the same event through a `ToastRegion` or an `Announcement` if it must be spoken. A status message that sits inside content (D86): above a form, in a panel. A tinted surface with a 1px border in the variant's colour and a radius; it fills the width of its container rather than setting its own. Presentational and stateless, with no dismiss button. For a page-wide strip, use `Banner`.",
       "slots": [
+        {
+          "name": "title",
+          "accepts": {},
+          "cardinality": "0..1",
+          "order": 1
+        },
         {
           "name": "body",
           "accepts": {},
           "cardinality": "1..*",
-          "order": 1
+          "order": 2
         },
         {
           "name": "action",
@@ -1297,7 +2076,7 @@
             ]
           },
           "cardinality": "0..1",
-          "order": 2
+          "order": 3
         }
       ],
       "props": [
@@ -1308,6 +2087,13 @@
           "default": "neutral",
           "description": "Status variant."
         },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "A short heading, rendered before the body in the medium weight."
+        },
         {
           "name": "children",
           "type": "ReactNode",
@@ -1320,14 +2106,14 @@
           "type": "ReactNode",
           "required": false,
           "default": null,
-          "description": "Trailing affordance — a ghost Button (Undo, Retry, View)."
+          "description": "Trailing affordance — a ghost Button (Review, Retry, Learn more)."
         },
         {
-          "name": "onDismiss",
-          "type": "(() => void)",
+          "name": "statusLabel",
+          "type": "string | null",
           "required": false,
           "default": null,
-          "description": "When provided, renders the dismiss button and calls this. Toast does not\nremove itself; the owner disposes."
+          "description": "The visually hidden status word (D83). A string replaces the default\n(\"Success:\", \"Warning:\", \"Error:\") — pass the translated word; `null`\ndrops it. Unset keeps the default, and `neutral` has none."
         },
         {
           "name": "className",
@@ -1346,30 +2132,30 @@
       ]
     },
     {
-      "name": "ToastRegion",
-      "description": "The positioned live region that holds the toast stack (D64). Two things here are load-bearing and both look like details: 1. **The two live wrappers are always rendered**, empty queue included. A live region announces mutations to a subtree that already existed; a wrapper that mounts together with its first toast reads as a new subtree, and that first toast is never announced. 2. **`popover=\"manual\"`, not `\"auto\"`.** Manual puts the region in the native top layer without light dismiss. The top layer is required because Dialog uses showModal() — also top layer — so a fixed region at --psi-z-overlay would paint *under* the modal backdrop, hiding the confirmation for the action a user just took inside a dialog. And `auto` would be dismissed by the very click that raised the toast. Routing reads `variant` off each child, the same Children.map technique Table uses for select-all injection. Consequence of the split, visible in the `InRegion` VR baseline: the stack is grouped by politeness, not strictly chronological — every assertive toast sorts below every polite one regardless of arrival order. Chronological order is preserved *within* each group. Keeping it exact across both would mean one live region with a politeness that changes per message, which is the thing the two wrappers exist to avoid. Accepted: at `limit` 3 the grouping reads as severity ordering, and the newest toast still lands nearest the screen edge within its group.",
+      "name": "Skeleton",
+      "description": "A loading placeholder. It is not a live region: it renders no `role` and no `aria-live`, and it is always `aria-hidden=\"true\"`, so assistive tech skips it entirely. Put `aria-busy` on the region the skeleton stands for — that is what tells a screen reader the content is coming. Its width fills the container; size the container, not the skeleton. The pulse is an opacity animation that stops under `prefers-reduced-motion: reduce` (D86).",
       "slots": [],
       "props": [
         {
-          "name": "placement",
-          "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+          "name": "variant",
+          "type": "\"text\" | \"block\"",
           "required": false,
-          "default": "bottom-end",
-          "description": "Corner the stack occupies."
+          "default": "text",
+          "description": "`text` renders `lines` stacked bars; `block` one box."
         },
         {
-          "name": "aria-label",
-          "type": "string",
+          "name": "lines",
+          "type": "number",
           "required": false,
-          "default": "Notifications",
-          "description": "Accessible name for the region."
+          "default": 1,
+          "description": "Number of text lines; the last of several is shorter. Text only."
         },
         {
-          "name": "children",
-          "type": "ReactNode",
-          "required": true,
-          "default": null,
-          "description": "The toast stack — `Toast` elements, routed to a live wrapper by variant."
+          "name": "size",
+          "type": "24 | 32 | 40 | 48",
+          "required": false,
+          "default": 40,
+          "description": "Height of a block, from the size scale. Block only."
         },
         {
           "name": "className",
@@ -1383,49 +2169,56 @@
           "type": "Ref<HTMLDivElement>",
           "required": false,
           "default": null,
-          "description": "Forwarded ref to the region element."
+          "description": "Forwarded ref to the underlying `<div>`."
         }
       ]
     },
     {
-      "name": "ToastProvider",
-      "description": "Owns the toast queue, its auto-dismiss timers, and the single ToastRegion (D65). This is the library's one stateful container, and the exception is deliberately narrow. D50 and D53 rejected internal state for Dialog and Menu because the consumer already owned the state that decided visibility — a menu is open because a user clicked a trigger the consumer rendered. A toast has no such owner: it is created by an outcome, not by a UI state, and it disappears on a timer nobody is watching. The rule that survives is the useful half — presentational components stay controlled (`Toast` still holds nothing), a stateful container may exist when the state has no natural owner, and it must be opt-in. Timers pause while the pointer or focus is inside the region (WCAG 2.2.1), and resume with the time *remaining* rather than a fresh full duration — restarting would let a user hold a toast open indefinitely by jiggling the mouse.",
+      "name": "CopyButton",
+      "description": "Not a live region: it renders no role and no `aria-live`, never changes its label or icon after a copy, and announces nothing. The application speaks the result — route `onCopy` through its announcer or a Toast (D86). Copies `value` to the clipboard when pressed. A `Button` with a leading `IconCopy` and a visible label; the icon only reinforces the word.",
       "slots": [],
       "props": [
         {
-          "name": "limit",
-          "type": "number",
+          "name": "value",
+          "type": "string",
+          "required": true,
+          "default": null,
+          "description": "The text written to the clipboard."
+        },
+        {
+          "name": "label",
+          "type": "string",
           "required": false,
-          "default": 3,
-          "description": "Max simultaneous toasts; the oldest is evicted first."
+          "default": "Copy",
+          "description": "Visible text of the button."
         },
         {
-          "name": "duration",
-          "type": "number",
+          "name": "size",
+          "type": "24 | 32 | 40 | 48",
           "required": false,
-          "default": 5000,
-          "description": "Auto-dismiss for toasts with no action, in ms."
+          "default": 32,
+          "description": "Button height in px."
         },
         {
-          "name": "actionDuration",
-          "type": "number",
+          "name": "variant",
+          "type": "\"accent\" | \"accent-subtle\" | \"neutral\" | \"neutral-subtle\" | \"ghost\" | \"danger\" | \"danger-subtle\" | \"outline\"",
           "required": false,
-          "default": 10000,
-          "description": "Auto-dismiss for toasts carrying an action, in ms. An affordance that\nvanishes before it can be reached is not an affordance."
+          "default": "ghost",
+          "description": "Button variant."
         },
         {
-          "name": "placement",
-          "type": "\"top-start\" | \"top-end\" | \"bottom-start\" | \"bottom-end\"",
+          "name": "onCopy",
+          "type": "((result: \"copied\" | \"failed\") => void)",
           "required": false,
-          "default": "bottom-end",
-          "description": "Corner the stack occupies."
+          "default": null,
+          "description": "Called with the outcome once the clipboard write settles. `\"failed\"` covers\na rejected write and an environment with no clipboard API."
         },
         {
-          "name": "children",
-          "type": "ReactNode",
-          "required": true,
+          "name": "className",
+          "type": "string",
+          "required": false,
           "default": null,
-          "description": "The subtree that may call `useToast()`. The region is rendered alongside it."
+          "description": "Additional CSS class name(s) merged onto the component's root element."
         }
       ]
     },