@creact-labs/creact 0.1.7 → 0.2.0

package/README.md

@@ -1,38 +1,89 @@
+# CReact
 
-NOTE: !!! THIS IS A EXPERIMENT OF THOUGHT NOT A PRODUCTION READY PRODUCT !!!
+**Declarative universal reactive runtime.**
 
-# CReact 
+## Install
 
+```bash
+npm install creact
+```
 
-Write your cloud architecture in JSX
+## Quick Example
 
 ```tsx
-function App() {
+// tsconfig.json: "jsxImportSource": "creact"
+
+import { CReact, renderCloudDOM, useInstance } from 'creact';
+
+// Define constructs
+class ChatModel {
+  constructor(public props: { model: string }) {}
+}
+
+class Memory {
+  constructor(public props: {}) {}
+}
+
+// Define components
+function Model({ model, children }) {
+  const out = useInstance(ChatModel, { model });
+  return children(out);
+}
+
+function Mem({ children }) {
+  const out = useInstance(Memory, {});
+  return children(out);
+}
+
+function App({ prompt }) {
   return (
-    <VPC name="prod-vpc">
-      <Database name="users-db">
-        <API name="users-api">
-          <Monitoring />
-        </API>
-      </Database>
-    </VPC>
+    <Model model="gpt-4">
+      {(model) => (
+        <Mem>
+          {(memory) => (
+            <Agent
+              prompt={prompt}
+              modelId={model.id()}
+              messages={memory.messages()}
+            />
+          )}
+        </Mem>
+      )}
+    </Model>
   );
 }
+
+// Run
+CReact.provider = new AgentProvider();
+CReact.backend = new FileBackend({ directory: '.state' });
+
+await renderCloudDOM(<App prompt="Hello" />, 'agent');
 ```
 
-## Watch It Work
+## The Four Pillars
 
+**Declarative** — Describe what you want, not how to get it.
 
-## Installation & Usage
+**Universal** — Works for AI agents, cloud infrastructure, APIs, anything.
 
-```bash
-# Deploy your infrastructure
-creact deploy --entry my-app.tsx
+**Reactive** — Automatically responds when things change.
 
-# Development mode with hot reload
-creact dev --entry my-app.tsx --auto-approve
+**Runtime** — Keeps running continuously, handles events, recovers from crashes.
 
-# Preview changes
-creact plan --entry my-app.tsx
-```
+## Documentation
+
+### Getting Started
+
+- [Tutorial: Build an AI Agent](./docs/getting-started/1-setup.md)
+
+### Concepts
+
+- [Thinking in CReact](./docs/concepts/thinking-in-creact.md) — The mental model
+- [Constructs](./docs/concepts/constructs.md) — Your building blocks
+- [Components](./docs/concepts/components.md) — Composing with JSX
+- [Reactivity](./docs/concepts/reactivity.md) — When things change
+- [Providers](./docs/concepts/providers.md) — Connecting to the real world
+
+## License
 
+Apache-2.0

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CReact CLI
+ *
+ * Usage: creact ./app.tsx
+ *        creact --watch ./app.tsx
+ *
+ * Runs a CReact application with the configured provider.
+ * Uses tsx under the hood to execute TypeScript/TSX files.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * CReact CLI
+ *
+ * Usage: creact ./app.tsx
+ *        creact --watch ./app.tsx
+ *
+ * Runs a CReact application with the configured provider.
+ * Uses tsx under the hood to execute TypeScript/TSX files.
+ */
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+function showHelp() {
+    console.log(`
+CReact CLI
+
+Usage:
+  creact <entrypoint>           Run a CReact application
+  creact --watch <entrypoint>   Run with hot reload on file changes
+  creact -w <entrypoint>        Short form of --watch
+  creact --help                 Show this help message
+
+Examples:
+  creact ./app.tsx              Run app.tsx
+  creact -w ./app.tsx           Run with hot reload
+  creact --watch src/index.tsx  Run src/index.tsx with hot reload
+
+The entrypoint file should:
+  1. Set CReact.provider to your provider
+  2. Export a default async function that calls renderCloudDOM()
+
+Example entrypoint:
+  import { CReact, renderCloudDOM } from 'creact';
+  import { App } from './components/App.js';
+  import { MyProvider } from './providers/MyProvider.js';
+
+  CReact.provider = await MyProvider.create();
+
+  export default async function() {
+    return await renderCloudDOM(<App />, 'my-stack');
+  }
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        showHelp();
+        process.exit(0);
+    }
+    // Parse --watch / -w flag and get entrypoint
+    let watch = false;
+    let entrypointArg;
+    const firstArg = args[0];
+    if (firstArg === '--watch' || firstArg === '-w') {
+        watch = true;
+        const arg = args[1];
+        if (!arg) {
+            console.error('Error: --watch requires an entrypoint');
+            process.exit(1);
+        }
+        entrypointArg = arg;
+    }
+    else if (firstArg) {
+        entrypointArg = firstArg;
+    }
+    else {
+        showHelp();
+        process.exit(0);
+    }
+    const entrypoint = resolve(process.cwd(), entrypointArg);
+    // Build tsx command
+    const tsxArgs = watch ? ['tsx', 'watch', entrypoint] : ['tsx', entrypoint];
+    // Spawn tsx to run the entrypoint
+    const child = spawn('npx', tsxArgs, {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+        shell: true,
+    });
+    child.on('error', (error) => {
+        console.error('Error running CReact application:');
+        console.error(error.message);
+        process.exit(1);
+    });
+    child.on('exit', (code) => {
+        process.exit(code ?? 0);
+    });
+}
+main();

package/dist/index.d.ts

@@ -1,46 +1,21 @@
 /**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
+ * CReact - Universal Reactive Runtime
  */
-export { CReact, JSXElement } from './jsx';
-export type { FC, PropsWithChildren, ComponentProps } from './jsx';
-import { CReact as CReactClass } from './core/CReact';
-export { CReact as CReactCore, CReactConfig } from './core/CReact';
-export declare const renderCloudDOM: typeof CReactClass.renderCloudDOM;
-export { Renderer } from './core/Renderer';
-export { Validator } from './core/Validator';
-export { CloudDOMBuilder } from './core/CloudDOMBuilder';
-export { FiberNode, CloudDOMNode } from './core/types';
-export { ICloudProvider, DriftDetectionResult, OutputChangeEvent } from './providers/ICloudProvider';
-export { IBackendProvider } from './providers/IBackendProvider';
-export { useInstance } from './hooks/useInstance';
-export { useState } from './hooks/useState';
-export { useContext } from './hooks/useContext';
-export { useEffect } from './hooks/useEffect';
-export { createContext, Context } from './context';
-export { generateResourceId, toKebabCase, getNodeName, validateIdUniqueness, normalizePathSegment, normalizePath, formatPath, parseResourceId, } from './utils/naming';
+export { createElement, Fragment, jsx, jsxs } from './jsx/jsx-runtime';
+export { createContext, useContext } from './primitives/context';
+export { useInstance } from './primitives/instance';
+export { createStore } from './primitives/store';
+export type { AuditLogEntry, Backend, ChangeSet, DeploymentState, DeploymentStatus, ResourceState, SerializedNode, } from './provider/backend';
+export { serializeNode, serializeNodes } from './provider/backend';
+export type { OutputChangeEvent, Provider } from './provider/interface';
+export { createMockProvider } from './provider/interface';
+export { createEffect, onCleanup } from './reactive/effect';
+export { createSignal } from './reactive/signal';
+export { batch, untrack } from './reactive/tracking';
+export type { DependencyGraph } from './runtime/reconcile';
+export { buildDependencyGraph, computeParallelBatches, hasNewNodes, reconcile, topologicalSort, } from './runtime/reconcile';
+export type { CReactOptions } from './runtime/run';
+export { CReact, renderCloudDOM, resetRuntime, run, runWithBackend } from './runtime/run';
+export type { StateMachineOptions } from './runtime/state-machine';
+export { StateMachine } from './runtime/state-machine';
+export type { Accessor, Context, Fiber, InstanceNode, JSXElement, OutputAccessors, SetStoreFunction, Setter, } from './types';

package/dist/index.js

@@ -1,70 +1,22 @@
-"use strict";
 /**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
+ * CReact - Universal Reactive Runtime
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseResourceId = exports.formatPath = exports.normalizePath = exports.normalizePathSegment = exports.validateIdUniqueness = exports.getNodeName = exports.toKebabCase = exports.generateResourceId = exports.createContext = exports.useEffect = exports.useContext = exports.useState = exports.useInstance = exports.CloudDOMBuilder = exports.Validator = exports.Renderer = exports.renderCloudDOM = exports.CReactCore = exports.CReact = void 0;
-// CReact - Infrastructure as Code with JSX
-// Main entry point for the library
-// JSX support
-var jsx_1 = require("./jsx");
-Object.defineProperty(exports, "CReact", { enumerable: true, get: function () { return jsx_1.CReact; } });
-// Core classes
-const CReact_1 = require("./core/CReact");
-var CReact_2 = require("./core/CReact");
-Object.defineProperty(exports, "CReactCore", { enumerable: true, get: function () { return CReact_2.CReact; } });
-exports.renderCloudDOM = CReact_1.CReact.renderCloudDOM;
-var Renderer_1 = require("./core/Renderer");
-Object.defineProperty(exports, "Renderer", { enumerable: true, get: function () { return Renderer_1.Renderer; } });
-var Validator_1 = require("./core/Validator");
-Object.defineProperty(exports, "Validator", { enumerable: true, get: function () { return Validator_1.Validator; } });
-var CloudDOMBuilder_1 = require("./core/CloudDOMBuilder");
-Object.defineProperty(exports, "CloudDOMBuilder", { enumerable: true, get: function () { return CloudDOMBuilder_1.CloudDOMBuilder; } });
-// Hooks
-var useInstance_1 = require("./hooks/useInstance");
-Object.defineProperty(exports, "useInstance", { enumerable: true, get: function () { return useInstance_1.useInstance; } });
-var useState_1 = require("./hooks/useState");
-Object.defineProperty(exports, "useState", { enumerable: true, get: function () { return useState_1.useState; } });
-var useContext_1 = require("./hooks/useContext");
-Object.defineProperty(exports, "useContext", { enumerable: true, get: function () { return useContext_1.useContext; } });
-var useEffect_1 = require("./hooks/useEffect");
-Object.defineProperty(exports, "useEffect", { enumerable: true, get: function () { return useEffect_1.useEffect; } });
-// Context API
-var context_1 = require("./context");
-Object.defineProperty(exports, "createContext", { enumerable: true, get: function () { return context_1.createContext; } });
-// Utilities
-var naming_1 = require("./utils/naming");
-Object.defineProperty(exports, "generateResourceId", { enumerable: true, get: function () { return naming_1.generateResourceId; } });
-Object.defineProperty(exports, "toKebabCase", { enumerable: true, get: function () { return naming_1.toKebabCase; } });
-Object.defineProperty(exports, "getNodeName", { enumerable: true, get: function () { return naming_1.getNodeName; } });
-Object.defineProperty(exports, "validateIdUniqueness", { enumerable: true, get: function () { return naming_1.validateIdUniqueness; } });
-Object.defineProperty(exports, "normalizePathSegment", { enumerable: true, get: function () { return naming_1.normalizePathSegment; } });
-Object.defineProperty(exports, "normalizePath", { enumerable: true, get: function () { return naming_1.normalizePath; } });
-Object.defineProperty(exports, "formatPath", { enumerable: true, get: function () { return naming_1.formatPath; } });
-Object.defineProperty(exports, "parseResourceId", { enumerable: true, get: function () { return naming_1.parseResourceId; } });
+// JSX
+export { createElement, Fragment, jsx, jsxs } from './jsx/jsx-runtime';
+export { createContext, useContext } from './primitives/context';
+// Primitives
+export { useInstance } from './primitives/instance';
+export { createStore } from './primitives/store';
+// Backend
+export { serializeNode, serializeNodes } from './provider/backend';
+// Provider
+export { createMockProvider } from './provider/interface';
+// Reactive
+export { createEffect, onCleanup } from './reactive/effect';
+export { createSignal } from './reactive/signal';
+export { batch, untrack } from './reactive/tracking';
+// Reconciler
+export { buildDependencyGraph, computeParallelBatches, hasNewNodes, reconcile, topologicalSort, } from './runtime/reconcile';
+// Runtime
+export { CReact, renderCloudDOM, resetRuntime, run, runWithBackend } from './runtime/run';
+export { StateMachine } from './runtime/state-machine';

package/dist/jsx/index.d.ts

@@ -0,0 +1,2 @@
+export { createElement, Fragment, type JSXElement, jsx, jsxDEV, jsxs } from './jsx-runtime';
+export type { JSX } from './types';

package/dist/jsx/index.js

@@ -0,0 +1 @@
+export { createElement, Fragment, jsx, jsxDEV, jsxs } from './jsx-runtime';

package/dist/jsx/jsx-dev-runtime.d.ts

@@ -0,0 +1,4 @@
+/**
+ * JSX Dev Runtime - re-exports from jsx-runtime for development mode
+ */
+export { Fragment, jsx, jsx as jsxDEV, jsxs } from './jsx-runtime';

package/dist/jsx/jsx-dev-runtime.js

@@ -0,0 +1,4 @@
+/**
+ * JSX Dev Runtime - re-exports from jsx-runtime for development mode
+ */
+export { Fragment, jsx, jsx as jsxDEV, jsxs } from './jsx-runtime';

package/dist/jsx/jsx-runtime.d.ts

@@ -0,0 +1,38 @@
+/**
+ * JSX Runtime - createElement and Fragment
+ */
+export interface JSXElement {
+    type: any;
+    props: Record<string, any>;
+    key?: string | number;
+}
+/**
+ * JSX namespace for TypeScript
+ * Handles key and children automatically - no need to declare in component props
+ */
+export declare namespace JSX {
+    type Element = JSXElement;
+    interface IntrinsicElements {
+        [elemName: string]: any;
+    }
+    interface IntrinsicAttributes {
+        key?: string | number;
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+}
+/**
+ * Create a JSX element
+ */
+export declare function createElement(type: any, props: Record<string, any> | null, ...children: any[]): JSXElement;
+/**
+ * Fragment - renders children without wrapper
+ */
+export declare const Fragment: unique symbol;
+/**
+ * JSX runtime functions (for automatic JSX transform)
+ */
+export declare function jsx(type: any, props: Record<string, any>, key?: string | number): JSXElement;
+export declare function jsxs(type: any, props: Record<string, any>, key?: string | number): JSXElement;
+export { jsx as jsxDEV };

package/dist/jsx/jsx-runtime.js

@@ -0,0 +1,38 @@
+/**
+ * JSX Runtime - createElement and Fragment
+ */
+/**
+ * Create a JSX element
+ */
+export function createElement(type, props, ...children) {
+    const normalizedProps = { ...props };
+    // Handle children
+    if (children.length === 1) {
+        normalizedProps.children = children[0];
+    }
+    else if (children.length > 1) {
+        normalizedProps.children = children;
+    }
+    // Extract key
+    const key = normalizedProps.key;
+    delete normalizedProps.key;
+    return {
+        type,
+        props: normalizedProps,
+        key,
+    };
+}
+/**
+ * Fragment - renders children without wrapper
+ */
+export const Fragment = Symbol.for('creact.fragment');
+/**
+ * JSX runtime functions (for automatic JSX transform)
+ */
+export function jsx(type, props, key) {
+    return { type, props, key };
+}
+export function jsxs(type, props, key) {
+    return { type, props, key };
+}
+export { jsx as jsxDEV };

package/dist/jsx/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * JSX Type Definitions
+ */
+export declare namespace JSX {
+    type Element = import('./jsx-runtime').JSXElement;
+    interface IntrinsicElements {
+        [key: string]: any;
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+}

package/dist/jsx/types.js

@@ -0,0 +1,4 @@
+/**
+ * JSX Type Definitions
+ */
+export {};

package/dist/primitives/context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Context - pass values down the component tree (non-reactive)
+ */
+export interface Context<T> {
+    id: symbol;
+    defaultValue: T | undefined;
+    Provider: (props: {
+        value: T;
+        children: any;
+    }) => any;
+}
+/**
+ * Create a context for passing values down the tree
+ */
+export declare function createContext<T>(defaultValue?: T): Context<T>;
+/**
+ * Read a context value
+ */
+export declare function useContext<T>(context: Context<T>): T;
+/**
+ * Push a context value (called by renderer)
+ * @internal
+ */
+export declare function pushContext<T>(contextId: symbol, value: T): void;
+/**
+ * Pop a context value (called by renderer)
+ * @internal
+ */
+export declare function popContext(contextId: symbol): void;
+/**
+ * Clear all context stacks (for testing)
+ * @internal
+ */
+export declare function clearContextStacks(): void;

package/dist/primitives/context.js

@@ -0,0 +1,63 @@
+/**
+ * Context - pass values down the component tree (non-reactive)
+ */
+// Stack of values per context ID
+// biome-ignore lint/suspicious/noExplicitAny: context values can be any type
+const contextStacks = new Map();
+/**
+ * Create a context for passing values down the tree
+ */
+export function createContext(defaultValue) {
+    const id = Symbol('context');
+    // biome-ignore lint/suspicious/noExplicitAny: Provider accepts any JSX children
+    const Provider = (props) => {
+        return {
+            type: Provider,
+            props,
+            __context: id,
+            __isProvider: true,
+        };
+    };
+    return {
+        id,
+        defaultValue,
+        Provider,
+    };
+}
+/**
+ * Read a context value
+ */
+export function useContext(context) {
+    const stack = contextStacks.get(context.id);
+    if (stack?.length) {
+        return stack[stack.length - 1];
+    }
+    return context.defaultValue;
+}
+/**
+ * Push a context value (called by renderer)
+ * @internal
+ */
+export function pushContext(contextId, value) {
+    let stack = contextStacks.get(contextId);
+    if (!stack) {
+        stack = [];
+        contextStacks.set(contextId, stack);
+    }
+    stack.push(value);
+}
+/**
+ * Pop a context value (called by renderer)
+ * @internal
+ */
+export function popContext(contextId) {
+    const stack = contextStacks.get(contextId);
+    stack?.pop();
+}
+/**
+ * Clear all context stacks (for testing)
+ * @internal
+ */
+export function clearContextStacks() {
+    contextStacks.clear();
+}

package/dist/primitives/index.d.ts

@@ -0,0 +1,3 @@
+export { type Context, createContext, useContext } from './context';
+export { clearNodeRegistry, fillInstanceOutputs, getAllNodes, getNodeById, type InstanceNode, type OutputAccessors, useInstance, } from './instance';
+export { createStore, type SetStoreFunction } from './store';

package/dist/primitives/index.js

@@ -0,0 +1,3 @@
+export { createContext, useContext } from './context';
+export { clearNodeRegistry, fillInstanceOutputs, getAllNodes, getNodeById, useInstance, } from './instance';
+export { createStore } from './store';

package/dist/primitives/instance.d.ts

@@ -0,0 +1,72 @@
+/**
+ * useInstance - bind to a provider and get reactive outputs
+ */
+import { type Accessor, type Setter } from '../reactive/signal';
+/**
+ * Instance node - represents something materialized by provider
+ */
+export interface InstanceNode {
+    id: string;
+    path: string[];
+    construct: any;
+    constructType: string;
+    props: Record<string, any>;
+    outputSignals: Map<string, [Accessor<any>, Setter<any>]>;
+    children: InstanceNode[];
+    store?: any;
+    outputs?: Record<string, any>;
+    /** Update outputs reactively - triggers dependent re-renders via signals */
+    setOutputs(outputs: Record<string, any>): void;
+}
+/**
+ * Serialized node shape (from backend.ts) - only what we need for hydration
+ */
+interface SerializedNodeForHydration {
+    id: string;
+    outputs?: Record<string, any>;
+}
+/**
+ * Prepare output hydration from serialized nodes
+ * Called by runtime BEFORE rendering to restore outputs
+ */
+export declare function prepareOutputHydration(serializedNodes: SerializedNodeForHydration[]): void;
+/**
+ * Clear output hydration map
+ */
+export declare function clearOutputHydration(): void;
+/**
+ * Output accessor type - each property is a signal accessor
+ */
+export type OutputAccessors<O> = {
+    [K in keyof O]: () => O[K] | undefined;
+};
+/**
+ * Create an instance bound to a provider
+ */
+export declare function useInstance<O extends Record<string, any> = Record<string, any>>(construct: any, props: Record<string, any>): OutputAccessors<O>;
+/**
+ * Fill instance outputs (called by runtime after provider returns)
+ * @internal
+ */
+export declare function fillInstanceOutputs(nodeId: string, outputs: Record<string, any>): void;
+/**
+ * Get a node by ID
+ * @internal
+ */
+export declare function getNodeById(nodeId: string): InstanceNode | undefined;
+/**
+ * Get all registered nodes
+ * @internal
+ */
+export declare function getAllNodes(): InstanceNode[];
+/**
+ * Clear node registry (for testing)
+ * @internal
+ */
+export declare function clearNodeRegistry(): void;
+/**
+ * Clear node ownership (call at start of each render pass)
+ * @internal
+ */
+export declare function clearNodeOwnership(): void;
+export {};