@adia-ai/adia-ui-forge 0.8.23 → 0.8.25

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.23",
+  "version": "0.8.25",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.25] — 2026-07-31
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 11-package version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.25 work shipped in theme-panel scoped-target [parametric] density/radius fix (gh#570) + System scheme option; anchor-bar-ui; stat-ui band chart layout; chart-ui dots/series-emphasis. See `packages/web-components/CHANGELOG.md#0825--2026-07-31` for details.
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`skills/` touched in this release window** (1 file(s), e.g. `references/common-gotchas.md`) — carried by the entries above.
+
+## [0.8.24] — 2026-07-30
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 11-package version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.24 work shipped in requiredIcons drift cleared across 16 components + checker comment handling (gh#550), worktree bootstrap workspace-link hardening + retrieval corpus-pin fix (gh#554), list-item two-line icon centering (gh#558), card footer bottom-pinning (gh#559). See `packages/web-components/CHANGELOG.md#0824--2026-07-30` for details.
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+
 ## [0.8.23] — 2026-07-30
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.23",
+  "version": "0.8.25",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/skills/adia-author/references/common-gotchas.md

@@ -1,12 +1,12 @@
 # Common gotchas — authoring traps
 
-Six concrete failure modes: five from a billing-overview rebuild + multi-demo grandfather-elimination cycle (CSS/composition-layering traps, §§1–5, composite authoring specifically), plus one from the site-a2ui migration's router-race root cause (async-lifecycle sequencing, §6, any primitive or module with a multi-await lifecycle method). Each is the kind of bug that:
+Seven concrete failure modes: five from a billing-overview rebuild + multi-demo grandfather-elimination cycle (CSS/composition-layering traps, §§1–5, composite authoring specifically), one from the site-a2ui migration's router-race root cause (async-lifecycle sequencing, §6, any primitive or module with a multi-await lifecycle method), plus one from minting `anchor-bar-ui` (generated-artifact regeneration ordering, §7, any change that mints/renames a component and touches a demo using it in the same pass). Each is the kind of bug that:
 
 - Renders visually broken without console errors
 - Passes existing audits silently
 - Is fixed in one place but recurs in others until pattern-corrected
 
-Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async lifecycle method (fetch, dynamic `import()`, any multi-`await` sequence) to any primitive or module: read §6. Each entry includes the pattern, the detector (if any), and the fix.
+Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async lifecycle method (fetch, dynamic `import()`, any multi-`await` sequence) to any primitive or module: read §6. Anyone minting or renaming a component whose PR also regenerates a demo using it: read §7. Each entry includes the pattern, the detector (if any), and the fix.
 
 ## Contents
 
@@ -16,6 +16,7 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 4. [minmax(min, 1fr) inside repeat() fighting container queries](#4-minmaxmin-1fr-inside-repeat-fighting-container-queries)
 5. [Nested `<!-- ... -->` inside design-plan canonical-sketch fenced blocks](#5-nested----inside-design-plan-canonical-sketch-fenced-blocks)
 6. [Async load/render function completing out of order](#6-async-loadrender-function-completing-out-of-order--a-guard-at-the-checkpoint-isnt-enough)
+7. [Minting a wrapper-shaped component before its registry.js entry lands](#7-minting-a-wrapper-shaped-component-before-its-registryjs-entry-lands--site-a2ui-silently-deletes-the-node-not-just-mis-types-it)
 
 ---
 
@@ -122,8 +123,22 @@ async #loadContent(route) {
 
 ---
 
+## 7. Minting a wrapper-shaped component before its registry.js entry lands — site-a2ui silently deletes the node, not just mis-types it
+
+**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/a2ui/runtime/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Regenerate a site-a2ui row for a demo using a component minted in the SAME change, before its `registry.js` line lands, and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh`/`verify:site-a2ui` both report clean.
+
+**Example**: minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): `site-a2ui/pages/site__patterns__bulk-action-toolbar.a2ui.json` contains zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere — not retyped-and-visible, genuinely absent — while its single child (the toolbar content) survived, reparented one level up. `verify:site-a2ui` reported 321/321 clean.
+
+**Detector**: none generic — `verify:site-a2ui`'s freshness check can't catch this (the row IS fresh relative to its source, it transpiled correctly against a registry that was itself incomplete). The only catch is rendering the actual route in a browser and confirming the new tag's node count is nonzero, or re-running `node scripts/build/site-a2ui.mjs --page <route>` (or `--stale`) after `registry.js` is updated and diffing the row for the new component name. A non-wrapper-shaped new component (multiple children, or attributes that happen to map to real props) is lower-risk here — it survives as a visible-but-wrong Column, the gh#535 class, which at least has a visual tell.
+
+**Fix**: the `registry.js` entry is what gates resolution — land it (not just run `components.mjs`, which is necessary for prop fidelity but not sufficient to avoid the retype) before regenerating any site-a2ui row that uses the new tag. When gating a dispatched agent's PR that did this out of order, re-run `node scripts/build/site-a2ui.mjs --page <route>` on the merged tree and browser-probe the tag actually appears — never trust `verify:site-a2ui`'s green alone for a route touching a component minted in the same change.
+
+**Generalizes to**: any hand-maintained resolution map (not build-generated) that a later regeneration step reads through — regenerating before the map is updated produces an internally-consistent-but-wrong artifact that passes a same-source freshness check; if the misresolved shape also happens to trip a downstream simplification/collapse rule, the failure escalates from "renders wrong" to "renders nothing," with no visual tell at all.
+
+---
+
 ## Meta-pattern across gotchas 1–5
 
 **Composites and primitives have layered contracts. The parent's CSS shouldn't reach into the child's layout territory. The child's CSS shouldn't fight its parent's container queries. The audit should detect the rendering hazard, not just the parsing structure.**
 
-The structural defense for #1 (composition-grammar bypass) is `npm run audit:card-structure[:strict]` / `npm run audit:avatar-structure` / `npm run audit:alert-structure` (HTML + JS `createElement` scan) plus `npm run audit:sketch-grammar` at Phase 3. The component-literacy read is a hint, not a gate — the mechanical defenses above are the proximate fix. See [composite-demo-protocol.md](composite-demo-protocol.md) Phase 2. Gotchas #2–4 are caught only by visual review until corresponding audits are added. #6 is a distinct axis (async-lifecycle correctness, not CSS layering) — see its own Detector/Fix above.
+The structural defense for #1 (composition-grammar bypass) is `npm run audit:card-structure[:strict]` / `npm run audit:avatar-structure` / `npm run audit:alert-structure` (HTML + JS `createElement` scan) plus `npm run audit:sketch-grammar` at Phase 3. The component-literacy read is a hint, not a gate — the mechanical defenses above are the proximate fix. See [composite-demo-protocol.md](composite-demo-protocol.md) Phase 2. Gotchas #2–4 are caught only by visual review until corresponding audits are added. #6 is a distinct axis (async-lifecycle correctness, not CSS layering) — see its own Detector/Fix above. #7 is a third axis (a hand-maintained resolution map read by a downstream regeneration step, not CSS or async ordering) — its own Detector/Fix above; no audit catches it, only a browser probe of the specific route touched.