@exponential-at/ui 0.0.0-stage → 0.1.0

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-at/ui` — the Exponential UI catalog
 
-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 data half of Exponential UI (VAPP-84): the **core catalog** of
+components an A2UI surface may use, the **A2UI basic catalog** vendored and
+mapped onto it, the **macro table** that turns composite components into
+natives, the **model-facing descriptions** and prompt, the **token names**
+themes must define, the **runtime theme format** with the four built-in
+themes and the theme builder (VAPP-92), codegen for TypeScript, Swift, Kotlin
+and Rust, and the fixtures every renderer suite locks against. No renderer
+lives here (React: VAPP-87, Solid: FEED-128, the web component
+`<exponential-surface>`: FEED-130, the Rust core: VAPP-86, painters:
+VAPP-88/89/90).
+
+It also defines the **host API** every renderer shares (VAPP-91: transport,
+functions, bindings, negotiation, policy, declarative packages, the
+Exponential connector) and packages the **conformance suite**. The workspace
+package.json stays `"private": true` with `main` on the sources; the npm
+package is staged and published by `release/` on `ui-v*` tags. Depends on
+nothing from the Exponential app.
+
+## Layout
+
+| path | what |
+|---|---|
+| `catalog/core.catalog.json` | THE source: ids, enums, shared shapes, functions (the basic 14 + the 17 core ones, `functions.core`), the built-in glyphs (`builtinIcons`), 76 components (74 offered + the hidden TreeGuides part and Unknown placeholder; round 4 removed the round-3 aliases; EXP-1259 added `SearchList`, EXP-1324 `Trace` + `TraceItem`, EXP-1280 `ChoiceTiles`) with props + descriptions |
+| `catalog/macros.json` | the declarative expansion table, one template per macro component |
+| `catalog/basic-map.json` | A2UI basic → core: components (+ named transforms), icons, functions |
+| `catalog/style.json` | the `Box` style whitelist (VAPP-4), one source for TS / schema / natives |
+| `catalog/tokens.json` | the token NAMES (`$color.primary`, `$spacing.md`, `$breakpoint.md`, `$ease.standard`, …); values come from a theme |
+| `catalog/strings.json` | round 1: the renderers' built-in UI copy (ids + English defaults), overridable per surface, referenced as `$string.<id>` |
+| `catalog/locale.json` | round 1: week start by region, likely regions (CLDR), deprecated language aliases, the RTL languages, the glyphs mirrored under RTL |
+| `catalog/code.json` | round 1: CodeBlock's built-in tokenizer (rules + per-language specs) |
+| `catalog/a11y.json` | round 1: the machine-readable role vocabulary; per component its role, notes and keyboard expectations; the rules; the host commands (focus, announce, scrollIntoView). Macro parts carry role/states/name via `$a11y` (macros.json) |
+| `catalog/layout.json` | round 2: the shared layout numbers (window threshold + overscan, field and media intrinsic sizes, Resizable step/min/hit, the tree-guide column/radius/bridge) |
+| `catalog/recipes.json` | the recipe contract: interaction states (+ `invalid`, `dragover`), the recipe key whitelist (+ motion, transform, per-side borders), every native's parts + `when` props (macro parts come from macros.json) |
+| `catalog/host.json` | the host API contract (VAPP-91): message kinds, ops, error codes, function decisions, URL schemes, MCP carrier, package format |
+| `catalog/core.schema.json` | generated: the catalog as JSON Schema in A2UI's catalog shape |
+| `catalog/theme.schema.json` | generated: a theme file as JSON Schema |
+| `themes/` | the built-in themes: `neutral` (stock shadcn, the root), `exponential` (GENERATED: design-tokens values + `exponential.recipes.json`), `playful` (the test theme), `orange` (the brand reference: `exponential` with an orange primary) |
+| `builder/` | the theme builder page (`dev:builder` / `build:builder`); ui.exponential.at mounts it (VAPP-93) |
+| `src/` | the TS reference implementation (below) |
+| `generated/*.{swift,kt,rs}` | generated constants for the three native targets; `*Themes*` = the built-ins RESOLVED, embedded as JSON; `catalog.descriptions.generated.rs` = the catalog's text for a Rust host behind the crate's `descriptions` feature (VAPP-106) |
+| `generated/core.runtime.json` | VAPP-106: the RUNTIME catalog `src/catalog.ts` loads (the source minus every description, example and `$comment`): what a renderer needs, what the Rust core embeds |
+| `generated/core.descriptions.json` | VAPP-106: the rest of the source, keyed like the catalog; `describeCatalog()` (`src/catalog.described.ts`) attaches it for the prompt, the schema emitter and the docs |
+| `docs/components.generated.json` | generated: one doc page per component as data (ui.exponential.at renders it, VAPP-93) |
+| `docs/themes.generated.json` | generated: the token vocabulary with every built-in's values, the recipe contract per component |
+| `fixtures/` | the contract (below) |
+| `docs/round-1-contract.md` | the renderer-hardening round: every contract change with notes per renderer |
+| `docs/round-2-contract.md` | round 2: Resizable, sticky, backdrop blur, animations, the Formatter, sections + scrollToIndex, the 53 gpui-vs-web decisions; a checklist per renderer |
+| `docs/round-3-contract.md` | round 3 (VAPP-102): ONE Row / Section / Chip / Segmented / Menu, the core-computed tree guides (`src/tree-guides.ts`, `fixtures/tree-guides.json`), the 16 names round 4 removed, the lite prune |
+| `src/host/` | the host API reference: router, decoders, policy, sources, packages, the `ExponentialHost` runtime + transports |
+| `src/connector/` | the Exponential connector (MCP OAuth + `exp:` sources over MCP) and `createAppHost` |
+| `conformance/` | the conformance suite: `manifest.json` (generated), `report.schema.json`, the runner guide; round 1's real-font harness beside it (`run.ts`, `dump.ts`, `compare.ts`, `fonts.json`); the shared web runner (`browser-suites.ts`) and the web-parity check (`parity.ts`: Solid and the web component against React) |
+| `release/` | the npm build + staging scripts and the release runbook (all registries) |
+| `vendor/a2ui/` | A2UI v0.9 schemas, byte-pinned (see its README) |
+| `vendor/json-render/` | attribution for the borrowed description wording |
+
+## The catalog
+
+Canonical names are shadcn's; the issue's table decides what is **native**
+(a renderer paints it) and what is a **macro** (expanded into natives before
+painting). Every component has one sentence, every prop one sentence; both
+are what the model reads. Components carry `variant` and `size` where
+shadcn does (`default|secondary|outline|ghost|destructive|link`,
+`sm|default|lg|icon`); what a variant looks like is the theme's recipe, keyed
+by the `recipe: {macro, part, props}` every expanded node carries.
+
+Ids: `CORE_CATALOG_ID` = `https://ui.exponential.at/catalogs/core/v1`,
+`CORE_LITE_CATALOG_ID` (the subset without overlays, media and Chart),
+`A2UI_BASIC_CATALOG_ID`; `SUPPORTED_CATALOG_IDS` is what a client advertises.
+
+Wire form = A2UI's: a flat list of `{id, component, …props, children: [ids] |
+{componentId, path}, slots?: {name: id}, on?: {event: Action}, style?}`.
+Normalized form (what painters get) = `UiNode`: `{id, component, props,
+style?, on?, children: [UiNode], slots?, template?, recipe?}`.
+
+## Themes (VAPP-92)
+
+A theme is **data, never code**: one JSON file (`catalog/theme.schema.json`)
+every renderer loads at runtime, safe to fetch from a URL or a app package.
+Three levels of customisation, cheapest first: **tokens** (colours per mode,
+radius, spacing, type, control heights, shadows, border widths, motion, the press / popover-enter `scale`),
+**recipes** (per component part × `when` selector a small style object), and a
+**painter override** through the extension API (VAPP-91) that must keep the
+measure contract (`src/geometry.ts`, `fixtures/control-geometry.json`).
+
+```jsonc
+{
+  "id": "brand", "name": "Brand", "extends": "neutral",      // override only what changes
+  "modes": { "light": { "color": { "primary": "#2563eb" }, "shadow": { "sm": [{ "x": 0, "y": 1, "blur": 2, "spread": 0, "color": "#0000000d" }] } }, "dark": { … } },
+  "tokens": { "spacing": { "md": 12 }, "radius": { … }, "type": { "size": { … }, "lineHeight": { … }, "weight": { … }, "family": { "sans": "Inter" } }, "control": { … }, "opacity": { … }, "border": { … }, "motion": { … } },
+  "fonts": { "Inter": { "fallback": "ui-sans-serif, system-ui", "weights": [400, 500, 600, 700], "source": "host" } },
+  "recipes": {
+    "Button": { "root": [
+      { "style": { "borderRadius": "$radius.full" } },                       // the part's base
+      { "when": { "variant": "outline", "state": "hover" }, "style": { "backgroundColor": "$color.accent" } }
+    ] }
+  }
+}
+```
+
+- **Colours are `#rrggbb[aa]` only**; the builder's importer converts
+  oklch/hsl/rgb (`importShadcnCss`). Shadows live under `modes` (they differ
+  in the dark); every other group under `tokens`. Fonts are referenced by
+  family; the host registers the files per platform (`fonts` says what to
+  fall back to).
+- **Recipes**: `recipes.<Component>.<part>` = a list of rules; a rule applies
+  when every `when` entry matches (`state` = every listed state is active;
+  any other key = the recipe prop equals the value or is in the list). Rules
+  merge by SPECIFICITY (one point per `when` condition; ties in source order,
+  later wins — VAPP-90, the order the web's CSS gives them), so a child
+  theme's appended base rule never shadows its parent's `checked`/`focus`/
+  `variant` rules; a child theme's rules come after its parent's.
+  The keys a rule may set are `catalog/recipes.json` `keys` (the Box visual
+  subset + padding/gap/size + `native`); values may be token references.
+  Parts and `when` props per component: `recipeParts()` (natives from
+  `recipes.json`, macros from their templates: every `part`, the macro's
+  `recipeProps` + `$recipe` keys). States: hover, pressed, focus, disabled,
+  checked, open, selected, invalid, dragover.
+- **Precedence a painter applies** (`resolveNodeStyle`): the native's own
+  recipe (Text/root for its variant) < the node's style (the macro
+  template's structure + the author's style) < the macro part's recipe
+  (Badge/label). Macro templates state only structure, spacing, radius and
+  control heights; every colour and border is a recipe, so a theme restyles
+  what a template drew.
+- **Surface settings** (round 1): `mode` light | dark | system
+  (`resolveMode`), `density` compact | default | comfortable
+  (`applyDensity` scales `$control.*` and `$spacing.*` by the theme's
+  `$density.*`), high contrast (`applyContrast` merges the theme's
+  `contrast` overlays), `$breakpoint.*` for style conditions and responsive
+  props, `$ease.*` for transitions; `shadow` none → xl is the elevation scale.
+- **Loading**: `validateTheme(json)` → issues with a path and a readable
+  message (unknown token, key outside the whitelist, unknown part…);
+  `loadTheme(json, {themes})` flattens the `extends` chain into a
+  `ResolvedTheme` (every token present, recipes merged) or throws ONE
+  `ThemeError` listing every issue; `tryLoadTheme` never throws. A root theme
+  must give every token name a value. Built-ins: `builtinTheme(id)`,
+  `BUILTIN_THEMES`, `DEFAULT_THEME_ID` (`exponential`).
+- **Resolving**: `resolveRecipe(theme, {component, part, props, states}, mode)`
+  → concrete values (hex, px, shadow layers, family); `resolveStyleValues`
+  for a Box style; `styleToCss` for web painters.
+- **Built-ins**: `neutral` = stock shadcn light + dark and the full recipe
+  set (the root every other theme extends); `exponential` = the zinc glass
+  look, GENERATED from `packages/design-tokens/tokens.json` + the app's
+  `styles.css` palettes + `themes/exponential.recipes.json` so the app and
+  the SDK cannot drift; `playful` = the deliberately different test theme
+  (pill buttons, no card borders, underlined tabs, Nunito) the conformance
+  suite renders on every painter; `orange` = the brand-coloured reference
+  theme, `extends: exponential` with only the colours changed (primary, ring,
+  the accent pair, the chart scale), the smallest brand theme there is. The
+  natives get all four RESOLVED in
+  `generated/ExponentialUIThemes.generated.*` (parse once at startup).
+- **Builder** (`builder/`, `bun run --filter @exponential-at/ui dev:builder`
+  → :4180): pick a base, edit tokens and recipes with the recipe sheet and
+  the kitchen sink previewed live, import a shadcn `globals.css` / tweakcn
+  export or a theme JSON, export the smallest `extends` theme
+  (`diffTheme`). The preview is the real React renderer
+  (`builder/preview.tsx` on `@exponential-at/ui-react`, VAPP-87): what the
+  builder shows is what a host gets.
+
+## The reference implementation (`src/`)
+
+- Round 1 (`docs/round-1-contract.md`): `dynamic.ts` (the BIND pass: `resolveDynamic`, `bindTree` with props along the schema and DATA props verbatim, per-row Table slot cells via `bindRowSlot`, `runAction` with the `set` write-back), `strings.ts`, `locale.ts`, `code.ts` (CodeBlock tokenizer), `chart.ts` (extents, nice ticks), `a11y.ts`, and in `style.ts` the condition resolver (`resolveConditions`, `activeBreakpoint`); `theme.ts` gains `resolveMode`, `applyDensity`, `applyContrast`.
+- `reduceSurface(components, {catalogId, extensions?})` — flat list → one
+  normalized tree, basic components mapped, macros expanded, every unknown
+  component the `Unknown` placeholder (never an error), prop issues listed.
+  `reduceNested` does the same for the nested authoring form the fixtures use.
+- `expandMacros(tree)` — the macro table applied until every node is native.
+  The template language is documented in `macros.json`'s `$comment` and
+  implemented in `expr.ts` (pure, line-by-line mirrorable in Rust).
+- `validateProps(def, props)` — the mini schema (`types.ts` `PropSchema`).
+- Round 4 (VAPP-103, `fixtures/round4-contract.json`): `validateNode(node)`
+  (the reducer runs it on every authored node: the node's style, every
+  function its props / `visible` / actions call — a catalog function or a
+  namespaced host function, `isCallableName` — and a Table's slot columns);
+  colours in a node are `$color.*` tokens only; the core function
+  `filter{items, query?, fields?, where?}`; `withOwnWrites` (an action's
+  context resolves AFTER the component's own write, given explicitly by
+  prop) and
+  `submitClosesOverlay` (a valid Form submit closes the nearest overlay
+  around it when that is a dismissible Dialog/Drawer); `themeOrDefault` (never throws: the default theme + the issues); a
+  theme must name `$schema` = `THEME_SCHEMA_ID`; an action's function is
+  its `functionCall`.
+- `validateStyle` / `create` / `props` — the VAPP-4 `app-css` over the whitelist.
+- `defineExtension(def)` — an extension catalog: own id, `extends` the core,
+  components (+ macro templates), no core name shadowed.
+- `catalogPrompt({extensions?, lite?, terse?})` — the compact system prompt.
+- `coreSchema(iconNames)` / `extensionSchema(ext, iconNames)` — JSON Schema.
+
+## The web layer (`@exponential-at/ui/web`)
+
+FEED-128: the FRAMEWORK-FREE half of a web renderer, so React and Solid compile byte-identical stylesheets and share one bind pass. `src/web/`: `theme-css.ts` (`compileTheme`: a resolved theme → one scoped sheet; `globalsCss(theme, {light?, dark?})`: the theme as UNSCOPED shadcn globals with literal values, `:root` + `.dark`, for an app that is not Exponential UI), `box-css.ts` (the per-node sheet), `base-css.ts` (`BASE_CSS`, layer `xui-base`), `data.ts` (JSON pointers, bindings, client functions, `bindTree`), `urls.ts` + `media.ts` (URL/media policy, the bounded blob cache, `fetchLimited`), `host-types.ts` (`HostPlugin<Icon, Markdown>`, the events), and the natives' pure helpers (`coerce`, `table`, `dates`, `inputs` = `HostOwnedController`, `markdown` = the parser to a tree, `form` = the field registry, `list`, `listbox`). Nothing in it imports a UI framework.
+
+FEED-131: `@exponential-at/ui/web/primitives` (`src/web/primitives/`) is the framework-free half of the shadcn primitive set: one module per primitive holding its Tailwind class recipes (cva recipes keep their names, `buttonVariants`, `alertVariants`, `codeBlockVariants`; plain strings are one frozen `<MODULE>_CLASSES` object keyed by part, with conditional fragments as keyed entries; the named constants `MENU_*_CLASS`, `SEGMENTED_*`, `GLASS_CARD_CLASS`, `FIELD_CHROME_CLASS`, `MOBILE_ARMS` stay) plus the pure helpers (`cn`, `getInitials`, `middleTruncate`, `avatarHueIndex`, `ringGeometry`, `choiceToggle`, `isTypeaheadPortalInteraction`, …). The React set and its Solid twin import ONE source of class strings, and `recipes.test.ts` fails if either renderer's file of the same name carries a class literal. A Tailwind build that paints them scans this directory (`@source`).
+
+The DOM contract every web renderer keeps: a `.xui-surface.<scope>` root with `data-xui-mode`; `data-xui-id` (placed nodes and parts), `data-xui-part="<Component>/<part>"`, recipe props as `data-r-*` (natives) / `data-m-*` (macro parts), forced states as `data-xs`; `xui-<Component>-<part>` part classes (`partClass`); and the cascade order `LAYERS` (`xui-base` < `xui-recipe` < `xui-node` < `xui-part`).
+
+## The host API (VAPP-91)
+
+A surface needs exactly this from its host, the same shape on all four
+platforms (TS here, the Rust core's `host` module, the Swift and Kotlin
+painters through the facade); `catalog/host.json` is the contract and
+`fixtures/host-{transport,policy,router}.json` lock it everywhere.
+
+- **Transport**: messages in = the four A2UI v0.9 messages plus two
+  extensions, `applyTemplate {surfaceId, templateId, packageId?, data?}` and
+  `bindDataModel {surfaceId, path, source}`; client messages out = A2UI's
+  `{version, action: {name, surfaceId, sourceComponentId, timestamp,
+  context, payload?}}` or `{version, error: {code, surfaceId, message,
+  path?}}`. Adapters: `MemoryTransport`, `JsonlStreamTransport`,
+  `SseTransport`, `WebSocketTransport`, `McpTransport` (A2UI resources with
+  `application/json+a2ui` in a tool result; actions back as tools/call
+  `a2ui_event`), all on the shared decoders (`JsonlDecoder`, `SseDecoder`,
+  `messagesFromMcpResult`).
+- **Router**: `HostRouter.route(message)` → ops `create | components | data |
+  bind | delete | send` (pure; errors `UNSUPPORTED_CATALOG`,
+  `SURFACE_NOT_FOUND`, `INVALID_MESSAGE`, `TEMPLATE_NOT_FOUND` go back as
+  `send`).
+- **Functions**: an `on.<event>` `{functionCall: {call, args}}` (A2UI's
+  key) to a non-built-in name runs the host's
+  registered function after the gate: `decideFunction(policy, name,
+  registered)` → `allow | ask | deny | not_found` (deny wins, then allow,
+  then ask, then `default`; `harness.*` prefixes), `ask` = the host's
+  `onFunctionCall` consent hook; a package surface's `functions` list
+  narrows it (`combineDecisions`). The catalog's functions (the basic 14 + the 15 core ones) are built in.
+- **Bindings**: `source` URIs `<scheme>:<name>?k=v` (`parseSource`); a host
+  registers a resolver per scheme (`subscribe(source, emit) → cancel`), each
+  emit lands at the bound path.
+- **Negotiation**: `supportedCatalogIds(extensionIds)` = core, core lite,
+  A2UI basic, then the registered extensions; `clientCapabilities`.
+- **Policy** (every renderer, every href and src): `decideUrl` (schemes
+  `https http mailto tel`; `schemes: ["https"]` = https only; optional host
+  allowlist; relative urls against `baseUrl`) for `openUrl`, `Link`,
+  markdown links and FileUpload file urls (`safeHref`; denied = plain
+  text); `mediaRequest(url, {baseUrl, rules, schemes, hosts,
+  allowPrivate})` = the image loader's url + headers (auth for
+  `/api/attachments`), null when the media policy (default `https http
+  data`, `file` only when listed) denies it; `MEDIA_LIMITS` (20 MiB, 30 s,
+  32 Mpx across every frame, read by `mediaImageWithinLimits` before
+  decoding: header or SVG size × `imageFrames`; an unreadable raster is
+  refused) bound every image load, and the React video/audio whole-fetch
+  fallback too (VAPP-107). **Private hosts are denied by default**
+  (VAPP-107, `isPrivateHost`): `localhost`, `*.localhost`, `*.local`,
+  0/8, 10/8, 127/8, 169.254/16, 172.16/12, 192.168/16, `::`, `::1`,
+  fe80::/10, fc00::/7 and IPv4-mapped private addresses, for http(s)
+  hrefs and media alike, reason `private`; a host opts names back in with
+  `allowPrivate: ["localhost"]` (`*.suffix`, or `*` for all), which a
+  `hosts` allowlist does not do. Literals only: no DNS lookup (a public
+  name that resolves privately is the network's job). The threat model:
+  https://ui.exponential.at/guides/security/.
+- **Runtime**: `new ExponentialHost({transport, functions, sources,
+  extensions, packages, policy})`: `connect()`, `receive(message)`,
+  `surface(id)` (a `SurfaceStore`), `action(...)`, `callFunction(...)`,
+  `openUrl(url)`, `mediaRequest(src)`, `paintError({surfaceId,
+  componentId, message})` (a renderer's `onPaintError` → ONE A2UI
+  `RENDER_FAILED` error per surface + component + message), `status` / `hasTransport` /
+  `unsupportedCatalog` (the `host_offline` state and the catalog-update
+  banner), `issues` + `onIssue` (invalid packages, the errors it answered,
+  an unusable `createSurface.theme`; a package in `packages` that fails
+  validation throws `PackageError`). A surface's `createSurface.theme` (a
+  built-in id or a theme JSON) lands on `store.theme`. React paints it with
+  `<HostSurface host surfaceId>` (the surface's theme wins over `theme`).
+  Stream transports end on a clean EOF (`resumable` or an SSE `retry:`
+  reconnects) and reconnect after errors.
+- **Declarative apps** (VAPP-82): a package `{id, name, version, catalogId,
+  templates: {<id>: {components, data?, bindings?}}, functions?, theme?,
+  icon?}` (`validatePackage`); `createAppHost({package, …})` runs one in any
+  host. Against an Exponential instance, `ExponentialConnector` does the MCP
+  OAuth grant (discovery, dynamic registration, PKCE S256, consent;
+  `authorizeUrl()` returns `{url, verifier, state, clientId}`: keep all
+  three for the callback, `exchange(code, verifier, clientId)`, so a
+  connector rebuilt after the redirect never registers a second client) and
+  serves `exp:issues|boards|teams|members` over the instance's MCP tools
+  (`sources()`, polled) plus `exponential.mcp` (`functions()`). Hosted apps
+  (the peer-link transport, VAPP-10) embed through the same `Transport`
+  interface.
+
+The Exponential app is a host like any other: web `apps/web/src/lib/exponential-ui-host.tsx`
+(`harness.*` functions, `exp:` over the Electric collections, the consent
+card, the app extension's painters from `@exp/ui`, the Devices package
+`packages/ui/exponential-ui/templates/devices.json` on `/exponential-ui-devices`).
+Samples outside the workspace: `samples/exponential-ui/` (a local A2UI
+server, a third-party theme, one extension component, six hosts).
+
+## Conformance
+
+`conformance/README.md`: 24 suites (version 2); a renderer is conformant
+when `bun run --filter @exponential-at/ui conformance:check <report>` says
+so. All six renderers and the core run it in CI (`exponential-ui.yml`);
+the Solid renderer and the web component also pass the web-parity check
+against React.
+
+## Fixtures (the contract; the Rust core replays them with these test names)
+
+| file | locks |
+|---|---|
+| `catalog-components.json` | every component × its example × every enum value × both booleans |
+| `catalog-macros.json` | every macro case → the expanded tree, byte for byte; round 1 adds a `bound:<prop>` case per bindable macro prop and a `responsive:<prop>` case per responsive one |
+| `bind-time.json` | round 1: every bound macro case × three data models (sample, falsy twin, path missing) → the tree after the bind pass + every `set` press; `extra` = Table slot cells bound per row (`rowSlots`), literal data rows, a bound accessible name, the `$set` collision issue, string page data |
+| `style-conditions.json` | round 1: style × surface/state context → the flattened style (media in source order, then states) |
+| `code-tokens.json` | round 1: source × language → CodeBlock tokens per line |
+| `catalog-basic-map.json` | hand-written A2UI basic surfaces → expected trees + issues |
+| `catalog-extension.json` | an example extension (native + macro + enum) and its cases |
+| `kitchen-sink.json` / `.expanded.json` | every visible component once, the VAPP-4 layout cases kept, round 1's responsive section (1→2→3 column grid, collapsing sidebar, hidden-on-narrow nodes, state blocks) and bound macros; view id `exponential-ui-kitchen-sink` |
+| `specimens.json` | generated (VAPP-93): one surface per component (its example, up to two enum props and two booleans, captioned; an overlay once, open) + `exponential-ui-demo` from the hand-written `demo-surface.json`; id = the view id ui.exponential.at shows four shots of |
+| `prompt-budget.json` | the prompt's size on record (full / lite / terse) and the budget |
+| `theme-resolved.json` | every built-in theme resolved: what a native loader must produce from the same files |
+| `theme-recipes.json` | theme × component part × recipe props → visuals per mode and state (one case per distinct look) |
+| `theme-extends.json` | `extends` cases (the acceptance case: neutral + primary + button radius) → chain + probe styles |
+| `theme-invalid.json` | bad themes → the issues they must raise (paths ×4, never a crash) |
+| `control-geometry.json` | theme × control × props → the box a painter or override must measure to |
+| `host-transport.json` / `host-policy.json` / `host-router.json` | the host API (VAPP-91): decoders, the gate / urls / media / sources / negotiation, router flows → ops |
+| `format.json` | round 2: the format functions through the English fallback Formatter (= Intl en-US; UTC, and `zoned` at a fixed offset) + what a text prop shows for a bound number/boolean |
+| `template-items.json` | round 2: item keys (`#<index>` for missing/duplicate), Table row keys, accumulated (escaped) instance suffixes, template nodes lifted out of the tree, cycles reported |
+| `text-direction.json` | round 2: per-node direction (`direction` on any node) and the physical text alignment |
+| `resizable.json` | round 2: Resizable sizes: normalize, drag, keys (rtl), extents, px → percent |
+| `virtual-list.json` | round 2: the one-axis window, scrollToIndex, sections, the sticky header |
+| `animations.json` | round 2: timing + sampled frames of every `animation` per built-in theme, reduced motion, the CSS @keyframes |
+| `bench-list.json` | round 2: the 100,000-row List every renderer benches (numbers in each renderer's README) |
+| `round4-contract.json` | round 4 (VAPP-103): authored trees → the validator's issues; `filter` args → items; an Input/Switch change → the data + the action context after the own write; a Form submit → which Dialog/Drawer closes |
+| `conformance-known.json` | the gpui ratchet + round 2's 53 divergence decisions (`causes`, `rules`) |
+
+## Commands
+
+```bash
+bun run --filter @exponential-at/ui generate   # idempotent; generate.test.ts gates drift
+bun run --filter @exponential-at/ui test
+bun run --filter @exponential-at/ui typecheck
+```
+
+Change a component = edit `core.catalog.json` (and `macros.json` for a macro),
+run generate, commit everything it rewrote. The icon vocabulary is read from
+`packages/icons/icons.json` at generate time; the exponential theme reads
+`packages/design-tokens/tokens.json` and `packages/ui/src/styles.css` at
+generate time too (never at runtime).
+
+```bash
+bun run --filter @exponential-at/ui dev:builder     # the theme builder on :4180
+bun run --filter @exponential-at/ui build:builder   # bundles builder/dist (ignored)
+bun run --filter @exponential-at/ui size            # VAPP-106: bundle + binary sizes vs release/size-budget.json (release/README.md)
+```
+
+### Entries (VAPP-106)
+
+The root `@exponential-at/ui` is what a renderer needs (the runtime catalog,
+macros, the reducer, the validator, bind-time, formatting, themes, the host
+API). What only a server or a tool needs is an entry of its own, so a
+browser never downloads it: `@exponential-at/ui/prompt` (`catalogPrompt`,
+`estimateTokens`, `PROMPT_RULES`; it attaches the catalog's descriptions and
+examples with `describeCatalog()` first), `./schema` (`coreSchema`,
+`extensionSchema`, with the vendored A2UI basic catalog), `./conformance`
+(`conformanceManifest`, `checkReport`, with every fixture bundled),
+`./host` (the host API alone). The entries share chunks; sizes are on
+record in `release/sizes.json`.
+
+## Extensions
+
+The Exponential app's extension (IssueRow, SessionRow, IssueChip, …) lives with
+the app at `packages/ui/exponential-ui/extension.json` and is validated by
+`@exp/ui`'s tests through `defineExtension`; it is the first user of the
+mechanism and not part of this package.