@adia-ai/a2ui-compose 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -12,6 +12,203 @@ generator graph.
 
 _No pending changes._
 
+## [0.5.4] - 2026-05-14
+
+### Fixed — §163 transpiler prop-fidelity; catalog-driven extractor closes the harvester drop class (v0.5.4)
+
+`packages/a2ui/compose/transpiler/transpiler-maps.js` rewritten to derive
+the extractable-prop set from the v0.9 catalog at module init, replacing
+the pre-§163 hand-maintained per-type allowlists that omitted `label`,
+`icon`, literal `variant=`, and similar first-class props.
+
+**Bug class diagnosed 2026-05-14** against composition `auth-signin-card-password`
+rendering blank rectangles in the gen-ui canvas. Verified pre-§163 vs post-§163
+against `apps/user-flow/app/auth/sign-in/password/password.contents.html`:
+
+  Password Input  pre={} post={label,type,autocomplete,name,placeholder,required}
+  Remember check  pre={name} post={name,label}
+  Sign in button  pre={type} post={type,text,variant}
+  Divider         pre={} post={label}
+  Magic-link btn  pre={} post={icon,text,variant}
+  6-digit btn     pre={} post={icon,text,variant}
+
+**Implementation**: `CATALOG_PROPS` Map built at module init from
+`@adia-ai/a2ui-corpus/catalog-a2ui_0_9.json`; `TYPE_ALIAS` map with
+4 resolution passes (catalog-self-map + direct registry-match +
+shared-tag-match + kebab-to-PascalCase fallback) — closes the
+registry-vs-catalog name drift (registry has `CheckBox → check-ui`;
+catalog uses `Check`). Generic catalog-driven pass runs FIRST in
+`extractProps()`; legacy per-type blocks defer with `if (props.X === undefined)`
+guards so catalog values win on conflict.
+
+**Side-effect fixes**: pre-existing legacy quirks (Slider `'0'` → `'0'`
+returning string instead of numeric `0`, Button `disabled="false"` → `true`)
+incidentally fixed by the deferred-legacy pattern.
+
+NEW `packages/a2ui/compose/transpiler/extract-props.test.js` (+228 LOC,
+19 tests) pinning the regression class.
+
+Cycle followup: §164 re-harvested all 230 chunks with the §163-fixed
+transpiler (corpus package; +2920 LOC restored prop fidelity). §166a
+added audit-script-family slot 12 (`check-extract-props-coverage.mjs`)
+that re-verifies the catalog-vs-extractor invariant at every commit.
+
+### Fixed — §168 canvas-iteration merge always-on; close the 50-threshold mismatch (v0.5.4)
+
+`packages/a2ui/compose/strategies/monolithic/generate-pro.js:374` —
+removed the `priorComponents.length >= 50` gate. `mergeCanvasDiff()`
+now runs on every iteration turn regardless of canvas size.
+
+Closes the chart-workflow regression diagnosed 2026-05-14:
+32-component canvas + "add a chart" intent → 202-component response
+wholesale-replaced the user's prior work (`exec_mp4zbj47_1`,
+`comps= 202 score= 105`). Pre-§168 the 0–49 band had no merge gate
+even though the prompt asked the LLM to return COMPLETE; LLM canvas
+explosions wholesale-replaced. Now: `mergeCanvasDiff` runs always,
+the hallucination-detection guards (matchRatio < 0.2 reject + < 0.6
+accept-with-warning) discriminate by match ratio (more principled than
+canvas-size heuristics), and small-canvas iterations correctly preserve
+prior work when LLM speculatively expands.
+
+`mergeCanvasDiff` is a strict superset of "wholesale-replace"
+behaviorally: COMPLETE arrays merge to identical shape; DIFF arrays
+process unchanged; hallucinated rewrites get rejected with
+"Hallucinated replacement rejected" + canvas preservation.
+
+NEW `merge-canvas-diff.test.js` (+251 LOC, 12 tests) pinning behavior
+across all three bands (strict-superset-of-replace, hallucination
+guards, DIFF format, layout-type guards, the §168 chart-workflow
+regression fixture).
+
+### Fixed — §169 iteration-prompt structural priming; Card/Stat/Chart anatomy carry-over (v0.5.4)
+
+`packages/a2ui/compose/strategies/monolithic/_shared.js`
+`buildCanvasDiffPrompt()` — added NEW `ITERATION_STRUCTURAL_RULES`
+block injected into both the full-canvas + compact-summary branches.
+
+Pre-§169 the iteration prompts said "Preserve slot attributes and
+Card anatomy rules" without defining what those rules ARE. The
+fresh-generation prompt at `buildSystemPrompt()` defines them
+explicitly (Card > Header > [slot=heading...], Card > Section >
+Column > [content], etc.) but iteration mode relied on multi-turn
+context retention, which is unreliable.
+
+Empirically the corpus enforces Card > Section > Column > Chart
+(233 Section→Column + 95 Card→Section across 230 chunks). The
+2026-05-14 user-reported "where chart data should live in the tree"
+ticket was the LLM emitting Chart at the wrong depth during
+iteration.
+
+Token cost: ~150 tokens added to a 500-1500-token iteration prompt;
+well within 32k max_tokens budget.
+
+### Fixed — §167 surface yaml-declared deprecation to LLM via prompt builder (v0.5.4)
+
+`packages/a2ui/compose/strategies/monolithic/_shared.js:274` (+ legacy
+fallback at `:312`) — when building the per-component prop string,
+append `(deprecated, do not use)` to any prop whose description
+matches `/deprecated/i`.
+
+Closes the `<avatar-ui name="...">` false-positive class observed
+2026-05-14 console:
+
+  ```
+  class.js:60  [AdiaUI] <avatar-ui name="…"> is deprecated — use text="…" instead.
+  ```
+
+Root cause: `avatar.yaml` + sidecar + catalog all declare
+`Avatar.name` as a prop with description `"Deprecated alias for
+text..."`. The prompt builder captured description into
+`out.description` (line ~56) but never read it when assembling the
+`props:` line. LLM saw both `name` and `text` as equally-valid prop
+names and naturally picked `name` for "team member names" intents.
+
+Post-§167 prompt:
+  ```
+  - Avatar: ...  props: icon:String, name:String (deprecated, do not use), ...
+  ```
+
+### Fixed — §172 ChatInput catalog entry + scanner sibling-yaml fix + intent-keyword family inclusion (v0.5.4)
+
+Closes ticket `20260514045025-chatinput-training-data-unclea` —
+user reported the generator created a redundant Button(primary)
+sibling next to ChatInput, duplicating the built-in send button
+that `<chat-input-ui>` already stamps.
+
+**Three architectural layers fixed:**
+
+1. **Build scanner sibling-yaml discovery** —
+   `scripts/build/components.mjs` (+15 LOC). Pre-§172 the scanner
+   only looked for `<name>/<name>.yaml`; sibling yamls in the same
+   dir were invisible. `<chat-input-ui>` (sibling of chat-thread)
+   and `<feed-item-ui>` (sibling of feed) were orphans —
+   registered at runtime but invisible to the catalog. Post-§172
+   sibling discovery is automatic.
+
+2. **Retrieval catalog loader sibling-sidecar discovery** —
+   `packages/a2ui/retrieval/component-catalog.js:_loadNode()`
+   (+24 LOC). Same blind spot; same fix. Browser path already
+   recursive via `import.meta.glob('**/*.a2ui.json')`; Node path
+   now matches.
+
+3. **Intent-keyword family inclusion in prompt builder** —
+   `packages/a2ui/compose/strategies/monolithic/_shared.js`
+   (+26 LOC). Pre-§172 the prompt's always-include list had generic
+   primitives only; chat/table/form/chart/nav components only
+   entered via retrieval-pattern match. Post-§172 the chat family
+   (`ChatInput, ChatThread, ChatComposer, ChatShell, ChatHeader,
+   ChatSidebar`) is force-included when the intent mentions
+   `chat/message/conversation/composer/thread`. Same for the other
+   4 families.
+
+Together: ChatInput's full description, 3 a2ui rules, and 3
+anti-patterns (the "DO NOT add a separate Button sibling for send"
+guidance) now appear in every chat-intent prompt's CORPUS CONTEXT
+block.
+
+**Sixth distinct application of the SoT-coherence pattern** in
+v0.5.4 (§163 + §167 + §168 + §169 + §170 + §172).
+
+Commit `514e72697`.
+
+### Maintenance — audit-script companions §173 + §175 ship in v0.5.4 (no source change to compose)
+
+Repo-level audit scripts targeting compose drift classes:
+
+- **§173 `check-iteration-prompt-coherence.mjs`** (slot 14) — guards against
+  regressions in `monolithic/_shared.js` deprecation-marker logic (§167) +
+  iteration-prompt structural rules block (§169).
+- **§175 `check-registry-catalog-coherence.mjs`** (slot 16) — guards against
+  registry/catalog drift like §172 ChatInput orphan-component class.
+
+No compose source change in §173/§175 — both detect future drift in compose's
+catalog-vs-prompt + registry-vs-catalog invariants.
+
+### Changed — `version`: `0.5.3` → `0.5.4`.
+
+## [0.5.3] - 2026-05-14
+
+### Fixed — Deterministic chunk-loading order in zettel composition library (§160, v0.5.3)
+
+`strategies/zettel/composition-library.js`: `walk()` now sorts `fs.readdirSync` output via `localeCompare` before recursing. Pre-§160 the directory walker relied on filesystem-defined entry order, which varies across processes on APFS/ext4. When two chunks tied on retrieval score for a given intent, the first-loaded won the tie-break — so the same intent could match chunk A in one process and chunk B in the next.
+
+Surfaced as ~40% flake rate on the `admin dashboard with kpi cards` retrieval probe post-§143 (the 8 new UI-primitive chunks compete with the original `dashboard-kpi-grid` template). Sorted walk pins load order; remaining flakiness is now constrained to a corpus-quality bug (Stat chunks strip `label`/`value`/`change` attrs in the `template` field) tracked as v0.5.4 F-S1a.
+
+No behavior change for callers that don't hit a tie-break — most intents have a clear retrieval winner.
+
+### Deprecated — `_debug.attempts` and `_debug.warnings` on free-form-composed results (§146, v0.5.3)
+
+Finalizes the v0.6.0 deprecation schedule for the last two `_debug.*` fields that consumers might still read on `generateFreeFormAdapter`'s result. Both fields are dialog-recorder-gated (silently `undefined` when not recording) — the same access pattern §109 (v0.5.1) + §107a (v0.5.2) removed for `usedIngredients` / `rationale` / `plan`.
+
+**v0.6.0 migration path** (folded into the inline `@deprecated` JSDoc on `strategies/registry.js`):
+
+- `result._debug?.attempts` → `result.attempts: number` (LLM round-trips: 1 normally; 2-3 with hallucination retry or paraphrase-retry)
+- `result._debug?.warnings` → `result.warnings: string[]` (non-fatal transpile findings: unknown substitution keys, layout-value fall-throughs, chunk-resolution warns)
+
+**Scheduled removal**: v0.6.0 drops the `_debug` block entirely from the free-form-composed result shape. The dialog-recorder will read first-class fields directly. v0.5.3 is the **migration window** — any external consumers reading `_debug.attempts` / `_debug.warnings` should switch to the first-class fields before v0.6.0 ships.
+
+**Internal verification**: zero live in-repo consumers (`grep -rn '_debug\?\.attempts\|_debug\.attempts\|_debug\?\.warnings\|_debug\.warnings' apps/ playgrounds/ catalog/ packages/` returns only the deprecation comment itself).
+
 ## [0.5.2] - 2026-05-13
 
 ### Changed — `plan` graduates from `_debug.*` to first-class on free-form-composed result (§107a infra, v0.5.2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "AdiaUI A2UI compose engine — framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {

package/strategies/monolithic/_shared.js

@@ -248,6 +248,32 @@ KEY RULES:
       'Text', 'Button', 'Input', 'Badge', 'Icon', 'Avatar', 'Image', 'Divider']) {
       relevantTypes.add(t);
     }
+    // §172 (v0.5.4): intent-keyword inclusion — add component families when
+    // the intent mentions their domain. Pre-§172 the LLM had to learn chat
+    // components via multi-turn context (unreliable) or pattern-match (which
+    // depends on retrieval). The 2026-05-14 redundant-send-button regression
+    // happened because the LLM saw `ChatInput` in the runtime registry but
+    // had no schema describing what `<chat-input-ui>` stamps. Now the chat
+    // family is force-included whenever the intent mentions chat/message/
+    // conversation.
+    const intentLower = (intent || '').toLowerCase();
+    const FAMILIES = {
+      chat: { keywords: ['chat', 'message', 'conversation', 'composer', 'thread'],
+              types: ['ChatInput', 'ChatThread', 'ChatComposer', 'ChatShell', 'ChatHeader', 'ChatSidebar'] },
+      table: { keywords: ['table', 'grid of rows', 'tabular', 'spreadsheet'],
+               types: ['Table', 'TableToolbar'] },
+      form: { keywords: ['form', 'sign in', 'sign up', 'register', 'login', 'signup'],
+              types: ['Field', 'Input', 'CheckBox', 'Switch', 'Select', 'TextArea', 'Slider'] },
+      chart: { keywords: ['chart', 'graph', 'metric', 'kpi', 'dashboard', 'trend'],
+               types: ['Chart', 'ChartLegend', 'Stat'] },
+      navigation: { keywords: ['nav', 'sidebar', 'breadcrumb', 'tabs', 'menu'],
+                    types: ['Tabs', 'Tab', 'Menu', 'Breadcrumbs', 'NavGroup', 'NavItem'] },
+    };
+    for (const family of Object.values(FAMILIES)) {
+      if (family.keywords.some(kw => intentLower.includes(kw))) {
+        for (const t of family.types) relevantTypes.add(t);
+      }
+    }
     // Add types from matched patterns
     for (const p of patterns) {
       for (const c of (p.components || [])) relevantTypes.add(c);
@@ -276,6 +302,12 @@ KEY RULES:
           if (v.enum) desc += `=(${v.enum.join('|')})`;
           else if (v.type) desc += `:${v.type}`;
           if (v.default !== undefined) desc += `[${v.default}]`;
+          // §167 (v0.5.4): surface yaml-declared deprecation to the LLM. Pre-§167
+          // the description field was captured into out.description (line ~56)
+          // but never read here, so deprecated props (Avatar.name, Field.persist
+          // alias, etc.) looked indistinguishable from canonical props. LLM
+          // would pick e.g. <avatar-ui name="..."> instead of text="...".
+          if (v.description && /deprecated/i.test(v.description)) desc += ' (deprecated, do not use)';
           return desc;
         }).join(', ') : '';
         const events = a2uiData.events?.length ? ` events: ${a2uiData.events.join(', ')}` : '';
@@ -313,6 +345,12 @@ KEY RULES:
           if (v.enum) desc += `=(${v.enum.join('|')})`;
           else if (v.type) desc += `:${v.type}`;
           if (v.default !== undefined) desc += `[${v.default}]`;
+          // §167 (v0.5.4): surface yaml-declared deprecation to the LLM. Pre-§167
+          // the description field was captured into out.description (line ~56)
+          // but never read here, so deprecated props (Avatar.name, Field.persist
+          // alias, etc.) looked indistinguishable from canonical props. LLM
+          // would pick e.g. <avatar-ui name="..."> instead of text="...".
+          if (v.description && /deprecated/i.test(v.description)) desc += ' (deprecated, do not use)';
           return desc;
         }).join(', ') : '';
         const events = comp.events?.length ? ` events: ${comp.events.join(', ')}` : '';
@@ -929,6 +967,43 @@ export function mergeCanvasDiff(priorComponents, diffComponents) {
  * @param {string|null} [opts.originalIntent] — original design brief for drift anchoring
  * @returns {string} prompt text for the canvas diff
  */
+/**
+ * §169 (v0.5.4): structural rules block injected into iteration prompts.
+ *
+ * Pre-§169 the iteration prompts said "Preserve slot attributes and Card
+ * anatomy rules" without defining what those rules ARE. The fresh-generation
+ * prompt at buildSystemPrompt() defines them explicitly (Card > Header >
+ * [Text slot=heading...], Card > Section > Column > [content], etc.) but
+ * iteration mode relied on multi-turn context retention, which is unreliable.
+ *
+ * The 2026-05-14 chart-workflow ticket symptom: 32-component canvas + "add
+ * a chart" intent → LLM emitted Chart at the wrong nesting depth, prompting
+ * the user-friction complaint about "where chart data should live in the
+ * tree." Empirically the corpus enforces Card > Section > Column > Chart
+ * (233 Section→Column + 95 Card→Section across 230 chunks).
+ *
+ * This block echoes the fresh-generation contract's most-important
+ * structural guidance into iteration mode. Keeps token cost negligible
+ * (~150 tokens added to a 500-1500-token iteration prompt; well within
+ * 32k max_tokens budget).
+ */
+const ITERATION_STRUCTURAL_RULES = `
+STRUCTURAL RULES (carry-over from fresh-generation contract — apply when ADDING new components):
+- Card content: Card > Header > [Text slot="heading", Text slot="description", Button slot="action"]
+                Card > Section > Column > [content]  (Section ALWAYS wraps children in a Column)
+                Card > Footer > [Button, Button]  (action buttons go in Footer, not Section)
+- Stats:        use Stat component directly with {label, value, change, trend}; do NOT manually
+                build stat cards from Card+Header+Section+Text — emit a Stat node.
+- Charts:       place inside Section > Column. Chart props: type ("line"|"bar"|"area"), x (string),
+                y (string or array). Charts go in Section, not directly inside Card.
+- Forms:        wrap fields in Column with gap="3". Submit button in separate Row or Footer.
+- Tabs:         Tab children = ONLY Tab components. Content panels are SIBLINGS of Tabs, not children.
+                Column > [Tabs, Card, Card] (panels show/hide based on active tab; NOT Tab > Card).
+- Header slots: every Header child MUST have a slot= attribute (heading|description|action|icon).
+- Layout types: Grid/Row/Column types MUST NOT change during iteration unless the user explicitly
+                requests a layout change. To restructure, DELETE the old container + ADD a new one.
+`;
+
 export function buildCanvasDiffPrompt(intent, priorComponents, { originalIntent = null } = {}) {
   // Design intent anchor — prevents drift from the original brief
   const intentAnchor = originalIntent && originalIntent !== intent
@@ -946,10 +1021,10 @@ export function buildCanvasDiffPrompt(intent, priorComponents, { originalIntent
 ${JSON.stringify(priorComponents, null, 2)}
 
 The user is ITERATING on their existing canvas shown above. They want to MODIFY it, not replace it.
-
+${ITERATION_STRUCTURAL_RULES}
 Instructions:
 - Preserve ALL existing components unless explicitly asked to remove them
-- Add new components where they logically belong
+- Add new components where they logically belong (following the STRUCTURAL RULES above)
 - Change text content, labels, icons to match the new intent
 - Preserve slot attributes and Card anatomy rules
 - CRITICAL: Preserve layout container types — do NOT change Grid to Column or Row to Column. If the canvas has a Grid with columns="3" for a card collection, keep it as Grid. Only change layout types when the user explicitly requests a layout change.
@@ -966,6 +1041,7 @@ Instructions:
 ${summary}
 ${intentAnchor}
 The user wants to MODIFY their existing canvas. Return ONLY the components you need to ADD, MODIFY, or DELETE:
+${ITERATION_STRUCTURAL_RULES}
 CRITICAL PRESERVATION RULES:
 - NEVER change layout container types (Grid→Column, Row→Column, Grid→Row) unless the user explicitly asks to change the layout structure.
 - If a Grid has columns="3", keep it as Grid with columns="3". Adding a toggle/filter/button to a toolbar does NOT change the content layout below.

package/strategies/monolithic/generate-pro.js

@@ -368,10 +368,29 @@ ${buildCanvasDiffPrompt(intent, priorComponents, { originalIntent })}`;
     }
   }
 
-  // ── Canvas diff merge: apply LLM diff response onto prior canvas ──
-  // Only merge when using diff format (large canvases ≥50 components).
-  // For small canvases, the LLM was asked to return the COMPLETE modified array.
-  if (hasPriorCanvas && priorComponents.length >= 50 && messages && messages.length > 0) {
+  // ── Canvas diff merge: apply LLM response onto prior canvas ──
+  //
+  // §168 (v0.5.4): merge always runs on iteration turns regardless of canvas
+  // size. Pre-§168 the gate was `priorComponents.length >= 50`, which created
+  // a three-band threshold mismatch:
+  //   0–49   : prompt asked for COMPLETE array, merge skipped → LLM output
+  //            wholesale-replaced canvas (verified 2026-05-14 chart-workflow
+  //            ticket: 32-component canvas + "add a chart" intent →
+  //            202-component response wiped the user's prior work)
+  //   50–299 : prompt asked for COMPLETE array, merge ran treating output
+  //            as DIFF → prompt/code mismatch
+  //   300+   : prompt asked for DIFF only, merge ran (correct band)
+  //
+  // mergeCanvasDiff() is a strict superset of "replace" behaviorally:
+  //   - When LLM returns COMPLETE array: every prior id is present in output
+  //     → merged in-place (no-op if unchanged; updates if changed). Missing
+  //     prior ids preserved. New ids appended. Net behavior = identical to
+  //     wholesale-replace when LLM cooperates, safer when LLM returns subset.
+  //   - When LLM returns DIFF: existing behavior preserved.
+  // Plus the hallucination-detection guards in mergeCanvasDiff (matchRatio
+  // < 0.2 reject + < 0.6 accept-with-warning) discriminate by match ratio,
+  // which is more principled than canvas-size heuristics.
+  if (hasPriorCanvas && messages && messages.length > 0) {
     for (const msg of messages) {
       if (msg.type === 'updateComponents' && msg.components) {
         msg.components = mergeCanvasDiff(priorComponents, msg.components);

package/strategies/monolithic/merge-canvas-diff.test.js

@@ -0,0 +1,251 @@
+/**
+ * §168 (v0.5.4) — Pin canvas-iteration merge behavior across canvas sizes.
+ *
+ * Pre-§168 the merge gate was `priorComponents.length >= 50`, creating a
+ * three-band threshold mismatch:
+ *   0–49   : prompt asked for COMPLETE array, merge skipped → wholesale replace
+ *   50–299 : prompt asked for COMPLETE array, merge ran treating output as DIFF
+ *   300+   : prompt asked for DIFF only, merge ran (correct band)
+ *
+ * Post-§168 the merge runs on every iteration turn regardless of size.
+ * mergeCanvasDiff is a strict superset of "replace" behaviorally — when LLM
+ * returns COMPLETE array, every prior id is matched + merged in place;
+ * when LLM returns DIFF, existing behavior preserved.
+ *
+ * Hallucination guards (matchRatio < 0.2 reject + < 0.6 accept-with-warning)
+ * protect against LLM canvas explosions like the 2026-05-14 chart-workflow
+ * regression (32 → 202 components).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { mergeCanvasDiff } from './_shared.js';
+
+describe('§168 mergeCanvasDiff — iteration handoff invariants', () => {
+
+  describe('Strict-superset of wholesale-replace (the small-canvas band)', () => {
+    it('LLM returns COMPLETE array with all prior ids → merge preserves prior shape', () => {
+      const prior = [
+        { id: 'root', component: 'Grid', columns: 3, children: ['c1', 'c2', 'c3'] },
+        { id: 'c1', component: 'Card' },
+        { id: 'c2', component: 'Card' },
+        { id: 'c3', component: 'Card' },
+      ];
+      const llmOutput = [
+        { id: 'root', component: 'Grid', columns: 3, children: ['c1', 'c2', 'c3'] },
+        { id: 'c1', component: 'Card' },
+        { id: 'c2', component: 'Card' },
+        { id: 'c3', component: 'Card' },
+      ];
+      const result = mergeCanvasDiff(prior, llmOutput);
+      expect(result.length).toBe(4);
+      expect(result.map(c => c.id)).toEqual(['root', 'c1', 'c2', 'c3']);
+    });
+
+    it('LLM returns COMPLETE with one modification → merge applies the change', () => {
+      const prior = [
+        { id: 'root', component: 'Card', children: ['btn'] },
+        { id: 'btn', component: 'Button', text: 'Save' },
+      ];
+      const llmOutput = [
+        { id: 'root', component: 'Card', children: ['btn'] },
+        { id: 'btn', component: 'Button', text: 'Submit', variant: 'primary' },
+      ];
+      const result = mergeCanvasDiff(prior, llmOutput);
+      const btn = result.find(c => c.id === 'btn');
+      expect(btn.text).toBe('Submit');
+      expect(btn.variant).toBe('primary');
+    });
+
+    it('LLM returns COMPLETE with new addition → prior preserved + new appended', () => {
+      const prior = [
+        { id: 'root', component: 'Card', children: ['btn'] },
+        { id: 'btn', component: 'Button', text: 'Save' },
+      ];
+      const llmOutput = [
+        { id: 'root', component: 'Card', children: ['btn', 'btn-2'] },
+        { id: 'btn', component: 'Button', text: 'Save' },
+        { id: 'btn-2', component: 'Button', text: 'Cancel', variant: 'ghost' },
+      ];
+      const result = mergeCanvasDiff(prior, llmOutput);
+      expect(result.length).toBe(3);
+      expect(result.find(c => c.id === 'btn-2').text).toBe('Cancel');
+    });
+  });
+
+  describe('Hallucination-detection guards (the 32→202 regression class)', () => {
+    it('LLM hallucinates wholly-new canvas (matchRatio < 0.2) → REJECT and preserve prior', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const prior = [
+        { id: 'root', component: 'Card', children: ['c1', 'c2', 'c3'] },
+        { id: 'c1', component: 'Card' },
+        { id: 'c2', component: 'Card' },
+        { id: 'c3', component: 'Card' },
+      ];
+      // LLM "added a chart" but rebuilt from memory with no matching ids
+      const llmOutput = [
+        { id: 'root', component: 'Grid', columns: 2, children: ['new-1', 'new-2', 'new-3', 'new-4', 'new-5'] },
+        { id: 'new-1', component: 'Card' },
+        { id: 'new-2', component: 'Card' },
+        { id: 'new-3', component: 'Chart', type: 'line' },
+        { id: 'new-4', component: 'Stat' },
+        { id: 'new-5', component: 'Text' },
+      ];
+      const result = mergeCanvasDiff(prior, llmOutput);
+      // Result preserves prior canvas (user is better off unchanged)
+      expect(result).toBe(prior);
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('Hallucinated replacement rejected')
+      );
+      warn.mockRestore();
+    });
+
+    it('LLM does a major restructure (matchRatio 0.2-0.6) → accept-with-warning', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const prior = [
+        { id: 'root', component: 'Card', children: ['a', 'b', 'c', 'd', 'e'] },
+        { id: 'a', component: 'Text' },
+        { id: 'b', component: 'Text' },
+        { id: 'c', component: 'Button' },
+        { id: 'd', component: 'Button' },
+        { id: 'e', component: 'Divider' },
+      ];
+      // LLM kept 1 of 7 ids (~14% → falls into the < 0.2 band; flip to 0.2-0.6
+      // band by sharing 2 of 7 ids = 28%)
+      const llmOutput = [
+        { id: 'root', component: 'Card', children: ['a', 'new-1', 'new-2', 'new-3', 'new-4', 'new-5'] },
+        { id: 'a', component: 'Text' },
+        { id: 'new-1', component: 'Chart' },
+        { id: 'new-2', component: 'Stat' },
+        { id: 'new-3', component: 'Stat' },
+        { id: 'new-4', component: 'Stat' },
+        { id: 'new-5', component: 'Stat' },
+      ];
+      // matchRatio = 2/7 = 0.286 (between 0.2 and 0.6) → accept-with-warning path
+      const result = mergeCanvasDiff(prior, llmOutput);
+      expect(result).toBe(llmOutput);
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('Low-match rewrite accepted')
+      );
+      warn.mockRestore();
+    });
+  });
+
+  describe('DIFF format (the large-canvas band, unchanged behavior)', () => {
+    it('LLM returns ADD-only diff → prior preserved + new appended', () => {
+      const prior = [
+        { id: 'root', component: 'Card', children: ['btn'] },
+        { id: 'btn', component: 'Button', text: 'Save' },
+      ];
+      const llmDiff = [
+        { id: 'cancel', component: 'Button', text: 'Cancel', variant: 'ghost' },
+      ];
+      const result = mergeCanvasDiff(prior, llmDiff);
+      // Note: matchRatio is 0 here (1 new id, 0 matching), but only 1 component
+      // so the "hasRoot && length >= 5" guard doesn't fire (length < 5).
+      expect(result.length).toBe(3);
+      expect(result.find(c => c.id === 'btn')).toBeTruthy();
+      expect(result.find(c => c.id === 'cancel').text).toBe('Cancel');
+    });
+
+    it('LLM returns MODIFY diff → only matching id changes', () => {
+      const prior = [
+        { id: 'root', component: 'Card', children: ['btn', 'txt'] },
+        { id: 'btn', component: 'Button', text: 'Save' },
+        { id: 'txt', component: 'Text', textContent: 'Hello' },
+      ];
+      const llmDiff = [
+        { id: 'btn', text: 'Submit' },
+      ];
+      const result = mergeCanvasDiff(prior, llmDiff);
+      expect(result.find(c => c.id === 'btn').text).toBe('Submit');
+      // Component type preserved (modify-merge only updates declared fields)
+      expect(result.find(c => c.id === 'btn').component).toBe('Button');
+      // Other components untouched
+      expect(result.find(c => c.id === 'txt').textContent).toBe('Hello');
+    });
+
+    it('LLM returns DELETE diff → marked component removed', () => {
+      const prior = [
+        { id: 'root', component: 'Card', children: ['btn', 'txt'] },
+        { id: 'btn', component: 'Button' },
+        { id: 'txt', component: 'Text', textContent: 'Hello' },
+      ];
+      const llmDiff = [
+        { id: 'btn', _delete: true },
+      ];
+      const result = mergeCanvasDiff(prior, llmDiff);
+      expect(result.find(c => c.id === 'btn')).toBeUndefined();
+      expect(result.find(c => c.id === 'txt')).toBeTruthy();
+    });
+  });
+
+  describe('Layout-type guards (preserve Grid/Row/Column type during iteration)', () => {
+    it('LLM tries to change Grid → Column → block + warn', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const prior = [
+        { id: 'root', component: 'Grid', columns: 3, children: ['c1', 'c2', 'c3'] },
+        { id: 'c1', component: 'Card' },
+        { id: 'c2', component: 'Card' },
+        { id: 'c3', component: 'Card' },
+      ];
+      const llmOutput = [
+        { id: 'root', component: 'Column', children: ['c1', 'c2', 'c3'] },
+        { id: 'c1', component: 'Card' },
+        { id: 'c2', component: 'Card' },
+        { id: 'c3', component: 'Card' },
+      ];
+      const result = mergeCanvasDiff(prior, llmOutput);
+      // Grid type preserved despite LLM's attempted change
+      expect(result.find(c => c.id === 'root').component).toBe('Grid');
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('Blocked layout type change')
+      );
+      warn.mockRestore();
+    });
+  });
+
+  describe('§168 chart-workflow regression pin', () => {
+    // The 2026-05-14 user-reported scenario: 32-component canvas + "add chart"
+    // intent. Pre-§168 the LLM's 200-component response wholesale-replaced the
+    // canvas. Post-§168 the hallucination guard rejects the replacement.
+    it('32-component canvas + 200-component LLM response with low match ratio → reject', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const prior = Array.from({ length: 32 }, (_, i) => ({
+        id: `prior-${i}`,
+        component: i === 0 ? 'Grid' : (i < 10 ? 'Card' : 'Text'),
+        ...(i === 0 ? { children: ['prior-1', 'prior-2', 'prior-3'] } : {}),
+      }));
+      prior[0] = { id: 'root', component: 'Grid', children: prior.slice(1, 9).map(c => c.id) };
+
+      // LLM rebuilt from memory — 200 components, 0 matching ids
+      const llmOutput = Array.from({ length: 200 }, (_, i) => ({
+        id: `new-${i}`,
+        component: i === 0 ? 'Grid' : 'Card',
+        ...(i === 0 ? { children: ['new-1', 'new-2'] } : {}),
+      }));
+      llmOutput[0] = { id: 'root', component: 'Grid', children: ['new-1', 'new-2'] };
+
+      const result = mergeCanvasDiff(prior, llmOutput);
+      // Result preserves prior 32-component canvas (guard fires)
+      expect(result).toBe(prior);
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('Hallucinated replacement rejected')
+      );
+      warn.mockRestore();
+    });
+  });
+
+  describe('Empty-input edge cases', () => {
+    it('Empty diff → preserve prior unchanged', () => {
+      const prior = [{ id: 'root', component: 'Card' }];
+      const result = mergeCanvasDiff(prior, []);
+      expect(result).toBe(prior);
+    });
+
+    it('Empty prior → return diff as-is', () => {
+      const diff = [{ id: 'root', component: 'Card' }];
+      const result = mergeCanvasDiff([], diff);
+      expect(result).toBe(diff);
+    });
+  });
+});

package/strategies/registry.js

@@ -191,6 +191,33 @@ async function generateFreeFormAdapter(ctx) {
     // were removed by §109 / §107a; this block is now strictly debug-
     // recorder fodder. Scheduled removal: v0.6.0 will fold `attempts` +
     // `warnings` into first-class result fields and drop `_debug` here.
+    //
+    // §146 (v0.5.3): finalize the v0.6.0 deprecation schedule for the
+    // last two `_debug.*` fields that any consumer might still read.
+    //
+    // @deprecated `_debug.attempts` and `_debug.warnings` — both fields
+    //   are dialog-recorder-gated (silently `undefined` when not
+    //   recording), which is exactly the access pattern §109+§107a
+    //   removed for `usedIngredients`/`rationale`/`plan`. v0.6.0 folds
+    //   both into first-class result fields:
+    //
+    //     - `result.attempts: number` — number of LLM round-trips taken
+    //       to produce the final plan (1 normally; 2-3 with hallucination
+    //       retry or paraphrase-retry; same value as §106's loop counter)
+    //     - `result.warnings: string[]` — non-fatal transpile findings
+    //       (unknown substitution keys, layout-value fall-throughs,
+    //       chunk-resolution warns); same value as transpilePlan output
+    //
+    //   Consumers should switch reads from `result._debug?.attempts` →
+    //   `result.attempts` and `result._debug?.warnings` → `result.warnings`
+    //   before v0.6.0 ships. The `_debug` block itself disappears from
+    //   the free-form-composed result shape entirely in v0.6.0; the
+    //   dialog-recorder will read first-class fields directly.
+    //
+    //   No in-repo consumers currently read these fields (verified
+    //   `grep -rn '_debug\?.attempts\|_debug.attempts\|_debug\?.warnings\|_debug.warnings'
+    //   apps/ playgrounds/ catalog/ packages/` → 0 hits at v0.5.3 cut).
+    //   External consumers should treat v0.6.0 as the migration window.
     _debug: isRecording() ? {
       systemPrompt: null,
       rawLLMResponse: null,

package/strategies/zettel/composition-library.js

@@ -101,7 +101,17 @@ async function _loadAllNode() {
 
   function walk(dir, cb) {
     if (!fs.existsSync(dir)) return;
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    // §160 (v0.5.3, F-S1 root cause): sort readdir output. fs.readdirSync
+    // returns entries in filesystem-defined order (variable across
+    // processes on APFS/ext4), which means chunk-loading order varied
+    // run-to-run. When two chunks tied on score for a given intent, the
+    // first-loaded won the tie-break — so the same intent could match
+    // chunk A in one process and chunk B in the next. Surfaced as
+    // ~40% probe-failure rate on admin-dashboard post-§143 (the new
+    // chunks compete with the original 4-row KPI composition).
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
       const p = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(p, cb);
       else if (entry.name.endsWith('.json') && !entry.name.startsWith('_')) cb(p);

package/transpiler/extract-props.test.js

@@ -0,0 +1,228 @@
+/**
+ * §163c (v0.5.4) — extractProps() catalog-driven prop fidelity test.
+ *
+ * Pins the §163 fix: the transpiler's `extractProps()` must extract
+ * every prop the v0.9 catalog declares for a given A2UI type, not just
+ * the props in the legacy per-type allowlist (which omitted `label`,
+ * `icon`, literal `variant=` for several types).
+ *
+ * Bug class (pre-§163, diagnosed 2026-05-14):
+ *   <input-ui label="Password" type="password" placeholder="••••••••">
+ *   → emitted { component: "Input" } — label/type/placeholder all dropped
+ *   → rendered as blank rectangle in gen-ui canvas
+ *
+ * Test driver: synthetic MinimalElement objects (mimics the transpiler's
+ * fast-path token shape; no JSDOM dependency).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { extractProps } from './transpiler-maps.js';
+
+/**
+ * Build a synthetic element with the given attributes Map.
+ * Matches the MinimalElement shape transpiler.js uses for tokens.
+ */
+function elem(attrs = {}, opts = {}) {
+  const map = new Map(Object.entries(attrs));
+  return {
+    tagName: opts.tag || '',
+    attributes: map,
+    children: opts.children || [],
+    textContent: opts.text || '',
+    getAttribute(name) { return this.attributes.get(name) ?? null; },
+  };
+}
+
+describe('§163 extractProps — catalog-driven prop fidelity', () => {
+
+  describe('Input / TextField', () => {
+    it('extracts label, type, placeholder, autocomplete from <input-ui> attrs', () => {
+      const el = elem({
+        label: 'Password',
+        type: 'password',
+        name: 'password',
+        autocomplete: 'current-password',
+        placeholder: '••••••••',
+        required: '',
+      });
+      const props = extractProps(el, 'Input');
+      expect(props.label).toBe('Password');
+      expect(props.type).toBe('password');
+      expect(props.name).toBe('password');
+      expect(props.autocomplete).toBe('current-password');
+      expect(props.placeholder).toBe('••••••••');
+      expect(props.required).toBe(true);
+    });
+
+    it('keeps legacy TextField behavior', () => {
+      const el = elem({ name: 'email', value: 'foo@bar', readonly: '' });
+      const props = extractProps(el, 'TextField');
+      expect(props.name).toBe('email');
+      expect(props.value).toBe('foo@bar');
+      expect(props.readonly).toBe(true);
+    });
+  });
+
+  describe('CheckBox / Toggle (alias-resolves to Check / Switch catalog entries)', () => {
+    it('extracts label from CheckBox (aliased to Check in catalog)', () => {
+      const el = elem({ name: 'remember', label: 'Remember me' });
+      const props = extractProps(el, 'CheckBox');
+      expect(props.label).toBe('Remember me');
+      expect(props.name).toBe('remember');
+    });
+
+    it('extracts label from Toggle (aliased to Switch in catalog)', () => {
+      const el = elem({ name: 'notifications', label: 'Enable notifications', checked: '' });
+      const props = extractProps(el, 'Toggle');
+      expect(props.label).toBe('Enable notifications');
+      expect(props.name).toBe('notifications');
+      expect(props.checked).toBe(true);
+    });
+  });
+
+  describe('Button', () => {
+    it('extracts icon and variant (literal attribute, not class-inferred)', () => {
+      const el = elem({
+        text: 'Email me a magic link',
+        icon: 'envelope-simple',
+        variant: 'outline',
+      });
+      const props = extractProps(el, 'Button');
+      expect(props.text).toBe('Email me a magic link');
+      expect(props.icon).toBe('envelope-simple');
+      expect(props.variant).toBe('outline');
+    });
+
+    it('extracts type=submit + variant=primary', () => {
+      const el = elem({ text: 'Sign in', variant: 'primary', type: 'submit' });
+      const props = extractProps(el, 'Button');
+      expect(props.text).toBe('Sign in');
+      expect(props.variant).toBe('primary');
+      expect(props.type).toBe('submit');
+    });
+  });
+
+  describe('Divider', () => {
+    it('extracts label (Divider had NO extractor pre-§163)', () => {
+      const el = elem({ label: 'or use a one-time code' });
+      const props = extractProps(el, 'Divider');
+      expect(props.label).toBe('or use a one-time code');
+    });
+  });
+
+  describe('Radio', () => {
+    it('extracts label + name + value + checked', () => {
+      const el = elem({ name: 'plan', value: 'pro', label: 'Pro tier', checked: '' });
+      const props = extractProps(el, 'Radio');
+      expect(props.label).toBe('Pro tier');
+      expect(props.name).toBe('plan');
+      expect(props.value).toBe('pro');
+      expect(props.checked).toBe(true);
+    });
+  });
+
+  describe('Image', () => {
+    it('extracts src + alt', () => {
+      const el = elem({ src: '/logo.svg', alt: 'Logo' });
+      const props = extractProps(el, 'Image');
+      expect(props.src).toBe('/logo.svg');
+      expect(props.alt).toBe('Logo');
+    });
+  });
+
+  describe('Link', () => {
+    it('extracts text + href + target', () => {
+      const el = elem({ href: '/docs', target: '_blank' }, { text: 'Read docs' });
+      const props = extractProps(el, 'Link');
+      expect(props.text).toBe('Read docs');
+      expect(props.href).toBe('/docs');
+      expect(props.target).toBe('_blank');
+    });
+  });
+
+  describe('Slider', () => {
+    it('extracts label + min/max/value/step', () => {
+      const el = elem({ label: 'Volume', min: '0', max: '100', value: '50', step: '5' });
+      const props = extractProps(el, 'Slider');
+      expect(props.label).toBe('Volume');
+      // min/max/value all numeric per catalog
+      expect(props.min).toBe(0);
+      expect(props.max).toBe(100);
+      expect(props.value).toBe(50);
+    });
+  });
+
+  describe('No regression on simple cases', () => {
+    it('Text extracts textContent from element body', () => {
+      const el = elem({}, { text: 'Hello world' });
+      const props = extractProps(el, 'Text');
+      expect(props.textContent).toBe('Hello world');
+    });
+
+    it('Layout types extract gap', () => {
+      const el = elem({ gap: '4' });
+      const props = extractProps(el, 'Column');
+      expect(props.gap).toBe('4');
+    });
+
+    it('Unknown A2UI type returns empty props (no catalog crash)', () => {
+      const el = elem({ foo: 'bar' });
+      const props = extractProps(el, 'NonexistentType');
+      // No throw; just returns {} or whatever falls through legacy logic
+      expect(typeof props).toBe('object');
+    });
+  });
+
+  describe('Boolean attribute handling', () => {
+    it('treats empty string as true (HTML boolean attr convention)', () => {
+      const el = elem({ disabled: '' });
+      const props = extractProps(el, 'Button');
+      expect(props.disabled).toBe(true);
+    });
+
+    it('treats explicit "false" as false', () => {
+      const el = elem({ disabled: 'false' });
+      const props = extractProps(el, 'Button');
+      // String 'false' should not become true (defensive: HTML never has disabled="false" in practice
+      // but our catalog-driven extractor handles it)
+      expect(props.disabled).toBe(false);
+    });
+  });
+
+  describe('§163 grounding: auth-signin-card-password regression pin', () => {
+    // These are the 6 elements from the 2026-05-14 diagnosis. Pre-§163
+    // they rendered as blank rectangles. Post-§163 they have full props.
+    it('Password Input — 6 props verified', () => {
+      const el = elem({
+        label: 'Password',
+        type: 'password',
+        name: 'password',
+        autocomplete: 'current-password',
+        placeholder: '••••••••',
+        required: '',
+      });
+      const props = extractProps(el, 'Input');
+      expect(Object.keys(props).sort()).toEqual(
+        ['autocomplete', 'label', 'name', 'placeholder', 'required', 'type'].sort()
+      );
+    });
+
+    it('Remember CheckBox — label survives the alias hop CheckBox→Check', () => {
+      const el = elem({ name: 'remember', label: 'Remember me' });
+      const props = extractProps(el, 'CheckBox');
+      expect(props).toEqual({ name: 'remember', label: 'Remember me' });
+    });
+
+    it('Magic-link Button — icon, text, variant all preserved', () => {
+      const el = elem({
+        text: 'Email me a magic link',
+        icon: 'envelope-simple',
+        variant: 'outline',
+      });
+      const props = extractProps(el, 'Button');
+      expect(props.text).toBe('Email me a magic link');
+      expect(props.icon).toBe('envelope-simple');
+      expect(props.variant).toBe('outline');
+    });
+  });
+});

package/transpiler/transpiler-maps.js

@@ -6,10 +6,162 @@
  *   1. Reverse A2UI registry (tag → type, for *-n elements)
  *   2. HTML tag map (native HTML → A2UI type)
  *   3. Input type / ARIA role sub-maps
+ *
+ * §163 (v0.5.4) — Prop-fidelity fix: extractProps() now runs a
+ * catalog-driven generic pass AFTER the legacy per-type blocks. The
+ * catalog (`@adia-ai/a2ui-corpus`'s v0.9 sidecars) is the single source
+ * of truth for which attributes are first-class props per component
+ * type. Pre-§163, the per-type blocks hardcoded an allowlist that
+ * omitted `label`, `icon`, literal `variant=`, and similar — see
+ * `.brain/postmortems/2026-05-14-lossy-transpiler-boundary.md`.
+ * The catalog-driven pass closes the drift class: when a new prop is
+ * added to the catalog (regenerated from `<name>.yaml`), the extractor
+ * picks it up automatically without manual sync.
  */
 
+import catalogData from '../../corpus/catalog-a2ui_0_9.json' with { type: 'json' };
+
 import { registry } from '@adia-ai/a2ui-runtime';
 
+// ── §163 Catalog-driven prop schema ──────────────────────────────────────
+//
+// Build CATALOG_PROPS at module-init by reading the v0.9 catalog. Each
+// component's `properties` block declares its first-class props with
+// type hints (string / boolean / number / enum). The transpiler uses
+// this map to extract any prop the catalog declares, closing the
+// pre-§163 drift class where the per-type allowlists (lines ~155-249
+// below) omitted `label`, `icon`, literal `variant=`, etc.
+//
+// Aliasing: the runtime registry maps multiple A2UI type names to the
+// same tag (e.g. CheckBox → check-ui, Toggle → switch-ui, Select →
+// select-ui = ChoicePicker). The catalog is keyed by ONE canonical
+// name per tag (e.g. `Check`, `Switch`, `ChoicePicker`). We build an
+// alias map below so `extractProps(el, 'CheckBox')` resolves to the
+// `Check` catalog entry.
+
+/** @type {Map<string, {props: Map<string, {type: string, enum?: string[]}>, canonical: string}>} */
+const CATALOG_PROPS = (() => {
+  const map = new Map();
+  const components = catalogData?.components || {};
+  for (const [name, def] of Object.entries(components)) {
+    const props = def?.properties || {};
+    const propMap = new Map();
+    for (const [pname, pdef] of Object.entries(props)) {
+      // Skip internal/computed props that aren't HTML attributes
+      if (pname === 'component' || pname === 'textContent') continue;
+      if (typeof pdef !== 'object' || !pdef) continue;
+      propMap.set(pname, {
+        type: pdef.type || 'string',
+        enum: pdef.enum || null,
+      });
+    }
+    map.set(name, { props: propMap, canonical: name });
+  }
+  return map;
+})();
+
+/**
+ * Map an A2UI type name (which may be an alias used by the runtime
+ * registry but not the catalog) to the canonical catalog name.
+ *
+ * Examples (driven by runtime/registry.js mappings):
+ *   CheckBox → Check  (registry: CheckBox→check-ui; catalog: Check)
+ *   Toggle   → Switch (registry: Toggle→switch-ui; catalog: Switch)
+ *   Select   → ChoicePicker (registry: Select→select-ui; catalog: ChoicePicker)
+ *
+ * Strategy: for every registry alias type, find the catalog entry whose
+ * tag (= kebab-cased catalog name + '-ui', or registry forward-lookup)
+ * matches the alias's runtime tag. The catalog often uses a name that
+ * is NOT in the registry as a forward entry (e.g. `Check` is in the
+ * catalog but the registry only has `CheckBox → check-ui`).
+ *
+ * Cached at module-init.
+ */
+const TYPE_ALIAS = (() => {
+  const m = new Map();
+  // Pre-pass: every catalog name maps to itself (catalog names ARE valid A2UI types
+  // even when the runtime registry doesn't carry them as forward entries — e.g.
+  // `Check` is in catalog but registry only has `CheckBox → check-ui`).
+  for (const catName of CATALOG_PROPS.keys()) {
+    m.set(catName, catName);
+  }
+  // First pass: direct match (typeName IS the catalog canonical)
+  for (const typeName of registry.keys()) {
+    if (CATALOG_PROPS.has(typeName)) {
+      m.set(typeName, typeName);
+    }
+  }
+  // Second pass: type's tag matches another registry entry that's in the catalog
+  for (const [typeName, tagName] of registry.entries()) {
+    if (m.has(typeName)) continue;
+    for (const [otherType, otherTag] of registry.entries()) {
+      if (otherTag === tagName && CATALOG_PROPS.has(otherType)) {
+        m.set(typeName, otherType);
+        break;
+      }
+    }
+  }
+  // Third pass: derive canonical from tag — `check-ui` → `Check`,
+  // `switch-ui` → `Switch`. The catalog often has the canonical
+  // PascalCase that the registry doesn't list as a forward entry.
+  // We convert tag kebab → PascalCase and check the catalog.
+  for (const [typeName, tagName] of registry.entries()) {
+    if (m.has(typeName)) continue;
+    // 'check-ui' → 'Check'; 'switch-ui' → 'Switch'; 'list-item-ui' → 'ListItem'
+    const stripped = tagName.replace(/-ui$/, '');
+    const pascal = stripped.split('-').map(s => s[0]?.toUpperCase() + s.slice(1)).join('');
+    if (CATALOG_PROPS.has(pascal)) {
+      m.set(typeName, pascal);
+    }
+  }
+  return m;
+})();
+
+/**
+ * §163 generic extractor: pull every catalog-declared prop from the
+ * element's attributes. Type-aware (booleans become true on presence,
+ * numbers parse, enums validate optimistically).
+ *
+ * Runs AFTER the legacy per-type blocks below — so type-specific
+ * extraction (e.g. Button.text from textContent, Image.alt) wins on
+ * conflict. The generic pass FILLS IN props the legacy blocks miss
+ * (the prop-fidelity gap this fix closes).
+ *
+ * @param {object} el — DOM element or MinimalElement
+ * @param {string} a2uiType — Resolved A2UI type name (may be alias)
+ * @returns {Record<string, unknown>}
+ */
+function extractCatalogProps(el, a2uiType) {
+  const canonical = TYPE_ALIAS.get(a2uiType);
+  if (!canonical) return {};
+  const schema = CATALOG_PROPS.get(canonical);
+  if (!schema) return {};
+  const attr = (name) => el.getAttribute?.(name) ?? el.attributes?.get?.(name) ?? null;
+  const props = {};
+  for (const [pname, pdef] of schema.props.entries()) {
+    const raw = attr(pname);
+    if (raw === null || raw === undefined) continue;
+
+    if (pdef.type === 'boolean') {
+      // HTML boolean attr convention: presence (incl. empty string) = true.
+      //   <input required>            → raw === ''      → true
+      //   <input required="">         → raw === ''      → true
+      //   <input required="required"> → raw === 'required' → true
+      //   <input required="false">    → raw === 'false' → false (defensive)
+      props[pname] = raw !== 'false';
+    } else if (pdef.type === 'number' || pdef.type === 'integer') {
+      if (raw === '') continue;
+      const n = Number(raw);
+      props[pname] = Number.isFinite(n) ? n : raw;
+    } else {
+      // string (incl. enum) — skip empty
+      if (raw === '') continue;
+      props[pname] = raw;
+    }
+  }
+  return props;
+}
+
 // ── Alias types to skip in reverse registry (prefer primary type) ────────
 
 const ALIAS_TYPES = new Set([
@@ -144,6 +296,13 @@ export function extractProps(el, a2uiType) {
   const props = {};
   const attr = (name) => el.getAttribute?.(name) ?? el.attributes?.get?.(name) ?? null;
 
+  // §163 (v0.5.4) — Catalog-driven generic extraction FIRST. Fills in
+  // every prop the v0.9 catalog declares for this type (label, icon,
+  // variant=, etc.). Legacy per-type blocks below run AFTER and can
+  // overwrite specific values (e.g. Button.text inferred from
+  // textContent when no `text=` attribute is set).
+  Object.assign(props, extractCatalogProps(el, a2uiType));
+
   // ── Text content (for leaf elements) ──
   if (['Text', 'Kbd', 'Code'].includes(a2uiType)) {
     const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
@@ -152,17 +311,23 @@ export function extractProps(el, a2uiType) {
 
   // ── Button ──
   if (a2uiType === 'Button') {
-    const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
-    if (text) props.text = text;
-    const type = attr('type');
-    if (type && type !== 'button') props.type = type;
-    if (attr('disabled') !== null) props.disabled = true;
-    // Variant inference from class
-    const cls = attr('class') || '';
-    if (cls.includes('primary')) props.variant = 'primary';
-    else if (cls.includes('danger')) props.variant = 'danger';
-    else if (cls.includes('ghost')) props.variant = 'ghost';
-    else if (cls.includes('outline')) props.variant = 'outline';
+    if (props.text === undefined) {
+      const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+      if (text) props.text = text;
+    }
+    if (props.type === undefined) {
+      const type = attr('type');
+      if (type && type !== 'button') props.type = type;
+    }
+    if (props.disabled === undefined && attr('disabled') !== null) props.disabled = true;
+    // Variant inference from class (only if generic pass didn't already extract literal `variant=` attr)
+    if (props.variant === undefined) {
+      const cls = attr('class') || '';
+      if (cls.includes('primary')) props.variant = 'primary';
+      else if (cls.includes('danger')) props.variant = 'danger';
+      else if (cls.includes('ghost')) props.variant = 'ghost';
+      else if (cls.includes('outline')) props.variant = 'outline';
+    }
   }
 
   // ── Link ── (§47 — <a> tags map to Link, not Button; carries href, target, rel)
@@ -204,10 +369,11 @@ export function extractProps(el, a2uiType) {
   // ── Slider ──
   if (a2uiType === 'Slider') {
     for (const name of ['min', 'max', 'value', 'step', 'name']) {
+      if (props[name] !== undefined) continue;  // catalog pass already filled this
       const v = attr(name);
       if (v !== null && v !== '') props[name] = name === 'step' ? v : Number(v) || v;
     }
-    if (attr('disabled') !== null) props.disabled = true;
+    if (props.disabled === undefined && attr('disabled') !== null) props.disabled = true;
   }
 
   // ── Image ──