@box-kite/react 2.0.1 → 2.2.0

package/docs/interop.md

@@ -0,0 +1,237 @@
+# Ecosystem interop
+
+`@box-kite/react/interop` is this library's shapes and four other runtimes' shapes, mapped onto each
+other. It is framework-free, carries no engine, and depends on none of them — an adapter that imported a
+runtime would be choosing it for the app, and the app has already chosen.
+
+There are two things every agentic runtime describes, in words of its own:
+
+- **A tool call.** Where it is, what it was given, what it answered, and whether it is waiting on a
+  person. `<ToolCallCard>` and `<ApprovalCard>` (`components/agent`) draw the two halves of it.
+- **A tree of components.** A name resolved against an allow-list the app owns, JSON props, children.
+  `catalog()` says what may be in it and `<SpecRenderer>` renders it.
+
+```ts
+import { toolPart, a2uiApplyAll, a2uiSurface, a2uiToSpec, a2uiCatalog } from '@box-kite/react/interop';
+```
+
+## The tool state, in one vocabulary
+
+`toolPart(part)` reads a part from AI SDK, assistant-ui or CopilotKit and answers in this library's
+words: `{ kind, status, decision, input, output, error }`, where `kind` is `'call'` or `'approval'` and
+`status` is the `pending`/`running`/`success`/`error` a `<ToolCallCard>` takes.
+
+```tsx
+import { toolPart } from '@box-kite/react/interop';
+import { ToolCallCard, ApprovalCard } from '@box-kite/react/components/agent';
+
+function Part({ part }: { part: unknown }) {
+  const mapped = toolPart(part);
+
+  if (!mapped) return null;
+  if (mapped.kind === 'approval') return <ApprovalCard title="Approve this call?" onDecisionChange={respond} />;
+
+  return <ToolCallCard name="searchOrders" status={mapped.status} input={mapped.input} output={mapped.output} />;
+}
+```
+
+**A decision is not a stage a call passes through, it is a question somebody answers** — which is why
+two components cover what AI SDK reports as six states, and why the runtimes that report four are the
+ones whose human-in-the-loop lives on a second channel:
+
+| Runtime      | What it reports                                                                                                      | Where the question is                                 |
+| ------------ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| AI SDK 6/7   | `input-streaming`, `input-available`, `output-available`, `output-error`, `approval-requested`, `approval-responded` | Two of the six states, with `approval.approved`       |
+| assistant-ui | `status: { type: 'running' \| 'complete' \| 'incomplete' \| 'requires-action' }`                                     | `requires-action`, under either of its two reasons    |
+| CopilotKit   | `status: 'inProgress' \| 'executing' \| 'complete'`                                                                  | `renderAndWaitForResponse`, which hands you `respond` |
+| AG-UI        | `TOOL_CALL_START` / `_ARGS` / `_END` / `_RESULT` events                                                              | `INTERRUPT`                                           |
+
+**AG-UI is the odd one out, and it is worth knowing why**: it reports _events_, not parts, so its cards
+need a fold rather than a mapping. `applyToolEvent(parts, event)` is that fold — one call per event,
+oldest first, keyed by `toolCallId`.
+
+```ts
+import { applyToolEvent } from '@box-kite/react/interop';
+
+const parts = events.reduce(applyToolEvent, {});
+```
+
+## A2UI
+
+[A2UI](https://a2ui.org/) is the declarative UI protocol Google published, and the one CopilotKit and
+Oracle converged on. Its wire shape is the only one in this family that is genuinely different: 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. `<SpecRenderer>` renders a tree, so this is a real adapter rather than a
+rename.
+
+### Their messages, rendered here
+
+`a2uiApplyAll` folds a message stream into the surfaces it names, and `a2uiToSpec` turns one surface's
+adjacency list into the tree the renderer takes. Both v0.8 and v0.9 are read; the fold is **pure and
+hands the same state back when a message changed nothing**, so holding it in `useState` re-renders when
+the surface moved and not when a message arrived for a different one.
+
+```tsx
+import { useState } from 'react';
+import { a2uiApply, a2uiEmpty, a2uiSurface, a2uiToSpec } from '@box-kite/react/interop';
+import SpecRenderer from '@box-kite/react/spec';
+
+function Surface({ registry, catalog }) {
+  const [state, setState] = useState(a2uiEmpty);
+
+  useA2uiStream((message) => setState((current) => a2uiApply(current, message)));
+
+  const surface = a2uiSurface(state);
+
+  return <SpecRenderer spec={a2uiToSpec(surface, { catalog })} registry={registry} data={surface?.data} onAction={run} />;
+}
+```
+
+Three things the two models already agreed on, each a special case that did not have to be written:
+
+- **A2UI's data binding is already ours.** `{ "path": "/user/email" }` is a JSON Pointer, and `$data` has
+  taken a JSON Pointer since it was written, so a binding is a rename rather than a parse. The surface's
+  own data model is what goes in `<SpecRenderer data>`.
+- **A template is a `repeat`.** `children: { componentId, path }` is one node per item of an array, which
+  is exactly what `repeat` means, so a list that streams costs nothing extra.
+- **A half-arrived surface is the ordinary case.** An agent streams a leaf before the branch that holds
+  it; a component nothing reaches from the root is simply not rendered yet, and appears when the message
+  naming it does. A cycle in the id graph is cut rather than walked.
+
+What A2UI owns rather than the component — `id`, `component`, `child`, `children`, `action` — never
+reaches the registry as a prop. **`action` becomes an `on` binding under that name**, because what it
+means belongs to the component it lands on: an app registering Box components under A2UI's own names
+(`Text`, `Button`, `Row`) declares `events: ['action']` on them.
+
+```ts
+createSpecRegistry({
+  components: {
+    Button: { component: Button, events: ['action'], props: BUTTON_PROPS },
+    Column: { component: Flex, props: COLUMN_PROPS },
+  },
+});
+```
+
+Where the agent generated against _this library's_ catalog instead, pass it — then a prop the catalog
+calls an event is bound as one and the rest are values:
+
+```ts
+a2uiToSpec(surface, { catalog: catalog({ include: ['Flex', 'H2', 'Button'] }) });
+```
+
+### Our components, generated for
+
+`a2uiCatalog(catalog())` is `catalog()` as an A2UI catalog document — the same components and the same
+values their props take, in the shape around them that an adjacency list needs: a component carries its
+own `id`, its type is a property rather than the key above it, and its children are **ids** rather than
+nested nodes. Every event becomes a string, because a JSON message cannot carry a function: what an agent
+writes is the name of an action, and `onAction` is where the host decides what it does.
+
+```ts
+import { catalog } from '@box-kite/react/catalog';
+import { a2uiCatalog } from '@box-kite/react/interop';
+
+export const document = a2uiCatalog(catalog({ include: ['Flex', 'H2', 'Sparkline'], styleProps: ['p', 'gap', 'bgColor'] }), {
+  catalogId: 'https://example.com/a2ui/box-kite.json',
+});
+```
+
+**Serve it at the `catalogId` you gave it**, which is what an agent's `createSurface` names.
+
+## CopilotKit
+
+Two surfaces, and they want opposite directions.
+
+**Its A2UI renderer** (`@copilotkit/a2ui-renderer`) takes a catalog built from Zod schemas and React
+renderers. `z.fromJSONSchema` is the whole of the bridge — which is why `catalog()` emits JSON Schema at
+all. One trap, measured against zod 4.6: **a `$ref` resolves against the document, not against the piece
+you lifted out of it**, so converting a component on its own throws `Reference not found: #/$defs/color`.
+`a2uiComponentSchema(document, name)` is that component with the document's definitions attached.
+
+```tsx
+import { createCatalog } from '@copilotkit/a2ui-renderer';
+import * as z from 'zod';
+import { a2uiCatalog, a2uiComponentSchema } from '@box-kite/react/interop';
+
+const document = a2uiCatalog(catalog({ include: ['Flex', 'H2', 'P'] }));
+const names = Object.keys(document.components);
+
+const definitions = Object.fromEntries(
+  names.map((name) => [name, { props: z.fromJSONSchema(a2uiComponentSchema(document, name)), description: '' }]),
+);
+
+// Their renderer hands a component its resolved props and a `children(id)` — the adjacency list again.
+const renderers = { Flex: ({ props, children }) => <Flex {...props}>{props.children?.map(children)}</Flex> };
+
+export const boxKiteCatalog = createCatalog(definitions, renderers, { catalogId: document.catalogId });
+```
+
+**Its actions** (`useCopilotAction`) take a render function, so the cards go in as they are. `render` is a
+call being shown; `renderAndWaitForResponse` is a question, and the `respond` it hands you is what
+`onDecisionChange` calls.
+
+```tsx
+useCopilotAction({
+  name: 'refundOrder',
+  parameters: [{ name: 'orderId', type: 'number' }],
+  renderAndWaitForResponse: ({ args, respond }) => (
+    <ApprovalCard title={`Refund order ${args.orderId}`} onDecisionChange={(decision) => respond?.(decision === 'approved')} />
+  ),
+});
+```
+
+## assistant-ui
+
+Its `GenerativeUISpec` and this library's `SpecNode` are the same idea arrived at twice. Three
+differences, and they are the whole adapter: the name is `component` rather than `type`, a child may be a
+bare string that renders as text, and their nodes carry no data binding, no repeat and no action channel
+— in their design those are the tool's job rather than the spec's.
+
+`fromGenerativeUi(spec)` reads theirs and gives back an array of `SpecNode` (several roots stay several
+roots; wrapping them in a container nobody asked for would change the layout). `toGenerativeUi(spec)`
+goes the other way, and **reports what it could not carry** rather than emitting a tree that renders half
+a view in silence:
+
+```ts
+const { spec, losses } = toGenerativeUi(node);
+// losses: [{ code: 'data-binding' | 'repeat' | 'event', path }]
+```
+
+**Its Tool UI** is a component per tool name, and the cards go in as they are:
+
+```tsx
+import { makeAssistantToolUI } from '@assistant-ui/react';
+import { ToolCallCard } from '@box-kite/react/components/agent';
+import { toolPart } from '@box-kite/react/interop';
+
+export const SearchOrdersUI = makeAssistantToolUI({
+  toolName: 'searchOrders',
+  render: (part) => <ToolCallCard name="searchOrders" {...toolPart(part)} />,
+});
+```
+
+## json-render
+
+[`@json-render/react`](https://json-render.dev) wants a Zod schema per component, and `z.fromJSONSchema`
+is again the whole adapter — the recipe is in
+[generative-ui.md](generative-ui.md#rendering-it-somewhere-else-json-render), with the measured caveat
+that its own `validate` lets any props through once a catalog holds more than one component, so each
+node still wants checking against its own schema.
+
+## What is verified, and how
+
+Every runtime named here is a devDependency of this repository, and `src/interop.test.tsx` runs the
+adapters against the published packages rather than against a memory of them:
+
+| Claim                                                        | Checked against                                  |
+| ------------------------------------------------------------ | ------------------------------------------------ |
+| `toGenerativeUi` emits their `GenerativeUISpec`              | `@assistant-ui/core`'s own type                  |
+| `fromGenerativeUi` reads their `GenerativeUINode`            | the same                                         |
+| every member of their `ToolCallMessagePartStatus` union maps | the same                                         |
+| `a2uiCatalog` is a document their `createCatalog` accepts    | `@copilotkit/a2ui-renderer`'s published function |
+| a surface generated against it renders here                  | the fold and `a2uiToSpec`, end to end            |
+| the catalog is one json-render accepts, and validates a spec | `@json-render/react`, in `src/catalog.test.tsx`  |
+
+The two cases A2UI's own conformance suite keeps for a message processor — that an update lands on the
+surface it names and nowhere else, and that each surface owns its data model — are in
+`src/utils/interop/a2uiInterop.test.ts` in the vocabulary that suite uses.

package/docs/mcp.md

@@ -0,0 +1,70 @@
+# @box-kite/mcp
+
+The [Box Kite](https://www.box-kite.dev) MCP server: the retrieval channel for an agent writing Box
+Kite code. Six tools, at capability level — what may I write, what does this component take, and the
+one no documentation mirror can answer: **does this value actually work.**
+
+```bash
+npx @box-kite/mcp
+```
+
+No key, no network, no state. Everything it answers with was built into it from the library's own
+repository at the version you install, including the styling engine itself. Node 22 or newer.
+
+## Install
+
+**Claude Code**
+
+```bash
+claude mcp add box-kite -- npx -y @box-kite/mcp
+```
+
+**Cursor, VS Code, Codex, Zed** — anything that speaks stdio:
+
+```json
+{
+  "mcpServers": {
+    "box-kite": { "command": "npx", "args": ["-y", "@box-kite/mcp"] }
+  }
+}
+```
+
+## The tools
+
+| tool            | what it answers                                                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search_docs`   | The prop, component, nesting key or rule for what you are trying to build — ranked across all four, so a goal finds the answer without its name.  |
+| `get_props`     | A style prop's whole record: the CSS it writes, every value it accepts, a measured example, and for a numeric prop its scale measured at 1/2/4/8. |
+| `get_component` | One component's contract: props and defaults, sub-parts, the keyboard map and the ARIA it writes.                                                 |
+| `check_styles`  | A prop bag through the real engine: the CSS each prop writes, or why it wrote none.                                                               |
+| `get_rules`     | The rules the library is written by, as an index or in full.                                                                                      |
+| `get_blocks`    | Whole sections the `shadcn` CLI installs — a data-grid page, a settings form, a dashboard shell.                                                  |
+
+## Why `check_styles` exists
+
+Box Kite accepts a closed set of values per prop, and **a value it does not accept produces no rule
+and no class name**, by design, because a typo must not emit a broken declaration. A development
+build warns in the console once the page renders; a production one says nothing at all. The way to
+answer "does `bgColor="blue-550"` work" before anything renders is to hand it to the engine:
+
+```
+check_styles { "props": { "p": 4, "bgColor": "blue-550", "fontSize": 14, "lineHeight": 1.5, "href": "/about" } }
+
+✅ `p` → `.p-4{padding:1rem}`
+❌ `bgColor` does not accept "blue-550" — no rule and no class name were written.
+✅ `fontSize` → `.fontSize-14{font-size:0.875rem}`
+⚠️ `lineHeight` → `.lineHeight-1\.5{line-height:1.5px}` — lineHeight={1.5} is a 1.5px line: lineHeight is direct pixels, …
+⚠️ `href` an HTML attribute, not a style prop. It goes in `props={{ "href": … }}`.
+```
+
+The dividers differ per prop — spacing is ÷4, `fontSize` is ÷16, border width is direct px — which is
+why `get_props` measures a scale rather than describing one.
+
+## What else the library ships for agents
+
+- `AGENTS.md` and `docs/` inside the published `@box-kite/react` package
+- The skill and rules file: `npx skills add box-kite/box-kite`
+- Every documentation page as markdown at `https://www.box-kite.dev/<route>.md`, indexed by
+  [llms.txt](https://www.box-kite.dev/llms.txt)
+
+MIT © Box Kite

package/docs/props.md

@@ -1,4 +1,4 @@
-# Every prop (221)
+# Every prop (235)
 
 Generated from the prop registry of `@box-kite/react`. The description is the prop's own doc comment and the example is **measured** — the CSS beside a value is what the engine emits for it, not what a doc claims. Alphabetical; the registry's own order is what decides the cascade and is not this.
 
@@ -14,7 +14,7 @@ The accent-color CSS property tints the parts of a native control the page does
 
 - Writes: `accent-color`
 - Values: 304 named values, anything else the types allow
-- Example: `accentColor="sky-500"` → `accent-color: var(--sky-500)`
+- Example: `accentColor="sky-500"` → `accent-color: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `ai`
 
@@ -112,6 +112,38 @@ The animation-play-state CSS property sets whether an animation is running or pa
 - Values: `running` · `paused`
 - Example: `animationPlayState="running"` → `animation-play-state: running`
 
+### `animationRange`
+
+The shorthand that sets both ends of the range at once: one value sets the start and leaves the end at `normal`, two set both. `entry` is the whole of the element coming into view, `cover 0% cover 50%` the first half of its pass across the scrollport. Only meaningful beside a view timeline.
+
+- Writes: `animation-range`
+- Values: whatever the types allow
+- Example: `animationRange="entry"` → `animation-range: entry`
+
+### `animationRangeEnd`
+
+Where along the timeline the animation finishes: a named part of the pass (`cover`, `contain`, `entry`, `exit`, `entry-crossing`, `exit-crossing`), an offset into one, or a plain length.
+
+- Writes: `animation-range-end`
+- Values: whatever the types allow
+- Example: `animationRangeEnd="exit"` → `animation-range-end: exit`
+
+### `animationRangeStart`
+
+Where along the timeline the animation starts. Same values as the end, and the pair is what turns "when this element is scrolled past" into "while it is entering, and no longer".
+
+- Writes: `animation-range-start`
+- Values: whatever the types allow
+- Example: `animationRangeStart="entry 25%"` → `animation-range-start: entry 25%`
+
+### `animationTimeline`
+
+What drives the animation — a scroll position rather than a clock, so there is no rAF loop, no scroll listener and no state. `scroll()` is the nearest scrollport's progress (`scroll(root)` the page's), `view()` this element's progress through it; both need nothing declared anywhere else. A name is a timeline `scrollTimeline`/`viewTimeline` declared elsewhere. Two things to know. **It is declared after `animation`**, because the CSS shorthand resets this property to `auto` — the registry's order is what stops `animation="spin"` quietly undoing it. And a scroll-driven animation has **no duration**, so `--transitionTime` cannot reach it and reduced motion needs saying out loud: `motionReduce={{ animation: 'none' }}`.
+
+- Writes: `animation-timeline`
+- Values: `none` · `auto`, anything else the types allow
+- Example: `animationTimeline="scroll()"` → `animation-timeline: scroll()`
+
 ### `animationTimingFunction`
 
 How an animation progresses through each cycle: a keyword, one of the four sampled springs, or a curve of your own — `cubic-bezier()`, `steps()` and `linear()` are values. A spring names its duration too.
@@ -254,7 +286,7 @@ The background-color CSS property sets the background color of an element.
 
 - Writes: `background-color`
 - Values: 304 named values, anything else the types allow
-- Example: `bgColor="sky-500"` → `background-color: var(--sky-500)`
+- Example: `bgColor="sky-500"` → `background-color: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `bgGradient`
 
@@ -262,7 +294,7 @@ A gradient written as a value: the key names the kind and carries its geometry (
 
 - Writes: `background-image`
 - Values: whatever the types allow
-- Example: `bgGradient={{ linear: 'r', colors: ['blue-500', 'pink-500'] }}` → `background-image: linear-gradient(to right,var(--blue-500),var(--pink-500))`
+- Example: `bgGradient={{ linear: 'r', colors: ['blue-500', 'pink-500'] }}` → `background-image: linear-gradient(to right,var(--blue-500,oklch(62.3% .214 259.8)),var(--pink-500,oklch(65.6% .241 354.3)))`
 
 ### `bgImage`
 
@@ -270,7 +302,7 @@ The background-image CSS property sets one or more background images on an eleme
 
 - Writes: `background-image`
 - Values: `gradient-primary` · `gradient-aurora-light` · `gradient-aurora-dark` · `gradient-accent` · `bg-img-checked` · `bg-img-indeterminate` · `bg-img-radio` · `none`
-- Example: `bgImage="gradient-primary"` → `background-image: var(--gradient-primary)`
+- Example: `bgImage="gradient-primary"` → `background-image: var(--gradient-primary,linear-gradient(135deg, #6366f1 0%, #8b5cf6 50%, #a855f7 100%))`
 
 ### `bl`
 
@@ -282,7 +314,7 @@ The border-left-width CSS property sets the width of the left border of an eleme
 
 ### `blur`
 
-How far the element's own pixels are blurred: a step of Tailwind's scale (`xs` 4px through `xxxl` 64px) or a radius in px. One of nine functions that compose into a single `filter`, so a blur and a `brightness` coexist; `none` clears this one and leaves the rest.
+How far the element's own pixels are blurred: a step of the named scale (`xs` 4px through `xxxl` 64px) or a radius in px. One of nine functions that compose into a single `filter`, so a blur and a `brightness` coexist; `none` clears this one and leaves the rest.
 
 - Writes: `--boxBlur`, `filter`
 - Values: `xs` · `sm` · `md` · `lg` · `xl` · `xxl` · `xxxl` · `none`, a number
@@ -302,7 +334,7 @@ The border-color shorthand CSS property sets the color of an element's border.
 
 - Writes: `border-color`
 - Values: 304 named values, anything else the types allow
-- Example: `borderColor="sky-500"` → `border-color: var(--sky-500)`
+- Example: `borderColor="sky-500"` → `border-color: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `borderRadius`
 
@@ -510,7 +542,7 @@ The caret-color CSS property sets the colour of the insertion caret in a text fi
 
 - Writes: `caret-color`
 - Values: 304 named values, anything else the types allow
-- Example: `caretColor="sky-500"` → `caret-color: var(--sky-500)`
+- Example: `caretColor="sky-500"` → `caret-color: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `clipPath`
 
@@ -526,7 +558,7 @@ The color CSS property sets the foreground color value of an element's text and
 
 - Writes: `color`
 - Values: 304 named values, anything else the types allow
-- Example: `color="sky-500"` → `color: var(--sky-500)`
+- Example: `color="sky-500"` → `color: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `colorScheme`
 
@@ -662,7 +694,7 @@ What colour `dropShadow` draws in. Shows nothing on its own.
 
 - Writes: `--boxDropShadowColor`
 - Values: 304 named values, anything else the types allow
-- Example: `dropShadowColor="sky-500"` → `--boxDropShadowColor: var(--sky-500)`
+- Example: `dropShadowColor="sky-500"` → `--boxDropShadowColor: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `fieldSizing`
 
@@ -678,7 +710,7 @@ The fill CSS property defines how SVG text content and the interior canvas of SV
 
 - Writes: `fill`
 - Values: 304 named values, anything else the types allow
-- Example: `fill="sky-500"` → `fill: var(--sky-500)`
+- Example: `fill="sky-500"` → `fill: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `fillOpacity`
 
@@ -894,7 +926,7 @@ What colour `insetRing` draws in. `currentColor` otherwise.
 
 - Writes: `--boxInsetRingColor`
 - Values: 304 named values, anything else the types allow
-- Example: `insetRingColor="sky-500"` → `--boxInsetRingColor: var(--sky-500)`
+- Example: `insetRingColor="sky-500"` → `--boxInsetRingColor: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `insetShadow`
 
@@ -910,7 +942,7 @@ What colour `insetShadow` draws in. Shows nothing on its own.
 
 - Writes: `--boxInsetShadowColor`
 - Values: 304 named values, anything else the types allow
-- Example: `insetShadowColor="sky-500"` → `--boxInsetShadowColor: var(--sky-500)`
+- Example: `insetShadowColor="sky-500"` → `--boxInsetShadowColor: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `insetStart`
 
@@ -1022,7 +1054,7 @@ What the element is masked by: the alpha channel of an image decides which of it
 
 - Writes: `mask-image`
 - Values: `none`, anything else the types allow
-- Example: `maskImage={{ linear: 'b', colors: ['black', 'transparent'] }}` → `mask-image: linear-gradient(to bottom,var(--black),var(--transparent))`
+- Example: `maskImage={{ linear: 'b', colors: ['black', 'transparent'] }}` → `mask-image: linear-gradient(to bottom,var(--black,#000),var(--transparent,transparent))`
 
 ### `maxHeight`
 
@@ -1158,7 +1190,7 @@ The outline-color CSS property sets the color of an element's outline.
 
 - Writes: `outline-color`
 - Values: 304 named values, anything else the types allow
-- Example: `outlineColor="sky-500"` → `outline-color: var(--sky-500)`
+- Example: `outlineColor="sky-500"` → `outline-color: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `outlineOffset`
 
@@ -1386,11 +1418,11 @@ A hard-edged shadow outside the border box, in px — `ring={2}`. Unlike `outlin
 
 ### `ringColor`
 
-What colour `ring` draws in. `currentColor` otherwise, the way Tailwind's is.
+What colour `ring` draws in. `currentColor` otherwise.
 
 - Writes: `--boxRingColor`
 - Values: 304 named values, anything else the types allow
-- Example: `ringColor="sky-500"` → `--boxRingColor: var(--sky-500)`
+- Example: `ringColor="sky-500"` → `--boxRingColor: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `rotate`
 
@@ -1446,7 +1478,7 @@ The scrollbar-color CSS property sets the color of the scrollbar thumb and track
 
 - Writes: `scrollbar-color`
 - Values: `currentColor,transparent,green,red,blue,gray,black,white,vi,slate-50,slate-100,slate-200,slate-300,slate-400,slate-500,slate-600,slate-700,slate-800,slate-900,slate-950,gray-50,gray-100,gray-200,gray-300,gray-400,gray-500,gray-600,gray-700,gray-800,gray-900,gray-950,zinc-50,zinc-100,zinc-200,zinc-300,zinc-400,zinc-500,zinc-600,zinc-700,zinc-800,zinc-900,zinc-950,neutral-50,neutral-100,neutral-200,neutral-300,neutral-400,neutral-500,neutral-600,neutral-700,neutral-800,neutral-900,neutral-950,stone-50,stone-100,stone-200,stone-300,stone-400,stone-500,stone-600,stone-700,stone-800,stone-900,stone-950,mauve-50,mauve-100,mauve-200,mauve-300,mauve-400,mauve-500,mauve-600,mauve-700,mauve-800,mauve-900,mauve-950,mist-50,mist-100,mist-200,mist-300,mist-400,mist-500,mist-600,mist-700,mist-800,mist-900,mist-950,olive-50,olive-100,olive-200,olive-300,olive-400,olive-500,olive-600,olive-700,olive-800,olive-900,olive-950,taupe-50,taupe-100,taupe-200,taupe-300,taupe-400,taupe-500,taupe-600,taupe-700,taupe-800,taupe-900,taupe-950,red-50,red-100,red-200,red-300,red-400,red-500,red-600,red-700,red-800,red-900,red-950,orange-50,orange-100,orange-200,orange-300,orange-400,orange-500,orange-600,orange-700,orange-800,orange-900,orange-950,amber-50,amber-100,amber-200,amber-300,amber-400,amber-500,amber-600,amber-700,amber-800,amber-900,amber-950,yellow-50,yellow-100,yellow-200,yellow-300,yellow-400,yellow-500,yellow-600,yellow-700,yellow-800,yellow-900,yellow-950,lime-50,lime-100,lime-200,lime-300,lime-400,lime-500,lime-600,lime-700,lime-800,lime-900,lime-950,green-50,green-100,green-200,green-300,green-400,green-500,green-600,green-700,green-800,green-900,green-950,emerald-50,emerald-100,emerald-200,emerald-300,emerald-400,emerald-500,emerald-600,emerald-700,emerald-800,emerald-900,emerald-950,teal-50,teal-100,teal-200,teal-300,teal-400,teal-500,teal-600,teal-700,teal-800,teal-900,teal-950,cyan-50,cyan-100,cyan-200,cyan-300,cyan-400,cyan-500,cyan-600,cyan-700,cyan-800,cyan-900,cyan-950,sky-50,sky-100,sky-200,sky-300,sky-400,sky-500,sky-600,sky-700,sky-800,sky-900,sky-950,blue-50,blue-100,blue-200,blue-300,blue-400,blue-500,blue-600,blue-700,blue-800,blue-900,blue-950,indigo-50,indigo-100,indigo-200,indigo-300,indigo-400,indigo-500,indigo-600,indigo-700,indigo-800,indigo-900,indigo-950,violet-50,violet-100,violet-200,violet-300,violet-400,violet-500,violet-600,violet-700,violet-800,violet-900,violet-950,purple-50,purple-100,purple-200,purple-300,purple-400,purple-500,purple-600,purple-700,purple-800,purple-900,purple-950,fuchsia-50,fuchsia-100,fuchsia-200,fuchsia-300,fuchsia-400,fuchsia-500,fuchsia-600,fuchsia-700,fuchsia-800,fuchsia-900,fuchsia-950,pink-50,pink-100,pink-200,pink-300,pink-400,pink-500,pink-600,pink-700,pink-800,pink-900,pink-950,rose-50,rose-100,rose-200,rose-300,rose-400,rose-500,rose-600,rose-700,rose-800,rose-900,rose-950,none`
-- Example: `scrollbarColor={['gray-400', 'gray-100']}` → `scrollbar-color: var(--gray-400) var(--gray-100)`
+- Example: `scrollbarColor={['gray-400', 'gray-100']}` → `scrollbar-color: var(--gray-400,oklch(70.7% .022 261.3)) var(--gray-100,oklch(96.7% .003 264.5))`
 
 ### `scrollbarGutter`
 
@@ -1464,6 +1496,30 @@ How wide a scrollbar the browser draws. `none` hides it without taking the scrol
 - Values: `auto` · `thin` · `none`
 - Example: `scrollbarWidth="auto"` → `scrollbar-width: auto`
 
+### `scrollTimeline`
+
+Declares a named scroll timeline on this scroller — the shorthand, `<name>` or `<name> <axis>`, and the one to reach for: the longhands exist to override half of it. The name is written with or without the `--`, the way an anchor's is. Anything inside this element can then name it on `animationTimeline`; anything outside needs a `timelineScope` on a common ancestor.
+
+- Writes: `scroll-timeline`
+- Values: `none`, anything else the types allow
+- Example: `scrollTimeline="page block"` → `scroll-timeline: --page block`
+
+### `scrollTimelineAxis`
+
+Which axis of this scroller the named timeline follows. `block`/`inline` are the writing mode's, so a timeline declared on the block axis is the vertical one in English and still correct in Japanese.
+
+- Writes: `scroll-timeline-axis`
+- Values: `block` · `inline` · `x` · `y`
+- Example: `scrollTimelineAxis="block"` → `scroll-timeline-axis: block`
+
+### `scrollTimelineName`
+
+The name half of `scrollTimeline`, on its own.
+
+- Writes: `scroll-timeline-name`
+- Values: `none`, anything else the types allow
+- Example: `scrollTimelineName="page"` → `scroll-timeline-name: --page`
+
 ### `sepia`
 
 How far the element is pushed towards sepia, as a percentage.
@@ -1474,7 +1530,7 @@ How far the element is pushed towards sepia, as a percentage.
 
 ### `shadow`
 
-The elevation of the box: `xxs` through `xxl` on Tailwind's scale, or one of the three original presets (`small`, `medium`, `large`, which carry their own colour). `shadowColor` recolours the scale, and the shadow stacks with `ring`, `insetRing` and `insetShadow` rather than replacing them.
+The elevation of the box: `xxs` through `xxl` on the elevation scale, or one of the three original presets (`small`, `medium`, `large`, which carry their own colour). `shadowColor` recolours the scale, and the shadow stacks with `ring`, `insetRing` and `insetShadow` rather than replacing them.
 
 - Writes: `--boxShadow`, `box-shadow`
 - Values: `xxs` · `xs` · `sm` · `md` · `lg` · `xl` · `xxl` · `none` · `small` · `medium` · `large`
@@ -1486,7 +1542,7 @@ What colour `shadow` draws in — the scale's own translucent black otherwise. S
 
 - Writes: `--boxShadowColor`
 - Values: 304 named values, anything else the types allow
-- Example: `shadowColor="sky-500"` → `--boxShadowColor: var(--sky-500)`
+- Example: `shadowColor="sky-500"` → `--boxShadowColor: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `shapeRendering`
 
@@ -1502,7 +1558,7 @@ The stroke CSS property defines the color or SVG paint server used to draw an el
 
 - Writes: `stroke`
 - Values: 304 named values, anything else the types allow
-- Example: `stroke="sky-500"` → `stroke: var(--sky-500)`
+- Example: `stroke="sky-500"` → `stroke: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `strokeDasharray`
 
@@ -1614,7 +1670,7 @@ What colour `textShadow` draws in. Shows nothing on its own.
 
 - Writes: `--boxTextShadowColor`
 - Values: 304 named values, anything else the types allow
-- Example: `textShadowColor="sky-500"` → `--boxTextShadowColor: var(--sky-500)`
+- Example: `textShadowColor="sky-500"` → `--boxTextShadowColor: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `textTransform`
 
@@ -1632,6 +1688,14 @@ The text-wrap CSS shorthand property controls how text inside an element is wrap
 - Values: `wrap` · `nowrap` · `balance` · `pretty`
 - Example: `textWrap="wrap"` → `text-wrap: wrap`
 
+### `timelineScope`
+
+Makes the named timelines below this element reachable from anywhere else below it. A timeline is otherwise visible only to the declaring element's own descendants, so a progress bar that is not inside the article it tracks needs their common ancestor to declare the scope. Comma-separated.
+
+- Writes: `timeline-scope`
+- Values: `none`, anything else the types allow
+- Example: `timelineScope="page"` → `timeline-scope: --page`
+
 ### `top`
 
 The top CSS property sets the vertical position of a positioned element. This inset property has no effect on non-positioned elements. It also takes `anchor()`, an inset measured to one of the anchor's own edges.
@@ -1710,7 +1774,7 @@ CSS custom properties on this element, inherited by everything inside it: `vars=
 
 - Writes: `--color-revenue`
 - Values: whatever the types allow
-- Example: `vars={{ 'color-revenue': 'sky-500' }}` → `--color-revenue: var(--sky-500)`
+- Example: `vars={{ 'color-revenue': 'sky-500' }}` → `--color-revenue: var(--sky-500,oklch(68.5% .169 237.3))`
 
 ### `vectorEffect`
 
@@ -1720,6 +1784,54 @@ How an SVG element's stroke reacts to the transforms above it: `non-scaling-stro
 - Values: `none` · `non-scaling-stroke`
 - Example: `vectorEffect="none"` → `vector-effect: none`
 
+### `viewTimeline`
+
+Declares a named view timeline on this element — its own progress across the scrollport, rather than the scroller's progress through its content. Same shorthand shape as `scrollTimeline`, and the same rule about who can see the name.
+
+- Writes: `view-timeline`
+- Values: `none`, anything else the types allow
+- Example: `viewTimeline="card block"` → `view-timeline: --card block`
+
+### `viewTimelineAxis`
+
+Which axis this element's pass across the scrollport is measured on.
+
+- Writes: `view-timeline-axis`
+- Values: `block` · `inline` · `x` · `y`
+- Example: `viewTimelineAxis="block"` → `view-timeline-axis: block`
+
+### `viewTimelineInset`
+
+Shrinks the scrollport the timeline measures against, so the pass starts and ends somewhere other than the viewport edges: one value for both ends, two for the start and the end. A positive inset moves the edge inwards, which is what makes an element count as "in view" before it really is.
+
+- Writes: `view-timeline-inset`
+- Values: whatever the types allow
+- Example: `viewTimelineInset="20%"` → `view-timeline-inset: 20%`
+
+### `viewTimelineName`
+
+The name half of `viewTimeline`, on its own.
+
+- Writes: `view-timeline-name`
+- Values: `none`, anything else the types allow
+- Example: `viewTimelineName="card"` → `view-timeline-name: --card`
+
+### `viewTransitionClass`
+
+A class shared by several named elements, so one rule styles the lot of them: `::view-transition-group(.card)` reaches every element carrying `viewTransitionClass="card"`. Space separated for more than one.
+
+- Writes: `view-transition-class`
+- Values: `none`, anything else the types allow
+- Example: `viewTransitionClass="card"` → `view-transition-class: card`
+
+### `viewTransitionName`
+
+Names this element for a view transition, which is what makes the browser animate it from where it was to where it is rather than cross-fading the whole page over it. A name has to be **unique in the document while the transition runs** — two elements sharing one is how a transition silently does nothing — so a list wants a name per item, and that is a rule per item this library would never free: write those with `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition` already takes. This prop is for the handful of names a layout has (`header`, `main`, `sidebar`).
+
+- Writes: `view-transition-name`
+- Values: `none` · `auto` · `match-element`, anything else the types allow
+- Example: `viewTransitionName="header"` → `view-transition-name: header`
+
 ### `visibility`
 
 The visibility CSS property shows or hides an element without changing the layout of a document. The property can also hide rows or columns in a <table>.