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

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.