@adia-ai/a2ui-compose 0.0.1

package/engines/monolithic/generate-thinking.js

@@ -0,0 +1,211 @@
+/**
+ * @adia-ai/a2ui-compose — monolithic engine, thinking mode.
+ *
+ * Extracted from engine/generator.js per spec §11 Phase 2. Shares state
+ * (ArtifactStore, PipelineEngine) via engine/state.js. Pure helpers live
+ * in engines/monolithic/_shared.js.
+ */
+
+import { validateSchema } from '../../../validator/validator.js';
+import { validateMessages as validateCatalog } from '../../../validator/catalog-validator.js';
+import { getContext, searchBlocksSemantic, lookupDomain } from '../../engine/reference.js';
+import { assessClarity } from '../../../retrieval/clarity.js';
+import { feedbackStore } from '../../../retrieval/feedback-store.js';
+import { store, engine } from '../../engine/state.js';
+import { isRecording } from '../../../retrieval/dialog-recorder.js';
+import {
+  buildSystemPrompt,
+  buildChatMessages,
+  parseA2UIResponse,
+  buildRepairPrompt,
+  generateSuggestions,
+} from './_shared.js';
+
+export async function generateThinking({ intent, executionId, storeId, llmAdapter, analysis, priorComponentsFromPayload }) {
+  // Note: thinking mode currently composes from scratch each turn. The
+  // priorComponentsFromPayload param is accepted for forward-compatibility
+  // with multi-turn thinking iterations; not used in this pass yet.
+  void priorComponentsFromPayload;
+  const execId = executionId;
+  const searchQuery = analysis?.steelman || intent;
+  const analysisHint = (analysis?.analyzed && (
+    analysis.steelman !== analysis.raw ||
+    analysis.impliedComponents?.length ||
+    analysis.concepts?.length
+  ))
+    ? [
+        analysis.steelman && analysis.steelman !== analysis.raw ? `BRIEF: ${analysis.steelman}` : null,
+        analysis.impliedComponents?.length ? `EXPECTED COMPONENTS: ${analysis.impliedComponents.join(', ')}` : null,
+        analysis.concepts?.length ? `CONCEPTS: ${analysis.concepts.join(', ')}` : null,
+        analysis.styleHints?.length ? `STYLE: ${analysis.styleHints.join(', ')}` : null,
+      ].filter(Boolean).join('\n') + '\n\n'
+    : '';
+
+  // ── Stage 1: Interpret ──
+  const domain = lookupDomain(intent);
+  engine.submitStage(execId, 'interpret', {
+    domain,
+    intent,
+    confidence: domain.confidence,
+  });
+
+  // ── Clarity gate (defense-in-depth) ──
+  if (domain.confidence === 0) {
+    const clarity = assessClarity(intent, domain);
+    if (!clarity.clear) {
+      engine.submitStage(execId, 'clarify', { clarity, reason: 'no-ui-signals' });
+      return {
+        executionId: storeId,
+        messages: [],
+        validation: { score: 0, errors: [], warnings: ['Intent does not describe a UI component'] },
+        suggestions: clarity.questions.map(q => q.text),
+        clarify: {
+          needed: true,
+          questions: clarity.questions,
+          score: clarity.score,
+          dimensions: clarity.dimensions,
+          summary: clarity.summary,
+        },
+        pipeline: engine.getState(execId),
+      };
+    }
+  }
+
+  // ── Stage 2: Analyze (tier 2 = 5000 token budget) ──
+  const context = await getContext(intent, 2);
+  engine.submitStage(execId, 'analyze', {
+    context,
+    componentCount: context.components.length,
+    patternCount: context.patterns.length,
+    confidence: context.components.length > 0 ? 0.85 : 0.5,
+  });
+
+  // ── Stage 3: Plan ──
+  // Use semantic search — LLM-enhanced pattern matching when adapter available
+  const { matches: patterns } = await searchBlocksSemantic(searchQuery, { llmAdapter });
+  const plan = {
+    patterns: patterns.map(p => p.name),
+    strategy: patterns.length > 0 ? 'adapt-pattern' : 'generate-fresh',
+    confidence: patterns.length > 0 ? 0.9 : 0.7,
+  };
+  engine.submitStage(execId, 'plan', plan);
+
+  // ── Stage 4: Generate via LLM ──
+  const systemPrompt = await buildSystemPrompt(context, patterns, '', intent);
+  const chatMessages = buildChatMessages(intent, storeId || execId);
+  // Prepend the analyzer's enriched signals to the first user message so the
+  // LLM treats them as ground truth instead of re-deriving from a terse prompt.
+  if (analysisHint && chatMessages[0]?.role === 'user') {
+    chatMessages[0] = { ...chatMessages[0], content: analysisHint + chatMessages[0].content };
+  }
+
+  let response;
+  try {
+    response = await llmAdapter.complete({
+      messages: chatMessages,
+      systemPrompt,
+    });
+  } catch (err) {
+    engine.fail(execId, 'generate', `LLM call failed: ${err.message}`);
+    throw err;
+  }
+
+  let messages = parseA2UIResponse(response.content, { executionId: execId, mode: 'thinking', intent, stopReason: response.stopReason });
+  // Capture for the dialog recorder when ADIA_LOG_DIALOGS is on. See pro engine
+  // for rationale — same pattern, same _debug shape on the result.
+  let lastRawResponse = isRecording() ? response.content : null;
+  let lastTokens = isRecording() ? (response.usage || null) : null;
+  engine.submitStage(execId, 'generate', {
+    messages,
+    tokenUsage: response.usage,
+    source: 'llm',
+    confidence: 0.8,
+  });
+
+  // ── Stage 5: Validate + repair loop ──
+  // Two orthogonal validators run in parallel:
+  //   - scored: weighted heuristic checks (intent alignment, card model, etc.)
+  //   - catalog: AJV against v0.9 catalog schema (strict structural correctness)
+  // Either failing triggers a repair attempt. Catalog failures are typically
+  // small (unknown prop, wrong enum, missing required id) and fix cleanly in
+  // one repair round. Three-attempt cap preserved from the original loop.
+  let validation = validateSchema(messages, { intent });
+  let catalogValidation = await validateCatalog(messages);
+  let attempts = 0;
+
+  while ((!validation.valid || !catalogValidation.valid) && attempts < 3) {
+    attempts++;
+    const failedChecks = validation.checks.filter(c => !c.passed);
+    const catalogFailures = catalogValidation.failures || [];
+    const repairPrompt = buildRepairPrompt(failedChecks, messages, catalogFailures);
+
+    try {
+      const repairResponse = await llmAdapter.complete({
+        messages: [{ role: 'user', content: repairPrompt }],
+        systemPrompt,
+      });
+      messages = parseA2UIResponse(repairResponse.content, { executionId: execId, mode: 'thinking', intent, stopReason: repairResponse.stopReason });
+      if (isRecording()) { lastRawResponse = repairResponse.content; lastTokens = repairResponse.usage || lastTokens; }
+      validation = validateSchema(messages, { intent });
+      catalogValidation = await validateCatalog(messages);
+    } catch {
+      break; // stop repair loop on adapter error
+    }
+  }
+
+  engine.submitStage(execId, 'validate', {
+    ...validation,
+    repairAttempts: attempts,
+    confidence: validation.score / 100,
+  });
+
+  // ── Stage 6: Render (store artifact) ──
+  // Store under storeId (previous execution) for multi-turn history continuity.
+  // First-turn analysis is recorded so iteration turns can recover concepts +
+  // implied components for canvas-aware suggestions.
+  const artifactId = storeId || execId;
+  store.record(artifactId, {
+    messages,
+    summary: intent,
+    intent,
+    validation,
+    analysis,
+  });
+
+  engine.submitStage(execId, 'render', {
+    stored: true,
+    success: validation.valid,
+    repairAttempts: attempts,
+    confidence: validation.valid ? 1 : 0.5,
+  });
+
+  // ── Suggestions (canvas-aware — see generate-pro.js for rationale) ──
+  const originalAnalysis = store.getOriginalAnalysis(artifactId);
+  const originalIntent = store.getOriginalIntent(artifactId);
+  const suggestions = generateSuggestions({ intent, domain, messages, originalAnalysis, originalIntent });
+
+  // Fire-and-forget feedback logging
+  feedbackStore.logExecution({
+    executionId: artifactId, intent, mode: 'thinking',
+    domain: domain.domain, patternMatch: patterns[0]?.name,
+    score: validation?.score, componentCount: messages[0]?.components?.length || 0,
+  }).catch(() => {});
+
+  // ── Drift detection ──
+  const driftMetrics = store.getDriftMetrics(artifactId);
+
+  return {
+    executionId: artifactId,
+    messages,
+    validation,
+    suggestions,
+    drift: driftMetrics,
+    pipeline: engine.getState(execId),
+    _debug: isRecording() ? {
+      systemPrompt,
+      rawLLMResponse: lastRawResponse,
+      tokens: lastTokens,
+      patterns: patterns.slice(0, 8).map(p => ({ name: p.name, score: p.score, keywords: p.keywords })),
+    } : undefined,
+  };
+}

package/engines/registry.js

@@ -0,0 +1,195 @@
+/**
+ * Engine registry + dispatcher — the seam between gen-ui's public API and the
+ * per-engine implementations. Per docs/specs/package-architecture.md §11 Phase 5.
+ *
+ * Two engines are currently wired:
+ *   - monolithic  → pattern-match + adapt (instant | pro | thinking modes)
+ *   - zettel      → fragment-graph composition (single mode: instant)
+ *
+ * The registry deliberately does NOT own intent-gating, clarity assessment, or
+ * execution lifecycle — the public `generateUI()` in engine/generator.js does
+ * that, then delegates the actual work through `pick()`.
+ *
+ * Shape invariant: every engine function returns
+ *   { executionId, messages, validation, suggestions?, strategy?, ... }
+ */
+
+// Zettel is lazy-loaded — it transitively imports node:fs / node:path / node:url
+// (engines/zettel/fragment-library.js), which Vite externalizes in the browser.
+// Static-importing it here would break browser loads of engine/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
+// import on first server-side invocation.
+let _generateZettel = null;
+async function getGenerateZettel() {
+  if (!_generateZettel) {
+    const mod = await import('./zettel/generator-adapter.js');
+    _generateZettel = mod.generateZettel;
+  }
+  return _generateZettel;
+}
+
+// Same lazy-load story for isRecording — keeps the cold-import surface tight.
+let _isRecording = null;
+async function getIsRecording() {
+  if (!_isRecording) {
+    const mod = await import('../../retrieval/dialog-recorder.js');
+    _isRecording = mod.isRecording;
+  }
+  return _isRecording;
+}
+
+// The three monolithic paths live inside engine/generator.js as internal
+// functions. They're injected at boot via `registerMonolithicEngines()` to
+// avoid a circular import (engine/generator.js owns the registry caller).
+let _monolithicInstant = null;
+let _monolithicPro = null;
+let _monolithicThinking = null;
+
+export function registerMonolithicEngines({ instant, pro, thinking }) {
+  _monolithicInstant = instant;
+  _monolithicPro = pro;
+  _monolithicThinking = thinking;
+}
+
+// Engine adapters — uniform call signature `(ctx) => Promise<result>` where
+// ctx is prepared by the public generateUI() orchestrator.
+async function generateInstantAdapter(ctx) {
+  if (!_monolithicInstant) throw new Error('monolithic-instant engine not registered');
+  return _monolithicInstant(ctx);
+}
+async function generateProAdapter(ctx) {
+  if (!_monolithicPro) throw new Error('monolithic-pro engine not registered');
+  return _monolithicPro(ctx);
+}
+async function generateThinkingAdapter(ctx) {
+  if (!_monolithicThinking) throw new Error('monolithic-thinking engine not registered');
+  return _monolithicThinking(ctx);
+}
+
+async function generateZettelAdapter(ctx) {
+  // Map the monolithic ctx to the zettel adapter's expected shape.
+  // storeId (monolithic's multi-turn handle) → sessionId (zettel's turn history).
+  // The steelman from the baseline analyzer drives both retrieval (better
+  // keyword match against the corpus) and LLM synthesis (richer brief). Falls
+  // back to raw intent on iteration turns when analyzer was skipped.
+  // Note: ctx.priorComponentsFromPayload is forwarded for forward-compat —
+  // zettel's session-store currently owns iteration history, but a future
+  // pass should let payload override session state for true statelessness.
+  const generateZettel = await getGenerateZettel();
+  const enrichedIntent = ctx.analysis?.steelman || ctx.intent;
+  const result = await generateZettel({
+    intent: enrichedIntent,
+    mode: 'instant',
+    llmAdapter: ctx.llmAdapter || null,
+    sessionId: ctx.storeId || ctx.executionId || null,
+    priorComponentsFromPayload: ctx.priorComponentsFromPayload || null,
+  });
+
+  // Dialog-recorder hook for zettel. No "system prompt" to capture (the
+  // synthesizer builds its own internally), but the strategy + composition +
+  // candidates are the equivalent reasoning surface — they explain why this
+  // turn produced what it did. Surfaced via _debug so the recorder picks
+  // them up the same way it picks up monolithic engines' system prompts.
+  const isRecording = await getIsRecording();
+  return {
+    executionId: ctx.executionId,
+    messages: result.messages,
+    validation: result.validation,
+    suggestions: [],
+    strategy: result.strategy,
+    engine: 'zettel',
+    _debug: isRecording() ? {
+      systemPrompt: null,
+      rawLLMResponse: null,
+      tokens: null,
+      patterns: (result.candidates || []).slice(0, 8).map(c => ({
+        name: c.name,
+        score: c.score,
+        type: c.type,
+      })),
+      strategy: result.strategy || null,
+      composition: result.composition || result.patternName || null,
+      fragmentsUsed: result.fragments_used || null,
+      retrievalScore: result.retrievalScore ?? null,
+      synthesisAttempts: result.synthesis?.attempts ?? null,
+      sessionTurns: result.sessionTurns ?? null,
+    } : undefined,
+  };
+}
+
+export const ENGINES = {
+  'monolithic-instant':  generateInstantAdapter,
+  'monolithic-pro':      generateProAdapter,
+  'monolithic-thinking': generateThinkingAdapter,
+  'zettel':              generateZettelAdapter,
+};
+
+/**
+ * Register a third-party generation engine at runtime (OD-5 plugin path).
+ *
+ * Contract:
+ *   generate(ctx) → Promise<{ executionId, messages, validation, strategy?, suggestions?, engine }>
+ *
+ *   ctx = { intent, executionId, storeId, llmAdapter, sessionId, catalog? }
+ *
+ * Built-in engine names (`monolithic-*`, `zettel`) are reserved and cannot be
+ * overwritten. Custom engines are dispatched via `pick({ engine: name })` —
+ * mode is ignored for custom engines unless the implementation uses it.
+ *
+ *   @example
+ *   import { registerEngine } from '@adia-ai/a2ui-compose';
+ *   registerEngine('my-hybrid', async (ctx) => {
+ *     const result = await myCustomPipeline(ctx.intent);
+ *     return { executionId: ctx.executionId, messages: result.messages,
+ *              validation: { score: result.score }, strategy: 'hybrid',
+ *              engine: 'my-hybrid' };
+ *   });
+ *   generateUI({ engine: 'my-hybrid', intent: '...' });
+ */
+const RESERVED = new Set(['monolithic', 'monolithic-instant', 'monolithic-pro', 'monolithic-thinking', 'zettel']);
+
+export function registerEngine(name, generateFn) {
+  if (typeof name !== 'string' || !name.length) {
+    throw new Error('registerEngine: name must be a non-empty string');
+  }
+  if (RESERVED.has(name)) {
+    throw new Error(`registerEngine: "${name}" is a reserved built-in engine name`);
+  }
+  if (typeof generateFn !== 'function') {
+    throw new Error('registerEngine: generateFn must be a function');
+  }
+  ENGINES[name] = generateFn;
+}
+
+/**
+ * Remove a previously-registered custom engine. Reserved built-ins are
+ * protected — this throws rather than silently noop-ing on a reserved name.
+ */
+export function unregisterEngine(name) {
+  if (RESERVED.has(name)) {
+    throw new Error(`unregisterEngine: "${name}" is a reserved built-in engine name`);
+  }
+  return delete ENGINES[name];
+}
+
+/**
+ * Pick the right engine function for an `{ engine, mode }` pair.
+ * Dispatch order:
+ *   1. Custom-registered name → direct lookup
+ *   2. engine === 'zettel' → zettel adapter
+ *   3. `monolithic-${mode}` → monolithic variant
+ *   4. Fallback → monolithic-instant
+ */
+export function pick({ engine = 'monolithic', mode = 'instant' } = {}) {
+  // Custom engines have priority over built-in name-parsing.
+  if (engine && engine !== 'monolithic' && ENGINES[engine]) return ENGINES[engine];
+  if (engine === 'zettel') return ENGINES.zettel;
+  const key = `monolithic-${mode}`;
+  return ENGINES[key] || ENGINES['monolithic-instant'];
+}
+
+/** Introspection for tooling / docs. */
+export function listEngines() {
+  return Object.keys(ENGINES);
+}

package/engines/zettel/_smoke.js

@@ -0,0 +1,37 @@
+#!/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';
+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})`);
+
+console.log('\n=== Search: "login" ===');
+console.log(searchAll('login form password', { limit: 5 }));
+
+console.log('\n=== Search: "card header title" ===');
+console.log(searchAll('card header title', { limit: 5 }));
+
+console.log('\n=== Resolve login-form ===');
+const comp = getComposition('login-form');
+const resolved = resolveComposition(comp);
+console.log(`resolved ${resolved.length} nodes:`);
+for (const n of resolved) {
+  const kids = n.children ? `→[${n.children.join(',')}]` : '';
+  const text = n.textContent ? ` "${n.textContent}"` : '';
+  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(', ')}`);
+}

package/engines/zettel/composer.js

@@ -0,0 +1,146 @@
+/**
+ * Composer — resolves compositions and fragment references into flat A2UI templates.
+ *
+ * Input:  a composition (or any template array containing $fragment nodes)
+ * Output: a standard A2UI flat-adjacency node list, ready to validate / render.
+ *
+ * Algorithm:
+ *   For each node in the composition template:
+ *     If node.$fragment:
+ *       - clone the fragment's template
+ *       - prefix every internal id with the composition-node id (to avoid collisions)
+ *       - apply slot bindings (set the attribute on the slot's targetId)
+ *       - if node.children was provided, append those ids to the fragment root's children
+ *       - emit the fragment root under node.id, then the rest of the fragment nodes
+ *     Else:
+ *       - emit the node as-is
+ */
+
+import { getFragment } from './fragment-library.js';
+
+function cloneFragmentWithPrefix(fragment, prefix) {
+  const idMap = new Map();
+  const cloned = fragment.template.map((n) => ({ ...n }));
+
+  // Generate new ids
+  for (const node of cloned) {
+    const newId = `${prefix}--${node.id}`;
+    idMap.set(node.id, newId);
+  }
+  // Rewrite ids and children refs
+  for (const node of cloned) {
+    node.id = idMap.get(node.id);
+    if (Array.isArray(node.children)) {
+      node.children = node.children
+        .map((c) => (typeof c === 'string' ? idMap.get(c) || c : c));
+    }
+  }
+  return { cloned, idMap, rootId: idMap.get(fragment.template[0].id) };
+}
+
+function applyBindings(nodes, fragment, idMap, bindings = {}) {
+  if (!bindings) return;
+  for (const slot of fragment.slots || []) {
+    const internalId = idMap.get(slot.targetId);
+    const target = nodes.find((n) => n.id === internalId);
+    if (!target) continue;
+
+    const value = bindings[slot.name] ?? slot.defaultValue;
+    if (value === undefined) continue;
+
+    const attr = slot.attribute || 'textContent';
+    target[attr] = value;
+  }
+}
+
+/**
+ * Expand a composition (or any template) into a flat A2UI node list.
+ * @param {object} composition - { template: [...] }
+ * @returns {Array<object>} resolved flat nodes
+ */
+export function resolveComposition(composition) {
+  const out = [];
+  const template = composition.template || [];
+
+  for (const node of template) {
+    if (!node.$fragment) {
+      out.push({ ...node });
+      continue;
+    }
+
+    const fragment = getFragment(node.$fragment);
+    if (!fragment) {
+      out.push({
+        id: node.id,
+        component: 'Text',
+        textContent: `⚠ unresolved fragment: ${node.$fragment}`,
+      });
+      continue;
+    }
+
+    const { cloned, idMap, rootId } = cloneFragmentWithPrefix(fragment, node.id);
+    applyBindings(cloned, fragment, idMap, node.bindings);
+
+    // Substitute: composition-node id becomes the fragment root id.
+    // So any sibling that references node.id still resolves to the expanded root.
+    const rootNode = cloned.find((n) => n.id === rootId);
+    if (rootNode) {
+      rootNode.id = node.id;
+      // fix up any sibling refs inside cloned
+      for (const n of cloned) {
+        if (Array.isArray(n.children)) {
+          n.children = n.children.map((c) => (c === rootId ? node.id : c));
+        }
+      }
+    }
+
+    // Allow composition to inject extra children into the fragment root.
+    //   children        — alias for appendChildren (legacy; append to end)
+    //   appendChildren  — append composition-owned nodes to the fragment's children
+    //   prependChildren — prepend composition-owned nodes before the fragment's children
+    // This lets a composition add things INSIDE a fragment's root (e.g. a logo above
+    // a card-header's title) without having to inline the whole fragment.
+    if (rootNode) {
+      const prepend = Array.isArray(node.prependChildren) ? node.prependChildren : [];
+      const append = Array.isArray(node.appendChildren)
+        ? node.appendChildren
+        : (Array.isArray(node.children) ? node.children : []);
+      if (prepend.length || append.length) {
+        rootNode.children = [
+          ...prepend,
+          ...(rootNode.children || []),
+          ...append,
+        ];
+      }
+    }
+
+    out.push(...cloned);
+  }
+
+  return out;
+}
+
+/**
+ * Convert a resolved flat template into A2UI `beginComponent` messages
+ * compatible with the existing validator / renderer. Strips zettel-only
+ * fields (`$fragment`, `bindings`, `prependChildren`, `appendChildren`) that
+ * were already consumed by resolveComposition — they'd be dead weight in the
+ * emitted A2UI messages.
+ */
+export function templateToMessages(template) {
+  return template.map((node) => {
+    const {
+      id, component, children,
+      $fragment, bindings,
+      prependChildren, appendChildren,
+      ...rest
+    } = node;
+    return {
+      messageType: 'beginComponent',
+      componentId: id,
+      componentType: component,
+      children: children || [],
+      ...rest,
+    };
+  });
+}