@adia-ai/gen-ui 0.8.37

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

@@ -0,0 +1,279 @@
+/**
+ * transpile.js — turn a free-form composer plan into A2UI messages.
+ *
+ * Input: a `plan` object from the LLM in the shape:
+ *
+ *   { ingredients: [{ name: string, substitutions?: object }], rationale: string }
+ *
+ * Output: a single `updateComponents` message with a `Column` root that
+ * wraps every ingredient's template in sequence.
+ *
+ * Stitch design:
+ * - Each ingredient's nodes get prefixed IDs (`<ingredientName>__<originalId>`)
+ *   so concatenating two ingredients with overlapping IDs doesn't collide.
+ *   Children references inside each chunk are rewritten to point at the
+ *   prefixed IDs.
+ * - The root `Column` enumerates the prefixed ROOT id of each ingredient
+ *   as its children (defined by the first node in each chunk template).
+ *
+ * Substitution rules (v0.5.0 §105 — multi-attribute scope):
+ * - Substitution key = chunk-internal node ID (the same `id` field the
+ *   prompt surfaces in the `substitutables:` line per ingredient).
+ * - Each substitutable component has ONE target attribute defined in
+ *   `SUBSTITUTABLE_ATTRS` below. The transpiler maps node.component →
+ *   target attribute name automatically; the substitution value lands
+ *   on that attribute regardless of whether the node currently carries
+ *   one.
+ * - Nodes whose `component` isn't in the map produce a `warnings[]`
+ *   entry; the substitution is dropped.
+ * - Unknown substitution keys (no node with that ID) produce a
+ *   `warnings[]` entry; transpile continues.
+ *
+ * The v0.4.8 §88 ship of this file restricted substitutions to
+ * Text.textContent only. The v0.5.0 §105 expansion adds Button.text,
+ * Badge.text, Tag.text, Icon.name, Image.alt, Link.href, Kbd.textContent —
+ * the 7 most common consumer-tweaked text-bearing attributes per the
+ * v0.5.0 plan §99-rev table. Non-text "structural" substitutions
+ * (swapping Card → Section, etc.) remain out of scope.
+ *
+ * Root container picker (v0.5.0 §103, auto-grouping):
+ * - Plan may carry `layout: "column" | "row" | "grid"` to override the
+ *   default `Column` root. `"row"` wraps in a Row with wrap=true (for
+ *   horizontal nav / inline-card sequences). `"grid"` wraps in a Grid
+ *   with `columns` from the plan (or `"auto-fill"` fallback) for
+ *   responsive tile / pricing-tier layouts. Missing / unknown `layout`
+ *   value falls through to `Column` — back-compat for v0.4.8 plans.
+ *
+ * Out of scope:
+ * - Slot-conflict resolution (two ingredients claiming the same slot).
+ *   The current stitch is sequential-stacking inside the root; slot
+ *   conflicts cannot arise because no shared slot surface exists.
+ * - Nested-composition (ingredients-inside-ingredients).
+ * - Cross-chunk merge (fusing two chunks rather than stacking).
+ * - Structural substitutions (swap Card → Section, etc.).
+ */
+
+const VALID_LAYOUTS = new Set(['column', 'row', 'grid']);
+
+/**
+ * Maps component name → the single attribute that consumer substitutions
+ * target on that component. The set was chosen from the v0.5.0 §99-rev
+ * plan table: text-bearing primitives' "primary text attribute" + the
+ * two URL/alt-text attributes consumers tweak most often.
+ *
+ * Components NOT in this map are non-substitutable from a free-form
+ * plan: substitution keys pointing at e.g. a Card or Column node are
+ * reported as warnings.
+ *
+ * @type {Record<string, string>}
+ */
+export const SUBSTITUTABLE_ATTRS = {
+  Text: 'textContent',
+  Button: 'text',
+  Badge: 'text',
+  Tag: 'text',
+  Kbd: 'textContent',
+  Icon: 'name',
+  Image: 'alt',
+  Link: 'href',
+};
+
+/**
+ * Apply text substitutions to a single chunk's template. Returns a fresh
+ * cloned array with prefixed IDs + substituted textContent where keys match.
+ *
+ * @param {object[]} template — original chunk template
+ * @param {string} prefix — ingredient name, used for ID namespacing
+ * @param {object} substitutions — { [innerNodeId]: newText }
+ * @returns {{ nodes: object[], rootId: string, warnings: string[] }}
+ */
+function applyIngredient(template, prefix, substitutions = {}) {
+  if (!Array.isArray(template) || template.length === 0) {
+    return { nodes: [], rootId: null, warnings: [`empty template for ingredient "${prefix}"`] };
+  }
+  const warnings = [];
+  const subKeys = Object.keys(substitutions || {});
+  const usedSubKeys = new Set();
+  const prefixId = (id) => `${prefix}__${id}`;
+
+  const nodes = template.map((node) => {
+    const cloned = { ...node, id: prefixId(node.id) };
+    if (Array.isArray(node.children)) {
+      cloned.children = node.children.map(prefixId);
+    }
+    if (Object.hasOwn(substitutions, node.id)) {
+      usedSubKeys.add(node.id);
+      const targetAttr = SUBSTITUTABLE_ATTRS[node.component];
+      if (targetAttr) {
+        cloned[targetAttr] = String(substitutions[node.id]);
+      } else {
+        warnings.push(`substitution skipped: "${node.id}" in "${prefix}" is component=${node.component ?? '?'}, not in SUBSTITUTABLE_ATTRS map`);
+      }
+    }
+    return cloned;
+  });
+
+  for (const k of subKeys) {
+    if (!usedSubKeys.has(k)) {
+      warnings.push(`unknown substitution key: "${k}" in "${prefix}" (no node with that id)`);
+    }
+  }
+
+  return {
+    nodes,
+    rootId: prefixId(template[0].id),
+    warnings,
+  };
+}
+
+/**
+ * Transpile a plan into A2UI messages. Returns:
+ *
+ *   { messages: [{type:'updateComponents', components: [...]}],
+ *     warnings: string[],
+ *     usedIngredients: string[] }
+ *
+ * If `ingredients` is empty after resolution, returns
+ * `{ messages: [], warnings: [...], usedIngredients: [] }` — caller decides
+ * whether that's a fallthrough or an error.
+ *
+ * @param {{ ingredients: Array<{name: string, substitutions?: object}>, rationale?: string }} plan
+ * @param {Map<string, object> | Function} chunkLookup — Map or function
+ *   `(name) => composition | undefined`. The strategy entry point typically
+ *   passes a Map built from `getAllCompositions()` for O(1) lookups.
+ * @returns {{ messages: object[], warnings: string[], usedIngredients: string[] }}
+ */
+export function transpilePlan(plan, chunkLookup) {
+  const warnings = [];
+  const usedIngredients = [];
+
+  if (!plan || !Array.isArray(plan.ingredients) || plan.ingredients.length === 0) {
+    return { messages: [], warnings: ['plan has no ingredients'], usedIngredients };
+  }
+
+  const lookup = typeof chunkLookup === 'function'
+    ? chunkLookup
+    : (name) => chunkLookup.get(name);
+
+  const flatComponents = [];
+  const rootChildren = [];
+
+  for (const ing of plan.ingredients) {
+    if (!ing || typeof ing.name !== 'string') {
+      warnings.push(`malformed ingredient entry: ${JSON.stringify(ing)}`);
+      continue;
+    }
+    const chunk = lookup(ing.name);
+    if (!chunk) {
+      warnings.push(`ingredient not found in vocabulary: "${ing.name}"`);
+      continue;
+    }
+    const { nodes, rootId, warnings: ingWarnings } = applyIngredient(
+      chunk.template,
+      ing.name,
+      ing.substitutions || {}
+    );
+    warnings.push(...ingWarnings);
+    if (rootId) {
+      flatComponents.push(...nodes);
+      rootChildren.push(rootId);
+      usedIngredients.push(ing.name);
+    }
+  }
+
+  if (rootChildren.length === 0) {
+    return { messages: [], warnings, usedIngredients };
+  }
+
+  const root = buildRoot(plan, rootChildren, warnings);
+
+  return {
+    messages: [{
+      type: 'updateComponents',
+      surfaceId: 'main',
+      components: [root, ...flatComponents],
+    }],
+    warnings,
+    usedIngredients,
+  };
+}
+
+/**
+ * Build the root container node for the transpiled plan. Reads
+ * `plan.layout` and, for grids, `plan.columns`. Defaults to Column when
+ * `layout` is missing or unknown (back-compat with v0.4.8 plans).
+ *
+ * @param {object} plan — the parsed LLM plan
+ * @param {string[]} rootChildren — prefixed root IDs from each ingredient
+ * @param {string[]} warnings — mutated; receives invalid-layout warnings
+ * @returns {object} the root A2UI node
+ */
+function buildRoot(plan, rootChildren, warnings) {
+  const requested = typeof plan?.layout === 'string' ? plan.layout.toLowerCase() : null;
+  let layout = 'column';
+  if (requested) {
+    if (VALID_LAYOUTS.has(requested)) {
+      layout = requested;
+    } else {
+      warnings.push(`unknown layout: "${plan.layout}" — falling back to Column`);
+    }
+  }
+
+  const base = {
+    // 'root' — not 'free-form-root' — matches the convention every other
+    // engine's root component uses (validator.js's checkHasRootComponent
+    // hard-fails without it: "at least one component with id: 'root'").
+    // This engine never ran real schema validation before Phase 3 of the
+    // A2UI overhaul plan, so the mismatch went unnoticed until then.
+    id: 'root',
+    gap: '6',
+    children: rootChildren,
+  };
+
+  if (layout === 'row') {
+    return { ...base, component: 'Row', wrap: true };
+  }
+  if (layout === 'grid') {
+    const columns = typeof plan?.columns === 'string' && plan.columns.length > 0
+      ? plan.columns
+      : 'auto-fill';
+    return { ...base, component: 'Grid', columns };
+  }
+  return { ...base, component: 'Column' };
+}
+
+/**
+ * Parse a raw LLM response into a plan object. The LLM is asked to emit
+ * strict JSON; we accept either a bare JSON object or one wrapped in a
+ * fenced code block (the most common drift mode).
+ *
+ * Returns `null` if parsing fails — caller treats that as a hallucination
+ * and retries (or falls through).
+ */
+export function parsePlan(rawContent) {
+  if (typeof rawContent !== 'string') return null;
+  let text = rawContent.trim();
+
+  // Strip fenced code block if present.
+  const fenceMatch = text.match(/^```(?:json)?\s*([\s\S]*?)```\s*$/i);
+  if (fenceMatch) text = fenceMatch[1].trim();
+
+  // If the response starts with explanation prose, try to find the first { ... } block.
+  if (!text.startsWith('{')) {
+    const firstBrace = text.indexOf('{');
+    const lastBrace = text.lastIndexOf('}');
+    if (firstBrace === -1 || lastBrace <= firstBrace) return null;
+    text = text.slice(firstBrace, lastBrace + 1);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== 'object') return null;
+  if (!Array.isArray(parsed.ingredients)) return null;
+  return parsed;
+}