@adia-ai/a2ui-compose 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -12,6 +12,33 @@ generator graph.
 
 _No pending changes._
 
+## [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
+
+- **`process.env` browser-compat guard** — `core/generator.js` and `strategies/zettel/state-cache.js` were accessing `process.env` directly, which throws `ReferenceError: process is not defined` in browser execution paths (e.g. the gen-ui playground importing compose directly). Both sites now guard via `const IS_NODE = typeof process !== 'undefined' && process.versions?.node;` before reading `process.env`. The `A2UI_COMPOSE_TRACE` debug-trace and `STATE_CACHE_DIR` env-lookup paths are Node-only by design; the dynamic `node:fs/promises` + `node:path` imports also short-circuit when `IS_NODE` is false.
+
+### Lockstep
+
+9-package coordinated PATCH cut to v0.4.3 (per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy)). Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). Source change scoped to `core/generator.js` + `strategies/zettel/state-cache.js`. Rides alongside `@adia-ai/web-components` v0.4.3 (input-ui locale + thousands grouping + hold-to-repeat). See root [CHANGELOG.md `## [0.4.3]`](../../../CHANGELOG.md) for the cut narrative.
+
 ## [0.4.2] - 2026-05-11
 
 ### Ride-along (no source changes)

package/README.md

@@ -14,7 +14,18 @@ ready for a renderer.
 >
 > Published to the public `@adia-ai` scope on 2026-04-24 alongside
 > `a2ui-corpus`, `a2ui-mcp`, `a2ui-retrieval`, and `a2ui-validator`.
-> Install with `npm i @adia-ai/a2ui-compose`.
+
+## Install
+
+```bash
+npm install @adia-ai/a2ui-compose
+```
+
+Typically paired with `@adia-ai/a2ui-corpus` (the pattern corpus the engine reads from) and `@adia-ai/llm` (the LLM client; runtime peer-dep):
+
+```bash
+npm install @adia-ai/a2ui-compose @adia-ai/a2ui-corpus @adia-ai/llm
+```
 
 ## What it does
 

package/core/generator.js

@@ -191,7 +191,14 @@ export async function generateUI({ intent, engine: engineName = 'monolithic', mo
   // a per-request JSON file BEFORE the strip. Useful for debugging
   // strategy-label decisions or reproducing eval failures. Off by default;
   // file writes happen synchronously and add ~1-5ms per request.
-  const traceDir = process.env.A2UI_COMPOSE_TRACE;
+  //
+  // Node-only: `process` is undefined in the browser. Guard the env lookup
+  // so the post-await codepath doesn't throw `ReferenceError: process is
+  // not defined` when generator.js runs in the gen-ui playground. The
+  // dynamic node:fs/path imports below would also fail in the browser, but
+  // the guard short-circuits before we get there.
+  const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
+  const traceDir = IS_NODE ? process.env.A2UI_COMPOSE_TRACE : null;
   if (traceDir && result._debug) {
     try {
       const { writeFile, mkdir } = await import('node:fs/promises');

package/package.json

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

package/strategies/_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/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,44 @@ 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.
+  const chunkReferenceBlock = chunkRefHtml
+    ? `\nSTRUCTURAL REFERENCE — a real production block from the codebase matched this intent. Match its 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:
+
+CHUNK: ${chunkMatch.name} (${chunkMatch.kind}, primary=${chunkMatch.primary}, score=${chunkMatch.score})
+---
+${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 +261,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 +298,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 +329,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 +339,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 +415,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(', ')}`);
-}