@plures/praxis 1.0.3 → 1.1.0

package/docs/MONETIZATION.md

@@ -40,6 +40,7 @@ Praxis Cloud uses GitHub as the exclusive authentication and billing provider, a
 ## Subscription Tiers
 
 ### Free Tier
+
 - **Cost**: Free
 - **Limits**:
   - 1,000 syncs/month
@@ -48,6 +49,7 @@ Praxis Cloud uses GitHub as the exclusive authentication and billing provider, a
   - Community support
 
 ### Solo Tier ($5/month via GitHub Sponsors)
+
 - **Limits**:
   - 50,000 syncs/month
   - 1 GB storage
@@ -55,6 +57,7 @@ Praxis Cloud uses GitHub as the exclusive authentication and billing provider, a
   - Standard support
 
 ### Team Tier ($20/month via GitHub Sponsors)
+
 - **Limits**:
   - 500,000 syncs/month
   - 10 GB storage
@@ -63,6 +66,7 @@ Praxis Cloud uses GitHub as the exclusive authentication and billing provider, a
   - Standard support
 
 ### Enterprise Tier ($50/month via GitHub Sponsors/Marketplace)
+
 - **Limits**:
   - 5,000,000 syncs/month
   - 100 GB storage
@@ -102,9 +106,9 @@ praxis logout
 ### 3. Programmatic Authentication
 
 ```typescript
-import { authenticateWithDeviceFlow } from "@plures/praxis/cloud";
+import { authenticateWithDeviceFlow } from '@plures/praxis/cloud';
 
-const result = await authenticateWithDeviceFlow("YOUR_CLIENT_ID");
+const result = await authenticateWithDeviceFlow('YOUR_CLIENT_ID');
 if (result.success) {
   console.log(`Authenticated as ${result.user?.login}`);
   console.log(`Token: ${result.token}`);
@@ -153,10 +157,10 @@ PRAXIS_APP_ID=your_app_id
 ### Checking Subscription Status
 
 ```typescript
-import { createSponsorsClient } from "@plures/praxis/cloud";
+import { createSponsorsClient } from '@plures/praxis/cloud';
 
 const client = createSponsorsClient(githubToken);
-const subscription = await client.getSubscription("username");
+const subscription = await client.getSubscription('username');
 
 console.log(`Tier: ${subscription.tier}`);
 console.log(`Status: ${subscription.status}`);
@@ -199,21 +203,21 @@ See `github/marketplace/` for listing templates and screenshots.
 ### Webhook Handler
 
 ```typescript
-import { createMarketplaceClient } from "@plures/praxis/cloud";
+import { createMarketplaceClient } from '@plures/praxis/cloud';
 
 const client = createMarketplaceClient(githubToken);
 
 // Handle webhook event
-app.post("/webhook/marketplace", (req, res) => {
+app.post('/webhook/marketplace', (req, res) => {
   const event = req.body;
   const result = client.handleWebhookEvent(event);
-  
+
   if (result) {
     // Provision or update tenant
     console.log(`User ${result.userLogin} subscribed to ${result.subscription.tier}`);
   }
-  
-  res.status(200).send("OK");
+
+  res.status(200).send('OK');
 });
 ```
 
@@ -224,7 +228,7 @@ app.post("/webhook/marketplace", (req, res) => {
 When a user authenticates, a tenant is automatically provisioned:
 
 ```typescript
-import { provisionTenant, createTenant } from "@plures/praxis/cloud";
+import { provisionTenant, createTenant } from '@plures/praxis/cloud';
 
 const result = await provisionTenant(githubUser, subscription);
 
@@ -248,7 +252,7 @@ Storage namespaces follow Azure Blob Storage naming rules:
 Access to cloud features is controlled by subscription tier:
 
 ```typescript
-import { hasAccessToTier, SubscriptionTier } from "@plures/praxis/cloud";
+import { hasAccessToTier, SubscriptionTier } from '@plures/praxis/cloud';
 
 if (hasAccessToTier(subscription, SubscriptionTier.TEAM)) {
   // Allow team features
@@ -264,6 +268,7 @@ praxis cloud usage
 ```
 
 Output:
+
 ```
 App ID: my-app
 
@@ -279,7 +284,7 @@ Period: 720.0 hours
 ### Enforcing Limits
 
 ```typescript
-import { checkUsageLimits } from "@plures/praxis/cloud";
+import { checkUsageLimits } from '@plures/praxis/cloud';
 
 const result = checkUsageLimits(subscription, {
   syncCount: 1500,
@@ -289,8 +294,8 @@ const result = checkUsageLimits(subscription, {
 });
 
 if (!result.withinLimits) {
-  console.error("Usage limits exceeded:");
-  result.violations.forEach(v => console.error(`  - ${v}`));
+  console.error('Usage limits exceeded:');
+  result.violations.forEach((v) => console.error(`  - ${v}`));
 }
 ```
 
@@ -307,7 +312,7 @@ Authentication tokens are stored securely:
 ### Best Practices
 
 1. **Never commit tokens** to source control
-2. **Rotate tokens regularly** 
+2. **Rotate tokens regularly**
 3. **Use environment variables** for CI/CD
 4. **Revoke tokens** when no longer needed
 5. **Use GitHub App tokens** for production services
@@ -335,7 +340,7 @@ For tests, use mock responses:
 
 ```typescript
 // Mock GitHub API
-vi.mock("../cloud/sponsors.js", () => ({
+vi.mock('../cloud/sponsors.js', () => ({
   createSponsorsClient: vi.fn(() => ({
     getSubscription: vi.fn(async () => ({
       tier: SubscriptionTier.SOLO,

package/docs/REACTIVE_REDESIGN.md

@@ -0,0 +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).
+

package/docs/README.md

@@ -21,47 +21,47 @@ npm run dev
 
 ### Core Concepts
 
-| Document | Description |
-|----------|-------------|
-| [What is Praxis](./core/what-is-praxis.md) | Overview of Praxis and its core philosophy |
-| [Schema Model](./core/schema-model.md) | Understanding the Praxis Schema Format (PSF) |
-| [Logic Engine](./core/logic-engine.md) | Facts, events, rules, and constraints |
-| [UI Generation](./core/ui-generation.md) | Automatic component generation from schemas |
-| [PluresDB Integration](./core/pluresdb-integration.md) | Local-first data with reactive storage |
-| [Code ↔ Canvas Sync](./core/code-canvas-sync.md) | Bidirectional synchronization |
-| [CLI Usage](./core/cli-usage.md) | Command-line interface reference |
-| [Building Extensions](./core/building-extensions.md) | Extending Praxis functionality |
+| Document                                               | Description                                  |
+| ------------------------------------------------------ | -------------------------------------------- |
+| [What is Praxis](./core/what-is-praxis.md)             | Overview of Praxis and its core philosophy   |
+| [Schema Model](./core/schema-model.md)                 | Understanding the Praxis Schema Format (PSF) |
+| [Logic Engine](./core/logic-engine.md)                 | Facts, events, rules, and constraints        |
+| [UI Generation](./core/ui-generation.md)               | Automatic component generation from schemas  |
+| [PluresDB Integration](./core/pluresdb-integration.md) | Local-first data with reactive storage       |
+| [Code ↔ Canvas Sync](./core/code-canvas-sync.md)      | Bidirectional synchronization                |
+| [CLI Usage](./core/cli-usage.md)                       | Command-line interface reference             |
+| [Building Extensions](./core/building-extensions.md)   | Extending Praxis functionality               |
 
 ### Guides
 
-| Guide | Description |
-|-------|-------------|
-| [Getting Started](./guides/getting-started.md) | First steps with Praxis |
-| [Svelte Integration](./guides/svelte-integration.md) | Using Praxis with Svelte 5 |
-| [Canvas](./guides/canvas.md) | Visual development with CodeCanvas |
+| Guide                                                         | Description                         |
+| ------------------------------------------------------------- | ----------------------------------- |
+| [Getting Started](./guides/getting-started.md)                | First steps with Praxis             |
+| [Svelte Integration](./guides/svelte-integration.md)          | Using Praxis with Svelte 5          |
+| [Canvas](./guides/canvas.md)                                  | Visual development with CodeCanvas  |
 | [History & State Patterns](./guides/history-state-pattern.md) | Undo/redo and time-travel debugging |
-| [Parallel State Patterns](./guides/parallel-state-pattern.md) | Managing parallel state machines |
-| [Orchestration](./guides/orchestration.md) | Distributed system coordination |
+| [Parallel State Patterns](./guides/parallel-state-pattern.md) | Managing parallel state machines    |
+| [Orchestration](./guides/orchestration.md)                    | Distributed system coordination     |
 
 ### Tutorials
 
-| Tutorial | Description |
-|----------|-------------|
-| [Build Your First App](./tutorials/first-app.md) | Step-by-step beginner tutorial |
-| [Todo with PluresDB](./tutorials/todo-pluresdb.md) | Local-first todo application |
-| [Form Builder](./tutorials/form-builder.md) | Dynamic form creation |
-| [E-commerce Cart](./tutorials/ecommerce-cart.md) | Shopping cart with checkout flow |
+| Tutorial                                           | Description                      |
+| -------------------------------------------------- | -------------------------------- |
+| [Build Your First App](./tutorials/first-app.md)   | Step-by-step beginner tutorial   |
+| [Todo with PluresDB](./tutorials/todo-pluresdb.md) | Local-first todo application     |
+| [Form Builder](./tutorials/form-builder.md)        | Dynamic form creation            |
+| [E-commerce Cart](./tutorials/ecommerce-cart.md)   | Shopping cart with checkout flow |
 
 ### Examples
 
-| Example | Description |
-|---------|-------------|
-| [Hero Shop](../examples/hero-shop/) | Full e-commerce application |
-| [Todo](../examples/todo/) | Minimal todo application |
-| [Form Builder](../examples/form-builder/) | Dynamic form builder |
-| [Offline Chat](../examples/offline-chat/) | Local-first chat application |
-| [Terminal Node](../examples/terminal-node/) | Self-orchestrating node |
-| [Cloud Sync](../examples/cloud-sync/) | Multi-client synchronization |
+| Example                                     | Description                  |
+| ------------------------------------------- | ---------------------------- |
+| [Hero Shop](../examples/hero-shop/)         | Full e-commerce application  |
+| [Todo](../examples/todo/)                   | Minimal todo application     |
+| [Form Builder](../examples/form-builder/)   | Dynamic form builder         |
+| [Offline Chat](../examples/offline-chat/)   | Local-first chat application |
+| [Terminal Node](../examples/terminal-node/) | Self-orchestrating node      |
+| [Cloud Sync](../examples/cloud-sync/)       | Multi-client synchronization |
 
 ## Architecture Overview
 
@@ -70,27 +70,27 @@ flowchart TB
     subgraph Schema["Schema Layer"]
         PSF[Praxis Schema Format]
     end
-    
+
     subgraph Generation["Code Generation"]
         PSF --> Types[TypeScript Types]
         PSF --> Components[Svelte Components]
         PSF --> Logic[Logic Engine]
         PSF --> Docs[Documentation]
     end
-    
+
     subgraph Runtime["Runtime"]
         Logic --> Engine[Praxis Engine]
         Components --> UI[User Interface]
         Engine <--> PluresDB[(PluresDB)]
         Engine <--> Cloud[Praxis Cloud]
     end
-    
+
     subgraph Tools["Development Tools"]
         Canvas[CodeCanvas]
         CLI[Praxis CLI]
         StateDocs[State-Docs]
     end
-    
+
     Canvas <--> PSF
     CLI --> Generation
     Engine --> StateDocs
@@ -99,42 +99,53 @@ flowchart TB
 ## Key Features
 
 ### 🎯 Schema-Driven Development
+
 Define your entire application in PSF (Praxis Schema Format), then generate everything else.
 
 ### ⚡ Logic Engine
+
 Pure, functional business logic with facts, events, rules, and constraints.
 
 ### 🧩 Component Generation
+
 Automatically generate Svelte components from your schemas.
 
 ### 📱 Local-First
+
 Built-in PluresDB integration for offline-capable, reactive data storage.
 
 ### 🎨 Visual Development
+
 CodeCanvas provides visual schema and logic editing.
 
 ### 📚 Auto-Documentation
+
 State-Docs generates documentation automatically from schemas.
 
 ### 🌐 Cross-Platform
+
 Deploy to web, desktop (Tauri), and mobile from a single codebase.
 
 ### 🔄 Real-Time Sync
+
 Praxis Cloud provides sync across devices and users.
 
 ## Installation Options
 
 ### npm
+
 ```bash
 npm install @plures/praxis
 ```
 
 ### Deno
+
 ```typescript
-import { createPraxisEngine } from "jsr:@plures/praxis";
+import { createPraxisEngine } from 'jsr:@plures/praxis';
 ```
 
 ### C# (.NET)
+
 ```bash
 dotnet add package Plures.Praxis
 ```

package/docs/SVELTE_INTEGRATION_STRATEGY.md

@@ -0,0 +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.

package/docs/TERMINAL_NODE.md

@@ -57,8 +57,8 @@ const schema: PraxisSchema = {
 ### YAML
 
 ```yaml
-version: "1.0.0"
-name: "MyApp"
+version: '1.0.0'
+name: 'MyApp'
 orchestration:
   type: custom
   nodes:
@@ -129,10 +129,10 @@ const terminal = createTerminalAdapter({
 // Execute a command
 const result = await terminal.executeCommand('echo "Hello World"');
 
-console.log(result.command);    // 'echo "Hello World"'
-console.log(result.output);     // Command output (currently stubbed)
-console.log(result.exitCode);   // 0 for success
-console.log(result.timestamp);  // Execution timestamp
+console.log(result.command); // 'echo "Hello World"'
+console.log(result.output); // Command output (currently stubbed)
+console.log(result.exitCode); // 0 for success
+console.log(result.timestamp); // Execution timestamp
 ```
 
 ### Managing Command History
@@ -201,16 +201,16 @@ import TerminalNode from '@plures/praxis/components/TerminalNode.svelte';
 
 **Props:**
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `adapter` | `TerminalAdapter` | required | Terminal adapter instance |
-| `x` | `number` | `0` | X position on canvas |
-| `y` | `number` | `0` | Y position on canvas |
-| `width` | `number` | `600` | Component width in pixels |
-| `height` | `number` | `400` | Component height in pixels |
-| `draggable` | `boolean` | `true` | Enable drag to move |
-| `resizable` | `boolean` | `true` | Enable resize handle |
-| `showContextMenu` | `boolean` | `false` | Show context menu |
+| Prop              | Type              | Default  | Description                |
+| ----------------- | ----------------- | -------- | -------------------------- |
+| `adapter`         | `TerminalAdapter` | required | Terminal adapter instance  |
+| `x`               | `number`          | `0`      | X position on canvas       |
+| `y`               | `number`          | `0`      | Y position on canvas       |
+| `width`           | `number`          | `600`    | Component width in pixels  |
+| `height`          | `number`          | `400`    | Component height in pixels |
+| `draggable`       | `boolean`         | `true`   | Enable drag to move        |
+| `resizable`       | `boolean`         | `true`   | Enable resize handle       |
+| `showContextMenu` | `boolean`         | `false`  | Show context menu          |
 
 **Features:**
 
@@ -347,19 +347,19 @@ The main class for managing terminal node runtime behavior.
 ```typescript
 class TerminalAdapter {
   constructor(options: TerminalAdapterOptions);
-  
+
   /** Execute a terminal command */
   executeCommand(command: string): Promise<TerminalExecutionResult>;
-  
+
   /** Get current terminal state */
   getState(): Readonly<TerminalNodeState>;
-  
+
   /** Update terminal props */
   updateProps(props: Partial<TerminalNodeProps>): void;
-  
+
   /** Clear command history */
   clearHistory(): void;
-  
+
   /** Get command history */
   getHistory(): ReadonlyArray<string>;
 }
@@ -441,7 +441,7 @@ const terminal = createTerminalAdapter({
 });
 
 await terminal.executeCommand('echo "New session"');
-console.log(terminal.getHistory()); 
+console.log(terminal.getHistory());
 // ['echo "Previous session"', 'echo "New session"']
 ```
 
@@ -469,8 +469,8 @@ Terminal nodes support PluresDB bindings for reactive state management:
 ```typescript
 const terminal = createTerminalAdapter({
   nodeId: 'reactive-terminal',
-  inputPath: '/app/terminal/input',   // Listen for commands
-  outputPath: '/app/terminal/output',  // Publish results
+  inputPath: '/app/terminal/input', // Listen for commands
+  outputPath: '/app/terminal/output', // Publish results
 });
 
 // When implemented, commands from inputPath will be auto-executed
@@ -521,6 +521,7 @@ Visual terminal component for Praxis Canvas is now available! Use the `TerminalN
 ```
 
 **Component Features:**
+
 - Drag and drop positioning
 - Resizable dimensions
 - Context menu operations
@@ -540,6 +541,7 @@ npm test
 ```
 
 Tests cover:
+
 - Schema validation with various configurations
 - YAML and JSON loading
 - Terminal adapter creation and configuration
@@ -580,6 +582,7 @@ To adopt terminal nodes:
 ## Support
 
 For questions, issues, or feature requests:
+
 - GitHub Issues: https://github.com/plures/praxis/issues
 - Documentation: https://github.com/plures/praxis/tree/main/docs