@adia-ai/a2ui-compose 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -12,6 +12,39 @@ generator graph.
 
 _No pending changes._
 
+## [0.4.5] - 2026-05-12
+
+### Changed — GenUI overhaul prompt-engineering (§56, v0.4.5)
+
+- **`strategies/monolithic/_shared.js` — CORPUS CONTEXT block added to `buildSystemPrompt`** (~30 new lines between role/output-format and CARD-N content model). Surgical insertion explaining the §36-§51 retrieval-augmented pipeline:
+  - Pipeline searches PATTERNS / COMPOSITIONS first (full-canvas A2UI templates: login-form, pricing-tiers, dashboard-admin-page)
+  - Pipeline also searches ANNOTATED CHUNKS (real production HTML with `metadata.{domain, keywords, description}`)
+  - When matched, `MATCHED PATTERN` / `STRUCTURAL REFERENCE` blocks carry the actual reference
+  - Only AVAILABLE COMPONENTS are usable — anything else is a hallucination
+
+  Cost: ~150 tokens per request. Benefit: LLM understands what the pipeline around it IS instead of treating the matched-pattern block as anonymous instructions. Existing rules unchanged; no removed lines.
+
+- **`strategies/monolithic/generate-pro.js` — STRUCTURAL REFERENCE prose enriched.** Prior copy: "a real production block from the codebase matched this intent." New copy: "this chunk was retrieved from the AdiaUI training corpus (annotated production HTML, harvested from real app pages). It matched your intent on keyword/domain ranking." Threads chunk `metadata.domain`, `metadata.description`, `metadata.keywords` into the prompt when present. Reframes "do not copy the HTML" as "the chunk represents the SHAPE the user wants; instantiate it with their content" — more actionable framing.
+
+See root [CHANGELOG.md `[Unreleased]`](../../../CHANGELOG.md) for the v0.4.5 overhaul arc + apps/genui/CHANGELOG.md `[Unreleased]` for the per-§ rollup.
+
+## [0.4.4] - 2026-05-12
+
+### Changed
+
+- **`strategies/zettel/fragment-library.js` → `composition-library.js` rename (§38).** Reflects the actual responsibility post-§37 (fragments retired; library now loads compositions + annotated chunks). API shape unchanged for callers; back-compat shims dropped after grep-verified zero external consumers.
+- **`strategies/zettel/composer.js` simplified (§37).** `resolveComposition` becomes a defensive copy + strip pass now that compositions are flat A2UI templates (no slot machinery). `templateToMessages` preserved for callers.
+- **`strategies/zettel/composition-library.js` — read annotated chunks alongside hand-authored compositions (§41).** `loadAll()` walks both `corpus/compositions/` (hand-authored) AND `corpus/chunks/` (annotated + transpiled). Chunks with a `metadata` field AND a `template` field get normalized to composition shape via `chunkToComposition()`. Name collisions: hand-authored wins with a loud warn. Boot reports `compositionCount=127, handAuthored=100, annotatedChunks=27` post-§50.
+- **`strategies/zettel/synthesizer.js` retired as throwing stub (§37).** Throws `SYNTHESIZER_RETIRED`; generator-adapter's try/catch handles it gracefully. Deferred follow-up: chunk-based synthesizer for zettel iteration.
+- **`compose/transpiler/transpiler-maps.js` — `<a>` → `Link` (was: `Button + variant=ghost`) (§47).** button.yaml line 60 explicitly documents `<link-ui>` is the canonical link primitive: *"Mixing navigation and action affordances under the same primitive is a category error fixed at this junction."* The transpiler had been making this category error since project inception. Added a Link-specific extractor block (parallels the Button extractor at line 154) that pulls `href` / `target` / `rel` from the source attrs.
+
+### Fixed
+
+- **`compose/strategies/monolithic/generate-pro.js` + companion `_shared/fragment-expander.js` — fragment machinery removed (§37).** Fragments retired; 85 compositions inlined with previously-referenced fragment content. Expander deleted; its caller's try/catch in `generator-adapter.js` handles the absence gracefully.
+- **MCP server `mcp/server.js` (§37).** Removed `get_fragment` tool, simplified `zettel_stats`, updated imports + boot logs + engine description to reflect the post-fragment world.
+
+See root [CHANGELOG.md `[Unreleased]`](../../../CHANGELOG.md) for the cross-cutting arc narrative + [docs/journal/2026/05/2026-05-12.md](../../../docs/journal/2026/05/2026-05-12.md) §§ 37 / 38 / 41 / 47 for per-§ details.
+
 ## [0.4.3] - 2026-05-11
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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/_shared/chunk-loader.js

@@ -0,0 +1,208 @@
+/**
+ * Dual-environment chunk loader — Node + browser.
+ *
+ * Mirrors the pattern in packages/a2ui/retrieval/pattern-library.js so the
+ * gen-UI training chunks at packages/a2ui/corpus/chunks/*.json are reachable
+ * from BOTH server-side engines (monolithic-pro via /api/generate's Node
+ * process) AND browser-side engines (monolithic-pro called directly from
+ * gen-ui playground's IIFE).
+ *
+ * The existing packages/a2ui/corpus/scripts/chunk-library.js is Node-only
+ * (uses node:fs / readdirSync). This module exists so monolithic-pro can
+ * search + fetch chunks WITHOUT pulling node:fs into the browser bundle.
+ *
+ * Surface:
+ *   - searchChunks(query, { kind, limit }): keyword-ranked chunk matches
+ *   - getChunk(name): full chunk record by name
+ *
+ * Both are async because the browser path uses dynamic imports.
+ */
+
+const IS_NODE =
+  typeof process !== 'undefined' &&
+  typeof process.versions?.node === 'string';
+
+// ── State ──────────────────────────────────────────────────────────
+let _state = null;       // { chunks: Map<name, record>, byKind: Map<kind, Set<name>> }
+let _loadPromise = null;
+
+// ── Browser glob ───────────────────────────────────────────────────
+// Vite resolves this at build time; in Node the variable is unused.
+let _globModules = null;
+if (!IS_NODE) {
+  try {
+    _globModules = import.meta.glob('../../../corpus/chunks/*.json', {
+      query: '?raw',
+      import: 'default',
+    });
+  } catch {
+    // Not in a Vite context — fall back to empty corpus
+  }
+}
+
+// ── Public API ─────────────────────────────────────────────────────
+async function _load() {
+  if (_state) return _state;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = (async () => {
+    if (IS_NODE) {
+      _state = await _loadNode();
+    } else {
+      _state = await _loadBrowser();
+    }
+    return _state;
+  })();
+  return _loadPromise;
+}
+
+async function _loadNode() {
+  const fs = await import(/* @vite-ignore */ 'node:fs/promises');
+  const path = await import(/* @vite-ignore */ 'node:path');
+  const url = await import(/* @vite-ignore */ 'node:url');
+
+  const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+  const chunksDir = path.resolve(__dirname, '..', '..', '..', 'corpus', 'chunks');
+
+  const chunks = new Map();
+  const byKind = new Map();
+  let entries;
+  try {
+    entries = await fs.readdir(chunksDir);
+  } catch {
+    return { chunks, byKind };
+  }
+  for (const file of entries) {
+    if (file === '_index.json' || !file.endsWith('.json')) continue;
+    try {
+      const raw = await fs.readFile(path.join(chunksDir, file), 'utf8');
+      const rec = JSON.parse(raw);
+      if (!rec?.name) continue;
+      chunks.set(rec.name, rec);
+      const kind = rec.kind || 'block';
+      if (!byKind.has(kind)) byKind.set(kind, new Set());
+      byKind.get(kind).add(rec.name);
+    } catch {
+      // Skip malformed chunks rather than fail the whole load
+    }
+  }
+  return { chunks, byKind };
+}
+
+async function _loadBrowser() {
+  const chunks = new Map();
+  const byKind = new Map();
+  if (!_globModules) return { chunks, byKind };
+
+  await Promise.all(
+    Object.entries(_globModules).map(async ([path, loader]) => {
+      if (path.endsWith('/_index.json')) return;
+      try {
+        const raw = await loader();
+        const rec = JSON.parse(raw);
+        if (!rec?.name) return;
+        chunks.set(rec.name, rec);
+        const kind = rec.kind || 'block';
+        if (!byKind.has(kind)) byKind.set(kind, new Set());
+        byKind.get(kind).add(rec.name);
+      } catch {
+        // Skip malformed
+      }
+    })
+  );
+
+  return { chunks, byKind };
+}
+
+/**
+ * Keyword-rank chunks against a query. Mirrors the scoring shape of
+ * corpus/scripts/chunk-library.js so behavior is consistent regardless
+ * of which loader was used.
+ *
+ * Scoring (per chunk):
+ *   +3  query word in name (exact part match)
+ *   +2  query word in primary tag
+ *   +1  query word in nested chunk name
+ *   +1  query word in source page path
+ *
+ * @param {string} query   — user intent
+ * @param {object} [opts]  — { kind?: 'block'|'page'|'panel', limit?: number }
+ * @returns {Promise<Array<{ name, score, kind, primary, record }>>}
+ */
+export async function searchChunks(query, { kind, limit = 20 } = {}) {
+  if (!query || typeof query !== 'string') return [];
+  const { chunks } = await _load();
+  if (!chunks.size) return [];
+
+  const words = query.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  if (!words.length) return [];
+
+  const candidates = [];
+  for (const [name, rec] of chunks) {
+    if (kind && rec.kind !== kind) continue;
+    let score = 0;
+    const nameLow = name.toLowerCase();
+    const primary = (rec.primary || '').toLowerCase();
+    const source = (rec.source || rec.page || '').toLowerCase();
+    const nested = (rec.nested || []).map((n) => n.toLowerCase());
+
+    for (const w of words) {
+      if (nameLow.includes(w)) score += 3;
+      if (primary && primary.includes(w)) score += 2;
+      for (const n of nested) {
+        if (n.includes(w)) {
+          score += 1;
+          break;
+        }
+      }
+      if (source && source.includes(w)) score += 1;
+    }
+    if (score > 0) {
+      candidates.push({ name, score, kind: rec.kind, primary: rec.primary, record: rec });
+    }
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates.slice(0, limit);
+}
+
+/**
+ * Fetch a chunk record by name.
+ * @param {string} name
+ * @returns {Promise<object|null>}
+ */
+export async function getChunk(name) {
+  if (!name) return null;
+  const { chunks } = await _load();
+  return chunks.get(name) || null;
+}
+
+/**
+ * Recursively expand a chunk's nested-chunk references into a flat array
+ * of chunk records. Useful for materializing the "full structural context"
+ * of a top-level chunk into a single prompt-injection payload.
+ *
+ * Cycle-safe: tracks visited names. Depth-limited to prevent runaway.
+ *
+ * @param {string|object} nameOrRecord
+ * @param {object} [opts] — { maxDepth?: 4 }
+ * @returns {Promise<Array<object>>} — flat list of resolved chunk records, root first
+ */
+export async function expandChunkGraph(nameOrRecord, { maxDepth = 4 } = {}) {
+  const visited = new Set();
+  const out = [];
+
+  async function walk(item, depth) {
+    if (depth > maxDepth) return;
+    const rec = typeof item === 'string' ? await getChunk(item) : item;
+    if (!rec || visited.has(rec.name)) return;
+    visited.add(rec.name);
+    out.push(rec);
+
+    for (const childName of rec.nested || []) {
+      await walk(childName, depth + 1);
+    }
+  }
+
+  await walk(nameOrRecord, 0);
+  return out;
+}

package/strategies/_shared/chunk-loader.test.js

@@ -0,0 +1,80 @@
+/**
+ * chunk-loader.js — Node-side tests.
+ *
+ * Verifies that:
+ *   1. The dual-environment loader correctly loads chunks from the
+ *      corpus on the Node path.
+ *   2. searchChunks ranks expected chunks for known intents (the
+ *      ground-truth case from the user's signup-form screenshot).
+ *   3. expandChunkGraph traverses the `nested:` graph correctly with
+ *      cycle safety + depth capping.
+ */
+import { describe, it, expect } from 'vitest';
+import { searchChunks, getChunk, expandChunkGraph } from './chunk-loader.js';
+
+describe('chunk-loader / Node path', () => {
+  it('searchChunks returns top-ranked matches for a sign-in query', async () => {
+    const hits = await searchChunks('sign in with email', { limit: 5 });
+    expect(hits.length).toBeGreaterThan(0);
+    // auth-signin-card-email should be the top match — it's the canonical
+    // signin block in the corpus. If this assertion ever flips, look at
+    // chunk-loader's scoring weights or the corpus harvest.
+    expect(hits[0].name).toBe('auth-signin-card-email');
+    expect(hits[0].score).toBeGreaterThanOrEqual(5);
+  });
+
+  it('getChunk returns the full record by name', async () => {
+    const rec = await getChunk('auth-signin-card-email');
+    expect(rec).not.toBeNull();
+    expect(rec.name).toBe('auth-signin-card-email');
+    expect(rec.kind).toBe('block');
+    expect(rec.primary).toBe('card-ui');
+    expect(Array.isArray(rec.nested)).toBe(true);
+    expect(rec.nested).toContain('auth-card-header');
+  });
+
+  it('getChunk returns null for unknown names', async () => {
+    const rec = await getChunk('this-chunk-does-not-exist');
+    expect(rec).toBeNull();
+  });
+
+  it('expandChunkGraph traverses nested refs (root first, breadth-ish)', async () => {
+    const graph = await expandChunkGraph('auth-signin-card-email', { maxDepth: 3 });
+    // Root should be first
+    expect(graph[0].name).toBe('auth-signin-card-email');
+    // Nested chunks should appear in the output
+    const names = graph.map((g) => g.name);
+    expect(names).toContain('auth-card-header');
+    expect(names).toContain('auth-card-content');
+    expect(names).toContain('auth-email-entry');
+    expect(names).toContain('auth-social-auths');
+  });
+
+  it('expandChunkGraph respects maxDepth', async () => {
+    const shallow = await expandChunkGraph('auth-signin-card-email', { maxDepth: 0 });
+    expect(shallow.length).toBe(1); // root only
+    expect(shallow[0].name).toBe('auth-signin-card-email');
+  });
+
+  it('expandChunkGraph deduplicates revisits (cycle safety)', async () => {
+    const graph = await expandChunkGraph('auth-signin-card-email', { maxDepth: 5 });
+    const names = graph.map((g) => g.name);
+    const unique = new Set(names);
+    // No duplicates — visited set should catch any revisits even on
+    // cyclic graphs.
+    expect(names.length).toBe(unique.size);
+  });
+
+  it('searchChunks filters by kind when requested', async () => {
+    const pageHits = await searchChunks('admin dashboard', { kind: 'page', limit: 5 });
+    for (const h of pageHits) {
+      expect(h.kind).toBe('page');
+    }
+  });
+
+  it('searchChunks returns empty array for empty / non-string queries', async () => {
+    expect(await searchChunks('')).toEqual([]);
+    expect(await searchChunks(null)).toEqual([]);
+    expect(await searchChunks(undefined)).toEqual([]);
+  });
+});

package/strategies/monolithic/_shared.js

@@ -51,6 +51,32 @@ Output format: [{ "type": "updateComponents", "surfaceId": "default", "component
 Each component: { "id": "<unique>", "component": "<Type>", "children": ["<childId>", ...], ...props }
 The root must have id "root". Use short, descriptive IDs (e.g., "hdr", "email-field", "submit-btn").`);
 
+  // ── Corpus context (§56, v0.4.5) ──
+  // Tells the LLM how the system surrounding it is wired so it doesn't
+  // hallucinate component names and so it understands what MATCHED PATTERN /
+  // STRUCTURAL REFERENCE blocks actually ARE. Keep this section tight — every
+  // token costs latency + money.
+  parts.push(`CORPUS CONTEXT (the system around you):
+
+You are part of a retrieval-augmented pipeline. Before this prompt was built,
+the pipeline searched two corpora for matches to the user's intent:
+
+1. PATTERNS / COMPOSITIONS — full-canvas A2UI templates curated for the
+   AdiaUI design system. Examples: login-form, pricing-tiers,
+   dashboard-admin-page. When a strong match exists, you'll see a
+   "MATCHED PATTERN" block below with the canonical template.
+
+2. ANNOTATED CHUNKS — real production HTML blocks harvested from the AdiaUI
+   apps (auth flows, dashboards, error pages, etc.) with metadata
+   (domain, keywords, description). When a strong chunk match exists,
+   you'll see a "STRUCTURAL REFERENCE" block with the production HTML.
+   Match its component palette + information density, but translate to
+   A2UI components — do not copy raw HTML.
+
+Both corpora use ONLY components from the AVAILABLE COMPONENTS list further
+down. If you would invent a component name not in that list, you're
+hallucinating — use the closest canonical name instead.`);
+
   // ── Card-N content model (critical for quality) ──
   parts.push(`CARD-N CONTENT MODEL (mandatory for any card surface):
 - Card > Header: for title/description. Use Text children with heading variants (h3, h4).

package/strategies/monolithic/generate-pro.js

@@ -14,6 +14,7 @@ import { isConversational } from '../../../retrieval/intent/intent-gate.js';
 import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
 import { store, engine } from '../../core/state.js';
 import { isRecording } from '../../../retrieval/feedback/dialog-recorder.js';
+import { searchChunks, expandChunkGraph } from '../_shared/chunk-loader.js';
 import {
   buildSystemPrompt,
   buildChatMessages,
@@ -94,10 +95,43 @@ export async function generatePro({ intent, executionId, storeId, llmAdapter, an
     confidence: 0.85,
   });
 
-  // ── Stage 3: Plan — search for best pattern ──
+  // ── Stage 3: Plan — search for best pattern + best chunk ──
   const patterns = searchBlocks(searchQuery, { domain: domain.domain });
   const bestPattern = patterns[0];
 
+  // ── Parallel chunk retrieval (training-corpus path) ──
+  // The chunks corpus at packages/a2ui/corpus/chunks/*.json captures real
+  // page-shape blocks harvested from working apps (auth/sign-in,
+  // settings pages, dashboards, etc.). When a query strongly matches a
+  // chunk, we inject the chunk's HTML as a STRUCTURAL REFERENCE into the
+  // adapt prompt — so the LLM has the canonical shape, not just a
+  // description of it. This closes the gap where monolithic-pro was
+  // describing chunks (via the score-card's pattern-match telemetry) but
+  // never actually using them in generation.
+  //
+  // Threshold rationale: searchChunks's keyword-score scale is the same
+  // family as the existing STRONG_RETRIEVAL_SCORE=8 in zettel's chunk
+  // synthesizer. We use a slightly lower threshold (5) for monolithic
+  // because the chunk is REFERENCE, not authoritative — the LLM still
+  // adapts, so we'd rather over-inject and let the LLM judge relevance.
+  let chunkMatch = null;
+  let chunkRefHtml = null;
+  try {
+    const chunkHits = await searchChunks(searchQuery, { limit: 1 });
+    if (chunkHits.length && chunkHits[0].score >= 5) {
+      chunkMatch = chunkHits[0];
+      // Expand the chunk's nested refs so the LLM sees the complete
+      // structural context, not just the outer shell. Depth-capped to
+      // protect against the recursive nested chain blowing token budget.
+      const graph = await expandChunkGraph(chunkMatch.record, { maxDepth: 3 });
+      chunkRefHtml = graph
+        .map((g) => `<!-- chunk: ${g.name} (${g.kind}/${g.primary}) -->\n${g.html || ''}`)
+        .join('\n\n');
+    }
+  } catch {
+    // Chunk loader is best-effort — never block generation on its failures
+  }
+
   // ── Compositional reasoning: decompose multi-section intents ──
   // ALWAYS attempt decomposition for compound intents — even when a single
   // best pattern matches.  This lets the LLM receive fragment patterns for
@@ -128,10 +162,11 @@ export async function generatePro({ intent, executionId, storeId, llmAdapter, an
   const hasFragments = fragmentPatterns.length >= 2;
   engine.submitStage(execId, 'plan', {
     strategy: bestPattern?.template ? (hasFragments ? 'adapt-with-fragments' : 'adapt-pattern') : hasFragments ? 'compose-fragments' : 'generate-fresh',
-    patternName: bestPattern?.name ?? null,
+    patternName: bestPattern?.name ?? (chunkMatch?.name ?? null),
+    chunkRef: chunkMatch ? { name: chunkMatch.name, score: chunkMatch.score, kind: chunkMatch.kind, primary: chunkMatch.primary } : null,
     fragments: hasFragments ? fragmentPatterns.map(f => f.pattern.name) : undefined,
     layout: hasFragments ? decomposition?.layout : undefined,
-    confidence: bestPattern?.template ? 0.9 : hasFragments ? 0.85 : 0.7,
+    confidence: bestPattern?.template ? 0.9 : hasFragments ? 0.85 : chunkMatch ? 0.8 : 0.7,
   });
 
   // ── Stage 4: Generate ──
@@ -171,19 +206,52 @@ export async function generatePro({ intent, executionId, storeId, llmAdapter, an
   // when the recorder actually persists them to disk.
   let lastRawResponse = null;
   let lastTokens = null;
+
+  // Pattern templates are pre-inlined as of the 2026-05-12 fragment
+  // retirement (§37) — compositions/ no longer carry $fragment refs and
+  // there's nothing left to expand. We pass the template straight to the
+  // LLM. If a stale pattern with $fragment refs sneaks back in, the LLM
+  // will see the literal placeholder string and likely include it in
+  // output (acceptable failure mode; corpus drift is caught by the
+  // verify:corpus script).
+  const expandedPatternTemplate = bestPattern?.template ?? null;
+
+  // ── Chunk reference block — injected into the user prompt when a
+  //    strong chunk match was found at retrieval time. This is the
+  //    structural "look like this" hint that lets the LLM materialize the
+  //    real chunk shape (e.g. auth-signin-card-email) instead of
+  //    hallucinating a passable-but-wrong shape from the brief alone.
+  //
+  //    §56 (v0.4.5): prompt language enriched with provenance + metadata so
+  //    the LLM understands the chunk's domain/keywords context. Tested via
+  //    factory-chat + gen-ui live submit; LLMs produce closer structural
+  //    matches when told what the chunk is + where it came from.
+  const chunkReferenceBlock = chunkRefHtml
+    ? `\nSTRUCTURAL REFERENCE — this chunk was retrieved from the AdiaUI training corpus (annotated production HTML, harvested from real app pages). It matched your intent on keyword/domain ranking:
+
+CHUNK: ${chunkMatch.name}
+  kind=${chunkMatch.kind}, primary=${chunkMatch.primary}, score=${chunkMatch.score}${chunkMatch.metadata?.domain ? `, domain=${chunkMatch.metadata.domain}` : ''}${chunkMatch.metadata?.description ? `\n  description: ${chunkMatch.metadata.description}` : ''}${chunkMatch.metadata?.keywords ? `\n  keywords: ${chunkMatch.metadata.keywords.join(', ')}` : ''}
+
+Match this chunk's component palette, information density, and Card/Header/Section/Footer anatomy. Do NOT copy the HTML verbatim into A2UI — translate its semantic structure into the equivalent A2UI components. The chunk represents the SHAPE the user wants; your job is to instantiate that shape with their content:
+---
+${chunkRefHtml}
+---
+`
+    : '';
+
   if (bestPattern && bestPattern.template) {
     // PRO PATH: Adapt the matched pattern via LLM
     systemPrompt = await buildSystemPrompt(context, patterns, '', intent);
 
     const adaptPrompt = hasPriorCanvas
       ? `Adapt this UI for the intent: "${intent}"${driftGuard}
-
+${chunkReferenceBlock}
 ${buildCanvasDiffPrompt(intent, priorComponents, { originalIntent })}`
       : hasFragments
         ? `Adapt this UI for the intent: "${intent}"
-
+${chunkReferenceBlock}
 BASE TEMPLATE (use for overall structure — modify, don't generate from scratch):
-${JSON.stringify(bestPattern.template, null, 2)}
+${JSON.stringify(expandedPatternTemplate, null, 2)}
 
 Pattern: "${bestPattern.name}" — ${bestPattern.description}
 
@@ -201,9 +269,9 @@ Instructions:
 - Include realistic text content, labels, and placeholder data — not generic text
 - Output ONLY the JSON array, no explanation`
         : `Adapt this UI for the intent: "${intent}"
-
+${chunkReferenceBlock}
 BASE TEMPLATE (modify this, don't generate from scratch):
-${JSON.stringify(bestPattern.template, null, 2)}
+${JSON.stringify(expandedPatternTemplate, null, 2)}
 
 Pattern: "${bestPattern.name}" — ${bestPattern.description}
 
@@ -238,7 +306,7 @@ Instructions:
       : '';
 
     const composePrompt = `Compose a UI for: "${intent}"
-${canvasContext}
+${chunkReferenceBlock}${canvasContext}
 This intent has ${fragmentPatterns.length} sections. ${layoutHint}
 
 FRAGMENT PATTERNS — use these as building blocks for each section:
@@ -269,7 +337,7 @@ Instructions:
     if (hasPriorCanvas) {
       // Multi-turn: inject current canvas as explicit iteration context
       const iteratePrompt = `Modify this UI for the intent: "${intent}"${driftGuard}
-
+${chunkReferenceBlock}
 ${buildCanvasDiffPrompt(intent, priorComponents, { originalIntent })}`;
 
       const response = await llmAdapter.complete({
@@ -279,7 +347,21 @@ ${buildCanvasDiffPrompt(intent, priorComponents, { originalIntent })}`;
       messages = parseA2UIResponse(response.content, { executionId: execId, intent, mode: 'pro', stopReason: response.stopReason });
       if (isRecording()) { lastRawResponse = response.content; lastTokens = response.usage || null; }
     } else {
+      // First-turn fresh generation. When we have a chunk match, prepend
+      // the structural reference to the user message so the LLM sees the
+      // canonical shape before the standard chat-built prompt.
       const chatMessages = buildChatMessages(intent, storeId || execId);
+      if (chunkReferenceBlock && chatMessages.length) {
+        // The last message in chatMessages is the user's brief — prepend
+        // the chunk reference to its content.
+        const lastIdx = chatMessages.length - 1;
+        if (chatMessages[lastIdx].role === 'user') {
+          chatMessages[lastIdx] = {
+            ...chatMessages[lastIdx],
+            content: `${chunkReferenceBlock}\n${chatMessages[lastIdx].content}`,
+          };
+        }
+      }
       const response = await llmAdapter.complete({ messages: chatMessages, systemPrompt });
       messages = parseA2UIResponse(response.content, { executionId: execId, intent, mode: 'pro', stopReason: response.stopReason });
       if (isRecording()) { lastRawResponse = response.content; lastTokens = response.usage || null; }
@@ -341,6 +423,7 @@ ${buildCanvasDiffPrompt(intent, priorComponents, { originalIntent })}`;
   feedbackStore.logExecution({
     executionId: artifactId, intent, mode: 'pro',
     domain: domain.domain, patternMatch: bestPattern?.name,
+    chunkMatch: chunkMatch ? chunkMatch.name : null,
     composedFrom: hasFragments ? fragmentPatterns.map(f => f.pattern.name) : undefined,
     score: validation?.score, componentCount: messages[0]?.components?.length || 0,
   }).catch(() => {});

package/strategies/registry.js

@@ -15,7 +15,7 @@
  */
 
 // Zettel is lazy-loaded — it transitively imports node:fs / node:path / node:url
-// (strategies/zettel/fragment-library.js), which Vite externalizes in the browser.
+// (strategies/zettel/composition-library.js), which Vite externalizes in the browser.
 // Static-importing it here would break browser loads of core/generator.js.
 // In-browser callers reach zettel via POST /api/generate (server-side), never
 // through this registry, so lazy-loading is safe and incurs only a one-time

package/strategies/zettel/_smoke.js

@@ -1,14 +1,11 @@
 #!/usr/bin/env node
-/** Smoke test: load library, resolve login-form, print resolved template. */
-import { loadAll, getAllFragments, getAllCompositions, searchAll, getGraph, getComposition } from './fragment-library.js';
+/** Smoke test: load library, resolve login-form composition, print template. */
+import { loadAll, getAllCompositions, searchAll, getComposition } from './composition-library.js';
 import { resolveComposition } from './composer.js';
 
 const boot = loadAll();
 console.log('boot:', boot);
 
-console.log('\n=== Fragments ===');
-for (const f of getAllFragments()) console.log(` - ${f.name} [${f.semantic_role}]`);
-
 console.log('\n=== Compositions ===');
 for (const c of getAllCompositions()) console.log(` - ${c.name} (${c.domain})`);
 
@@ -28,10 +25,3 @@ for (const n of resolved) {
   const label = n.label ? ` label="${n.label}"` : '';
   console.log(`  ${n.id.padEnd(20)} ${n.component}${label}${text} ${kids}`);
 }
-
-console.log('\n=== Graph ===');
-const g = getGraph();
-console.log('fragments with usage:');
-for (const f of g.fragments) {
-  if (f.used_by.length) console.log(`  ${f.name} ← ${f.used_by.map(u => u.name).join(', ')}`);
-}