@rrjs/babel-plugin 0.1.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saman Abaasi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,26 @@
-# babel-plugin-reactive-react
+# @rrjs/babel-plugin
 
-Babel plugin that compiles JSX to `h()` calls compatible with `@rrjs/renderer`. Dynamic expressions inside JSX are wrapped in thunks so the renderer can establish reactive bindings.
+Babel plugin that compiles React components for `@rrjs/renderer`. By default each
+component body runs once per mount, state is read as an ordinary value, and DOM
+updates and list changes are applied directly with no keyed reconciliation.
+Source outside the supported subset is a build error rather than a silent
+difference.
+
+Two paths, selected with the `runOnce` option:
+
+| | default (`runOnce`) | `runOnce: false` |
+| --- | --- | --- |
+| Component source | ordinary React: `count` | adapted: state is a getter, `count()` |
+| Lists | direct insert/move/remove | reconciling `list()` |
+| Unsupported source | rejected at build time | compiled, sometimes incorrectly |
+
+Version 0.2.0 made `runOnce` the default. Builds that relied on the previous
+default must pass `runOnce: false` explicitly.
 
 ## Install
 
 ```bash
-npm install -D babel-plugin-reactive-react @babel/core
+npm install -D @rrjs/babel-plugin @babel/core
 ```
 
 ## Setup
@@ -16,7 +31,7 @@ npm install -D babel-plugin-reactive-react @babel/core
 // vite.config.ts
 import { defineConfig } from 'vite'
 import babel from '@babel/core'
-import reactiveReact from 'babel-plugin-reactive-react'
+import reactiveReact from '@rrjs/babel-plugin'
 
 export default defineConfig({
   esbuild: { jsx: 'preserve' },
@@ -39,14 +54,63 @@ export default defineConfig({
 })
 ```
 
-In your entry file:
+### Module contracts for imports
+
+The default compiler handles components and hooks defined in the module it is
+compiling. Imported hooks and components need an explicit build-tool contract. Define one manifest for the source root and
+resolve every transformed module by its exact path:
+
+```ts
+import reactiveReact, {
+  defineModuleContracts,
+  resolveModuleMetadata,
+} from '@rrjs/babel-plugin'
+
+const contracts = defineModuleContracts({
+  root: '/absolute/project/src',
+  modules: {
+    'App.tsx': {
+      imports: {
+        './theme': { hooks: ['useTheme'] },
+        './Rows': {
+          components: {
+            Rows: {
+              props: ['rows'],
+              operationKeys: { rows: 'id' },
+            },
+          },
+        },
+      },
+    },
+    'Rows.tsx': {
+      operationProps: ['rows'],
+      operationKeyProps: { rows: 'id' },
+    },
+  },
+})
+
+const options = {
+  moduleMetadata: resolveModuleMetadata(contracts, filename),
+}
+```
+
+Import contracts use the source string and exported name, so named aliases keep
+the same identity. Manifest module keys must be normalized, root-relative paths;
+unknown paths fail explicitly. These contracts are manually asserted facts. The
+compiler does not inspect an imported implementation or infer arbitrary module
+graphs. Operation props require a direct item-property JSX key, and accepted map
+updates must preserve that key. Opaque list replacements remain unsupported.
+
+In your application's entry file:
 
 ```js
-import { h } from '@rrjs/renderer'
-;(globalThis as any).h = h
+import { mount } from '@rrjs/renderer'
+import { App } from './App'
+
+mount(App, document.getElementById('app'))
 ```
 
-The plugin assumes `h` is in scope where JSX is used.
+The plugin injects `import { h, list } from '@rrjs/renderer'` into every file that actually emits those calls. You do not assign `globalThis.h`. `@rrjs/renderer` must be installed in the app — it is a peer dependency of the plugin.
 
 ## What it transforms
 
@@ -61,6 +125,15 @@ The plugin assumes `h` is in scope where JSX is used.
 
 Static literals are not wrapped. Event handlers (anything matching `on[A-Z]`) are passed through directly.
 
+### SVG namespace boundary
+
+Intrinsic SVG descendants in one compiled JSX tree are marked so the renderer
+creates them in the SVG namespace; children of `foreignObject` return to HTML.
+The tested aliases are `className`, `strokeWidth` and `xlinkHref`. An SVG-only
+intrinsic without a visible `svg` ancestor and a component child directly under
+SVG are rejected because cross-component namespace context is not implemented.
+Namespaced JSX and the broader SVG attribute surface are outside this contract.
+
 ## Why thunks
 
 Inside the renderer, thunks run inside an `effect`. That effect subscribes to any signals read by the thunk. When those signals change, the thunk re-runs and the bound DOM node updates — without re-running the component function. This is what makes the "component runs once" property possible.
@@ -86,4 +159,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/dist/index.d.ts

@@ -1,2 +1,23 @@
 import type { PluginObj, PluginPass } from '@babel/core';
+import type { ModuleMetadata } from './module-contracts.js';
+export { defineModuleContracts, resolveModuleMetadata, } from './module-contracts.js';
+export type { ImportedComponentContract, ImportedModuleContract, ModuleContractManifest, ModuleMetadata, } from './module-contracts.js';
+export type PluginOptions = {
+    /**
+     * Compile the checked React-source subset without component re-execution or
+     * list reconciliation. Default: true. Set false for the older path, which
+     * wraps reactive reads instead and does not run component bodies once.
+     */
+    runOnce?: boolean;
+    /** Module to import `h` and `list` from. Default: `@rrjs/renderer`. */
+    importSource?: string;
+    /**
+     * When false, assume `h`/`list` are already in scope. Used by the audit
+     * harness, which evals compiled output with `new Function('h', 'list', ...)`.
+     * Default: true.
+     */
+    injectImports?: boolean;
+    /** Explicit module-graph facts supplied by an integrating build tool. */
+    moduleMetadata?: ModuleMetadata;
+};
 export default function reactiveReactPlugin(): PluginObj<PluginPass>;

package/dist/index.js

@@ -1,22 +1,137 @@
 import * as t from '@babel/types';
 import jsxSyntaxPlugin from '@babel/plugin-syntax-jsx';
-// ─── The Plugin ──────────────────────────────────────────────────────────────
-// Transforms JSX into h() calls.
-// Dynamic expressions (signals, computeds, variables that may change)
-// are wrapped in thunks so the renderer can subscribe them to signal changes.
+import { addNamed } from '@babel/helper-module-imports';
+import { compileRunOnce } from './run-once.js';
+const SVG_ONLY_INTRINSICS = new Set([
+    'animate', 'animateMotion', 'animateTransform', 'circle', 'clipPath', 'defs',
+    'desc', 'ellipse', 'feBlend', 'feColorMatrix', 'feComponentTransfer',
+    'feComposite', 'feConvolveMatrix', 'feDiffuseLighting', 'feDisplacementMap',
+    'feDistantLight', 'feDropShadow', 'feFlood', 'feFuncA', 'feFuncB', 'feFuncG',
+    'feFuncR', 'feGaussianBlur', 'feImage', 'feMerge', 'feMergeNode',
+    'feMorphology', 'feOffset', 'fePointLight', 'feSpecularLighting', 'feSpotLight',
+    'feTile', 'feTurbulence', 'filter', 'foreignObject', 'g', 'image', 'line',
+    'linearGradient', 'marker', 'mask', 'metadata', 'mpath', 'path', 'pattern',
+    'polygon', 'polyline', 'radialGradient', 'rect', 'stop', 'switch', 'symbol',
+    'text', 'textPath', 'tspan', 'use', 'view',
+]);
+function annotateIntrinsicNamespaces(program) {
+    program.traverse({
+        JSXElement(path) {
+            const opening = path.node.openingElement;
+            if (!t.isJSXIdentifier(opening.name))
+                return;
+            const name = opening.name.name;
+            const parent = path.findParent(parent => parent.isJSXElement());
+            const inherited = parent?.node.openingElement.extra?.rrjsChildNamespace;
+            if (/^[A-Z]/.test(name)) {
+                if (inherited === 'svg') {
+                    throw path.buildCodeFrameError('SVG component children require cross-component namespace compilation');
+                }
+                return;
+            }
+            const namespace = name === 'svg' ? 'svg' : inherited ?? 'html';
+            if (namespace === 'html' && SVG_ONLY_INTRINSICS.has(name)) {
+                throw path.buildCodeFrameError(`SVG intrinsic <${name}> requires an <svg> ancestor in the same compiled module`);
+            }
+            opening.extra = {
+                ...(opening.extra ?? {}),
+                rrjsNamespace: namespace,
+                rrjsChildNamespace: namespace === 'svg' && name === 'foreignObject' ? 'html' : namespace,
+            };
+        },
+    });
+}
+function rewriteRunOnceReactDomImports(program, importSource) {
+    for (const statement of program.get('body')) {
+        if (!statement.isImportDeclaration() || statement.node.source.value !== 'react-dom')
+            continue;
+        for (const specifier of statement.get('specifiers')) {
+            if (!specifier.isImportSpecifier()) {
+                throw specifier.buildCodeFrameError('Strict portal compilation requires a named createPortal import from react-dom');
+            }
+            const imported = specifier.node.imported;
+            const name = t.isIdentifier(imported) ? imported.name : imported.value;
+            if (name !== 'createPortal') {
+                throw specifier.buildCodeFrameError(`Unsupported react-dom import ${name}; only named createPortal is supported`);
+            }
+        }
+        statement.node.source = t.stringLiteral(importSource);
+    }
+}
+export { defineModuleContracts, resolveModuleMetadata, } from './module-contracts.js';
+function makeRuntime(path, state) {
+    const opts = (state.opts ?? {});
+    const inject = opts.injectImports !== false;
+    const source = opts.importSource ?? '@rrjs/renderer';
+    if (!inject) {
+        return {
+            h: () => t.identifier('h'),
+            list: () => t.identifier('list'),
+        };
+    }
+    return {
+        h: () => {
+            let id = state.get('rrjs.h');
+            if (!id) {
+                id = addNamed(path, 'h', source);
+                state.set('rrjs.h', id);
+            }
+            return t.cloneNode(id);
+        },
+        list: () => {
+            let id = state.get('rrjs.list');
+            if (!id) {
+                id = addNamed(path, 'list', source);
+                state.set('rrjs.list', id);
+            }
+            return t.cloneNode(id);
+        },
+    };
+}
 export default function reactiveReactPlugin() {
     return {
         name: 'babel-plugin-reactive-react',
         inherits: jsxSyntaxPlugin.default ?? jsxSyntaxPlugin,
         visitor: {
-            JSXElement(path) {
-                const replacement = transformElement(path.node);
-                path.replaceWith(replacement);
+            Program(path, state) {
+                const opts = state.opts;
+                annotateIntrinsicNamespaces(path);
+                if (opts?.runOnce === false)
+                    return;
+                rewriteRunOnceReactDomImports(path, opts.importSource ?? '@rrjs/renderer');
+                let helper;
+                let selector;
+                compileRunOnce(path, () => {
+                    if (opts.injectImports === false)
+                        return t.identifier('derive');
+                    helper ??= addNamed(path, 'derive', '@rrjs/react-compat');
+                    return t.cloneNode(helper);
+                }, () => {
+                    if (opts.injectImports === false)
+                        return t.identifier('choose');
+                    selector ??= addNamed(path, 'choose', opts.importSource ?? '@rrjs/renderer');
+                    return t.cloneNode(selector);
+                }, (name) => {
+                    if (opts.injectImports === false)
+                        return t.identifier(name);
+                    const key = `rrjs.${name}`;
+                    let id = state.get(key);
+                    if (!id) {
+                        id = addNamed(path, name, opts.importSource ?? '@rrjs/renderer');
+                        state.set(key, id);
+                    }
+                    return t.cloneNode(id);
+                }, opts.moduleMetadata);
+            },
+            JSXElement(path, state) {
+                const rt = makeRuntime(path, state);
+                path.replaceWith(transformElement(path.node, rt));
             },
-            JSXFragment(path) {
+            JSXFragment(path, state) {
                 // Fragments: <>...</> → [child, child, ...]
                 // We use an array because there's no h() call for fragments yet
-                const children = filterChildren(path.node.children).map(transformChild);
+                const rt = makeRuntime(path, state);
+                const children = filterChildren(path.node.children).map(c => transformChild(c, rt));
                 path.replaceWith(t.arrayExpression(children));
             },
         },
@@ -53,13 +168,20 @@ function getAttributeName(name) {
         return name.name;
     throw new Error('Namespaced JSX attributes not supported');
 }
-function transformElement(element) {
+function transformElement(element, rt) {
     const openingElement = element.openingElement;
     const tag = transformTag(openingElement.name);
     const isNativeElement = t.isStringLiteral(tag);
-    const props = transformProps(openingElement.attributes, isNativeElement);
-    const children = filterChildren(element.children).map(transformChild);
-    return t.callExpression(t.identifier('h'), [
+    let props = transformProps(openingElement.attributes, isNativeElement);
+    if (isNativeElement && openingElement.extra?.rrjsNamespace === 'svg') {
+        const marker = t.objectProperty(t.stringLiteral('__rrjsNamespace'), t.stringLiteral('svg'));
+        if (t.isObjectExpression(props))
+            props.properties.unshift(marker);
+        else
+            props = t.objectExpression([marker]);
+    }
+    const children = filterChildren(element.children).map(c => transformChild(c, rt));
+    return t.callExpression(rt.h(), [
         tag,
         props,
         ...children,
@@ -122,35 +244,39 @@ function transformAttributeValue(name, value, isNativeElement) {
     return t.nullLiteral();
 }
 // ─── Transform a child of a JSX element ──────────────────────────────────────
-function transformChild(child) {
+function transformChild(child, rt) {
     if (t.isJSXText(child)) {
         return t.stringLiteral(child.value);
     }
     if (t.isJSXExpressionContainer(child)) {
         const expr = child.expression;
+        if (expr.extra?.rrjsRegion)
+            return expr;
         if (t.isJSXEmptyExpression(expr)) {
             return t.nullLiteral();
         }
         if (isStaticExpression(expr)) {
             return expr;
         }
+        // The strict run-once pass marks maps whose source membership is a fixed
+        // source array. Execute ordinary Array#map once instead of importing the
+        // keyed reconciler used by the plugin's general mode.
+        if (expr.extra?.rrjsStaticMap)
+            return wrapInThunk(expr);
         // Try the list-as-JSX transform first.
         // If the expression matches items.map((item) => <X key={...} />),
         // rewrite it to a list() call for keyed reconciliation.
-        const listCall = tryTransformMapToList(expr);
+        const listCall = tryTransformMapToList(expr, rt);
         if (listCall)
             return listCall;
-        // Call expressions (like h(...) or list(...)) return Nodes directly
-        // and must NOT be wrapped in a thunk.
-        if (t.isCallExpression(expr)) {
-            return expr;
-        }
+        // Calls may read signals, including through helpers. Evaluate them inside
+        // the child's reactive binding just like other dynamic expressions.
         return wrapInThunk(expr);
     }
     if (t.isJSXElement(child) || t.isJSXFragment(child)) {
         return t.isJSXElement(child)
-            ? transformElement(child)
-            : t.arrayExpression(filterChildren(child.children).map(transformChild));
+            ? transformElement(child, rt)
+            : t.arrayExpression(filterChildren(child.children).map(c => transformChild(c, rt)));
     }
     if (t.isJSXSpreadChild(child)) {
         return child.expression;
@@ -167,22 +293,25 @@ function wrapInThunk(expr) {
 // to list(() => items, (item) => item.id, (item) => h(Foo, ...)).
 // This wires standard JSX iteration into the keyed list reconciler
 // without requiring developers to call list() directly.
-function tryTransformMapToList(expr) {
+function tryTransformMapToList(expr, rt) {
     // Must be a method call to .map
     if (!t.isCallExpression(expr))
         return null;
     if (!t.isMemberExpression(expr.callee))
         return null;
-    if (!t.isIdentifier(expr.callee.property, { name: 'map' }))
+    if (expr.callee.computed || !t.isIdentifier(expr.callee.property, { name: 'map' }))
         return null;
     // Must have a single callback argument
     if (expr.arguments.length !== 1)
         return null;
     const callback = expr.arguments[0];
-    if (!t.isArrowFunctionExpression(callback) && !t.isFunctionExpression(callback))
+    // Function expressions can depend on their own `this` or `arguments`.
+    // Preserve their ordinary map execution until those semantics are modeled.
+    if (!t.isArrowFunctionExpression(callback) || callback.async)
         return null;
-    // Callback should have at least one parameter (the item)
-    if (callback.params.length === 0)
+    // The keyed renderer currently supplies only a reactive item proxy. Keep
+    // native map evaluation for callbacks that also need an index/source array.
+    if (callback.params.length !== 1)
         return null;
     const itemParam = callback.params[0];
     if (!t.isIdentifier(itemParam))
@@ -194,13 +323,13 @@ function tryTransformMapToList(expr) {
         returnedJsx = callback.body;
     }
     else if (t.isBlockStatement(callback.body)) {
-        // Find a top-level return statement
-        for (const stmt of callback.body.body) {
-            if (t.isReturnStatement(stmt) && t.isJSXElement(stmt.argument)) {
-                returnedJsx = stmt.argument;
-                break;
-            }
-        }
+        // Extracting only the return would discard declarations, side effects,
+        // or branches. More complex callbacks use the reactive child path.
+        if (callback.body.body.length !== 1)
+            return null;
+        const stmt = callback.body.body[0];
+        if (t.isReturnStatement(stmt) && t.isJSXElement(stmt.argument))
+            returnedJsx = stmt.argument;
     }
     if (!returnedJsx)
         return null;
@@ -220,8 +349,8 @@ function tryTransformMapToList(expr) {
     //     (item) => <transformed JSX>
     //   )
     const sourceExpression = expr.callee.object;
-    const transformedRenderJsx = transformElement(returnedJsx);
-    return t.callExpression(t.identifier('list'), [
+    const transformedRenderJsx = transformElement(returnedJsx, rt);
+    return t.callExpression(rt.list(), [
         // getItems: () => items
         t.arrowFunctionExpression([], sourceExpression),
         // getKey: (item) => item.id
@@ -243,11 +372,11 @@ function isStaticExpression(expr) {
         t.isBigIntLiteral(expr));
 }
 function filterChildren(children) {
-    // Strip whitespace-only JSXText nodes (caused by JSX formatting)
+    // Preserve intentional inline spaces between children. Whitespace containing
+    // a line break is formatting indentation and does not produce a React child.
     return children.filter(child => {
         if (t.isJSXText(child)) {
-            // Trim and check if anything remains
-            return child.value.trim().length > 0;
+            return child.value.trim().length > 0 || !/[\r\n]/.test(child.value);
         }
         return true;
     });

package/dist/module-contracts.d.ts

@@ -0,0 +1,32 @@
+export type ImportedComponentContract = {
+    props: string[];
+    /** Operation-bearing array prop to its required direct JSX key property. */
+    operationKeys?: Record<string, string>;
+};
+export type ImportedModuleContract = {
+    /** Named hook exports whose direct return value is reactive. */
+    hooks?: string[];
+    /** Named component exports and their accepted prop contracts. */
+    components?: Record<string, string[] | ImportedComponentContract>;
+};
+export type ModuleMetadata = {
+    /** Contracts keyed by the import source exactly as written in this module. */
+    imports?: Record<string, ImportedModuleContract>;
+    /** @deprecated Local-name contracts retained for existing integrations. */
+    importedHooks?: string[];
+    /** @deprecated Local-name contracts retained for existing integrations. */
+    importedComponents?: Record<string, string[] | ImportedComponentContract>;
+    operationProps?: string[];
+    /** Exported operation-bearing prop to its required direct JSX key property. */
+    operationKeyProps?: Record<string, string>;
+};
+export type ModuleContractManifest = {
+    /** Absolute directory against which module keys are resolved. */
+    root: string;
+    /** Exact root-relative module IDs, using forward slashes. */
+    modules: Record<string, ModuleMetadata>;
+};
+/** Validate and retain a build-tool module contract manifest. */
+export declare function defineModuleContracts<T extends ModuleContractManifest>(manifest: T): T;
+/** Resolve metadata by exact module identity. Query strings are ignored. */
+export declare function resolveModuleMetadata(manifest: ModuleContractManifest, moduleId: string): ModuleMetadata;

package/dist/module-contracts.js

@@ -0,0 +1,32 @@
+function normalized(value) {
+    return value.replace(/\\/g, '/').replace(/\/+$/, '');
+}
+/** Validate and retain a build-tool module contract manifest. */
+export function defineModuleContracts(manifest) {
+    const seen = new Set();
+    for (const key of Object.keys(manifest.modules)) {
+        const clean = normalized(key).replace(/^\.\//, '');
+        if (!clean || clean.startsWith('/') || clean === '..' || clean.startsWith('../')) {
+            throw new Error(`runOnce: module contract key must be root-relative: ${key}`);
+        }
+        if (clean !== key)
+            throw new Error(`runOnce: module contract key is not normalized: ${key}`);
+        if (seen.has(clean))
+            throw new Error(`runOnce: duplicate module contract key: ${key}`);
+        seen.add(clean);
+    }
+    return manifest;
+}
+/** Resolve metadata by exact module identity. Query strings are ignored. */
+export function resolveModuleMetadata(manifest, moduleId) {
+    const root = normalized(manifest.root);
+    const id = normalized(moduleId.split('?')[0]);
+    const prefix = `${root}/`;
+    if (!id.startsWith(prefix))
+        throw new Error(`runOnce: module is outside the contract root: ${moduleId}`);
+    const relative = id.slice(prefix.length);
+    const metadata = manifest.modules[relative];
+    if (!metadata)
+        throw new Error(`runOnce: no module contract for ${relative}`);
+    return metadata;
+}

package/dist/run-once.d.ts

@@ -0,0 +1,4 @@
+import type { NodePath } from '@babel/core';
+import * as t from '@babel/types';
+import type { ModuleMetadata } from './module-contracts.js';
+export declare function compileRunOnce(program: NodePath<t.Program>, derive: () => t.Identifier, choose: () => t.Identifier, rendererHelper: (name: 'operationList' | 'listAppend' | 'listPrepend' | 'listClear' | 'listTruncate' | 'listSplice' | 'listReverse' | 'listFilter' | 'listSort' | 'listMap' | 'listMove') => t.Identifier, moduleMetadata?: ModuleMetadata): void;