@creact-labs/creact 0.1.8 → 0.2.1

package/dist/runtime/render.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Render - transform JSX to Fiber tree
+ */
+import type { Fiber } from './fiber';
+/**
+ * Get current fiber (for hooks)
+ */
+export declare function getCurrentFiber(): Fiber | null;
+/**
+ * Get current path (for hooks)
+ */
+export declare function getCurrentPath(): string[];
+/**
+ * Get current resource path (for useInstance)
+ * Only components with useInstance contribute to this path
+ */
+export declare function getCurrentResourcePath(): string[];
+/**
+ * Push a segment to resource path (called by useInstance)
+ */
+export declare function pushResourcePath(segment: string): void;
+/**
+ * Pop a segment from resource path (called after component with instance renders)
+ */
+export declare function popResourcePath(): void;
+/**
+ * Reset resource path (called at start of render)
+ */
+export declare function resetResourcePath(): void;
+/**
+ * Render a JSX element to a Fiber
+ */
+export declare function renderFiber(element: any, path: string[]): Fiber;
+/**
+ * Collect all instance nodes from fiber tree
+ * Returns cloned nodes to ensure returned arrays are independent snapshots
+ */
+export declare function collectInstanceNodes(fiber: Fiber): any[];
+/**
+ * Clean up a fiber tree
+ */
+export declare function cleanupFiber(fiber: Fiber): void;

package/dist/runtime/render.js

@@ -0,0 +1,231 @@
+/**
+ * Render - transform JSX to Fiber tree
+ */
+import { popContext, pushContext } from '../primitives/context';
+import { cleanComputation, runComputation } from '../reactive/tracking';
+import { createFiber } from './fiber';
+// Current render context
+let currentFiber = null;
+let currentPath = [];
+// Resource path - only components with useInstance contribute to this
+// This makes wrapper components (without useInstance) transparent
+let resourcePath = [];
+/**
+ * Get current fiber (for hooks)
+ */
+export function getCurrentFiber() {
+    return currentFiber;
+}
+/**
+ * Get current path (for hooks)
+ */
+export function getCurrentPath() {
+    return [...currentPath];
+}
+/**
+ * Get current resource path (for useInstance)
+ * Only components with useInstance contribute to this path
+ */
+export function getCurrentResourcePath() {
+    return [...resourcePath];
+}
+/**
+ * Push a segment to resource path (called by useInstance)
+ */
+export function pushResourcePath(segment) {
+    resourcePath.push(segment);
+}
+/**
+ * Pop a segment from resource path (called after component with instance renders)
+ */
+export function popResourcePath() {
+    resourcePath.pop();
+}
+/**
+ * Reset resource path (called at start of render)
+ */
+export function resetResourcePath() {
+    resourcePath = [];
+}
+/**
+ * Render a JSX element to a Fiber
+ */
+export function renderFiber(element, path) {
+    // Handle null/undefined/boolean
+    if (element == null || typeof element === 'boolean') {
+        return createFiber(null, {}, path);
+    }
+    // Handle primitives (text)
+    if (typeof element === 'string' || typeof element === 'number') {
+        return createFiber('text', { value: element }, path);
+    }
+    // Handle arrays
+    if (Array.isArray(element)) {
+        const fiber = createFiber('fragment', {}, path);
+        fiber.children = element.map((child, i) => {
+            const childKey = child?.key ?? i;
+            return renderFiber(child, [...path, String(childKey)]);
+        });
+        return fiber;
+    }
+    // Handle JSX element
+    const { type, props = {}, key } = element;
+    const { children, ...restProps } = props;
+    // Generate path segment
+    const name = getNodeName(type, props, key);
+    const fiberPath = [...path, name];
+    const fiber = createFiber(type, restProps, fiberPath, key);
+    // Check if this is a context provider
+    if (element.__isProvider && element.__context) {
+        pushContext(element.__context, props.value);
+        try {
+            fiber.children = renderChildren(children, fiberPath);
+        }
+        finally {
+            popContext(element.__context);
+        }
+        return fiber;
+    }
+    // Handle function components
+    if (typeof type === 'function') {
+        // Capture incoming resource path for reactive re-renders
+        fiber.incomingResourcePath = [...resourcePath];
+        // Create computation for this component
+        const computation = {
+            fn: () => executeComponent(fiber, type, { ...restProps, children }),
+            sources: null,
+            sourceSlots: null,
+            state: 1, // STALE
+            cleanups: null,
+        };
+        fiber.computation = computation;
+        // Initial render
+        runComputation(computation);
+    }
+    else {
+        // Intrinsic element - just render children
+        fiber.children = renderChildren(children, fiberPath);
+    }
+    return fiber;
+}
+/**
+ * Recursively clean up computations from a fiber tree
+ * This prevents stale computations from observing signals after re-render
+ * and ensures queued computations won't run (by marking them CLEAN)
+ */
+function cleanupFiberTree(fibers) {
+    for (const fiber of fibers) {
+        if (fiber.computation) {
+            cleanComputation(fiber.computation);
+            // Mark as CLEAN (0) so it won't run if already queued in batch
+            fiber.computation.state = 0;
+        }
+        if (fiber.children.length > 0) {
+            cleanupFiberTree(fiber.children);
+        }
+    }
+}
+/**
+ * Execute a component function
+ */
+// biome-ignore lint/complexity/noBannedTypes: JSX component types are dynamically resolved at runtime
+function executeComponent(fiber, type, props) {
+    const prevFiber = currentFiber;
+    const prevPath = currentPath;
+    currentFiber = fiber;
+    currentPath = fiber.path;
+    // Restore resource path for reactive re-renders
+    // This ensures components see the correct resource path even when
+    // re-executing independently (not from root)
+    resourcePath = [...(fiber.incomingResourcePath ?? [])];
+    // Clean up old children's computations before re-rendering
+    // This prevents stale computations from observing signals
+    if (fiber.children.length > 0) {
+        cleanupFiberTree(fiber.children);
+    }
+    // Clear instance nodes and placeholder flag before re-executing component
+    fiber.instanceNodes = [];
+    fiber.hasPlaceholderInstance = false;
+    try {
+        // Execute component
+        const result = type(props);
+        // Render children from result
+        fiber.children = renderChildren(result, fiber.path);
+    }
+    finally {
+        // If this component had useInstance (real or placeholder), pop its resource path segment
+        // (useInstance pushes a segment so children see it in their resource path)
+        if (fiber.instanceNodes.length > 0 || fiber.hasPlaceholderInstance) {
+            popResourcePath();
+        }
+        currentFiber = prevFiber;
+        currentPath = prevPath;
+    }
+}
+/**
+ * Render children (handles various child types)
+ */
+function renderChildren(children, parentPath) {
+    if (children == null || typeof children === 'boolean') {
+        return [];
+    }
+    if (Array.isArray(children)) {
+        return children.flatMap((child, i) => {
+            const childKey = child?.key ?? i;
+            const fiber = renderFiber(child, [...parentPath, String(childKey)]);
+            return fiber.type === null ? [] : [fiber];
+        });
+    }
+    const fiber = renderFiber(children, parentPath);
+    return fiber.type === null ? [] : [fiber];
+}
+/**
+ * Get node name from type and props
+ */
+function getNodeName(type, _props, key) {
+    if (key !== undefined) {
+        return String(key);
+    }
+    if (typeof type === 'string') {
+        return type;
+    }
+    if (typeof type === 'function') {
+        return type.name || 'Component';
+    }
+    return 'unknown';
+}
+/**
+ * Collect all instance nodes from fiber tree
+ * Returns cloned nodes to ensure returned arrays are independent snapshots
+ */
+export function collectInstanceNodes(fiber) {
+    const nodes = [];
+    function walk(f) {
+        for (const instanceNode of f.instanceNodes) {
+            // Clone the node to create an independent snapshot
+            // (outputSignals are not cloned - they're internal reactive state)
+            const snapshot = {
+                ...instanceNode,
+                // Deep clone the store so it's independent between runs
+                store: f.store ? JSON.parse(JSON.stringify(f.store)) : undefined,
+            };
+            nodes.push(snapshot);
+        }
+        for (const child of f.children) {
+            walk(child);
+        }
+    }
+    walk(fiber);
+    return nodes;
+}
+/**
+ * Clean up a fiber tree
+ */
+export function cleanupFiber(fiber) {
+    if (fiber.computation) {
+        cleanComputation(fiber.computation);
+    }
+    for (const child of fiber.children) {
+        cleanupFiber(child);
+    }
+}

package/dist/runtime/run.d.ts

@@ -0,0 +1,119 @@
+/**
+ * CReact - Continuous Reactive Runtime with State Machine
+ *
+ * Event-driven runtime that:
+ * 1. Renders JSX -> Fiber tree
+ * 2. Reconciles and applies changes with dependency ordering
+ * 3. Persists state to backend for crash recovery
+ * 4. Subscribes to provider events
+ * 5. When events arrive -> updates affected fibers -> re-renders -> applies new changes
+ */
+import type { InstanceNode } from '../primitives/instance';
+import type { Backend } from '../provider/backend';
+import type { OutputChangeEvent, Provider } from '../provider/interface';
+import type { Fiber } from './fiber';
+import { StateMachine } from './state-machine';
+export interface CReactOptions {
+    maxIterations?: number;
+    /** User identifier for audit logs */
+    user?: string;
+    /** Enable audit logging (requires backend support) */
+    enableAuditLog?: boolean;
+}
+/**
+ * CReact - Continuous reactive runtime with state machine
+ *
+ * Subscribes to provider events and automatically re-renders
+ * components when outputs change. This is event-driven, not poll-driven.
+ *
+ * Requires both:
+ * - CReact.provider: Materializes resources (AWS, Terraform, etc.)
+ * - CReact.backend: Persists deployment state (file, DynamoDB, etc.)
+ */
+export declare class CReact {
+    static provider: Provider;
+    static backend: Backend;
+    private static _lastRuntime;
+    private static _lastStackName;
+    protected instanceProvider: Provider;
+    protected instanceBackend: Backend;
+    protected stateMachine: StateMachine;
+    protected rootFiber: Fiber | null;
+    protected currentNodes: InstanceNode[];
+    protected options: CReactOptions;
+    protected outputChangeHandler: ((change: OutputChangeEvent) => void) | null;
+    protected stackName: string | null;
+    constructor(provider: Provider, backend: Backend, options?: CReactOptions);
+    /**
+     * Start the runtime - render, apply, and begin listening for events
+     *
+     * @param element - JSX element to render
+     * @param stackNameOrPrevious - Stack name (string) or previous nodes (array) for backward compat
+     */
+    run(element: any, stackNameOrPrevious?: string | InstanceNode[]): Promise<void>;
+    /**
+     * Apply changes between previous and current nodes
+     *
+     * Uses dependency ordering from reconciler:
+     * 1. Apply deletes (reverse dependency order)
+     * 2. Apply creates/updates in deployment order
+     * 3. Recursively apply any new nodes that appeared
+     *
+     * With synchronous batching, fillInstanceOutputs triggers dependent
+     * re-renders immediately. New nodes appear in registry right away.
+     */
+    protected applyChanges(previousNodes: InstanceNode[]): Promise<void>;
+    /**
+     * Handle provider output change events
+     *
+     * This is the event-driven part - when provider emits changes,
+     * we update signals (triggering synchronous re-renders via batch),
+     * and apply any new nodes.
+     */
+    protected handleOutputChange(change: OutputChangeEvent): Promise<void>;
+    /**
+     * Get current instance nodes (for debugging/testing)
+     */
+    getNodes(): InstanceNode[];
+    /**
+     * Get the state machine (for advanced usage)
+     */
+    getStateMachine(): StateMachine | null;
+    /**
+     * Stop the runtime
+     */
+    stop(): void;
+    /**
+     * Render CloudDOM - main entry point
+     *
+     * Usage:
+     *   CReact.provider = myProvider;
+     *   CReact.backend = myBackend;
+     *   export default () => renderCloudDOM(<App />, 'my-stack');
+     */
+    static renderCloudDOM(element: any, stackName: string): Promise<InstanceNode[]>;
+    /**
+     * Get last runtime instance (for hot reload / CLI tooling)
+     * Hot reload uses this to re-render with updated code without full restart
+     */
+    static getLastRuntime(): {
+        runtime: CReact;
+        stackName: string;
+    } | null;
+}
+/**
+ * Reset all runtime state (for testing)
+ */
+export declare function resetRuntime(): void;
+/**
+ * Convenience function to run once and return nodes (for testing)
+ *
+ * Creates a runtime with a simple in-memory backend and runs it.
+ * Use this for tests where you don't need persistent state.
+ */
+export declare function run(rootElement: any, provider: Provider, previousNodes?: InstanceNode[], options?: CReactOptions): Promise<InstanceNode[]>;
+/**
+ * Run with explicit backend (for production use)
+ */
+export declare function runWithBackend(rootElement: any, provider: Provider, backend: Backend, stackName: string, options?: CReactOptions): Promise<InstanceNode[]>;
+export declare const renderCloudDOM: typeof CReact.renderCloudDOM;