@adia-ai/web-components 0.8.40 → 0.8.42

package/README.md

@@ -1,9 +1,9 @@
 # @adia-ai/web-components
 
-Vanilla web components + A2UI runtime for AdiaUI. **95 light-DOM custom
-elements** + **56 composable traits**, a reactive core (signals + tagged-template renderer), form-associated form controls, and integration into the A2UI generation pipeline.
+Vanilla web components for AdiaUI. **~130 light-DOM custom elements**
+(`ls components | wc -l` is the census) + **56 composable traits**, a reactive core (signals + tagged-template renderer), form-associated form controls, and integration into the A2UI generation pipeline.
 
-> This package ships UI atoms only. Composite shells (admin / chat / editor / simple / theme) live in [`@adia-ai/web-modules`](../web-modules). The generation pipeline lives in [`@adia-ai/a2ui-compose`](../gen-ui/engine/compose); the pattern corpus in [`@adia-ai/a2ui-corpus`](../gen-ui/engine/corpus); the MCP server in [`@adia-ai/mcp`](../gen-ui/mcp) (its `gen-ui` surface).
+> This package ships UI atoms only. Composite shells (admin / chat / editor / simple / theme) live in [`@adia-ai/web-modules`](../web-modules). The A2UI protocol runtime lives in [`@adia-ai/a2ui`](../gen-ui/a2ui); the generation pipeline + pattern corpus in [`@adia-ai/gen-ui`](../gen-ui/engine); the MCP server in [`@adia-ai/mcp`](../gen-ui/mcp) (its `gen-ui` surface).
 >
 > **Consumer guide:** [`USAGE.md`](./USAGE.md) — property reactivity, event contract, form participation, lifecycle, registration, TypeScript. Start here if you're integrating AdiaUI into an app.
 >
@@ -25,7 +25,7 @@ npm install @adia-ai/web-components @adia-ai/web-modules
 
 When composing UI with an AI coding agent, load the **`adia-ui-kit` skill** in the agent's harness. It encodes:
 
-- 95-primitive catalog (which `*-ui` tag does what + when to use it)
+- The full primitive catalog (which `*-ui` tag does what + when to use it)
 - Composition patterns (admin shell, dashboards, forms, chat, editor surfaces)
 - Pre-flight manifest gate (catches "imports without declared deps" before authoring)
 - Plan-Execute-Verify discipline (render the result in a real demo to verify)
@@ -40,13 +40,13 @@ Since **v0.6.30**, this package ships pre-flattened + minified bundles under `di
 <!-- CSS: all primitives, tokens, resets (443 KB raw / ~50 KB gzipped) -->
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.8/dist/web-components.min.css">
 
-<!-- JS: registers all 122 primitives (~250 KB gzipped via Brotli) -->
+<!-- JS: registers every primitive (~250 KB gzipped via Brotli) -->
 <script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.8/dist/web-components.min.js"></script>
 ```
 
 The `@0.8` range tracks the latest `0.8.x` patch automatically (won't jump to a breaking `0.9`). For reproducible builds, pin an exact version instead — e.g. `@adia-ai/web-components@0.8.7/dist/web-components.min.css`.
 
-For composite shells, add the corresponding bundle from `@adia-ai/web-modules` — see [its README](../web-modules/#cdn-no-bundler--codepen-marketing-pages-static-html) or the [CDN usage guide](https://ui-kit.exe.xyz/site/cdn-usage). The kitchen-sink path is `@adia-ai/web-modules/dist/everything.min.js` (all primitives + all 4 shells; ~190 KB gzipped) — one tag for CodePen demos.
+For composite shells, add the corresponding bundle from `@adia-ai/web-modules` — see [its README](../web-modules/#cdn-no-bundler--codepen-marketing-pages-static-html) or the [CDN usage guide](https://ui-kit.exe.xyz/site/cdn-usage). The kitchen-sink path is `@adia-ai/web-modules/dist/everything.min.js` (all primitives + all 4 shells; ~424 KB gzipped) — one tag for CodePen demos.
 
 **Pick ONE bundle path.** Mixing (e.g. `everything.min.js` + a separate `web-components.min.js`) causes `customElements.define` to throw "name already defined" on dup-load. The choice tree:
 
@@ -59,7 +59,7 @@ For composite shells, add the corresponding bundle from `@adia-ai/web-modules`
 ESM-only — bundlers (Vite, esbuild, webpack 5+, Rollup) resolve `import` for both `.js` and `.css`; in plain HTML use `<script type="module">` + `<link rel="stylesheet">`.
 
 ```js
-import '@adia-ai/web-components';          // registers every *-ui tag (122 primitives)
+import '@adia-ai/web-components';          // registers every *-ui tag
 import '@adia-ai/web-components/css';      // every primitive's CSS (one stylesheet)
 ```
 
@@ -101,7 +101,7 @@ web-components/
 │   └── data-stream.js   `data-stream-*` attribute trait (HTTP/SSE/WS,
 │                        signal-backed, refcounted shared transports)
 │
-├── components/     — 95 *-ui custom elements (primitives)
+├── components/     — ~130 *-ui custom elements (primitives)
 │   └── <tag>/
 │       ├── <tag>.js       class definition (extends UIElement / UIFormElement)
 │       ├── <tag>.css      @scope(tag-ui) two-block: tokens + styles
@@ -119,14 +119,6 @@ web-components/
 │                     drives the MCP get_traits tool + per-trait demo
 │                     pages. Full contract in .claude/docs/specs/traits.md.
 │
-├── a2ui/           — deprecation shim for one release
-│   └── index.js            Re-exports @adia-ai/a2ui-runtime with a
-│                           one-time console.warn. Removed in 0.1.0.
-│                           All actual A2UI runtime code (renderer,
-│                           registry, streams, surface manifest,
-│                           wiring, dockables, controllers) lives in
-│                           `@adia-ai/a2ui` at packages/gen-ui/a2ui/.
-│
 └── styles/         — Global tokens and CSS layering
     ├── tokens.css              all --a-* design tokens
     ├── colors/                 primitives / semantics / scrims
@@ -261,13 +253,14 @@ examples.
 
 ## A2UI runtime
 
+The A2UI runtime lives in the sibling zero-dependency [`@adia-ai/a2ui`](../gen-ui/a2ui) package; this package is the component catalog its renderer resolves tags against:
+
 ```javascript
-import { A2UIRenderer } from '@adia-ai/a2ui-runtime';
-// (The old `@adia-ai/web-components/a2ui` subpath still resolves in 0.0.4
-// via a deprecation shim that prints a console.warn; removed in 0.1.0.)
+import { A2UIRenderer } from '@adia-ai/a2ui';
+import '@adia-ai/web-components';   // register the custom elements
 
-const renderer = new A2UIRenderer({ target: document.getElementById('canvas') });
-renderer.apply({
+const renderer = new A2UIRenderer(document.getElementById('canvas'));
+renderer.process({
   type: 'updateComponents',
   components: [
     { id: 'root', component: 'Card', children: ['hdr', 'body'] },
@@ -278,10 +271,11 @@ renderer.apply({
 });
 ```
 
-Accepts the four A2UI message kinds: `updateComponents`,
-`updateDataModel`, `wireComponents`, `createSurface`. The registry
-normalizes LLM-emitted aliases (e.g. `Carousel` → `swiper-ui`) so generated
-output is robust to name drift.
+Core message kinds: `createSurface`, `updateComponents`,
+`updateDataModel`, `wireComponents`, `deleteSurface` (plus
+`updateStyles`/`removeStyles`). The registry normalizes LLM-emitted
+aliases (e.g. `Carousel` → `swiper-ui`) so generated output is robust
+to name drift.
 
 ## Data streaming via `data-stream-*` attributes
 
@@ -329,9 +323,10 @@ attribute table + live demos:
 npm run build:components    # regenerate all .a2ui.json from YAML
 ```
 
-The build also writes `packages/gen-ui/engine/corpus/catalog-a2ui_0_9.json` and
+The build also writes `packages/gen-ui/a2ui/catalog/catalog-a2ui_0_9.json` and
 `catalog-a2ui_0_9_rules.txt` — the flat-file catalog the MCP server and
-generation engine consume.
+generation engine consume (ADR-0050: the catalog is `@adia-ai/a2ui`'s
+contract).
 
 ## Themes, density, scale
 
@@ -353,11 +348,11 @@ Each is a CSS-variable override; no class toggles, no re-imports.
 ## Dependency direction
 
 ```
-a2ui-compose  ──reads──>  a2ui-corpus  ←─reads──  web-components
-a2ui-mcp      ──reads──>  a2ui-compose, a2ui-corpus
+gen-ui (compose/) ──reads──>  gen-ui (corpus/)  ←─reads──  web-components
+mcp               ──reads──>  gen-ui
 ```
 
-Web-components never imports from a2ui-compose or a2ui-mcp. The A2UI renderer
+Web-components never imports from `@adia-ai/gen-ui` or `@adia-ai/mcp`. The A2UI renderer
 consumes a protocol, not a generator — anything that emits valid A2UI
 messages drives it.
 

package/USAGE.md

@@ -104,6 +104,32 @@ guide and the yaml disagree, the yaml wins — file a doc-bug FEEDBACK.
 
 For the live demo of every component: <https://ui-kit.exe.xyz/site/components/>.
 
+### SSR admission gate — `adia-ui-audit-template-children` (gh#1446)
+
+A second bin, for a consumer running its own SSR pipeline against this
+package: it flags any shipped component whose `static template` is non-null
+AND whose yaml declares a `slots.default` entry — the shape where
+`connectedCallback`'s first-mount `stamp()` calls `replaceChildren()` and
+silently destroys real, server-rendered light-DOM children (gh#284). Resolves
+against the INSTALLED package (`node_modules/@adia-ai/web-components/components/**`
++ `@adia-ai/web-modules` if present), not this repo's own source tree — the
+same audit `scripts/dev/audit-template-child-conflict.mjs` runs here, now
+consumable outside the monorepo instead of needing its own reimplementation:
+
+```bash
+npx adia-ui-audit-template-children            # human-readable report
+npx adia-ui-audit-template-children --json     # machine-readable, for a CI gate
+npx adia-ui-audit-template-children --strict   # also fail on advisory (projected-text) findings
+```
+
+Exit 0 clean, 1 on a finding (critical always; advisory only under
+`--strict`), 2 on a usage error. The exact definition of "accepts consumer
+children" this bin enforces is documented in its own header
+(`node_modules/@adia-ai/web-components/bin/audit-template-children.mjs`) —
+read it there before reimplementing any part of this check; a
+reimplementation that drifts from that definition is the bug gh#1446 was
+filed to fix.
+
 ---
 
 ## Icons — wiring the registry
@@ -411,7 +437,7 @@ Some primitives emit named events beyond `change`/`input`:
 - `<select-ui>` — emits `action` for option-callbacks with `detail.action`
 - `<search-ui>` — emits `search` after debounce with `detail.value`
 - `<chat-composer>` — emits `composer-submit` on Enter with `detail.value`
-- `<color-picker-ui>` — emits `input` + `change` with rich detail (`{ value, l, c, h, hex, oklch }`)
+- `<color-area-ui>` — emits `input` + `change` with rich detail (`{ value, l, c, h, hex, oklch }`)
 
 Each primitive's yaml lists its complete event surface. Live demos at `https://ui-kit.exe.xyz/site/components/<name>`.
 
@@ -1182,18 +1208,18 @@ When a custom `[slot="header"]` carries action buttons (Copy / Download / Edit),
 
 §206 (v0.5.7) added the `[slot="action"]` / `[slot="actions"]` / `[data-no-toggle]` exclusion list to the toggle-cascade.
 
-### §221f — `<color-picker-ui>` inline pattern
+### §221f — `<color-area-ui>` inline pattern
 
 For a compact swatch-and-popover authoring shape:
 
 ```html
 <popover-ui trigger="click" placement="bottom-start">
   <button-ui slot="trigger" text="" icon="palette" aria-label="Pick a color"></button-ui>
-  <color-picker-ui slot="content" value="oklch(0.7 0.15 220)" alpha="off"></color-picker-ui>
+  <color-area-ui slot="content" value="oklch(0.7 0.15 220)" alpha="off"></color-area-ui>
 </popover-ui>
 ```
 
-The popover handles focus management + click-outside dismiss; the button-ui exposes the right ARIA semantics. `<color-picker-ui>` fires `change` events that bubble through the popover — listen on the popover host.
+The popover handles focus management + click-outside dismiss; the button-ui exposes the right ARIA semantics. `<color-area-ui>` fires `change` events that bubble through the popover — listen on the popover host. (`<color-area-ui>` is the ADR-0063/gh#1563 rename of `<color-picker-ui>`, which still works as a deprecated alias — this recipe is exactly what `<color-input-ui>` canonicalizes.)
 
 ### §221g — `[data-scheme]` ancestor opt-in for color scheme