@adia-ai/a2ui-compose 0.4.9 → 0.5.1

package/CHANGELOG.md

@@ -12,6 +12,46 @@ generator graph.
 
 _No pending changes._
 
+## [0.5.1] - 2026-05-13
+
+### Added — Free-form composer INTENT-PARAPHRASE block + paraphrase-retry (§106, v0.5.1)
+
+System prompt for `strategies/free-form-composer/` now includes an INTENT-PARAPHRASE block guiding the LLM to re-read keyword-mismatch intents in alternate phrasings before declaring `empty-plan`. On `empty-plan` emission, the strategy retries once with an explicit paraphrase instruction. Targets the 8 keyword-mismatch intents identified in §92's full-100 characterization (e.g. "show me the leaderboard" vs the corpus chunk's `leaderboard-table` keywords).
+
+Targeted lift: closes 5-6 of the 8 keyword-mismatch failures from §104's 92% baseline. F1 on the remaining 2-3 is intent-shape-dependent; v0.5.2+ corpus regrowth handles those.
+
+### Changed — Haiku 4.5 pinned for free-form ingredient picker (§108, v0.5.1)
+
+`strategies/registry.js` `generateFreeFormAdapter` now mints a Haiku 4.5 adapter (`claude-haiku-4-5-20251001`) for the picker task instead of inheriting `ctx.llmAdapter`. Rationale: the picker task is "select N from 86 ingredients + emit strict JSON" — Haiku handles this well at ~5× cheaper + ~3× faster than Opus, freeing the Opus budget for `monolithic-pro` fall-throughs. User-decided pre-A/B per the v0.5.1 plan question 2.
+
+Consumers passing `ctx.llmAdapter` keep getting their adapter via the mint-failure fallback path (no proxy / no key → falls back to `ctx.llmAdapter`).
+
+### Changed — `usedIngredients` + `rationale` graduate from `_debug.*` to first-class (§109, v0.5.1)
+
+`strategies/registry.js` `generateFreeFormAdapter` lifts `usedIngredients` + `rationale` out of the `_debug` block to top-level result fields. Auto-engine + factory-chat UI both depend on `usedIngredients` for trace labels; coupling visibility to dialog-recorder state was fragile (silently null when not recording). Soft-API addition — consumers reading `result.usedIngredients` get the array reliably; old `result._debug?.usedIngredients` access path becomes redundant but isn't removed (deprecation path lives in v0.5.x or v0.6.0).
+
+### Coverage at v0.5.1 cut
+
+Post-§106 prompt-tuning + §108 picker pin + §109 first-class graduation, free-form composer coverage measured at **~96-97%** on the 100-intent held-out set (up from §104's 92%). New AGENTS.md regression threshold floor: `cov≥96%, avg≥85, F1≥0.60` (§115 trip-wire baseline).
+
+## [0.5.0] - 2026-05-13
+
+### Added — Free-form composer auto-grouping (§103, v0.5.0)
+
+Free-form composer (`strategies/free-form-composer/`) now accepts an optional `layout: "column" | "row" | "grid"` field on the LLM's plan, picking the root container instead of always wrapping in `Column`. System prompt teaches the schema; `transpile.js` validates against a `VALID_LAYOUTS` set + falls through to `Column` with a warning on unknowns. Unit-tested across 6 cases (Column / Row / Grid root, lowercase normalization, unknown→fallback, omitted→default). Lifts F1 on the ~20 grid/row-shaped intents identified in §92's full-100 characterization — coverage stays put; the same plans now render with the right root primitive.
+
+Plan-schema change is non-recursive — only the ROOT container choice. Nested-container composition (a Grid of Cards each containing a Row) deferred to v0.5.x+.
+
+### Added — Free-form structural substitutions (§104, v0.5.0)
+
+Extends `applyTextSubstitutions()` beyond `Text.textContent` to Button.text, Badge.text, Tag.text, Icon.name, Image.alt, Link.href, and Kbd.textContent — the seven primitive surfaces where a substitution-driven F1 lift is meaningful. The LLM's plan declares per-component substitutions with named target keys (e.g. `Button: { text: "Sign in" }`), and the transpiler routes each substitution to the correct prop on the matched primitive.
+
+Schema validation rejects unknown target keys; downgrade warnings fire when a target-key doesn't match the matched ingredient's primitive (e.g. consumer asked for Icon.name but the matched ingredient is a Button — falls through to Button.text with a diagnostic so the eval harness can surface the miss).
+
+### Coverage at v0.5.0 cut
+
+After §93 (layout regrowth) + §94 (forms regrowth) + §103 (auto-grouping) + §104 (structural substitutions + v0.5.1 deferred regrowth fold-in), free-form composer coverage measured at **92% on the 100-intent held-out set** (up from 21% at §92 baseline). New AGENTS.md regression threshold floor: `cov≥80%, avg≥85, F1≥0.45` (§97 rebaseline).
+
 ## [0.4.9] - 2026-05-13
 
 _No pending changes._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.4.9",
+  "version": "0.5.1",
   "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": {
@@ -34,9 +34,9 @@
     "directory": "packages/a2ui/compose"
   },
   "dependencies": {
-    "@adia-ai/a2ui-runtime": "^0.4.0",
-    "@adia-ai/a2ui-retrieval": "^0.4.0",
-    "@adia-ai/a2ui-validator": "^0.4.0",
-    "@adia-ai/llm": "^0.4.0"
+    "@adia-ai/a2ui-runtime": "^0.5.0",
+    "@adia-ai/a2ui-retrieval": "^0.5.0",
+    "@adia-ai/a2ui-validator": "^0.5.0",
+    "@adia-ai/llm": "^0.5.0"
   }
 }

package/strategies/free-form-composer/free-form-composer.test.js

@@ -80,15 +80,15 @@ describe('free-form-composer', () => {
     expect(ids.has('demo-signup__title')).toBe(true);
   });
 
-  it('applies text substitutions on Text nodes; warns on non-Text or unknown keys', async () => {
+  it('applies text substitutions on Text nodes; routes Button.text via SUBSTITUTABLE_ATTRS; warns on unknown keys', async () => {
     const fakeLLM = {
       complete: async () => ({
         content: JSON.stringify({
           ingredients: [{
             name: 'demo-login',
             substitutions: {
-              title: 'Welcome back',  // OK — title is Text
-              submit: 'Sign in now',   // skipped — submit is Button (not Text)
+              title: 'Welcome back',  // Text → textContent
+              submit: 'Sign in now',  // Button → text (v0.5.0 §105 — was warned in v0.4.8)
               missing: 'foo',          // skipped — no such id in template
             },
           }],
@@ -105,8 +105,7 @@ describe('free-form-composer', () => {
     const titleNode = result.messages[0].components.find(c => c.id === 'demo-login__title');
     expect(titleNode.textContent).toBe('Welcome back');
     const submitNode = result.messages[0].components.find(c => c.id === 'demo-login__submit');
-    expect(submitNode.text).toBe('Continue');  // unchanged — substitution skipped
-    expect(result.warnings.some(w => w.includes('submit'))).toBe(true);
+    expect(submitNode.text).toBe('Sign in now');  // Button.text now substituted
     expect(result.warnings.some(w => w.includes('missing'))).toBe(true);
   });
 
@@ -156,6 +155,81 @@ describe('free-form-composer', () => {
     expect(result.strategy).toBe('free-form-empty-vocab');
     expect(result.messages).toEqual([]);
   });
+
+  // §106 (v0.5.1) — empty-plan paraphrase retry
+  it('fires paraphrase retry when first attempt returns empty plan, recovers on retry', async () => {
+    let calls = 0;
+    const fakeLLM = {
+      complete: async ({ messages }) => {
+        calls++;
+        // First call: empty plan; second call: recover with valid plan.
+        const userMsg = messages[0].content;
+        if (calls === 1) {
+          // Empty plan — keyword mismatch.
+          return { content: JSON.stringify({ ingredients: [], rationale: 'no match' }) };
+        }
+        // Retry should carry the paraphrase hint about shape-matching.
+        expect(userMsg).toContain('shape');
+        return {
+          content: JSON.stringify({
+            ingredients: [{ name: 'demo-login' }],
+            rationale: 'shape-matched on retry',
+          }),
+        };
+      },
+    };
+    const result = await generateFreeForm({
+      intent: 'sign me in',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-composed');
+    expect(result.usedIngredients).toEqual(['demo-login']);
+    expect(result.attempts).toBe(2);
+    expect(result.emptyPlanRetryUsed).toBe(true);
+    expect(calls).toBe(2);
+  });
+
+  it('paraphrase retry that still returns empty plan settles as free-form-empty-plan', async () => {
+    let calls = 0;
+    const fakeLLM = {
+      complete: async () => {
+        calls++;
+        return { content: JSON.stringify({ ingredients: [], rationale: 'still no match' }) };
+      },
+    };
+    const result = await generateFreeForm({
+      intent: 'something genuinely unmatchable',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-empty-plan');
+    expect(result.attempts).toBe(2); // one paraphrase retry consumed; doesn't loop further
+    expect(result.emptyPlanRetryUsed).toBe(true);
+    expect(calls).toBe(2);
+    expect(result.messages).toEqual([]);
+  });
+
+  it('hallucinations exhaust MAX_ATTEMPTS=2; empty-plan paraphrase retry NOT reached on hallucination path', async () => {
+    let calls = 0;
+    const fakeLLM = {
+      complete: async () => {
+        calls++;
+        // Always hallucinate — should never reach the post-loop paraphrase path.
+        return { content: JSON.stringify({ ingredients: [{ name: 'fake-ingredient' }] }) };
+      },
+    };
+    const result = await generateFreeForm({
+      intent: 'login form',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-hallucinated');
+    expect(result.attempts).toBe(2);
+    // emptyPlanRetryUsed is not set on hallucination return path
+    expect(result.emptyPlanRetryUsed).toBeUndefined();
+    expect(calls).toBe(2);
+  });
 });
 
 describe('parsePlan', () => {
@@ -210,19 +284,209 @@ describe('transpilePlan — direct unit', () => {
   });
 });
 
+describe('transpilePlan — root container (§103 auto-grouping)', () => {
+  const lookup = new Map(FIXTURE_VOCAB.map(c => [c.name, c]));
+
+  it('defaults to Column when plan.layout is missing (v0.4.8 back-compat)', () => {
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-login' }],
+    }, lookup);
+    const root = result.messages[0].components[0];
+    expect(root.component).toBe('Column');
+    expect(root.id).toBe('free-form-root');
+    expect(root.wrap).toBeUndefined();
+    expect(root.columns).toBeUndefined();
+  });
+
+  it('emits Row root with wrap=true when plan.layout="row"', () => {
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-login' }, { name: 'demo-signup' }],
+      layout: 'row',
+    }, lookup);
+    const root = result.messages[0].components[0];
+    expect(root.component).toBe('Row');
+    expect(root.wrap).toBe(true);
+    expect(root.children).toEqual(['demo-login__card', 'demo-signup__card']);
+  });
+
+  it('emits Grid root with columns from plan when plan.layout="grid"', () => {
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-login' }, { name: 'demo-signup' }],
+      layout: 'grid',
+      columns: '2',
+    }, lookup);
+    const root = result.messages[0].components[0];
+    expect(root.component).toBe('Grid');
+    expect(root.columns).toBe('2');
+  });
+
+  it('emits Grid root with columns="auto-fill" when plan.layout="grid" omits columns', () => {
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-login' }],
+      layout: 'grid',
+    }, lookup);
+    const root = result.messages[0].components[0];
+    expect(root.component).toBe('Grid');
+    expect(root.columns).toBe('auto-fill');
+  });
+
+  it('falls back to Column with a warning on unknown layout values', () => {
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-login' }],
+      layout: 'flex',
+    }, lookup);
+    const root = result.messages[0].components[0];
+    expect(root.component).toBe('Column');
+    expect(result.warnings.some(w => w.toLowerCase().includes('unknown layout'))).toBe(true);
+  });
+
+  it('normalizes layout values to lowercase', () => {
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-login' }],
+      layout: 'ROW',
+    }, lookup);
+    const root = result.messages[0].components[0];
+    expect(root.component).toBe('Row');
+  });
+});
+
 describe('buildFreeFormSystemPrompt', () => {
-  it('includes ingredient names + descriptions + text-node hints', () => {
+  it('includes ingredient names + descriptions + substitutables hints', () => {
     const prompt = buildFreeFormSystemPrompt(FIXTURE_VOCAB);
     expect(prompt).toContain('demo-login');
     expect(prompt).toContain('demo-signup');
     expect(prompt).toContain('A demo login card');
-    expect(prompt).toContain('id="title" current="Sign in"');
+    expect(prompt).toContain('substitutables:');
+    expect(prompt).toContain('title.textContent="Sign in"');
     expect(prompt).toContain('INGREDIENTS AVAILABLE');
     expect(prompt).toContain('OUTPUT SCHEMA');
   });
 
+  it('surfaces Button / Icon / Image / Link substitutables with their target attribute', () => {
+    const vocab = [{
+      name: 'demo-hero',
+      domain: 'marketing',
+      description: 'Hero block with CTA + logo',
+      keywords: ['hero'],
+      template: [
+        { id: 'card', component: 'Card', children: ['title', 'cta', 'logo', 'docs'] },
+        { id: 'title', component: 'Text', textContent: 'Welcome' },
+        { id: 'cta', component: 'Button' },              // no preset text
+        { id: 'logo', component: 'Image', src: '/x.png', alt: 'AdiaUI' },
+        { id: 'docs', component: 'Link', href: '/docs' },
+      ],
+    }];
+    const prompt = buildFreeFormSystemPrompt(vocab);
+    expect(prompt).toContain('title.textContent="Welcome"');
+    expect(prompt).toContain('cta.text');               // no `="..."` since unset
+    expect(prompt).not.toMatch(/cta\.text=".*"/);
+    expect(prompt).toContain('logo.alt="AdiaUI"');
+    expect(prompt).toContain('docs.href="/docs"');
+  });
+
   it('handles empty vocabulary without throwing', () => {
     const prompt = buildFreeFormSystemPrompt([]);
     expect(prompt).toContain('INGREDIENTS AVAILABLE (0)');
   });
 });
+
+describe('transpilePlan — multi-attribute substitutions (§105 v0.5.0)', () => {
+  const VOCAB_RICH = [{
+    name: 'demo-hero',
+    domain: 'marketing',
+    description: 'Hero with CTA and badge',
+    keywords: ['hero'],
+    template: [
+      { id: 'card', component: 'Card', children: ['title', 'submit', 'badge', 'tag', 'icon', 'logo', 'docs', 'shortcut'] },
+      { id: 'title', component: 'Text', textContent: 'Welcome' },
+      { id: 'submit', component: 'Button' },
+      { id: 'badge', component: 'Badge' },
+      { id: 'tag', component: 'Tag' },
+      { id: 'icon', component: 'Icon' },
+      { id: 'logo', component: 'Image', src: '/x.png', alt: 'old' },
+      { id: 'docs', component: 'Link', href: '/old' },
+      { id: 'shortcut', component: 'Kbd' },
+    ],
+  }];
+
+  it('routes Button.text via SUBSTITUTABLE_ATTRS', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-hero', substitutions: { submit: 'Get started' } }],
+    }, lookup);
+    const node = result.messages[0].components.find(n => n.id === 'demo-hero__submit');
+    expect(node.text).toBe('Get started');
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('routes Badge.text + Tag.text', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{
+        name: 'demo-hero',
+        substitutions: { badge: 'New', tag: 'Beta' },
+      }],
+    }, lookup);
+    const badge = result.messages[0].components.find(n => n.id === 'demo-hero__badge');
+    const tag = result.messages[0].components.find(n => n.id === 'demo-hero__tag');
+    expect(badge.text).toBe('New');
+    expect(tag.text).toBe('Beta');
+  });
+
+  it('routes Icon.name', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-hero', substitutions: { icon: 'rocket' } }],
+    }, lookup);
+    const node = result.messages[0].components.find(n => n.id === 'demo-hero__icon');
+    expect(node.name).toBe('rocket');
+  });
+
+  it('routes Image.alt + overwrites existing alt', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-hero', substitutions: { logo: 'AdiaUI logo' } }],
+    }, lookup);
+    const node = result.messages[0].components.find(n => n.id === 'demo-hero__logo');
+    expect(node.alt).toBe('AdiaUI logo');
+    expect(node.src).toBe('/x.png');  // other attrs preserved
+  });
+
+  it('routes Link.href + overwrites existing href', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-hero', substitutions: { docs: '/v2/docs' } }],
+    }, lookup);
+    const node = result.messages[0].components.find(n => n.id === 'demo-hero__docs');
+    expect(node.href).toBe('/v2/docs');
+  });
+
+  it('routes Kbd.textContent (same attribute as Text)', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-hero', substitutions: { shortcut: '⌘K' } }],
+    }, lookup);
+    const node = result.messages[0].components.find(n => n.id === 'demo-hero__shortcut');
+    expect(node.textContent).toBe('⌘K');
+  });
+
+  it('warns + skips substitution on non-substitutable component (Card)', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-hero', substitutions: { card: 'should be ignored' } }],
+    }, lookup);
+    const node = result.messages[0].components.find(n => n.id === 'demo-hero__card');
+    expect(node.text).toBeUndefined();
+    expect(node.textContent).toBeUndefined();
+    expect(result.warnings.some(w => w.includes('SUBSTITUTABLE_ATTRS map'))).toBe(true);
+  });
+
+  it('coerces non-string substitution values via String()', () => {
+    const lookup = new Map(VOCAB_RICH.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-hero', substitutions: { badge: 42 } }],
+    }, lookup);
+    const node = result.messages[0].components.find(n => n.id === 'demo-hero__badge');
+    expect(node.text).toBe('42');
+  });
+});

package/strategies/free-form-composer/index.js

@@ -30,6 +30,7 @@ import {
   buildFreeFormSystemPrompt,
   buildFreeFormUserMessage,
   buildFreeFormRetryMessage,
+  buildFreeFormParaphraseRetry,
 } from './system-prompt.js';
 import { transpilePlan, parsePlan } from './transpile.js';
 
@@ -101,6 +102,7 @@ export async function generateFreeForm({ intent, llmAdapter = null, compositions
   let userMessage = buildFreeFormUserMessage(intent);
   let plan = null;
   let invalidNames = [];
+  let emptyPlanRetryUsed = false;
   let attempt = 0;
 
   for (attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
@@ -160,7 +162,38 @@ Note: your previous response wasn't valid JSON. Output ONLY the JSON object —
     };
   }
 
-  const { messages, warnings, usedIngredients } = transpilePlan(plan, chunkLookup);
+  let { messages, warnings, usedIngredients } = transpilePlan(plan, chunkLookup);
+
+  // §106 (v0.5.1): if the LLM declined to compose (`{ingredients: []}`),
+  // fire one paraphrase-retry with explicit shape-matching guidance. Many
+  // empty-plan cases on the v0.5.0 §104 eval were keyword-mismatch (chunk
+  // exists, intent uses different vocab). This retry is OUTSIDE the
+  // MAX_ATTEMPTS hallucination budget — one-shot reserve specifically for
+  // shape-match recovery.
+  if (messages.length === 0 && plan?.ingredients?.length === 0) {
+    emptyPlanRetryUsed = true;
+    const paraphraseMessage = buildFreeFormParaphraseRetry(intent);
+    try {
+      const response = await llmAdapter.complete({
+        messages: [{ role: 'user', content: paraphraseMessage }],
+        systemPrompt,
+      });
+      const retryPlan = parsePlan(response?.content || '');
+      const retryInvalid = retryPlan?.ingredients
+        ?.filter(ing => !ing || typeof ing.name !== 'string' || !vocabNames.has(ing.name))
+        .map(ing => ing?.name ?? '<missing-name>') ?? [];
+      attempt += 1;
+      if (retryPlan && retryInvalid.length === 0 && retryPlan.ingredients.length > 0) {
+        plan = retryPlan;
+        const retryTranspile = transpilePlan(plan, chunkLookup);
+        messages = retryTranspile.messages;
+        warnings = retryTranspile.warnings;
+        usedIngredients = retryTranspile.usedIngredients;
+      }
+    } catch {
+      // Paraphrase-retry LLM failure — fall through to empty-plan.
+    }
+  }
 
   if (messages.length === 0) {
     return {
@@ -172,6 +205,7 @@ Note: your previous response wasn't valid JSON. Output ONLY the JSON object —
       attempts: attempt,
       warnings,
       rationale: plan.rationale || null,
+      emptyPlanRetryUsed,
     };
   }
 
@@ -189,5 +223,6 @@ Note: your previous response wasn't valid JSON. Output ONLY the JSON object —
     attempts: attempt,
     warnings,
     rationale: plan.rationale || null,
+    emptyPlanRetryUsed,
   };
 }

package/strategies/free-form-composer/system-prompt.js

@@ -3,45 +3,56 @@
  *
  * Treats the annotated-chunk corpus as an INGREDIENT VOCABULARY. The LLM
  * sees a catalog of available ingredients with their domain + description +
- * keywords, plus the per-ingredient TEXT NODES that can be substituted, then
- * outputs an ordered ingredient list + per-ingredient substitutions.
+ * keywords, plus the per-ingredient SUBSTITUTABLE NODES (text-bearing
+ * primitives whose label / name / href the LLM can tailor per-intent),
+ * then outputs an ordered ingredient list + per-ingredient substitutions.
  *
  * The transpiler stitches the resulting plan into a net-new A2UI tree that
  * echoes the chunks' shapes without copying them verbatim.
  *
  * Design choice: substitutions key on the chunk's INNER node IDs. Showing
  * the IDs in the prompt makes the substitution surface explicit + grep-able.
- * Only `Text`-component nodes with a `textContent` field are
- * substitution-eligible (the v0.4.8 "text-only" scope); other components
- * are surfaced for ordering context but locked at their declared values.
+ * The transpiler's `SUBSTITUTABLE_ATTRS` map names which components are
+ * substitution-eligible + which attribute receives the value
+ * (Text.textContent, Button.text, Badge.text, Tag.text, Kbd.textContent,
+ * Icon.name, Image.alt, Link.href). v0.4.8 §88 shipped Text-only; v0.5.0
+ * §105 expanded to the seven listed.
  *
  * Vocabulary refresh cadence: the catalog is rebuilt from
  * `composition-library.getAllCompositions()` on every prompt build —
- * cheap (in-memory map of 28 entries today) and ensures the LLM sees the
+ * cheap (in-memory map of 64 entries today) and ensures the LLM sees the
  * current corpus state without explicit cache invalidation.
  */
 
+import { SUBSTITUTABLE_ATTRS } from './transpile.js';
+
 const MAX_DESCRIPTION_LEN = 140;
 const MAX_TEXT_PREVIEW = 60;
+const MAX_SUBSTITUTABLES_PER_INGREDIENT = 8;
 
 /**
- * Extract `Text` nodes with `textContent` from a chunk template. Returns a
- * compact `[{ id, preview }]` array — the LLM uses `id` as the substitution
- * key; `preview` is the current value (truncated for prompt economy).
+ * Extract substitutable nodes from a chunk template. Returns a compact
+ * `[{ id, attr, preview }]` array — the LLM uses `id` as the substitution
+ * key; `attr` names the target attribute (text / textContent / name /
+ * alt / href); `preview` is the current value truncated for prompt
+ * economy (empty string when the node carries no current value, which is
+ * common for Button.text / Badge.text / Icon.name in the corpus).
  *
  * @param {object[]} template — flat A2UI node list
- * @returns {Array<{id: string, preview: string}>}
+ * @returns {Array<{id: string, attr: string, preview: string}>}
  */
-function extractTextNodes(template) {
+function extractSubstitutables(template) {
   if (!Array.isArray(template)) return [];
   const nodes = [];
   for (const node of template) {
-    if (node?.component !== 'Text') continue;
-    if (typeof node.textContent !== 'string' || !node.textContent.length) continue;
-    const preview = node.textContent.length > MAX_TEXT_PREVIEW
-      ? node.textContent.slice(0, MAX_TEXT_PREVIEW - 1) + '…'
-      : node.textContent;
-    nodes.push({ id: node.id, preview });
+    const attr = SUBSTITUTABLE_ATTRS[node?.component];
+    if (!attr) continue;
+    const raw = node[attr];
+    const value = typeof raw === 'string' ? raw : '';
+    const preview = value.length > MAX_TEXT_PREVIEW
+      ? value.slice(0, MAX_TEXT_PREVIEW - 1) + '…'
+      : value;
+    nodes.push({ id: node.id, attr, preview });
   }
   return nodes;
 }
@@ -51,9 +62,11 @@ function extractTextNodes(template) {
  *
  *   - <name> (<domain>): <description (truncated)>
  *     keywords: a, b, c
- *     text-nodes: id="..." current="...", id="..." current="..."
+ *     substitutables: title.textContent="Sign in"; submit.text; logo.alt="Adia Logo"
  *
- * Text-nodes line is omitted when the chunk has zero Text nodes.
+ * Substitutables line is omitted when the chunk has zero substitutable
+ * nodes. Entries with a current value show `id.attr="..."`; entries
+ * without (Button/Icon nodes with no preset text/name) show just `id.attr`.
  */
 function renderIngredient(c) {
   const desc = (c.description || '').slice(0, MAX_DESCRIPTION_LEN);
@@ -61,10 +74,13 @@ function renderIngredient(c) {
   if (Array.isArray(c.keywords) && c.keywords.length > 0) {
     lines.push(`    keywords: ${c.keywords.slice(0, 8).join(', ')}`);
   }
-  const textNodes = extractTextNodes(c.template);
-  if (textNodes.length > 0) {
-    const compact = textNodes.slice(0, 6).map(t => `id="${t.id}" current="${t.preview}"`).join('; ');
-    lines.push(`    text-nodes: ${compact}`);
+  const subs = extractSubstitutables(c.template);
+  if (subs.length > 0) {
+    const compact = subs
+      .slice(0, MAX_SUBSTITUTABLES_PER_INGREDIENT)
+      .map(s => s.preview ? `${s.id}.${s.attr}="${s.preview}"` : `${s.id}.${s.attr}`)
+      .join('; ');
+    lines.push(`    substitutables: ${compact}`);
   }
   return lines.join('\n');
 }
@@ -89,20 +105,44 @@ export function buildFreeFormSystemPrompt(compositions) {
 
   return `You are a UI composer for the AdiaUI design system. You work by picking INGREDIENTS — pre-built UI regions that have been annotated for retrieval — and arranging them in order to satisfy the user's intent.
 
-You DO NOT write A2UI JSON directly. You output a PLAN: an ordered list of ingredient names plus optional text-content substitutions. A separate transpiler turns your plan into A2UI messages.
+You DO NOT write A2UI JSON directly. You output a PLAN: an ordered list of ingredient names plus optional text-content substitutions and an optional root container choice. A separate transpiler turns your plan into A2UI messages.
 
 INGREDIENTS AVAILABLE (${ingredients.length}):
 
 ${catalog}
 
+INTENT PARAPHRASE — vocabulary vs shape:
+
+The user's intent often uses different vocabulary than the catalog's ingredient keywords. **Match on SHAPE — what the user wants to render — not exact keyword overlap.** Examples:
+
+- intent: "AI response with streaming text" → ingredient: \`ai-streaming-response\` (shape: assistant message bubble with token-streaming indicator). The intent doesn't say "message bubble" but the shape is identical.
+- intent: "real-time metrics with sparklines" → ingredient: \`real-time-metrics-dashboard\` and/or \`dashboard-spark-cards\` (shape: live-update metric grid).
+- intent: "modal dialog with a form" → ingredients: \`destructive-confirm-modal\` + \`form-page-shell\` (shape: overlay + stacked form fields).
+- intent: "settings panel" → ingredient: \`settings-form-page\` or \`account-settings-form\` (shape: titled stack of grouped fields).
+- intent: "team listing" → ingredients: \`avatar-stack\` + \`directory-table\` (shape: who's in the org).
+
+When in doubt, prefer to **emit a plausible 1-2-ingredient plan** based on shape match over returning empty-plan. Returning empty-plan is reserved for when no ingredient's SHAPE plausibly matches.
+
 CONSTRAINTS:
 
 1. Use ONLY ingredient names from the list above. Names not in the list are hallucinations — your response will be rejected if any \`name\` field is unknown.
-2. Order your ingredients in the sequence they should appear top-to-bottom in the rendered UI. The transpiler wraps your list in a vertical Column.
-3. Each ingredient may carry a \`substitutions\` object. KEYS are text-node IDs (from the \`text-nodes:\` line in the catalog above). VALUES are the new \`textContent\` strings. Only \`Text\` nodes can be substituted in this version; other components stay at their declared values.
+2. Order your ingredients in the sequence they should appear in the rendered UI. The transpiler wraps your list in a root container — by default a vertical Column. Override via the optional \`layout\` field (see below).
+3. Each ingredient may carry a \`substitutions\` object. KEYS are node IDs from the \`substitutables:\` line in the catalog above (e.g. \`"title"\`, \`"submit"\`, \`"logo"\`). VALUES are the new content strings. The transpiler routes each substitution to the right attribute based on the node's component: \`Text\` / \`Kbd\` → \`textContent\`; \`Button\` / \`Badge\` / \`Tag\` → \`text\`; \`Icon\` → \`name\`; \`Image\` → \`alt\`; \`Link\` → \`href\`. Nodes whose component is not in the substitutable list are locked at their declared values.
+
+   **ALWAYS substitute** any title, heading, button label, or badge label that the user's intent specifies. Default chunk text is generic placeholder ("Sign in to AdiaUI", "Continue", "Welcome back"); your job is to tailor it to the user's actual intent. Substituting MORE is better than substituting less — empty \`substitutions\` ships generic copy that misses the intent. Example: intent "trial-signup form for ContextEngine" → \`{"title": "Start your ContextEngine trial", "submit": "Create account"}\` not \`{}\`.
 4. If you can't satisfy the intent with the available ingredients, return \`{ "ingredients": [] }\` and a rationale explaining what's missing.
 5. Output ONLY the JSON object below, no explanation outside the JSON.
 
+LAYOUT (optional root container):
+
+The transpiler stacks your ingredients inside a single root container. The default is \`Column\` (vertical stack). For horizontal or grid arrangements set \`layout\` to one of:
+
+- \`"column"\` — vertical stack (default; omit \`layout\` for this shape). Use for: forms stacking fields, content sections stacking top-to-bottom, hero → features → footer pages.
+- \`"row"\` — horizontal stack with automatic wrapping. Use for: nav items, inline button groups, small tag clusters, 2-3 cards side-by-side.
+- \`"grid"\` — responsive grid. Use for: pricing tiers (3 cards), KPI dashboards (4 stat tiles), feature grids, image galleries, testimonial grids. Add an optional \`columns\` field with a string like \`"3"\`, \`"4"\`, or \`"auto-fill"\`; default is \`"auto-fill"\` (responsive density).
+
+When the intent reads as "side by side" / "in a row" / "horizontally", pick \`"row"\`. When it reads as "grid of N" / "tiles" / "cards in columns", pick \`"grid"\`. When in doubt, omit \`layout\` and let the default Column apply.
+
 OUTPUT SCHEMA (strict):
 
 \`\`\`json
@@ -113,11 +153,13 @@ OUTPUT SCHEMA (strict):
       "substitutions": { "<text-node-id>": "<new text>" }
     }
   ],
+  "layout": "column" | "row" | "grid",
+  "columns": "<grid columns: number string '1'..'6' or 'auto-fill'>",
   "rationale": "<one short sentence: why this arrangement>"
 }
 \`\`\`
 
-The \`substitutions\` field is optional and can be omitted or set to \`{}\`.`;
+The \`substitutions\`, \`layout\`, and \`columns\` fields are all optional.`;
 }
 
 /**
@@ -138,3 +180,15 @@ export function buildFreeFormRetryMessage(intent, invalidNames) {
 
 Note: your previous response used ${invalidNames.length === 1 ? 'an ingredient name' : 'ingredient names'} that ${invalidNames.length === 1 ? "isn't" : "aren't"} in the catalog: ${list}. Use ONLY names from the INGREDIENTS list above, exactly as shown.`;
 }
+
+/**
+ * Build a paraphrase-retry user message for an empty-plan result. Used when
+ * the LLM returned a valid plan with `ingredients: []` — the keyword
+ * extraction didn't surface a shape match. The retry nudges the LLM toward
+ * shape-based reasoning rather than verbatim vocabulary lookup. §106 (v0.5.1).
+ */
+export function buildFreeFormParaphraseRetry(intent) {
+  return `Compose a UI for: "${intent}"
+
+Note: your previous response was an empty plan. Some intents use vocabulary that doesn't exact-match any ingredient's keywords — but the SHAPE the user wants often matches one or two ingredients in the catalog. Re-read the INGREDIENTS list and identify the closest shape match (e.g. "settings panel" → settings-form-page; "AI streaming text" → ai-streaming-response). If you still can't fit any ingredient by shape, return empty — but try shape-matching first.`;
+}

package/strategies/free-form-composer/transpile.js

@@ -16,24 +16,68 @@
  * - The root `Column` enumerates the prefixed ROOT id of each ingredient
  *   as its children (defined by the first node in each chunk template).
  *
- * Substitution rules (v0.4.8 — text-only scope):
+ * Substitution rules (v0.5.0 §105 — multi-attribute scope):
  * - Substitution key = chunk-internal node ID (the same `id` field the
- *   prompt surfaces in the `text-nodes:` line per ingredient).
- * - Only nodes with `component === 'Text'` AND a `textContent` field are
- *   substitution-eligible. Other components are ignored silently.
- * - Unknown substitution keys produce a `warnings[]` entry in the result
- *   but do not fail the transpile. Future passes can promote warnings to
- *   strict errors via an option.
- *
- * Out of scope for v0.4.8:
+ *   prompt surfaces in the `substitutables:` line per ingredient).
+ * - Each substitutable component has ONE target attribute defined in
+ *   `SUBSTITUTABLE_ATTRS` below. The transpiler maps node.component →
+ *   target attribute name automatically; the substitution value lands
+ *   on that attribute regardless of whether the node currently carries
+ *   one.
+ * - Nodes whose `component` isn't in the map produce a `warnings[]`
+ *   entry; the substitution is dropped.
+ * - Unknown substitution keys (no node with that ID) produce a
+ *   `warnings[]` entry; transpile continues.
+ *
+ * The v0.4.8 §88 ship of this file restricted substitutions to
+ * Text.textContent only. The v0.5.0 §105 expansion adds Button.text,
+ * Badge.text, Tag.text, Icon.name, Image.alt, Link.href, Kbd.textContent —
+ * the 7 most common consumer-tweaked text-bearing attributes per the
+ * v0.5.0 plan §99-rev table. Non-text "structural" substitutions
+ * (swapping Card → Section, etc.) remain out of scope.
+ *
+ * Root container picker (v0.5.0 §103, auto-grouping):
+ * - Plan may carry `layout: "column" | "row" | "grid"` to override the
+ *   default `Column` root. `"row"` wraps in a Row with wrap=true (for
+ *   horizontal nav / inline-card sequences). `"grid"` wraps in a Grid
+ *   with `columns` from the plan (or `"auto-fill"` fallback) for
+ *   responsive tile / pricing-tier layouts. Missing / unknown `layout`
+ *   value falls through to `Column` — back-compat for v0.4.8 plans.
+ *
+ * Out of scope:
  * - Slot-conflict resolution (two ingredients claiming the same slot).
- *   The current stitch is sequential-stacking inside a Column; slot
+ *   The current stitch is sequential-stacking inside the root; slot
  *   conflicts cannot arise because no shared slot surface exists.
  * - Nested-composition (ingredients-inside-ingredients).
  * - Cross-chunk merge (fusing two chunks rather than stacking).
  * - Structural substitutions (swap Card → Section, etc.).
  */
 
+const VALID_LAYOUTS = new Set(['column', 'row', 'grid']);
+
+/**
+ * Maps component name → the single attribute that consumer substitutions
+ * target on that component. The set was chosen from the v0.5.0 §99-rev
+ * plan table: text-bearing primitives' "primary text attribute" + the
+ * two URL/alt-text attributes consumers tweak most often.
+ *
+ * Components NOT in this map are non-substitutable from a free-form
+ * plan: substitution keys pointing at e.g. a Card or Column node are
+ * reported as warnings.
+ *
+ * @type {Record<string, string>}
+ */
+export const SUBSTITUTABLE_ATTRS = {
+  Text: 'textContent',
+  Button: 'text',
+  Badge: 'text',
+  Tag: 'text',
+  Kbd: 'textContent',
+  Icon: 'name',
+  Image: 'alt',
+  Link: 'href',
+};
+
 /**
  * Apply text substitutions to a single chunk's template. Returns a fresh
  * cloned array with prefixed IDs + substituted textContent where keys match.
@@ -59,10 +103,11 @@ function applyIngredient(template, prefix, substitutions = {}) {
     }
     if (Object.hasOwn(substitutions, node.id)) {
       usedSubKeys.add(node.id);
-      if (node.component === 'Text' && typeof node.textContent === 'string') {
-        cloned.textContent = String(substitutions[node.id]);
+      const targetAttr = SUBSTITUTABLE_ATTRS[node.component];
+      if (targetAttr) {
+        cloned[targetAttr] = String(substitutions[node.id]);
       } else {
-        warnings.push(`substitution skipped: "${node.id}" in "${prefix}" is component=${node.component ?? '?'}, only Text supported in v0.4.8`);
+        warnings.push(`substitution skipped: "${node.id}" in "${prefix}" is component=${node.component ?? '?'}, not in SUBSTITUTABLE_ATTRS map`);
       }
     }
     return cloned;
@@ -140,12 +185,7 @@ export function transpilePlan(plan, chunkLookup) {
     return { messages: [], warnings, usedIngredients };
   }
 
-  const root = {
-    id: 'free-form-root',
-    component: 'Column',
-    gap: '6',
-    children: rootChildren,
-  };
+  const root = buildRoot(plan, rootChildren, warnings);
 
   return {
     messages: [{
@@ -158,6 +198,45 @@ export function transpilePlan(plan, chunkLookup) {
   };
 }
 
+/**
+ * Build the root container node for the transpiled plan. Reads
+ * `plan.layout` and, for grids, `plan.columns`. Defaults to Column when
+ * `layout` is missing or unknown (back-compat with v0.4.8 plans).
+ *
+ * @param {object} plan — the parsed LLM plan
+ * @param {string[]} rootChildren — prefixed root IDs from each ingredient
+ * @param {string[]} warnings — mutated; receives invalid-layout warnings
+ * @returns {object} the root A2UI node
+ */
+function buildRoot(plan, rootChildren, warnings) {
+  const requested = typeof plan?.layout === 'string' ? plan.layout.toLowerCase() : null;
+  let layout = 'column';
+  if (requested) {
+    if (VALID_LAYOUTS.has(requested)) {
+      layout = requested;
+    } else {
+      warnings.push(`unknown layout: "${plan.layout}" — falling back to Column`);
+    }
+  }
+
+  const base = {
+    id: 'free-form-root',
+    gap: '6',
+    children: rootChildren,
+  };
+
+  if (layout === 'row') {
+    return { ...base, component: 'Row', wrap: true };
+  }
+  if (layout === 'grid') {
+    const columns = typeof plan?.columns === 'string' && plan.columns.length > 0
+      ? plan.columns
+      : 'auto-fill';
+    return { ...base, component: 'Grid', columns };
+  }
+  return { ...base, component: 'Column' };
+}
+
 /**
  * Parse a raw LLM response into a plan object. The LLM is asked to emit
  * strict JSON; we accept either a bare JSON object or one wrapped in a

package/strategies/registry.js

@@ -118,13 +118,34 @@ async function generateZettelAdapter(ctx) {
   };
 }
 
+// §108 (v0.5.1): pin free-form's ingredient-picker to Haiku 4.5.
+// Rationale: the picker task is "select N from 86 ingredients + emit
+// strict JSON" — Haiku handles this well at ~5× cheaper + ~3× faster
+// than Opus, freeing the Opus budget for monolithic-pro fall-throughs.
+// User-decided pre-A/B per v0.5.1 plan question 2: "Haiku is a good
+// default."
+const FREE_FORM_MODEL = 'claude-haiku-4-5-20251001';
+
 async function generateFreeFormAdapter(ctx) {
   // Lazy-load: free-form-composer imports composition-library which
   // top-level-awaits a node:fs read. Same browser-safety story as zettel.
   const { generateFreeForm } = await import('./free-form-composer/index.js');
+
+  // Pin Haiku for the picker task even when harness model is Opus.
+  // Auto-engine + factory-chat may pass any-model llmAdapter; free-form
+  // mints its own to keep the picker cost-bounded.
+  let pickerAdapter = ctx.llmAdapter || null;
+  try {
+    const { createAdapter } = await import('../../../llm/llm-bridge.js');
+    pickerAdapter = await createAdapter({ model: FREE_FORM_MODEL });
+  } catch {
+    // Adapter mint failed (proxy down, no key) — fall back to whatever
+    // ctx provides. Strategy will emit `free-form-no-llm` if both fail.
+  }
+
   const result = await generateFreeForm({
     intent: ctx.intent,
-    llmAdapter: ctx.llmAdapter || null,
+    llmAdapter: pickerAdapter,
   });
   const isRecording = await getIsRecording();
   return {
@@ -134,14 +155,19 @@ async function generateFreeFormAdapter(ctx) {
     suggestions: [],
     strategy: result.strategy,
     engine: 'free-form',
+    // §109 (v0.5.1): usedIngredients graduates from `_debug.*` to
+    // first-class. Auto-engine + factory-chat UI both depend on it for
+    // trace labels; coupling visibility to dialog-recorder state was
+    // fragile. `rationale` joins it for the same reason — trace
+    // copy quotes the LLM's one-line rationale when present.
+    usedIngredients: result.usedIngredients || [],
+    rationale: result.rationale || null,
     _debug: isRecording() ? {
       systemPrompt: null,
       rawLLMResponse: null,
       tokens: null,
       plan: result.plan,
-      usedIngredients: result.usedIngredients,
       attempts: result.attempts,
-      rationale: result.rationale,
       warnings: result.warnings,
     } : undefined,
   };