@mmapp/react-compiler 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,1099 @@
+import { E as ExtractedWorkflow, C as CompilerState, a as CompilerOptions } from './index-revho_gS.js';
+export { R as ReactCompilerError, b as babelPlugin } from './index-revho_gS.js';
+import { NodePath, Visitor } from '@babel/traverse';
+import * as t from '@babel/types';
+import { IRWorkflowDefinition, PureFormWorkflow, IRDataSource, IRExperienceNode as IRExperienceNode$1 } from '@mindmatrix/player-core';
+export { B as BuildOptions, d as BuildResult, a as DevServerInstance, D as DevServerOptions, b as build, c as createDevServer } from './dev-server-Bs_sz2DG.js';
+import { F as FileRole } from './envelope-DD7v0v6E.js';
+export { B as BuildEnvelopeOptions, c as BuildEnvelopeResult, a as EnvelopeFile, E as EnvelopeManifest, i as EnvelopeMetadata, n as FsTree, o as FsTreeEntry, h as SourceBinding, S as SourceEnvelope, b as buildEnvelope, e as computeEnvelopeId, d as createSourceEnvelope, k as detectFileRole, g as diffEnvelopes, m as diffFsTrees, f as envelopesEqual, l as filterByRole, j as generateFsTree } from './envelope-DD7v0v6E.js';
+import 'vite';
+
+/**
+ * State Extractor — extracts useState calls and converts them to IRFieldDefinition.
+ *
+ * INPUT:
+ *   const [count, setCount] = useState(0);
+ *   const [name, setName] = useState('');
+ *   const [active, setActive] = useState(false);
+ *   const [items, setItems] = useState<string[]>([]);
+ *
+ * OUTPUT:
+ *   [
+ *     { name: "count", type: "number", default_value: 0 },
+ *     { name: "name", type: "text", default_value: "" },
+ *     { name: "active", type: "boolean", default_value: false },
+ *     { name: "items", type: "json", default_value: [] }
+ *   ]
+ */
+
+/**
+ * Main extractor function called from the visitor.
+ */
+declare function extractStates(path: NodePath<t.CallExpression>, state: any): void;
+
+/**
+ * Effect Extractor — extracts useOnEnter, useOnExit calls and converts callback bodies to IRActionDefinition.
+ *
+ * INPUT:
+ *   useOnEnter('active', () => {
+ *     setCount(1);
+ *     setMemory('entered', true);
+ *   });
+ *
+ *   useOnExit('active', () => {
+ *     console.log('left active');
+ *   });
+ *
+ * OUTPUT for state 'active':
+ *   {
+ *     on_enter: [
+ *       { id: "auto_1", type: "set_field", mode: "auto", config: { field: "count", value: 1 } },
+ *       { id: "auto_2", type: "set_memory", mode: "auto", config: { key: "entered", value: true } }
+ *     ],
+ *     on_exit: [
+ *       { id: "auto_3", type: "log_event", mode: "auto", config: { message: "left active" } }
+ *     ]
+ *   }
+ */
+
+/**
+ * Main extractor function called from the visitor.
+ */
+declare function extractEffects(path: NodePath<t.CallExpression>, state: any): void;
+
+/**
+ * Transition Extractor — extracts useTransition calls to build IRTransitionDefinition.
+ *
+ * INPUT:
+ *   const submit = useTransition('submit');
+ *   const cancel = useTransition('cancel');
+ *
+ * OUTPUT:
+ *   [
+ *     { name: "submit", from: [], to: "", actions: [], conditions: [] },
+ *     { name: "cancel", from: [], to: "", actions: [] }
+ *   ]
+ *
+ * Note: The from/to states are inferred during the emitter phase by analyzing state flow.
+ */
+
+/**
+ * Main extractor function called from the visitor.
+ *
+ * Supports two forms:
+ *   useTransition('submit')
+ *   useTransition('submit', { from: ['DRAFT'], to: 'SUBMITTED' })
+ */
+declare function extractTransitions(path: NodePath<t.CallExpression>, state: any): void;
+
+/**
+ * Event Extractor — extracts useOnEvent calls and converts them to IROnEventSubscription.
+ *
+ * INPUT:
+ *   useOnEvent('message.received', (event) => {
+ *     setField('message_count', getField('message_count') + 1);
+ *   }, { while: 'active' });
+ *
+ * OUTPUT (added to state 'active' on_event):
+ *   {
+ *     match: "message.received",
+ *     conditions: [],
+ *     actions: [
+ *       { type: "set_field", field: "message_count", expression: "message_count + 1" }
+ *     ]
+ *   }
+ */
+
+/**
+ * Main extractor function called from the visitor.
+ */
+declare function extractEvents(path: NodePath<t.CallExpression>, state: any): void;
+
+/**
+ * Component Extractor — extracts JSX return value into IRExperienceNode tree.
+ *
+ * Handles:
+ * - JSX elements with identifier and member expression names
+ * - Fragments (anonymous containers)
+ * - Text content as Text nodes
+ * - Expression children ({count}, {status})
+ * - Conditional rendering ({show && <X/>}, {cond ? <A/> : <B/>})
+ * - List rendering ({items.map(i => <Item/>)})
+ * - Spread attributes
+ * - visible_when, data-slot special attributes
+ */
+
+/**
+ * Main extractor function called from the visitor.
+ */
+declare function extractComponents(path: NodePath<t.ReturnStatement>, state: any): void;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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).
+ */
+declare function emitIR(extracted: ExtractedWorkflow): IRWorkflowDefinition;
+/** @deprecated Use emitIR() instead. Kept for backward compatibility. */
+declare const emitPureForm: typeof emitIR;
+/**
+ * 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.
+ */
+declare function emitCanonical(extracted: ExtractedWorkflow, sourceFilename?: string): PureFormWorkflow;
+/**
+ * Emits the combined compiled output: canonical tree + lowered IR.
+ */
+declare function emitCompiledOutput(extracted: ExtractedWorkflow, sourceFilename?: string): {
+    canonical: PureFormWorkflow;
+    ir: IRWorkflowDefinition;
+};
+/**
+ * Converts compiler state to ExtractedWorkflow.
+ *
+ * Critical: must transfer ALL extracted data — nothing may be lost.
+ */
+declare function compilerStateToWorkflow(state: CompilerState, metadata: {
+    slug?: string;
+    name?: string;
+    version?: string;
+    description?: string;
+    category?: string;
+    [key: string]: unknown;
+}): ExtractedWorkflow;
+
+/**
+ * Experience Transform — converts IRExperienceNode to frontend ExperienceNode format.
+ *
+ * The React compiler emits player-core IR types (IRExperienceNode, IRDataSource).
+ * The frontend runtime expects the richer types from experience-tree-types.ts.
+ * This transform bridges the gap by:
+ *
+ *   1. Hoisting legacy config fields (slot, className, displayName) to top-level
+ *   2. Mapping IRDataSource → frontend DataSource shape (adding default fields)
+ *   3. Recursively transforming the entire node tree
+ *
+ * This is a pure function with no side effects — safe for tests and caching.
+ */
+
+/**
+ * Extended IR node type — the compiler emits additional fields beyond the
+ * base player-core IRExperienceNode. These are consumed by the frontend CTR.
+ * We use our own interface to avoid fighting the base type's narrowness.
+ */
+interface IRExperienceNode {
+    id: string;
+    component?: string;
+    config?: Record<string, unknown>;
+    bindings?: Record<string, string>;
+    children?: IRExperienceNode[];
+    dataSources?: IRDataSource[];
+    dataScope?: string;
+    layout?: string;
+    visible_when?: string;
+    displayName?: string;
+    experienceId?: string;
+    slot?: string;
+    className?: string;
+    style?: Record<string, unknown>;
+    overrides?: Record<string, unknown>;
+}
+/**
+ * Frontend-compatible ExperienceNode shape.
+ * Matches packages/frontend/src/experiences/experience-tree-types.ts.
+ * Declared locally to avoid a cross-package import dependency.
+ */
+interface FrontendExperienceNode {
+    id: string;
+    displayName?: string;
+    experienceId?: string;
+    component?: string;
+    slot?: string;
+    dataSources?: FrontendDataSource[];
+    dataScope?: string;
+    children?: FrontendExperienceNode[];
+    config?: Record<string, unknown>;
+    layout?: string;
+    className?: string;
+    style?: Record<string, unknown>;
+    overrides?: Record<string, unknown>;
+    bindings?: Record<string, string>;
+    visible_when?: string;
+}
+/**
+ * Frontend-compatible DataSource — superset of IR DataSource with default fields.
+ */
+interface FrontendDataSource {
+    type: 'workflow' | 'api' | 'ref' | 'static';
+    name: string;
+    [key: string]: unknown;
+}
+/**
+ * Transforms an IRExperienceNode tree into frontend-compatible ExperienceNode format.
+ *
+ * Handles:
+ * - Hoisting config.slot → top-level slot (backward compat for old IR)
+ * - Hoisting config.className → top-level className
+ * - Hoisting config.displayName → top-level displayName
+ * - Mapping IRDataSource[] → FrontendDataSource[] with defaults
+ * - Recursive child transformation
+ */
+declare function transformToFrontend(node: IRExperienceNode): FrontendExperienceNode;
+
+/**
+ * project.ts — Multi-file project decompiler.
+ *
+ * Takes a full IRWorkflowDefinition and produces a project file tree:
+ *   - main.workflow.tsx   (root layout + routing + state machine hooks)
+ *   - pages/*.tsx         (separate page components per route/view)
+ *   - models/*.ts         (TypeScript interfaces from field definitions)
+ *   - actions/*.server.ts (server action stubs from transition actions)
+ *   - mm.config.ts        (blueprint configuration: defineBlueprint)
+ *
+ * This is the multi-file counterpart to the single-file decompile() function.
+ * It splits complex definitions into cohesive, focused files matching the
+ * envelope fs-tree file role conventions (view-entry, page, model, server-action, config).
+ */
+
+/** A single file in the decompiled project. */
+interface ProjectFile {
+    /** Relative path from project root (e.g. "main.workflow.tsx"). */
+    path: string;
+    /** File role matching the envelope fs-tree convention. */
+    role: FileRole;
+    /** Generated source code. */
+    content: string;
+}
+/** Result of decompiling a definition into a multi-file project. */
+interface DecompileProjectResult {
+    /** All generated files. */
+    files: ProjectFile[];
+    /** The main entry file path. */
+    entryFile: string;
+    /** The slug used for naming. */
+    slug: string;
+}
+/** Options for project decompilation. */
+interface DecompileProjectOptions extends DecompileOptions {
+    /** Skip generating mm.config.ts. Default: false. */
+    skipConfig?: boolean;
+    /** Skip generating model files. Default: false. */
+    skipModels?: boolean;
+    /** Skip generating server action stubs. Default: false. */
+    skipActions?: boolean;
+    /** Skip splitting pages into separate files. Default: false. */
+    skipPages?: boolean;
+    /** Skip decompiling child definitions into separate files. Default: false. */
+    skipChildren?: boolean;
+}
+/**
+ * Decompiles an IR definition into a multi-file project structure.
+ *
+ * Produces files matching the envelope fs-tree file role conventions:
+ *   - main.workflow.tsx   → view-entry (root layout + state machine)
+ *   - pages/*.tsx         → page (per-route components)
+ *   - models/<slug>.ts    → model (TypeScript interfaces)
+ *   - actions/<slug>.server.ts → server-action (backend handlers)
+ *   - mm.config.ts        → config (defineBlueprint)
+ *
+ * For simple definitions (no states/transitions/models), falls back
+ * to single-file output in main.workflow.tsx.
+ */
+declare function decompileProject(definition: DecompilerInput, options?: DecompileProjectOptions): DecompileProjectResult;
+/**
+ * Returns true if a definition is complex enough to warrant multi-file output.
+ *
+ * Criteria: has states + transitions + either fields or experience tree.
+ */
+declare function shouldDecompileAsProject(def: IRWorkflowDefinition): boolean;
+
+/**
+ * IR-to-TSX Decompiler — converts IRWorkflowDefinition back to .workflow.tsx source.
+ *
+ * This is the inverse of the Babel compiler (extractors + pure-form-emitter).
+ * Given an IR tree (from the database, visual editor, or AI agent), it produces
+ * valid .workflow.tsx source code that compiles back to an equivalent IR.
+ *
+ * Architecture (per Appendix H):
+ *   IRWorkflowDefinition
+ *     → Import collection
+ *     → Field declarations (useState)
+ *     → State effects (useOnEnter/useOnExit)
+ *     → Transition declarations (useTransition)
+ *     → JSX return tree (experience → atoms)
+ *     → Babel AST (t.program)
+ *     → @babel/generator
+ *     → .workflow.tsx source string
+ *
+ * Covers: fields, states (enter/exit/during), transitions (with conditions),
+ * experience tree (JSX + sx props + bindings), and all known action types.
+ */
+
+/**
+ * Decompiler input — an IR definition plus an optional experience tree.
+ *
+ * The experience tree may come from:
+ *   - ExtractedWorkflow.experience (compiler internal)
+ *   - Stored definition metadata
+ *   - Visual editor BlueprintEditorContext.tree
+ */
+interface DecompilerInput extends IRWorkflowDefinition {
+    /** The experience tree to decompile into the JSX return. */
+    experience?: IRExperienceNode$1;
+    /** Child workflow definitions for multi-workflow blueprints (UBER-SCALE projects). */
+    childDefinitions?: IRWorkflowDefinition[];
+}
+interface DecompileOptions {
+    /** Override the component function name. Defaults to displayName or pascalCase(slug). */
+    componentName?: string;
+    /** Include JSDoc workflow annotation. Default: true. */
+    includeAnnotation?: boolean;
+    /** Emit displayName comments for named nodes. Default: false. */
+    emitDisplayNames?: boolean;
+}
+interface DecompileResult {
+    /** The generated .workflow.tsx source code. */
+    code: string;
+    /** List of package specifiers that were imported. */
+    imports: string[];
+    /** The component function name used. */
+    componentName: string;
+}
+/**
+ * Decompiles an IR definition into a .workflow.tsx source string.
+ *
+ * @param definition - The IR workflow definition to decompile.
+ * @param options - Optional configuration for the output.
+ * @returns The generated source code, imports list, and component name.
+ */
+declare function decompile(definition: DecompilerInput, options?: DecompileOptions): DecompileResult;
+
+/**
+ * IR-to-TSX Emitter — bridge module that re-exports the decompiler API
+ * from the canonical location expected by the investigation doc (Appendix H).
+ *
+ * The full decompiler implementation lives in packages/react-compiler/src/decompiler/
+ * (index.ts, ast-builder.ts, state-emitter.ts, sx-emitter.ts, project.ts).
+ *
+ * This module provides:
+ *   - decompileToTSX() — the primary entry point per Appendix H §H.3
+ *   - All supporting types and sub-emitters
+ *
+ * Usage:
+ *   import { decompileToTSX } from './ir-to-tsx-emitter';
+ *   const result = decompileToTSX(irDefinition, { includeAnnotation: true });
+ *   console.log(result.code); // valid .workflow.tsx source
+ */
+
+/**
+ * Decompiles an IRWorkflowDefinition to valid .workflow.tsx source code.
+ *
+ * This is the primary entry point specified in Appendix H §H.3.
+ * Uses @babel/types to construct a Babel AST, then @babel/generator to emit code.
+ *
+ * Emits:
+ *   - useState for fields
+ *   - useOnEnter/Exit for state effects
+ *   - useTransition declarations
+ *   - useWhileIn for during-actions
+ *   - useOnEvent subscriptions
+ *   - useOnChange watchers
+ *   - useOnTransition effects
+ *   - useRole declarations
+ *   - useQuery/useMutation data sources
+ *   - JSX return tree from experience nodes
+ *   - @workflow JSDoc header
+ *   - Proper imports from @mindmatrix/react
+ *
+ * @param definition - The IR workflow definition (with optional experience tree).
+ * @param options - Decompile options (componentName, includeAnnotation, etc.).
+ * @returns { code, imports, componentName }
+ */
+declare function decompileToTSX(definition: IRWorkflowDefinition & {
+    experience?: IRExperienceNode$1;
+}, options?: DecompileOptions): DecompileResult;
+/**
+ * Convenience: checks if a definition needs the experience tree attached.
+ *
+ * The decompiler expects the experience tree either:
+ *   1. As definition.experience (direct on the input)
+ *   2. From (definition as any).views?.default (stored IR format)
+ *   3. From definition.metadata?.experience (legacy format)
+ *
+ * This helper normalizes the input.
+ */
+declare function normalizeDecompilerInput(definition: IRWorkflowDefinition): DecompilerInput;
+
+/**
+ * Computed Extractor — extracts useComputed() calls into IRFieldDefinition entries.
+ *
+ * INPUT:
+ *   const total = useComputed('line_total', () => quantity * unitPrice, {
+ *     mode: 'transaction-maintained',
+ *     deps: ['quantity', 'unit_price'],
+ *   });
+ *
+ * OUTPUT (added to compilerState.fields[]):
+ *   {
+ *     name: 'line_total',
+ *     type: 'number',            // inferred from return type or default
+ *     computed: 'quantity * unitPrice',
+ *     computed_deps: ['quantity', 'unit_price'],
+ *     computed_mode: 'transaction-maintained',
+ *   }
+ *
+ * Supports all three modes:
+ *   - 'read-time' (RT): computed on every read, no storage
+ *   - 'transaction-maintained' (TM): recomputed synchronously on dependency change
+ *   - 'async-materialized' (AM): recomputed asynchronously via background job
+ */
+
+interface ComputedFieldExtraction {
+    /** The canonical field name (snake_case). */
+    name: string;
+    /** The variable name in the component (camelCase). */
+    varName: string;
+    /** The raw expression body as a string. */
+    expression: string;
+    /** Declared dependencies (from options.deps). */
+    deps: string[];
+    /** Execution mode. Default: 'read-time'. */
+    mode: 'read-time' | 'transaction-maintained' | 'async-materialized';
+    /** Inferred field type. */
+    type: string;
+    /** Staleness config for async-materialized fields. */
+    staleness?: string;
+    /** Whether RLS staleness is explicitly acceptable. */
+    rlsStalenessOk?: boolean;
+}
+/**
+ * Extracts useComputed() calls from the AST and adds computed field
+ * definitions to the compiler state.
+ *
+ * Called from the visitor for each CallExpression node.
+ */
+declare function extractComputed(path: NodePath<t.CallExpression>, state: any): void;
+
+/**
+ * Babel Visitor — main AST traversal logic for extracting workflow definitions.
+ *
+ * Handles all @mindmatrix/react hooks:
+ * - useState → fields
+ * - useOnEnter / useOnExit → state enter/exit actions
+ * - useTransition → transitions
+ * - useOnEvent → event subscriptions
+ * - useWhileIn → during actions (interval while in state)
+ * - useOnChange → field watchers
+ * - useOnTransition → transition effects
+ *
+ * Supports strict/infer mode enforcement.
+ */
+
+/**
+ * Creates the Babel visitor for the plugin.
+ */
+declare function createVisitor(options?: CompilerOptions): Visitor;
+
+/**
+ * RoundTripValidator — validates that decompile → recompile produces equivalent IR.
+ *
+ * Given an IR definition:
+ *   1. Decompiles it to .workflow.tsx source code
+ *   2. Recompiles that source via the Babel compiler
+ *   3. Structurally compares the original and round-tripped IR
+ *
+ * This validates that the decompiler produces code the compiler can understand,
+ * and that no information is silently dropped during the round trip.
+ */
+
+interface RoundTripResult {
+    /** Whether the round trip preserves all structural data. */
+    success: boolean;
+    /** The generated TSX source code (intermediate). */
+    generatedSource: string;
+    /** The original IR. */
+    originalIR: IRWorkflowDefinition;
+    /** The round-tripped IR (compiled from generated source). */
+    roundTrippedIR: IRWorkflowDefinition | null;
+    /** List of structural differences found. */
+    diffs: RoundTripDiff[];
+}
+interface RoundTripDiff {
+    path: string;
+    expected: unknown;
+    actual: unknown;
+    severity: 'error' | 'warning';
+}
+/**
+ * Validates the decompile → compile round trip for a given IR definition.
+ */
+declare function validateRoundTrip(definition: DecompilerInput): RoundTripResult;
+/**
+ * Compiles a .workflow.tsx source file and returns the IR.
+ * Useful for testing the forward direction independently.
+ */
+declare function compileSource(source: string, filename?: string): IRWorkflowDefinition | null;
+/**
+ * Full round-trip from source: compile → decompile → recompile → diff.
+ */
+declare function validateSourceRoundTrip(source: string, filename?: string): RoundTripResult | null;
+
+/**
+ * CLI Deploy Command — uploads compiled workflow definitions to the backend.
+ *
+ * Deployment rules:
+ * 1. If definition is new → create it
+ * 2. If definition exists and has no instances → update in place
+ * 3. If definition exists and has instances → create NEW version (immutability)
+ *
+ * The deploy command checks existing definitions via the API and
+ * applies the correct strategy automatically.
+ */
+interface DeployOptions {
+    apiUrl: string;
+    token: string;
+    dir?: string;
+    /** Force update even if instances exist (bypasses immutability). */
+    force?: boolean;
+    /** Dry run — show what would happen without making changes. */
+    dryRun?: boolean;
+    /** Write deploy report to this file. */
+    reportFile?: string;
+}
+interface DeployResult {
+    created: string[];
+    updated: string[];
+    versioned: string[];
+    skipped: string[];
+    failed: {
+        slug: string;
+        error: string;
+    }[];
+}
+declare function deploy(options: DeployOptions): Promise<DeployResult>;
+
+/**
+ * Model Compiler — standalone module for compiling model files into IR.
+ *
+ * Extracts TypeScript interfaces from models/*.ts files and produces
+ * category='data' IRWorkflowDefinition objects. Handles:
+ *   - Interface properties → IRFieldDefinition[]
+ *   - Exported `transitions` arrays/objects → IRTransitionDefinition[]
+ *   - Exported `fieldOptions` → field enrichment (validation, ACL, computed)
+ *   - Exported `states` → explicit state declarations
+ *   - JSDoc @workflow annotations for slug, version, category
+ *
+ * This module wraps the low-level Babel model-extractor with a clean
+ * file-level API for the ProjectCompiler to consume.
+ */
+
+interface ModelCompilationResult {
+    /** The compiled IR with category='data'. */
+    ir: IRWorkflowDefinition;
+    /** Interface name extracted from the model file. */
+    interfaceName: string;
+    /** Field names extracted from the interface. */
+    fieldNames: string[];
+    /** Transition names extracted from the model. */
+    transitionNames: string[];
+    /** State names (derived from transitions + explicit declarations). */
+    stateNames: string[];
+    /** Whether fieldOptions were present and applied. */
+    hasFieldOptions: boolean;
+    /** Raw field options map (for cross-file enrichment). */
+    fieldOptions: Record<string, Record<string, unknown>>;
+}
+interface ModelCompilerOptions {
+    /** Compilation mode. Default: 'infer'. */
+    mode?: 'strict' | 'infer';
+    /** Override the slug (otherwise derived from interface name or @workflow). */
+    slugOverride?: string;
+    /** Override the category (defaults to 'data'). */
+    categoryOverride?: string;
+}
+/**
+ * Compiles a single model file (models/*.ts) into an IRWorkflowDefinition
+ * with category='data'.
+ */
+declare function compileModel(filename: string, source: string, options?: ModelCompilerOptions): ModelCompilationResult;
+/**
+ * Compiles multiple model files and returns all results keyed by filename.
+ */
+declare function compileModels(files: Record<string, string>, options?: ModelCompilerOptions): Map<string, ModelCompilationResult>;
+
+/**
+ * Route Extractor — parses app/ directory structure into a routing table.
+ *
+ * Supports Next.js-style file-based routing conventions:
+ *   - app/page.tsx → route '/'
+ *   - app/rider/home.tsx → route '/rider/home'
+ *   - app/[id]/page.tsx → route '/:id'
+ *   - app/layout.tsx → wrapping layout boundary
+ *   - app/admin/layout.tsx → nested layout boundary
+ *
+ * Generates a router configuration that maps to IR states and transitions.
+ */
+
+interface RouteEntry {
+    /** URL path pattern (e.g., '/rider/home', '/chat/:channelId'). */
+    path: string;
+    /** IR state name (e.g., 'RIDER_HOME', 'CHAT_CHANNELID'). */
+    stateName: string;
+    /** Source file relative path. */
+    sourceFile: string;
+    /** Dynamic route parameters. */
+    params: string[];
+    /** Nearest layout boundary file. */
+    layoutBoundary?: string;
+    /** Route segment depth (0 = root). */
+    depth: number;
+}
+interface LayoutEntry {
+    /** Relative path to layout file. */
+    sourceFile: string;
+    /** Directory this layout covers. */
+    directory: string;
+    /** Depth in the layout hierarchy. */
+    depth: number;
+}
+interface RouteExtractionResult {
+    /** All extracted routes. */
+    routes: RouteEntry[];
+    /** All discovered layout boundaries. */
+    layouts: LayoutEntry[];
+    /** Generated router workflow IR. */
+    routerIR: IRWorkflowDefinition;
+    /** Route parameters discovered (for field generation). */
+    allParams: string[];
+}
+interface RouteExtractorOptions {
+    /** Blueprint slug prefix for the router. */
+    slugPrefix?: string;
+    /** Root directory name (default: 'app'). */
+    rootDir?: string;
+    /** Page file naming convention (default: 'page.tsx'). */
+    pageFileName?: string;
+    /** Layout file naming convention (default: 'layout.tsx'). */
+    layoutFileName?: string;
+}
+/**
+ * Extracts routes from a set of files in an app/ directory structure.
+ *
+ * @param files - Record of filename → source code (only app/ files needed)
+ * @param options - Extraction options
+ * @returns RouteExtractionResult with routes, layouts, and router IR
+ */
+declare function extractRoutes(files: Record<string, string>, options?: RouteExtractorOptions): RouteExtractionResult;
+
+/**
+ * Action Compiler — extracts server action signatures from *.server.ts files.
+ *
+ * Server action files define backend-side handlers that execute during
+ * workflow transitions. This compiler:
+ *   - Extracts exported function signatures (name, params, async, JSDoc)
+ *   - Registers actions on the parent blueprint metadata
+ *   - Maps each action to a Rust execution endpoint
+ *   - Resolves action references from model hooks and transitions
+ *
+ * INPUT (actions/pricing.server.ts):
+ *   export async function calculateEstimatedFare(ctx: TransitionContext): Promise<ActionResult> { ... }
+ *   export async function calculateActualFare(ctx: TransitionContext): Promise<ActionResult> { ... }
+ *
+ * OUTPUT:
+ *   ServerActionRegistration[] with endpoint mappings and parameter metadata
+ */
+interface ServerActionRegistration {
+    /** Function name (e.g., 'calculateEstimatedFare'). */
+    name: string;
+    /** Source file path. */
+    sourceFile: string;
+    /** Whether the function is async. */
+    async: boolean;
+    /** Parameter names. */
+    params: string[];
+    /** TypeScript type of the context parameter. */
+    contextType?: string;
+    /** JSDoc description. */
+    description?: string;
+    /** Full function source text (for round-trip preservation). */
+    body?: string;
+    /** TypeScript return type (e.g., 'Promise<ActionResult>'). */
+    returnType?: string;
+    /** Generated Rust execution endpoint. */
+    endpoint: string;
+    /** Action group (derived from filename without .server.ts). */
+    group: string;
+    /** Fully qualified action ID for blueprint registration. */
+    actionId: string;
+}
+interface ActionCompilationResult {
+    /** All extracted server actions. */
+    actions: ServerActionRegistration[];
+    /** Actions grouped by source file. */
+    byFile: Map<string, ServerActionRegistration[]>;
+    /** Actions grouped by action group. */
+    byGroup: Map<string, ServerActionRegistration[]>;
+    /** Compilation errors. */
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+interface ActionCompilerOptions {
+    /** Compilation mode. Default: 'infer'. */
+    mode?: 'strict' | 'infer';
+    /** Blueprint slug (used for endpoint generation). */
+    blueprintSlug?: string;
+    /** API base path for endpoint generation. Default: '/api/v1/actions'. */
+    apiBasePath?: string;
+}
+/**
+ * Compiles all server action files and extracts their function signatures.
+ *
+ * @param files - Record of filename → source (only *.server.ts files)
+ * @param options - Compilation options
+ * @returns ActionCompilationResult with all registered actions
+ */
+declare function compileActions(files: Record<string, string>, options?: ActionCompilerOptions): ActionCompilationResult;
+/**
+ * Resolves action references found in model hooks/transitions to registered actions.
+ * Returns a map of action name → ServerActionRegistration.
+ */
+declare function resolveActionReferences(actionNames: string[], registrations: ServerActionRegistration[]): Map<string, ServerActionRegistration | null>;
+
+/**
+ * Incremental Compiler — content-hash based incremental compilation.
+ *
+ * Maintains a cache of per-file compilation results (IR + errors) and
+ * only recompiles files whose content hash has changed. Merges changed
+ * IR into the cached full project IR.
+ *
+ * Performance target: <200ms for a single-file change in a 30-file project.
+ *
+ * Architecture:
+ *   1. Hash each file's content with djb2 (fast, no crypto overhead)
+ *   2. Compare against cached hashes to find dirty files
+ *   3. Recompile only dirty files
+ *   4. Merge fresh IR with cached IR for unchanged files
+ *   5. Rebuild composed result
+ *
+ * Also tracks dependency edges so that when a model file changes,
+ * workflow files that import from it are marked dirty too.
+ */
+interface FileHash {
+    /** djb2 hash of the file content. */
+    hash: string;
+    /** Timestamp of last compilation. */
+    compiledAt: number;
+    /** File size in characters. */
+    size: number;
+}
+interface IncrementalStats {
+    /** Total files in cache. */
+    totalCached: number;
+    /** Files recompiled in last compilation. */
+    lastRecompiled: number;
+    /** Files served from cache in last compilation. */
+    lastCacheHits: number;
+    /** Total compilation time in ms for last compile. */
+    lastCompileMs: number;
+    /** Average per-file compilation time in ms. */
+    avgPerFileMs: number;
+    /** Cache hit rate (0-1). */
+    cacheHitRate: number;
+}
+interface DependencyEdge {
+    /** The file that imports. */
+    from: string;
+    /** The file being imported. */
+    to: string;
+}
+interface DirtyFileSet {
+    /** Files whose content hash changed. */
+    contentChanged: string[];
+    /** Files dirty due to dependency on a changed file. */
+    dependencyDirty: string[];
+    /** Files removed since last compilation. */
+    removed: string[];
+    /** Files added since last compilation. */
+    added: string[];
+}
+/**
+ * Fast content hash using djb2 algorithm.
+ * Returns a short base-36 string suitable for cache invalidation.
+ */
+declare function hashContent(content: string): string;
+/**
+ * Extracts import paths from a source file using regex.
+ * Returns relative import targets (e.g., ['../models/user', './components/Map']).
+ */
+declare function extractImports(source: string): string[];
+/**
+ * Resolves a relative import to an absolute filename within the project.
+ */
+declare function resolveImport(fromFile: string, importPath: string, availableFiles: string[]): string | null;
+/**
+ * Builds a dependency graph from a set of files.
+ * Returns edges and a reverse dependency map (file → dependents).
+ */
+declare function buildDependencyGraph(files: Record<string, string>): {
+    edges: DependencyEdge[];
+    dependents: Map<string, Set<string>>;
+    dependencies: Map<string, Set<string>>;
+};
+/**
+ * Given a set of directly changed files, computes the full set of dirty files
+ * by following the dependency graph (transitive dependents).
+ */
+declare function computeTransitiveDirtySet(directlyChanged: Set<string>, dependents: Map<string, Set<string>>): Set<string>;
+/**
+ * Returns files in compilation order (dependencies first).
+ * Uses Kahn's algorithm for topological sorting.
+ */
+declare function topologicalSort(files: string[], dependencies: Map<string, Set<string>>): string[];
+/**
+ * Manages file hashes and determines which files need recompilation.
+ */
+declare class IncrementalCache<T> {
+    private hashes;
+    private results;
+    private lastStats;
+    /**
+     * Determines which files are dirty given current file contents.
+     */
+    detectDirtyFiles(files: Record<string, string>, dependents?: Map<string, Set<string>>): DirtyFileSet;
+    /**
+     * Updates the cache with a compilation result.
+     */
+    set(filename: string, source: string, result: T): void;
+    /**
+     * Gets a cached result.
+     */
+    get(filename: string): T | undefined;
+    /**
+     * Checks if a file is in cache and not dirty.
+     */
+    has(filename: string): boolean;
+    /**
+     * Removes a file from cache.
+     */
+    delete(filename: string): void;
+    /**
+     * Clears all cached data.
+     */
+    clear(): void;
+    /**
+     * Updates stats after a compilation run.
+     */
+    updateStats(recompiled: number, cacheHits: number, compileMs: number): void;
+    /**
+     * Gets compilation statistics.
+     */
+    getStats(): IncrementalStats;
+    /**
+     * Gets all cached filenames.
+     */
+    getCachedFiles(): string[];
+    /**
+     * Gets all cached results.
+     */
+    getAllResults(): Map<string, T>;
+}
+
+/**
+ * ProjectCompiler — multi-file project compilation for UBER-SCALE apps.
+ *
+ * Takes a Record<string, string> of filename → source code, compiles each
+ * file to IR independently, then composes a blueprint with child definitions.
+ *
+ * Handles:
+ *   - Multiple .workflow.tsx files → each becomes a child IRWorkflowDefinition
+ *   - Model files (models/*.ts) → category='data' child definitions
+ *   - Server action files (*.server.ts) → registered action metadata
+ *   - Page files (pages/ or app/ dir .tsx) → route table + router workflow child
+ *   - mm.config.ts → parent blueprint metadata
+ *   - Cross-file imports (topological sort for compilation order)
+ *   - Incremental compilation (hash-based, only recompile changed files)
+ *
+ * Phase 2 enhancements:
+ *   - Model compilation via model-compiler module
+ *   - Route extraction via route-extractor module
+ *   - Action compilation via action-compiler module
+ *   - Incremental compilation via incremental-compiler module
+ *   - Cross-file import resolution with data source linking
+ */
+
+/**
+ * A resolved module's compilation output, used for route merging.
+ * The caller (build tool) compiles each dependency and passes the result here.
+ */
+interface ResolvedModule {
+    /** The module's slug (must match the dependency slug in mm.config.ts). */
+    slug: string;
+    /** The module's compiled route table. */
+    routeTable: RouteTableEntry[];
+    /** The module's declared routes from its mm.config.ts (if any). */
+    manifestRoutes?: Array<{
+        path: string;
+        label?: string;
+        group?: string;
+        icon?: string;
+        showInNav?: boolean;
+    }>;
+}
+interface ProjectCompilerOptions {
+    /** Compilation mode: strict or infer. Default: 'infer'. */
+    mode?: 'strict' | 'infer';
+    /** Enable Phase 2 modules (model-compiler, route-extractor, action-compiler). Default: true. */
+    usePhase2Modules?: boolean;
+    /** Pre-compiled module results for route merging at compile time. */
+    resolvedModules?: ResolvedModule[];
+}
+interface ProjectCompilationResult {
+    /** The parent blueprint IRWorkflowDefinition (merged from all files). */
+    ir: IRWorkflowDefinition;
+    /** Child workflow definitions — one per .workflow.tsx + one per model + router. */
+    childDefinitions: IRWorkflowDefinition[];
+    /** Per-file IRs keyed by filename. */
+    fileIRs: Record<string, IRWorkflowDefinition>;
+    /** Route table extracted from pages*.tsx directory structure. */
+    routeTable: RouteTableEntry[];
+    /** Server actions extracted from *.server.ts files. */
+    serverActions: ServerActionEntry[];
+    /** Errors from individual file compilations. */
+    errors: ProjectCompilationError[];
+    /** Warnings from individual file compilations. */
+    warnings: ProjectCompilationError[];
+    /** Per-page experience trees extracted from app/**\/*.tsx file IRs. */
+    pageExperiences: Record<string, IRExperienceNode$1>;
+    /** Component definitions captured from components/*.tsx files. */
+    componentDefinitions: Record<string, {
+        experience: IRExperienceNode$1;
+        props: string[];
+    }>;
+    /** Phase 2: Cross-file import links (importer → imported data sources). */
+    importLinks?: ImportLink[];
+    /** Phase 2: Model compilation results (if usePhase2Modules enabled). */
+    modelResults?: Map<string, ModelCompilationResult>;
+    /** Phase 2: Action compilation result (if usePhase2Modules enabled). */
+    actionResult?: ActionCompilationResult;
+    /** Phase 2: Route extraction result (if usePhase2Modules enabled). */
+    routeResult?: RouteExtractionResult;
+}
+interface ProjectCompilationError {
+    file: string;
+    message: string;
+    line?: number;
+    column?: number;
+    /** End line for marker spans (defaults to start line). */
+    endLine?: number;
+    /** End column for marker spans (defaults to start column + token length). */
+    endColumn?: number;
+    severity: 'error' | 'warning';
+}
+interface RouteTableEntry {
+    /** Route URL path (e.g., '/rider/home'). */
+    path: string;
+    /** State name derived from the route (e.g., 'RIDER_HOME'). */
+    stateName: string;
+    /** Source file path (e.g., 'pages/rider/home.tsx'). */
+    sourceFile: string;
+    /** Dynamic parameters from [param] segments. */
+    params: string[];
+    /** Module slug if this route was merged from a dependency. */
+    moduleSlug?: string;
+}
+interface ServerActionEntry {
+    /** Function name. */
+    name: string;
+    /** Source file path. */
+    sourceFile: string;
+    /** Whether the function is async. */
+    async: boolean;
+    /** Parameter names. */
+    params: string[];
+    /** Description from JSDoc. */
+    description?: string;
+    /** Full function body source text (for round-trip preservation). */
+    body?: string;
+    /** TypeScript return type (e.g., 'Promise<ActionResult>'). */
+    returnType?: string;
+}
+/** Phase 2: Cross-file import link metadata. */
+interface ImportLink {
+    /** The file that imports. */
+    fromFile: string;
+    /** The file being imported. */
+    toFile: string;
+    /** Type of link: 'data-source' for model imports, 'component' for component imports. */
+    linkType: 'data-source' | 'component' | 'action' | 'unknown';
+    /** Imported symbol names. */
+    symbols: string[];
+}
+/**
+ * Compiles a multi-file project into a composed blueprint with child definitions.
+ *
+ * @param files - Record of filename → source code
+ * @param options - Compilation options
+ * @returns Composed result with parent IR, children, routes, actions, errors
+ */
+declare function compileProject(files: Record<string, string>, options?: ProjectCompilerOptions): ProjectCompilationResult;
+/**
+ * Stateful project compiler that caches per-file IR results and only
+ * recompiles files whose content has changed (hash-based invalidation).
+ *
+ * Phase 2 enhancements:
+ *   - Uses IncrementalCache from incremental-compiler module
+ *   - Dependency-aware invalidation (model change → workflow recompile)
+ *   - Compilation statistics tracking
+ */
+declare class IncrementalProjectCompiler {
+    private cache;
+    private lastConfig;
+    constructor();
+    /**
+     * Compile a project incrementally — only recompiles changed files.
+     */
+    compile(files: Record<string, string>, options?: ProjectCompilerOptions): ProjectCompilationResult;
+    /**
+     * Rebuild result from cache without recompiling anything.
+     */
+    private rebuildFromCache;
+    /** Invalidate a specific file's cache. */
+    invalidate(filename: string): void;
+    /** Invalidate all caches. */
+    invalidateAll(): void;
+    /** Check if a file would need recompilation given its current source. */
+    isDirty(filename: string, source: string): boolean;
+    /** Get list of files currently in cache. */
+    getCachedFiles(): string[];
+    /** Get compilation statistics. */
+    getStats(): {
+        cachedFiles: number;
+        totalHashes: number;
+    } & IncrementalStats;
+}
+
+export { type ActionCompilationResult, type ActionCompilerOptions, CompilerOptions, CompilerState, type ComputedFieldExtraction, type DecompileOptions, type DecompileProjectOptions, type DecompileProjectResult, type DecompileResult, type DecompilerInput, type DependencyEdge, type DeployOptions, type DeployResult, type DirtyFileSet, ExtractedWorkflow, type FileHash, FileRole, type FrontendDataSource, type FrontendExperienceNode, type ImportLink, IncrementalCache, IncrementalProjectCompiler, type IncrementalStats, type LayoutEntry, type ModelCompilationResult, type ModelCompilerOptions, type ProjectCompilationError, type ProjectCompilationResult, type ProjectCompilerOptions, type ProjectFile, type RoundTripDiff, type RoundTripResult, type RouteEntry, type RouteExtractionResult, type RouteExtractorOptions, type RouteTableEntry, type ServerActionEntry, type ServerActionRegistration, buildDependencyGraph, compileActions, compileModel, compileModels, compileProject, compileSource, compilerStateToWorkflow, computeTransitiveDirtySet, createVisitor, decompile, decompileProject, decompileToTSX, deploy, emitCanonical, emitCompiledOutput, emitIR, emitPureForm, extractComponents, extractComputed, extractEffects, extractEvents, extractImports, extractRoutes, extractStates, extractTransitions, hashContent, normalizeDecompilerInput, resolveActionReferences, resolveImport, shouldDecompileAsProject, topologicalSort, transformToFrontend, validateRoundTrip, validateSourceRoundTrip };