@plures/praxis 1.1.0 → 1.1.2

package/docs/REACTIVE_REDESIGN.md

@@ -1,132 +1,132 @@
-# Praxis Reactive Redesign (Svelte 5 Native)
-
-## 1. Vision
-
-Praxis will evolve from a "step-based" logic engine to a **natively reactive** framework built on Svelte 5 Runes. This means the core `LogicEngine` will be a Svelte class, and state changes will propagate automatically through the dependency graph.
-
-## 2. Core Architecture
-
-### 2.1. The Reactive Engine (`LogicEngine.svelte.ts`)
-
-The engine will no longer be a plain TS class. It will use `$state` to hold the application context and facts.
-
-```typescript
-// praxis/src/core/engine.svelte.ts
-import { type Class } from 'type-fest';
-
-export class LogicEngine<TContext extends object> {
-    // The single source of truth, reactive by default
-    state = $state<{
-        context: TContext;
-        facts: PraxisFact[];
-        meta: Record<string, unknown>;
-    }>({
-        context: {} as TContext,
-        facts: [],
-        meta: {}
-    });
-
-    constructor(initialContext: TContext) {
-        this.state.context = initialContext;
-    }
-
-    // Expose the raw reactive state for binding/derivation
-    get context() {
-        return this.state.context;
-    }
-    
-    get facts() {
-        return this.state.facts;
-    }
-}
-```
-
-### 2.2. Rules as Mutators
-
-In the previous version, rules returned new facts. In the reactive version, rules are **mutators** that directly modify the reactive state. This allows Svelte's fine-grained reactivity to trigger only the necessary updates.
-
-```typescript
-// praxis/src/core/types.ts
-export type ReactiveRule<TContext> = (
-    state: { context: TContext; facts: PraxisFact[] }, 
-    event: PraxisEvent
-) => void;
-```
-
-### 2.3. Derivations (Computed State)
-
-Instead of recomputing state in every "step", we encourage using `$derived` for values that depend on the core state.
-
-```typescript
-// Example usage in an app
-class AppState {
-    // Core state
-    connections = $state<Connection[]>([]);
-    activeId = $state<string | null>(null);
-
-    // Derived state (automatically updates)
-    activeConnection = $derived(
-        this.connections.find(c => c.id === this.activeId)
-    );
-}
-```
-
-### 2.4. Actors as Effects
-
-Actors are simply `$effect` blocks that watch the state.
-
-```typescript
-// praxis/src/core/actor.ts
-export function createActor<TContext>(
-    engine: LogicEngine<TContext>, 
-    fn: (context: TContext) => void
-) {
-    $effect(() => {
-        fn(engine.context);
-    });
-}
-```
-
-## 3. Migration Plan
-
-### Phase 1: Core Update
-1.  **Rename** `engine.ts` to `engine.svelte.ts`.
-2.  **Update** `LogicEngine` to use `$state`.
-3.  **Update** `PraxisRegistry` to support reactive rules.
-4.  **Add** `svelte` as a direct dependency (or ensure peer dependency is strictly enforced).
-
-### Phase 2: Bridge Update
-1.  Create a `ReactiveBridge` that uses `$effect.root` to subscribe to state changes and send messages to the WebView.
-2.  This replaces the manual `getSerializableContext` calls.
-
-### Phase 3: Tooling
-1.  Update the CLI to generate `.svelte.ts` files for schemas.
-
-## 4. Example Usage
-
-```typescript
-// defining the engine
-const engine = new LogicEngine({ count: 0 });
-
-// defining a rule
-const incrementRule: ReactiveRule<any> = (state, event) => {
-    if (event.type === 'INCREMENT') {
-        state.context.count++;
-    }
-};
-
-// processing an event
-engine.apply(incrementRule, { type: 'INCREMENT' });
-
-// reacting (Actor)
-$effect(() => {
-    console.log("Count is now:", engine.context.count);
-});
-```
-
-## 5. Benefits
-
-1.  **Simplicity**: No more complex "step" logic or diffing. Svelte handles the dependency tracking.
-2.  **Performance**: Fine-grained updates. Only the parts of the UI/logic that depend on changed data will re-run.
-3.  **Isomorphism**: The same logic code runs in the Extension Host (Node) and the WebView (Browser).
-
+# Praxis Reactive Redesign (Svelte 5 Native)
+
+## 1. Vision
+
+Praxis will evolve from a "step-based" logic engine to a **natively reactive** framework built on Svelte 5 Runes. This means the core `LogicEngine` will be a Svelte class, and state changes will propagate automatically through the dependency graph.
+
+## 2. Core Architecture
+
+### 2.1. The Reactive Engine (`LogicEngine.svelte.ts`)
+
+The engine will no longer be a plain TS class. It will use `$state` to hold the application context and facts.
+
+```typescript
+// praxis/src/core/engine.svelte.ts
+import { type Class } from 'type-fest';
+
+export class LogicEngine<TContext extends object> {
+    // The single source of truth, reactive by default
+    state = $state<{
+        context: TContext;
+        facts: PraxisFact[];
+        meta: Record<string, unknown>;
+    }>({
+        context: {} as TContext,
+        facts: [],
+        meta: {}
+    });
+
+    constructor(initialContext: TContext) {
+        this.state.context = initialContext;
+    }
+
+    // Expose the raw reactive state for binding/derivation
+    get context() {
+        return this.state.context;
+    }
+    
+    get facts() {
+        return this.state.facts;
+    }
+}
+```
+
+### 2.2. Rules as Mutators
+
+In the previous version, rules returned new facts. In the reactive version, rules are **mutators** that directly modify the reactive state. This allows Svelte's fine-grained reactivity to trigger only the necessary updates.
+
+```typescript
+// praxis/src/core/types.ts
+export type ReactiveRule<TContext> = (
+    state: { context: TContext; facts: PraxisFact[] }, 
+    event: PraxisEvent
+) => void;
+```
+
+### 2.3. Derivations (Computed State)
+
+Instead of recomputing state in every "step", we encourage using `$derived` for values that depend on the core state.
+
+```typescript
+// Example usage in an app
+class AppState {
+    // Core state
+    connections = $state<Connection[]>([]);
+    activeId = $state<string | null>(null);
+
+    // Derived state (automatically updates)
+    activeConnection = $derived(
+        this.connections.find(c => c.id === this.activeId)
+    );
+}
+```
+
+### 2.4. Actors as Effects
+
+Actors are simply `$effect` blocks that watch the state.
+
+```typescript
+// praxis/src/core/actor.ts
+export function createActor<TContext>(
+    engine: LogicEngine<TContext>, 
+    fn: (context: TContext) => void
+) {
+    $effect(() => {
+        fn(engine.context);
+    });
+}
+```
+
+## 3. Migration Plan
+
+### Phase 1: Core Update
+1.  **Rename** `engine.ts` to `engine.svelte.ts`.
+2.  **Update** `LogicEngine` to use `$state`.
+3.  **Update** `PraxisRegistry` to support reactive rules.
+4.  **Add** `svelte` as a direct dependency (or ensure peer dependency is strictly enforced).
+
+### Phase 2: Bridge Update
+1.  Create a `ReactiveBridge` that uses `$effect.root` to subscribe to state changes and send messages to the WebView.
+2.  This replaces the manual `getSerializableContext` calls.
+
+### Phase 3: Tooling
+1.  Update the CLI to generate `.svelte.ts` files for schemas.
+
+## 4. Example Usage
+
+```typescript
+// defining the engine
+const engine = new LogicEngine({ count: 0 });
+
+// defining a rule
+const incrementRule: ReactiveRule<any> = (state, event) => {
+    if (event.type === 'INCREMENT') {
+        state.context.count++;
+    }
+};
+
+// processing an event
+engine.apply(incrementRule, { type: 'INCREMENT' });
+
+// reacting (Actor)
+$effect(() => {
+    console.log("Count is now:", engine.context.count);
+});
+```
+
+## 5. Benefits
+
+1.  **Simplicity**: No more complex "step" logic or diffing. Svelte handles the dependency tracking.
+2.  **Performance**: Fine-grained updates. Only the parts of the UI/logic that depend on changed data will re-run.
+3.  **Isomorphism**: The same logic code runs in the Extension Host (Node) and the WebView (Browser).
+

package/docs/SVELTE_INTEGRATION_STRATEGY.md

@@ -1,68 +1,68 @@
-# Svelte Integration Strategy for Praxis
-
-## Current State
-
-Praxis uses **Svelte 5 Runes** (`$state`, `$derived`, `$effect`) as its core reactivity engine. This provides excellent performance and developer experience but introduces a build-time dependency on the Svelte compiler.
-
-## The Problem
-
-Consumers of `@plures/praxis` in non-browser environments (Node.js, Electron Main, VS Code Extension Host) currently face a hurdle:
-
-1.  They import `ReactiveLogicEngine`.
-2.  This imports code containing `$state`.
-3.  **Runtime Error**: `$state is not defined`.
-
-To fix this, the **consumer** currently has to configure their bundler (esbuild, webpack, vite) to compile the *library's* code (or their own usage of it) using `esbuild-svelte`. This leaks implementation details and increases friction.
-
-## Strategy: Invisible Integration
-
-We want users to `import { engine } from '@plures/praxis'` and have it "just work" anywhere, without knowing it uses Svelte under the hood.
-
-### 1. Dual Distribution Builds (Recommended)
-
-The `@plures/praxis` package should ship pre-compiled artifacts for different environments.
-
-**`package.json` exports:**
-
-```json
-{
-  "exports": {
-    ".": {
-      "node": "./dist/node/index.js",      // Compiled with generate: 'server'
-      "browser": "./dist/browser/index.js", // Compiled with generate: 'client' (or raw?)
-      "default": "./dist/node/index.js"
-    }
-  }
-}
-```
-
-**Build Pipeline Changes:**
-*   Run `tsup` or `esbuild` twice during the library build process.
-*   **Build 1 (Node)**: Use `esbuild-svelte` with `generate: 'server'`. This bakes the reactivity into standard JS getters/setters/signals that Node can execute.
-*   **Build 2 (Browser)**: Use `esbuild-svelte` with `generate: 'client'` (or leave as raw `.svelte.ts` if we expect the user to bundle it, but pre-compiled is safer).
-
-**Result**:
-The consumer installs `@plures/praxis`.
-*   **In VS Code**: Node resolves `dist/node/index.js`. The code is standard JS. No `esbuild-svelte` needed in the consumer's build config (unless they write *their own* `.svelte.ts` files).
-*   **In Webview**: Bundler resolves `dist/browser/index.js`.
-
-### 2. The "Core" vs "Reactive" Split
-
-If we want to support users who strictly cannot have Svelte code (even compiled), we could separate the packages:
-
-*   `@plures/praxis-core`: Pure TS, no reactivity. Just the logic engine, types, and rule processing. State is a plain object.
-*   `@plures/praxis`: Re-exports core + the Svelte reactive engine.
-
-### 3. Seamless Developer Experience (DX)
-
-To make the integration invisible:
-
-1.  **Pre-compile everything**: Never force the user to compile `node_modules`.
-2.  **Type Definitions**: Ensure `.d.ts` files hide the Svelte implementation details (e.g., `state` property should just look like `TContext`, not a Svelte proxy type).
-3.  **Templates**: If the user *does* want to write reactive logic (e.g., `myRules.svelte.ts`), provide templates (`praxis init`) that set up the build tools automatically.
-
-## Action Plan
-
-1.  **Update Praxis Build**: Modify `praxis/package.json` and build scripts to output a Node-compatible build.
-2.  **Verify**: Create a test consumer (simple Node script) that imports the library and runs without any build step.
-3.  **Document**: Update the main README to explain that Praxis works in Node.js out of the box.
+# Svelte Integration Strategy for Praxis
+
+## Current State
+
+Praxis uses **Svelte 5 Runes** (`$state`, `$derived`, `$effect`) as its core reactivity engine. This provides excellent performance and developer experience but introduces a build-time dependency on the Svelte compiler.
+
+## The Problem
+
+Consumers of `@plures/praxis` in non-browser environments (Node.js, Electron Main, VS Code Extension Host) currently face a hurdle:
+
+1.  They import `ReactiveLogicEngine`.
+2.  This imports code containing `$state`.
+3.  **Runtime Error**: `$state is not defined`.
+
+To fix this, the **consumer** currently has to configure their bundler (esbuild, webpack, vite) to compile the *library's* code (or their own usage of it) using `esbuild-svelte`. This leaks implementation details and increases friction.
+
+## Strategy: Invisible Integration
+
+We want users to `import { engine } from '@plures/praxis'` and have it "just work" anywhere, without knowing it uses Svelte under the hood.
+
+### 1. Dual Distribution Builds (Recommended)
+
+The `@plures/praxis` package should ship pre-compiled artifacts for different environments.
+
+**`package.json` exports:**
+
+```json
+{
+  "exports": {
+    ".": {
+      "node": "./dist/node/index.js",      // Compiled with generate: 'server'
+      "browser": "./dist/browser/index.js", // Compiled with generate: 'client' (or raw?)
+      "default": "./dist/node/index.js"
+    }
+  }
+}
+```
+
+**Build Pipeline Changes:**
+*   Run `tsup` or `esbuild` twice during the library build process.
+*   **Build 1 (Node)**: Use `esbuild-svelte` with `generate: 'server'`. This bakes the reactivity into standard JS getters/setters/signals that Node can execute.
+*   **Build 2 (Browser)**: Use `esbuild-svelte` with `generate: 'client'` (or leave as raw `.svelte.ts` if we expect the user to bundle it, but pre-compiled is safer).
+
+**Result**:
+The consumer installs `@plures/praxis`.
+*   **In VS Code**: Node resolves `dist/node/index.js`. The code is standard JS. No `esbuild-svelte` needed in the consumer's build config (unless they write *their own* `.svelte.ts` files).
+*   **In Webview**: Bundler resolves `dist/browser/index.js`.
+
+### 2. The "Core" vs "Reactive" Split
+
+If we want to support users who strictly cannot have Svelte code (even compiled), we could separate the packages:
+
+*   `@plures/praxis-core`: Pure TS, no reactivity. Just the logic engine, types, and rule processing. State is a plain object.
+*   `@plures/praxis`: Re-exports core + the Svelte reactive engine.
+
+### 3. Seamless Developer Experience (DX)
+
+To make the integration invisible:
+
+1.  **Pre-compile everything**: Never force the user to compile `node_modules`.
+2.  **Type Definitions**: Ensure `.d.ts` files hide the Svelte implementation details (e.g., `state` property should just look like `TContext`, not a Svelte proxy type).
+3.  **Templates**: If the user *does* want to write reactive logic (e.g., `myRules.svelte.ts`), provide templates (`praxis init`) that set up the build tools automatically.
+
+## Action Plan
+
+1.  **Update Praxis Build**: Modify `praxis/package.json` and build scripts to output a Node-compatible build.
+2.  **Verify**: Create a test consumer (simple Node script) that imports the library and runs without any build step.
+3.  **Document**: Update the main README to explain that Praxis works in Node.js out of the box.

package/package.json

@@ -1,132 +1,132 @@
-{
-  "name": "@plures/praxis",
-  "version": "1.1.0",
-  "description": "The Full Plures Application Framework - declarative schemas, logic engine, component generation, and local-first data",
-  "type": "module",
-  "main": "./dist/node/index.js",
-  "types": "./dist/node/index.d.ts",
-  "bin": {
-    "praxis": "./dist/node/cli/index.js"
-  },
-  "exports": {
-    ".": {
-      "node": {
-        "types": "./dist/node/index.d.ts",
-        "import": "./dist/node/index.js",
-        "require": "./dist/node/index.cjs"
-      },
-      "browser": {
-        "types": "./dist/browser/index.d.ts",
-        "import": "./dist/browser/index.js"
-      },
-      "default": "./dist/node/index.js"
-    },
-    "./svelte": {
-      "node": {
-        "types": "./dist/node/integrations/svelte.d.ts",
-        "import": "./dist/node/integrations/svelte.js",
-        "require": "./dist/node/integrations/svelte.cjs"
-      },
-      "browser": {
-        "types": "./dist/browser/integrations/svelte.d.ts",
-        "import": "./dist/browser/integrations/svelte.js"
-      },
-      "default": "./dist/node/integrations/svelte.js"
-    },
-    "./schema": {
-      "types": "./dist/node/schema.d.ts",
-      "import": "./dist/node/schema.js",
-      "require": "./dist/node/schema.cjs",
-      "default": "./dist/node/schema.js"
-    },
-    "./component": {
-      "types": "./dist/node/component.d.ts",
-      "import": "./dist/node/component.js",
-      "require": "./dist/node/component.cjs",
-      "default": "./dist/node/component.js"
-    },
-    "./cloud": {
-      "types": "./dist/node/cloud/index.d.ts",
-      "import": "./dist/node/cloud/index.js",
-      "require": "./dist/node/cloud/index.cjs",
-      "default": "./dist/node/cloud/index.js"
-    },
-    "./components": {
-      "types": "./dist/node/components/index.d.ts",
-      "svelte": "./src/components/TerminalNode.svelte",
-      "import": "./dist/node/components/index.js",
-      "require": "./dist/node/components/index.cjs",
-      "default": "./dist/node/components/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "src",
-    "core",
-    "cli",
-    "templates",
-    "docs",
-    "README.md",
-    "FRAMEWORK.md",
-    "src/components",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "typecheck": "tsc --noEmit",
-    "cli": "node ./dist/src/cli/index.js"
-  },
-  "keywords": [
-    "praxis",
-    "framework",
-    "plures",
-    "logic",
-    "schema",
-    "component-generation",
-    "local-first",
-    "functional",
-    "typescript",
-    "state-management",
-    "facts",
-    "rules",
-    "constraints",
-    "orchestration",
-    "canvas",
-    "visual-development"
-  ],
-  "author": "Plures",
-  "license": "MIT",
-  "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^6.2.1",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.0.1",
-    "@types/ws": "^8.18.1",
-    "@vitest/ui": "^4.0.15",
-    "esbuild-svelte": "^0.9.4",
-    "svelte": "^5.46.0",
-    "svelte-preprocess": "^6.0.3",
-    "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.2.7",
-    "vitest": "^4.0.15"
-  },
-  "dependencies": {
-    "commander": "^14.0.2",
-    "js-yaml": "^4.1.1"
-  },
-  "peerDependencies": {
-    "svelte": "^5.46.0"
-  },
-  "peerDependenciesMeta": {
-    "svelte": {
-      "optional": true
-    }
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@plures/praxis",
+  "version": "1.1.2",
+  "description": "The Full Plures Application Framework - declarative schemas, logic engine, component generation, and local-first data",
+  "type": "module",
+  "main": "./dist/node/index.js",
+  "types": "./dist/node/index.d.ts",
+  "bin": {
+    "praxis": "./dist/node/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./dist/node/index.d.ts",
+        "import": "./dist/node/index.js",
+        "require": "./dist/node/index.cjs"
+      },
+      "browser": {
+        "types": "./dist/browser/index.d.ts",
+        "import": "./dist/browser/index.js"
+      },
+      "default": "./dist/node/index.js"
+    },
+    "./svelte": {
+      "node": {
+        "types": "./dist/node/integrations/svelte.d.ts",
+        "import": "./dist/node/integrations/svelte.js",
+        "require": "./dist/node/integrations/svelte.cjs"
+      },
+      "browser": {
+        "types": "./dist/browser/integrations/svelte.d.ts",
+        "import": "./dist/browser/integrations/svelte.js"
+      },
+      "default": "./dist/node/integrations/svelte.js"
+    },
+    "./schema": {
+      "types": "./dist/node/schema.d.ts",
+      "import": "./dist/node/schema.js",
+      "require": "./dist/node/schema.cjs",
+      "default": "./dist/node/schema.js"
+    },
+    "./component": {
+      "types": "./dist/node/component.d.ts",
+      "import": "./dist/node/component.js",
+      "require": "./dist/node/component.cjs",
+      "default": "./dist/node/component.js"
+    },
+    "./cloud": {
+      "types": "./dist/node/cloud/index.d.ts",
+      "import": "./dist/node/cloud/index.js",
+      "require": "./dist/node/cloud/index.cjs",
+      "default": "./dist/node/cloud/index.js"
+    },
+    "./components": {
+      "types": "./dist/node/components/index.d.ts",
+      "svelte": "./src/components/TerminalNode.svelte",
+      "import": "./dist/node/components/index.js",
+      "require": "./dist/node/components/index.cjs",
+      "default": "./dist/node/components/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "core",
+    "cli",
+    "templates",
+    "docs",
+    "README.md",
+    "FRAMEWORK.md",
+    "src/components",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "typecheck": "tsc --noEmit",
+    "cli": "node ./dist/src/cli/index.js"
+  },
+  "keywords": [
+    "praxis",
+    "framework",
+    "plures",
+    "logic",
+    "schema",
+    "component-generation",
+    "local-first",
+    "functional",
+    "typescript",
+    "state-management",
+    "facts",
+    "rules",
+    "constraints",
+    "orchestration",
+    "canvas",
+    "visual-development"
+  ],
+  "author": "Plures",
+  "license": "MIT",
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^6.2.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.0.1",
+    "@types/ws": "^8.18.1",
+    "@vitest/ui": "^4.0.15",
+    "esbuild-svelte": "^0.9.4",
+    "svelte": "^5.46.0",
+    "svelte-preprocess": "^6.0.3",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.7",
+    "vitest": "^4.0.15"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "js-yaml": "^4.1.1"
+  },
+  "peerDependencies": {
+    "svelte": "^5.46.0"
+  },
+  "peerDependenciesMeta": {
+    "svelte": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}