@adia-ai/gen-ui 0.8.37

package/compose/strategies/zettel/composition-library.js

@@ -0,0 +1,418 @@
+/**
+ * Composition Library — zettel-style loader for harvested A2UI chunks.
+ *
+ * Reads `corpus/chunks/<name>.json` whenever the chunk carries both
+ * `metadata` (from `data-chunk-*` source-HTML attrs per §40) AND
+ * `template` (from the harvester's transpileHTML pass per §41). Chunks
+ * are normalized to composition shape by hoisting `metadata.*` to
+ * top level so consumers can search them uniformly.
+ *
+ * The legacy `corpus/compositions/<domain>/<name>.json` glob was
+ * retired in v0.4.7 (§65). The harvested-chunks substrate (~30
+ * annotated chunks at landing time) is the canonical retrieval
+ * surface; per the project's "source-of-truth = shipped /site/"
+ * principle, anything not in a shipped surface should fall through
+ * to LLM generation rather than be retrieval-matched from a curated
+ * JSON. The 199 MODE-C-MAYBE + 9 KEEP-AS-CHUNK + 3 DELETE
+ * composition/pattern files all retired alongside the dir.
+ *
+ * Records carry `_kind: 'annotated-chunk'` and the source-of-truth
+ * path so consumers can distinguish if they care; most shouldn't.
+ *
+ * Renamed from fragment-library.js in §38. Fragments retired §37.
+ * Annotated-chunk loading added §41. Compositions-glob retired §65.
+ */
+
+// §72 follow-up (v0.4.7): dual-mode loader so this module is safe to
+// statically import from browser entrypoints. Previously the top-level
+// `import 'node:fs'` poisoned the browser bundle the moment any
+// app/playground reached `core/reference.js` → composition-library.
+// Pattern mirrors `retrieval/component-catalog.js`.
+//
+// 2026-06-10: TRI-mode loader. The original dual-mode pattern assumed
+// every browser context is a Vite dev server. The STATIC deploy
+// (ui-kit.exe.xyz) serves the raw source JS — there is no Vite to transform
+// the glob — so the glob `try/catch` swallowed silently and loaded 0 chunks.
+// Every canvas intent then "composition-retrieval missed" on prod even
+// though the chunk scored 66 in Node. Third branch: static-browser → fetch
+// the corpus over HTTP.
+//   - Node (fs)             — server / eval / smoke
+//   - Vite browser (glob)   — `npm run dev`
+//   - Static browser (fetch)— deployed dist (no Vite, no /api/generate)
+//
+// CRUX — how we tell Vite-browser from static-browser (2026-06-10):
+// `import.meta.glob` is a Vite **compile-time macro on the CALL expression**,
+// NOT a runtime function. Vite rewrites `import.meta.glob('…')` into an
+// object literal at transform time, but a bare reference like
+// `typeof import.meta.glob` is left untouched — so at RUNTIME
+// `import.meta.glob` is `undefined` in BOTH Vite-dev and static contexts
+// (verified empirically 2026-06-10). The only reliable discriminator is to
+// ATTEMPT the call in a try/catch: in Vite it was already rewritten to the
+// object literal (succeeds, returns N loaders); on the raw static site the
+// call hits the real `import.meta.glob` which is undefined → throws
+// `import.meta.glob is not a function` → caught → we take the fetch branch.
+// (This is parse-safe: `import.meta` is a real object in every ES module;
+// the throw is a runtime TypeError, not a SyntaxError.)
+const IS_NODE =
+  typeof process !== 'undefined' &&
+  typeof process.versions?.node === 'string';
+
+/** @type {Map<string, object>} */
+const compositions = new Map();
+
+// Vite rewrites this call at transform time; on the static site the call
+// throws (no Vite) → `_globChunkModules` stays null → fetch branch runs.
+let _globChunkModules = null;
+if (!IS_NODE) {
+  try {
+    _globChunkModules = import.meta.glob('../../../corpus/chunks/*.json', {
+      query: '?raw',
+      import: 'default',
+      eager: false,
+    });
+  } catch {
+    // No Vite transform here (static deploy) — fall through to the fetch branch.
+  }
+}
+// `HAS_VITE_GLOB` is now decided by whether the glob CALL produced loaders,
+// not by an (always-undefined-at-runtime) `typeof` probe.
+const HAS_VITE_GLOB =
+  !IS_NODE && !!_globChunkModules && Object.keys(_globChunkModules).length > 0;
+
+/**
+ * Promote an annotated chunk record to composition shape. Lifts
+ * `metadata.{domain,description,keywords,related,tags}` to top-level
+ * fields so the existing searchAll scorer can read them uniformly.
+ */
+function chunkToComposition(chunkDoc, sourcePath, { bodyUrl = null } = {}) {
+  const meta = chunkDoc.metadata || {};
+  return {
+    _kind: 'annotated-chunk',
+    _sourceFile: sourcePath,
+    // Static-browser only: URL to fetch the chunk body (template) on demand.
+    // null in Node / Vite, where `template` is already populated eagerly.
+    _bodyUrl: bodyUrl,
+    name: chunkDoc.name,
+    kind: 'composition', // honest with the searchAll filter
+    domain: meta.domain,
+    description: meta.description,
+    keywords: meta.keywords || [],
+    related: meta.related || [],
+    tags: meta.tags || {},
+    template: chunkDoc.template ?? null,
+  };
+}
+
+/**
+ * Track whether the eager top-level load has run. Multiple `loadAll`
+ * call sites (mcp/server.js bootstrap + any other consumer) re-clear
+ * + re-build, which is wasted work but not incorrect.
+ */
+let _autoLoaded = false;
+let _loadStats = { compositionCount: 0, handAuthoredCount: 0, annotatedChunkCount: 0 };
+
+/**
+ * Filter + register an annotated chunk. Returns 1 if it qualified
+ * (had `metadata` + non-empty `template` + domain/keywords), else 0.
+ */
+function registerChunk(doc, sourcePath) {
+  if (!doc?.metadata) return 0;
+  if (!doc.template || !Array.isArray(doc.template) || doc.template.length === 0) return 0;
+  const meta = doc.metadata;
+  if (!meta.domain && !(meta.keywords && meta.keywords.length > 0)) return 0;
+  compositions.set(doc.name, chunkToComposition(doc, sourcePath));
+  return 1;
+}
+
+/**
+ * Static-browser only: register a chunk from its `_index.json` entry for
+ * SCORING (name + metadata.{domain,description,keywords} — verified at
+ * 2026-06-10 to be byte-identical to the per-chunk file's metadata). The
+ * `template` is NOT in the index; it is fetched lazily by
+ * `hydrateComposition(name)` when a strong match is actually emitted, so
+ * page-load costs one request (the 281 KB index) instead of 339.
+ *
+ * Index entries carry no `template`, so the eager `registerChunk` gate
+ * (which requires a non-empty template) would reject every one. We apply
+ * the SAME metadata gate (domain OR keywords present) but defer the
+ * template requirement to hydration time.
+ */
+function registerIndexEntry(entry, bodyUrl) {
+  if (!entry?.metadata || !entry.name) return 0;
+  const meta = entry.metadata;
+  if (!meta.domain && !(meta.keywords && meta.keywords.length > 0)) return 0;
+  // template: null here — hydrated on demand. searchAll never reads it.
+  compositions.set(entry.name, chunkToComposition(entry, entry.name, { bodyUrl }));
+  return 1;
+}
+
+async function _loadAllNode() {
+  const fs = await import(/* @vite-ignore */ 'node:fs');
+  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 CHUNKS_ROOT = path.resolve(__dirname, '../../../corpus/chunks');
+
+  function walk(dir, cb) {
+    if (!fs.existsSync(dir)) return;
+    // §160 (v0.5.3, F-S1 root cause): sort readdir output. fs.readdirSync
+    // returns entries in filesystem-defined order (variable across
+    // processes on APFS/ext4), which means chunk-loading order varied
+    // run-to-run. When two chunks tied on score for a given intent, the
+    // first-loaded won the tie-break — so the same intent could match
+    // chunk A in one process and chunk B in the next. Surfaced as
+    // ~40% probe-failure rate on admin-dashboard post-§143 (the new
+    // chunks compete with the original 4-row KPI composition).
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(p, cb);
+      else if (entry.name.endsWith('.json') && !entry.name.startsWith('_')) cb(p);
+    }
+  }
+
+  let annotatedChunkCount = 0;
+  walk(CHUNKS_ROOT, (p) => {
+    const doc = JSON.parse(fs.readFileSync(p, 'utf8'));
+    annotatedChunkCount += registerChunk(doc, p);
+  });
+  return annotatedChunkCount;
+}
+
+async function _loadAllBrowser() {
+  if (!_globChunkModules) return 0;
+  let annotatedChunkCount = 0;
+  for (const [globPath, loader] of Object.entries(_globChunkModules)) {
+    try {
+      const raw = await loader();
+      const doc = JSON.parse(raw);
+      annotatedChunkCount += registerChunk(doc, globPath);
+    } catch {
+      // skip malformed chunk JSON
+    }
+  }
+  return annotatedChunkCount;
+}
+
+// Base URL for the corpus on a static deploy. Relative-to-module
+// (`import.meta.url`) — NOT an absolute `/packages/...` path — deliberately:
+//   1. It is the SAME path the Vite glob trusts ('../../../corpus/chunks/*'),
+//      so dev and prod resolve through one mental model.
+//   2. It is mount-point-independent: works whether dist is served at `/`,
+//      under a sub-path, or via the dist symlink layout
+//      (dist/node_modules/@adia-ai/gen-ui → packages/gen-ui),
+//      because `import.meta.url` always reflects the actually-served path.
+//      Verified 2026-06-10: `new URL('../../../corpus/chunks/_index.json',
+//      import.meta.url)` → `<root>/packages/gen-ui/corpus/chunks/_index.json`.
+const _CORPUS_CHUNKS_BASE =
+  !IS_NODE && !HAS_VITE_GLOB
+    ? new URL('../../../corpus/chunks/', import.meta.url)
+    : null;
+
+/**
+ * Static-browser loader. Fetches `_index.json` ONCE and registers every
+ * chunk for scoring. Bodies (templates) are fetched lazily by
+ * `hydrateComposition` so page-load stays at a single request, not 339.
+ *
+ * Degrades to 0 chunks (not a throw) on any fetch / parse failure — same
+ * graceful-empty contract as the Node and Vite branches.
+ */
+async function _loadAllStatic() {
+  if (!_CORPUS_CHUNKS_BASE) return 0;
+  let index;
+  try {
+    const res = await fetch(new URL('_index.json', _CORPUS_CHUNKS_BASE));
+    if (!res.ok) return 0;
+    index = await res.json();
+  } catch {
+    return 0;
+  }
+  const entries = Array.isArray(index?.chunks) ? index.chunks : [];
+  let count = 0;
+  for (const entry of entries) {
+    if (!entry?.name) continue;
+    const bodyUrl = new URL(`${entry.name}.json`, _CORPUS_CHUNKS_BASE).href;
+    count += registerIndexEntry(entry, bodyUrl);
+  }
+  return count;
+}
+
+/**
+ * Load all annotated chunks into the in-memory map. Returns a stats
+ * snapshot. In Node, runs synchronously via `fs.readFileSync`; in the Vite
+ * browser, dispatches the glob loaders in parallel; on a static deploy,
+ * fetches the index (bodies lazy-loaded on emit).
+ */
+export async function loadAll() {
+  compositions.clear();
+  let annotatedChunkCount;
+  if (IS_NODE) annotatedChunkCount = await _loadAllNode();
+  else if (HAS_VITE_GLOB) annotatedChunkCount = await _loadAllBrowser();
+  else annotatedChunkCount = await _loadAllStatic();
+  _autoLoaded = true;
+  _loadStats = {
+    compositionCount: compositions.size,
+    handAuthoredCount: 0,
+    annotatedChunkCount,
+  };
+  return _loadStats;
+}
+
+/**
+ * Ensure a composition's `template` (body) is loaded before a consumer
+ * resolves it. No-op in Node / Vite (the eager load already populated
+ * `template`). On a static deploy, fetches `<name>.json` once, patches the
+ * in-memory record's `template`, and caches it for subsequent calls.
+ *
+ * The zettel adapter's STRONG-MATCH branch awaits this immediately before
+ * `getComposition(name)` so verbatim emission has a body. Index-only
+ * scoring + lazy single-body hydration is what keeps the static page-load
+ * to one request — `searchAll` itself never needs the template.
+ *
+ * @param {string} name
+ * @returns {Promise<object|undefined>} the (now-hydrated) composition record
+ */
+export async function hydrateComposition(name) {
+  const rec = compositions.get(name);
+  if (!rec) return undefined;
+  // Already has a body (Node / Vite, or a prior hydration) — done.
+  if (Array.isArray(rec.template) && rec.template.length > 0) return rec;
+  if (!rec._bodyUrl) return rec; // not a static-deferred record; nothing to fetch
+  try {
+    const res = await fetch(rec._bodyUrl);
+    if (!res.ok) return rec;
+    const doc = await res.json();
+    if (Array.isArray(doc?.template) && doc.template.length > 0) {
+      rec.template = doc.template;
+    }
+  } catch {
+    // Leave template null — resolveComposition handles an empty template
+    // (emits nothing) rather than throwing.
+  }
+  return rec;
+}
+
+// Eager top-level load so synchronous getters (getComposition,
+// getAllCompositions, searchAll) work for consumers that don't call
+// loadAll themselves — test harnesses, smoke scripts, and the
+// retrieval-side helpers migrated off pattern-library in §64.
+//
+// In Node we top-level-await the load so the map is populated before
+// any importer reaches the synchronous getters. In the browser the
+// auto-load is fire-and-forget (the map fills as chunk JSONs come back
+// from Vite's glob loaders); callers that need the map populated MUST
+// `await loadAll()` themselves. Documented in §72-follow-up.
+if (IS_NODE && !_autoLoaded) {
+  await loadAll();
+} else if (!IS_NODE && !_autoLoaded) {
+  // Fire-and-forget; do not block module import on the network round-trips.
+  // Covers BOTH browser branches (Vite glob + static fetch). Consumers that
+  // need the map populated before a synchronous searchAll MUST `await
+  // loadAll()` (or await the adapter's own boot). The canvas does: its
+  // generateViaZettel awaits a fresh loadAll on the static-browser path.
+  loadAll().catch(() => { /* swallow; browsers that don't need this path won't trip */ });
+}
+
+// Back-compat shims removed in §38 — fragment-library.js → composition-library.js
+// rename. The retired `getFragment` / `getAllFragments` exports had zero
+// external callers; drop them.
+
+export function getComposition(name) { return compositions.get(name); }
+export function getAllCompositions() { return [...compositions.values()]; }
+
+/**
+ * Keyword search across compositions. (Fragments retired; only one
+ * corpus class to search now.)
+ *
+ * Ranking design:
+ *   1. Tokenize query, drop generic UI stop-words ("form", "page", "view"…)
+ *      so they can't be the sole evidence for a match.
+ *   2. Whole-word match, not substring — prevents "form" matching "login-form".
+ *   3. Require ≥2 content-token hits (compositions are concrete templates —
+ *      promiscuous matching is expensive). Exception: a direct name-token
+ *      match is strong enough on its own.
+ *   4. Tiered weights: name hit > keyword hit > description.
+ */
+// Mirrored in `corpus/scripts/chunk-library.js` (`SEARCH_STOP_WORDS`) — this
+// module is browser-safe and can't import that node-only one. Change both or neither.
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'at', 'for', 'with',
+  'form', 'forms', 'page', 'pages', 'view', 'views', 'screen', 'screens',
+  'ui', 'component', 'components', 'widget', 'widgets', 'block', 'blocks',
+  'section', 'sections', 'layout', 'layouts',
+]);
+
+function tokenize(str) {
+  return (str || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2);
+}
+
+export function searchAll(query, { limit = 20 } = {}) {
+  const q = (query || '').trim();
+  if (!q) return [];
+  const queryTokens = tokenize(q);
+
+  const scoreDoc = (doc) => {
+    const nameTokens = new Set(tokenize(doc.name));
+    const keywordTokens = new Set((doc.keywords || []).flatMap((k) => tokenize(k)));
+    const descTokens = new Set(tokenize(doc.description || ''));
+    const tagTokens = new Set(
+      Object.values(doc.tags || {}).flat().flatMap((v) => tokenize(String(v))),
+    );
+
+    let s = 0;
+    const contentMatched = new Set();
+
+    for (const t of queryTokens) {
+      const isStop = STOP_WORDS.has(t);
+      let matched = false;
+      if (nameTokens.has(t))    { s += isStop ? 1 : 12; matched = true; }
+      if (keywordTokens.has(t)) { s += isStop ? 1 : 8;  matched = true; }
+      if (tagTokens.has(t))     { s += isStop ? 0 : 3;  matched = true; }
+      if (descTokens.has(t))    { s += isStop ? 0 : 2;  matched = true; }
+      if (matched && !isStop) {
+        contentMatched.add(t);
+      }
+    }
+    const contentHits = contentMatched.size;
+
+    // Gate: compositions require ≥2 content-token hits, OR a direct
+    // name-token match (the query contains the composition's primary
+    // concept word — strong evidence on its own).
+    const nameHit = queryTokens.some((t) => !STOP_WORDS.has(t) && nameTokens.has(t));
+    if (contentHits < 2 && !nameHit) return 0;
+
+    // Coverage bonus: more distinct content tokens matched = better match
+    s += contentHits * 3;
+
+    return s;
+  };
+
+  return getAllCompositions()
+    .map((doc) => ({ doc, score: scoreDoc(doc) }))
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((x) => ({
+      type: 'composition',
+      name: x.doc.name,
+      score: Math.round(x.score * 100) / 100,
+      description: x.doc.description,
+      domain: x.doc.domain,
+    }));
+}
+
+/** Return composition catalog for inspection / visualization. */
+export function getGraph() {
+  return {
+    compositions: getAllCompositions().map((c) => ({
+      name: c.name,
+      domain: c.domain,
+      node_count: (c.template || []).length,
+    })),
+  };
+}

package/compose/strategies/zettel/generate.js

@@ -0,0 +1,15 @@
+/**
+ * @adia-ai/gen-ui — zettel engine facade.
+ *
+ * Fragment-graph composition. Three reasoning layers:
+ *   1. Retrieval (always) — keyword-rank corpus, resolve top composition
+ *   2. LLM synthesis (when llmAdapter + weak retrieval) — compose a new
+ *      composition from fragments
+ *   3. Session-aware iteration (when sessionId + prior turns) — modify
+ *      existing canvas instead of regenerating
+ *
+ * The actual implementation is generator-adapter.js; this file is the
+ * spec-compliant entry point at strategies/zettel/generate.js per §11.
+ */
+
+export { generateZettel as generate } from './generator-adapter.js';

package/compose/strategies/zettel/generator-adapter.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};

package/compose/strategies/zettel/generator-adapter.js

@@ -0,0 +1,242 @@
+/**
+ * Generator adapter for zettel MCP — conforms to the eval harness contract:
+ *
+ *   generate({ intent, mode, llmAdapter, sessionId }) -> { messages, validation, strategy, ...extra }
+ *
+ * Two reasoning layers (post-§195, v0.5.6):
+ *   1. Retrieval (always available) — keyword-rank the corpus, resolve top composition.
+ *   2. LLM synthesis (when llmAdapter provided AND retrieval weak) — bridge to
+ *      chunk-zettel's `composeFromIntent` (the §37 successor codepath) which
+ *      produces a single-shot html composition from the chunk corpus.
+ *
+ * Session iteration is currently NOT history-aware in this engine. Prior turns
+ * are recorded for analytics + drift tracking, but turn≥2 takes the same code
+ * path as turn 1 (fresh retrieval → fresh synthesis). Full history-aware
+ * iteration (multi-turn refinement modifying an existing canvas) lives in the
+ * `chunk-zettel` engine via `chunk-refiner.js::refineFromIntent` — wire it via
+ * `engine: 'chunk-zettel'` rather than `engine: 'zettel'`.
+ *
+ * The prior fragment-graph iteration codepath (`synthesizeComposition` with
+ * `historySummary`) was retired in §37 (2026-05-12) when fragments retired.
+ * §195 (v0.5.6) cleaned up the dangling caller — turn≥2 no longer throws +
+ * auto-fires a `iteration-synthesis-failure` issue on every multi-turn turn.
+ *
+ * Strategy labels in the return:
+ *   - composition-match          — fresh retrieval, strong match, emitted verbatim
+ *   - composition-synthesized    — chunk-zettel single-shot synthesis
+ *   - fragment-candidates        — retrieval weak + no LLM, returning atoms only
+ *   - synthesis-failed           — chunk-zettel tried and failed validation
+ */
+import {
+  getComposition,
+  hydrateComposition,
+  searchAll,
+} from './composition-library.js';
+import { resolveComposition, templateToMessages } from './composer.js';
+import {
+  recordTurn,
+  getTurns,
+} from './session-store.js';
+import { validateSchema } from '@adia-ai/a2ui/validate';
+
+// Lazy-load the chunk-synthesizer bridge. It imports chunk-corpus data
+// via composition-library's dual-mode loader, which is already top-level
+// awaited; importing it here statically would not break anything but the
+// async-import keeps the cold-start surface tight for the strong-match
+// (no-LLM) path that doesn't need synthesis at all.
+async function bridgeToChunkSynthesis({ intent, llmAdapter }) {
+  const { composeFromIntent } = await import('./chunk-synthesizer.js');
+  const result = await composeFromIntent({ intent, llmAdapter, maxAttempts: 2 });
+  // Shape-adapt chunk-synthesizer's `{ html, template, plan, source, ... }`
+  // to the synthesis-branch's prior `{ messages, template, synthesis }`
+  // contract. TKT-0009: prefer the real component array (`result.template`)
+  // over the pre-fix fallback of wrapping raw HTML in a single node with an
+  // UNREGISTERED `component: 'article'` type — that fallback made this
+  // caller's validate-and-repair pass below structurally unable to ever
+  // report a clean pass.
+  const messages = result.template
+    ? [{ type: 'updateComponents', components: result.template }]
+    : result.html
+      ? [{ type: 'updateComponents', components: [{ id: 'chunk-root', component: 'article', html: result.html }] }]
+      : [];
+  return {
+    messages,
+    template: result.plan ? [{ $chunk: 'composeFromIntent', plan: result.plan }] : [],
+    synthesis: {
+      source: result.source,
+      score: result.score,
+      warnings: result.warnings || [],
+      scopeDrift: result.scopeDrift || null,
+    },
+  };
+}
+
+// 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).
+// Calibrated on the 100-intent held-out set:
+//   strong matches: login-form=24 (exact), signup-form=27, chart-dashboard=48, pricing-tiers=54
+//   weak/false-positive matches: drop below 22 on off-topic queries
+// Raised from 22 → 40 (2026-04-19) so that only near-perfect retrievals play
+// verbatim; merely-good matches (login-form, signup-form) fall through to LLM
+// synthesis instead of being emitted as canned output. Tradeoff: more LLM calls
+// (slower, costlier) in exchange for compositional variety. The previous 22
+// threshold maximized verbatim-cache hits at the cost of repetitive output.
+const STRONG_MATCH_THRESHOLD = 40;
+
+function toUpdateComponentsMessages(template) {
+  return [{
+    type: 'updateComponents',
+    components: template.map((n) => {
+      const {
+        id, component, children,
+        $fragment, bindings,
+        prependChildren, appendChildren,
+        ...rest
+      } = n;
+      return { id, component, children: children || [], ...rest };
+    }),
+  }];
+}
+
+export async function generateZettel({ intent, mode = 'instant', llmAdapter = null, sessionId = null } = {}) {
+  // ── Session iteration note (post-§195, v0.5.6) ──
+  // Fragment-graph history-aware iteration (`synthesizeComposition` with
+  // `historySummary`) was retired in §37 when fragments retired. Turn≥2 now
+  // takes the same path as turn 1 — fresh retrieval → fresh chunk-synthesis.
+  // For true history-aware iteration (modify-an-existing-canvas), wire the
+  // request via `engine: 'chunk-zettel'` which uses `chunk-refiner.js`.
+  //
+  // Prior turns are still recorded (analytics + drift tracking via `getDrift`)
+  // but the iteration BRANCH is gone — no more spurious
+  // `iteration-synthesis-failure` auto-fires on every multi-turn request.
+  const priorTurns = sessionId ? getTurns(sessionId) : [];
+
+  const hits = searchAll(intent, { limit: 5 });
+  const composition = hits.find((h) => h.type === 'composition');
+  const strongMatch = composition && composition.score >= STRONG_MATCH_THRESHOLD;
+
+  // ── Strong retrieval match: emit verbatim (turn 1 only — iteration branch above handles repeats) ──
+  if (strongMatch) {
+    // On a static deploy the composition was registered from `_index.json`
+    // for SCORING only — its `template` is fetched lazily here, right before
+    // we resolve it. No-op in Node / Vite (template already populated). This
+    // keeps the static page-load to a single index request; only the
+    // actually-emitted match pays for its body. 2026-06-10.
+    await hydrateComposition(composition.name);
+    const comp = getComposition(composition.name);
+    const template = resolveComposition(comp);
+    // Parity guard: Node's `registerChunk` excludes template-less chunks, so
+    // they never reach this branch server-side. The static index-scoring gate
+    // is looser (it can't see templates in `_index.json`), so a handful of
+    // body-less partials (auth-card-header, onb-step-*, …) COULD surface as a
+    // strong match on a static deploy. If hydration produced no usable
+    // template, treat it as a non-match and fall through — keeping the
+    // static result identical to what Node would emit (synthesis / atoms),
+    // never an empty verbatim surface.
+    if (!Array.isArray(template) || template.length === 0) {
+      // fall through to the weak/no-match paths below
+    } else {
+    const messages = toUpdateComponentsMessages(template);
+    const validation = validateSchema(messages, { intent });
+    const rank = hits.findIndex((h) => h.type === 'composition' && h.name === composition.name) + 1;
+    const fragments = (comp.template || []).filter((n) => n.$fragment).map((n) => n.$fragment);
+    recordTurn(sessionId, {
+      intent,
+      messages,
+      template: comp.template,
+      composition: composition.name,
+      strategy: 'composition-match',
+      fragments,
+      validation,
+    });
+    return {
+      messages,
+      validation,
+      strategy: 'composition-match',
+      retrieval: { hit: true, rank, candidate: composition.name },
+      composition: composition.name,
+      retrievalScore: composition.score,
+      fragments_used: fragments,
+      candidates: hits,
+      sessionTurns: priorTurns.length + 1,
+    };
+    } // end else (template present)
+  }
+
+  // ── Weak/no retrieval: bridge to chunk-zettel synthesis (the §37 successor) ──
+  if (llmAdapter && mode !== 'instant-only') {
+    try {
+      const synth = await bridgeToChunkSynthesis({ intent, llmAdapter });
+      // Full schema/catalog/anti-pattern conformance (validate-only — see
+      // validate-and-repair.js; TKT-0009 made this meaningful for the first
+      // time by giving synth.messages a real component graph instead of an
+      // opaque HTML wrapper).
+      const { validateAndRepair } = await import('../../shared/validate-and-repair.js');
+      const schemaCheck = synth.messages.length ? await validateAndRepair({ messages: synth.messages }) : { valid: false, validation: { score: 0 } };
+      const validation = schemaCheck.validation;
+      // Chunk-bridge produces an html-bearing single component, not
+      // resolved fragment instances. `fragments_used` is empty by design;
+      // consumers tracking fragment usage should switch to the
+      // chunk-zettel engine which surfaces `_debug.plan` directly.
+      recordTurn(sessionId, {
+        intent,
+        messages: synth.messages,
+        template: synth.template,
+        composition: null,
+        strategy: 'composition-synthesized',
+        fragments: [],
+        validation,
+      });
+      return {
+        messages: synth.messages,
+        validation,
+        strategy: 'composition-synthesized',
+        retrieval: {
+          hit: false,
+          rank: composition ? hits.findIndex((h) => h.type === 'composition' && h.name === composition.name) + 1 : null,
+          candidate: composition?.name ?? null,
+          reason: composition ? `top score ${composition.score} below threshold ${STRONG_MATCH_THRESHOLD}` : 'no composition retrieved',
+        },
+        composition: null,
+        fragments_used: [],
+        synthesized_template: synth.template,
+        synthesis: synth.synthesis,
+        candidates: hits,
+        sessionTurns: priorTurns.length + 1,
+      };
+    } catch (err) {
+      return {
+        messages: [],
+        validation: { score: 0 },
+        strategy: 'synthesis-failed',
+        retrieval: { hit: false, rank: null, candidate: hits[0]?.name ?? null },
+        candidates: hits,
+        error: err.message,
+      };
+    }
+  }
+
+  // ── No LLM, no strong match: return atoms for downstream assembly ──
+  return {
+    messages: [],
+    validation: { score: 0 },
+    strategy: 'fragment-candidates',
+    retrieval: { hit: false, rank: null, candidate: hits[0]?.name ?? null },
+    candidates: hits,
+  };
+}
+
+// Re-export session management so server.js / MCP tools can reset a session
+export { clearSession, getTurns, getDrift } from './session-store.js';