@adia-ai/a2ui-mcp 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -9,8 +9,124 @@ zettel strategies.
 
 ## [Unreleased]
 
+---
+
+## [0.0.3] - 2026-04-28
+
+Same-day follow-up to `0.0.2` shipped earlier today. Wires the corpus
+embedding vectors (from `@adia-ai/a2ui-corpus@0.0.4`) into the chunk
+retrieval path so the synthesizer mixes-and-matches against semantic
+similarity, not just keyword overlap.
+
+### Added
+
+- **`chunk-embedding-retriever.js`** (`packages/a2ui/retrieval/`) — sibling
+  to the existing pattern-embedding retriever. Lazy-loads
+  `chunk-embeddings.json`, scores cosine similarity against the same
+  provider that built the index. Graceful no-op when index is missing or
+  no API key is available.
+- **`searchChunksAsync(query, opts)`** in `chunk-library.js` — embedding-
+  blended search. Returns top candidates ranked by `keyword + 5×cosine`
+  when embeddings are available; falls back to keyword-only otherwise.
+  Sync `searchChunks()` is preserved for callers that want the keyword
+  floor without the network round-trip.
+
 ### Changed
-- Registry / transpilation scripts at `packages/web-components/scripts/a2ui-to-html.cjs` and `packages/web-components/scripts/mcp-pipeline.cjs` now mirror the canonical `packages/web-components/a2ui/registry.js` for all A2UI component → custom-element mappings. Previously these scripts had several stale mappings that diverged from the runtime registry.
+
+- `chunk-synthesizer.composeFromIntent()` — both tier-1 retrieval AND
+  tier-2 pre-search now go through `searchChunksAsync` instead of the
+  keyword-only `searchChunks`. The pre-search filters the prompt token
+  budget more accurately; the retrieval-first path catches more direct
+  hits before the LLM is invoked.
+
+### Measured impact
+
+`eval:chunk-synthesis` (10 hold-out intents, real Anthropic LLM):
+
+| | 0.0.2 (keyword) | **0.0.3 (semantic)** |
+|---|---|---|
+| Retrieval-tier hits | 7/10 | **9/10** |
+| Synthesis-tier attempts | 3 | **1** |
+| Synthesis plans validated | 3/3 | 1/1 |
+| Total time | 5.0s | 5.1s |
+
+Examples that flipped from synthesis → direct retrieval:
+- "kpi grid with 4 stat cards" → matches `dashboard-kpi-grid` cleanly.
+- "conversion funnel chart" → matches `dashboard-funnel`.
+
+The remaining synthesis intent ("recovery page with backup-code form +
+contact-support link") is genuinely novel — it composes from parts that
+don't have a 1:1 chunk and exercises the slot-validator path correctly.
+
+### Dependencies
+
+- Bumps `@adia-ai/a2ui-corpus` requirement from `^0.0.3` to `^0.0.4`.
+
+---
+
+## [0.0.2] - 2026-04-28
+
+Adds **gen-UI training-chunk tools** that expose the new chunk corpus
+(shipped in `@adia-ai/a2ui-corpus@0.0.3`) via the MCP transport. Also
+adds a chunk-aware composition synthesizer that mixes-and-matches chunks
+when retrieval can't find a 1:1 match — the LLM picks a page chunk + binds
+block/panel chunks to its slots, validated against the chunk catalog
+before HTML is materialized.
+
+### Added (MCP tools)
+
+- **`search_chunks(query, kind?, limit?)`** — keyword search over the
+  chunk corpus. Filters by `kind` (`block` | `panel` | `page`); returns
+  ranked candidates with relevance score, primary tag, and chunk name.
+- **`get_chunk(name)`** — full record for a single chunk by name. For
+  reusable slot chunks (e.g. `auth-card-header`, `reg-step-header`)
+  returns an `instances` array — one entry per page.
+- **`lookup_chunk(component_name)`** — list every chunk whose primary
+  element is `<component_name>`. Useful for "show me every page that
+  opens with a `<card-ui raw>`" or "every chunk built around a
+  `<grid-ui>` root."
+- **`compose_from_chunks(intent?, plan?, max_attempts?)`** — two-tier
+  composition tool: retrieval-first (returns matched chunk HTML
+  directly), synthesis-fallback (LLM picks a page chunk + binds
+  block/panel chunks to its slots when retrieval is weak). The
+  synthesizer mirrors the existing fragment synthesizer's prompt
+  pattern, repointed at the chunk catalog. Pre-search filters the
+  catalog to ~30 candidates before the LLM sees them. Plan-only
+  invocation skips the LLM and just materializes HTML from a
+  pre-baked binding.
+
+### Added (engine internals)
+
+- `packages/a2ui/compose/engines/zettel/chunk-composer.js` —
+  HTML-string-level composer that walks a page chunk and substitutes
+  each `data-chunk-slot` region with the bound block-level chunks'
+  HTML. Companion `validatePlan()` checks slot names + chunk-kind
+  contracts before composition.
+- `packages/a2ui/compose/engines/zettel/chunk-synthesizer.js` —
+  LLM-driven mix-and-match composition; pre-searches the catalog,
+  builds a prompt with a one-shot in-context example, validates the
+  LLM's binding plan against the catalog, retries with feedback on
+  validation failure (default 2 attempts).
+
+### Smoke
+
+- `npm run smoke:chunks` (33/33 passing, 2026-04-28) — covers
+  chunk-library indexing, retrieval scoring, plan validation, plan
+  composition, and synthesis fallback path with a stub LLM adapter.
+
+### Convention reference
+
+- Spec: [`docs/specs/genui-chunk-marker.md`](../../../docs/specs/genui-chunk-marker.md).
+- Plan: [`docs/plans/training-pipeline-chunk-harvest-2026-04-27.md`](../../../docs/plans/training-pipeline-chunk-harvest-2026-04-27.md).
+
+### Other
+
+- Registry / transpilation scripts at
+  `packages/web-components/scripts/a2ui-to-html.cjs` and
+  `packages/web-components/scripts/mcp-pipeline.cjs` now mirror the
+  canonical `packages/web-components/a2ui/registry.js` for all A2UI
+  component → custom-element mappings. Previously these scripts had
+  several stale mappings that diverged from the runtime registry.
 
 ---
 

package/README.md

@@ -6,9 +6,9 @@ feedback loop as stdio tools for Claude Desktop, Claude Code, and any
 other MCP-speaking host.
 
 > Runtime only. Generation logic lives in `@adia-ai/a2ui-compose`; UI atoms in
-> [`@adia-ai/web-components`](../web-components); the A2UI protocol runtime
+> [`@adia-ai/web-components`](../../web-components); the A2UI protocol runtime
 > (renderer, registry, streams, wiring) in
-> [`@adia-ai/a2ui-utils`](../a2ui/utils); corpus in
+> [`@adia-ai/a2ui-utils`](../utils); corpus in
 > [`@adia-ai/a2ui-corpus`](../corpus).
 
 ## Quick start
@@ -42,31 +42,35 @@ export GEMINI_API_KEY=AIza…
 
 ## Tools
 
-The server registers 21 tools. Shape is stable; argument schemas via Zod.
-
-| Tool                   | What it does                                              |
-|------------------------|-----------------------------------------------------------|
-| `generate_ui`          | Intent → A2UI tree. Engine (`monolithic`/`zettel`) + mode. |
-| `validate_schema`      | Run the 15-check validator on an A2UI tree; returns 0-100. |
-| `classify_intent`      | Extract concepts, entities, implied components, steelman.  |
-| `lookup_component`     | Resolve a component name (alias-aware) to its schema.      |
-| `get_component_map`    | Full tag→class map including alias normalizations.         |
-| `search_patterns`      | Keyword-rank the monolithic pattern corpus.                |
-| `assemble_context`     | Build the system prompt context for a given intent.        |
-| `check_anti_patterns`  | Scan a tree for canonical anti-patterns (chart-legend, …). |
-| `get_traits`           | List trait catalog + their host-binding rules.             |
-| `convert_html`         | Raw HTML → best-effort A2UI tree (import path).            |
-| `get_wiring_catalog`   | Declarative wiring-engine recipes.                         |
-| `import_pattern`       | Commit a generated result into the pattern library.        |
-| `submit_feedback`      | Append a user-feedback event to the feedback store.        |
-| `get_quality_metrics`  | Aggregate pass/fail scores over a window.                  |
-| `get_training_gaps`    | Intents that currently miss coverage.                      |
-| `run_eval`             | Run the held-out benchmark; return pass/fail per intent.   |
-| `get_fragment`         | Fetch a single zettel fragment by id.                      |
-| `get_composition`      | Fetch a named multi-fragment composition.                  |
-| `resolve_composition`  | Expand a composition reference into its fragments.         |
-| `get_graph`            | Dump the zettel fragment-dependency graph.                 |
-| `zettel_stats`         | Corpus counts (fragments, compositions, reuse ratio, …).   |
+The server registers 25 tools. Shape is stable; argument schemas via Zod.
+
+| Tool                    | What it does                                              |
+|-------------------------|-----------------------------------------------------------|
+| `generate_ui`           | Intent → A2UI tree. Engine (`monolithic`/`zettel`) + mode. |
+| `validate_schema`       | Run the 15-check validator on an A2UI tree; returns 0-100. |
+| `classify_intent`       | Extract concepts, entities, implied components, steelman.  |
+| `lookup_component`      | Resolve a component name (alias-aware) to its schema.      |
+| `get_component_map`     | Full tag→class map including alias normalizations.         |
+| `search_patterns`       | Keyword-rank the monolithic pattern corpus.                |
+| `assemble_context`      | Build the system prompt context for a given intent.        |
+| `check_anti_patterns`   | Scan a tree for canonical anti-patterns (chart-legend, …). |
+| `get_traits`            | List trait catalog + their host-binding rules.             |
+| `convert_html`          | Raw HTML → best-effort A2UI tree (import path).            |
+| `get_wiring_catalog`    | Declarative wiring-engine recipes.                         |
+| `import_pattern`        | Commit a generated result into the pattern library.        |
+| `submit_feedback`       | Append a user-feedback event to the feedback store.        |
+| `get_quality_metrics`   | Aggregate pass/fail scores over a window.                  |
+| `get_training_gaps`     | Intents that currently miss coverage.                      |
+| `run_eval`              | Run the held-out benchmark; return pass/fail per intent.   |
+| `get_fragment`          | Fetch a single zettel fragment by id.                      |
+| `get_composition`       | Fetch a named multi-fragment composition.                  |
+| `resolve_composition`   | Expand a composition reference into its fragments.         |
+| `get_graph`             | Dump the zettel fragment-dependency graph.                 |
+| `zettel_stats`          | Corpus counts (fragments, compositions, reuse ratio, …).   |
+| **`search_chunks`**     | Semantic + keyword search over the gen-UI training-chunk corpus (since 0.0.2). |
+| **`get_chunk`**         | Full record (HTML + metadata + slots) for one chunk.       |
+| **`lookup_chunk`**      | List every chunk whose primary element is `<component>`.   |
+| **`compose_from_chunks`** | Retrieval-first / LLM-mix-and-match composition. Picks a page chunk + binds block/panel chunks to its slots when retrieval is weak. Validator enforces slot+kind contracts. **Embedding-blended retrieval as of 0.0.3** (was keyword-only in 0.0.2). |
 
 ## Layout
 
@@ -116,12 +120,12 @@ npm run eval:diff -- --engine zettel
   └─────────────┘                      │
                                        ├── @adia-ai/a2ui-compose          (engines, validator, LLM bridge)
                                        ├── @adia-ai/a2ui-corpus (catalog, fragments, feedback)
-                                       └── @adiahealth/web-components  (component schemas via .a2ui.json)
+                                       └── @adia-ai/web-components  (component schemas via .a2ui.json)
 ```
 
 On start, the server:
 
-1. Loads the component catalog (`gen-ui-training/catalog-a2ui_0_9.json`)
+1. Loads the component catalog (`@adia-ai/a2ui-corpus/catalog-a2ui_0_9.json`)
 2. Lazy-initializes the zettel corpus on first `generate_ui`/`zettel_*` call
 3. Resolves LLM adapter from env vars
 4. Registers tools + opens stdio transport

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     "@adia-ai/a2ui-compose": "^0.0.1",
     "@adia-ai/a2ui-retrieval": "^0.0.1",
     "@adia-ai/a2ui-validator": "^0.0.1",
-    "@adia-ai/a2ui-corpus": "^0.0.1",
+    "@adia-ai/a2ui-corpus": "^0.0.4",
     "zod": "^3.24.0"
   }
 }

package/scripts/eval-chunk-synthesis.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Real-LLM eval set for the chunk-aware composition synthesizer.
+ *
+ * Walks a hold-out set of intents that DON'T have a 1:1 chunk match in the
+ * corpus and exercises the full retrieval-first → synthesis-fallback path.
+ * For each intent, records:
+ *   - which tier handled it (retrieval direct hit vs LLM synthesis)
+ *   - whether HTML was produced
+ *   - whether the synthesizer's plan validated against slot/kind contracts
+ *   - composed HTML byte length (rough proxy for "not empty")
+ *
+ * Pass criterion: ≥ 80% of intents produce non-empty HTML; all synthesizer
+ * plans pass the slot+kind validator.
+ *
+ * Usage:
+ *   node packages/a2ui/mcp/scripts/eval-chunk-synthesis.mjs
+ *   ANTHROPIC_API_KEY=… node packages/a2ui/mcp/scripts/eval-chunk-synthesis.mjs
+ */
+
+import '../../../../scripts/load-env.mjs';
+import { composeFromIntent } from '../../compose/engines/zettel/chunk-synthesizer.js';
+import { createAdapter } from '../../compose/llm/llm-bridge.js';
+
+// Hold-out intents — chosen to NOT have a 1:1 chunk match (so synthesis path
+// is exercised). Mix of dashboard-shape, auth-shape, and novel composites.
+const INTENTS = [
+  // Dashboard composites that don't exist as a single chunk:
+  'admin dashboard with KPI grid and conversion funnel',
+  'analytics page with audience KPIs and a country list',
+  'reports page with a transactions table and a sparkline grid',
+
+  // Auth-card variations that aren't pre-baked:
+  'sign-in page with email + password + remember-me + magic-link alternative',
+  'recovery page with backup-code form and contact-support link',
+
+  // Generic page-shaped composites:
+  'page with a sticky header and a tabbed body',
+  'data-rich settings page with a members table and an integrations grid',
+
+  // Things that should retrieve directly (control group):
+  'kpi grid with 4 stat cards', // → likely matches dashboard-kpi-grid via search
+  'conversion funnel chart',     // → dashboard-funnel
+  'sign in form with email',     // → auth-signin-card-email
+];
+
+const startedAt = Date.now();
+const results = [];
+
+console.log(`▶ chunk-synthesis eval — ${INTENTS.length} intents\n`);
+
+const llmAdapter = await createAdapter();
+
+for (const intent of INTENTS) {
+  const t0 = Date.now();
+  let row = { intent, ms: 0, source: null, hasHtml: false, htmlBytes: 0, planValid: null, error: null };
+  try {
+    const result = await composeFromIntent({ intent, llmAdapter, maxAttempts: 2 });
+    row.ms = Date.now() - t0;
+    row.source = result.source;
+    row.hasHtml = !!result.html;
+    row.htmlBytes = result.html ? result.html.length : 0;
+    row.planValid = result.synthesis ? !!result.synthesis.validation?.ok : null;
+    row.warnings = (result.warnings || []).length;
+  } catch (e) {
+    row.ms = Date.now() - t0;
+    row.error = e.message;
+  }
+  results.push(row);
+  const flag = row.hasHtml ? '✓' : '✗';
+  const tag = row.source === 'retrieval' ? '[ret]' : row.source === 'synthesis' ? '[syn]' : '[err]';
+  console.log(`  ${flag} ${tag} ${row.ms.toString().padStart(5)}ms  ${intent}`);
+  if (row.error) console.log(`      error: ${row.error}`);
+  if (row.warnings) console.log(`      ${row.warnings} warning(s)`);
+}
+
+const passed = results.filter((r) => r.hasHtml).length;
+const passRate = passed / results.length;
+const synthAttempts = results.filter((r) => r.source === 'synthesis');
+const retrievalAttempts = results.filter((r) => r.source === 'retrieval');
+const synthValidPlans = synthAttempts.filter((r) => r.planValid).length;
+
+console.log(`\n── Summary ──`);
+console.log(`  Total intents: ${results.length}`);
+console.log(`  Produced HTML: ${passed} (${(passRate * 100).toFixed(0)}%)`);
+console.log(`  Retrieval-tier hits: ${retrievalAttempts.length}`);
+console.log(`  Synthesis-tier attempts: ${synthAttempts.length}`);
+if (synthAttempts.length) {
+  console.log(`  Synthesis plans validated: ${synthValidPlans}/${synthAttempts.length}`);
+}
+console.log(`  Total time: ${((Date.now() - startedAt) / 1000).toFixed(1)}s`);
+
+const passThreshold = 0.8;
+if (passRate >= passThreshold) {
+  console.log(`\n✓ PASS — ≥${passThreshold * 100}% intents produced HTML`);
+  process.exit(0);
+} else {
+  console.log(`\n✗ FAIL — pass rate ${(passRate * 100).toFixed(0)}% < ${passThreshold * 100}% threshold`);
+  process.exit(1);
+}

package/scripts/test-chunks.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Smoke test for the gen-UI chunk MCP tools.
+ *
+ * Tests search_chunks / get_chunk / lookup_chunk against known chunks
+ * harvested from site/pages/* and corpus/exemplars/*.
+ *
+ * Wired into:
+ *   - npm run smoke:chunks
+ *   - Phase D verification gate (docs/plans/training-pipeline-chunk-harvest-2026-04-27.md)
+ */
+
+import {
+  getChunk,
+  getChunkIndex,
+  lookupChunksByPrimary,
+  searchChunks,
+} from '../../corpus/scripts/chunk-library.js';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(name, cond, detail) {
+  if (cond) { passed++; console.log(`  ✓ ${name}`); }
+  else { failed++; failures.push(`${name}: ${detail || 'failed'}`); console.log(`  ✗ ${name}: ${detail || 'failed'}`); }
+}
+
+console.log('── chunk-library smoke ──');
+
+const idx = getChunkIndex();
+assert('index loaded', idx && idx.unique_names > 0, idx ? `got ${idx.unique_names}` : 'no index');
+assert('expected counts', idx && idx.unique_names >= 700 && idx.total_instances >= 800,
+  idx ? `${idx.unique_names} unique / ${idx.total_instances} instances (need ≥700/800)` : 'no index');
+assert('by_kind covers block + panel + page', idx && idx.by_kind.block && idx.by_kind.panel && idx.by_kind.page,
+  idx ? JSON.stringify(idx.by_kind) : 'no index');
+
+console.log('\n── get_chunk ──');
+
+const signin = getChunk('auth-signin-card-email');
+assert('get_chunk(auth-signin-card-email) returns record', signin && signin.name === 'auth-signin-card-email');
+assert('record has primary=card-ui', signin && signin.primary === 'card-ui',
+  signin ? `got primary=${signin.primary}` : '');
+assert('record HTML is non-empty', signin && typeof signin.html === 'string' && signin.html.length > 100);
+
+const kpi = getChunk('dashboard-kpi-grid');
+assert('get_chunk(dashboard-kpi-grid) returns record', kpi && kpi.name === 'dashboard-kpi-grid');
+assert('kpi primary=grid-ui', kpi && kpi.primary === 'grid-ui',
+  kpi ? `got primary=${kpi.primary}` : '');
+
+const adminPage = getChunk('dashboard-admin-page');
+assert('get_chunk(dashboard-admin-page) returns record', adminPage && adminPage.name === 'dashboard-admin-page');
+assert('admin-page is kind=page', adminPage && adminPage.kind === 'page',
+  adminPage ? `got kind=${adminPage.kind}` : '');
+assert('admin-page declares page-header + page-content slots',
+  adminPage && (adminPage.slots || []).map(s => s.name).includes('page-header') &&
+  (adminPage.slots || []).map(s => s.name).includes('page-content'),
+  adminPage ? JSON.stringify((adminPage.slots || []).map(s => s.name)) : '');
+
+const reusable = getChunk('reg-step-header');
+assert('reusable slot chunk has instances array', reusable && Array.isArray(reusable.instances) && reusable.instances.length >= 18,
+  reusable ? `instances=${reusable.instances?.length}` : '');
+
+const missing = getChunk('definitely-does-not-exist');
+assert('non-existent chunk returns null', missing === null);
+
+console.log('\n── search_chunks ──');
+
+const results = searchChunks('dashboard');
+assert('search_chunks(dashboard) returns ≥10', results.length >= 10, `got ${results.length}`);
+assert('search results sorted by score', results.length === 0 || results.every((r, i, a) => i === 0 || a[i - 1].score >= r.score));
+
+const blockOnly = searchChunks('dashboard', { kind: 'block' });
+assert('kind=block filter excludes pages', blockOnly.every((r) => r.kind === 'block'));
+
+const auth = searchChunks('auth signin');
+assert('search_chunks(auth signin) finds auth-signin-card-email',
+  auth.some((r) => r.name === 'auth-signin-card-email'));
+
+const code = searchChunks('code language');
+assert('search_chunks(code language) finds code-language', code.some((r) => r.name === 'code-language'));
+
+console.log('\n── lookup_chunk ──');
+
+const cardChunks = lookupChunksByPrimary('card-ui');
+assert('lookup_chunk(card-ui) returns ≥5', cardChunks.length >= 5, `got ${cardChunks.length}`);
+assert('all card-ui chunks have primary=card-ui', cardChunks.every((c) => c.primary === 'card-ui'));
+
+const drawerChunks = lookupChunksByPrimary('drawer-ui');
+assert('lookup_chunk(drawer-ui) returns ≥10', drawerChunks.length >= 10, `got ${drawerChunks.length}`);
+
+const articleChunks = lookupChunksByPrimary('article');
+assert('lookup_chunk(article) finds dashboard-admin-page',
+  articleChunks.some((c) => c.name === 'dashboard-admin-page'));
+
+// ── chunk-composer + chunk-synthesizer ──
+import { composeFromPlan, validatePlan } from '../../compose/engines/zettel/chunk-composer.js';
+import { composeFromIntent } from '../../compose/engines/zettel/chunk-synthesizer.js';
+
+console.log('\n── validatePlan ──');
+
+const goodPlan = {
+  page: 'dashboard-admin-page',
+  slot_bindings: {
+    'page-header': 'dashboard-page-header',
+    'page-content': ['dashboard-overview-panel', 'dashboard-funnel'],
+  },
+};
+const v1 = validatePlan(goodPlan);
+assert('validatePlan(goodPlan) ok', v1.ok, JSON.stringify(v1.errors));
+
+const badPagePlan = { page: 'definitely-not-real', slot_bindings: {} };
+const v2 = validatePlan(badPagePlan);
+assert('validatePlan(bad page) fails', !v2.ok && v2.errors.length > 0);
+
+const badSlotPlan = {
+  page: 'dashboard-admin-page',
+  slot_bindings: { 'made-up-slot': 'dashboard-funnel' },
+};
+const v3 = validatePlan(badSlotPlan);
+assert('validatePlan(undeclared slot) fails', !v3.ok && v3.errors.some((e) => e.includes('slot')));
+
+const badBoundPlan = {
+  page: 'dashboard-admin-page',
+  slot_bindings: { 'page-content': 'no-such-chunk' },
+};
+const v4 = validatePlan(badBoundPlan);
+assert('validatePlan(bad bound chunk) fails', !v4.ok && v4.errors.some((e) => e.includes('not found')));
+
+console.log('\n── composeFromPlan ──');
+
+const composed = composeFromPlan(goodPlan);
+assert('composeFromPlan returns html', composed.html && composed.html.length > 1000,
+  composed.html ? `len=${composed.html.length}` : 'null');
+assert('composed html includes admin-page wrapper', composed.html && composed.html.includes('dashboard-admin-page'));
+assert('composed html injects funnel content',
+  composed.html && composed.html.includes('Conversion funnel'),
+  composed.html ? 'no funnel text found' : 'no html');
+
+console.log('\n── composeFromIntent (retrieval-first, no LLM) ──');
+
+// Use a stub adapter — synthesis path shouldn't be hit when retrieval matches
+const stubLLM = { complete: async () => ({ content: '{"page":"dashboard-admin-page","slot_bindings":{"page-content":["dashboard-funnel"]}}' }) };
+
+const direct = await composeFromIntent({ intent: 'dashboard-kpi-grid', llmAdapter: stubLLM });
+assert('retrieval direct hit returns html', direct.html && direct.html.length > 50,
+  direct.warnings?.join('; '));
+assert('retrieval source labeled correctly', direct.source === 'retrieval',
+  `got ${direct.source}`);
+
+const synthesized = await composeFromIntent({ intent: 'admin dashboard with KPIs', llmAdapter: stubLLM });
+assert('synthesis path produces html when retrieval is weak',
+  synthesized.html && synthesized.html.length > 1000,
+  synthesized.warnings?.join('; ') || 'no html');
+// Source could be either retrieval or synthesis depending on score — both are
+// acceptable as long as we got HTML out.
+assert('synthesis source labeled', ['retrieval', 'synthesis'].includes(synthesized.source));
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) {
+  console.log('\nFailures:');
+  for (const f of failures) console.log(`  ${f}`);
+  process.exit(1);
+}

package/server.js

@@ -19,7 +19,7 @@
  */
 
 // ── Load .env for API keys (Node doesn't read .env automatically) ──
-import '../../scripts/load-env.mjs';
+import '../../../scripts/load-env.mjs';
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -66,6 +66,23 @@ console.error(
   `[adiaui-mcp] zettel corpus: ${_zettelBoot.fragmentCount} fragments, ${_zettelBoot.compositionCount} compositions`,
 );
 
+// ── Gen-UI training-chunk corpus ──
+import {
+  getChunk as getGenUIChunk,
+  getChunkIndex,
+  lookupChunksByPrimary,
+  searchChunks as searchGenUIChunks,
+} from '../corpus/scripts/chunk-library.js';
+
+const _chunkIndex = getChunkIndex();
+if (_chunkIndex) {
+  console.error(
+    `[adiaui-mcp] gen-ui chunks: ${_chunkIndex.unique_names} unique chunks (${_chunkIndex.total_instances} instances; block=${_chunkIndex.by_kind.block || 0}, panel=${_chunkIndex.by_kind.panel || 0}, page=${_chunkIndex.by_kind.page || 0})`,
+  );
+} else {
+  console.error('[adiaui-mcp] gen-ui chunks: index not found — run `npm run harvest:chunks`');
+}
+
 // ── Server ──
 
 const server = new McpServer({
@@ -547,6 +564,189 @@ server.tool(
   },
 );
 
+// ── Gen-UI training-chunk tools ──────────────────────────────────────
+// Spec: docs/specs/genui-chunk-marker.md (Draft v0.1.0).
+// Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md.
+
+server.tool(
+  'search_chunks',
+  `Search the gen-UI training-chunk corpus by keyword.
+
+The chunk corpus comes from \`packages/a2ui/corpus/chunks/\` — JSON records
+extracted from every \`[data-chunk]\` element in site/pages/* and the corpus
+exemplars. There are three kinds:
+  - block (default): atomic UI fragment (KPI grid, sign-in form, table)
+  - panel: tab-panel fragment of a page (e.g. dashboard-overview-panel)
+  - page: full-page composition (e.g. dashboard-admin-page)
+
+Returns ranked candidates with chunk name, kind, primary tag, and a relevance
+score. Use \`get_chunk\` to fetch the full record (HTML + slot bindings + nested
+chunks) for a specific name.`,
+  {
+    query: z.string().describe('Keyword query — chunk name fragment, intent words, primary-tag name'),
+    kind: z.enum(['block', 'panel', 'page']).optional().describe('Filter by chunk kind'),
+    limit: z.number().int().min(1).max(50).default(20).describe('Max results'),
+  },
+  async ({ query, kind, limit }) => {
+    const results = searchGenUIChunks(query, { kind, limit });
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ query, kind: kind || 'any', count: results.length, results }, null, 2),
+      }],
+    };
+  },
+);
+
+server.tool(
+  'get_chunk',
+  `Fetch the full record for a single gen-UI training chunk by name.
+
+Returns the chunk's bounding HTML, slot annotations, nested chunk names, and
+metadata (primary tag, kind, source page). For chunks that appear on multiple
+pages (reusable slot chunks like \`auth-card-header\`, \`reg-step-header\`),
+returns an \`instances\` array — one entry per page where the chunk appears.
+
+The HTML is suitable for direct rendering / inclusion in an A2UI message
+construction prompt.`,
+  {
+    name: z.string().describe('The chunk name, e.g. "dashboard-kpi-grid", "auth-signin-card-email", "code-language"'),
+  },
+  async ({ name }) => {
+    const rec = getGenUIChunk(name);
+    if (!rec) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'chunk not found', name }, null, 2) }],
+      };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(rec, null, 2) }] };
+  },
+);
+
+server.tool(
+  'lookup_chunk',
+  `List every chunk whose primary element is \`<component_name>\`.
+
+Useful for "show me every page that opens with a \`<card-ui raw>\`" or "every
+chunk built around a \`<grid-ui>\` root." Returns chunk names + kinds + sources.
+
+Pair with \`get_chunk\` to fetch full records for any of the returned names.`,
+  {
+    component_name: z.string().describe('Component tag name, e.g. "card-ui", "grid-ui", "drawer-ui"'),
+  },
+  async ({ component_name }) => {
+    const recs = lookupChunksByPrimary(component_name);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          component: component_name,
+          count: recs.length,
+          chunks: recs.map((r) => ({
+            name: r.name,
+            kind: r.kind,
+            page: r.page || r.instances?.[0]?.page,
+            slots: (r.slots || r.instances?.[0]?.slots || []).map((s) => s.name),
+            nested: r.nested || r.instances?.[0]?.nested || [],
+          })),
+        }, null, 2),
+      }],
+    };
+  },
+);
+
+// ── Chunk-aware composition synthesizer (Phase C.2) ──────────────────
+// Mix-and-match: when retrieval returns no strong match, the LLM picks a
+// page chunk + binds block/panel chunks to its slots. Validator checks
+// chunk names + kind contracts; composer materializes to HTML.
+//
+// Spec: docs/specs/genui-chunk-marker.md (§ "Harvester contract", future:
+// composition reasoning). Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md.
+
+import { composeFromIntent as composeFromChunksImpl } from '../compose/engines/zettel/chunk-synthesizer.js';
+import { composeFromPlan, validatePlan } from '../compose/engines/zettel/chunk-composer.js';
+import { createAdapter as createLLMAdapter } from '../compose/llm/llm-bridge.js';
+
+server.tool(
+  'compose_from_chunks',
+  `Compose a UI page from training chunks — retrieval-first, synthesis-fallback.
+
+Mix-and-match composition for intents that don't have a 1:1 chunk match. Workflow:
+  1. Pure-retrieval tier: if \`search_chunks\` returns a strong direct match, return
+     that chunk's HTML immediately (no LLM call).
+  2. Synthesis tier: when retrieval is weak, the LLM picks a page-kind chunk and
+     binds block/panel chunks to its named slots. Output validated against the
+     chunk catalog (slot names exist, bound chunks exist, kinds match).
+
+Returns the composed HTML string + a binding plan describing which chunks plug
+where. Useful when the prompt is novel ("dashboard with KPI grid + funnel +
+country list") and no exact chunk has all those parts together — the LLM mixes
+and matches from the corpus.
+
+Two-call mode also available via \`plan\` parameter — pass a pre-baked binding
+plan to skip the LLM call and just materialize HTML.`,
+  {
+    intent: z.string().optional().describe('Natural-language description of what to build (uses LLM synthesis)'),
+    plan: z.object({
+      page: z.string(),
+      slot_bindings: z.record(z.union([z.string(), z.array(z.string())])),
+    }).optional().describe('Pre-baked binding plan (skips LLM, materializes directly)'),
+    max_attempts: z.number().int().min(1).max(5).default(2).describe('LLM retry budget for synthesis'),
+  },
+  async ({ intent, plan, max_attempts }) => {
+    if (plan) {
+      const validation = validatePlan(plan);
+      if (!validation.ok) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: 'invalid plan', errors: validation.errors }, null, 2) }],
+        };
+      }
+      const result = composeFromPlan(plan);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          html: result.html,
+          plan: result.plan,
+          warnings: result.warnings,
+          source: 'plan',
+        }, null, 2) }],
+      };
+    }
+
+    if (!intent) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or plan' }, null, 2) }],
+      };
+    }
+
+    try {
+      const llmAdapter = await createLLMAdapter();
+      const result = await composeFromChunksImpl({
+        intent,
+        llmAdapter,
+        maxAttempts: max_attempts,
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          html: result.html,
+          plan: result.plan,
+          source: result.source,
+          score: result.score,
+          warnings: result.warnings,
+          synthesis: result.synthesis ? { attempts: result.synthesis.attempts } : undefined,
+        }, null, 2) }],
+      };
+    } catch (e) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+      };
+    }
+  },
+);
+
 // ── Start ──
 
 async function main() {