@box-kite/react 2.0.1 → 2.2.0

package/BOX_KITE_AI_CONTEXT.md

@@ -1,6 +1,6 @@
 # @box-kite/react - AI Assistant Context
 
-Runtime CSS-in-JS library. `Box` component accepts 221 CSS props and generates CSS classes at runtime. Same prop values share a single class.
+Runtime CSS-in-JS library. `Box` component accepts 235 CSS props and generates CSS classes at runtime. Same prop values share a single class.
 
 ---
 
@@ -282,9 +282,13 @@ const { css, anchorProps, layerProps } = useAnchorPosition({ side: 'bottom', ali
 The palette is **Tailwind 4.3's, in OKLCH**: twenty-six families of eleven steps (`50`–`950`) — the five
 neutrals (`slate`, `gray`, `zinc`, `neutral`, `stone`), the four Tailwind 4.3 added (`mauve`, `mist`,
 `olive`, `taupe`) and seventeen hues (`red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`,
-`teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`). Each token is a
-CSS variable declared in `:root` the first time something uses it, so a colour you never write costs
-nothing.
+`teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`). A token is a
+CSS variable written **with its own value as the fallback** — `bgColor="sky-500"` is
+`background-color: var(--sky-500,oklch(68.5% .169 237.3))` — so nothing is declared in `:root` (a late
+`:root` insert recalculates every element on the page) and declaring `--sky-500` yourself still overrides
+it. `var(--sky-500)` elsewhere in this file is that, shortened. Your own CSS cannot count on `--sky-500`
+existing: hand it a variable of yours with `vars={{ brand: 'violet-500' }}` on an ancestor. A hand-written
+`var(--sky-500)` _inside_ a Box value — `fill`, `vars`, `css`, a `Box.extend()` variable — gets the fallback too.
 
 Any colour value takes a slash and a percentage:
 
@@ -642,6 +646,131 @@ const wobble = Box.spring({ stiffness: 120, damping: 8 });
 
 ---
 
+### Scroll-driven animations
+
+An animation's progress can come from a scroll position rather than a clock. There is no listener, no
+`requestAnimationFrame` and no state: the browser runs it off the compositor, and the whole thing is props.
+
+| Prop                                        | CSS Property                 | Notes                                                                                                                                                 |
+| ------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `animationTimeline`                         | animation-timeline           | `'none'`, `'auto'`, an anonymous timeline (`'scroll()'`, `'scroll(root block)'`, `'view()'`, `'view(inline 20%)'`) or a name a declaration below gave |
+| `animationRange`                            | animation-range              | One end or both: `'entry'`, `'cover 20%'`, `'entry 0% entry 100%'`, `'normal'`                                                                        |
+| `animationRangeStart` / `animationRangeEnd` | animation-range-start / -end | One end at a time. A named part of the pass with an optional offset, a bare length, or `'normal'`                                                     |
+| `scrollTimeline`                            | scroll-timeline              | Declares a named timeline on a **scroller**: `'page'` or `'page block'`. The `--` is optional and added for you                                       |
+| `scrollTimelineName` / `scrollTimelineAxis` | scroll-timeline-name / -axis | The two halves of that shorthand. Axis: `'block'`, `'inline'`, `'x'`, `'y'`                                                                           |
+| `viewTimeline`                              | view-timeline                | Declares a named timeline on a **subject** — its own pass across the scrollport: `'card'` or `'card block'`                                           |
+| `viewTimelineName` / `viewTimelineAxis`     | view-timeline-name / -axis   | The two halves of that one                                                                                                                            |
+| `viewTimelineInset`                         | view-timeline-inset          | `'auto'`, or one or two lengths, shrinking the scrollport the pass is measured against                                                                |
+| `timelineScope`                             | timeline-scope               | Makes named timelines below this element reachable from anywhere else below it. Comma-separated                                                       |
+
+The two anonymous timelines cover most of it and need nothing declared elsewhere:
+
+```tsx
+// A reading-progress bar: the page's own scroll, driving a scaleX from 0 to 1.
+Box.keyframes({ progress: { from: { scale: 0 }, to: { scale: 1 } } });
+
+<Box
+  position="fixed"
+  top={0}
+  insetX={0}
+  height={1}
+  bgColor="sky-500"
+  css={{ transformOrigin: 'left' }}
+  animationName="progress"
+  animationTimeline="scroll(root)"
+  animationFillMode="both"
+  motionReduce={{ animation: 'none' }}
+/>;
+
+// Reveal on scroll: this element's own pass, over the first 60% of its entry.
+Box.keyframes({ 'fade-up': { from: { opacity: 0, translateY: 4 }, to: { opacity: 1, translateY: 0 } } });
+
+<Box animationName="fade-up" animationTimeline="view()" animationRange="entry 0% entry 60%" motionReduce={{ animation: 'none' }}>
+  …
+</Box>;
+```
+
+A **named** timeline is the two-sided form, for when the animated element is not inside the scroller:
+
+```tsx
+<Box timelineScope="page">
+  <Box height="fit-screen" overflow="auto" scrollTimeline="page block">
+    …
+  </Box>
+  <Box animationName="progress" animationTimeline="page" animationFillMode="both" />
+</Box>
+```
+
+**Three things to know, and all three are traps:**
+
+- **The CSS `animation` shorthand resets `animation-timeline`.** A timeline declared before it is
+  silently undone. The registry declares `animationTimeline` after `animation`, so writing both props is
+  safe in either order — but an `animation` written inside `css` sorts last and will undo it.
+- **A scroll-driven animation has no duration**, so `--transitionTime` cannot zero it. It is the one kind
+  of motion in this library that does **not** stop itself under `prefers-reduced-motion`: pair it with
+  `motionReduce={{ animation: 'none' }}`, every time.
+- **Where the browser has none, the declaration is dropped rather than the animation.** It then runs on the
+  document timeline over whatever duration it was given. Make the end state the resting state — with
+  `animationFillMode="both"` and a sequence that ends where the element belongs, a missing timeline degrades
+  to "already arrived" rather than to a loop. Chrome/Edge 115+, Safari 26+; Firefox is behind a flag.
+
+---
+
+### View transitions
+
+The browser screenshots the page, runs the update, screenshots again, and cross-fades between the two —
+so a change that was a jump becomes a transition with nothing animated by hand.
+
+| Prop / API                            | What it does                                                                                                                                         |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `viewTransitionName`                  | Names this element, so it animates _from where it was to where it is_ instead of being cross-faded with the page. A `<custom-ident>`, **not** dashed |
+| `viewTransitionClass`                 | A name shared by several elements, so `::view-transition-group(.card)` styles them together. Space-separated for more than one                       |
+| `Box.viewTransition(update, options)` | Runs `update` inside `document.startViewTransition` where the browser has one, and plainly where it has not                                          |
+| `<Box.Theme viewTransition>`          | That call around a theme change, `flushSync` included                                                                                                |
+
+```tsx
+const handle = Box.viewTransition(() => flushSync(() => setTab(next)), { types: ['forward'] });
+await handle.finished;
+```
+
+```ts
+interface ViewTransitionOptions {
+  /** `'skip'` (default) runs the update with no transition under reduced motion; `'play'` transitions anyway. */
+  reducedMotion?: 'skip' | 'play';
+  /** Types `:active-view-transition-type(name)` selects on, so forward and back can differ. */
+  types?: string[];
+}
+
+interface ViewTransitionHandle {
+  ready: Promise<void>;
+  finished: Promise<void>;
+  updateCallbackDone: Promise<void>;
+  skip(): void;
+  /** False when the browser had no API, or reduced motion skipped it. */
+  transitioned: boolean;
+}
+```
+
+**Four things to know:**
+
+- **In React the update has to be flushed.** The browser takes its second screenshot the moment the
+  callback returns, and a `setState` has not rendered by then — so a hand-rolled version captures the old
+  state twice and nothing appears to move. `flushSync` inside the callback is the fix, and
+  `<Box.Theme viewTransition>` is it already done for the one change every app has.
+- **A name has to be unique in the document while the transition runs.** Two elements sharing one is how a
+  transition silently does nothing. The prop is for the handful of names a layout has (`header`, `main`);
+  a name **per list item** is a rule per item that is never freed, so that one goes in
+  `props={{ style: { viewTransitionName: id } }}` — the exception `useAnchorPosition`'s anchor name and a
+  `Slider` thumb already take.
+- **Reduced motion skips the transition and keeps the update.** A whole-page cross-fade is exactly the
+  motion the preference is about. `{ reducedMotion: 'play' }` is the opt-out, for a change that is
+  unreadable without one.
+- **The handle is the same shape either way**, so there is one code path: with no API, `finished` is an
+  already-resolved promise, `skip()` a no-op and `transitioned` false. `ready` rejects when a transition is
+  skipped, which is not an error — branch on `finished`.
+
+---
+
 ## Pseudo-Classes, Breakpoints & Themes
 
 ```tsx
@@ -868,6 +997,7 @@ setTheme(null);     // reset to system auto-detection (clears localStorage)
 
 **Props**: `theme?` (string — explicit theme name), `use?` (`'global'`|`'local'`, default `'local'`), `storageKey?` (string — localStorage key for persistence), `globalStyles?` (BoxStyleProps — app-wide styles on `<html>`, only with `use="global"`).
 **DOM**: Sets `data-theme` attribute and theme class on wrapper (local) or `document.documentElement` (global). Cleaned up on unmount.
+**Nesting**: a theme reaches the subtree it owns and stops at the next element declaring one, so `<Box.Theme use="local" theme="light">` inside a dark page really is light. Each theme rule is `@scope (.light) to ([data-theme]) { :scope .className … }`, which is why `data-theme` marks a theme root — write it beside any theme class you set by hand (the `<html>` one in a prerendered shell). Needs Chrome 118+, Safari 17.4+, Firefox 128+.
 
 #### globalStyles — App-wide styles on `<html>`
 
@@ -1118,24 +1248,41 @@ second argument for an element inside an `<svg>`. `<Icon>` is this hook plus tha
 ### Server-Side Rendering
 
 ```tsx
-import { getStyles, resetStyles } from '@box-kite/react/ssg';
+import Box from '@box-kite/react';
+import { getStyleTag, resetStyles } from '@box-kite/react/ssg';
+
+Box.configure({ classNames: 'stable' }); // in the server AND in the browser entry
 
 const html = renderToString(<App />); // any React server renderer
-const cssString = getStyles(); // the CSS for what was just rendered
-// <style id="box-kite-styles">{cssString}</style> in the document head
+const styleTag = getStyleTag(); // <style id="box-kite-styles" data-box-kite="…">…</style>, for the head
 resetStyles(); // reset before the next request
 ```
 
-Or in one call, which injects the styles into the rendered `<head>` and resets afterwards:
+Or in one call, which injects the tag into the rendered `<head>` and resets afterwards:
 
 ```tsx
 import { renderToStaticMarkup } from '@box-kite/react/ssg';
 
-const { html, styles } = renderToStaticMarkup(<App />);
+const { html, styles, styleTag } = renderToStaticMarkup(<App />);
 ```
 
 No DOM is needed: with no `document` in the process the engine collects CSS in memory. Sequential
-requests are independent and identical markup gets identical class names.
+requests are independent and identical markup gets identical class names. `getStyles()` is the bare CSS.
+
+**Adoption.** The `data-box-kite` attribute is a manifest — each rule's cascade position and a checksum
+of the classes it styles. On the first render the browser engine checks it against the sheet it parsed
+and takes the sheet over: every rule in it counts as generated, so hydration builds and inserts nothing
+for what the HTML already styled, and only rules the client adds afterwards are inserted, each in its
+cascade position. Two conditions:
+
+| Condition                               | Why                                                                        | If it does not hold                                                           |
+| --------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `classNames: 'stable'` on both sides    | the content-hashed names are how the browser recognises the server's rules | the sheet is left in place under no id and the engine writes its own after it |
+| the browser parsed every generated rule | an index is only trustworthy if nothing in between was dropped             | same fallback                                                                 |
+
+Do **not** remove the server's `<style>` after hydration — it is the engine's own sheet now. Register
+the same `Box.extend()` props and `Box.keyframes()` sequences on both sides. `engine.getStyleTag()` is
+the same thing for `@box-kite/core`.
 
 ---
 
@@ -2138,7 +2285,7 @@ function TrendCell({ cell }: { cell: CellModel<Row> }) {
 9. **Theme styles nest**: `theme={{ dark: { hover: { ... } } }}`
 10. **HTML attributes go in `props` prop**: `<Link props={{ href: '/about' }}>` not `<Link href>`. `data-*` and `aria-*` go there too — a `data-state` written at the top level typechecks and is then dropped
 11. **Size shortcuts**: `width="fit"` = 100%, `width="fit-screen"` = 100vw, `width="1/2"` = 50%
-12. **Box is memoized** with `React.memo`
+12. **Box is memoized** with `React.memo`, and so are `Flex`, `H1`, `Button` and the rest. A component of your own that is a Box with defaults calls `useBoxElement({ p: 4, ...props }, ref)` from its own `forwardRef` rather than returning `<Box>` — one fiber instead of two
 13. **`style` is top-level only** — never inside breakpoints (`sm={{ style: ... }}`), pseudo-classes, or theme objects. `css` is the one that nests: `sm={{ css: { objectPosition: 'top' } }}` is a rule
 14. **A CSS variable is a prop**: `vars={{ 'color-x': 'sky-500' }}` declares `--color-x` for everything inside — and a third-party chart goes in `<ChartContainer series={['revenue']}>` so it names no colour at all
 15. **All sizing props use divider 4** — `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` are NOT direct pixels. `height={10}` = 2.5rem = 40px
@@ -2208,7 +2355,9 @@ the element wrapping the bars, the rows and the pager. Every callback below is a
 | `expandedRowKeys` / `onExpandedRowKeysChange` | `Key[]` / `(keys, { reason })`                           | Controlled expanded rows; reason: `expand`/`collapse`                                      |
 | `globalFilterValue` / `onGlobalFilterChange`  | `string` / `(value, { reason })`                         | Controlled global filter; reason: `filter`/`clear`                                         |
 | `columnFilters` / `onColumnFiltersChange`     | `ColumnFilters` / `(filters, { reason })`                | Controlled column filters; reason: `filter`/`clear`                                        |
-| `onCellEditsChange`                           | `(edits, { reason })`                                    | Every accepted edit, oldest first; reason: `edit`/`clear`                                  |
+| `onCellEditsChange`                           | `(edits, { reason })`                                    | Every accepted edit, oldest first; reason: `edit`/`paste`/`clear`                          |
+| `onRangeChange`                               | `(range, { reason })`                                    | The block of cells marked, or `undefined`; reason: `select`/`extend`/`clear`               |
+| `onPaste`                                     | `(paste)`                                                | One Ctrl+V: `{ range, applied, rejected, skipped }`, once for the whole block              |
 
 `onSelectionChange(event)`, `onSortChange(key, dir)`, `onPageChange(page, size)` and
 `onPageSizeChange(size)` are the pre-contract spellings of the four above. They still fire; the
@@ -2242,6 +2391,8 @@ named ones carry the reason.
 | `noDataComponent`         | `ReactNode`                           | `'empty'`   | Custom empty state                                                                                             |
 | `footer`                  | `boolean \| { label? }`               | `false`     | A pinned row of grand totals over every column with an `aggregate`. `label` replaces the default `Total`       |
 | `export`                  | `boolean \| ExportConfig`             | `false`     | Export buttons in the top bar: `{ csv?, xlsx?, fileName? }`. The writers load on the first press               |
+| `tabNavigation`           | `'none' \| 'cells'`                   | `'none'`    | What Tab does. `'none'` is APG's single tab stop; `'cells'` is the spreadsheet reading                         |
+| `rangeSelection`          | `boolean`                             | `false`     | A drag or Shift+arrow marks a block of cells, and `Ctrl+C`/`Ctrl+V` copy and paste it as TSV (see below)       |
 
 ### ColumnType
 
@@ -2471,6 +2622,95 @@ the same function — and an answer to an edit the user has since abandoned is d
   value was refused — and `datagrid.body.cell.editor` (`isPending`) and `datagrid.body.cell.error` are
   the editor and its message.
 
+### Range selection and the clipboard
+
+Every grid marks the cell its arrows carry on from — whether the pointer or the keyboard put it there —
+and the mark **survives the grid losing focus**. `Ctrl+C` on it copies that cell, with no opt-in.
+`def.rangeSelection` is the rest: a drag, or Shift with the arrow keys, marks a rectangle, and `Ctrl+C`
+writes it as the tab-separated text a spreadsheet pastes as columns.
+
+```tsx
+<DataGrid
+  data={people}
+  def={{
+    rowKey: 'id',
+    rangeSelection: true,
+    columns: [
+      { key: 'name', header: 'Name' },
+      { key: 'country', header: 'Country' },
+      { key: 'salary', header: 'Salary', align: 'end' },
+    ],
+  }}
+  onRangeChange={(range, { reason }) => setSum(sumOf(range?.values()))}
+/>
+```
+
+- **The mark is state, not a focus ring.** `:focus-visible` never matches a pointer, so a _clicked_ cell
+  drew nothing (bug #64), and any ring made of focus goes out with it — leaving a copy with nothing to act
+  on. It is the corner a Shift+arrow grows the block from, and after a drag it is the cell the drag ended
+  on, so the ring, the tab stop and the next Shift+arrow are one cell.
+- **Extending:** drag across cells, hold Shift with the arrow keys (Home/End, Ctrl+Home/End and
+  PageUp/PageDown extend too), or Shift+press to extend from wherever the block was anchored. A move with
+  no modifier collapses the block onto the cell it landed on.
+- **A block is selected; one cell is a cursor.** The cells of a block carry `aria-selected` and the grid is
+  `aria-multiselectable`; a lone current cell carries neither, because it has chosen nothing. The block is
+  tinted _around_ the current cell, which keeps its ring — the way a sheet says where typing would land.
+- **What is copied is what a file would carry.** The clipboard is an export: a column's `exportValue` wins
+  where it has one, an accepted edit wins over the row, and a group row copies its own value in the column
+  that spans it. Fields are joined with tabs and rows with CRLF; a field carrying a tab, a newline or a
+  quote is quoted with its quotes doubled. The copy rides the browser's own `copy` event, so text you have
+  selected on the page still belongs to the page.
+- **Marking cells is a drag, so text selection is not.** A grid with `rangeSelection` on gives text
+  selection up; an open editor hands it back for the value being typed. A press that lands on a widget
+  belongs to the widget, and a touch is left alone entirely — that press is how the grid scrolls.
+- **`onRangeChange(range, { reason })`** reports `{ startRow, endRow, columns, values() }` or `undefined`,
+  with `select` / `extend` / `clear`. Rows are **indices into the rows on screen** rather than keys,
+  because a block may reach rows a datasource has not fetched — and `values()` is a call for the same
+  reason, gathering the rectangle when it is asked for.
+- Style nodes: `datagrid.body.cell` gains `isCurrentCell` (the ring) and `isInRange` (the tint).
+
+### Paste: Ctrl+V, one judgement per cell
+
+The block goes back the other way. `Ctrl+V` fills from the current cell — or from the block that is marked,
+where one is — and every cell it covers goes through the same `def.onCellEdit` an editor would, so a paste
+needs no second validator and no second way of writing a value. It needs no opt-in either: `rangeSelection`
+only gives it a bigger target.
+
+```tsx
+<DataGrid
+  data={people}
+  def={{
+    rowKey: 'id',
+    rangeSelection: true,
+    columns: [
+      { key: 'name', header: 'Name', editable: true },
+      { key: 'salary', header: 'Salary', align: 'end', editable: true },
+    ],
+    onCellEdit: ({ columnKey, value }) => (columnKey === 'salary' && Number(value) < 0 ? 'Salary cannot be negative' : undefined),
+  }}
+  onPaste={({ applied, rejected, skipped }) => setReport({ applied, rejected, skipped })}
+/>
+```
+
+- **Each axis takes whichever is longer, the block or the clipboard.** A block bigger than the clipboard is
+  tiled with it, a clipboard bigger than the block spills past it, and both stop at the edge of the grid.
+  One rule, with the degenerate case falling out of it: a paste onto the current cell alone starts from a
+  block of one.
+- **A refusal skips its own cell and nothing else.** A paste is many independent judgements, and stopping at
+  the first bad value would leave the block half written with no way back. The refused cells wear the red
+  ring (`datagrid.body.cell`'s `isInvalid`, with no editor open behind it) and report `aria-invalid`, so the
+  cells say which ones and `onPaste` says why.
+- **The clipboard carries no types, so the cell says how to read the text.** A number column parses it and
+  refuses what is not a number, a checkbox takes `true`/`false` (and `1`/`0`), and a `select` keeps to its
+  own options and holds the option's value rather than its spelling. A value that did not change is not an
+  edit at all, so pasting a column back over itself costs nothing.
+- **A paste that reaches an open editor belongs to the editor** — that is a value being typed, not a block
+  being filled — and a cell that cannot be edited at all is skipped before anything is asked about it, so a
+  validator only ever hears about cells that could have taken a value.
+- **`onPaste({ range, applied, rejected, skipped })`** fires once for the whole block, after the values have
+  landed, so `range.values()` reads what the grid now shows. Everything it accepted lands in the same
+  stream a typed value does: `onCellEditsChange(edits, { reason: 'paste' })`.
+
 ### ContextMenuConfig
 
 | Prop    | Type      | Default | Description                                                               |
@@ -2802,3 +3042,483 @@ Also accepts: `data` (TRow[]), `value`/`defaultValue`, `label`/`labelProps`, `mu
 3. **CSS variables**: In `:root` rules
 4. **Theme issues**: Ensure `<Box.Theme>` wraps your app
 5. **Layer theming**: a tooltip or dropdown popup stays where it was declared and inherits the theme; only the no-Popover-API fallback uses the `#box-kite-portal` container
+6. **Read the console first**: outside a production build the engine prints one `[box-kite]` warning per mistake that would otherwise be silent, each naming the fix:
+
+   | You wrote                  | The warning says                                                           |
+   | -------------------------- | -------------------------------------------------------------------------- |
+   | `bgColor="bleu-500"`       | wrote no CSS … Did you mean `"blue-500"`?                                  |
+   | `opacity={50}`             | wrote no CSS … It takes one of 0, 0.1, … 1                                 |
+   | `<Link href="/about">`     | `href` is an HTML attribute … write `props={{ href: ... }}`                |
+   | `fontSize={4}`             | is 4px text … For 16px write `fontSize={16}`                               |
+   | `lineHeight={1.5}`         | is a 1.5px line … `lineHeight="font-size"`, or `css={{ lineHeight: 1.5 }}` |
+   | `transitionDuration={0.3}` | is 0.3ms … For 0.3s write `transitionDuration={300}`                       |
+   | `brightness={1.1}`         | is 1.1% … For 110% write `brightness={110}`                                |
+
+   Once per value, and `Box.configure({ warnings: false })` silences them. In production a rejected value is dropped with nothing said, which is why `check_styles` (`@box-kite/mcp`) exists
+
+---
+
+---
+
+## Dashboard (`components/dashboard`)
+
+A grid of widgets people rearrange, and a layout a model can write. Two components and one artifact:
+`<DashboardGrid>` places, `<Widget>` is the chrome, and the layout is plain JSON in cells.
+
+```tsx
+import DashboardGrid, { DashboardUtils, Widget } from '@box-kite/react/components/dashboard';
+import { Sparkline } from '@box-kite/react/components/chart';
+
+<DashboardGrid layout={layout} onLayoutChange={setLayout} onLayoutCommit={save} editable label="Sales">
+  <Widget id="revenue" title="Revenue" description="Last 12 weeks">
+    <Sparkline data={revenue} variant="area" width="100%" height="100%" />
+  </Widget>
+  <Widget id="orders" title="Orders" onRefresh={reload} loading={pending} />
+</DashboardGrid>;
+```
+
+### The layout
+
+```jsonc
+{
+  "version": 1,
+  "columns": 12,
+  "items": [
+    { "id": "revenue", "x": 0, "y": 0, "w": 6, "h": 2 },
+    { "id": "orders", "x": 6, "y": 0, "w": 6, "h": 2, "minW": 3, "fixed": false },
+  ],
+}
+```
+
+`x`/`y` are zero-based cells, `w`/`h` spans. `minW`/`minH`/`maxW`/`maxH` bound a resize, and `fixed`
+pins a widget: it is never moved or resized and has no handles at all. The layout is **compacted
+upward**, so a widget cannot be parked in mid-air and two dashboards of the same widgets in the same
+places compare equal. A widget dropped on a neighbour **takes the cell**, and the neighbour is handed one
+of its own — the row above where there is room for it, the row below otherwise. That is `moveTo`'s half
+of it; compaction is reading order and nothing else.
+
+### DashboardGridProps
+
+| Prop                       | Type                                               | What it does                                                                                |
+| -------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `layout` / `defaultLayout` | `DashboardLayout`                                  | Controlled and uncontrolled. Normalized on the way in, so a generated one need not be tidy. |
+| `onLayoutChange`           | `ChangeHandler<DashboardLayout, DashboardReason>`  | Every cell a drag crosses, and every arrow key.                                             |
+| `onLayoutCommit`           | `ChangeHandler<DashboardLayout, DashboardReason>`  | Once when the interaction ends — the one to write to a server.                              |
+| `columns`                  | `number \| Partial<Record<DashboardSize, number>>` | One count, or one per container size. Default `{ xs: 1, md: 6, xxl: 12 }`.                  |
+| `rowHeight`                | `number`                                           | The height of one row, ÷4 scale. Default `24` (6rem).                                       |
+| `editable`                 | `boolean`                                          | The edit/view split: no handles and nothing in the tab order without it.                    |
+| `label` / `labelledBy`     | `string`                                           | Names the `role="list"` of widgets.                                                         |
+
+`DashboardReason` is `'move' | 'resize' | 'imperative'` — which _device_ did it is in `details.event`.
+
+### WidgetProps
+
+| Prop                          | Type                        | What it does                                                                             |
+| ----------------------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `id`                          | `string`                    | The layout item it fills. Without one it is a card with the same chrome.                 |
+| `title` / `description`       | `ReactNode`                 | The title bar. `title` is a real heading at `level` (default `3`).                       |
+| `name`                        | `string`                    | What the handles and the announcements call it. Defaults to a string `title`, then `id`. |
+| `actions`                     | `ReactNode`                 | The end of the title bar — a menu, a filter, a link out.                                 |
+| `loading` / `error` / `empty` | `boolean` / `ReactNode` / … | The three states that replace the content; anything else renders the children.           |
+| `onRefresh` / `refreshLabel`  | `() => void` / `string`     | A refresh button in the bar, and the retry an error state offers.                        |
+
+### Placement is a class; only a drag is an inline style
+
+A widget's cell is `gridColumnStart`/`gridColumnEnd`/`gridRowStart`/`gridRowEnd` — props, so a shared
+class — which is why a resting dashboard measures nothing and renders on a server. The one inline style
+in the component is the translate that keeps a dragged widget under the pointer.
+
+`columns` as a record projects the one layout into each declared space by arithmetic, written as a
+container query. **A grid cannot container-query itself** (the query resolves against an ancestor
+container), so every projection is drawn on the widest arrangement's tracks. And an arrangement can only
+be edited in the space it is written in: where a projection is showing, the handles are not rendered.
+
+### The keyboard, and what it says
+
+Both handles are real buttons. Enter or Space picks the widget up (`aria-pressed`), the arrows move or
+resize it a cell at a time following the **reading order**, Enter drops it and Escape puts it back — the
+whole layout with it. A grab that loses focus is cancelled rather than dropped. Every step is announced
+in a polite live region that exists before there is anything to say.
+
+### The model (`DashboardUtils`)
+
+Framework-free, exported from the same module:
+
+```ts
+DashboardUtils.SCHEMA; // the layout as JSON Schema — the subset catalog() emits
+DashboardUtils.parse(value); // { layout, issues } from a database, a file or a model
+DashboardUtils.add(layout, { id: 'latency', w: 3, h: 2 }); // placed under everything, then floated up
+DashboardUtils.remove(layout, 'latency');
+DashboardUtils.moveTo(layout, 'revenue', 3, 0); // what a drag does
+DashboardUtils.resizeTo(layout, 'revenue', 6, 3);
+DashboardUtils.project(layout, 6); // the same layout in a narrower space
+```
+
+`parse` clamps what is out of range (a generated `w: 0`, a column count of 400), drops what it cannot
+read and reports it rather than throwing. Where a dashboard is **kept** is the app's decision.
+
+### Style tree
+
+`dashboard` (+ `placeholder`) and `widget` (+ `header`, `label`, `title`, `description`, `actions`,
+`handle`, `body`, `message`, `retry`, `skeleton`). Both handles are the one `handle` node, whose
+`corner` variant is the resize one; the row height is a variable (`vars={{ 'dashboard-row': '8rem' }}`),
+so it can be set per breakpoint or per theme.
+
+## Agent chrome (`components/agent`)
+
+The parts of an agent's turn that are not prose — what it ran, what it was thinking, what it wants
+permission to do — plus the text it answers with. One entry, four components, and a framework-free model
+behind them.
+
+```tsx
+import { AgentUtils, ApprovalCard, Reasoning, StreamingText, ToolCallCard } from '@box-kite/react/components/agent';
+
+<Reasoning duration={1400}>{reasoningText}</Reasoning>
+<ToolCallCard name="searchOrders" status="success" input={{ orderId: 4182 }} output={{ total: 6400 }} />
+<ApprovalCard
+  title="Refund order 4182"
+  description="6,400 MDL back to the customer. This cannot be undone."
+  input={{ orderId: 4182, amount: 6400 }}
+  onDecisionChange={(decision) => respond(decision === 'approved')}
+/>;
+```
+
+### ToolCallCard
+
+| Prop                                    | Type                                                | What it does                                                                        |
+| --------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `name`                                  | `ReactNode`                                         | The tool, as the model called it. Required, and what the header reads.              |
+| `description`                           | `ReactNode`                                         | A line under the name, in the app's own words.                                      |
+| `status`                                | `'pending' \| 'running' \| 'success' \| 'error'`    | Default `pending`. Every state carries its own **word** beside the dot.             |
+| `input` / `output` / `error`            | `unknown`                                           | Shown under `inputLabel`/`outputLabel`/`errorLabel`, formatted rather than trusted. |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` / … / `ChangeHandler<boolean, 'trigger'>` | The body's state. Closed by default.                                                |
+| `collapsible`                           | `boolean`                                           | Default `true`. `false` leaves the header a plain row.                              |
+| `valueLimit`                            | `number`                                            | Characters before a value is cut. Default 20,000.                                   |
+
+The four statuses map one for one onto what every runtime reports under its own spelling — AI SDK's
+`input-streaming` / `input-available` / `output-available` / `output-error` — so wiring a message part
+to a card is a lookup rather than a state machine. `aria-busy` while running.
+
+**A card with nothing to disclose renders no control at all**: the header is a row of text rather than a
+button, because a control that opens nothing is a tab stop nobody wants to land on.
+
+### ApprovalCard
+
+| Prop                                                | Type                                                                               | What it does                                                              |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `title`                                             | `ReactNode`                                                                        | Required. Names the `role="group"`.                                       |
+| `description`                                       | `ReactNode`                                                                        | The consequence, and whether it can be undone.                            |
+| `input` / `inputLabel`                              | `unknown` / `ReactNode`                                                            | The call being gated, shown as a tool card shows its input.               |
+| `decision` / `defaultDecision` / `onDecisionChange` | `'approved' \| 'rejected' \| null` / … / `ChangeHandler<…, 'approve' \| 'reject'>` | The one channel.                                                          |
+| `busy`                                              | `boolean`                                                                          | The answer is on its way: both buttons disabled, `aria-busy` on the card. |
+| `approveLabel` / `rejectLabel`                      | `ReactNode`                                                                        | Default `Approve` / `Reject`.                                             |
+| `autoFocus`                                         | `boolean`                                                                          | Default `false`. Lands on **Reject** — the least destructive action.      |
+
+`onDecisionChange(decision, { reason })` maps straight onto AI SDK 6's `needsApproval`, CopilotKit's
+`renderAndWaitForResponse` and AG-UI's `INTERRUPT`. Once there is a decision the buttons are gone, and
+the answer lands in a `role="status"` **that was in the DOM before there was anything in it** — a live
+region inserted together with its text is not reliably announced.
+
+### Reasoning
+
+| Prop                                    | Type        | What it does                                                                      |
+| --------------------------------------- | ----------- | --------------------------------------------------------------------------------- |
+| `label`                                 | `ReactNode` | Default `Reasoning`, or `Thinking…` while `streaming`.                            |
+| `streaming`                             | `boolean`   | Still arriving: the header says so, shimmers, and reports `aria-busy`.            |
+| `duration`                              | `number`    | Milliseconds. The header reads "Thought for 4.2s" once it is over.                |
+| `open` / `defaultOpen` / `onOpenChange` | …           | Closed by default. Auto-opening while streaming is the app's: `open={streaming}`. |
+
+It opens in the same one-row grid an `Accordion` panel does — a track running `1fr` to `0fr`, so nothing
+is measured and the rules are shared with every other disclosure on the page.
+
+### The model (`AgentUtils`)
+
+Framework-free, exported from the same module — a tool's arguments are JSON a **model** invented, and
+`JSON.stringify` answers a circular structure, a `BigInt` and a four-megabyte result with a throw, a
+throw and a frozen frame:
+
+```ts
+AgentUtils.formatValue(part.output, 4000); // { text, truncated } — capped, never throws
+AgentUtils.hasValue(part.input); // `0` and `''` are values; `null` and `undefined` are not
+AgentUtils.formatCount(3980); // '3,980' — grouped here rather than by locale, so a prerender matches
+AgentUtils.formatDuration(4200); // '4.2s'
+AgentUtils.statusLabel('success'); // 'Done'
+AgentUtils.decisionLabel('approved'); // 'Approved'
+```
+
+### Style tree
+
+`toolCall` (+ `header`, `summary`, `name`, `description`, `status` with `status.dot`, `arrow`, `track`,
+`clip`, `body`, `section`, `label`, `value`, `truncated`), `approval` (+ `title`, `description`,
+`section`, `label`, `value`, `truncated`, `footer`, `actions`, `button`, `decision`) and `reasoning`
+(+ `trigger`, `arrow`, `duration`, `track`, `clip`, `body`). The status is a variant on
+`toolCall.status`, the decision one on `approval` itself, and `toolCall.header`'s `interactive` variant
+is what makes it look pressable — so a card with nothing to open does not.
+
+### StreamingText
+
+What the agent _says_, as it arrives. Same entry.
+
+| Prop        | Type      | What it does                                                                         |
+| ----------- | --------- | ------------------------------------------------------------------------------------ |
+| `text`      | `string`  | The message **so far**, not the delta — knowing what is new means comparing the two. |
+| `streaming` | `boolean` | More is coming: the caret shows and the element reports `aria-busy`.                 |
+| `window`    | `number`  | How many arrived runs stay faded at once. Default 8; `0` turns the entrance off.     |
+| `caret`     | `boolean` | Default `true`.                                                                      |
+
+```tsx
+<StreamingText text={message} streaming={status === 'streaming'} />
+```
+
+What is on the page is one settled string plus the last few runs to arrive, so a message that is already
+whole paints at once with nothing animating — a prerendered page, a transcript read back — and one still
+arriving costs the same at the ten-thousandth token as at the first. Anything but an append (a
+regenerate, an edit) settles at once rather than fading in the part that differs.
+
+The entrance is `@starting-style`, not a keyframe, so it rides `--transitionTime` and disappears under
+`prefers-reduced-motion` with nothing declared for it; the caret is the `pulse` preset. It is **not** a
+live region — one announcing every token reads the message out a word at a time and again when it
+finishes — so what announces the turn is the transcript it lands in. Tree: `streamingText` (+ `segment`,
+`caret`).
+
+`AgentUtils.initialStream`, `advanceStream` and `streamText` are the model behind it, framework-free and
+pure: advancing is keyed on the text rather than on a counter, so doing it twice is doing it once.
+
+## Markdown (`components/markdown`)
+
+`markdownComponents` is the `components` map `react-markdown`, Streamdown and everything built on that
+shape already take, with this engine's classes on it — **not** a renderer, because a parser is a choice
+an app has usually already made, and wrapping Streamdown would ask the project for a Tailwind `@source`
+line and shadcn's design tokens in a global stylesheet.
+
+```tsx
+import Markdown from 'react-markdown';
+import { markdownComponents } from '@box-kite/react/components/markdown';
+
+<Box component="markdown">
+  <Markdown components={markdownComponents}>{message}</Markdown>
+</Box>;
+```
+
+Three things to know. It is a **constant, not a factory**: a map built inside render is a new set of
+component _types_ every token, which React answers by unmounting the whole message and mounting it again
+— override by spreading at module scope (`{ ...markdownComponents, h1: MyHeading }`). Whether a URL is
+safe stays the **renderer's** (`urlTransform`, `defaultUrlTransform`), because the href is parsed before
+a component is called; the map sets `rel="noreferrer"`. And wrapping in `<Box component="markdown">` is
+what gives the block its size and colour, which the nodes inherit.
+
+Covers `h1`–`h6`, `p`, `a`, `ul`, `ol`, `li`, `blockquote`, `code`, `pre`, `hr`, `img`, `table`,
+`thead`, `tbody`, `tr`, `th`, `td`, `strong`, `em`, `del` and a task list's `input`. Tree: `markdown`
+(+ `heading` with `level1`–`level6`, `paragraph`, `link`, `list`, `item`, `quote`, `code`, `codeBlock`
+with `language` and `code`, `rule`, `image`, `tableWrap`, `table`, `row`, `cell`, `inline`, `checkbox`).
+
+## Skeleton (`components/skeleton`)
+
+Where content will be, while it is being fetched.
+
+| Prop     | Type        | What it does                                                                 |
+| -------- | ----------- | ---------------------------------------------------------------------------- |
+| `lines`  | `number`    | How many bars. Default 1; past that the last one is short.                   |
+| `circle` | `boolean`   | One round bar — an avatar. `width` sets its size and the height follows.     |
+| `label`  | `ReactNode` | Makes it a `role="status"` naming what is on its way. Absent: `aria-hidden`. |
+
+```tsx
+<Skeleton lines={3} label="Loading orders" />
+<Skeleton circle width={10} />
+```
+
+A `label` belongs on the one skeleton standing for a region and not on each bar — a screen of
+placeholders each announcing itself is a screen nobody can listen to, and a region inserted together
+with its text is not reliably announced anyway, so what it really buys is words for somebody who lands
+there. The gloss is a named duration in milliseconds, so it sits outside what `--transitionTime` zeroes
+and stops itself under `prefers-reduced-motion`. It renders on a server. Tree: `skeleton` (+ `bar` with
+`short` and `circle` variants, `gloss`).
+
+## The catalog (`@box-kite/react/catalog`)
+
+What a **generated** UI is allowed to build, as JSON Schema — the runtime counterpart to everything
+above, which is for whatever writes the code at dev time. A generative-UI runtime (json-render,
+assistant-ui, CopilotKit, A2UI) takes a component catalog; this is that catalog, read off the live prop
+registry rather than written down.
+
+```ts
+import { catalog } from '@box-kite/react/catalog';
+
+const allowed = catalog({ include: ['Flex', 'H2', 'P', 'Sparkline'], styleProps: ['d', 'gap', 'p', 'bgColor', 'fontSize'] });
+
+allowed.components.Flex.props; // a strict JSON Schema: additionalProperties false, colours patterned to the palette
+allowed.rules; // the dividers — what a schema cannot state and a prompt must
+allowed.tokens; // the colours, the @keyframes names and the style-tree nodes a host may restyle
+```
+
+- **The engine says what a prop accepts, the manifest says what it means.** Values come off the live
+  registry, so a `Box.extend()` prop or colour is in the catalog with nothing regenerated — call
+  `catalog()` after the `extend()`. Prose is generated from the same JSDoc as the prop reference.
+- **A colour prop is a `pattern` over the palette**, so a generated tree cannot invent `#ff00ff`. Every
+  closed value list is an `enum`; a prop the registry leaves open is `{ type: 'string' }` with its
+  values as `examples`, never a constraint the library does not enforce.
+- **Function props are `events`** (named, for the host to bind) and a `ReactNode` prop is a **slot**
+  (`children` is `default`). A prop a JSON spec cannot express is left out rather than half-described.
+- **The props that are a _shape_ are described by hand**, since the other half of each is React:
+  `DataGrid`'s `def` (required — the columns and the grid-wide flags) and `data`, `DashboardGrid`'s
+  `layout`/`defaultLayout`/`columns`, `Widget`'s `empty`, `ChartContainer`'s `series`. A column's nested
+  `columns`, and `dataSource`/`onCellEdit`/`rowDetail`/`treeData`, stay out — they are the app's to pass.
+- **The allow-list is the app's.** `catalog()` with no options is all 78 components and all 235 props —
+  ~4.6 MB serialized. `include`, `exclude` and `styleProps` are how an app narrows it.
+
+Full reference: `docs/catalog.md`.
+
+---
+
+## The spec renderer (`@box-kite/react/spec`)
+
+The other half of the catalog: the catalog says what a model may write, this renders what it wrote.
+Nothing in it imports Box — the components are the app's, handed over in a registry — so the entry
+carries no engine.
+
+```tsx
+import { catalog } from '@box-kite/react/catalog';
+import Flex from '@box-kite/react/components/flex';
+import { H2, P } from '@box-kite/react/components/semantics';
+import SpecRenderer, { createSpecRegistry } from '@box-kite/react/spec';
+
+const allowed = catalog({ include: ['Flex', 'H2', 'P'], styleProps: ['d', 'gap', 'p', 'bgColor', 'fontSize'] });
+const registry = createSpecRegistry({ catalog: allowed, components: { Flex, H2, P } });
+
+<SpecRenderer spec={spec} registry={registry} data={data} onAction={(action, details) => run(action, details)} />;
+```
+
+A node is JSON, and these are all the fields it has:
+
+| Field      | What it is                                                                                   |
+| ---------- | -------------------------------------------------------------------------------------------- |
+| `type`     | The component. A name the registry does not hold renders nothing.                            |
+| `props`    | Everything that component's own schema allows. A prop it refuses is dropped, not the node.   |
+| `children` | The default slot: nodes, text, or `{ $data }` references to text.                            |
+| `slots`    | A named slot (`Tooltip`'s `content`, a control's `label`).                                   |
+| `on`       | An event the catalog lists, bound to an action name: `{ onClick: 'refresh' }`.               |
+| `repeat`   | A reference to an array. The node renders once per item, with `$item` and `$index` in scope. |
+| `key`      | React's key, where a node's identity has to survive a re-order.                              |
+
+```jsonc
+{
+  "type": "Flex",
+  "props": { "d": "column", "gap": 4, "bgColor": "sky-500/10" },
+  "children": [
+    { "type": "H2", "props": { "fontSize": 24 }, "children": ["Revenue"] },
+    { "type": "P", "children": [{ "$data": "summary" }] },
+  ],
+}
+```
+
+- **The registry is the allow-list.** `createSpecRegistry({ catalog, components })` pairs an
+  implementation with the catalog's rules for it; a component of your own takes `{ component, props,
+slots, events }` with its own JSON Schema, and one registered **without** a schema takes no props at
+  all.
+- **Only an `event` can become a function.** `on` binds nothing else, and what an action does is the
+  host's — `onAction(action, { payload, args, prop, component, path })`. There is no tag from the
+  spec, no `eval` and no `dangerouslySetInnerHTML`.
+- **A reference resolves before it is validated.** `{ $data: 'stats.revenue' }` (a dot path or a JSON
+  Pointer), `{ $item: 'label' }` and `{ $index: true }` read from `data`, own properties only, and the
+  resolved value is what the schema judges.
+- **A partial spec is the normal case.** A node with no `type` yet renders nothing and reports nothing;
+  a half-written value fails its schema and is dropped until it is whole.
+- **One node cannot take the tree down.** Every node has an error boundary; `fallback` is what stands
+  in its place (nothing, by default), and `maxNodes` (1,000) and `maxDepth` (32) end a runaway tree.
+- **Everything refused is reported.** `onIssues` gets a `{ code, path, message, component, prop }` per
+  render whose issues changed: `unknown-component`, `unknown-prop`, `invalid-prop`, `unknown-slot`,
+  `unknown-event`, `unresolved-data`, `missing-prop`, `invalid-child`, `invalid-repeat`, `too-deep`,
+  `too-many-nodes`, `render-error`.
+- **A node missing a prop it cannot do without is held back.** A required prop that has not arrived —
+  or was refused — would be `undefined` inside the component, so the node renders nothing and reports
+  `missing-prop` instead of throwing into its own boundary once a frame.
+- **A generated node writes the controlled prop, never the `default…` twin.** `layout` not
+  `defaultLayout`, `value` not `defaultValue`: React reads an uncontrolled default once, so the frame
+  it first arrived whole in is the one that sticks, and a second spec rendered in the same place keeps
+  the first one's state.
+- **What a node has been shown with, it is not stripped of.** A stream is not monotone — a column's
+  `align` passes through `"e"` on its way to `"end"`, and that takes the whole `def` with it — so
+  `<SpecRenderer>` keeps the last value each node was given for a prop it cannot render without. It
+  remembers while it is mounted; `key` it to forget. Gating a heavy component is the app's call:
+  point its name at a placeholder in the registry while the spec is arriving.
+
+`specSchema(source, { bindings, root })` is the other direction: one JSON Schema for a whole tree, for
+`streamObject`, a structured-output API or `z.fromJSONSchema`. **Import it from
+`@box-kite/react/catalog` in a route handler** — it is exported there too, and that entry renders
+nothing, where `/spec` carries a `use client` banner; it takes a `catalog()` as readily as a registry,
+so the server half of the loop needs no components. `renderSpec(spec, options)` is the same walk with
+no hook in it — it returns `{ element, issues }`, so a static spec renders on a server.
+
+Full reference: `docs/catalog.md`.
+
+## Ecosystem interop (`@box-kite/react/interop`)
+
+The agentic runtimes' shapes and this library's, mapped onto each other. It **imports none of them**:
+an adapter that pulled in a runtime would be choosing one for the app. Framework-free and engine-free,
+so a route handler and a client both import from it.
+
+```ts
+import { toolPart, applyToolEvent } from '@box-kite/react/interop';
+import { a2uiApply, a2uiEmpty, a2uiSurface, a2uiToSpec, a2uiCatalog, a2uiComponentSchema } from '@box-kite/react/interop';
+import { fromGenerativeUi, toGenerativeUi } from '@box-kite/react/interop';
+```
+
+`toolPart(part)` reads a part from AI SDK, assistant-ui or CopilotKit and answers
+`{ kind, status, decision, input, output, error }` — `kind` is `'call'` or `'approval'`, `status` is
+the `pending`/`running`/`success`/`error` `<ToolCallCard>` takes, and `null` means it is not a tool part
+at all. **A decision is not a stage a call passes through, it is a question somebody answers**, which is
+why two components cover six states:
+
+| Runtime      | Call                                                                  | Question                                  |
+| ------------ | --------------------------------------------------------------------- | ----------------------------------------- |
+| AI SDK 6/7   | `input-streaming` `input-available` `output-available` `output-error` | `approval-requested` `approval-responded` |
+| assistant-ui | `status.type` `running` `complete` `incomplete`                       | `requires-action`, under either reason    |
+| CopilotKit   | `inProgress` `executing` `complete`                                   | `executing` holding a `respond`           |
+| AG-UI        | `TOOL_CALL_START` `_ARGS` `_END` `_RESULT`                            | `INTERRUPT`                               |
+
+**AG-UI reports events, not parts**, so its cards are a fold rather than a mapping:
+`applyToolEvent(parts, event)`, one call per event, oldest first, keyed by `toolCallId`.
+
+### A2UI
+
+The only genuinely different shape here: a **flat adjacency list** of components referring to each other
+by id, arriving one message at a time, with a data model of its own per surface.
+
+```tsx
+const [state, setState] = useState(a2uiEmpty);
+// v0.8 and v0.9 both. Pure, and the same state back when a message changed nothing.
+const next = (message: unknown) => setState((current) => a2uiApply(current, message));
+const surface = a2uiSurface(state);
+
+<SpecRenderer spec={a2uiToSpec(surface, { catalog })} registry={registry} data={surface?.data} onAction={run} />;
+```
+
+- **Its data binding is already `$data`.** `{ "path": "/user/email" }` is a JSON Pointer, which `$data`
+  has always taken — a rename, not a parse. The surface's own data model goes in `<SpecRenderer data>`.
+- **A template is a `repeat`.** `children: { componentId, path }` is one node per item of an array.
+- **A half-arrived surface is the ordinary case.** A component nothing reaches from the root is not
+  rendered yet; a cycle in the id graph is cut rather than walked.
+- **`id`, `component`, `child`, `children` and `action` never reach the registry as props.** `action`
+  becomes an `on` binding under that name, so an app registering Box components under A2UI's own names
+  declares `events: ['action']` on them. Pass `{ catalog }` instead where the agent generated against
+  this library, and a prop the catalog calls an event is bound as one.
+
+`a2uiCatalog(catalog(), { catalogId })` is the other direction — `catalog()` as an A2UI catalog
+document, where a component carries its own `id`, its type is a property rather than the key above it,
+and its children are **ids**. Serve it at the `catalogId` you gave it.
+
+### assistant-ui, CopilotKit, json-render
+
+`fromGenerativeUi(spec)` reads their `GenerativeUISpec` (`component` where this says `type`, a bare
+string child that renders as text) and `toGenerativeUi(node)` goes back, returning `{ spec, losses }`:
+their nodes carry no data binding, no repeat and no action channel, so what could not come along is
+**reported** rather than dropped in silence. Tool UI is `makeAssistantToolUI` with the cards in it.
+
+CopilotKit is two surfaces. Its A2UI renderer takes Zod, so `z.fromJSONSchema` over the catalog document
+is the bridge — and **a `$ref` resolves against the document, not against the piece you lifted out of
+it**, so `a2uiComponentSchema(document, name)` is what to convert (measured: zod 4.6 throws
+`Reference not found: #/$defs/color` otherwise). Its actions take a render function, where `render` is a
+call being shown and `renderAndWaitForResponse` is a question whose `respond` is what
+`onDecisionChange` calls. json-render is the same `z.fromJSONSchema` over `catalog()` itself.
+
+Full reference: `docs/interop.md`.