@mmapp/react-compiler 0.1.0-alpha.1

package/src/babel/emitters/pure-form-emitter.ts

@@ -0,0 +1,1023 @@
+/**
+ * Workflow Emitter — assembles extracted pieces into IR, engine-compatible, and canonical outputs.
+ *
+ * Three output stages:
+ *   1. emitIR()                → IRWorkflowDefinition (the IR cache)
+ *   2. emitWorkflowDefinition() → engine-compatible JSON (state_type, field_type, action_type)
+ *   3. emitCanonical()          → PureFormWorkflow (canonical tree per 041 protocol)
+ *   4. emitCompiledOutput()     → { canonical, ir } (combined output)
+ *
+ * Data flow:
+ *   CompilerState → compilerStateToWorkflow() → ExtractedWorkflow → emitIR()         → IRWorkflowDefinition
+ *                                                                 → emitWorkflowDefinition() → engine-compatible JSON
+ *                                                                 → emitCanonical()  → PureFormWorkflow
+ *
+ * Critical contract: NOTHING extracted may be silently dropped.
+ * Every piece of data extracted by the visitor must appear in the output.
+ */
+
+import type {
+  IRWorkflowDefinition,
+  IRStateDefinition,
+  IRTransitionDefinition,
+  IRFieldDefinition,
+  IRConditionDefinition,
+  IRDuringAction,
+  IROnEventSubscription,
+  IRGrammarIsland,
+  IRActionDefinition,
+  IRExperienceNode,
+  IRDataSource,
+  PureFormWorkflow,
+} from '@mindmatrix/player-core';
+import { normalizeCategory } from '@mindmatrix/player-core';
+import type { ExtractedWorkflow, CompilerState } from '../../types';
+import type { FieldWatcher } from '../extractors/change-extractor';
+import type { TransitionEffect } from '../extractors/transition-effect-extractor';
+import { inferTransitionStates } from '../extractors/transition-extractor';
+import { transformToFrontend } from './experience-transform';
+
+// =============================================================================
+// View normalization (moved from seed-compiled.mjs into compiler)
+// =============================================================================
+
+const PROP_RULES: Record<string, { config?: Record<string, string>; bindings?: Record<string, string> }> = {
+  Text: {
+    config: { text: 'value' },
+    bindings: { text: 'value' },
+  },
+  Heading: {
+    config: { text: 'value' },
+    bindings: { text: 'value' },
+  },
+  Button: {
+    config: { text: 'label' },
+    bindings: { text: 'label', onPress: 'onClick' },
+  },
+};
+
+const COMPONENT_RENAMES: Record<string, string> = {
+  Heading: 'Text',
+};
+
+const RENAME_EXTRA_CONFIG: Record<string, Record<string, unknown>> = {
+  Heading: { variant: 'h2' },
+};
+
+/**
+ * Normalizes an ExperienceNode tree:
+ * - Renames components (Heading → Text + variant)
+ * - Remaps prop names (text→value, onPress→onClick)
+ * - Converts template strings ({field}) → $fn.concat() bindings
+ * - Rewrites .fire bindings → $action.transition()
+ * - Rewrites $instance.field → $instance.state_data.field
+ */
+function normalizeViewNode(node: IRExperienceNode, fieldNames: Set<string>): IRExperienceNode {
+  if (!node || typeof node !== 'object') return node;
+
+  // Rename component if needed
+  const originalComponent = node.component;
+  if (originalComponent && COMPONENT_RENAMES[originalComponent]) {
+    node.component = COMPONENT_RENAMES[originalComponent];
+    const extra = RENAME_EXTRA_CONFIG[originalComponent];
+    if (extra) {
+      node.config = { ...extra, ...(node.config || {}) };
+    }
+  }
+
+  // Apply prop rename rules
+  const rules = PROP_RULES[originalComponent || ''] || PROP_RULES[node.component || ''];
+  if (rules) {
+    if (node.config && rules.config) {
+      for (const [from, to] of Object.entries(rules.config)) {
+        if (from in node.config && !(to in node.config)) {
+          node.config[to] = node.config[from];
+          delete node.config[from];
+        }
+      }
+    }
+    if (node.bindings && rules.bindings) {
+      for (const [from, to] of Object.entries(rules.bindings)) {
+        if (from in node.bindings && !(to in node.bindings)) {
+          node.bindings[to] = node.bindings[from];
+          delete node.bindings[from];
+        }
+      }
+    }
+  }
+
+  // Convert template strings in config to bindings
+  if (node.config && fieldNames.size > 0) {
+    for (const [prop, val] of Object.entries(node.config)) {
+      if (typeof val !== 'string') continue;
+      const templateRe = /\{\{(\w+)\}\}|\{(\w+)\}/g;
+      let match;
+      const refs: Array<{ full: string; field: string; index: number }> = [];
+      while ((match = templateRe.exec(val)) !== null) {
+        const field = match[1] || match[2];
+        if (fieldNames.has(field)) {
+          refs.push({ full: match[0], field, index: match.index });
+        }
+      }
+      if (refs.length > 0) {
+        const parts: string[] = [];
+        let lastEnd = 0;
+        for (const ref of refs) {
+          const before = val.slice(lastEnd, ref.index);
+          if (before) parts.push(`"${before}"`);
+          parts.push(`$instance.state_data.${ref.field}`);
+          lastEnd = ref.index + ref.full.length;
+        }
+        const trailing = val.slice(lastEnd);
+        if (trailing) parts.push(`"${trailing}"`);
+        const expr = `$fn.concat(${parts.join(', ')})`;
+        if (!node.bindings) node.bindings = {};
+        node.bindings[prop] = expr;
+        delete node.config[prop];
+      }
+    }
+  }
+
+  // Rewrite bindings
+  if (node.bindings) {
+    for (const [prop, expr] of Object.entries(node.bindings)) {
+      if (typeof expr !== 'string') continue;
+
+      // .fire bindings → $action.transition("name")
+      if (expr.endsWith('.fire')) {
+        const transitionName = expr.slice(0, -5);
+        node.bindings[prop] = `$action.transition("${transitionName}")`;
+        continue;
+      }
+
+      // $instance.fieldName → $instance.state_data.fieldName
+      if (fieldNames.size > 0 && expr.startsWith('$instance.')) {
+        const field = expr.slice('$instance.'.length);
+        if (fieldNames.has(field)) {
+          node.bindings[prop] = `$instance.state_data.${field}`;
+        }
+      }
+    }
+  }
+
+  if (node.children && Array.isArray(node.children)) {
+    node.children = node.children.map(child => normalizeViewNode(child, fieldNames));
+
+    // Fold single Text children into parent config/bindings — only when the
+    // child Text is "simple" (no style, className, children, or extra config).
+    // Use PROP_RULES-mapped key so the result is already canonical.
+    if (node.children.length === 1 && node.children[0].component === 'Text') {
+      const textChild = node.children[0];
+      // Only fold when the child Text is truly simple — no style, className,
+      // children, visible_when, or extra config/binding keys beyond value.
+      const configKeys = textChild.config ? Object.keys(textChild.config).filter(k => k !== 'value') : [];
+      const bindingKeys = textChild.bindings ? Object.keys(textChild.bindings).filter(k => k !== 'value') : [];
+      const isSimple = !textChild.style && !textChild.className && !textChild.children
+        && !textChild.visible_when && configKeys.length === 0 && bindingKeys.length === 0;
+      if (isSimple) {
+        const parentRules = PROP_RULES[node.component || ''];
+        const configKey = parentRules?.config?.text || 'text';
+        const bindingKey = parentRules?.bindings?.text || 'text';
+        if (textChild.config?.value && !textChild.bindings) {
+          // Static text child: fold into config
+          if (!node.config) node.config = {};
+          node.config[configKey] = textChild.config.value;
+          delete node.children;
+        } else if (textChild.bindings?.value && !textChild.config?.value) {
+          // Dynamic text child: fold into bindings
+          if (!node.bindings) node.bindings = {};
+          node.bindings[bindingKey] = textChild.bindings.value;
+          delete node.children;
+        }
+      }
+    }
+  }
+
+  return node;
+}
+
+// =============================================================================
+// Utility functions
+// =============================================================================
+
+/**
+ * Converts camelCase to snake_case.
+ */
+function toSnakeCase(str: string): string {
+  return str.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+}
+
+/**
+ * Converts action from IR format (type) to engine format (action_type).
+ */
+function convertAction(action: any): any {
+  return {
+    id: action.id,
+    action_type: action.type,
+    config: action.config || {},
+    ...(action.condition && { condition: action.condition }),
+  };
+}
+
+/**
+ * Converts an IRDuringAction to engine format.
+ */
+function convertDuringAction(during: IRDuringAction): Record<string, unknown> {
+  return {
+    id: during.id,
+    type: during.type,
+    ...(during.interval_ms !== undefined && { interval_ms: during.interval_ms }),
+    ...(during.cron && { cron: during.cron }),
+    ...(during.delay_ms !== undefined && { delay_ms: during.delay_ms }),
+    actions: during.actions.map(convertAction),
+    ...(during.condition && { condition: during.condition }),
+  };
+}
+
+/**
+ * Converts an IROnEventSubscription to engine format.
+ */
+function convertOnEvent(sub: IROnEventSubscription): Record<string, unknown> {
+  return {
+    match: sub.match,
+    ...(sub.description && { description: sub.description }),
+    conditions: sub.conditions || [],
+    actions: sub.actions.map((a) => ({
+      type: a.type,
+      ...(a.field && { field: a.field }),
+      ...(a.expression && { expression: a.expression }),
+      ...(a.key && { key: a.key }),
+      ...(a.message && { message: a.message }),
+      ...(a.config && { config: a.config }),
+      ...(a.conditions && a.conditions.length > 0 && { conditions: a.conditions }),
+    })),
+  };
+}
+
+// =============================================================================
+// IR Emission (renamed from emitPureForm)
+// =============================================================================
+
+/**
+ * Emits IR from extracted workflow data.
+ *
+ * This is the lowered IR output — everything extracted ends up here.
+ * View tree is normalized and emitted as a top-level `view` field
+ * (not inside metadata.experience).
+ */
+export function emitIR(extracted: ExtractedWorkflow): IRWorkflowDefinition {
+  const { slug, name, version, description, category, fields, states, transitions } = extracted;
+
+  // Convert state map to array
+  const stateArray: IRStateDefinition[] = Array.from(states.values());
+
+  // Ensure at least one START state exists
+  if (stateArray.length === 0) {
+    stateArray.push({
+      name: 'draft',
+      type: 'START',
+      on_enter: [],
+      during: [],
+      on_exit: [],
+    });
+  } else {
+    const hasStart = stateArray.some((s) => s.type === 'START');
+    if (!hasStart && stateArray.length > 0) {
+      stateArray[0].type = 'START';
+    }
+  }
+
+  // Only infer from/to for transitions that don't already have explicit values
+  inferTransitionStates(transitions, states);
+
+  // Validate: every transition references existing states
+  const stateNames = new Set(stateArray.map((s) => s.name));
+  for (const transition of transitions) {
+    if (transition.to && !stateNames.has(transition.to)) {
+      stateArray.push({
+        name: transition.to,
+        type: 'REGULAR',
+        on_enter: [],
+        during: [],
+        on_exit: [],
+      });
+      stateNames.add(transition.to);
+    }
+  }
+
+  // Normalize view tree (prop renames, binding rewrites, template conversion)
+  const fieldNames = new Set(fields.map(f => f.name));
+  let normalizedView: IRExperienceNode | undefined;
+  if (extracted.experience) {
+    normalizedView = normalizeViewNode(
+      JSON.parse(JSON.stringify(extracted.experience)),
+      fieldNames,
+    );
+
+    // Attach dataSources from useQuery() extractions to the root view node
+    const dataSources = extracted.extraMetadata?.dataSources as IRDataSource[] | undefined;
+    if (dataSources && dataSources.length > 0) {
+      normalizedView.dataSources = dataSources;
+    }
+
+    // Attach localDefaults config for $local initialization from useState fields
+    if (fields.length > 0) {
+      const localDefaults: Record<string, unknown> = {};
+      for (const f of fields) {
+        localDefaults[toSnakeCase(f.name)] = f.default_value ?? null;
+      }
+      if (!normalizedView.config) normalizedView.config = {};
+      normalizedView.config.localDefaults = localDefaults;
+    }
+  }
+
+  // Build metadata — include everything extracted EXCEPT experience (now top-level view)
+  const metadata: Record<string, unknown> = {
+    stable_id: `def-${slug}`,
+    provenance: {
+      frontend: 'react-compiler',
+      source: `${slug}.workflow.tsx`,
+      compiler_version: '1.0.0',
+    },
+  };
+  if (extracted.fieldWatchers && extracted.fieldWatchers.length > 0) {
+    metadata.fieldWatchers = extracted.fieldWatchers;
+  }
+  if (extracted.transitionEffects && extracted.transitionEffects.length > 0) {
+    metadata.transitionEffects = extracted.transitionEffects;
+  }
+  // Forward extra metadata from model files (runtime, etc.)
+  if (extracted.extraMetadata) {
+    for (const [key, value] of Object.entries(extracted.extraMetadata)) {
+      metadata[key] = value;
+    }
+  }
+
+  // Keep experience in metadata for backward compatibility during migration
+  if (extracted.experience) {
+    metadata.experience = extracted.experience;
+  }
+
+  const ir: IRWorkflowDefinition = {
+    slug,
+    name,
+    version,
+    description,
+    category,
+    fields,
+    states: stateArray,
+    transitions,
+    roles: [],
+    tags: [],
+    metadata,
+  };
+
+  // Attach normalized view as views.default (IR format)
+  // Also attach frontend-compatible view via transform pass
+  if (normalizedView) {
+    (ir as any).views = { default: normalizedView };
+    (ir as any).frontendViews = { default: transformToFrontend(normalizedView) };
+  }
+
+  // Emit workflow-level on_event
+  if (extracted.events && extracted.events.length > 0) {
+    ir.on_event = extracted.events;
+  }
+
+  // Emit grammar islands as extensions
+  if (extracted.grammarIslands && extracted.grammarIslands.length > 0) {
+    const extensions: Record<string, typeof extracted.grammarIslands> = {};
+    for (const island of extracted.grammarIslands) {
+      const key = island.contextTag;
+      if (!extensions[key]) extensions[key] = [];
+      extensions[key].push(island);
+    }
+    ir.extensions = extensions;
+  }
+
+  return ir;
+}
+
+/** @deprecated Use emitIR() instead. Kept for backward compatibility. */
+export const emitPureForm = emitIR;
+
+// =============================================================================
+// Canonical Tree Emission (per 041 protocol)
+// =============================================================================
+
+/**
+ * Lifts an IR action into canonical form.
+ */
+function liftAction(action: IRActionDefinition): PureFormWorkflow {
+  const parts: PureFormWorkflow[] = [];
+
+  if (action.config) {
+    for (const [key, value] of Object.entries(action.config)) {
+      parts.push({
+        slug: key,
+        category: ['atom'],
+        parts: [{ slug: String(value), category: ['atom'] }],
+      });
+    }
+  }
+
+  if (action.condition) {
+    parts.push({
+      slug: 'condition',
+      category: ['expression', 'guard'],
+      parts: [{ slug: action.condition, category: ['binding'] }],
+    });
+  }
+
+  return {
+    slug: action.id,
+    category: normalizeCategory('expression', 'mutation', action.type),
+    parts: parts.length > 0 ? parts : undefined,
+  };
+}
+
+/**
+ * Lifts an IR during action (schedule) into canonical form.
+ */
+function liftSchedule(during: IRDuringAction): PureFormWorkflow {
+  const parts: PureFormWorkflow[] = [];
+
+  if (during.interval_ms !== undefined) {
+    parts.push({
+      slug: 'every',
+      category: ['atom'],
+      parts: [{ slug: String(during.interval_ms), category: ['literal'] }],
+    });
+  }
+
+  if (during.cron) {
+    parts.push({
+      slug: 'cron',
+      category: ['atom'],
+      parts: [{ slug: during.cron, category: ['literal'] }],
+    });
+  }
+
+  if (during.delay_ms !== undefined) {
+    parts.push({
+      slug: 'delay',
+      category: ['atom'],
+      parts: [{ slug: String(during.delay_ms), category: ['literal'] }],
+    });
+  }
+
+  // Lift inner actions
+  for (const action of during.actions) {
+    parts.push({
+      slug: 'do',
+      category: normalizeCategory('expression', 'mutation', action.type),
+      parts: Object.entries(action.config || {}).map(([key, value]) => ({
+        slug: key,
+        category: ['atom'],
+        parts: [{ slug: String(value), category: ['atom'] }],
+      })),
+    });
+  }
+
+  return {
+    slug: during.id,
+    category: normalizeCategory('schedule', during.type),
+    parts,
+  };
+}
+
+/**
+ * Lifts an IR state into canonical form.
+ */
+function liftState(state: IRStateDefinition): PureFormWorkflow {
+  const parts: PureFormWorkflow[] = [];
+  const tags: string[] = [];
+
+  if (state.type === 'START') tags.push('start');
+  if (state.type === 'END') tags.push('end');
+  if (state.type === 'CANCELLED') tags.push('cancelled');
+
+  // on_enter actions
+  if (state.on_enter && state.on_enter.length > 0) {
+    parts.push({
+      slug: 'on_enter',
+      category: normalizeCategory('expression', 'sequence'),
+      parts: state.on_enter.map(liftAction),
+    });
+  }
+
+  // on_exit actions
+  if (state.on_exit && state.on_exit.length > 0) {
+    parts.push({
+      slug: 'on_exit',
+      category: normalizeCategory('expression', 'sequence'),
+      parts: state.on_exit.map(liftAction),
+    });
+  }
+
+  // during actions (schedules)
+  if (state.during && state.during.length > 0) {
+    for (const d of state.during) {
+      parts.push(liftSchedule(d));
+    }
+  }
+
+  return {
+    slug: state.name,
+    category: normalizeCategory('state', ...tags),
+    parts: parts.length > 0 ? parts : undefined,
+  };
+}
+
+/**
+ * Lifts an IR transition into canonical form.
+ */
+function liftTransition(transition: IRTransitionDefinition): PureFormWorkflow {
+  const parts: PureFormWorkflow[] = [];
+
+  // from refs
+  if (transition.from && transition.from.length > 0) {
+    parts.push({
+      slug: 'from',
+      category: ['part'],
+      parts: transition.from.map((s: string) => ({ slug: s, category: ['ref'] as string[] })),
+    });
+  }
+
+  // to ref
+  if (transition.to) {
+    parts.push({
+      slug: 'to',
+      category: ['part'],
+      parts: [{ slug: transition.to, category: ['ref'] }],
+    });
+  }
+
+  // actions
+  if (transition.actions && transition.actions.length > 0) {
+    parts.push({
+      slug: 'actions',
+      category: normalizeCategory('expression', 'sequence'),
+      parts: transition.actions.map(liftAction),
+    });
+  }
+
+  // conditions
+  if (transition.conditions && transition.conditions.length > 0) {
+    parts.push({
+      slug: 'conditions',
+      category: normalizeCategory('expression', 'guard'),
+      parts: transition.conditions.map((c: IRConditionDefinition, i: number) => ({
+        slug: `condition_${i}`,
+        category: normalizeCategory('expression', c.type || 'condition'),
+        parts: c.expression ? [{ slug: c.expression, category: ['binding'] as string[] }] : undefined,
+      })),
+    });
+  }
+
+  return {
+    slug: transition.name,
+    category: ['transition'],
+    parts,
+  };
+}
+
+/**
+ * Lifts an IR field into canonical form.
+ */
+function liftField(field: IRFieldDefinition): PureFormWorkflow {
+  const parts: PureFormWorkflow[] = [];
+
+  if (field.label) {
+    parts.push({
+      slug: 'label',
+      category: ['atom'],
+      parts: [{ slug: field.label, category: ['atom'] }],
+    });
+  }
+
+  if (field.default_value !== undefined) {
+    parts.push({
+      slug: 'default',
+      category: ['atom'],
+      parts: [{ slug: String(field.default_value), category: ['literal'] }],
+    });
+  }
+
+  if (field.required) {
+    parts.push({ slug: 'required', category: ['atom'], parts: [{ slug: 'true', category: ['literal'] }] });
+  }
+
+  if (field.computed) {
+    parts.push({
+      slug: 'computed',
+      category: ['expression'],
+      parts: [{ slug: field.computed, category: ['binding'] }],
+    });
+  }
+
+  return {
+    slug: field.name,
+    category: normalizeCategory('field', field.type),
+    parts: parts.length > 0 ? parts : undefined,
+  };
+}
+
+/**
+ * Lifts an ExperienceNode tree into canonical view form.
+ */
+function liftView(node: IRExperienceNode): PureFormWorkflow {
+  const componentTag = (node.component || 'stack').toLowerCase().replace(/\s+/g, '-');
+  const parts: PureFormWorkflow[] = [];
+
+  // Config as atom parts
+  if (node.config) {
+    for (const [key, value] of Object.entries(node.config)) {
+      parts.push({
+        slug: key,
+        category: ['atom'],
+        parts: [{ slug: String(value), category: ['atom'] }],
+      });
+    }
+  }
+
+  // Bindings as expression parts
+  if (node.bindings) {
+    for (const [key, expr] of Object.entries(node.bindings)) {
+      if (key === 'onClick' || key === 'onPress') {
+        // Transition binding
+        const match = typeof expr === 'string' ? expr.match(/\$action\.transition\("(.+?)"\)/) : null;
+        if (match) {
+          parts.push({
+            slug: key,
+            category: normalizeCategory('expression', 'effect', 'transition'),
+            parts: [{ slug: match[1], category: ['ref'] }],
+          });
+        } else {
+          parts.push({
+            slug: key,
+            category: normalizeCategory('expression', 'binding'),
+            parts: [{ slug: String(expr), category: ['binding'] }],
+          });
+        }
+      } else {
+        parts.push({
+          slug: key,
+          category: normalizeCategory('expression', 'binding'),
+          parts: [{ slug: String(expr), category: ['binding'] }],
+        });
+      }
+    }
+  }
+
+  // visible_when as guard expression
+  if (node.visible_when) {
+    const eqMatch = node.visible_when.match(/\$fn\.eq\((.+?),\s*"(.+?)"\)/);
+    if (eqMatch) {
+      parts.push({
+        slug: 'visible_when',
+        category: normalizeCategory('expression', 'guard'),
+        parts: [{
+          slug: 'body',
+          category: normalizeCategory('expression', 'eq'),
+          parts: [
+            { slug: 'lhs', category: normalizeCategory('expression', 'path'), parts: [{ slug: eqMatch[1], category: ['binding'] }] },
+            { slug: 'rhs', category: normalizeCategory('expression', 'literal'), parts: [{ slug: eqMatch[2], category: ['literal'] }] },
+          ],
+        }],
+      });
+    } else {
+      parts.push({
+        slug: 'visible_when',
+        category: normalizeCategory('expression', 'guard'),
+        parts: [{ slug: node.visible_when, category: ['binding'] }],
+      });
+    }
+  }
+
+  // Recurse children
+  if (node.children && node.children.length > 0) {
+    for (const child of node.children) {
+      parts.push(liftView(child));
+    }
+  }
+
+  return {
+    slug: node.id,
+    category: normalizeCategory('view', componentTag),
+    parts: parts.length > 0 ? parts : undefined,
+  };
+}
+
+/**
+ * Emits canonical tree from extracted workflow data.
+ *
+ * Produces `{ slug, category, parts, metadata }` per 041 protocol.
+ * This is the TRUTH. The IR is a derivable cache.
+ */
+export function emitCanonical(extracted: ExtractedWorkflow, sourceFilename?: string): PureFormWorkflow {
+  // First get the IR to reuse its processing (START state inference, transition validation, etc.)
+  const ir = emitIR(extracted);
+
+  const parts: PureFormWorkflow[] = [];
+
+  // Lift states
+  for (const state of ir.states) {
+    parts.push(liftState(state));
+  }
+
+  // Lift transitions
+  for (const transition of ir.transitions) {
+    parts.push(liftTransition(transition));
+  }
+
+  // Lift fields
+  for (const field of ir.fields) {
+    parts.push(liftField(field));
+  }
+
+  // Lift view tree (from original experience, not normalized IR view)
+  if (extracted.experience) {
+    parts.push(liftView(extracted.experience));
+  }
+
+  // Manifest as meta part
+  parts.push({
+    slug: 'manifest',
+    category: normalizeCategory('meta', 'manifest'),
+    parts: [
+      {
+        slug: 'workflows',
+        category: ['ref-list'],
+        parts: [{ slug: ir.slug, category: ['ref'] }],
+      },
+      {
+        slug: 'route',
+        category: ['route'],
+        parts: [
+          { slug: 'path', category: ['atom'], parts: [{ slug: `/${ir.slug}`, category: ['atom'] }] },
+          { slug: 'label', category: ['atom'], parts: [{ slug: ir.name, category: ['atom'] }] },
+        ],
+      },
+    ],
+  });
+
+  // Parse category: the user-specified category is the primary.
+  // Open category set — any string is valid (workflow, data, blueprint, module,
+  // data-type, view, expression-library, or user-defined categories).
+  // If the category contains a slash (e.g., "workflow/demo"), split into primary + tag.
+  const category = extracted.category;
+  let categoryArray: string[];
+  if (category.includes('/')) {
+    const [primary, ...tags] = category.split('/');
+    categoryArray = normalizeCategory(primary, ...tags);
+  } else {
+    categoryArray = [category];
+  }
+
+  return {
+    slug: ir.slug,
+    category: categoryArray,
+    parts,
+    metadata: {
+      stable_id: `def-${ir.slug}`,
+      provenance: {
+        frontend: 'react-compiler',
+        source: sourceFilename || `${ir.slug}.workflow.tsx`,
+        compiler_version: '1.0.0',
+        compiled_at: new Date().toISOString(),
+      },
+    },
+  };
+}
+
+/**
+ * Emits the combined compiled output: canonical tree + lowered IR.
+ */
+export function emitCompiledOutput(extracted: ExtractedWorkflow, sourceFilename?: string): { canonical: PureFormWorkflow; ir: IRWorkflowDefinition } {
+  return {
+    canonical: emitCanonical(extracted, sourceFilename),
+    ir: emitIR(extracted),
+  };
+}
+
+// =============================================================================
+// Text-content folding (lightweight, no renames/rewrites)
+// =============================================================================
+
+/**
+ * Folds single Text children into parent config/bindings.
+ * e.g. <Heading>Counter</Heading> → Heading with config.text = "Counter"
+ * e.g. <Text>{count}</Text> → Text with bindings.text = "$instance.count"
+ * Does NOT rename components or rewrite bindings — that's normalizeViewNode's job.
+ */
+function foldTextContent(node: IRExperienceNode): IRExperienceNode {
+  if (!node || typeof node !== 'object') return node;
+
+  if (node.children && Array.isArray(node.children)) {
+    node.children = node.children.map(child => foldTextContent(child));
+
+    // Fold single Text children into parent — only when truly simple
+    if (node.children.length === 1 && node.children[0].component === 'Text') {
+      const textChild = node.children[0];
+      const configKeys = textChild.config ? Object.keys(textChild.config).filter((k: string) => k !== 'value') : [];
+      const bindingKeys = textChild.bindings ? Object.keys(textChild.bindings).filter((k: string) => k !== 'value') : [];
+      const isSimple = !textChild.style && !textChild.className && !textChild.children
+        && !textChild.visible_when && configKeys.length === 0 && bindingKeys.length === 0;
+      if (isSimple) {
+        const parentRules = PROP_RULES[node.component || ''];
+        const configKey = parentRules?.config?.text || 'text';
+        const bindingKey = parentRules?.bindings?.text || 'text';
+        if (textChild.config?.value && !textChild.bindings) {
+          if (!node.config) node.config = {};
+          node.config[configKey] = textChild.config.value;
+          node.children = undefined as any;
+        } else if (textChild.bindings?.value && !textChild.config?.value) {
+          if (!node.bindings) node.bindings = {};
+          node.bindings[bindingKey] = textChild.bindings.value;
+          node.children = undefined as any;
+        }
+      }
+    }
+
+    // Clean up empty children arrays
+    if (node.children && node.children.length === 0) {
+      node.children = undefined as any;
+    }
+  }
+
+  // Remove undefined children from serialization
+  if (!node.children) delete (node as any).children;
+
+  return node;
+}
+
+// =============================================================================
+// Engine-compatible Definition Emission
+// =============================================================================
+
+/**
+ * Emits a LocalWorkflowEngine-compatible WorkflowDefinition.
+ *
+ * This converts from the IR format to the engine format:
+ * - state.type → state.state_type
+ * - field.type → field.field_type
+ * - action.type → action.action_type
+ * - during actions → engine format with action_type
+ * - on_event → preserved per-state and at workflow level
+ * - camelCase field names → snake_case
+ */
+export function emitWorkflowDefinition(extracted: ExtractedWorkflow): Record<string, unknown> {
+  const ir = emitIR(extracted);
+
+  // Convert states: type → state_type, actions type → action_type
+  const states = ir.states.map((s) => ({
+    name: s.name,
+    state_type: s.type,
+    description: s.description || '',
+    on_enter: (s.on_enter || []).map(convertAction),
+    on_exit: (s.on_exit || []).map(convertAction),
+    during: (s.during || []).map(convertDuringAction),
+    on_event: (s.on_event || []).map(convertOnEvent),
+  }));
+
+  // Convert fields: type → field_type, name to snake_case, preserve ACL
+  const fields = ir.fields.map((f) => ({
+    name: toSnakeCase(f.name),
+    field_type: f.type,
+    label: f.label || f.name.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase()),
+    required: f.required || false,
+    default_value: f.default_value ?? null,
+    ...(f.validation && { validation: f.validation }),
+    ...(f.computed && { computed: f.computed }),
+    ...(f.computed_deps && { computed_deps: f.computed_deps }),
+    ...(f.visible_in_states && { visible_in_states: f.visible_in_states }),
+    ...(f.editable_in_states && { editable_in_states: f.editable_in_states }),
+    ...(f.visible_to_roles && { visible_to_roles: f.visible_to_roles }),
+    ...(f.editable_by_roles && { editable_by_roles: f.editable_by_roles }),
+    ...(f.visible_when && { visible_when: f.visible_when }),
+    ...(f.editable_when && { editable_when: f.editable_when }),
+    ...(f.state_home && { state_home: f.state_home }),
+  }));
+
+  // Convert transitions: add engine-expected extra fields
+  const transitions = ir.transitions.map((t) => ({
+    name: t.name,
+    from: t.from,
+    to: t.to,
+    description: t.description || '',
+    roles: t.roles || [],
+    auto: t.auto || false,
+    conditions: t.conditions || [],
+    actions: (t.actions || []).map(convertAction),
+    required_fields: t.required_fields || [],
+    priority: 0,
+  }));
+
+  // Build state_data from fields
+  const state_data: Record<string, unknown> = {};
+  for (const f of fields) {
+    state_data[f.name] = f.default_value;
+  }
+
+  // Build workflow-level on_event
+  const on_event = (ir.on_event || []).map(convertOnEvent);
+
+  // Build views from raw experience (with text-content folding only, no normalization)
+  let views: Record<string, unknown> | undefined;
+  if (extracted.experience) {
+    const viewRoot = foldTextContent(JSON.parse(JSON.stringify(extracted.experience)));
+
+    // Attach dataSources to the engine-compatible view root
+    const dataSources = extracted.extraMetadata?.dataSources as IRDataSource[] | undefined;
+    if (dataSources && dataSources.length > 0) {
+      viewRoot.dataSources = dataSources;
+    }
+
+    // Attach localDefaults for $local initialization
+    if (extracted.fields.length > 0) {
+      const localDefaults: Record<string, unknown> = {};
+      for (const f of extracted.fields) {
+        localDefaults[toSnakeCase(f.name)] = f.default_value ?? null;
+      }
+      if (!viewRoot.config) viewRoot.config = {};
+      viewRoot.config.localDefaults = localDefaults;
+    }
+
+    views = { default: viewRoot };
+  }
+
+  return {
+    id: `def-${ir.slug}`,
+    slug: ir.slug,
+    name: ir.name,
+    version: ir.version,
+    description: ir.description || '',
+    category: ir.category,
+    states,
+    transitions,
+    fields,
+    state_data,
+    roles: [],
+    child_definitions: [],
+    tags: ir.tags || [],
+    metadata: ir.metadata || {},
+    ...(views && { views }),
+    ...(on_event.length > 0 && { on_event }),
+    config: {},
+    is_immutable: false,
+  };
+}
+
+// =============================================================================
+// Compiler State Conversion
+// =============================================================================
+
+/**
+ * Converts compiler state to ExtractedWorkflow.
+ *
+ * Critical: must transfer ALL extracted data — nothing may be lost.
+ */
+export function compilerStateToWorkflow(state: CompilerState, metadata: {
+  slug?: string;
+  name?: string;
+  version?: string;
+  description?: string;
+  category?: string;
+  [key: string]: unknown;
+}): ExtractedWorkflow {
+  // Extract field watchers and transition effects from metadata
+  const fieldWatchers = (metadata.fieldWatchers as FieldWatcher[] | undefined) || [];
+  const transitionEffects = (metadata.transitionEffects as TransitionEffect[] | undefined) || [];
+
+  // Extract grammar islands from metadata
+  const grammarIslands = (metadata.grammarIslands as IRGrammarIsland[] | undefined) || [];
+
+  // Collect extra metadata — everything that isn't a known key
+  const knownKeys = new Set(['slug', 'name', 'version', 'description', 'category', 'fieldWatchers', 'transitionEffects', 'grammarIslands', '__modelImports', '__modelImportSlugs', '__slugAutoFallback']);
+  const extraMetadata: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (!knownKeys.has(key) && value !== undefined) {
+      extraMetadata[key] = value;
+    }
+  }
+
+  return {
+    slug: metadata.slug || 'workflow',
+    name: metadata.name || 'Workflow',
+    version: metadata.version || '0.1.0',
+    description: metadata.description,
+    category: metadata.category || 'workflow',
+    fields: state.fields || [],
+    states: state.states || new Map(),
+    transitions: state.transitions || [],
+    events: state.events || [],
+    experience: state.experience,
+    fieldWatchers: fieldWatchers.length > 0 ? fieldWatchers : undefined,
+    transitionEffects: transitionEffects.length > 0 ? transitionEffects : undefined,
+    grammarIslands: grammarIslands.length > 0 ? grammarIslands : undefined,
+    errors: state.errors,
+    warnings: state.warnings,
+    extraMetadata: Object.keys(extraMetadata).length > 0 ? extraMetadata : undefined,
+  };
+}