@adia-ai/a2ui-compose 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -12,6 +12,16 @@ generator graph.
 
 _No pending changes._
 
+## [0.4.9] - 2026-05-13
+
+_No pending changes._
+
+## [0.4.8] - 2026-05-12
+
+### Fixed — `strategies/zettel/generator-adapter.js` `ensureBooted()` race (§87a, v0.4.8)
+
+The zettel composition library's lazy boot had a race condition where concurrent `ensureBooted()` calls could each kick off a separate boot promise. Under contention (multiple requests landing simultaneously at server cold-start), the composition map could be partially populated when consumers reached the synchronous getters. Fix: memoize the boot promise on first call so all subsequent callers await the same promise. Pairs with the v0.4.8 §87 honest-floor eval threshold rebaseline — without the boot race fix, the 1% rebaseline was actually undercounting due to occasional empty-map reads.
+
 ## [0.4.7] - 2026-05-12
 
 ### Changed — `strategies/monolithic/_shared.js` `getComponentCatalog()` reads canonical catalog (§72)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "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/free-form-composer/free-form-composer.test.js

@@ -0,0 +1,228 @@
+/**
+ * free-form-composer — vitest cases.
+ *
+ * Six cases per the v0.4.8 §88 spec:
+ *   1. No LLM → returns `free-form-no-llm` cleanly
+ *   2. Valid plan → composes, prefixes IDs, wraps in Column
+ *   3. Substitution applies on Text node, ignores non-Text node
+ *   4. Hallucination → retries once with feedback, then falls through
+ *   5. Parse-fail → same hallucination path
+ *   6. Empty vocabulary → returns `free-form-empty-vocab`
+ */
+import { describe, it, expect } from 'vitest';
+import { generateFreeForm } from './index.js';
+import { transpilePlan, parsePlan } from './transpile.js';
+import { buildFreeFormSystemPrompt } from './system-prompt.js';
+
+const FIXTURE_VOCAB = [
+  {
+    name: 'demo-login',
+    domain: 'auth',
+    description: 'A demo login card',
+    keywords: ['login', 'auth'],
+    template: [
+      { id: 'card', component: 'Card', children: ['title', 'submit'] },
+      { id: 'title', component: 'Text', variant: 'h1', textContent: 'Sign in' },
+      { id: 'submit', component: 'Button', text: 'Continue', variant: 'primary' },
+    ],
+  },
+  {
+    name: 'demo-signup',
+    domain: 'auth',
+    description: 'A demo signup card',
+    keywords: ['signup', 'register'],
+    template: [
+      { id: 'card', component: 'Card', children: ['title'] },
+      { id: 'title', component: 'Text', variant: 'h1', textContent: 'Create account' },
+    ],
+  },
+];
+
+describe('free-form-composer', () => {
+  it('returns free-form-no-llm when no LLM adapter is provided', async () => {
+    const result = await generateFreeForm({
+      intent: 'login form',
+      llmAdapter: null,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-no-llm');
+    expect(result.messages).toEqual([]);
+    expect(result.validation.score).toBe(0);
+  });
+
+  it('composes a plan into A2UI messages with prefixed IDs + Column root', async () => {
+    const fakeLLM = {
+      complete: async () => ({
+        content: JSON.stringify({
+          ingredients: [{ name: 'demo-login' }, { name: 'demo-signup' }],
+          rationale: 'Two-card auth flow.',
+        }),
+      }),
+    };
+    const result = await generateFreeForm({
+      intent: 'auth flow',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-composed');
+    expect(result.usedIngredients).toEqual(['demo-login', 'demo-signup']);
+    expect(result.messages).toHaveLength(1);
+    const components = result.messages[0].components;
+    const root = components[0];
+    expect(root.component).toBe('Column');
+    expect(root.children).toEqual(['demo-login__card', 'demo-signup__card']);
+    // IDs are prefixed so two ingredients with the same internal id ('card', 'title') don't collide.
+    const ids = new Set(components.map(c => c.id));
+    expect(ids.size).toBe(components.length);
+    expect(ids.has('demo-login__card')).toBe(true);
+    expect(ids.has('demo-signup__card')).toBe(true);
+    expect(ids.has('demo-login__title')).toBe(true);
+    expect(ids.has('demo-signup__title')).toBe(true);
+  });
+
+  it('applies text substitutions on Text nodes; warns on non-Text or 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)
+              missing: 'foo',          // skipped — no such id in template
+            },
+          }],
+          rationale: 'Re-skinned login card.',
+        }),
+      }),
+    };
+    const result = await generateFreeForm({
+      intent: 'login form',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-composed');
+    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(result.warnings.some(w => w.includes('missing'))).toBe(true);
+  });
+
+  it('retries once on hallucination, then falls through with free-form-hallucinated', async () => {
+    let calls = 0;
+    const fakeLLM = {
+      complete: async () => {
+        calls++;
+        return { content: JSON.stringify({ ingredients: [{ name: 'not-a-real-name' }], rationale: '...' }) };
+      },
+    };
+    const result = await generateFreeForm({
+      intent: 'login form',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-hallucinated');
+    expect(calls).toBe(2); // initial + one retry
+    expect(result.attempts).toBe(2);
+    expect(result.messages).toEqual([]);
+  });
+
+  it('treats unparseable LLM response as hallucination and retries', async () => {
+    let calls = 0;
+    const fakeLLM = {
+      complete: async () => {
+        calls++;
+        return { content: 'I think you want a login form, but I cannot output JSON.' };
+      },
+    };
+    const result = await generateFreeForm({
+      intent: 'login form',
+      llmAdapter: fakeLLM,
+      compositions: FIXTURE_VOCAB,
+    });
+    expect(result.strategy).toBe('free-form-hallucinated');
+    expect(calls).toBe(2);
+  });
+
+  it('returns free-form-empty-vocab when vocabulary is empty', async () => {
+    const fakeLLM = { complete: async () => ({ content: '{"ingredients":[]}' }) };
+    const result = await generateFreeForm({
+      intent: 'anything',
+      llmAdapter: fakeLLM,
+      compositions: [],
+    });
+    expect(result.strategy).toBe('free-form-empty-vocab');
+    expect(result.messages).toEqual([]);
+  });
+});
+
+describe('parsePlan', () => {
+  it('parses bare JSON', () => {
+    const plan = parsePlan('{"ingredients":[{"name":"x"}]}');
+    expect(plan).not.toBeNull();
+    expect(plan.ingredients).toHaveLength(1);
+  });
+
+  it('strips fenced code blocks', () => {
+    const plan = parsePlan('```json\n{"ingredients":[{"name":"x"}]}\n```');
+    expect(plan).not.toBeNull();
+    expect(plan.ingredients).toHaveLength(1);
+  });
+
+  it('extracts JSON object from prose lead-in', () => {
+    const plan = parsePlan('Sure! Here is the plan: {"ingredients":[{"name":"x"}]}. Hope that helps.');
+    expect(plan).not.toBeNull();
+    expect(plan.ingredients).toHaveLength(1);
+  });
+
+  it('returns null on garbage', () => {
+    expect(parsePlan('not a json blob')).toBeNull();
+    expect(parsePlan('{ broken json')).toBeNull();
+    expect(parsePlan(null)).toBeNull();
+  });
+
+  it('returns null when ingredients is not an array', () => {
+    expect(parsePlan('{"ingredients":"oops"}')).toBeNull();
+  });
+});
+
+describe('transpilePlan — direct unit', () => {
+  it('handles missing ingredient names with warnings, not failures', () => {
+    const lookup = new Map(FIXTURE_VOCAB.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'demo-login' }, { name: 'unknown' }, { name: 'demo-signup' }],
+    }, lookup);
+    expect(result.usedIngredients).toEqual(['demo-login', 'demo-signup']);
+    expect(result.warnings.some(w => w.includes('unknown'))).toBe(true);
+    // Still emits a Column root with the resolved ingredients.
+    expect(result.messages[0].components[0].component).toBe('Column');
+  });
+
+  it('returns empty messages when all ingredients are unknown', () => {
+    const lookup = new Map(FIXTURE_VOCAB.map(c => [c.name, c]));
+    const result = transpilePlan({
+      ingredients: [{ name: 'unknown-1' }, { name: 'unknown-2' }],
+    }, lookup);
+    expect(result.messages).toEqual([]);
+    expect(result.usedIngredients).toEqual([]);
+  });
+});
+
+describe('buildFreeFormSystemPrompt', () => {
+  it('includes ingredient names + descriptions + text-node 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('INGREDIENTS AVAILABLE');
+    expect(prompt).toContain('OUTPUT SCHEMA');
+  });
+
+  it('handles empty vocabulary without throwing', () => {
+    const prompt = buildFreeFormSystemPrompt([]);
+    expect(prompt).toContain('INGREDIENTS AVAILABLE (0)');
+  });
+});

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

@@ -0,0 +1,193 @@
+/**
+ * free-form-composer — generative composition mode (§88, v0.4.8).
+ *
+ * The third generative path between verbatim retrieval (zettel's
+ * `composition-match`) and free-hand LLM generation (`monolithic-pro`).
+ *
+ * Treats the annotated-chunk corpus as an INGREDIENT VOCABULARY. The
+ * foundation model is given the catalog (28 chunks as of cut), declares
+ * an ordered list of ingredients + optional text-only substitutions, and
+ * the transpiler stitches a net-new A2UI tree that echoes the patterns
+ * the corpus documents without copying them verbatim.
+ *
+ * Grounding rule (v0.4.6 §62, carried forward): every ingredient name is
+ * an annotated chunk that traces to a real page via `data-chunk-*` markers.
+ * The strategy enforces this by rejecting any plan whose ingredient names
+ * aren't in the live `getAllCompositions()` result.
+ *
+ * Hallucination guard: one retry with explicit feedback ("you used X
+ * which isn't an ingredient"). If the retry still hallucinates, the
+ * strategy returns an empty-messages result with strategy label
+ * `free-form-hallucinated` so the upstream registry can fall through to
+ * monolithic-pro.
+ *
+ * No LLM available: returns `strategy='free-form-no-llm'` immediately;
+ * caller falls through.
+ */
+
+import { getAllCompositions } from '../zettel/composition-library.js';
+import {
+  buildFreeFormSystemPrompt,
+  buildFreeFormUserMessage,
+  buildFreeFormRetryMessage,
+} from './system-prompt.js';
+import { transpilePlan, parsePlan } from './transpile.js';
+
+const MAX_ATTEMPTS = 2;
+
+/**
+ * Run the free-form composer for a single intent.
+ *
+ * @param {object} opts
+ * @param {string} opts.intent — user intent
+ * @param {object|null} opts.llmAdapter — LLM adapter with `.complete({messages, systemPrompt}) → {content, ...}`
+ * @param {object[]} [opts.compositions] — override vocabulary (test fixtures); defaults to live corpus
+ * @returns {Promise<{
+ *   messages: object[],
+ *   validation: { score: number, warnings?: string[] },
+ *   strategy: string,
+ *   plan: object|null,
+ *   usedIngredients: string[],
+ *   attempts: number,
+ *   warnings: string[],
+ *   rationale: string|null,
+ * }>}
+ */
+export async function generateFreeForm({ intent, llmAdapter = null, compositions = null } = {}) {
+  if (!intent || typeof intent !== 'string') {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: ['empty or invalid intent'] },
+      strategy: 'free-form-bad-input',
+      plan: null,
+      usedIngredients: [],
+      attempts: 0,
+      warnings: ['empty or invalid intent'],
+      rationale: null,
+    };
+  }
+
+  const vocab = Array.isArray(compositions) ? compositions : getAllCompositions();
+  if (vocab.length === 0) {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: ['empty vocabulary'] },
+      strategy: 'free-form-empty-vocab',
+      plan: null,
+      usedIngredients: [],
+      attempts: 0,
+      warnings: ['empty vocabulary: 0 annotated chunks available'],
+      rationale: null,
+    };
+  }
+
+  if (!llmAdapter || typeof llmAdapter.complete !== 'function') {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: ['no LLM adapter; free-form requires LLM'] },
+      strategy: 'free-form-no-llm',
+      plan: null,
+      usedIngredients: [],
+      attempts: 0,
+      warnings: ['free-form-composer requires an LLM adapter (mode=pro|thinking, not instant)'],
+      rationale: null,
+    };
+  }
+
+  const systemPrompt = buildFreeFormSystemPrompt(vocab);
+  const vocabNames = new Set(vocab.map(c => c.name));
+  const chunkLookup = new Map(vocab.map(c => [c.name, c]));
+
+  let userMessage = buildFreeFormUserMessage(intent);
+  let plan = null;
+  let invalidNames = [];
+  let attempt = 0;
+
+  for (attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    let raw;
+    try {
+      const response = await llmAdapter.complete({
+        messages: [{ role: 'user', content: userMessage }],
+        systemPrompt,
+      });
+      raw = response?.content || '';
+    } catch (err) {
+      return {
+        messages: [],
+        validation: { score: 0, warnings: [`LLM call failed: ${err?.message || err}`] },
+        strategy: 'free-form-llm-error',
+        plan: null,
+        usedIngredients: [],
+        attempts: attempt,
+        warnings: [`LLM call failed on attempt ${attempt}: ${err?.message || err}`],
+        rationale: null,
+      };
+    }
+
+    const candidate = parsePlan(raw);
+    if (!candidate) {
+      // Parse-fail counts as a hallucination — retry once.
+      invalidNames = ['<parse-fail>'];
+      userMessage = `Compose a UI for: "${intent}"
+
+Note: your previous response wasn't valid JSON. Output ONLY the JSON object — no prose, no fenced code block markers around it.`;
+      continue;
+    }
+
+    invalidNames = candidate.ingredients
+      .filter(ing => !ing || typeof ing.name !== 'string' || !vocabNames.has(ing.name))
+      .map(ing => ing?.name ?? '<missing-name>');
+
+    if (invalidNames.length === 0) {
+      plan = candidate;
+      break;
+    }
+
+    // Retry with explicit hallucination feedback.
+    userMessage = buildFreeFormRetryMessage(intent, invalidNames);
+  }
+
+  if (!plan) {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: [`hallucination guard tripped after ${MAX_ATTEMPTS} attempts; invalid: ${invalidNames.join(', ')}`] },
+      strategy: 'free-form-hallucinated',
+      plan: null,
+      usedIngredients: [],
+      attempts: MAX_ATTEMPTS,
+      warnings: [`exhausted ${MAX_ATTEMPTS} attempts; final invalid names: ${invalidNames.join(', ')}`],
+      rationale: null,
+    };
+  }
+
+  const { messages, warnings, usedIngredients } = transpilePlan(plan, chunkLookup);
+
+  if (messages.length === 0) {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: warnings.concat(['transpile produced no messages']) },
+      strategy: 'free-form-empty-plan',
+      plan,
+      usedIngredients,
+      attempts: attempt,
+      warnings,
+      rationale: plan.rationale || null,
+    };
+  }
+
+  // Score reflects "we successfully composed N ingredients without
+  // hallucination". Validator-level scoring is upstream's responsibility.
+  // 85 chosen to match zettel's `composition-match` avgScore baseline.
+  const score = 85;
+
+  return {
+    messages,
+    validation: { score, warnings },
+    strategy: 'free-form-composed',
+    plan,
+    usedIngredients,
+    attempts: attempt,
+    warnings,
+    rationale: plan.rationale || null,
+  };
+}

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

@@ -0,0 +1,140 @@
+/**
+ * system-prompt.js — builds the system prompt for free-form-composer.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * current corpus state without explicit cache invalidation.
+ */
+
+const MAX_DESCRIPTION_LEN = 140;
+const MAX_TEXT_PREVIEW = 60;
+
+/**
+ * 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).
+ *
+ * @param {object[]} template — flat A2UI node list
+ * @returns {Array<{id: string, preview: string}>}
+ */
+function extractTextNodes(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 });
+  }
+  return nodes;
+}
+
+/**
+ * Render a single ingredient as a prompt line. Format:
+ *
+ *   - <name> (<domain>): <description (truncated)>
+ *     keywords: a, b, c
+ *     text-nodes: id="..." current="...", id="..." current="..."
+ *
+ * Text-nodes line is omitted when the chunk has zero Text nodes.
+ */
+function renderIngredient(c) {
+  const desc = (c.description || '').slice(0, MAX_DESCRIPTION_LEN);
+  const lines = [`- ${c.name} (${c.domain || 'general'}): ${desc}`];
+  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}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build the system prompt. Caller passes the live `getAllCompositions()`
+ * result; this function doesn't import composition-library directly so the
+ * strategy entry point can pass test fixtures in unit tests.
+ *
+ * @param {object[]} compositions — output of `getAllCompositions()`
+ * @returns {string}
+ */
+export function buildFreeFormSystemPrompt(compositions) {
+  const ingredients = (compositions || []).slice().sort((a, b) => {
+    const da = a.domain || 'z'; const db = b.domain || 'z';
+    if (da !== db) return da < db ? -1 : 1;
+    return a.name < b.name ? -1 : 1;
+  });
+
+  const catalog = ingredients.map(renderIngredient).join('\n\n');
+  const ingredientNames = ingredients.map(c => c.name).join(', ');
+
+  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.
+
+INGREDIENTS AVAILABLE (${ingredients.length}):
+
+${catalog}
+
+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.
+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.
+
+OUTPUT SCHEMA (strict):
+
+\`\`\`json
+{
+  "ingredients": [
+    {
+      "name": "<one of: ${ingredientNames.length > 200 ? ingredientNames.slice(0, 200) + '… (see list above)' : ingredientNames}>",
+      "substitutions": { "<text-node-id>": "<new text>" }
+    }
+  ],
+  "rationale": "<one short sentence: why this arrangement>"
+}
+\`\`\`
+
+The \`substitutions\` field is optional and can be omitted or set to \`{}\`.`;
+}
+
+/**
+ * Build the user message for an intent. Kept separate from system prompt
+ * so future iteration prompts can extend it (e.g. with prior-canvas diffs).
+ */
+export function buildFreeFormUserMessage(intent) {
+  return `Compose a UI for: "${intent}"`;
+}
+
+/**
+ * Build a retry user message that surfaces invalid ingredient names from a
+ * prior attempt. Called by the strategy entry point on hallucination.
+ */
+export function buildFreeFormRetryMessage(intent, invalidNames) {
+  const list = invalidNames.slice(0, 5).join(', ');
+  return `Compose a UI for: "${intent}"
+
+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.`;
+}

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

@@ -0,0 +1,195 @@
+/**
+ * transpile.js — turn a free-form composer plan into A2UI messages.
+ *
+ * Input: a `plan` object from the LLM in the shape:
+ *
+ *   { ingredients: [{ name: string, substitutions?: object }], rationale: string }
+ *
+ * Output: a single `updateComponents` message with a `Column` root that
+ * wraps every ingredient's template in sequence.
+ *
+ * Stitch design:
+ * - Each ingredient's nodes get prefixed IDs (`<ingredientName>__<originalId>`)
+ *   so concatenating two ingredients with overlapping IDs doesn't collide.
+ *   Children references inside each chunk are rewritten to point at the
+ *   prefixed IDs.
+ * - 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 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:
+ * - Slot-conflict resolution (two ingredients claiming the same slot).
+ *   The current stitch is sequential-stacking inside a Column; 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.).
+ */
+
+/**
+ * Apply text substitutions to a single chunk's template. Returns a fresh
+ * cloned array with prefixed IDs + substituted textContent where keys match.
+ *
+ * @param {object[]} template — original chunk template
+ * @param {string} prefix — ingredient name, used for ID namespacing
+ * @param {object} substitutions — { [innerNodeId]: newText }
+ * @returns {{ nodes: object[], rootId: string, warnings: string[] }}
+ */
+function applyIngredient(template, prefix, substitutions = {}) {
+  if (!Array.isArray(template) || template.length === 0) {
+    return { nodes: [], rootId: null, warnings: [`empty template for ingredient "${prefix}"`] };
+  }
+  const warnings = [];
+  const subKeys = Object.keys(substitutions || {});
+  const usedSubKeys = new Set();
+  const prefixId = (id) => `${prefix}__${id}`;
+
+  const nodes = template.map((node) => {
+    const cloned = { ...node, id: prefixId(node.id) };
+    if (Array.isArray(node.children)) {
+      cloned.children = node.children.map(prefixId);
+    }
+    if (Object.hasOwn(substitutions, node.id)) {
+      usedSubKeys.add(node.id);
+      if (node.component === 'Text' && typeof node.textContent === 'string') {
+        cloned.textContent = String(substitutions[node.id]);
+      } else {
+        warnings.push(`substitution skipped: "${node.id}" in "${prefix}" is component=${node.component ?? '?'}, only Text supported in v0.4.8`);
+      }
+    }
+    return cloned;
+  });
+
+  for (const k of subKeys) {
+    if (!usedSubKeys.has(k)) {
+      warnings.push(`unknown substitution key: "${k}" in "${prefix}" (no node with that id)`);
+    }
+  }
+
+  return {
+    nodes,
+    rootId: prefixId(template[0].id),
+    warnings,
+  };
+}
+
+/**
+ * Transpile a plan into A2UI messages. Returns:
+ *
+ *   { messages: [{type:'updateComponents', components: [...]}],
+ *     warnings: string[],
+ *     usedIngredients: string[] }
+ *
+ * If `ingredients` is empty after resolution, returns
+ * `{ messages: [], warnings: [...], usedIngredients: [] }` — caller decides
+ * whether that's a fallthrough or an error.
+ *
+ * @param {{ ingredients: Array<{name: string, substitutions?: object}>, rationale?: string }} plan
+ * @param {Map<string, object> | Function} chunkLookup — Map or function
+ *   `(name) => composition | undefined`. The strategy entry point typically
+ *   passes a Map built from `getAllCompositions()` for O(1) lookups.
+ * @returns {{ messages: object[], warnings: string[], usedIngredients: string[] }}
+ */
+export function transpilePlan(plan, chunkLookup) {
+  const warnings = [];
+  const usedIngredients = [];
+
+  if (!plan || !Array.isArray(plan.ingredients) || plan.ingredients.length === 0) {
+    return { messages: [], warnings: ['plan has no ingredients'], usedIngredients };
+  }
+
+  const lookup = typeof chunkLookup === 'function'
+    ? chunkLookup
+    : (name) => chunkLookup.get(name);
+
+  const flatComponents = [];
+  const rootChildren = [];
+
+  for (const ing of plan.ingredients) {
+    if (!ing || typeof ing.name !== 'string') {
+      warnings.push(`malformed ingredient entry: ${JSON.stringify(ing)}`);
+      continue;
+    }
+    const chunk = lookup(ing.name);
+    if (!chunk) {
+      warnings.push(`ingredient not found in vocabulary: "${ing.name}"`);
+      continue;
+    }
+    const { nodes, rootId, warnings: ingWarnings } = applyIngredient(
+      chunk.template,
+      ing.name,
+      ing.substitutions || {}
+    );
+    warnings.push(...ingWarnings);
+    if (rootId) {
+      flatComponents.push(...nodes);
+      rootChildren.push(rootId);
+      usedIngredients.push(ing.name);
+    }
+  }
+
+  if (rootChildren.length === 0) {
+    return { messages: [], warnings, usedIngredients };
+  }
+
+  const root = {
+    id: 'free-form-root',
+    component: 'Column',
+    gap: '6',
+    children: rootChildren,
+  };
+
+  return {
+    messages: [{
+      type: 'updateComponents',
+      surfaceId: 'main',
+      components: [root, ...flatComponents],
+    }],
+    warnings,
+    usedIngredients,
+  };
+}
+
+/**
+ * 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
+ * fenced code block (the most common drift mode).
+ *
+ * Returns `null` if parsing fails — caller treats that as a hallucination
+ * and retries (or falls through).
+ */
+export function parsePlan(rawContent) {
+  if (typeof rawContent !== 'string') return null;
+  let text = rawContent.trim();
+
+  // Strip fenced code block if present.
+  const fenceMatch = text.match(/^```(?:json)?\s*([\s\S]*?)```\s*$/i);
+  if (fenceMatch) text = fenceMatch[1].trim();
+
+  // If the response starts with explanation prose, try to find the first { ... } block.
+  if (!text.startsWith('{')) {
+    const firstBrace = text.indexOf('{');
+    const lastBrace = text.lastIndexOf('}');
+    if (firstBrace === -1 || lastBrace <= firstBrace) return null;
+    text = text.slice(firstBrace, lastBrace + 1);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== 'object') return null;
+  if (!Array.isArray(parsed.ingredients)) return null;
+  return parsed;
+}

package/strategies/registry.js

@@ -118,6 +118,35 @@ async function generateZettelAdapter(ctx) {
   };
 }
 
+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');
+  const result = await generateFreeForm({
+    intent: ctx.intent,
+    llmAdapter: ctx.llmAdapter || null,
+  });
+  const isRecording = await getIsRecording();
+  return {
+    executionId: ctx.executionId,
+    messages: result.messages,
+    validation: result.validation,
+    suggestions: [],
+    strategy: result.strategy,
+    engine: 'free-form',
+    _debug: isRecording() ? {
+      systemPrompt: null,
+      rawLLMResponse: null,
+      tokens: null,
+      plan: result.plan,
+      usedIngredients: result.usedIngredients,
+      attempts: result.attempts,
+      rationale: result.rationale,
+      warnings: result.warnings,
+    } : undefined,
+  };
+}
+
 async function generateChunkZettelAdapter(ctx) {
   const { composeFromIntent } = await import('./zettel/chunk-synthesizer.js');
   const result = await composeFromIntent({
@@ -151,6 +180,7 @@ export const ENGINES = {
   'monolithic-thinking': generateThinkingAdapter,
   'zettel':              generateZettelAdapter,
   'chunk-zettel':        generateChunkZettelAdapter,
+  'free-form':           generateFreeFormAdapter,
 };
 
 /**
@@ -175,7 +205,7 @@ export const ENGINES = {
  *   });
  *   generateUI({ engine: 'my-hybrid', intent: '...' });
  */
-const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel', 'chunk-zettel']);
+const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel', 'chunk-zettel', 'free-form']);
 
 export function registerEngine(name, generateFn) {
   if (typeof name !== 'string' || !name.length) {

package/strategies/zettel/generator-adapter.js

@@ -19,7 +19,6 @@
  *   - synthesis-failed           — LLM tried and failed validation
  */
 import {
-  loadAll,
   getComposition,
   searchAll,
 } from './composition-library.js';
@@ -33,25 +32,17 @@ import {
 import { autoReport } from './issue-reporter.js';
 import { validateSchema } from '../../../validator/validator.js';
 
-let booted = false;
-function ensureBooted() {
-  if (!booted) {
-    loadAll();
-    booted = true;
-  }
-}
-
-// NOTE on cache invalidation: `loadAll()` itself reloads fragments + compositions
-// from disk every time it's called — `fragments.clear()` + `compositions.clear()`
-// at the top, then re-walk. The CACHING happens here at the call-site: we set
-// `booted = true` after the first load and never reload for the lifetime of
-// this process. Trade-offs:
-//   - GOOD for long-running MCP: zero corpus-load cost on subsequent requests.
-//   - BAD for tests / hot-reload: a fresh fragment file isn't visible until
-//     the process restarts.
-// To force a reload (e.g. in a test that just wrote a new fragment file),
-// call `loadAll()` directly — it's idempotent. The `booted` flag here is a
-// process-singleton optimization, not a correctness invariant.
+// Composition library auto-loads at module import time via top-level `await
+// loadAll()` in composition-library.js (§72 dual-mode loader, commit
+// `76dbcff2`). The previous `ensureBooted()` here called `loadAll()` WITHOUT
+// `await`, which after §72 made it async — clearing the compositions map +
+// racing the synchronous `searchAll` below. Symptom (caught in §87):
+// eval:diff zettel coverage dropped 5% → 1% because the race-winner pattern
+// emitted composition-match only for the intent whose `searchAll` happened
+// to fire AFTER the async load resolved.
+//
+// Fix: rely entirely on the top-level await. Tests that want a forced reload
+// can call `loadAll()` directly with `await` (it's idempotent).
 
 // Retrieval score threshold — above this we trust the match and emit verbatim;
 // below, fall through to LLM synthesis (creative composition from fragments).
@@ -81,8 +72,6 @@ function toUpdateComponentsMessages(template) {
 }
 
 export async function generateZettel({ intent, mode = 'instant', llmAdapter = null, sessionId = null } = {}) {
-  ensureBooted();
-
   // ── Session-aware iteration (turn > 1) ──
   // If we have prior turns AND an LLM, the user is almost certainly modifying
   // the existing canvas — NEVER pick a fresh retrieved composition. Go straight