@adia-ai/a2ui-compose 0.0.1

package/engine/pipeline/engine.js

@@ -0,0 +1,289 @@
+/**
+ * PipelineEngine — State machine for generative pipeline executions.
+ *
+ * Manages execution lifecycle: start → stage submissions → completion/abort.
+ * Enforces stage ordering (interpret → analyze → plan → generate → validate → render)
+ * with doNotRedo support for skipping stages on iteration.
+ */
+
+import { STAGES, stageIndex, createStepReport, createEvent } from './types.js';
+
+let nextId = 1;
+
+/** Generate a unique execution ID */
+function uid() {
+  return `exec_${Date.now().toString(36)}_${(nextId++).toString(36)}`;
+}
+
+/**
+ * @typedef {object} PipelineExecution
+ * @property {string} id — Unique execution ID
+ * @property {string} intent — Original user intent
+ * @property {'instant'|'thinking'|'pro'|'god'} mode — Generation mode
+ * @property {'active'|'completed'|'failed'|'aborted'} state — Current state
+ * @property {Map<string, object>} stages — Stage outputs keyed by stage name
+ * @property {object[]} reports — StepReports in order
+ * @property {object[]} events — PipelineEvent log
+ * @property {string[]} doNotRedo — Stages to skip on iteration
+ * @property {number} created — Timestamp
+ * @property {number} updated — Timestamp
+ */
+
+export class PipelineEngine {
+  #executions = new Map();
+
+  /**
+   * Start a new pipeline execution.
+   *
+   * @param {object} opts
+   * @param {string} opts.intent — User intent text
+   * @param {'instant'|'thinking'|'pro'|'god'} [opts.mode='instant'] — Generation mode
+   * @returns {string} — executionId
+   */
+  start({ intent, mode = 'instant' }) {
+    const id = uid();
+    const execution = {
+      id,
+      intent,
+      mode,
+      state: 'active',
+      stages: new Map(),
+      reports: [],
+      events: [],
+      doNotRedo: [],
+      created: Date.now(),
+      updated: Date.now(),
+    };
+
+    execution.events.push(createEvent({
+      executionId: id,
+      type: 'pipeline:start',
+      message: `Pipeline started for intent: "${intent}" (mode: ${mode})`,
+      data: { intent, mode },
+    }));
+
+    this.#executions.set(id, execution);
+    return id;
+  }
+
+  /**
+   * Submit a stage output to an active execution.
+   *
+   * Validates stage ordering: stages must proceed in STAGES order.
+   * Stages listed in doNotRedo are skipped automatically.
+   *
+   * @param {string} executionId
+   * @param {string} stage — Stage name (from STAGES)
+   * @param {object} output — Stage output data
+   * @param {object} [opts] — Options
+   * @param {boolean} [opts.force=false] — Skip ordering check
+   * @param {string[]} [opts.doNotRedo] — Stages to skip on future iterations
+   * @returns {object} — StepReport
+   */
+  submitStage(executionId, stage, output, { force = false, doNotRedo = [] } = {}) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) throw new Error(`Unknown execution: ${executionId}`);
+    if (execution.state !== 'active') throw new Error(`Execution ${executionId} is ${execution.state}, not active`);
+
+    const idx = stageIndex(stage);
+    if (idx === -1) throw new Error(`Unknown stage: ${stage}`);
+
+    // Check ordering: the submitted stage must come after the last completed stage
+    if (!force && execution.stages.size > 0) {
+      const completedStages = [...execution.stages.keys()];
+      const lastCompleted = completedStages[completedStages.length - 1];
+      const lastIdx = stageIndex(lastCompleted);
+
+      // Allow re-submission of same stage (iteration) or next stage
+      if (idx < lastIdx) {
+        throw new Error(`Stage "${stage}" (${idx}) cannot precede already completed "${lastCompleted}" (${lastIdx}). Use force to override.`);
+      }
+
+      // Check for skipped stages (unless they're in doNotRedo)
+      const allSkippable = [...execution.doNotRedo, ...doNotRedo];
+      for (let i = lastIdx + 1; i < idx; i++) {
+        const skippedName = STAGES[i];
+        if (!allSkippable.includes(skippedName) && !execution.stages.has(skippedName)) {
+          throw new Error(`Stage "${skippedName}" must be completed before "${stage}". Add to doNotRedo to skip.`);
+        }
+      }
+    }
+
+    // Record doNotRedo additions
+    if (doNotRedo.length > 0) {
+      for (const s of doNotRedo) {
+        if (!execution.doNotRedo.includes(s)) execution.doNotRedo.push(s);
+      }
+    }
+
+    // Store stage output
+    execution.stages.set(stage, output);
+    execution.updated = Date.now();
+
+    // Create step report
+    const report = createStepReport({
+      stage,
+      status: 'passed',
+      goal: `Complete ${stage} stage`,
+      summary: `Stage "${stage}" submitted successfully`,
+      confidence: output.confidence ?? 0.8,
+      checks: output.checks ?? [],
+      assumptions: output.assumptions ?? [],
+    });
+
+    execution.reports.push(report);
+
+    // Log event
+    execution.events.push(createEvent({
+      executionId,
+      type: 'stage:complete',
+      stage,
+      message: `Stage "${stage}" completed`,
+      data: { output: summarizeOutput(output) },
+    }));
+
+    // Auto-complete if render stage is done
+    if (stage === 'render') {
+      execution.state = 'completed';
+      execution.events.push(createEvent({
+        executionId,
+        type: 'pipeline:complete',
+        message: 'Pipeline completed successfully',
+      }));
+    }
+
+    return report;
+  }
+
+  /**
+   * Get the current state of an execution.
+   *
+   * @param {string} executionId
+   * @returns {object|null} — Execution state snapshot (or null if not found)
+   */
+  getState(executionId) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) return null;
+
+    return {
+      id: execution.id,
+      intent: execution.intent,
+      mode: execution.mode,
+      state: execution.state,
+      completedStages: [...execution.stages.keys()],
+      currentStage: this.#currentStage(execution),
+      reports: [...execution.reports],
+      eventCount: execution.events.length,
+      doNotRedo: [...execution.doNotRedo],
+      created: execution.created,
+      updated: execution.updated,
+    };
+  }
+
+  /**
+   * Get the full event log for an execution.
+   *
+   * @param {string} executionId
+   * @returns {object[]}
+   */
+  getEvents(executionId) {
+    const execution = this.#executions.get(executionId);
+    return execution ? [...execution.events] : [];
+  }
+
+  /**
+   * Get the output from a specific stage.
+   *
+   * @param {string} executionId
+   * @param {string} stage
+   * @returns {object|null}
+   */
+  getStageOutput(executionId, stage) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) return null;
+    return execution.stages.get(stage) ?? null;
+  }
+
+  /**
+   * Abort an active execution.
+   *
+   * @param {string} executionId
+   * @param {string} [reason] — Abort reason
+   */
+  abort(executionId, reason = 'Aborted by caller') {
+    const execution = this.#executions.get(executionId);
+    if (!execution) throw new Error(`Unknown execution: ${executionId}`);
+    if (execution.state !== 'active') return; // already terminal
+
+    execution.state = 'aborted';
+    execution.updated = Date.now();
+
+    execution.events.push(createEvent({
+      executionId,
+      type: 'pipeline:abort',
+      message: reason,
+    }));
+  }
+
+  /**
+   * Mark an execution as failed.
+   *
+   * @param {string} executionId
+   * @param {string} stage — Stage where failure occurred
+   * @param {string} error — Error description
+   */
+  fail(executionId, stage, error) {
+    const execution = this.#executions.get(executionId);
+    if (!execution) throw new Error(`Unknown execution: ${executionId}`);
+    if (execution.state !== 'active') return;
+
+    execution.state = 'failed';
+    execution.updated = Date.now();
+
+    const report = createStepReport({
+      stage,
+      status: 'failed',
+      goal: `Complete ${stage} stage`,
+      summary: error,
+      confidence: 0,
+    });
+    execution.reports.push(report);
+
+    execution.events.push(createEvent({
+      executionId,
+      type: 'stage:fail',
+      stage,
+      message: error,
+    }));
+
+    execution.events.push(createEvent({
+      executionId,
+      type: 'pipeline:fail',
+      message: `Pipeline failed at stage "${stage}": ${error}`,
+    }));
+  }
+
+  /**
+   * Determine the next expected stage for an execution.
+   * @param {object} execution
+   * @returns {string|null}
+   */
+  #currentStage(execution) {
+    if (execution.state !== 'active') return null;
+    const completed = new Set(execution.stages.keys());
+    for (const stage of STAGES) {
+      if (!completed.has(stage) && !execution.doNotRedo.includes(stage)) {
+        return stage;
+      }
+    }
+    return null;
+  }
+}
+
+/** Summarize output for event log (avoid storing huge payloads in events) */
+function summarizeOutput(output) {
+  if (!output) return null;
+  const keys = Object.keys(output);
+  if (keys.length <= 5) return output;
+  return { _keys: keys, _size: JSON.stringify(output).length };
+}

package/engine/pipeline/types.js

@@ -0,0 +1,91 @@
+/**
+ * Pipeline Type Definitions — Stage names, StepReport, Handoff, PipelineEvent.
+ *
+ * Pure data constructors for the pipeline state machine.
+ * No dependencies — usable from browser and Node.
+ */
+
+/** Ordered pipeline stages */
+export const STAGES = ['interpret', 'analyze', 'plan', 'generate', 'validate', 'render'];
+
+/** Stage index lookup for ordering enforcement */
+const STAGE_INDEX = Object.fromEntries(STAGES.map((s, i) => [s, i]));
+
+/**
+ * Get the numeric index of a stage (for ordering checks).
+ * @param {string} stage
+ * @returns {number} — -1 if unknown
+ */
+export function stageIndex(stage) {
+  return STAGE_INDEX[stage] ?? -1;
+}
+
+/**
+ * Create a StepReport — per-stage quality gate.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage — Stage name (from STAGES)
+ * @param {'passed'|'failed'|'skipped'} opts.status — Gate result
+ * @param {string} opts.goal — What this stage aimed to accomplish
+ * @param {string} opts.summary — What actually happened
+ * @param {number} opts.confidence — 0-1 confidence score
+ * @param {object[]} [opts.checks] — Individual check results
+ * @param {string[]} [opts.assumptions] — Assumptions made during this stage
+ * @returns {object}
+ */
+export function createStepReport({ stage, status, goal, summary, confidence, checks = [], assumptions = [] }) {
+  return {
+    stage,
+    status,
+    goal,
+    summary,
+    confidence: Math.max(0, Math.min(1, confidence)),
+    checks,
+    assumptions,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Create a Handoff — stage boundary contract.
+ *
+ * @param {object} opts
+ * @param {string} opts.from — Source stage
+ * @param {string} opts.to — Target stage
+ * @param {object} opts.completed — Data produced by the source stage
+ * @param {string[]} [opts.unresolved] — Open questions or gaps
+ * @param {string[]} [opts.doNotRedo] — Stages that should be skipped on iteration
+ * @returns {object}
+ */
+export function createHandoff({ from, to, completed, unresolved = [], doNotRedo = [] }) {
+  return {
+    from,
+    to,
+    completed,
+    unresolved,
+    doNotRedo,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Create a PipelineEvent — event log entry.
+ *
+ * @param {object} opts
+ * @param {string} opts.executionId
+ * @param {'stage:start'|'stage:complete'|'stage:fail'|'stage:skip'|'pipeline:start'|'pipeline:complete'|'pipeline:fail'|'pipeline:abort'} opts.type
+ * @param {string} [opts.stage] — Stage name (if stage-level event)
+ * @param {string} opts.message — Human-readable description
+ * @param {*} [opts.data] — Arbitrary event payload
+ * @returns {object}
+ */
+export function createEvent({ executionId, type, stage = null, message, data = null }) {
+  return {
+    executionId,
+    type,
+    stage,
+    message,
+    data,
+    timestamp: Date.now(),
+  };
+}

package/engine/reference.js

@@ -0,0 +1,115 @@
+/**
+ * Reference Tools — Delegates to A003 intelligence system.
+ *
+ * Thin wrappers that provide a stable generative-system API surface
+ * over the intelligence module. Used by the generator and pipeline stages
+ * to look up components, patterns, and domain context.
+ */
+
+import { getCatalog, getComponent, getComponentsByCategory } from '../../retrieval/index.js';
+import { classifyIntent, assembleContext } from '../../retrieval/index.js';
+import { getAllPatterns, searchPatterns, getPattern, semanticSearchPatterns } from '../../retrieval/index.js';
+import { checkAllAntiPatterns } from '../../retrieval/index.js';
+import { serializeEntry } from '../../retrieval/index.js';
+
+/**
+ * Look up a single component by A2UI type name.
+ * @param {string} typeName — e.g. 'Button', 'Card', 'TextField'
+ * @returns {object|null}
+ */
+export async function lookupComponent(typeName) {
+  return getComponent(typeName);
+}
+
+/**
+ * Get reference-level entry for a component (full API surface).
+ * @param {string} typeName
+ * @returns {object|null}
+ */
+export async function getComponentAPI(typeName) {
+  const entry = await getComponent(typeName);
+  if (!entry) return null;
+  return serializeEntry(entry, 'reference');
+}
+
+/**
+ * Get the full component catalog map.
+ * @returns {object}
+ */
+export async function getComponentMap() {
+  return getCatalog();
+}
+
+/**
+ * Get components filtered by category.
+ * @param {string} category — e.g. 'input', 'layout', 'display'
+ * @returns {object[]}
+ */
+export async function getComponentsByGroup(category) {
+  return getComponentsByCategory(category);
+}
+
+/**
+ * Search the pattern library by query.
+ * @param {string} query — Natural language or keyword query
+ * @returns {object[]}
+ */
+export function searchBlocks(query, { domain } = {}) {
+  return searchPatterns(query, { domain });
+}
+
+/**
+ * Get a specific named pattern.
+ * @param {string} name — Pattern name (e.g. 'stat-cards', 'user-profile')
+ * @returns {object|null}
+ */
+export function lookupPattern(name) {
+  return getPattern(name);
+}
+
+/**
+ * Get all available patterns.
+ * @returns {object[]}
+ */
+export function listPatterns() {
+  return getAllPatterns();
+}
+
+/**
+ * Semantic search — LLM-enhanced pattern matching.
+ * Falls back to keyword search if no adapter provided.
+ * @param {string} query
+ * @param {object} [options] — { llmAdapter, remix }
+ * @returns {Promise<{ matches: object[], remix?: object }>}
+ */
+export async function searchBlocksSemantic(query, options = {}) {
+  return semanticSearchPatterns(query, options);
+}
+
+/**
+ * Classify an intent into a domain.
+ * @param {string} intent — Natural language intent
+ * @returns {object} — { domain, confidence, matchedSignals }
+ */
+export function lookupDomain(intent) {
+  return classifyIntent(intent);
+}
+
+/**
+ * Assemble progressive-disclosure context for generation.
+ * @param {string} intent — Natural language intent
+ * @param {number} [tier=1] — Budget tier (0-4)
+ * @returns {object}
+ */
+export async function getContext(intent, tier = 1) {
+  return assembleContext({ intent, tier });
+}
+
+/**
+ * Run anti-pattern checks against a component tree.
+ * @param {object[]} components — Flat component list
+ * @returns {object[]} — Anti-pattern violations
+ */
+export function checkAntiPatterns(components) {
+  return checkAllAntiPatterns(components);
+}

package/engine/state.js

@@ -0,0 +1,15 @@
+/**
+ * Shared module-level singletons for the monolithic engine.
+ *
+ * These were previously private to engine/generator.js. Extracted so that
+ * engines/monolithic/generate-{instant,pro,thinking}.js can share the same
+ * artifact store and pipeline engine without going through the dispatcher.
+ *
+ * Same instances, imported by reference — do NOT re-instantiate per-call.
+ */
+
+import { ArtifactStore } from './artifacts.js';
+import { PipelineEngine } from './pipeline/engine.js';
+
+export const store = new ArtifactStore();
+export const engine = new PipelineEngine();