@adia-ai/a2ui-compose 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -12,6 +12,17 @@ generator graph.
 
 _No pending changes._
 
+## [0.3.1] - 2026-05-06
+
+**9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).
+
+This package itself ships **no source changes** in v0.3.1. The cut bumps version only — substantive content lives in [`@adia-ai/web-components`](https://github.com/adiahealth/gen-ui-kit/releases/tag/web-components-v0.3.1) (folder-per-trait restructure; barrel API unchanged).
+
+### Changed
+
+- `version`: `0.3.0` → `0.3.1`.
+- Internal `@adia-ai/*` dep ranges: unchanged at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).
+
 ## [0.3.0] - 2026-05-05
 
 **9-package lockstep cut + LLM subpath dropped.** All 9 published `@adia-ai/*` packages bump 0.2.5 → 0.3.0 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges bump `^0.2.0` → `^0.3.0`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "AdiaUI A2UI compose engine \u2014 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": {
@@ -39,4 +39,4 @@
     "@adia-ai/a2ui-validator": "^0.3.0",
     "@adia-ai/llm": "^0.3.0"
   }
-}
+}

package/strategies/registry.js

@@ -118,11 +118,39 @@ async function generateZettelAdapter(ctx) {
   };
 }
 
+async function generateChunkZettelAdapter(ctx) {
+  const { composeFromIntent } = await import('./zettel/chunk-synthesizer.js');
+  const result = await composeFromIntent({
+    intent: ctx.intent,
+    llmAdapter: ctx.llmAdapter || null,
+    maxAttempts: 2,
+  });
+
+  // Convert chunk-composition result to A2UI message shape.
+  const messages = result.html
+    ? [{ type: 'updateComponents', components: [{ id: 'chunk-root', component: 'article', html: result.html }] }]
+    : [];
+
+  return {
+    executionId: ctx.executionId,
+    messages,
+    validation: { score: result.html ? 70 : 0 },
+    strategy: result.source === 'retrieval' ? 'chunk-retrieval' : 'chunk-synthesis',
+    engine: 'chunk-zettel',
+    _debug: {
+      plan: result.plan || null,
+      warnings: result.warnings || [],
+      scopeDrift: result.scopeDrift || null,
+    },
+  };
+}
+
 export const ENGINES = {
   'monolithic-instant':  generateInstantAdapter,
   'monolithic-pro':      generateProAdapter,
   'monolithic-thinking': generateThinkingAdapter,
   'zettel':              generateZettelAdapter,
+  'chunk-zettel':        generateChunkZettelAdapter,
 };
 
 /**
@@ -147,7 +175,7 @@ export const ENGINES = {
  *   });
  *   generateUI({ engine: 'my-hybrid', intent: '...' });
  */
-const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel']);
+const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel', 'chunk-zettel']);
 
 export function registerEngine(name, generateFn) {
   if (typeof name !== 'string' || !name.length) {

package/strategies/zettel/chunk-synthesizer.js

@@ -40,31 +40,56 @@ const SCOPE_DRIFT_MIN_ACTUAL = 20;
 
 const SYSTEM_PROMPT = `You compose web-app pages by binding training chunks into named slots.
 
-You are given:
-  - A user intent (what they want to build).
-  - A catalog of available chunks. Each chunk is a discrete UI sample harvested
-    from a real page. Chunks have:
-      - name (stable ID)
-      - kind ("page", "panel", or "block")
-      - primary (the chunk's outermost element, e.g. "card-ui", "grid-ui")
-      - slots (only on page/panel chunks — named regions where blocks plug in)
-  - 1-3 example bindings as in-context anchors.
+## YOUR TASK
+
+Given a user intent and a catalog of chunks, return a JSON object that:
+1. SELECTS the most appropriate page-kind shell
+2. BINDS block/panel chunks into its slots
+
+## STEP 1 — SELECT A PAGE SHELL
+
+Page shells (kind=page or kind=panel) define the layout topology. Match the
+intent domain to the right shell — NEVER default to dashboard-admin-page for
+non-dashboard intents:
+
+| Shell | Domain | Slots |
+|-------|--------|-------|
+| dashboard-admin-page | Admin/analytics dashboards | page-header, page-content |
+| settings-page-shell | Settings, preferences, configuration | page-header, page-tabs, page-content |
+| form-page-shell | Auth forms, sign-in, sign-up, profile | page-header, form-content, page-footer |
+| marketing-page-shell | Landing pages, heroes, features, CTAs | hero, features, cta |
+| error-page-shell | Error states (404, 500, permission denied) | error-content, navigation |
+| editor-page-shell | Split-pane editors (code + preview) | editor-pane, preview-pane |
+| onb-step-shell | Onboarding wizards, multi-step flows | page-story, page-header, page-content, page-footer |
+| reg-step-shell | Registration flows, multi-step sign-up | page-story, page-header, page-content, page-footer |
+
+Selection rule: the shell whose DOMAIN matches the intent keywords wins.
+
+## STEP 2 — SELECT BLOCKS TO FILL SLOTS
+
+- Search the block catalog for chunks whose name contains intent keywords.
+- Prefer blocks whose primary tag matches the desired component (e.g.
+  "stat-ui" for stat cards, "chart-ui" for charts).
+- If a slot is optional and no matching block exists, OMIT it rather
+  than forcing a random block.
+- Never invent chunk names. Every bound name must appear in the catalog.
+
+## STEP 3 — RETURN JSON
 
 Return ONLY a JSON object shaped exactly like:
 {
-  "page": "<name of a page-kind chunk to use as the layout shell>",
+  "page": "<name of page-kind chunk>",
   "slot_bindings": {
-    "<slot-name>": "<bound chunk name>"        // single chunk
+    "<slot-name>": "<bound chunk name>"
     OR
-    "<slot-name>": ["<chunk1>", "<chunk2>"]    // ordered list of chunks
+    "<slot-name>": ["<chunk1>", "<chunk2>"]
   }
 }
 
 Rules:
 - The "page" must be a chunk with kind="page" or kind="panel".
-- Every slot you bind must be declared by the page chunk (do not invent slots).
-- Bound chunks should be kind="block" or kind="panel" — pages can't nest inside
-  pages.
+- Every slot key must be declared by the chosen page shell.
+- Every bound value must be a real chunk name from the catalog.
 - Return valid JSON. No prose, no comments, no markdown fences. Begin with "{".
 `;
 
@@ -78,8 +103,8 @@ function buildCatalogSummary(chunks) {
 }
 
 function buildExamples() {
-  // Hard-coded canonical example: "build me an admin dashboard". This anchors
-  // the LLM on the expected output shape.
+  // Four canonical examples spanning different domains. Diverse examples
+  // prevent the LLM from defaulting to dashboard-shaped output.
   return [
     {
       intent: 'admin dashboard with KPIs and a conversion funnel',
@@ -91,6 +116,38 @@ function buildExamples() {
         },
       },
     },
+    {
+      intent: 'sign-in form with email and password',
+      output: {
+        page: 'form-page-shell',
+        slot_bindings: {
+          'page-header': 'auth-signin-card-password',
+          'form-content': 'auth-email-entry',
+        },
+      },
+    },
+    {
+      intent: 'settings page with tabs for general and billing',
+      output: {
+        page: 'settings-page-shell',
+        slot_bindings: {
+          'page-header': 'settings-general-form',
+          'page-tabs': 'check-combinations-settings-group',
+          'page-content': 'settings-general-form',
+        },
+      },
+    },
+    {
+      intent: 'marketing landing hero with feature cards',
+      output: {
+        page: 'marketing-page-shell',
+        slot_bindings: {
+          hero: 'hero-cta-simple',
+          features: 'empty-state-action',
+          cta: 'button-primary',
+        },
+      },
+    },
   ];
 }
 
@@ -150,23 +207,31 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
   //
   // Restricted to kind=block: page/panel chunks are SKELETONS that need
   // slot-binding composition (Tier 2 handles them). Returning a skeleton
-  // directly from Tier-1 would emit a near-empty page; we only want the
-  // fast-path for atomic block patterns.
-  const hits = await searchChunksAsync(intent, { kind: 'block', limit: 5 });
-  if (hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE) {
-    const top = getChunk(hits[0].name);
+  // Fast path — deterministic keyword-first; embeddings as tie-breaker only.
+  // Embeddings can drift (e.g. "pane" matching "panel" boosting unrelated
+  // chunks). Sync keyword search is stable and keyword-discoverability is
+  // the baseline guarantee. We run both and prefer the sync result when
+  // it meets the threshold; only use async when sync is weak but async
+  // is strong (e.g. semantic match on content not captured by keywords).
+  const syncHits = searchChunks(intent, { kind: 'block', limit: 5 });
+  const asyncHits = await searchChunksAsync(intent, { kind: 'block', limit: 5 });
+
+  const syncTop = syncHits[0];
+  const asyncTop = asyncHits[0];
+  const useSync = syncTop && syncTop.score >= STRONG_RETRIEVAL_SCORE;
+  const useAsync = !useSync && asyncTop && asyncTop.score >= STRONG_RETRIEVAL_SCORE;
+
+  if (useSync || useAsync) {
+    const hit = useSync ? syncTop : asyncTop;
+    const top = getChunk(hit.name);
     const html = top.html || top.instances?.[0]?.html || '';
-    // Tier-1 fast path: sole bound chunk is the retrieved block. The gate
-    // is mostly a no-op here (ratio ≈ 1) but stays for symmetry — and to
-    // catch a corner case where retrieval returns a block that, post-render,
-    // expands far beyond its source (shouldn't happen, but worth detecting).
     const scopeDrift = computeScopeDrift(html, [top]);
     return {
       html,
       plan: null,
       source: 'retrieval',
-      score: hits[0].score,
-      cosineScore: hits[0].cosineScore,
+      score: hit.score,
+      cosineScore: hit.cosineScore,
       warnings: scopeDrift.drift
         ? [`scope drift: ${scopeDrift.actual} components in HTML vs ${scopeDrift.expected} in bound chunk (ratio ${scopeDrift.ratio.toFixed(2)}×)`]
         : [],
@@ -211,15 +276,16 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
   // Trace: snapshot of the retrieval log for the issue-reporter to surface
   // verbatim on bug tickets. Recorded once before the retry loop so it
   // describes what the LLM actually saw.
+  const tier1HitList = useSync ? syncHits : (useAsync ? asyncHits : []);
   const retrievalTrace = {
-    tier1Hits: hits.slice(0, 5).map((h) => ({
+    tier1Hits: tier1HitList.slice(0, 5).map((h) => ({
       name: h.name,
       score: Number(h.score.toFixed(3)),
       kind: h.kind,
       cosineScore: h.cosineScore != null ? Number(h.cosineScore.toFixed(3)) : null,
     })),
     tier1Threshold: STRONG_RETRIEVAL_SCORE,
-    tier1Pass: hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE,
+    tier1Pass: tier1HitList.length > 0 && tier1HitList[0].score >= STRONG_RETRIEVAL_SCORE,
     catalogSize: filtered.length,
     catalogPageNames: pageChunks.map((c) => c.name),
     catalogPanelNames: panelChunks.map((c) => c.name),