@mmapp/react-compiler 0.1.0-alpha.1 → 0.1.0-alpha.3

package/ATOM-PIPELINE.md

@@ -0,0 +1,144 @@
+# Atom Pipeline — How Components Flow From Authoring to Runtime
+
+## The Two Atom Packages Are NOT Duplicates
+
+There are two places where atom components live. They serve different purposes and are **not** supposed to be identical.
+
+### `packages/react/src/components/atoms/` — Authoring Atoms (14 components)
+
+These are **specifications**, not implementations. They exist so that `.workflow.tsx` authors get TypeScript completion when writing views:
+
+```tsx
+import { Stack, Text, Button, TextInput } from '@mindmatrix/react';
+
+export default function MyPage() {
+  return (
+    <Stack gap={16}>
+      <Text variant="h3" value="Hello" />
+      <TextInput placeholder="Type here..." onChange={setName} />
+      <Button variant="primary" onPress={submit}>Save</Button>
+    </Stack>
+  );
+}
+```
+
+The Babel compiler (`react-compiler`) extracts this JSX into IR nodes. These components **never render in production**. They only need enough implementation to satisfy TypeScript and render a basic preview in tests.
+
+**Full list:** Stack, Row, Column, Text, Heading, Button, TextInput, Each, Show, Slot, Badge, Card, Divider
+
+### `packages/frontend/src/experiences/atoms/` — Runtime Atoms (50+ components)
+
+These are **real React components** that render in the browser. They implement the full visual and interactive behavior: Radix UI primitives, Tailwind styling, event handling, accessibility, config prop resolution, Style IR support.
+
+The `ComponentTreeRenderer` maps IR node `component` strings to these atoms via the component registry (`component-registry.ts`). When the experience tree has `{ component: 'TextInput', config: { placeholder: '...' } }`, the registry resolves it to the `TextInput` atom from this directory.
+
+**These include everything the authoring atoms have, plus:** Select, Icon, Image, Modal, Tabs, Accordion, Router, Route, NavLink, RoleGuard, AnimatedBox, Canvas3D, DataGrid, Chart, MetricCard, ServerGrid, all media atoms (Video, Audio, Map), interactive atoms (Slider, Toggle, Rating, Counter), data display (Tag, Timeline, Pricing), layout (Breadcrumb, Stepper, Drawer), and 17 sub-experience components.
+
+## Why They Differ
+
+The authoring atoms are intentionally minimal because:
+
+1. **Different players implement different subsets.** A web player has 90+ renderers. An iOS player might implement 30. A console/CLI player might implement 10. The authoring atoms define the universal vocabulary — what authors can write. Each player decides what it can render, falling back gracefully for unknown components.
+
+2. **The IR is the contract, not the React components.** The compiled IR node `{ component: 'TextInput', config: { placeholder, maxLength, multiline } }` is the spec. Any player that can render a `TextInput` with those config keys is compliant. The React authoring atoms are just one convenient way to produce that IR.
+
+3. **Player-specific atoms shouldn't pollute the authoring SDK.** The web player has `Canvas3D`, `DataGrid`, `GlassConsoleRunner`. These are web-specific. They don't belong in the authoring package that iOS developers also import.
+
+## The Full Pipeline
+
+```
+Author writes .workflow.tsx
+    │
+    ▼
+@mindmatrix/react atoms (Stack, Text, Button, ...)
+    │  TypeScript types + basic rendering for preview
+    │
+    ▼
+react-compiler Babel plugin
+    │  component-extractor.ts extracts JSX → IRExperienceNode
+    │  Each JSX element becomes { component, config, bindings, children }
+    │
+    ▼
+IRExperienceNode tree (stored in database)
+    │  component: "TextInput"
+    │  config: { placeholder: "Search...", maxLength: 100 }
+    │  bindings: { value: "$local.query", onChange: "$action.setLocal('query', $value)" }
+    │
+    ▼
+ComponentTreeRenderer (packages/frontend/src/experiences/)
+    │  Walks the IR tree, resolves each node.component via component-registry
+    │  Applies binding-resolver for dynamic values
+    │  Passes config as props, style from Style IR
+    │
+    ▼
+Frontend atoms render in the browser
+    TextInput, SelectAtom, ButtonAtom, etc.
+    Full Radix UI + Tailwind + accessibility
+```
+
+## The Decompiler (Reverse Direction)
+
+The decompiler converts IR back to `.workflow.tsx` source:
+
+```
+IRExperienceNode tree
+    │
+    ▼
+ast-builder.ts builds Babel JSX AST
+    │  Uses REACT_ATOMS set (32 components) to decide imports
+    │  Maps IR tokens ($local.x, $action.y) back to variable names
+    │
+    ▼
+@babel/generator produces source code
+    │
+    ▼
+.workflow.tsx with imports from @mindmatrix/react
+```
+
+The `REACT_ATOMS` set in `ast-builder.ts` determines which components get `import { X } from '@mindmatrix/react'` in the decompiled output. Components not in this set are emitted as bare identifiers (assumed to be local imports or custom components).
+
+## Style IR and the `style` Prop
+
+The compiled experience tree may attach Style IR to nodes as inline `style` objects. These flow through to the atom's wrapper div. This means **atoms receive border, borderRadius, background, etc. from the compiled view** — not just from their own CSS.
+
+If an atom should always be borderless (like TextInput and Select inside Cards), it must explicitly override the style prop:
+
+```tsx
+<div style={{ ...style, border: 'none', borderRadius: 0, background: 'transparent' }}>
+```
+
+This is by design — Style IR gives authors control over visual appearance, but atoms can override properties that conflict with their intended rendering.
+
+## Coverage Validation
+
+`atom-rendering-coverage.test.ts` validates the full pipeline:
+
+1. Compiles all blueprint packages and examples to IR
+2. Collects every unique `component` string from IR trees
+3. Checks each against `KNOWN_RENDERERS` (90+ registered) and `STRUCTURAL_COMPONENTS` (HTML elements)
+4. Fails if any IR component has no renderer
+
+This catches: new authoring atoms missing a frontend renderer, typos in component names, and regression when atoms are renamed.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `packages/react/src/components/atoms/index.tsx` | Authoring atoms (14) — the author's vocabulary |
+| `packages/frontend/src/experiences/atoms/` | Runtime atoms (50+) — what actually renders |
+| `packages/frontend/src/experiences/ComponentTreeRenderer.tsx` | Walks IR tree, resolves components, applies bindings |
+| `packages/frontend/src/experiences/component-registry.ts` | Maps component name strings → lazy-loaded React components |
+| `packages/frontend/src/experiences/binding-resolver.ts` | Resolves $local, $instance, $action, $fn expressions |
+| `packages/react-compiler/src/babel/extractors/component-extractor.ts` | Extracts JSX → IR nodes during compilation |
+| `packages/react-compiler/src/decompiler/ast-builder.ts` | Builds JSX AST from IR nodes (REACT_ATOMS set) |
+| `packages/react-compiler/src/__tests__/atom-rendering-coverage.test.ts` | Validates no gaps in the pipeline |
+
+## Rules of Thumb
+
+- **Adding a new authoring atom?** Add it to `packages/react/src/components/atoms/`, export from the package, and add a matching renderer in `packages/frontend/src/experiences/atoms/`. Register it in `component-registry.ts`. The coverage test will catch if you forget the renderer.
+
+- **Adding a web-only atom?** Add it only to `packages/frontend/src/experiences/atoms/` and register in `component-registry.ts`. Don't add it to the authoring package — it's platform-specific.
+
+- **Adding a new player (iOS, CLI, etc.)?** Implement renderers for whichever atoms make sense for that platform. The IR is the contract. Unknown components should render a fallback, not crash.
+
+- **Atom props drifting?** The coverage test catches missing atoms but not missing props. If you add a new config key to an authoring atom, make sure the corresponding frontend atom handles it. TypeScript won't catch this — it crosses package boundaries through IR serialization.

package/README.md

@@ -1,21 +1,47 @@
-# @mindmatrix/react-compiler
+# @mmapp/react-compiler
 
-Babel plugin + Vite integration that transforms React workflow files into Pure Form (IR) JSON output.
+Babel plugin, Vite integration, and CLI for compiling React workflow files into Pure Form IR (Intermediate Representation).
+
+Published on npm as `@mmapp/react-compiler` (internal workspace name: `@mindmatrix/react-compiler`).
 
 ## Installation
 
 ```bash
-pnpm add -D @mindmatrix/react-compiler
+npm install -g @mmapp/react-compiler   # for mmrc CLI
+npm install -D @mmapp/react-compiler   # for Vite/Babel plugin
 ```
 
-## Usage
+## CLI — `mmrc`
+
+```bash
+# Scaffold a new blueprint
+mmrc init my-app
+
+# Build workflows to IR
+mmrc build --src src/workflows --out dist/workflows
+
+# Deploy to MindMatrix server
+mmrc deploy --api-url https://dev.mindmatrix.club --token YOUR_TOKEN
+
+# Start dev server with hot reload
+mmrc dev
+
+# Run workflow tests
+mmrc test
+
+# Pull remote definitions to local files
+mmrc pull --slug my-workflow
 
-### Vite Plugin
+# Auth
+mmrc login / mmrc logout / mmrc whoami
+```
+
+## Vite Plugin
 
 ```typescript
 // vite.config.ts
 import { defineConfig } from 'vite';
-import { mindmatrixReact } from '@mindmatrix/react-compiler/vite';
+import { mindmatrixReact } from '@mmapp/react-compiler/vite';
 
 export default defineConfig({
   plugins: [
@@ -27,41 +53,36 @@ export default defineConfig({
 });
 ```
 
-### Babel Plugin
+## Babel Plugin
 
 ```javascript
 // babel.config.js
 module.exports = {
   plugins: [
-    ['@mindmatrix/react-compiler/babel', { mode: 'infer' }]
+    ['@mmapp/react-compiler/babel', { mode: 'infer' }]
   ]
 };
 ```
 
-### CLI
-
-```bash
-# Build workflows
-pnpm mmrc build --src src/workflows --out dist/workflows
-
-# Deploy workflows
-pnpm mmrc deploy --api-url http://localhost:3010 --token YOUR_TOKEN
-```
-
-## Features
-
-- Extract `useState` calls → IR field definitions
-- Extract `useOnEnter`, `useOnExit` → IR action definitions
-- Extract `useTransition` → IR transition definitions
-- Extract `useOnEvent` → IR event subscriptions
-- Extract JSX components → IR experience nodes
-- Emit Pure Form JSON matching `IRWorkflowDefinition` schema
+## What It Compiles
+
+| Source Pattern | IR Output |
+|---------------|-----------|
+| `useState(initial)` | Field definition |
+| `useOnEnter(state, fn)` | State on_enter actions |
+| `useOnExit(state, fn)` | State on_exit actions |
+| `useTransition(name)` | Transition definition |
+| `useOnEvent(pattern, fn)` | Event subscription |
+| JSX components | Experience tree nodes |
+| `defineModel({...})` | Model IR (fields, states, transitions) |
+| `defineBlueprint({...})` | Blueprint manifest |
+| `useServerAction(name)` | Server action binding |
+| Router/Route composition | Route definitions |
 
 ## Example
 
 ```tsx
-// src/workflows/approval.workflow.tsx
-import { useState, useOnEnter, useTransition } from '@mindmatrix/react';
+import { useState, useOnEnter, useTransition } from '@mmapp/react';
 
 export function ApprovalWorkflow() {
   const [status, setStatus] = useState('pending');
@@ -83,25 +104,52 @@ Compiles to:
 {
   "slug": "approval",
   "name": "ApprovalWorkflow",
-  "version": "0.1.0",
-  "category": "workflow",
   "fields": [
     { "name": "status", "type": "text", "default_value": "pending" },
     { "name": "approver", "type": "text", "default_value": "" }
   ],
   "states": [
-    {
-      "name": "approved",
-      "type": "REGULAR",
-      "on_enter": [
-        { "id": "auto_1", "type": "set_field", "mode": "auto", "config": { "field": "status", "value": "done" } }
-      ],
-      "during": [],
-      "on_exit": []
-    }
+    { "name": "approved", "type": "REGULAR",
+      "on_enter": [{ "type": "set_field", "config": { "field": "status", "value": "done" } }] }
   ],
   "transitions": [
-    { "name": "approve", "from": [], "to": "approved", "actions": [], "conditions": [] }
+    { "name": "approve", "from": [], "to": "approved" }
   ]
 }
 ```
+
+## npm Publishing
+
+This package is published to npm under the `@mmapp` scope.
+
+| npm name | workspace name | current version |
+|----------|---------------|-----------------|
+| `@mmapp/react-compiler` | `@mindmatrix/react-compiler` | 0.1.0-alpha.1 |
+
+### Publishing a new version
+
+Use the publish script from the monorepo root:
+
+```bash
+# Publish all 3 packages (player-core, react, react-compiler)
+./scripts/publish-npm.sh patch   # 0.1.0-alpha.1 → 0.1.0-alpha.2
+./scripts/publish-npm.sh minor   # 0.1.0-alpha.1 → 0.2.0-alpha.1
+./scripts/publish-npm.sh 0.2.0-beta.1  # explicit version
+```
+
+Or publish just this package:
+
+```bash
+cd packages/react-compiler
+pnpm run publish:alpha          # auto-increments alpha version
+```
+
+### Version strategy
+
+- `0.1.0-alpha.X` — internal development (current)
+- `0.1.0-beta.X` — user testing
+- `1.0.0` — production launch
+
+### Important: workspace dependency handling
+
+When publishing to npm, `workspace:*` dependencies are automatically rewritten to `@mmapp/*` equivalents by the publish script. The internal `@mindmatrix/player-core` becomes `@mmapp/player-core` in the published tarball.

package/dist/babel/index.js

@@ -649,6 +649,8 @@ var TranspileContext = class {
     this.localFieldMap = options.localFieldMap ?? /* @__PURE__ */ new Map();
     this.derivedVarMap = options.derivedVarMap ?? /* @__PURE__ */ new Map();
     this.setterToFieldMap = options.setterToFieldMap ?? /* @__PURE__ */ new Map();
+    this.parameterMap = options.parameterMap ?? /* @__PURE__ */ new Map();
+    this.allMutable = options.allMutable ?? false;
   }
   /**
    * Emit an opaque JS fallback, marking the result as impure.
@@ -670,6 +672,8 @@ var TranspileContext = class {
       if (snakeName) return `$local.${snakeName}`;
       const derivedInit = this.derivedVarMap.get(node.name);
       if (derivedInit) return `(${this.visit(derivedInit)})`;
+      const paramField = this.parameterMap.get(node.name);
+      if (paramField) return paramField;
       if (node.name === "undefined") return "null";
       if (node.name === "NaN") return "null";
       if (node.name === "Infinity") return "null";
@@ -717,6 +721,9 @@ var TranspileContext = class {
     if (t5.isNewExpression(node)) {
       return this.visitNew(node);
     }
+    if (t5.isAssignmentExpression(node) && node.operator === "=" && t5.isIdentifier(node.left)) {
+      return `${node.left.name} = ${this.visit(node.right)}`;
+    }
     return this.opaque(fallbackGenerate(node));
   }
   // ---------------------------------------------------------------------------
@@ -917,6 +924,11 @@ var TranspileContext = class {
         return this.visitArrayHigherOrder("some", obj, args);
       case "every":
         return this.visitArrayHigherOrder("every", obj, args);
+      // --- Array push: arr.push(item) → arr = push(arr, item) ---
+      case "push": {
+        const [item] = this.visitArgsList(args);
+        return `${obj} = push(${obj}, ${item})`;
+      }
       // --- Array mutation-free methods ---
       case "reverse":
         return `reverse(${obj})`;
@@ -2752,6 +2764,71 @@ function modelStateTypeToIR(type) {
   if (type === "final") return "END";
   return "REGULAR";
 }
+function parseActionArray(raw, actionCounter) {
+  if (!Array.isArray(raw)) return [];
+  const actions = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue;
+    const a = item;
+    actions.push({
+      id: a.id ? String(a.id) : `auto_${++actionCounter.value}`,
+      type: String(a.type || a.action_type || "unknown"),
+      mode: a.mode || "auto",
+      config: a.config && typeof a.config === "object" ? a.config : {},
+      ...a.condition ? { condition: String(a.condition) } : {}
+    });
+  }
+  return actions;
+}
+function parseDuringArray(raw, actionCounter) {
+  if (!Array.isArray(raw)) return [];
+  const result = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue;
+    const d = item;
+    result.push({
+      id: d.id ? String(d.id) : `during_${++actionCounter.value}`,
+      type: d.type || "interval",
+      ...d.interval_ms != null ? { interval_ms: Number(d.interval_ms) } : {},
+      ...d.cron ? { cron: String(d.cron) } : {},
+      ...d.delay_ms != null ? { delay_ms: Number(d.delay_ms) } : {},
+      ...d.condition ? { condition: String(d.condition) } : {},
+      actions: parseActionArray(d.actions, actionCounter)
+    });
+  }
+  return result;
+}
+function parseOnEventArray(raw, actionCounter) {
+  if (!Array.isArray(raw)) return [];
+  const result = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue;
+    const e = item;
+    const actions = [];
+    if (Array.isArray(e.actions)) {
+      for (const a of e.actions) {
+        if (typeof a !== "object" || a === null) continue;
+        const act = a;
+        actions.push({
+          type: act.type || "set_field",
+          ...act.field ? { field: String(act.field) } : {},
+          ...act.expression ? { expression: String(act.expression) } : {},
+          ...act.key ? { key: String(act.key) } : {},
+          ...act.message ? { message: String(act.message) } : {},
+          ...act.config && typeof act.config === "object" ? { config: act.config } : {},
+          ...act.conditions && Array.isArray(act.conditions) ? { conditions: act.conditions.map(String) } : {}
+        });
+      }
+    }
+    result.push({
+      match: String(e.match || ""),
+      ...e.description ? { description: String(e.description) } : {},
+      ...e.conditions && Array.isArray(e.conditions) ? { conditions: e.conditions.map(String) } : {},
+      actions
+    });
+  }
+  return result;
+}
 function extractDefineModelCall(programPath, compilerState, actionCounter) {
   for (const node of programPath.node.body) {
     if (!t11.isExportDefaultDeclaration(node)) continue;
@@ -2791,17 +2868,27 @@ function extractDefineModelCall(programPath, compilerState, actionCounter) {
       const statesObj = config.states;
       for (const [name, stateConfig] of Object.entries(statesObj)) {
         const stateType = modelStateTypeToIR(stateConfig.type);
+        const on_enter = parseActionArray(stateConfig.on_enter, actionCounter);
+        const on_exit = parseActionArray(stateConfig.on_exit, actionCounter);
+        const during = parseDuringArray(stateConfig.during, actionCounter);
+        const on_event = parseOnEventArray(stateConfig.on_event, actionCounter);
         if (!compilerState.states.has(name)) {
           compilerState.states.set(name, {
             name,
             type: stateType,
             description: stateConfig.description,
-            on_enter: [],
-            during: [],
-            on_exit: []
+            on_enter,
+            during,
+            on_exit,
+            ...on_event.length > 0 ? { on_event } : {}
           });
         } else {
-          compilerState.states.get(name).type = stateType;
+          const existing = compilerState.states.get(name);
+          existing.type = stateType;
+          if (on_enter.length > 0) existing.on_enter = on_enter;
+          if (on_exit.length > 0) existing.on_exit = on_exit;
+          if (during.length > 0) existing.during = during;
+          if (on_event.length > 0) existing.on_event = on_event;
         }
       }
     }
@@ -2839,13 +2926,21 @@ function extractDefineModelCall(programPath, compilerState, actionCounter) {
         if (transConfig.guard) {
           conditions.push(parseGuardExpression(String(transConfig.guard)));
         }
+        if (transConfig.conditions && Array.isArray(transConfig.conditions)) {
+          for (const cond of transConfig.conditions) {
+            if (typeof cond === "object" && cond !== null) {
+              conditions.push(cond);
+            }
+          }
+        }
+        const actions = parseActionArray(transConfig.actions, actionCounter);
         compilerState.transitions.push({
           name,
           from,
           to,
           description: transConfig.description,
           conditions: conditions.length > 0 ? conditions : void 0,
-          actions: [],
+          actions,
           roles: transConfig.roles,
           auto: transConfig.auto,
           required_fields: transConfig.required_fields
@@ -3771,6 +3866,18 @@ function emitIR(extracted) {
       });
       stateNames.add(transition.to);
     }
+    for (const from of transition.from) {
+      if (from && !stateNames.has(from)) {
+        stateArray.push({
+          name: from,
+          type: "REGULAR",
+          on_enter: [],
+          during: [],
+          on_exit: []
+        });
+        stateNames.add(from);
+      }
+    }
   }
   const fieldNames = new Set(fields.map((f) => f.name));
   let normalizedView;
@@ -4723,7 +4830,7 @@ function createVisitor(options = {}) {
         }
       }
       if (mode !== "strict") return;
-      if (source.startsWith("@mindmatrix/") || source === "react" || source.startsWith("react/") || source.startsWith(".") || source.startsWith("/")) {
+      if (source.startsWith("@mindmatrix/") || source.startsWith("@mmapp/") || source === "react" || source.startsWith("react/") || source.startsWith(".") || source.startsWith("/")) {
         return;
       }
       const error = {

package/dist/babel/index.mjs

@@ -1,7 +1,7 @@
 import {
   babelPlugin
-} from "../chunk-HLRGCCIL.mjs";
-import "../chunk-Y6FXYEAI.mjs";
+} from "../chunk-FYT47UBU.mjs";
+import "../chunk-CIESM3BP.mjs";
 export {
   babelPlugin as default
 };