@exponential_app/eui-react 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Dennis Strähhuber
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,54 @@
+Exponential
+Copyright 2026 Dennis Strähhuber
+
+This product includes software developed as part of the Exponential project,
+licensed under the Apache License, Version 2.0 (see LICENSE at the repo root).
+
+Third-party code vendored into this repository keeps its own NOTICE, next to
+the vendored source:
+
+  apps/desktop/crates/ui/NOTICE
+  apps/desktop/crates/gpui-markdown-editor/NOTICE
+
+This file records the attributions that travel with a distributed artifact.
+It is not the per-client dependency inventory; that is generated separately.
+
+
+================================================================================
+Feedback widget
+================================================================================
+
+The feedback widget (packages/widget, emitted to
+apps/web/public/widget/v1/loader.js and widget.js) is served cross-origin to
+third-party websites, so its bundle redistributes the software below. Both
+emitted files carry a short banner naming these packages and pointing here.
+
+  preact
+  Copyright (c) 2015-present Jason Miller
+  https://github.com/preactjs/preact
+  MIT License
+
+  @zumer/snapdom
+  Copyright (c) 2025 ZumerLab
+  https://github.com/zumerlab/snapdom
+  MIT License
+
+Both are made available under the following terms:
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,361 @@
-# Temporary Holding Version
+# `@exponential_app/eui-react` — the Exponential UI React renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The REFERENCE renderer of Exponential UI (VAPP-84): an A2UI surface in the
+core catalog (`@exponential_app/eui`) painted with real CSS on shadcn/Radix.
+Themes load at runtime, extensions register their own components, overlays
+ride Radix portals, inputs are host-owned, and the layout is the one the
+Rust core computes (the geometry fixture holds the browser to taffy's
+frames within a pixel). Published to npm from `release/` (VAPP-91); the
+workspace package.json stays private on the sources.
+Its SolidJS twin, `@exponential_app/eui-solid` (`packages/exponential-ui-solid`),
+paints the identical DOM, renderer and primitives, and is gated against this
+renderer by the web-parity check (`@exponential_app/eui/conformance/parity.ts`).
+
+It depends on `@exponential_app/eui`, React 19 (React 18 would keep
+`javascript:` hrefs clickable), `radix-ui` and
+`lucide-react` (its own chrome glyphs) — nothing from the Exponential app, no
+TanStack, no Electric, no tRPC. Tailwind is an internal build detail of the
+primitive set (below); the renderer itself ships no stylesheet an embedder
+has to wire up.
+
+```tsx
+import { ExponentialSurface, useSurface } from "@exponential_app/eui-react"
+
+function Chat({ messages }) {
+  const surface = useSurface({ surfaceId: "main" })
+  useEffect(() => messages.forEach(surface.apply), [messages])   // A2UI v0.9 server messages
+  return (
+    <ExponentialSurface
+      surface={surface}
+      theme="exponential"                     // or "neutral" | "playful" | "orange" | a theme JSON | a ResolvedTheme
+      mode="system"                           // light | dark | system (default; follows the platform live)
+      locale="de-AT"                          // formatting, calendar names, week start, text direction
+      timeZone="Europe/Vienna"                // dates and relative times (default: the platform's)
+      strings={{ search: "Suchen…" }}         // built-in copy overrides (catalog/strings.json ids)
+      density="compact" contrast="system"     // the theme's density multiplier; high-contrast overlays
+      host={{ icons, onAction, onInput, onUpload }}     // the host plugin (below)
+      handleRef={ref}                         // ref.current.run({ focus: { id } } | { announce } | { scrollIntoView } | { scrollToIndex })
+    />
+  )
+}
+```
+
+## Layout
+
+The stylesheet and the bind pass come from the core's web layer, `@exponential_app/eui/web` (FEED-128: `compileTheme`, `BASE_CSS`, the node sheet, `bindTree`, the URL/media policy, the natives' pure helpers), so every web renderer paints with byte-identical CSS; this package re-exports those names (`compileTheme`, `BASE_CSS`, `bindTree`, `linkHref`…) and keeps only the React half.
+
+| path | what |
+|---|---|
+| `src/surface.tsx` | `<ExponentialSurface>`: root (theme scope + variables, `data-xui-mode`, `dir`, `data-xq`), the two `<style>`s, the `xui` container with the tree + the overlay and toast LAYERS, the live regions, the settings (locale, strings, mode/density/contrast) and the host command handle |
+| `src/use-surface.ts` | `useSurface`: the TS reducer as React state; A2UI messages in, normalized tree + data model out |
+| `src/node-view.tsx` | the BIND pass per node (`visible`, props, dynamic style values, recipe props, `$string`, responsive native props), painter picked, root attributes, the action runner (`set` then the event), keyed templates |
+| `src/natives/` | the 46 native painters (Box, Text, Button… Form, NumberField, ChipInput, Date/Range/TimePicker, FileUpload, CodeBlock, Table, Chart, Menu, Segmented, Toast, Resizable, TreeGuides, Unknown); `natives.test.ts` gates them against the catalog |
+| `src/form.tsx` | the Form native + the field protocol every named control speaks (`useField`) |
+| `src/platform.ts` | live platform preferences (`matchMedia`) and the measured surface box |
+| `src/inputs.ts` | `useHostOwnedValue`: the hook around the web layer's `HostOwnedController` (150 ms debounce, revisions, echo rule) |
+| `src/list.tsx` | `WindowedList`: one axis, item key, estimated extent, gap + dividers, overscan, sticky rows, one ResizeObserver, `scrollToIndex` |
+| `src/extensions.ts` | `registerExtension` / `defineReactExtension` |
+| `src/primitives/` | the shadcn set (moved from `@exp/ui`, which re-exports it) as thin React wrappers over the class recipes of `@exponential_app/eui/web/primitives` (FEED-131: no class literal here, the Solid twin reads the same recipes) + `tailwind.css` (scans the recipes too); `bun run build:css` → `dist/exponential-ui-react.css` |
+| `harness/` | the browser harness the Chromium suites and the screenshot script drive (`dev:harness` → :4181; views kitchen-sink, geometry, overlay, catalog, conditions, tree, round2, bench) |
+| `browser/` | the headless-Chromium suites: geometry, overlays, typing, round 1 (conditions, overlays × breakpoints, kitchen sink × themes × widths, keyboard) (`test:browser`) |
+| `fixtures/kitchen-sink.data.json` | the data model the kitchen sink renders against (harness + the app's view) |
+| `scripts/` | `build-css.ts`, `shots.ts` (the stored kitchen-sink shots), `pack-smoke.ts` (a plain Vite app on the packed tarballs) |
+
+## How a theme becomes CSS
+
+`compileTheme(theme)` emits, scoped by a class derived from the theme's
+content (`xui-t-<id>-<hash>`, on the root AND on every painted element, so two
+surfaces on one page wear two themes and a host page's own variables are
+never touched):
+
+1. **Variables** on `.xui-surface.<scope>`: every token as `--xui-<group>-<name>`
+   (`--xui-spacing-md: 12px`, `--xui-type-lineHeight-sm`, `--xui-font-sans: "Inter", …`),
+   the colours and shadows per `[data-xui-mode="light|dark"]`, plus the shadcn
+   names (`--primary`, `--radius`, `--font-sans`…) and the app's `--glass-*`
+   set, so a Tailwind-built primitive inside a surface wears the theme too.
+2. **Recipe classes**: `recipes.<Component>.<part>` → `.xui-<Component>-<part>`.
+   A rule's `when` on recipe props becomes `[data-r-<prop>="…"]` (natives) or
+   `[data-m-<prop>="…"]` (macro parts: a Badge's label is a Text, both key on
+   `variant`); `state` becomes the pseudo-class or Radix attribute AND the
+   forced marker `[data-xs~="<state>"]` the builder's recipe sheet sets.
+   Values stay `var(--xui-…)`, so a mode switch is one attribute flip.
+3. **Layers**: `@layer xui-base, xui-recipe, xui-node, xui-part, xui-author` IS
+   the painter precedence of `resolveNodeStyle`: a native's own recipe < the
+   node's `style` < the macro part's recipe < the style keys authored on the
+   macro node (`recipe.authored`).
+
+The node sheet (`compileNodeSheet`) is per surface: `.xui-s-<id> .xui-n-<nodeId>`
+rules from each node's whitelisted style (tokens as variables), then each
+`@media` block in SOURCE order (round-1 contract §2; later wins):
+
+| condition | CSS |
+|---|---|
+| `min-width: N` / `max-width: N` (`N` px or `$breakpoint.*`, resolved from the theme) | `@container xui (width >= N)` / `(width < N)` — strict, so `min md` and `max md` never overlap |
+| `min-height` / `max-height` / `orientation` | `.xui-s-<id>:where([data-xq~="<token>"]) …` — the surface lists the matching conditions in `data-xq` (an inline-size container cannot answer height). The height is the VIEWPORT's, like the Rust core's `set_viewport` height: the `viewportHeight` prop, else an explicit inline `style.height` on the surface, else UNKNOWN (landscape, no min/max-height match — what the gpui host passes today); never the content height (no feedback loop) |
+| `hover: hover\|none`, `prefers-reduced-motion` | real `@media` |
+| `:hover`, `:focus-visible`, `:pressed` | after every media rule, in that order: `:hover`/`[data-xs~=hover]`, `:focus-visible`, `:active`/`[data-xs~=pressed]` |
+
+A value the macro expander left DYNAMIC (Progress `width: percent{…}`) is
+emitted as `var(--xd-<n>)` and the node sets the resolved value inline, so the
+layer order holds; a value that resolves to nothing is set to `initial`, so the
+property falls back instead of inheriting an ancestor's `--xd-<n>`. Template subtrees are part of the sheet and their items
+keep the template node's class (ids get the item's suffix), so a templated row
+wears its author and macro styles. New style keys map like `styleToCss`:
+`transition` → `transition-property: all` + `transition-duration` (the easing
+is `transition-timing-function`, `$ease.*` → `var(--xui-ease-*)`), gradients
+→ `background-image`, per-side widths default to `solid`, `overflowX/Y:
+hidden` → `clip`. Reduced motion (the media query or `data-xui-motion`)
+zeroes every duration.
+
+### The three rules that make CSS agree with taffy (VAPP-4)
+
+Every painted element restates `box-sizing: border-box; display: flex;
+flex-direction: row; position: relative` and leaves `min-width` AND
+`min-height` at `auto` (taffy's automatic minimum size; round 1 dropped the
+old `min-height: 0`, the geometry replay stays within 1 px); chrome
+is paint or inside the measured size (borders start at 0, a recipe's
+`borderWidth` is layout in both engines); `overflow: hidden` is emitted as
+`clip`. `fixtures/layout-geometry.json` (the spike's kitchen sink, taffy's
+frames at 900/390 px × LTR/RTL, a fixed fake measure) is replayed in headless
+Chromium by `browser/geometry.test.ts`: every node within 1 px. In geometry
+mode (`measure` prop) a leaf renders as a fixed box with no recipe on it.
+
+## The host plugin
+
+```ts
+interface HostPlugin {
+  icons?: IconMap                                   // registry name → component (the app passes its Lucide map)
+  onAction?(e: SurfaceActionEvent): void | Promise<void>   // on.<event> = {event: {name, context}}; a promise keeps the Button pending
+  onInput?(e: SurfaceInputEvent): void | Promise<void>     // host-owned edits: {name, path?, value, revision, kind: change|commit}
+  openUrl?(url: string): void                       // opens an href the URL policy allowed
+  urls?: UrlPolicy                                  // EVERY href (Link, markdown, FileUpload, openUrl); denied = text
+  media?: MediaOptions                              // EVERY src without a mediaRequest (schemes, hosts, rules)
+  mediaRequest?(src: string): MediaRequest | null   // null = denied; re-checked against media's schemes/hosts
+  onPaintError?(e: { surfaceId, componentId, message }): void   // a painter threw (it paints an empty box)
+  functions?: Record<string, ClientFunction>        // adds to / overrides the catalog functions
+  Markdown?: ComponentType<{ text: string }>       // a richer renderer than the built-in GFM subset
+  resolveUrl?(src: string): string                 // rewrites a media src BEFORE the media policy
+  onUnknown?(node: UiNode): void
+  onUpload?(files: File[], target: { nodeId, name }): void | Promise<void>   // FileUpload bytes (the event carries metadata only)
+  optionSource?(source: string, query: string): Option[] | Promise<Option[]> // Select `source` (a host list)
+  qrScanner?: { start(feed: HTMLElement, formats: readonly string[], onValue: (value: string) => void): (() => void) | false | void } // QrScanner's camera
+}
+```
+
+- **Actions** are optimistic: a Button is disabled (`aria-busy`,
+  `data-xs~="pending"`) from the press until `onAction`'s promise settles.
+  An action resolves its function args AND event context against the data
+  as it is, then runs the function (`set` writes the data model, two-way
+  binding for macros; `openUrl` → `host.openUrl`), then sends the event with
+  the component's payload merged OVER the author's context (the payload wins
+  a clashing key, like the Rust core's `fire`).
+- **Re-renders**: the surface keeps its measured box in a ref and re-renders
+  only when the active breakpoint or `data-xq` changes; nodes are memoized,
+  so a parent re-render (or a resize inside a breakpoint) repaints nothing.
+- **Template instance ids** accumulate: an item's nodes are
+  `<id><outer suffixes>.<key>` (`cell.a.0`), the key = the `template.key`
+  value, the index without a key, `#<index>` when the key is missing, null,
+  empty or a duplicate. A Table slot cell appends the row key the same way.
+- **Host-owned inputs** (`Input`, `Textarea`, `Composer`): the value lives in
+  local state; every edit bumps a revision and, 150 ms later, sends ONE
+  `change` with the latest value; `commit` goes out on blur/Enter. A value
+  the host pushes (the data model, a new prop) is adopted only when the
+  field is not focused and every sent revision is acknowledged (the promise
+  settled). A bound `value` (`{path}`) is also written through to the
+  surface's data model. `browser/typing.test.ts`: 40 keys at 150 ms RTT,
+  none dropped, three runs.
+- **Bindings**: `{path}` is a JSON pointer into `surface.data` (relative
+  inside a template item); `{call, args}` runs a client function (the bind
+  table `bindFunctionNames`; truthiness = the catalog's, `0` is true; the
+  format functions run through the surface Formatter);
+  `$string.<id>` resolves through the surface's string table. A falsy
+  `visible` drops the node. `bindTree` is the whole-tree form, replayed
+  against `fixtures/bind-time.json`.
+- **Bindable state**: a native whose state prop is bound (Dialog `open`,
+  Tabs `value`, Checkbox `checked`, Table `sort`/`selected`, ChipInput
+  `values`, …) writes the user's change to the path itself AND fires
+  `change`.
+- **Forms**: every named control registers with the nearest `Form`; a
+  submit (a `submit` Button, Enter in a single-line field) runs every
+  field's checks; a failure fires `invalid {errors}`, shows ALL failing
+  messages under each field (`<id>.error`, `role=alert`, linked by
+  `aria-describedby`, the `invalid` recipe state), the `summary`, moves
+  focus to the first invalid field and announces `invalidFields`.
+- **Templates**: `children: {componentId, path, key?}` renders the component
+  once per item at `path`, keyed by `key` (reordering keeps the item's
+  state). The component comes from the reducer's LIFTED `templates`
+  (`useSurface` keeps them; a fixture passes `templates` beside `root`); it
+  never renders in place.
+
+### The host API (VAPP-91)
+
+An `ExponentialHost` from `@exponential_app/eui` (transport, router, sources,
+functions, policy; see that package's README) feeds `<HostSurface host
+surfaceId plugin? …ExponentialSurface props>`; `hostPlugin(host, base)`
+routes actions to A2UI client messages, `functionCall`s to
+`host.callFunction` (the gate + consent), every href to the URL policy,
+every src to `host.mediaRequest` (fetched under the contract's
+`media.limits`: bytes, timeout, header pixels) and `onPaintError` to
+`host.paintError` (an A2UI `RENDER_FAILED` error). `useHostSurfaceIds(host)` and
+`useHostStatus(host)` (`status`, `unsupportedCatalog`) drive a host's own
+chrome (`host_offline`, the catalog-update banner). Two plugin members
+joined: `onFunctionCall(call)` and `mediaRequest(src)` (a request with
+headers is fetched once and shown as a blob url). Template items (a List's
+`{componentId, path}` rows) wear their component's node styles.
+
+`browser/suites.test.ts` is the renderer's conformance runner (every
+suite of the manifest; `test:conformance`).
+
+## Overlays
+
+Dialog, Drawer, Popover, Tooltip, Menu, Select and the
+pickers portal into the surface's OVERLAY LAYER inside the `xui` container
+(not `document.body`): the theme's variables and scope reach them, container
+breakpoints still match inside a Dialog (round 1), and an inline-size
+container does not trap `position: fixed`. Toasts portal into the TOAST layer
+above it (bottom-centre below `md`, bottom-end from `md`, newest at the edge,
+three visible; the duration pauses on hover/focus). Enter/exit animate on the
+theme's motion and easing tokens. Placement follows the core's
+rule (`placeOverlay` in `@exponential_app/eui`: `OVERLAY_OFFSET` 4 px, centred,
+flip when the preferred side lacks room, shift `OVERLAY_PADDING` 8 px inside
+the viewport); `browser/overlay.test.ts` holds Radix's popper to
+`fixtures/overlay-geometry.json` within 2 px, same side and flip. A trigger
+slot is wrapped in an inline-flex span the popper measures. `open` is a
+controlled prop with a local mirror (`change` reports the user's toggles).
+
+## Round 1 natives (contract §3)
+
+| native | behaviour |
+|---|---|
+| Form | field collection, submit gating, every failing message, summary, focus + announce, `busy`, `disabled` (a disabled fieldset) |
+| NumberField | `role=spinbutton`, steppers, Arrow ± step (Shift ×10), PageUp/Down, Home/End, clamp on commit, locale formatting/parsing |
+| ChipInput | Enter / comma add, Backspace focuses then removes the last chip, arrows between chips, suggestions listbox |
+| DatePicker, DateRangePicker | one keyboard grid (arrows, PageUp/Down ± month, Shift ± year, Home/End by the locale week start), Intl month/weekday names, two-step range |
+| TimePicker | a listbox of `step`-minute times in the locale's clock, type-ahead |
+| Select | Radix when plain; searchable/multiple = the combobox (aria-activedescendant, `search {query}` debounced, bound options = async source, `host.optionSource`) |
+| FileUpload | drop zone button, `dragover` state, accept/maxSize refusals, bytes → `host.onUpload`, removable files |
+| CodeBlock | the catalog tokenizer (`CodeBlock/token` per kind), gutter, highlighted lines, wrap, `maxLines`, copy + `copied` announced |
+| Table | typed cells (locale number/date, tick, badge, slot with the ROW as scope), sort (local or bound), single/multiple selection with select-all, striped odd rows, sticky header, windowing past 50; ONE roving row tab stop (focused, else first selected, else first), ArrowUp/Down + Home/End by index (through a windowed body), Enter presses, Space selects; slot edits over LITERAL rows stay table-local (never the data model, never a host path) |
+| Chart | measured width, `niceTicks` axes + grid, bar/stackedBar/line/area/pie/donut (a ring per series)/sparkline, values, legend (2+), tooltip on hover and ArrowLeft/Right, an sr-only data table; cartesian kinds MIRROR in RTL (first category on the right) |
+| Menu | item / checkbox (bound `checked` written) / separator / label / submenu (bound `items` render like literal ones), shortcuts; `openOn: press` = its child (or a default outline button) is the trigger, `contextmenu` = right-click / long-press / Shift+F10 / Menu key over the child |
+| Toast | the toast layer, duration paused on hover/focus, `open` written false, `dismiss` + `change`, error = assertive |
+| Image / Textarea / Drawer / Popover / Text / Markdown | fallback glyph + focal point + `loading`; autosize; `dismissible` + drag-to-dismiss + responsive `side`; `openOn: hover` (+ keyboard focus); `live`; `lines` |
+
+Owned parts draw the catalog's `builtinIcons` glyph (host registry first,
+then the same Lucide glyphs icons.json maps), and every piece of built-in
+copy comes from the string table.
+
+## Extensions
+
+```ts
+import { registerExtension } from "@exponential_app/eui-react"
+registerExtension({ catalog: myExtensionJson, components: { TrendLine } })   // page-wide
+<ExponentialSurface extensions={[defineReactExtension({ catalog, components })]} />  // per surface
+```
+
+A component receives `{ node, props (resolved), theme, mode, tokens, children,
+slots, emit, rootProps }` and spreads `rootProps` on its root element (the node
+class, the theme scope, the part classes, the recipe `data-*`). Macros of the
+extension expand in the reducer and need no component; their parts go in the
+`xui-part` layer. An entry for a CORE native (`{ Switch: MySwitch }`) is the
+VAPP-92 painter override.
+
+## Lists
+
+`List` renders its children, then the template's items. Past the catalog's
+`WINDOW_THRESHOLD` (50), or with `stickyHeaders`, it windows
+(`WindowedList`): one axis (`direction` vertical or horizontal), rows end to
+end with the gap (+ the hairline when `divided`, the divider centred in it),
+unmeasured rows at `$control.row`, ONE `ResizeObserver`. The window follows
+the nearest ancestor that actually scrolls on that axis, else the viewport.
+The numbers are the core's (`virtualWindow`, `scrollOffsetForIndex`,
+`stickyHeader`). Fewer items render flat, so fixtures snapshot every row.
+
+| feature | web |
+|---|---|
+| `sectionBy` | consecutive items share a header: the `section` slot bound to `{value, count, index}`, else the value; `role=heading` level 3, part `<id>.section.<i>` |
+| `stickyHeaders` | the current header pins at the top, pushed back by the next one; drawn even outside the window |
+| a11y | every item `role=listitem` with `aria-setsize` / `aria-posinset` of the WHOLE list |
+| `scrollToIndex` | host command `{scrollToIndex: {id, index, align}}` on List and Table (data index); re-aimed once the revealed rows are measured |
+
+Bench (`fixtures/bench-list.json`: 100,000 `Row`s, 390 × 800, neutral;
+i9-13900K, Linux, Playwright 1.59 headless Chromium / jsdom 27; median of 3):
+
+| renderer | firstPaintMs | scrollStepMs | scrollToIndexMs | renderedItems |
+|---|---|---|---|---|
+| Chromium (`bun run bench:list`) | 147 | 4.9 | 38 | 30 |
+| jsdom (`XUI_BENCH=1 vitest run src/bench.test.tsx`) | 549 | 14.9 | 70 | 30 |
+
+A step = the scroll, the window's render flushed and the layout read back
+(main-thread work, no frame wait); the jump includes the first re-aim.
+
+## Round 2 (contract `docs/round-2-contract.md`)
+
+| item | web |
+|---|---|
+| Resizable | flex panels (sizes = grow factors over a 0 basis = `panelExtents`), hairline handles with an 8 px hit area, pointer drag from the START sizes, `keyboardResize`, bound `sizes` + `change {sizes}` at drag end / key, `separator` a11y named `$string.resize` |
+| templates (breaking) | `<ExponentialSurface>` takes `templates` beside `root` (the reducer's lifted ones; `useSurface` and `HostSurface` pass them). The in-tree fallback and the `templateNodeFrom` export are gone: a `root`-only caller renders no template items, and dev builds warn once per missing template |
+| `position: sticky` | CSS sticky |
+| `backdropBlur` | `backdrop-filter: blur(var(--xui-blur-*))` (+ `-webkit-`) |
+| `animation` | `@keyframes xui-<name>` in the base sheet, duration `calc($motion × factor)`, `animationDuration` keeps the factor, shimmer = an `::after` band on `--xui-band`; reduced motion = 0 ms (the rest frame) |
+| `direction` | on any node: its `dir`, and its subtree's natives (Radix `dir`, arrows, chart mirror) read it; `rtlMirroredIcons` flip by `:dir(rtl)` |
+| Formatter | `intlFormatter(locale, timeZone)` per surface (`timeZone` prop, default the platform's): the six format functions, Table `number`/`currency`/`percent`/`date`/`relativeTime` cells, NumberField, Slider value, chart ticks and summary, picker triggers, calendar names; a `formatRelativeTime` without `now` or a Table `relativeTime` column re-binds every minute |
+| text props | a bound number shows `412`, a boolean `true`, an object nothing (`displayString`) |
+| strings | `invalidValue`, `message`, `codeBlock`, `dialog`, `table`, `carousel`, `slide`, `resize` |
+| parts | every laid-out part carries `data-xui-id="<id>.<part>[.<i or row key>]"` + `data-xui-part`; inactive carousel pages are `inert` + `data-xui-inactive` |
+| §7 sizes | overlays = layout-transparent wrappers (`data-xui-overlay-root`: the parent's alignment, a Button trigger at its own size at the start, a Link trigger fills), menu trigger without chevron, Chart `height` = the whole box, AudioPlayer track + controls row, Video / Image 16:9, Table and CodeBlock from recipes only (per-side border widths no longer pick up the UA's 3 px), Browse in the drop zone, TreeGuides columns (round 3: 14 px), Switch label first, Checkbox gap, Radio items at the root gap, Accordion count part |
+
+## Round 3 (VAPP-102: Row, Section, Chip, Segmented, Menu)
+
+| item | web |
+|---|---|
+| macros | `Row`, `Section`, `Chip` need no painter: they expand to Box/Text/Icon/List/TreeGuides/Badge/Button/Image and the two new natives. A `Section` body is a divided `List`; with `tree` it is `role=tree` of `treeitem`s |
+| Segmented | ONE row of segments (Radix ToggleGroup: radiogroup single / toolbar multiple, roving arrows), variants `segmented` (default) / `toggles` / `outline`; `bar` = a full-width `<nav>` of column buttons (icon above a caption label, `$control.tabBar` tall), `aria-current="page"`, the same roving keys; parts root, item, icon, label |
+| Menu | ONE painter for press and context menus (`openOn`); builtin glyphs `Menu.check`, `Menu.submenuIndicator` |
+| TreeGuides | a Row's `guides` part the CORE fills (`elbowAt`, `tee`, `passThrough`); `TREE_GUIDE_COLUMN` 14 px columns, the line at i·14 + 7, the elbow = one element (left + bottom borders) to the column's right edge with a `TREE_GUIDE_RADIUS` 3 px corner, every vertical starting `TREE_GUIDE_BRIDGE` 1 px above the part's top (overflow visible) |
+
+## Round 5 (VAPP-162, `docs/round-5-contract.md`)
+
+| item | web |
+|---|---|
+| macros | `MessageBubble`, `CallSurface`, `Plan` need no painter (they expand to Box/Text/Markdown/Icon/VoiceWave/Avatar/Tooltip/Button/Card/Trace/Progress) |
+| QrCode | ONE SVG path of the core's `qrMatrix` in module units (quiet zone 4, `shape-rendering: crispEdges`) over a `size` px plate; the lighter of the plate/module recipe colours fills the plate (`qrPaint`), so a dark theme still scans; `label` = caption + img name |
+| QrScanner | the viewfinder chrome (feed, four corner brackets, the scan line sweeping by CSS, still under reduced motion or `disabled`); THE CAMERA IS THE HOST'S: `host.qrScanner.start(feed, formats, onValue)` renders its feed into the `feed` element and returns the stop; every decoded string goes through `qrScanReporter` (once per distinct value) to `scanned {value}` and the polite live region; no `qrScanner` (or `start` returning `false`) = the `ui-scan` icon + `Camera unavailable` |
+| VoiceWave `bars` | the core's `voiceWaveBars` as 20 rounded rects in the `bar` colour, rAF writes `y`/`height` while it moves; a child stays unpainted |
+| Segmented | `orientation: vertical` stacks every variant (ArrowUp/ArrowDown); a vertical `bar` = the rail (72 × 56 items); `option.count` = the `badge` at a `bar` icon's top-end corner (`99+`, none at 0), read after the label |
+| Button `hold` | `ButtonHold` (the shared machine): pointer capture on down, 24 px slop, Space/Enter key down → up, Escape/blur/pointercancel cancel; `holdingLabel` while held; never `press` |
+| serif | `ui-serif` stays a CSS keyword: `font-family: ui-serif, Georgia, serif` |
+
+## The primitive set
+
+`src/primitives/` holds the generic shadcn/Radix components the app and
+extension authors share (button, input, select, dialog, sheet, tabs, meter,
+calendar, table, command, toast, … plus round 1's alert-dialog, breadcrumb,
+kbd, scroll-area), themed only through the surface's variables; the catalog's
+natives own Radix directly. The Exponential app's own components (the glass
+rows, typeahead, composer, trace, pill, segmented bar) live in `@exp/ui`, not
+here. Their class strings and pure helpers live in
+`@exponential_app/eui/web/primitives` (FEED-131), shared with the Solid twin
+(`@exponential_app/eui-solid/primitives`, the same module set). `@exp/ui` re-exports every one
+(its old paths are one-line shims), and its `styles.css` scans this directory
+so the app's Tailwind build still emits their classes. An embedder without
+Tailwind takes the compiled `dist/exponential-ui-react.css`
+(`bun run --filter @exponential_app/eui-react build:css`).
+
+## Commands
+
+```bash
+bun run --filter @exponential_app/eui-react test            # jsdom: fixtures → DOM, bind-time, round 1, inputs, data, theme css, primitives (LANG=en_US.UTF-8)
+bun run --filter @exponential_app/eui-react test:browser    # headless Chromium: geometry, overlays, typing, rounds 1–2, conformance
+bun run --filter @exponential_app/eui-react bench:list      # the 100,000-row list bench in Chromium
+bun run --filter @exponential_app/eui-react typecheck
+bun run --filter @exponential_app/eui-react dev:harness     # http://localhost:4181/?view=kitchen-sink&theme=playful
+bun run --filter @exponential_app/eui-react shots           # shots/exponential-ui-kitchen-sink/{web,web-mobile}.webp
+bun run --filter @exponential_app/eui-react build:css
+bun run --filter @exponential_app/eui-react smoke:pack      # packs both packages, builds a plain Vite app on them, renders the sink
+```
+
+The app's `/exponential-ui-kitchen-sink` route (view `exponential-ui-kitchen-sink`)
+renders the same fixture with the app's icon registry; the theme builder
+(`packages/exponential-ui/builder`) previews its recipe sheet and the sink
+through this renderer.