@adia-ai/gen-ui 0.8.37

package/compose/strategies/free-form-composer/index.js

@@ -0,0 +1,254 @@
+/**
+ * free-form-composer — generative composition mode (§88, v0.4.8).
+ *
+ * The third generative path between verbatim retrieval (zettel's
+ * `composition-match`) and free-hand LLM generation (`monolithic-pro`).
+ *
+ * Treats the annotated-chunk corpus as an INGREDIENT VOCABULARY. The
+ * foundation model is given the catalog (28 chunks as of cut), declares
+ * an ordered list of ingredients + optional text-only substitutions, and
+ * the transpiler stitches a net-new A2UI tree that echoes the patterns
+ * the corpus documents without copying them verbatim.
+ *
+ * Grounding rule (v0.4.6 §62, carried forward): every ingredient name is
+ * an annotated chunk that traces to a real page via `data-chunk-*` markers.
+ * The strategy enforces this by rejecting any plan whose ingredient names
+ * aren't in the live `getAllCompositions()` result.
+ *
+ * Hallucination guard: one retry with explicit feedback ("you used X
+ * which isn't an ingredient"). If the retry still hallucinates, the
+ * strategy returns an empty-messages result with strategy label
+ * `free-form-hallucinated` so the upstream registry can fall through to
+ * monolithic-pro.
+ *
+ * No LLM available: returns `strategy='free-form-no-llm'` immediately;
+ * caller falls through.
+ */
+
+import { getAllCompositions } from '../zettel/composition-library.js';
+import {
+  buildFreeFormSystemPrompt,
+  buildFreeFormUserMessage,
+  buildFreeFormRetryMessage,
+  buildFreeFormParaphraseRetry,
+} from './system-prompt.js';
+import { transpilePlan, parsePlan } from './transpile.js';
+import { validateAndRepair } from '../../shared/validate-and-repair.js';
+
+const MAX_ATTEMPTS = 2;
+
+/**
+ * Run the free-form composer for a single intent.
+ *
+ * @param {object} opts
+ * @param {string} opts.intent — user intent
+ * @param {object|null} opts.llmAdapter — LLM adapter with `.complete({messages, systemPrompt}) → {content, ...}`
+ * @param {object[]} [opts.compositions] — override vocabulary (test fixtures); defaults to live corpus
+ * @returns {Promise<{
+ *   messages: object[],
+ *   validation: { score: number, warnings?: string[] },
+ *   strategy: string,
+ *   plan: object|null,
+ *   usedIngredients: string[],
+ *   attempts: number,
+ *   warnings: string[],
+ *   rationale: string|null,
+ * }>}
+ */
+export async function generateFreeForm({ intent, llmAdapter = null, compositions = null } = {}) {
+  if (!intent || typeof intent !== 'string') {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: ['empty or invalid intent'] },
+      strategy: 'free-form-bad-input',
+      plan: null,
+      usedIngredients: [],
+      attempts: 0,
+      warnings: ['empty or invalid intent'],
+      rationale: null,
+    };
+  }
+
+  const vocab = Array.isArray(compositions) ? compositions : getAllCompositions();
+  if (vocab.length === 0) {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: ['empty vocabulary'] },
+      strategy: 'free-form-empty-vocab',
+      plan: null,
+      usedIngredients: [],
+      attempts: 0,
+      warnings: ['empty vocabulary: 0 annotated chunks available'],
+      rationale: null,
+    };
+  }
+
+  if (!llmAdapter || typeof llmAdapter.complete !== 'function') {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: ['no LLM adapter; free-form requires LLM'] },
+      strategy: 'free-form-no-llm',
+      plan: null,
+      usedIngredients: [],
+      attempts: 0,
+      warnings: ['free-form-composer requires an LLM adapter (mode=pro|thinking, not instant)'],
+      rationale: null,
+    };
+  }
+
+  const systemPrompt = buildFreeFormSystemPrompt(vocab);
+  const vocabNames = new Set(vocab.map(c => c.name));
+  const chunkLookup = new Map(vocab.map(c => [c.name, c]));
+
+  let userMessage = buildFreeFormUserMessage(intent);
+  let plan = null;
+  let invalidNames = [];
+  let emptyPlanRetryUsed = false;
+  let attempt = 0;
+
+  for (attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    let raw;
+    try {
+      const response = await llmAdapter.complete({
+        messages: [{ role: 'user', content: userMessage }],
+        systemPrompt,
+      });
+      raw = response?.content || '';
+    } catch (err) {
+      return {
+        messages: [],
+        validation: { score: 0, warnings: [`LLM call failed: ${err?.message || err}`] },
+        strategy: 'free-form-llm-error',
+        plan: null,
+        usedIngredients: [],
+        attempts: attempt,
+        warnings: [`LLM call failed on attempt ${attempt}: ${err?.message || err}`],
+        rationale: null,
+      };
+    }
+
+    const candidate = parsePlan(raw);
+    if (!candidate) {
+      // Parse-fail counts as a hallucination — retry once.
+      invalidNames = ['<parse-fail>'];
+      userMessage = `Compose a UI for: "${intent}"
+
+Note: your previous response wasn't valid JSON. Output ONLY the JSON object — no prose, no fenced code block markers around it.`;
+      continue;
+    }
+
+    invalidNames = candidate.ingredients
+      .filter(ing => !ing || typeof ing.name !== 'string' || !vocabNames.has(ing.name))
+      .map(ing => ing?.name ?? '<missing-name>');
+
+    if (invalidNames.length === 0) {
+      plan = candidate;
+      break;
+    }
+
+    // Retry with explicit hallucination feedback.
+    userMessage = buildFreeFormRetryMessage(intent, invalidNames);
+  }
+
+  if (!plan) {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: [`hallucination guard tripped after ${MAX_ATTEMPTS} attempts; invalid: ${invalidNames.join(', ')}`] },
+      strategy: 'free-form-hallucinated',
+      plan: null,
+      usedIngredients: [],
+      attempts: MAX_ATTEMPTS,
+      warnings: [`exhausted ${MAX_ATTEMPTS} attempts; final invalid names: ${invalidNames.join(', ')}`],
+      rationale: null,
+    };
+  }
+
+  let { messages, warnings, usedIngredients } = transpilePlan(plan, chunkLookup);
+
+  // §106 (v0.5.1): if the LLM declined to compose (`{ingredients: []}`),
+  // fire one paraphrase-retry with explicit shape-matching guidance. Many
+  // empty-plan cases on the v0.5.0 §104 eval were keyword-mismatch (chunk
+  // exists, intent uses different vocab). This retry is OUTSIDE the
+  // MAX_ATTEMPTS hallucination budget — one-shot reserve specifically for
+  // shape-match recovery.
+  if (messages.length === 0 && plan?.ingredients?.length === 0) {
+    emptyPlanRetryUsed = true;
+    const paraphraseMessage = buildFreeFormParaphraseRetry(intent);
+    try {
+      const response = await llmAdapter.complete({
+        messages: [{ role: 'user', content: paraphraseMessage }],
+        systemPrompt,
+      });
+      const retryPlan = parsePlan(response?.content || '');
+      const retryInvalid = retryPlan?.ingredients
+        ?.filter(ing => !ing || typeof ing.name !== 'string' || !vocabNames.has(ing.name))
+        .map(ing => ing?.name ?? '<missing-name>') ?? [];
+      attempt += 1;
+      if (retryPlan && retryInvalid.length === 0 && retryPlan.ingredients.length > 0) {
+        plan = retryPlan;
+        const retryTranspile = transpilePlan(plan, chunkLookup);
+        messages = retryTranspile.messages;
+        warnings = retryTranspile.warnings;
+        usedIngredients = retryTranspile.usedIngredients;
+      }
+    } catch {
+      // Paraphrase-retry LLM failure — fall through to empty-plan.
+    }
+  }
+
+  if (messages.length === 0) {
+    return {
+      messages: [],
+      validation: { score: 0, warnings: warnings.concat(['transpile produced no messages']) },
+      strategy: 'free-form-empty-plan',
+      plan,
+      usedIngredients,
+      attempts: attempt,
+      warnings,
+      rationale: plan.rationale || null,
+      emptyPlanRetryUsed,
+    };
+  }
+
+  // Full schema/catalog/anti-pattern conformance — the same final pass
+  // every other LLM-calling engine runs (see validate-and-repair.js).
+  // Validate-ONLY (no llmAdapter passed): a repair attempt here would mean
+  // re-authoring the ingredient PLAN, not the transpiled A2UI JSON
+  // directly — this engine's whole paradigm is ingredient selection +
+  // deterministic transpilation, not direct JSON authoring, so a schema-
+  // failure repair prompt has no natural target to hand back to the LLM.
+  // The existing hallucination-guard retry loop above (ingredient-name
+  // grounding) is this engine's own repair mechanism.
+  //
+  // REQ-05 (spec-factory-dx-ws4-acceptance): `validation.score` is now the
+  // MEASURED `schemaCheck.validation.score` — the verbatim 85 this engine
+  // reported on every success path (real validation ran, gh#pre-WS-4, but
+  // nothing read its score) made the release trip-wire's
+  // `avgScoreWhenEmitted` floor (`check-free-form-eval-regression.mjs`)
+  // tautological: it could only move when the pipeline broke outright.
+  // The floor itself is re-derived from the first honest run under
+  // a2ui-maintenance's ownership (preserve-not-regress cadence), not touched here.
+  // REQ-02: `validation.valid` is now first-class too — `judgeEngineResult`
+  // reads it for `free-form-composed` (a strong-emission strategy) instead
+  // of trusting the strategy label alone; `schemaValid`/`schemaValidation`
+  // stay as the pre-existing side fields for any consumer still reading them.
+  const schemaCheck = await validateAndRepair({ messages });
+  if (!schemaCheck.valid) {
+    warnings = warnings.concat([`schema/anti-pattern check failed (score ${schemaCheck.validation.score}): ${schemaCheck.validation.checks?.filter(c => !c.passed).map(c => c.name).join(', ') || 'see schemaValidation'}`]);
+  }
+  const score = schemaCheck.validation.score;
+
+  return {
+    messages,
+    validation: { score, valid: schemaCheck.valid, warnings },
+    strategy: 'free-form-composed',
+    plan,
+    usedIngredients,
+    attempts: attempt,
+    warnings,
+    rationale: plan.rationale || null,
+    emptyPlanRetryUsed,
+    schemaValid: schemaCheck.valid,
+    schemaValidation: schemaCheck.validation,
+  };
+}

package/compose/strategies/free-form-composer/system-prompt.js

@@ -0,0 +1,205 @@
+/**
+ * system-prompt.js — builds the system prompt for free-form-composer.
+ *
+ * Treats the annotated-chunk corpus as an INGREDIENT VOCABULARY. The LLM
+ * sees a catalog of available ingredients with their domain + description +
+ * keywords, plus the per-ingredient SUBSTITUTABLE NODES (text-bearing
+ * primitives whose label / name / href the LLM can tailor per-intent),
+ * then outputs an ordered ingredient list + per-ingredient substitutions.
+ *
+ * The transpiler stitches the resulting plan into a net-new A2UI tree that
+ * echoes the chunks' shapes without copying them verbatim.
+ *
+ * Design choice: substitutions key on the chunk's INNER node IDs. Showing
+ * the IDs in the prompt makes the substitution surface explicit + grep-able.
+ * The transpiler's `SUBSTITUTABLE_ATTRS` map names which components are
+ * substitution-eligible + which attribute receives the value
+ * (Text.textContent, Button.text, Badge.text, Tag.text, Kbd.textContent,
+ * Icon.name, Image.alt, Link.href). v0.4.8 §88 shipped Text-only; v0.5.0
+ * §105 expanded to the seven listed.
+ *
+ * Vocabulary refresh cadence: the catalog is rebuilt from
+ * `composition-library.getAllCompositions()` on every prompt build —
+ * cheap (in-memory map of 64 entries today) and ensures the LLM sees the
+ * current corpus state without explicit cache invalidation.
+ */
+
+import { SUBSTITUTABLE_ATTRS } from './transpile.js';
+
+const MAX_DESCRIPTION_LEN = 140;
+const MAX_TEXT_PREVIEW = 60;
+const MAX_SUBSTITUTABLES_PER_INGREDIENT = 8;
+
+/**
+ * Extract substitutable nodes from a chunk template. Returns a compact
+ * `[{ id, attr, preview }]` array — the LLM uses `id` as the substitution
+ * key; `attr` names the target attribute (text / textContent / name /
+ * alt / href); `preview` is the current value truncated for prompt
+ * economy (empty string when the node carries no current value, which is
+ * common for Button.text / Badge.text / Icon.name in the corpus).
+ *
+ * @param {object[]} template — flat A2UI node list
+ * @returns {Array<{id: string, attr: string, preview: string}>}
+ */
+function extractSubstitutables(template) {
+  if (!Array.isArray(template)) return [];
+  const nodes = [];
+  for (const node of template) {
+    const attr = SUBSTITUTABLE_ATTRS[node?.component];
+    if (!attr) continue;
+    const raw = node[attr];
+    const value = typeof raw === 'string' ? raw : '';
+    const preview = value.length > MAX_TEXT_PREVIEW
+      ? value.slice(0, MAX_TEXT_PREVIEW - 1) + '…'
+      : value;
+    nodes.push({ id: node.id, attr, preview });
+  }
+  return nodes;
+}
+
+/**
+ * Render a single ingredient as a prompt line. Format:
+ *
+ *   - <name> (<domain>): <description (truncated)>
+ *     keywords: a, b, c
+ *     substitutables: title.textContent="Sign in"; submit.text; logo.alt="Adia Logo"
+ *
+ * Substitutables line is omitted when the chunk has zero substitutable
+ * nodes. Entries with a current value show `id.attr="..."`; entries
+ * without (Button/Icon nodes with no preset text/name) show just `id.attr`.
+ */
+function renderIngredient(c) {
+  const desc = (c.description || '').slice(0, MAX_DESCRIPTION_LEN);
+  const lines = [`- ${c.name} (${c.domain || 'general'}): ${desc}`];
+  if (Array.isArray(c.keywords) && c.keywords.length > 0) {
+    lines.push(`    keywords: ${c.keywords.slice(0, 8).join(', ')}`);
+  }
+  const subs = extractSubstitutables(c.template);
+  if (subs.length > 0) {
+    const compact = subs
+      .slice(0, MAX_SUBSTITUTABLES_PER_INGREDIENT)
+      .map(s => s.preview ? `${s.id}.${s.attr}="${s.preview}"` : `${s.id}.${s.attr}`)
+      .join('; ');
+    lines.push(`    substitutables: ${compact}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build the system prompt. Caller passes the live `getAllCompositions()`
+ * result; this function doesn't import composition-library directly so the
+ * strategy entry point can pass test fixtures in unit tests.
+ *
+ * @param {object[]} compositions — output of `getAllCompositions()`
+ * @returns {string}
+ */
+export function buildFreeFormSystemPrompt(compositions) {
+  const ingredients = (compositions || []).slice().sort((a, b) => {
+    const da = a.domain || 'z'; const db = b.domain || 'z';
+    if (da !== db) return da < db ? -1 : 1;
+    return a.name < b.name ? -1 : 1;
+  });
+
+  const catalog = ingredients.map(renderIngredient).join('\n\n');
+  const ingredientNames = ingredients.map(c => c.name).join(', ');
+
+  return `You are a UI composer for the AdiaUI design system. You work by picking INGREDIENTS — pre-built UI regions that have been annotated for retrieval — and arranging them in order to satisfy the user's intent.
+
+You DO NOT write A2UI JSON directly. You output a PLAN: an ordered list of ingredient names plus optional text-content substitutions and an optional root container choice. A separate transpiler turns your plan into A2UI messages.
+
+INGREDIENTS AVAILABLE (${ingredients.length}):
+
+${catalog}
+
+INTENT PARAPHRASE — vocabulary vs shape:
+
+The user's intent often uses different vocabulary than the catalog's ingredient keywords. **Match on SHAPE — what the user wants to render — not exact keyword overlap.** Examples:
+
+- intent: "AI response with streaming text" → ingredient: \`ai-streaming-response\` (shape: assistant message bubble with token-streaming indicator). The intent doesn't say "message bubble" but the shape is identical.
+- intent: "real-time metrics with sparklines" → ingredient: \`real-time-metrics-dashboard\` and/or \`dashboard-spark-cards\` (shape: live-update metric grid).
+- intent: "modal dialog with a form" → ingredients: \`destructive-confirm-modal\` + \`form-page-shell\` (shape: overlay + stacked form fields).
+- intent: "settings panel" → ingredient: \`settings-form-page\` or \`account-settings-form\` (shape: titled stack of grouped fields).
+- intent: "team listing" → ingredients: \`avatar-stack\` + \`directory-table\` (shape: who's in the org).
+
+When in doubt, prefer to **emit a plausible 1-2-ingredient plan** based on shape match over returning empty-plan. Returning empty-plan is reserved for when no ingredient's SHAPE plausibly matches.
+
+CONSTRAINTS:
+
+1. Use ONLY ingredient names from the list above. Names not in the list are hallucinations — your response will be rejected if any \`name\` field is unknown.
+2. Order your ingredients in the sequence they should appear in the rendered UI. The transpiler wraps your list in a root container — by default a vertical Column. Override via the optional \`layout\` field (see below).
+3. Each ingredient may carry a \`substitutions\` object. KEYS are node IDs from the \`substitutables:\` line in the catalog above (e.g. \`"title"\`, \`"submit"\`, \`"logo"\`). VALUES are the new content strings. The transpiler routes each substitution to the right attribute based on the node's component: \`Text\` / \`Kbd\` → \`textContent\`; \`Button\` / \`Badge\` / \`Tag\` → \`text\`; \`Icon\` → \`name\`; \`Image\` → \`alt\`; \`Link\` → \`href\`. Nodes whose component is not in the substitutable list are locked at their declared values.
+
+   **ALWAYS substitute** any title, heading, button label, or badge label that the user's intent specifies. Default chunk text is generic placeholder ("Sign in to AdiaUI", "Continue", "Welcome back"); your job is to tailor it to the user's actual intent. Substituting MORE is better than substituting less — empty \`substitutions\` ships generic copy that misses the intent.
+
+   **Substitution examples per shape** (study these before emitting):
+
+   - **Text / Kbd (textContent)**: intent "trial-signup form for ContextEngine" → \`{"title": "Start your ContextEngine trial", "submit": "Create account"}\` not \`{}\`.
+   - **Button (text)**: intent "submit a support ticket" → \`{"submit-btn": "Open ticket"}\` not \`{"submit-btn": "Submit"}\`.
+   - **Badge / Tag (text)**: intent "show overdue invoices with status" → \`{"status-badge": "Overdue"}\` not \`{"status-badge": "Status"}\`.
+   - **Icon (name)**: intent "delete the project" → \`{"action-icon": "trash"}\` not omitting the icon substitution.
+   - **Image (alt)**: intent "team photo with three engineers" → \`{"hero-image": "Three engineers at a whiteboard"}\` not \`{}\`.
+   - **Link (href)**: intent "footer link to /docs/api" → \`{"docs-link": "/docs/api"}\` not \`{"docs-link": "#"}\`.
+
+   **Before emitting, self-check**: re-read the user's intent. Does it specify any content (text label, badge, icon, alt-text, URL)? If yes, every matching substitutable in your picked ingredients should appear in \`substitutions\`. If the intent is content-agnostic ("a sign-up form"), empty \`substitutions\` is correct.
+4. If you can't satisfy the intent with the available ingredients, return \`{ "ingredients": [] }\` and a rationale explaining what's missing.
+5. Output ONLY the JSON object below, no explanation outside the JSON.
+
+LAYOUT (optional root container):
+
+The transpiler stacks your ingredients inside a single root container. The default is \`Column\` (vertical stack). For horizontal or grid arrangements set \`layout\` to one of:
+
+- \`"column"\` — vertical stack (default; omit \`layout\` for this shape). Use for: forms stacking fields, content sections stacking top-to-bottom, hero → features → footer pages.
+- \`"row"\` — horizontal stack with automatic wrapping. Use for: nav items, inline button groups, small tag clusters, 2-3 cards side-by-side.
+- \`"grid"\` — responsive grid. Use for: pricing tiers (3 cards), KPI dashboards (4 stat tiles), feature grids, image galleries, testimonial grids. Add an optional \`columns\` field with a string like \`"3"\`, \`"4"\`, or \`"auto-fill"\`; default is \`"auto-fill"\` (responsive density).
+
+When the intent reads as "side by side" / "in a row" / "horizontally", pick \`"row"\`. When it reads as "grid of N" / "tiles" / "cards in columns", pick \`"grid"\`. When in doubt, omit \`layout\` and let the default Column apply.
+
+OUTPUT SCHEMA (strict):
+
+\`\`\`json
+{
+  "ingredients": [
+    {
+      "name": "<one of: ${ingredientNames.length > 200 ? ingredientNames.slice(0, 200) + '… (see list above)' : ingredientNames}>",
+      "substitutions": { "<text-node-id>": "<new text>" }
+    }
+  ],
+  "layout": "column" | "row" | "grid",
+  "columns": "<grid columns: number string '1'..'6' or 'auto-fill'>",
+  "rationale": "<one short sentence: why this arrangement>"
+}
+\`\`\`
+
+The \`substitutions\`, \`layout\`, and \`columns\` fields are all optional.`;
+}
+
+/**
+ * Build the user message for an intent. Kept separate from system prompt
+ * so future iteration prompts can extend it (e.g. with prior-canvas diffs).
+ */
+export function buildFreeFormUserMessage(intent) {
+  return `Compose a UI for: "${intent}"`;
+}
+
+/**
+ * Build a retry user message that surfaces invalid ingredient names from a
+ * prior attempt. Called by the strategy entry point on hallucination.
+ */
+export function buildFreeFormRetryMessage(intent, invalidNames) {
+  const list = invalidNames.slice(0, 5).join(', ');
+  return `Compose a UI for: "${intent}"
+
+Note: your previous response used ${invalidNames.length === 1 ? 'an ingredient name' : 'ingredient names'} that ${invalidNames.length === 1 ? "isn't" : "aren't"} in the catalog: ${list}. Use ONLY names from the INGREDIENTS list above, exactly as shown.`;
+}
+
+/**
+ * Build a paraphrase-retry user message for an empty-plan result. Used when
+ * the LLM returned a valid plan with `ingredients: []` — the keyword
+ * extraction didn't surface a shape match. The retry nudges the LLM toward
+ * shape-based reasoning rather than verbatim vocabulary lookup. §106 (v0.5.1).
+ */
+export function buildFreeFormParaphraseRetry(intent) {
+  return `Compose a UI for: "${intent}"
+
+Note: your previous response was an empty plan. Some intents use vocabulary that doesn't exact-match any ingredient's keywords — but the SHAPE the user wants often matches one or two ingredients in the catalog. Re-read the INGREDIENTS list and identify the closest shape match (e.g. "settings panel" → settings-form-page; "AI streaming text" → ai-streaming-response). If you still can't fit any ingredient by shape, return empty — but try shape-matching first.`;
+}