@adia-ai/gen-ui 0.8.37

package/compose/core/reference.js

@@ -0,0 +1,150 @@
+/**
+ * Reference Tools — stable generative-system API surface.
+ *
+ * Thin wrappers used by the monolithic engines + generator pipeline.
+ * §64 migrated the "pattern" surface from `pattern-library.js` (retired)
+ * to the zettel `composition-library.js`. Function names kept
+ * (searchBlocks/lookupPattern/listPatterns/searchBlocksSemantic) for
+ * back-compat with engine call sites; internally they hit compositions.
+ */
+
+import { getCatalog, getComponent, getComponentsByCategory } from '../../retrieval/index.js';
+import { classifyIntent, assembleContext } from '../../retrieval/index.js';
+import { checkAllAntiPatterns } from '../../retrieval/index.js';
+import { serializeEntry } from '../../retrieval/index.js';
+import {
+  searchAll as searchCompositions,
+  getComposition,
+  getAllCompositions,
+} from '../strategies/zettel/composition-library.js';
+
+/**
+ * Compositions have `tags: { purpose: [...], complexity: "", layout: "" }`
+ * but the monolithic engines (instant/pro/thinking) all assume the old
+ * pattern shape `tags: [string]` and call `.map(...)` on it. Flatten on
+ * the way out so legacy call sites keep working without re-templating
+ * every engine. Annotated chunks expose flat-but-shallow `tags`; both
+ * are handled.
+ */
+function normalize(record) {
+  if (!record) return record;
+  let tags = record.tags;
+  if (Array.isArray(tags)) return record;
+  if (tags && typeof tags === 'object') {
+    tags = Object.values(tags)
+      .flat()
+      .filter((v) => typeof v === 'string');
+  } else {
+    tags = [];
+  }
+  return { ...record, tags };
+}
+
+/**
+ * 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 composition library by query.
+ * Returns full composition records (rehydrated from name hits).
+ * @param {string} query — Natural language or keyword query
+ * @returns {object[]}
+ */
+export function searchBlocks(query, { domain } = {}) {
+  const hits = searchCompositions(query);
+  const records = hits.map((h) => getComposition(h.name)).filter(Boolean);
+  const filtered = domain ? records.filter((c) => c.domain === domain) : records;
+  return filtered.map(normalize);
+}
+
+/**
+ * Get a specific named composition.
+ * @param {string} name — Composition name
+ * @returns {object|null}
+ */
+export function lookupPattern(name) {
+  return normalize(getComposition(name));
+}
+
+/**
+ * Get all available compositions.
+ * @returns {object[]}
+ */
+export function listPatterns() {
+  return getAllCompositions().map(normalize);
+}
+
+/**
+ * Keyword search wrapped as the legacy `{ matches }` return shape so the
+ * monolithic-thinking engine's call site keeps working. The historical
+ * LLM-driven semantic path retired with `pattern-library.js` in §64;
+ * compositions don't have a semantic search backend yet.
+ *
+ * @param {string} query
+ * @param {object} [_options] — accepted for back-compat; llmAdapter/remix ignored
+ * @returns {Promise<{ matches: object[] }>}
+ */
+export async function searchBlocksSemantic(query, _options = {}) {
+  return { matches: searchBlocks(query) };
+}
+
+/**
+ * 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/compose/core/state.js

@@ -0,0 +1,15 @@
+/**
+ * Shared module-level singletons for the monolithic engine.
+ *
+ * These were previously private to core/generator.js. Extracted so that
+ * strategies/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();

package/compose/evals/harness.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};

package/compose/evals/harness.mjs

@@ -0,0 +1,193 @@
+/**
+ * Generator-agnostic eval harness.
+ *
+ * Contract (generator return):
+ *   {
+ *     messages?:   Array,                // A2UI messages (may be empty)
+ *     validation?: { score: number },    // 0-100 (or absent)
+ *     strategy?:   string,               // architecture-specific label
+ *     retrieval?:  {                     // optional retrieval metadata
+ *       hit: boolean,                    // top result considered relevant
+ *       rank: number|null,               // 1-indexed rank of first relevant candidate
+ *       candidate: string|null,          // name of chosen pattern/composition
+ *     },
+ *     fragments_used?: string[],         // zettel-only
+ *     ...extra
+ *   }
+ *
+ * Two runners:
+ *   - runHarness()   legacy shape — preserved byte-for-byte for back-compat
+ *   - runHarnessV2() augmented shape — coverage / avgScoreWhenEmitted /
+ *                    retrievalMRR / per-intent strategy & fragment data
+ */
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function loadHeldOut() {
+  // held-out.jsonl lives in the sibling @adia-ai/gen-ui/corpus package.
+  // Callers can still pass `intents` explicitly; this fallback is the default.
+  // Path from here: packages/gen-ui/compose/evals/ → ../.. → packages/gen-ui/
+  // → corpus/evals/held-out.jsonl.
+  const evalsPath = join(__dirname, '..', '..', 'corpus', 'evals', 'held-out.jsonl');
+  const raw = await readFile(evalsPath, 'utf8');
+  return raw.trim().split('\n').map((l) => JSON.parse(l));
+}
+
+function computeF1(result, evalItem) {
+  // Handle both message shapes:
+  //   mcp:    [{ components: [{ component: 'Card', ... }] }]
+  //   zettel: [{ messageType: 'beginComponent', componentType: 'Card', ... }]
+  const msgs = result.messages || [];
+  const types = new Set();
+  for (const m of msgs) {
+    if (Array.isArray(m.components)) {
+      for (const c of m.components) if (c.component) types.add(c.component);
+    }
+    if (m.componentType) types.add(m.componentType);
+  }
+  const expected = new Set(evalItem.expected_components || []);
+  const tp = [...expected].filter((t) => types.has(t)).length;
+  const precision = types.size ? tp / types.size : 0;
+  const recall = expected.size ? tp / expected.size : 0;
+  const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0;
+  return { precision, recall, f1 };
+}
+
+// ── Legacy runner (byte-compat with pre-2026-04-17 inline code) ──
+
+export async function runHarness({ generate, domain, limit, mode = 'instant', intents }) {
+  let items = intents || (await loadHeldOut());
+  if (domain) items = items.filter((i) => i.domain === domain);
+  if (limit) items = items.slice(0, limit);
+
+  const results = [];
+  for (const evalItem of items) {
+    try {
+      const result = await generate({ intent: evalItem.intent, mode });
+      const score = result.validation?.score || 0;
+      const { f1 } = computeF1(result, evalItem);
+      results.push({
+        id: evalItem.id,
+        intent: evalItem.intent,
+        score,
+        f1: Math.round(f1 * 100),
+        pass: score >= (evalItem.expected_validation_min || 70),
+      });
+    } catch (e) {
+      results.push({
+        id: evalItem.id,
+        intent: evalItem.intent,
+        score: 0,
+        f1: 0,
+        pass: false,
+        error: e.message,
+      });
+    }
+  }
+
+  const passCount = results.filter((r) => r.pass).length;
+  const avgScore = Math.round(
+    results.reduce((s, r) => s + r.score, 0) / (results.length || 1),
+  );
+  return {
+    total: results.length,
+    pass: passCount,
+    avgScore,
+    passRate: Math.round((passCount / (results.length || 1)) * 100),
+    results,
+  };
+}
+
+// ── V2 runner (coverage-aware, architecture-fair) ──
+
+export async function runHarnessV2({ generate, domain, limit, mode = 'instant', intents, label = 'generator' }) {
+  let items = intents || (await loadHeldOut());
+  if (domain) items = items.filter((i) => i.domain === domain);
+  if (limit) items = items.slice(0, limit);
+
+  const results = [];
+  for (const evalItem of items) {
+    const row = {
+      id: evalItem.id,
+      intent: evalItem.intent,
+      domain: evalItem.domain,
+      strategy: null,
+      messagesEmitted: false,
+      validationScore: null,
+      precision: null,
+      recall: null,
+      componentF1: null,
+      retrievalHit: null,
+      retrievalRank: null,
+      candidate: null,
+      fragmentsUsed: null,
+      pass: false,
+      error: null,
+    };
+    try {
+      const result = await generate({ intent: evalItem.intent, mode });
+      const emitted = Array.isArray(result.messages) && result.messages.length > 0;
+      row.messagesEmitted = emitted;
+      row.strategy = result.strategy || (emitted ? 'emitted' : 'miss');
+      if (emitted) {
+        row.validationScore = result.validation?.score ?? null;
+        const { precision, recall, f1 } = computeF1(result, evalItem);
+        row.precision = Math.round(precision * 100);
+        row.recall = Math.round(recall * 100);
+        row.componentF1 = Math.round(f1 * 100);
+        row.pass = (row.validationScore ?? 0) >= (evalItem.expected_validation_min || 70);
+      }
+      if (result.retrieval) {
+        row.retrievalHit = !!result.retrieval.hit;
+        row.retrievalRank = result.retrieval.rank ?? null;
+        row.candidate = result.retrieval.candidate ?? null;
+      }
+      if (Array.isArray(result.fragments_used)) {
+        row.fragmentsUsed = result.fragments_used;
+      }
+    } catch (e) {
+      row.error = e.message;
+    }
+    results.push(row);
+  }
+
+  // ── Aggregates ──
+  const emitted = results.filter((r) => r.messagesEmitted);
+  const coverage = results.length ? emitted.length / results.length : 0;
+  const avgScoreWhenEmitted = emitted.length
+    ? emitted.reduce((s, r) => s + (r.validationScore || 0), 0) / emitted.length
+    : 0;
+  const avgF1WhenEmitted = emitted.length
+    ? emitted.reduce((s, r) => s + (r.componentF1 || 0), 0) / emitted.length
+    : 0;
+  const passCount = results.filter((r) => r.pass).length;
+
+  // Mean reciprocal rank over intents with retrieval metadata
+  const withRetrieval = results.filter((r) => r.retrievalRank != null);
+  const retrievalMRR = withRetrieval.length
+    ? withRetrieval.reduce((s, r) => s + 1 / r.retrievalRank, 0) / withRetrieval.length
+    : null;
+
+  const strategyBreakdown = results.reduce((acc, r) => {
+    const k = r.strategy || 'unknown';
+    acc[k] = (acc[k] || 0) + 1;
+    return acc;
+  }, {});
+
+  return {
+    label,
+    total: results.length,
+    coverage: Math.round(coverage * 100),        // % intents that emitted
+    emitted: emitted.length,
+    pass: passCount,
+    passRate: Math.round((passCount / (results.length || 1)) * 100),
+    avgScoreWhenEmitted: Math.round(avgScoreWhenEmitted),
+    avgF1WhenEmitted: Math.round(avgF1WhenEmitted),
+    retrievalMRR: retrievalMRR == null ? null : Math.round(retrievalMRR * 1000) / 1000,
+    strategyBreakdown,
+    results,
+  };
+}

package/compose/index.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};

package/compose/index.js

@@ -0,0 +1,16 @@
+/**
+ * @adia-ai/gen-ui — main entry.
+ *
+ * Re-exports the most common consumer surface. For deeper access, reach
+ * via subpaths:
+ *
+ *   import { generateUI }      from '@adia-ai/gen-ui';
+ *   import { pick, registerEngine } from '@adia-ai/gen-ui/compose/strategies/registry';
+ *   import { generateZettel }  from '@adia-ai/gen-ui/compose/strategies/zettel';
+ *
+ * The LLM bridge moved to its own package — `@adia-ai/llm/bridge`.
+ * See README for the full public surface.
+ */
+
+export { generateUI, generateUIStream } from './core/generator.js';
+export { pick, listEngines, registerEngine, unregisterEngine, ENGINES } from './strategies/registry.js';

package/compose/shared/validate-and-repair.js

@@ -0,0 +1,122 @@
+/**
+ * @adia-ai/gen-ui — shared closed-loop validate→repair helper.
+ *
+ * Extracted from monolithic-thinking's original inline loop (the only
+ * engine that had this before) so every LLM-calling strategy engine can
+ * share ONE implementation instead of each hand-rolling its own. Direct
+ * investigation of the pipeline (A2UI overhaul plan, 2026-07) found
+ * generate-thinking.js was the only one of six engines running a genuine
+ * closed loop against full schema + Ajv catalog conformance; generate-pro
+ * did one repair shot with no catalog check; chunk-zettel and free-form
+ * each validate a narrower plan/ingredient-grounding contract, not this
+ * one — see this module's docstring below for how those compose with it.
+ *
+ * ORTHOGONAL, FINAL-STAGE CHECK: this function knows nothing about plans,
+ * bindings, or ingredient grounding. An engine with its own narrower
+ * validation (chunk-zettel's slot bindings, free-form's ingredient
+ * grounding) runs its own loop FIRST, then routes the final candidate
+ * through this one for full schema/anti-pattern/catalog conformance —
+ * never as a replacement for the narrower check, always in addition to it.
+ *
+ * All escalation policy stays with the CALLER. This function never
+ * decides "should I retry with a bigger model" or "should I escalate" —
+ * it only runs the loop it's given and reports what failed. On exhaustion
+ * (no adapter supplied, or attempts used up) it returns `exhausted: true`
+ * — it never silently returns broken output without flagging it.
+ */
+
+import { validateSchema } from '@adia-ai/a2ui/validate';
+import { validateMessages as validateCatalog } from '../../validate/catalog-validator.js';
+
+/**
+ * @param {object} params
+ * @param {Array<object>} params.messages - candidate A2UI messages to validate
+ * @param {object|null} [params.llmAdapter] - omit/null to validate-only (no repair attempts)
+ * @param {(failedChecks: object[], messages: object[], catalogFailures: object[]) => string} [params.buildRepairPrompt]
+ *   - required whenever `llmAdapter` is supplied
+ * @param {(repairResponse: object, prevMessages: object[]) => object[]} [params.parseResponse]
+ *   - required whenever `llmAdapter` is supplied; parses one repair completion (the FULL response
+ *     object — e.g. `{content, stopReason, usage}` — not just its content string, so callers that
+ *     need per-response metadata like `stopReason` in their parse context don't have to thread it
+ *     through separately) into new messages
+ * @param {string} [params.systemPrompt] - forwarded verbatim to each repair completion call
+ * @param {object} [params.validateContext] - forwarded to validateSchema as its second arg (e.g. `{ intent, context }`)
+ * @param {(messages: object[], validation: object) => object} [params.foldInAntiPatterns]
+ *   - optional post-processing hook folding anti-pattern findings into the schema validation result
+ *     (monolithic engines' own `_shared.js` version); omit if the caller's `validateContext`/
+ *     validator already covers anti-patterns another way
+ * @param {number} [params.maxAttempts=3]
+ * @param {boolean} [params.runCatalogCheck=true]
+ * @param {(repairResponse: object) => void} [params.onAttempt]
+ *   - optional side-effect hook invoked with each raw repair completion (e.g. dialog-recorder capture);
+ *     this module has no opinion on recording, telemetry, or debug capture — callers own that entirely
+ * @returns {Promise<{messages: object[], valid: boolean, validation: object, catalogValidation: object, attempts: number, exhausted: boolean}>}
+ */
+export async function validateAndRepair({
+  messages,
+  llmAdapter = null,
+  buildRepairPrompt,
+  parseResponse,
+  systemPrompt,
+  validateContext = {},
+  foldInAntiPatterns,
+  maxAttempts = 3,
+  runCatalogCheck = true,
+  onAttempt,
+}) {
+  const runSchemaCheck = (msgs) => {
+    const base = validateSchema(msgs, validateContext);
+    return foldInAntiPatterns ? foldInAntiPatterns(msgs, base) : base;
+  };
+  const runCatalog = (msgs) => (runCatalogCheck ? validateCatalog(msgs) : Promise.resolve({ valid: true, failures: [] }));
+
+  let validation = runSchemaCheck(messages);
+  let catalogValidation = await runCatalog(messages);
+  let attempts = 0;
+
+  while ((!validation.valid || !catalogValidation.valid) && attempts < maxAttempts && llmAdapter) {
+    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,
+      });
+      onAttempt?.(repairResponse);
+      messages = parseResponse(repairResponse, messages);
+      validation = runSchemaCheck(messages);
+      catalogValidation = await runCatalog(messages);
+    } catch {
+      break; // stop repair loop on adapter error — report what we have
+    }
+  }
+
+  const valid = validation.valid && catalogValidation.valid;
+  return { messages, valid, validation, catalogValidation, attempts, exhausted: !valid };
+}
+
+/**
+ * REQ-03 (spec-factory-dx-ws4-acceptance) support — normalizes a
+ * `{validation, catalogValidation}` pair (this module's own return shape)
+ * into the `{code, message}[]` failures list the acceptance block carries.
+ * Same shape convention `exit-gate.js`'s own feedback array already speaks,
+ * built independently here rather than imported from it (a different
+ * consumer's module, per REQ-01's own reuse-the-validators-not-the-module
+ * rule).
+ *
+ * @param {object} [validation] - a `validateSchema` result (`.checks[]`)
+ * @param {object} [catalogValidation] - a `validateMessages` (catalog) result (`.failures[]`)
+ * @returns {{code: string, message: string}[]}
+ */
+export function buildFailures(validation, catalogValidation) {
+  return [
+    ...((validation?.checks || []).filter((c) => !c.passed).map((c) => ({ code: c.name, message: c.detail || c.name }))),
+    ...((catalogValidation?.failures || []).map((f) => ({
+      code: 'catalog',
+      message: typeof f === 'string' ? f : (f.message || JSON.stringify(f)),
+    }))),
+  ];
+}