@adia-ai/a2ui-compose 0.0.1

package/engine/generator.js

@@ -0,0 +1,500 @@
+/**
+ * generate_ui — UI generation from natural language intent.
+ *
+ * Four modes:
+ *   instant  — pattern matching, no LLM (synchronous)
+ *   pro      — pattern search + LLM adaptation (async, blocking)
+ *   thinking — A003 intelligence + LLM adapter (async, blocking)
+ *   stream   — same as thinking but yields progressive updates via async generator
+ *
+ * Multi-turn: pass executionId from a previous run to iterate on the same surface.
+ * The previous A2UI output is fed back as assistant context so the LLM can refine.
+ */
+
+import { validateSchema } from '../../validator/validator.js';
+import { getContext, searchBlocks, searchBlocksSemantic, lookupDomain, listPatterns } from './reference.js';
+import { store, engine } from './state.js';
+import { checkIntentAlignment } from '../../retrieval/intent-alignment.js';
+import { decomposeIntent, composeSubtasks } from '../../retrieval/decomposer.js';
+import { getWiringCatalog } from '../../retrieval/wiring-catalog.js';
+import { getComponentData } from '../../retrieval/pattern-library.js';
+
+import { StubLLMAdapter } from '../llm/llm-stub.js';
+import { createAdapter } from '../llm/llm-bridge.js';
+import { assessClarity } from '../../retrieval/clarity.js';
+import { isConversational } from '../../retrieval/intent-gate.js';
+import { classifyIntent } from '../../retrieval/domain-router.js';
+import { researchIntent, detectReferences } from '../../retrieval/web-research.js';
+import { feedbackStore } from '../../retrieval/feedback-store.js';
+import { pick as pickEngine, registerMonolithicEngines } from '../engines/registry.js';
+import { analyzePrompt } from '../../retrieval/prompt-analyzer.js';
+import { recordTurn, isRecording } from '../../retrieval/dialog-recorder.js';
+import {
+  buildSystemPrompt,
+  buildChatMessages,
+  tryParsePartial,
+  mergeCanvasDiff,
+  buildCanvasDiffPrompt,
+  parseA2UIResponse,
+  buildRepairPrompt,
+  generateSuggestions,
+} from '../engines/monolithic/_shared.js';
+import { generateInstant }  from '../engines/monolithic/generate-instant.js';
+import { generatePro }      from '../engines/monolithic/generate-pro.js';
+import { generateThinking } from '../engines/monolithic/generate-thinking.js';
+
+
+/**
+ * Generate a UI surface from a natural language intent.
+ *
+ * @param {object} opts
+ * @param {string} opts.intent — Natural language intent
+ * @param {'instant'|'pro'|'thinking'|'stream'} [opts.mode='instant'] — Generation mode
+ * @param {string} [opts.executionId] — Existing execution ID (for multi-turn iteration)
+ * @param {object} [opts.currentCanvas] — Client-owned canvas state, enables
+ *   stateless iteration. Shape is a discriminated union — today:
+ *     { components: A2UIComponent[] }   — flat component array
+ *     { messages:   A2UIMessage[]   }   — full message sequence
+ *   Future:
+ *     { html: string }                  — raw HTML (parsed server-side)
+ *     { a2ui: A2UIMessage[], originalIntent?: string, meta?: {} }
+ *   When provided, the pipeline uses this as the iteration baseline instead
+ *   of looking up prior turns in the ArtifactStore. This makes generation
+ *   stateless — the client can iterate across server restarts, multiple tabs,
+ *   or from a saved-canvas JSON file. Backward compatible: if omitted, the
+ *   store lookup via `executionId` still works.
+ * @param {object} [opts.llmAdapter] — LLM adapter (defaults to auto-detected)
+ * @returns {Promise<{ executionId: string, messages: object[], validation: object, suggestions: string[] }>}
+ */
+export async function generateUI({ intent, engine: engineName = 'monolithic', mode = 'instant', executionId, currentCanvas, llmAdapter, model, sessionId }) {
+  // Iteration signal: either an executionId (server-stateful path) OR a
+  // currentCanvas (client-stateless path). Both mean "refine existing UI".
+  const hasClientCanvas = !!(currentCanvas && (currentCanvas.components?.length || currentCanvas.messages?.length || currentCanvas.html));
+  const isIteration = !!executionId || hasClientCanvas;
+
+  // ── Intent gate: reject non-UI prompts before entering the pipeline ──
+  // This prevents the LLM from hallucinating UIs from vague/abstract text.
+  // EXCEPTION: skip the gate on iteration turns. Modifiers like "make it 3D",
+  // "remove the avatar", "try a rose theme" rarely contain UI nouns the gate
+  // recognizes — they're refinements of the prior canvas, not fresh intents.
+  if (!isIteration) {
+    const classification = classifyIntent(intent);
+    const intentCheck = isConversational(intent, classification);
+    if (intentCheck.conversational) {
+      const clarity = assessClarity(intent, classification);
+      return {
+        executionId: executionId || 'rejected',
+        messages: [],
+        validation: { score: 0, valid: false, errors: [`Intent rejected: ${intentCheck.reason}`] },
+        suggestions: clarity.questions.map(q => q.text),
+        rejected: true,
+        reason: intentCheck.reason,
+      };
+    }
+  }
+
+  // For multi-turn: keep the old executionId for artifact history,
+  // but always start a fresh pipeline execution for stage tracking.
+  const previousExecId = executionId;
+  executionId = engine.start({ intent, mode, previousExecId });
+
+  // ── Engine dispatch (Phase 5) ──
+  // Zettel engine: single mode (instant), fragment-graph composition.
+  // Monolithic engine: three modes (instant | pro | thinking | stream→thinking).
+  // Analyzer is BASELINE for every reasoning level — every mode gets an LLM
+  // adapter (instant included). The analyzer call adds ~1-2s to the floor but
+  // the structured signals it produces (steelman, concepts, impliedComponents)
+  // dramatically improve downstream pattern retrieval and LLM generation
+  // quality. Adapter is always created upfront so all modes can analyze.
+  const effectiveMode = mode === 'stream' ? 'thinking' : mode;
+  const adapter = llmAdapter || await createAdapter({ model });
+
+  // ── Stage 0: Prompt Analysis (baseline ingestion) ──
+  // Extract structured signals from the raw prompt so every downstream stage
+  // — pattern search, concept-mapping retrieval, system prompt construction
+  // — reasons against an enriched brief instead of the raw text.
+  // Skipped on iteration turns where the user's modifier ("make it 3D") is
+  // most useful as-is for the LLM iteration prompt.
+  let analysis = null;
+  if (!isIteration) {
+    analysis = await analyzePrompt({ intent, llmAdapter: adapter });
+  }
+
+  // ── Normalize currentCanvas into a uniform priorComponents array ──
+  // Engines consume a single array; the shape union is collapsed here so
+  // engine code doesn't branch on input form. HTML → components conversion
+  // is a future tier-2 feature (see docstring) — for now HTML input falls
+  // through unchanged and the engine will treat it as "no prior canvas".
+  let priorComponentsFromPayload = null;
+  if (hasClientCanvas) {
+    if (Array.isArray(currentCanvas.components)) {
+      priorComponentsFromPayload = currentCanvas.components;
+    } else if (Array.isArray(currentCanvas.messages)) {
+      priorComponentsFromPayload = currentCanvas.messages.flatMap(m => m?.components || []);
+    }
+    // TODO(tier-2): if (currentCanvas.html) priorComponentsFromPayload = htmlToComponents(currentCanvas.html);
+  }
+
+  const fn = pickEngine({ engine: engineName, mode: effectiveMode });
+  const t0 = Date.now();
+  const result = await fn({
+    intent,
+    executionId,
+    storeId: previousExecId || executionId,
+    llmAdapter: adapter,
+    sessionId,
+    analysis,
+    priorComponentsFromPayload,
+  });
+  const totalMs = Date.now() - t0;
+
+  // ── Dialog recording (fire-and-forget, gated by ADIA_LOG_DIALOGS) ──
+  // Captures the entire turn — intent, analysis, system prompt, raw LLM
+  // response, parsed messages, validation, drift, telemetry — to disk for
+  // debugging, regression analysis, and training-data bootstrapping. The
+  // recorder no-ops when the env var is unset; the engine's _debug payload
+  // is also only populated when recording is on (see generate-pro.js).
+  if (isRecording()) {
+    const debug = result._debug || {};
+    // Anything the engine put on _debug beyond the canonical fields lands
+    // in engineDebug — useful for engine-specific reasoning (zettel strategy
+    // / composition / fragmentsUsed; instant patternName / strategy).
+    const { systemPrompt, rawLLMResponse, tokens, patterns, ...engineDebug } = debug;
+    recordTurn({
+      sessionId: previousExecId || result.executionId || null,
+      intent,
+      mode: effectiveMode,
+      engine: engineName,
+      model: model || null,
+      analysis,
+      currentCanvas: hasClientCanvas ? currentCanvas : null,
+      patterns: patterns || [],
+      systemPrompt: systemPrompt || null,
+      rawLLMResponse: rawLLMResponse || null,
+      messages: result.messages || [],
+      validation: result.validation || null,
+      drift: result.drift || null,
+      suggestions: result.suggestions || [],
+      timing: { totalMs },
+      tokens: tokens || null,
+      engineDebug: Object.keys(engineDebug).length ? engineDebug : null,
+      isIteration,
+    }).catch(() => { /* logger swallows internally; this is just last-resort */ });
+  }
+
+  // Strip the _debug payload before returning — it's an internal collaboration
+  // channel between engines and the recorder, not part of the public API.
+  // Without this strip the proxy would echo a 12KB+ system prompt to clients.
+  if (result._debug) delete result._debug;
+  return result;
+}
+
+/**
+ * Streaming UI generation — yields progressive events as the LLM generates.
+ *
+ * Events:
+ *   { type: 'status', stage, message }          — pipeline stage transition
+ *   { type: 'clarify', questions, score, dimensions } — intent needs clarification (consumer should pause)
+ *   { type: 'text_delta', text, snapshot }       — raw LLM text chunk
+ *   { type: 'partial', messages }                — parseable partial A2UI (render immediately)
+ *   { type: 'complete', messages, validation, suggestions, executionId }  — final result
+ *   { type: 'error', error }                     — generation error
+ *
+ * @param {object} opts
+ * @param {string} opts.intent
+ * @param {string} [opts.executionId]
+ * @param {object} [opts.llmAdapter]
+ * @param {(query: string) => Promise<{ results: { title: string, snippet: string, url: string }[] }>} [opts.search] — Web search function
+ * @yields {object}
+ */
+export async function* generateUIStream({ intent, executionId, llmAdapter, model, search, currentCanvas }) {
+  // currentCanvas accepted for API parity with generateUI. The streaming
+  // path's downstream consumers don't yet read it, but parity prevents the
+  // client from having to branch its call shape per mode. Tier-2 will
+  // wire it through the same way generatePro does.
+  void currentCanvas;
+  // ── Intent gate: reject non-UI prompts before entering the pipeline ──
+  // Same iteration bypass as generateUI() — modifiers don't need to clear the
+  // conversational gate when there's a prior turn to refine.
+  const isIteration = !!executionId;
+  if (!isIteration) {
+    const classification = classifyIntent(intent);
+    const intentCheck = isConversational(intent, classification);
+    if (intentCheck.conversational) {
+      const clarity = assessClarity(intent, classification);
+      yield {
+        type: 'clarify',
+        questions: clarity.questions.length > 0
+          ? clarity.questions
+          : [{ text: 'What would you like me to build?', dimension: 'domain', priority: 1 }],
+        score: clarity.score,
+        dimensions: clarity.dimensions,
+        summary: `Not a UI request (${intentCheck.reason}). ${clarity.summary}`,
+        rejected: true,
+        reason: intentCheck.reason,
+      };
+      return; // Do NOT continue to generation pipeline
+    }
+  }
+
+  const adapter = llmAdapter || await createAdapter({ model });
+  // For multi-turn: keep the old executionId for artifact history lookup,
+  // but always start a fresh pipeline execution for stage tracking.
+  const previousExecId = executionId;
+  executionId = engine.start({ intent, mode: 'stream', previousExecId });
+
+  // ── Stage 1: Interpret ──
+  const domain = lookupDomain(intent);
+  engine.submitStage(executionId, 'interpret', { domain, intent, confidence: domain.confidence });
+  yield { type: 'status', stage: 'interpret', message: `Domain: ${domain.domain}` };
+
+  // ── Clarity gate: yield clarify event if intent is vague ──
+  // Only for fresh intents (not multi-turn iterations which have prior context)
+  if (!previousExecId) {
+    const clarity = assessClarity(intent, domain);
+    if (!clarity.clear && clarity.questions.length > 0) {
+      yield {
+        type: 'clarify',
+        questions: clarity.questions,
+        score: clarity.score,
+        dimensions: clarity.dimensions,
+        summary: clarity.summary,
+      };
+      // The consumer decides whether to pause or continue.
+      // If they continue iterating, generation proceeds with what we have.
+      // If they stop iterating and re-submit with more detail, a new stream starts.
+    }
+  }
+
+  // ── Stage 2: Analyze ──
+  const context = await getContext(intent, 2);
+  engine.submitStage(executionId, 'analyze', {
+    context, componentCount: context.components.length, patternCount: context.patterns.length,
+    confidence: context.components.length > 0 ? 0.85 : 0.5,
+  });
+  yield { type: 'status', stage: 'analyze', message: `${context.components.length} components, ${context.patterns.length} patterns` };
+
+  // ── Research: web search enrichment (optional) ──
+  let researchContext = '';
+  const { references } = detectReferences(intent);
+  if (references.length > 0 || search) {
+    yield { type: 'status', stage: 'research', message: references.length > 0 ? `Researching: ${references.join(', ')}` : 'Searching for patterns...' };
+    try {
+      const research = await researchIntent(intent, { search, llmAdapter: adapter });
+      researchContext = research.context;
+      if (research.references.length > 0) {
+        yield { type: 'research', references: research.references, insights: research.insights };
+      }
+    } catch {
+      // Research failed — continue without it
+    }
+  }
+
+  // ── Stage 3: Plan ──
+  // Use semantic search in LLM modes — feeds pattern index to LLM for conceptual matching
+  const { matches: patterns, remix: remixSuggestion } = await searchBlocksSemantic(intent, { llmAdapter: adapter, remix: true });
+  engine.submitStage(executionId, 'plan', {
+    patterns: patterns.map(p => p.name),
+    strategy: patterns.length > 0 ? 'adapt-pattern' : 'generate-fresh',
+    confidence: patterns.length > 0 ? 0.9 : 0.7,
+    hasRemix: !!remixSuggestion,
+  });
+  yield { type: 'status', stage: 'plan', message: patterns.length > 0 ? `Adapting: ${patterns[0].name}${remixSuggestion ? ' (with remix)' : ''}` : 'Generating fresh' };
+
+  // ── Decomposition: split complex intents into subtasks ──
+  // Skip decomposition when a pattern match exists — the pattern already handles composition
+  const decomposition = patterns.length === 0 ? decomposeIntent(intent) : { shouldDecompose: false, subtasks: [], layout: null, original: intent };
+  if (decomposition.shouldDecompose && decomposition.subtasks.length >= 3) {
+    yield { type: 'status', stage: 'decompose', message: `Splitting into ${decomposition.subtasks.length} subtasks: ${decomposition.subtasks.map(s => s.label).join(', ')}` };
+    yield { type: 'decompose', subtasks: decomposition.subtasks, layout: decomposition.layout };
+
+    // Generate each subtask independently
+    const subtaskResults = [];
+    for (const subtask of decomposition.subtasks) {
+      yield { type: 'status', stage: 'generate', message: `Generating: ${subtask.label}...` };
+      try {
+        const subResult = await adapter.complete({
+          messages: [{ role: 'user', content: subtask.intent }],
+          systemPrompt: await buildSystemPrompt(context, patterns, researchContext, intent),
+        });
+        const subMessages = parseA2UIResponse(subResult.content, { executionId, mode: 'stream', intent: subtask.intent });
+        subtaskResults.push({ label: subtask.label, messages: subMessages });
+      } catch {
+        // Failed subtask — skip it
+        subtaskResults.push({ label: subtask.label, messages: [{ type: 'updateComponents', surfaceId: 'default', components: [{ id: 'root', component: 'Text', variant: 'body', textContent: `${subtask.label} (generation failed)` }] }] });
+      }
+    }
+
+    // Compose into layout
+    const composed = composeSubtasks(decomposition.layout, subtaskResults);
+
+    engine.submitStage(executionId, 'generate', {
+      messages: composed, source: 'decomposed', decomposed: true,
+      subtasks: decomposition.subtasks.length, confidence: 0.8,
+    });
+
+    const composedValidation = validateSchema(composed, { intent });
+
+    engine.submitStage(executionId, 'validate', {
+      ...composedValidation, confidence: composedValidation.score / 100,
+    });
+
+    // Alignment check
+    const alignment = checkIntentAlignment(intent, composed[0]?.components || []);
+
+    const storeId = previousExecId || executionId;
+    store.record(storeId, { messages: composed, summary: intent, validation: composedValidation, intent });
+    engine.submitStage(executionId, 'render', { stored: true, decomposed: true, subtasks: decomposition.subtasks.length });
+
+    // Fire-and-forget feedback logging (decomposed stream)
+    feedbackStore.logExecution({
+      executionId: storeId, intent, mode: 'stream',
+      domain: domain.domain, patternMatch: null,
+      score: composedValidation?.score, componentCount: composed[0]?.components?.length || 0,
+    }).catch(() => {});
+
+    yield {
+      type: 'complete',
+      executionId: storeId,
+      messages: composed,
+      validation: composedValidation,
+      alignment,
+      suggestions: generateSuggestions(intent, domain, composed),
+      pipeline: engine.getState(executionId),
+    };
+    return;
+  }
+
+  // ── Stage 4: Generate via LLM stream ──
+  const systemPrompt = await buildSystemPrompt(context, patterns, researchContext, intent);
+  const chatMessages = buildChatMessages(intent, previousExecId || executionId);
+
+  yield { type: 'status', stage: 'generate', message: 'Streaming from LLM...' };
+
+  let fullText = '';
+  let lastPartialRender = '';
+
+  try {
+    if (typeof adapter.stream === 'function') {
+      for await (const chunk of adapter.stream({ messages: chatMessages, systemPrompt })) {
+        if (chunk.type === 'text') {
+          fullText += chunk.content;
+          yield { type: 'text_delta', text: chunk.content, snapshot: fullText };
+
+          // Try to parse partial JSON and render incrementally
+          const partial = tryParsePartial(fullText);
+          if (partial && JSON.stringify(partial) !== lastPartialRender) {
+            lastPartialRender = JSON.stringify(partial);
+            yield { type: 'partial', messages: partial };
+          }
+        }
+      }
+    } else {
+      // Fallback: non-streaming adapter
+      const response = await adapter.complete({ messages: chatMessages, systemPrompt });
+      fullText = response.content;
+      yield { type: 'text_delta', text: fullText, snapshot: fullText };
+    }
+  } catch (err) {
+    yield { type: 'error', error: err };
+    return;
+  }
+
+  // ── Stage 5: Parse final + validate ──
+  let messages = parseA2UIResponse(fullText, { executionId, mode: 'stream', intent });
+  engine.submitStage(executionId, 'generate', {
+    messages, source: 'llm-stream', confidence: 0.8,
+  });
+
+  let validation = validateSchema(messages, { intent });
+
+  // One repair attempt if invalid (non-streaming, quick fix)
+  if (!validation.valid) {
+    yield { type: 'status', stage: 'validate', message: `Score ${validation.score}/100 — repairing...` };
+    try {
+      const failedChecks = validation.checks.filter(c => !c.passed);
+      const repairResponse = await adapter.complete({
+        messages: [{ role: 'user', content: buildRepairPrompt(failedChecks, messages) }],
+        systemPrompt,
+      });
+      messages = parseA2UIResponse(repairResponse.content, { executionId, mode: 'stream', intent });
+      validation = validateSchema(messages, { intent });
+    } catch { /* keep original */ }
+  }
+
+  engine.submitStage(executionId, 'validate', {
+    ...validation, confidence: validation.score / 100,
+  });
+
+  // ── Stage 6: Store artifact ──
+  // Store under the previous execution ID if iterating (keeps multi-turn history together)
+  const storeId = previousExecId || executionId;
+  store.record(storeId, { messages, summary: intent, validation, intent });
+  engine.submitStage(executionId, 'render', { stored: true, success: validation.valid, confidence: validation.valid ? 1 : 0.5 });
+
+  // ── Intent alignment check ──
+  const alignment = checkIntentAlignment(intent, messages[0]?.components || []);
+
+  const suggestions = generateSuggestions(intent, domain, messages);
+
+  // Fire-and-forget feedback logging (stream mode)
+  feedbackStore.logExecution({
+    executionId: storeId, intent, mode: 'stream',
+    domain: domain.domain, patternMatch: patterns[0]?.name,
+    score: validation?.score, componentCount: messages[0]?.components?.length || 0,
+  }).catch(() => {});
+
+  // ── Drift detection ──
+  const driftMetrics = store.getDriftMetrics(storeId);
+
+  yield {
+    type: 'complete',
+    executionId: storeId,
+    messages,
+    validation,
+    alignment,
+    drift: driftMetrics,
+    suggestions,
+    pipeline: engine.getState(executionId),
+  };
+}
+
+// ── Pro mode (pattern-aware LLM adaptation) ─────────────────────────
+
+
+// ═══════════════════════════════════════════════════════════════════════
+// SYSTEM PROMPT (Feature 2: improved with card-ui rules)
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Build a concise system prompt for the LLM with component catalog,
+ * card-ui content model, layout rules, and example patterns.
+ *
+ * @param {object} context — Assembled context from A003
+ * @param {object[]} patterns — Matched patterns from pattern library
+ * @returns {string}
+ */
+
+/**
+ * Get the shared artifact store (for external inspection).
+ * @returns {ArtifactStore}
+ */
+export function getArtifactStore() {
+  return store;
+}
+
+/**
+ * Get the shared pipeline engine (for external inspection).
+ * @returns {PipelineEngine}
+ */
+export function getPipelineEngine() {
+  return engine;
+}
+
+// ── Register the three monolithic engines with the dispatcher ──
+// Done at module load so the registry is ready before the first generateUI() call.
+registerMonolithicEngines({
+  instant: generateInstant,
+  pro: generatePro,
+  thinking: generateThinking,
+});

package/engine/pattern-export.js

@@ -0,0 +1,149 @@
+/**
+ * Pattern Export — Save generated UI as reusable named patterns.
+ *
+ * Produces two downloadable files:
+ *   {name}.json — A2UI flat adjacency pattern (importable into pattern-library)
+ *   {name}.html — Rendered HTML snapshot from the canvas
+ *
+ * Also supports importing patterns back into the runtime library.
+ */
+
+import { registerPattern } from '../../retrieval/pattern-library.js';
+
+/**
+ * Build a pattern-library-compatible JSON object from generation results.
+ *
+ * @param {string} name — Pattern name (kebab-case, e.g. "my-pricing-page")
+ * @param {object} opts
+ * @param {object[]} opts.components — Flat adjacency array from messages[0].components
+ * @param {string} opts.intent — Original user intent
+ * @param {string} [opts.domain] — Domain classification (forms, data, layout, agent, navigation)
+ * @param {string} [opts.description] — Human description (falls back to intent)
+ * @returns {object} — Pattern object matching pattern-library format
+ */
+export function buildPatternJSON(name, { components, intent, domain, description }) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+  // Extract unique component type names
+  const componentTypes = [...new Set(
+    components.map(c => c.component).filter(Boolean)
+  )];
+
+  // Clean components: strip internal fields
+  const template = components.map(c => {
+    const { _surfaceId, ...rest } = c;
+    return rest;
+  });
+
+  return {
+    name: slug,
+    description: description || intent || slug,
+    domain: domain || 'layout',
+    components: componentTypes,
+    template,
+  };
+}
+
+/**
+ * Save a generation as a named pattern. Downloads .json + .html files.
+ *
+ * @param {string} name — Pattern name
+ * @param {object} opts
+ * @param {object[]} opts.messages — A2UI messages array
+ * @param {object} opts.validation — Validation result (must have score >= 95)
+ * @param {string} opts.intent — Original user intent
+ * @param {string} [opts.domain] — Domain classification
+ * @param {string} [opts.canvasHTML] — Rendered HTML from canvas
+ * @param {number} [opts.minScore=95] — Minimum score to allow save
+ * @returns {{ json: object, html: string }} — The saved payloads
+ */
+export function savePattern(name, { messages, validation, intent, domain, canvasHTML, minScore = 95 }) {
+  if (!validation || validation.score < minScore) {
+    throw new Error(`Score ${validation?.score ?? 0} is below minimum ${minScore} for pattern save`);
+  }
+
+  const components = messages?.[0]?.components;
+  if (!components || !components.length) {
+    throw new Error('No components to save');
+  }
+
+  const json = buildPatternJSON(name, { components, intent, domain });
+
+  // Download .json
+  downloadFile(`${json.name}.json`, JSON.stringify(json, null, 2), 'application/json');
+
+  // Download .html (if available)
+  const html = canvasHTML || '';
+  if (html) {
+    const htmlDoc = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${json.name} — A2UI Pattern</title>
+  <style>body { font-family: system-ui, sans-serif; padding: 2rem; }</style>
+</head>
+<body>
+${html}
+</body>
+</html>`;
+    downloadFile(`${json.name}.html`, htmlDoc, 'text/html');
+  }
+
+  // Also register in the runtime library
+  registerPattern(json);
+
+  return { json, html };
+}
+
+/**
+ * Import a pattern JSON object into the runtime pattern library.
+ *
+ * @param {object|string} patternJSON — Pattern object or JSON string
+ * @returns {{ success: boolean, name?: string, error?: string }}
+ */
+export function importPattern(patternJSON) {
+  let pattern = patternJSON;
+  if (typeof pattern === 'string') {
+    try { pattern = JSON.parse(pattern); }
+    catch { return { success: false, error: 'Invalid JSON' }; }
+  }
+
+  if (!pattern?.name) return { success: false, error: 'Missing pattern name' };
+  if (!pattern?.template || !Array.isArray(pattern.template)) {
+    return { success: false, error: 'Missing or invalid template array' };
+  }
+
+  const registered = registerPattern(pattern);
+  if (!registered) {
+    return { success: false, error: `Pattern "${pattern.name}" already exists` };
+  }
+
+  return { success: true, name: pattern.name };
+}
+
+/**
+ * Trigger a file download in the browser.
+ *
+ * @param {string} filename
+ * @param {string} content
+ * @param {string} [mimeType='application/json']
+ */
+export function downloadFile(filename, content, mimeType = 'application/json') {
+  if (typeof document === 'undefined') {
+    throw new Error('downloadFile requires a browser environment');
+  }
+
+  const blob = new Blob([content], { type: mimeType });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.style.display = 'none';
+  // Prevent SPA router from intercepting the blob URL click
+  a.addEventListener('click', (e) => e.stopPropagation());
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}