@adia-ai/web-components 0.8.36 → 0.8.38

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.38] — 2026-08-15
+
+### Added
+- **`drilldown-ui` — a new single-panel, multi-level drill-in menu primitive (gh#1285).** Replaces the hand-rolled miller-columns shape (two stacked list columns) that adiav2's Schema Manager had to build because the kit had no drill-down primitive — cleared the pre-build audit against `tree-ui` (inline expand/collapse, wrong for wide/deep >2-level data), `segmented-ui` (no overflow behavior for 18 namespaces), `tag-ui`-as-menu (no keyboard path), `list-ui`/`nav-ui`/`menu-ui`/`context-menu`/`breadcrumb-ui` (flat, not hierarchical drill-in) — none provide single-panel level-swap navigation with back/focus-restoration. Data-driven (`.items` tree of `{value, label, meta?, dot?, counts?, children?}` nodes; `children` may be sync or an async `(item) => array | Promise<array>` lazy loader, rendering a `<skeleton-ui>` loading level while pending). Full keyboard path (roving-tabindex listbox per level; ArrowRight/Enter drills in, ArrowLeft/Backspace goes back with focus restored to the item drilled from), `select` + `navigate` events, a `path` property that reflects to a JSON-encoded attribute both ways (hand-managed, not the generic `reflect:` mechanism — array values don't round-trip through `String(v)`) for deep-link/URL restore, `[filterable]` filter input, `[select-on-drill]` mode flag, a `breadcrumb` slot, row-native trailing count chips (not full `<badge-ui>`, which reads oversized at row density), and a horizontal slide transition that honors `prefers-reduced-motion: reduce` automatically (also suppressible via `[static]`).
+
+### Fixed
+- **`page-ui` header now ships the slot-gated grid its docs promised (gh#1253).** ADR-0009 recorded the named-slot vocabulary (`slot="icon"` / `slot="heading"` / `slot="action"`) as wired into four containers — Card, Drawer, Modal, and Page — but `page.css` never shipped its half; the slot attributes on a page header's children were dead metadata, so a block-level action child (e.g. `<toggle-scheme-ui>`) dropped to its own row instead of clustering. `page.css` gains the same `:has(> [slot])`-gated header grid as `card.css` (icon/heading/action columns, direct-child guard against nested false-positives), plus the `--page-header-gap` / `--page-heading-*` tokens `card-ui`'s pair already had. `page.yaml`'s `slots.default` and `page.examples.html` (new "Header slot-gated grid" demo) now describe the contract that's actually implemented.
+- **`nav-ui` / `nav-item-ui` — `nav-select` now fires exactly once per click, and zero times re-clicking the already-selected item (gh#1254).** Root cause: two layered click handlers both drove selection for the same physical click — `nav-item-ui`'s own click handler called `nav.select(this)` *and* dispatched its own `nav-select`, while `nav-ui`'s click-delegation listener matched the same item on bubble and called `select()` again — three dispatches per click. `nav.select()` is now the single source of the event (idempotent: a no-op, including no hover-flush, when the item is already selected); `nav-item-ui` no longer dispatches its own copy, and `nav-ui`'s click listener no longer delegates item selection (it now only handles group expand/popover).
+- **`view-transition` trait — no longer leaks unhandled `AbortError` rejections when a transition is superseded (gh#1255).** Only `transition.finished` had a `.catch()`; `ready` and `updateCallbackDone` are distinct promises that also reject (with `AbortError`) when a newer transition supersedes this one, and were previously uncaught. All three are now swallowed on abort — expected behavior for rapid navigation, not an error — with `fireEnd()` still driven solely by `finished`.
+
+### Maintenance
+- **`bin/` touched in this release window** (1 file(s), e.g. `bin/doc.mjs`) — carried by the entries above.
+- **`components/` touched in this release window** (18 file(s), e.g. `card/card.css`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (4 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (1 file(s), e.g. `bulk-action-toolbar/bulk-action-toolbar.examples.html`) — carried by the entries above.
+- **`styles/` touched in this release window** (1 file(s), e.g. `styles/components.css`) — carried by the entries above.
+- **`traits/` touched in this release window** (2 file(s), e.g. `view-transition/view-transition.js`) — carried by the entries above.
+
+## [0.8.37] — 2026-08-14
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the lockstep version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.37 work shipped in ADR-0048 estate split: @adia-ai/{a2ui,gen-ui,mcp} first publish; six a2ui-* names ship as shims and retire. See `packages/mcp/CHANGELOG.md#0837--2026-08-14` for details.
+- **`components/` touched in this release window** (123 file(s), e.g. `accordion/accordion.examples.html`) — carried by the entries above.
+- **`core/` touched in this release window** (3 file(s), e.g. `core/element.test.js`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (1 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (20 file(s), e.g. `admin-keys-and-export/admin-keys-and-export.examples.html`) — carried by the entries above.
+- **`styles/` touched in this release window** (1 file(s), e.g. `type/scale.css`) — carried by the entries above.
+- **`traits/` touched in this release window** (57 file(s), e.g. `active-state/active-state.examples.html`) — carried by the entries above.
+
 ## [0.8.36] — 2026-08-13
 
 ### Maintenance

package/MIGRATION.md

@@ -52,10 +52,195 @@ Version cuts and migration scope:
 
 - **`0.8.11`** — PATCH lockstep cut (2026-07-23). Internal ranges stay at `^0.8.0`. **BREAKING: the size model.** Every component `size` enum is now exactly `sm | md | lg`; the removed tiers (`xs`, `xl`, icon's `2xl/3xl/4xl/fill`) are served by the new ancestor **`[scale]`** context — six hand-tabled tiers (`ui-sm · ui-md · ui-lg · content-sm · content-md · content-lg`): scale picks the table, `size` picks the row. `[verse]`/`[prose]` are deprecated aliases of `ui-sm`/`content-md` (removed at v1.0). Also new: `<adia-wordmark-ui>`. See [§ v0.8.11 section below](#migrating-to-adia-aiv0811-2026-07-23).
 
+- **`0.8.37`** — PATCH lockstep cut. **BREAKING: the a2ui / gen-ui estate split (ADR-0048).** Six published package names (`a2ui-runtime`, `a2ui-compose`, `a2ui-corpus`, `a2ui-retrieval`, `a2ui-validator`, `a2ui-mcp`) are replaced by four (`a2ui`, `gen-ui`, `gen-ui-mcp`, `a2ui-protocol-mcp`). **A patch-shaped version number does not make this non-breaking** — every old name is renamed. One-cycle re-export shims bridge the gap; the cut AFTER `0.8.37` retires them. See [§ 0.8.37 — the a2ui / gen-ui estate split](#0837--the-a2ui--gen-ui-estate-split-adr-0048).
+
 Live demos and per-component docs at [ui-kit.exe.xyz/site/](https://ui-kit.exe.xyz/site/). The `adia-ui-migration` skill (in `.agents/skills/`) automates most of the mechanical sweeps in this guide.
 
 ---
 
+## `0.8.37` — the a2ui / gen-ui estate split (ADR-0048)
+
+**Read this even though the version number is a patch.** The `0.8.37` lockstep
+cut renames six published packages. Nothing about the rename is patch-shaped
+except the number, which is an operator ruling (gh#1192, 2026-08-13) about
+release cadence, not a claim that your imports keep working forever.
+
+The split is by concept, ruled in `docs/adr/adr-0048-a2ui-gen-ui-estate-split.md`:
+
+- **`@adia-ai/a2ui` — the protocol.** How one system renders gen-UI canvases
+  in another system, safely: renderer, registry, streams, surface, wiring,
+  dockables, prop-apply, schema, plus protocol-side validation. **Zero
+  dependencies** — no LLM stack, no corpus. This is what an embedding host
+  installs.
+- **`@adia-ai/gen-ui` — the generation system.** compose + retrieval + corpus
+  + catalog-aware and LLM-judge validation, as one package.
+- **Two MCP servers, one npm package.** `@adia-ai/mcp` (gh#1240 — folds what
+  were originally two planned packages, `@adia-ai/gen-ui-mcp` and
+  `@adia-ai/a2ui-protocol-mcp`, before either ever published) ships one bin,
+  `adia-mcp`, dispatching two subcommands as separate processes:
+  `adia-mcp gen-ui` (30 tools — the generation surface, direct successor of
+  `@adia-ai/a2ui-mcp`) and `adia-mcp protocol` (4 tools — `validate_document`,
+  `get_registry_map`, `get_wiring_registry`, `protocol_status`; renamed off
+  their original same-named-as-`gen-ui`-surface forms by gh#1248 before this
+  server ever published). The name `@adia-ai/a2ui-mcp` is **burned, never
+  reused**: it means "the generation MCP" to every consumer that has it
+  pinned, so it is deprecated with a pointer rather than repurposed.
+
+### The one-cycle bridge — what happens if you do nothing
+
+At `0.8.37` every old name gets a final **shim publish**: a thin package whose
+exports re-export the new package's matching subpaths. Because npm's caret is
+minor-locked below 1.0, `0.8.37` satisfies the `^0.8.x` range you already
+carry — so **an existing consumer floats onto the shim on its next
+`npm install`, with no action and no broken import.** The `npm deprecate`
+pointer on each old name tells you where to move.
+
+That window is exactly one cycle. The follow-up PR deletes the shims from the
+repo and the release roster, so **the cut after `0.8.37` is the one that breaks
+an un-migrated consumer.** Migrate during the `0.8.37` line.
+
+Two things the shim structurally cannot bridge, so migrate these first:
+
+- **JSON-data subpaths of `@adia-ai/a2ui-corpus`** — the catalog,
+  `./manifest`, `./chunks`, `./chunks/*`, `./chunk-embeddings`. A JavaScript
+  forwarder cannot re-export a JSON module (`export *` drops `default`, and
+  Node requires `with { type: 'json' }`, which throws against a `.js` target).
+  These get pointer text only. The corpus package's one JS export,
+  `./chunk-library`, IS forwarded.
+- **TypeScript types**, except the two subpaths the old package itself
+  published as `.d.ts` (`a2ui-runtime`'s `./schema` and `./types`). A one-cycle
+  bridge ships JS.
+
+Also not minted, because they never worked on the published packages:
+extension-suffixed alias forms (`@adia-ai/a2ui-runtime/registry.js`,
+`@adia-ai/a2ui-compose/core/artifacts.js`). The published wildcard targets
+already end in `.js`, so those specifiers resolved to `…/artifacts.js.js` and
+failed at load. If you were writing them, they were already broken.
+
+### Subpath-export map (old → new)
+
+| Old import | New import |
+|---|---|
+| `@adia-ai/a2ui-runtime` | `@adia-ai/a2ui` |
+| `@adia-ai/a2ui-runtime/<sub>` (`registry`, `renderer`, `prop-apply`, `streams`, `surface`, `wiring`, `dockables`, `schema`, `types`) | `@adia-ai/a2ui/<sub>` (unchanged sub) |
+| `@adia-ai/a2ui-validator` / `./validator` | `@adia-ai/a2ui/validate` |
+| `@adia-ai/a2ui-validator/catalog` | `@adia-ai/gen-ui/validate/catalog` |
+| `@adia-ai/a2ui-validator/semantic` (+`/*`) | `@adia-ai/gen-ui/validate/semantic` (+`/*`) |
+| `@adia-ai/a2ui-compose` | `@adia-ai/gen-ui` (compose is the package's primary surface; root re-exports `generateUI`) |
+| `@adia-ai/a2ui-compose/<sub>` (`core`, `strategies/*`, `transpiler`, `evals`, `shared/*`; incl. deprecated `engine`/`engines/*` aliases) | `@adia-ai/gen-ui/compose/<sub>` (aliases NOT carried over — they were already deprecated one cycle) |
+| `@adia-ai/a2ui-retrieval` | `@adia-ai/gen-ui/retrieval` |
+| `@adia-ai/a2ui-retrieval/<sub>` (e.g. `domain-router`, `intent/*`, `embedding/*`, `feedback/*`, `authoring/*`) | `@adia-ai/gen-ui/retrieval/<sub>` (e.g. `@adia-ai/gen-ui/retrieval/domain-router`) |
+| `@adia-ai/a2ui-corpus` | **`@adia-ai/a2ui/catalog`** — this export WAS the catalog document, and the catalog moved protocol-side at ADR-0050 (gh#1243). `@adia-ai/gen-ui/corpus` no longer resolves as a root export |
+| `@adia-ai/a2ui-corpus/<sub>` (`chunks/*`, `chunk-library`, `chunk-embeddings`, `manifest`) | `@adia-ai/gen-ui/corpus/<sub>` (unchanged — corpus fuel stays in gen-ui) |
+| `@adia-ai/a2ui-mcp` (bin `adiaui-mcp`) | `@adia-ai/mcp` (bin `adia-mcp`, subcommand `gen-ui`) — retargeted gh#1240; the `@adia-ai/gen-ui-mcp` name this row originally named never published |
+| — (new) | `@adia-ai/mcp` (bin `adia-mcp`, subcommand `protocol`) — folded into the same package as the row above by gh#1240; the `@adia-ai/a2ui-protocol-mcp` name this row originally named never published |
+
+### Mechanical sweeps
+
+**First, hand-migrate the two deprecated compose aliases — the sweep below
+cannot do it and will silently break them.** `@adia-ai/a2ui-compose` published
+`./engine` and `./engines/*`, deprecated one cycle ago; they are **not** carried
+over to `@adia-ai/gen-ui`. A blind prefix rewrite would turn them into
+`@adia-ai/gen-ui/compose/engine{,s/…}`, which do not exist — and the post-sweep
+grep would not catch it, because by then they carry the new package name.
+
+```bash
+git grep -n '@adia-ai/a2ui-compose/engine'   # must be empty before you sweep
+```
+
+Any hit maps like this (the old alias and its successor resolve to the same
+file, so this is a rename, not a behaviour change):
+
+| Deprecated alias | Migrate to |
+|---|---|
+| `@adia-ai/a2ui-compose/engine` | `@adia-ai/gen-ui/compose/core` |
+| `@adia-ai/a2ui-compose/engines/zettel` | `@adia-ai/gen-ui/compose/strategies/zettel` |
+| `@adia-ai/a2ui-compose/engines/registry` | `@adia-ai/gen-ui/compose/strategies/registry` |
+| `@adia-ai/a2ui-compose/engines/cascade` | `@adia-ai/gen-ui/compose/strategies/cascade` |
+| `@adia-ai/a2ui-compose/engines/escalation` | `@adia-ai/gen-ui/compose/strategies/escalation` |
+
+Then run the sweeps in this order — the longest specifier first, so a shorter
+prefix doesn't eat a longer one:
+
+```bash
+# One helper, three deliberate choices:
+#
+# 1. A `while` loop, not `| xargs perl -i -pe …`: with no matches, GNU xargs
+#    runs perl with NO file arguments and it hangs reading stdin. The loop
+#    body simply never executes.
+# 2. The old/new strings go through the ENVIRONMENT, not the perl source —
+#    inlining them would let perl read `@adia-ai` on the replacement side as
+#    an array interpolation and silently substitute an empty string.
+# 3. NUL-delimited (`-lz` + `read -d ''`), so a path containing a space
+#    survives — this repo's own "MIGRATION GUIDE.md" is one, and
+#    `for f in $(git grep -l …)` word-splits it into two nonexistent paths.
+sweep() {
+  git grep -lz "$1" | while IFS= read -r -d '' f; do
+    OLD="$1" NEW="$2" perl -i -pe 'BEGIN{$o=$ENV{OLD};$n=$ENV{NEW}} s/\Q$o\E/$n/g' "$f"
+  done
+}
+
+# validator — longest specifier FIRST, so a shorter prefix doesn't eat it.
+# `./validator` was a real published subpath and maps to the SAME target as the
+# bare name; without its own line the generic rule below would produce
+# `@adia-ai/a2ui/validate/validator`, which a2ui does not export (no `./validate/*`
+# wildcard) → ERR_PACKAGE_PATH_NOT_EXPORTED.
+sweep '@adia-ai/a2ui-validator/validator' '@adia-ai/a2ui/validate'
+sweep '@adia-ai/a2ui-validator/catalog'   '@adia-ai/gen-ui/validate/catalog'
+sweep '@adia-ai/a2ui-validator/semantic'  '@adia-ai/gen-ui/validate/semantic'
+sweep '@adia-ai/a2ui-validator'           '@adia-ai/a2ui/validate'
+
+# generation system
+sweep '@adia-ai/a2ui-compose/'  '@adia-ai/gen-ui/compose/'
+sweep '@adia-ai/a2ui-compose'   '@adia-ai/gen-ui'
+sweep '@adia-ai/a2ui-retrieval' '@adia-ai/gen-ui/retrieval'
+sweep '@adia-ai/a2ui-corpus/'   '@adia-ai/gen-ui/corpus/'
+sweep '@adia-ai/a2ui-corpus'    '@adia-ai/a2ui/catalog'   # bare corpus import WAS the catalog (ADR-0050)
+
+# protocol
+sweep '@adia-ai/a2ui-runtime'   '@adia-ai/a2ui'
+```
+
+The helper takes paths from `git grep`, so it only ever touches tracked files —
+`node_modules/` and build output are never rewritten.
+
+Then fix your manifest by hand — a find-replace does not know the difference
+between a dependency and a peer:
+
+- **`dependencies` / `devDependencies`** on any renamed package → the new name
+  at the caret range for the cut (`^0.8.0`).
+- **`peerDependencies`** stay **exact-pinned** to the lockstep version. If you
+  peer-pinned `@adia-ai/a2ui-runtime`, the pin moves to `@adia-ai/a2ui` —
+  moving the import without the peer pin leaves you resolving two runtimes.
+- **MCP client config** (`.mcp.json`, Claude Desktop, Cursor): the generation
+  server's package and bin both change —
+  `npx -y @adia-ai/a2ui-mcp` → `npx -y @adia-ai/mcp gen-ui` (gh#1240 folded
+  the originally-planned `@adia-ai/gen-ui-mcp` name, and the separate protocol
+  MCP, into one package, `@adia-ai/mcp`, before either ever published — the
+  bin gained a subcommand accordingly). Tool names and their input/output
+  shapes are **unchanged**; only the package that serves them is renamed. The
+  30-tool surface is documented at `packages/gen-ui/mcp/TOOLS.md` (the `gen-ui`
+  section).
+
+### After the sweep, check
+
+- No `@adia-ai/a2ui-` specifier survives:
+  `git grep -nE '@adia-ai/a2ui-(runtime|compose|corpus|retrieval|validator|mcp)'`
+  should return nothing. (There is no exception to read past here —
+  `@adia-ai/a2ui-protocol-mcp` was the originally-planned protocol-server
+  name, but gh#1240 folded it into `@adia-ai/mcp`'s `protocol` subcommand
+  before it ever published, so it never became a real name to match.)
+- **The grep above cannot see a mis-rewritten subpath**, because those carry
+  the new package name. Check the two classes it misses directly:
+  `git grep -nE '@adia-ai/gen-ui/compose/engines?(/|$)'` and
+  `git grep -n '@adia-ai/a2ui/validate/'` — both should return nothing.
+  Any hit is a specifier that does not exist and will fail at import.
+- Your lockfile actually resolved the new names — a stale lockfile keeps
+  installing shims and hides the work until they retire.
+- `npm ls @adia-ai/a2ui` shows one copy, not two.
+
+---
+
 ## Upcoming — variant/color/tone convention cut
 
 **One theme: every color-ish attribute owns exactly one axis.** `variant`/`tone` on badge & tag
@@ -77,7 +262,9 @@ have exactly one fill style each.
 
   ```bash
   git grep -nE '<badge-ui[^>]*variant="accent"'
-  git grep -lE '<badge-ui[^>]*variant="accent"' | xargs perl -i -pe 's/(<badge-ui[^>]*variant=")accent(")/${1}primary${2}/g'
+  git grep -lz '<badge-ui[^>]*variant="accent"' | while IFS= read -r -d '' f; do
+    perl -i -pe 's/(<badge-ui[^>]*variant=")accent(")/${1}primary${2}/g' "$f"
+  done
   ```
 
 - **`<tag-ui variant="accent">` → `<tag-ui variant="primary">`** — identical rendering
@@ -85,7 +272,9 @@ have exactly one fill style each.
 
   ```bash
   git grep -nE '<tag-ui[^>]*variant="accent"'
-  git grep -lE '<tag-ui[^>]*variant="accent"' | xargs perl -i -pe 's/(<tag-ui[^>]*variant=")accent(")/${1}primary${2}/g'
+  git grep -lz '<tag-ui[^>]*variant="accent"' | while IFS= read -r -d '' f; do
+    perl -i -pe 's/(<tag-ui[^>]*variant=")accent(")/${1}primary${2}/g' "$f"
+  done
   ```
 
 - **`<badge-ui variant="muted">` / `<badge-ui variant="neutral">` → `<badge-ui tone="muted">`**
@@ -97,7 +286,9 @@ have exactly one fill style each.
 
   ```bash
   git grep -nE '<badge-ui[^>]*variant="(muted|neutral)"'
-  git grep -lE '<badge-ui[^>]*variant="(muted|neutral)"' | xargs perl -i -pe 's/(<badge-ui[^>]*)variant="(?:muted|neutral)"/${1}tone="muted"/g'
+  git grep -lz '<badge-ui[^>]*variant="(muted|neutral)"' | while IFS= read -r -d '' f; do
+    perl -i -pe 's/(<badge-ui[^>]*)variant="(?:muted|neutral)"/${1}tone="muted"/g' "$f"
+  done
   ```
 
 - **`<alert-ui variant="muted">` / `<alert-ui variant="neutral">` → drop the attribute** — both
@@ -113,8 +304,10 @@ have exactly one fill style each.
   ```bash
   EX=(-g '!*MIGRATION*' -g '!*CHANGELOG.md' -g '!**/dist/**' -g '!*.a2ui.json' -g '!*.examples.md')
   rg -nU '<alert-ui(\s[^>]*)?\svariant="(muted|neutral)"' "${EX[@]}"
-  rg -lU '<alert-ui(\s[^>]*)?\svariant="(muted|neutral)"' "${EX[@]}" \
-    | xargs perl -0777 -i -pe 's/(<alert-ui(?:\s[^>]*)?)\s+variant="(?:muted|neutral)"/${1}/gs'
+  rg -0 -lU '<alert-ui(\s[^>]*)?\svariant="(muted|neutral)"' "${EX[@]}" \
+    | while IFS= read -r -d '' f; do
+        perl -0777 -i -pe 's/(<alert-ui(?:\s[^>]*)?)\s+variant="(?:muted|neutral)"/${1}/gs' "$f"
+      done
   ```
 
 - **Programmatic setters (JS render paths — the sweep HTML greps miss):**
@@ -230,7 +423,9 @@ git grep -nE '"size": *"(xs|xl|2xl|3xl|4xl|fill)"'   # A2UI/JSON form
 
 **Sweep (mechanical, non-icon tags):**
 ```bash
-git grep -lE 'size="(xs|xl)"' | xargs perl -i -pe 's/size="xs"/size="sm"/g; s/size="xl"/size="lg"/g'
+git grep -lz 'size="(xs|xl)"' | while IFS= read -r -d '' f; do
+  perl -i -pe 's/size="xs"/size="sm"/g; s/size="xl"/size="lg"/g' "$f"
+done
 ```
 Icon named tiers are a table-driven remap (`xs→"12"`, `xl→"32"`, `2xl→"48"`, `3xl→"64"`, `4xl→"96"`, `fill→"100%"`) — sweep them BEFORE the generic pass, and never touch already-free-form values (`size="48"`).
 
@@ -268,7 +463,9 @@ git grep -nE -- '--a-accent'
 
 **Sweep (mechanical):**
 ```bash
-git grep -lE -- '--a-accent' | xargs perl -i -pe 's/--a-accent(?![a-z0-9])/--a-primary/g'
+git grep -lz -- '--a-accent' | while IFS= read -r -d '' f; do
+  perl -i -pe 's/--a-accent(?![a-z0-9])/--a-primary/g' "$f"
+done
 ```
 
 (The `(?![a-z0-9])` guard keeps suffixed forms like `--a-accent-strong` → `--a-primary-strong` correct while never touching unrelated names. Prefer consuming `--md-sys-color-primary*` directly in new code.)
@@ -295,7 +492,9 @@ git grep -n 'primitives-accent'
 
 **Sweep (mechanical):**
 ```bash
-git grep -l 'primitives-accent' | xargs perl -i -pe 's/primitives-accent/primitives-primary/g'
+git grep -lz 'primitives-accent' | while IFS= read -r -d '' f; do
+  perl -i -pe 's/primitives-accent/primitives-primary/g' "$f"
+done
 ```
 
 ### Behavioral: named `[theme]` presets no longer re-color (manual review)
@@ -315,7 +514,7 @@ git grep -c 'primitives-accent' || echo clean              # expect clean (item
 git grep -cE -- '--a-[a-z]+-[0-9]-(tint-|shade-)?scrim\b' || echo clean   # expect clean (item 2)
 ```
 
-Then the browser gate on the migrated screens (`adia-verify`): zero console errors,
+Then the browser gate on the migrated screens (`surface-qa`): zero console errors,
 non-zero bounding boxes, and read the screenshot — the scrim remap (item 2) and the
 `[theme]` behavioral change are visual; only the pixels prove overlay weights and
 brand color survived. Compare a before/after screenshot of one themed page if the
@@ -965,7 +1164,7 @@ Non-zero exit on regression. Used internally for the 6 in-repo consumers — pas
 If you maintain your own shell-style components in your fork or extension:
 - `<admin-shell>` host: 305 → **87 LOC** (-71%) at v0.4.0
 - The bespoke pattern moves resize / collapse / persistence / dialog behavior INTO each child. The host coordinates only.
-- See [`bespoke-shell-children` skill](../../.agents/skills/adia-author/SKILL.md) for the canonical decomposition recipe.
+- See [`bespoke-shell-children` skill](../../.agents/skills/primitive-authoring/SKILL.md) for the canonical decomposition recipe.
 
 ### Don't roll back
 
@@ -978,11 +1177,13 @@ Once on `0.4.0`, the legacy paths cannot be reactivated by config — they're ph
 `grid-ui` has only ever accepted `columns="N"` (see [`packages/web-components/components/grid/grid.js:12`](../../packages/web-components/components/grid/grid.js#L12)). Pages authored with `cols=` were silently rendering as the default 3-column grid — the attribute was ignored. Sweep:
 
 ```bash
-git grep -nlE '<grid-ui[^>]*\bcols=' \
-  | xargs perl -i -pe 's/(<grid-ui[^>]*?)\bcols=/$1columns=/g'
+git grep -nlz '<grid-ui[^>]*\bcols=' \
+  | while IFS= read -r -d '' f; do
+      perl -i -pe 's/(<grid-ui[^>]*?)\bcols=/$1columns=/g' "$f"
+    done
 ```
 
-Then re-run `npm run harvest:chunks` if any of the touched pages live under `site/pages/` and are tagged with `data-chunk` (extracts to `packages/a2ui/corpus/chunks/`).
+Then re-run `npm run harvest:chunks` if any of the touched pages live under `site/pages/` and are tagged with `data-chunk` (extracts to `packages/gen-ui/a2ui/corpus/chunks/`).
 
 ---
 
@@ -1355,46 +1556,48 @@ Not a break, but pairs with §1. `<button-ui>` now accepts `[color="default | ac
 
 ```bash
 # 1. button variant=danger → color=danger (sweep HTML)
-git grep -nlE 'button-ui[^>]*variant="danger"' \
-  | xargs perl -i -pe 's/(<button-ui[^>]*?)variant="danger"/$1color="danger"/g'
+git grep -nlz 'button-ui[^>]*variant="danger"' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<button-ui[^>]*?)variant="danger"/$1color="danger"/g' "$f"; done
 
 # 2. timeline-item-ui Booleans → status enum
-git grep -nlE '<timeline-item-ui[^>]*\bcompleted\b' \
-  | xargs perl -i -pe 's/(<timeline-item-ui[^>]*?)\bcompleted\b/$1status="completed"/g'
-git grep -nlE '<timeline-item-ui[^>]*\bactive\b' \
-  | xargs perl -i -pe 's/(<timeline-item-ui[^>]*?)\bactive\b/$1status="active"/g'
-git grep -nlE '<timeline-item-ui[^>]*\berror\b' \
-  | xargs perl -i -pe 's/(<timeline-item-ui[^>]*?)\berror\b/$1status="error"/g'
+git grep -nlz '<timeline-item-ui[^>]*\bcompleted\b' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<timeline-item-ui[^>]*?)\bcompleted\b/$1status="completed"/g' "$f"; done
+git grep -nlz '<timeline-item-ui[^>]*\bactive\b' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<timeline-item-ui[^>]*?)\bactive\b/$1status="active"/g' "$f"; done
+git grep -nlz '<timeline-item-ui[^>]*\berror\b' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<timeline-item-ui[^>]*?)\berror\b/$1status="error"/g' "$f"; done
 
 # 3. stepper-item-ui similarly
-git grep -nlE '<stepper-item-ui[^>]*\bcompleted\b' \
-  | xargs perl -i -pe 's/(<stepper-item-ui[^>]*?)\bcompleted\b/$1status="completed"/g'
+git grep -nlz '<stepper-item-ui[^>]*\bcompleted\b' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<stepper-item-ui[^>]*?)\bcompleted\b/$1status="completed"/g' "$f"; done
 
 # 4. pipeline-status-ui complete → status=completed (note spelling)
-git grep -nlE '<pipeline-status-ui[^>]*\bcomplete\b' \
-  | xargs perl -i -pe 's/(<pipeline-status-ui[^>]*?)\bcomplete\b/$1status="completed"/g'
-
-# 5. event listeners
-git grep -nE "addEventListener.*'chat-submit'" \
-  | xargs perl -i -pe "s/'chat-submit'/'submit'/g"
-git grep -nE "addEventListener.*'legend-toggle'" \
-  | xargs perl -i -pe "s/'legend-toggle'/'toggle'/g"
-git grep -nE "addEventListener.*'slide-change'" \
-  | xargs perl -i -pe "s/'slide-change'/'change'/g"
+git grep -nlz '<pipeline-status-ui[^>]*\bcomplete\b' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<pipeline-status-ui[^>]*?)\bcomplete\b/$1status="completed"/g' "$f"; done
+
+# 5. event listeners — note -l (files-with-matches), not -n: the old form piped
+# `grep -n` (file:line:text) straight into `perl -i`, handing perl a bogus
+# "filename" that never exists.
+git grep -lz "addEventListener.*'chat-submit'" \
+  | while IFS= read -r -d '' f; do perl -i -pe "s/'chat-submit'/'submit'/g" "$f"; done
+git grep -lz "addEventListener.*'legend-toggle'" \
+  | while IFS= read -r -d '' f; do perl -i -pe "s/'legend-toggle'/'toggle'/g" "$f"; done
+git grep -lz "addEventListener.*'slide-change'" \
+  | while IFS= read -r -d '' f; do perl -i -pe "s/'slide-change'/'change'/g" "$f"; done
 
 # 6. error → danger on toast/alert/tag (one component at a time so other variant=error don't collide)
-git grep -nlE '<toast-ui[^>]*variant="error"' \
-  | xargs perl -i -pe 's/(<toast-ui[^>]*?)variant="error"/$1variant="danger"/g'
-git grep -nlE '<alert-ui[^>]*variant="error"' \
-  | xargs perl -i -pe 's/(<alert-ui[^>]*?)variant="error"/$1variant="danger"/g'
-git grep -nlE '<tag-ui[^>]*variant="error"' \
-  | xargs perl -i -pe 's/(<tag-ui[^>]*?)variant="error"/$1variant="danger"/g'
+git grep -nlz '<toast-ui[^>]*variant="error"' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<toast-ui[^>]*?)variant="error"/$1variant="danger"/g' "$f"; done
+git grep -nlz '<alert-ui[^>]*variant="error"' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<alert-ui[^>]*?)variant="error"/$1variant="danger"/g' "$f"; done
+git grep -nlz '<tag-ui[^>]*variant="error"' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<tag-ui[^>]*?)variant="error"/$1variant="danger"/g' "$f"; done
 
 # 7. chat-input busy → loading
-git grep -nlE '<chat-input-ui[^>]*\bbusy\b' \
-  | xargs perl -i -pe 's/(<chat-input-ui[^>]*?)\bbusy\b/$1loading/g'
-git grep -nlE 'chatInput\.busy' \
-  | xargs perl -i -pe 's/chatInput\.busy/chatInput.loading/g'
+git grep -nlz '<chat-input-ui[^>]*\bbusy\b' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<chat-input-ui[^>]*?)\bbusy\b/$1loading/g' "$f"; done
+git grep -nlz 'chatInput\.busy' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/chatInput\.busy/chatInput.loading/g' "$f"; done
 
 # 8. agent-trace open → no attr (default visible) OR collapsed
 #    Manual review: default-visible is the new default; consumers that wrote
@@ -1405,8 +1608,8 @@ git grep -nE '<agent-trace-ui'
 # 9. avatar-ui name= → text= (deprecated alias, scheduled for removal)
 #    `name=` still works in 0.0.20+ but fires a one-shot console warning
 #    per page. Sweep before the next major to avoid the upcoming break.
-git grep -nlE '<avatar-ui[^>]*\bname=' \
-  | xargs perl -i -pe 's/(<avatar-ui[^>]*?\s)name=/\1text=/g'
+git grep -nlz '<avatar-ui[^>]*\bname=' \
+  | while IFS= read -r -d '' f; do perl -i -pe 's/(<avatar-ui[^>]*?\s)name=/\1text=/g' "$f"; done
 ```
 
 The `adia-ui-migration` skill in `.claude/skills/adia-ui-migration/` automates these sweeps and runs the verification gate after.

package/README.md

@@ -3,7 +3,7 @@
 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.
 
-> 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`](../a2ui/compose); the pattern corpus in [`@adia-ai/a2ui-corpus`](../a2ui/corpus); the MCP server in [`@adia-ai/a2ui-mcp`](../a2ui/mcp).
+> 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).
 >
 > **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.
 >
@@ -125,7 +125,7 @@ web-components/
 │                           All actual A2UI runtime code (renderer,
 │                           registry, streams, surface manifest,
 │                           wiring, dockables, controllers) lives in
-│                           `@adia-ai/a2ui-runtime` at packages/a2ui/runtime/.
+│                           `@adia-ai/a2ui` at packages/gen-ui/a2ui/.
 │
 └── styles/         — Global tokens and CSS layering
     ├── tokens.css              all --a-* design tokens
@@ -329,7 +329,7 @@ attribute table + live demos:
 npm run build:components    # regenerate all .a2ui.json from YAML
 ```
 
-The build also writes `packages/a2ui/corpus/catalog-a2ui_0_9.json` and
+The build also writes `packages/gen-ui/engine/corpus/catalog-a2ui_0_9.json` and
 `catalog-a2ui_0_9_rules.txt` — the flat-file catalog the MCP server and
 generation engine consume.
 

package/bin/doc.mjs

@@ -45,6 +45,32 @@ const DEMO_BASE = 'https://ui-kit.exe.xyz/site/components';
  * Defensive: any parse error returns a partial object plus an `_errors`
  * array — the caller decides how to surface failures.
  */
+/**
+ * Strips a trailing YAML comment from a single raw line. A `#` only
+ * starts a comment when it's at column 0 or preceded by whitespace (the
+ * YAML plain-scalar rule) — a bare mid-word `#` (e.g. `gh#1253` inside a
+ * folded description block) is content, not a comment marker. Quote
+ * state is tracked (paired ' / ") so a `#` inside an actual quoted
+ * string is never treated as a comment start either.
+ *
+ * Fixes a truncation bug (CodeRabbit, PR #1284): the previous regex
+ * (`/^([^#"']*)(#.*)?$/`) cut ANY line at its first bare `#` regardless
+ * of context, silently truncating descriptions containing `gh#NNNN`.
+ */
+function stripYamlComment(line) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === '#' && !inSingle && !inDouble && (i === 0 || /\s/.test(line[i - 1]))) {
+      return line.slice(0, i).replace(/\s+$/, '');
+    }
+  }
+  return line.replace(/\s+$/, '');
+}
+
 function parseYaml(source) {
   const out = {
     name: '',
@@ -59,11 +85,7 @@ function parseYaml(source) {
 
   // Strip comments + trailing whitespace, keep blank lines for block detection
   const rawLines = source.split(/\r?\n/);
-  const lines = rawLines.map((l) => {
-    // strip line comments unless inside a quoted string (rough heuristic)
-    const m = l.match(/^([^#"']*)(#.*)?$/);
-    return m ? m[1].replace(/\s+$/, '') : l;
-  });
+  const lines = rawLines.map(stripYamlComment);
 
   /** Find the line range of a top-level key block (indent === 0). */
   function blockRange(key) {

package/components/card/card.css

@@ -264,7 +264,7 @@
   /* Heading — row 1.
      Matches native h1-h6 AND the text-ui variants the A2UI transpiler emits
      for them (display|title|heading|subsection — see HTML_TAG_MAP in
-     packages/a2ui/compose/transpiler/transpiler-maps.js).
+     packages/gen-ui/a2ui/compose/transpiler/transpiler-maps.js).
      The text-ui variants are matched only when UNSLOTTED so an explicit
      `slot="heading"` / `slot="description"` / `slot="action"` always wins. */
   & > header > :is([slot="heading"], h1, h2, h3, h4, h5, h6),