@plures/praxis 1.1.1 → 1.1.3

package/README.md

@@ -1,6 +1,6 @@
 dotnet build
 dotnet test
-# Praxis 1.1.0
+# Praxis
 
 **Typed, visual-first application logic for Svelte, Node, and the browser.**
 
@@ -10,19 +10,20 @@ dotnet test
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 [![Deno Compatible](https://img.shields.io/badge/deno-compatible-brightgreen)](https://deno.land/)
 
-Praxis is a schema-driven, rule-based engine with first-class Svelte 5 integration, component generation, and optional cloud sync. Version **1.1.0** delivers a unified ESM/CJS build, curated subpath exports, Svelte runes support, and a slimmer, publish-ready package for npm and JSR.
+Praxis is a schema-driven, rule-based engine with first-class Svelte 5 integration, component generation, and optional cloud sync. The library delivers a unified ESM/CJS build, curated subpath exports, Svelte runes support, and a slimmer, publish-ready package for npm and JSR.
 
 ---
 
-## What’s new in 1.1.0
+## What’s new
 - **Unified builds & exports**: `./`, `./svelte`, `./schema`, `./component`, `./cloud`, `./components`, and CLI all ship with ESM, CJS, and type definitions.
 - **Svelte 5 runes native**: Runes-friendly stores and helpers; server+client builds for integrations.
+- **Framework-agnostic reactivity**: Proxy-based reactive engine for use without Svelte, enabling reactive state management in Node.js, browsers, and any JavaScript environment.
 - **Logic engine refinements**: Typed registry, step diagnostics, and trace-friendly rule execution.
 - **Cloud relay & local-first**: Polished cloud connector alongside PluresDB-first workflows.
 - **Publish-ready**: npm public access + JSR exports aligned to source.
 
 ## Capabilities at a glance
-- **Logic Engine**: Facts, events, rules, constraints, registry, introspection, and reactive engine variant.
+- **Logic Engine**: Facts, events, rules, constraints, registry, introspection, and reactive engine variants (Svelte 5 + framework-agnostic).
 - **Schema & Codegen**: PSF-style schema types plus component generator for Svelte UIs.
 - **Svelte Integration**: Typed helpers, runes-ready builds, and Svelte component typings.
 - **Local-First Data**: PluresDB integrations for offline-first, reactive state.
@@ -45,7 +46,7 @@ JSR (Deno):
 const result = engine.step([Login.create({ username: 'alice' })]);
 # or via import map pointing to npm:
 # {
-#   "imports": { "@plures/praxis": "npm:@plures/praxis@^1.1.0" }
+#   "imports": { "@plures/praxis": "npm:@plures/praxis@^1.1.2" }
 # }
 ```
 
@@ -100,16 +101,47 @@ engine.step([Login.create({ username: 'alex' })]);
   registry.registerRule(counterRule);
 
   const engine = createReactiveEngine({ initialContext: { count: 0 }, registry });
-  const count = engine.$derived((s) => s.context.count);
+  
+  // Use Svelte's $derived with the reactive engine state
+  const count = $derived(engine.context.count);
 
   function addOne() {
     engine.step([Increment.create({ amount: 1 })]);
   }
 </script>
 
-<button on:click={addOne}>Count is {$count}</button>
+<button on:click={addOne}>Count is {count}</button>
 ```
 
+## Framework-agnostic reactive engine
+For non-Svelte environments, use the framework-agnostic reactive engine with Proxy-based reactivity:
+
+```typescript
+import { createFrameworkAgnosticReactiveEngine } from '@plures/praxis';
+
+const engine = createFrameworkAgnosticReactiveEngine({
+  initialContext: { count: 0 },
+});
+
+// Subscribe to state changes
+engine.subscribe((state) => {
+  console.log('Count:', state.context.count);
+});
+
+// Create derived/computed values
+const doubled = engine.$derived((state) => state.context.count * 2);
+doubled.subscribe((value) => {
+  console.log('Doubled:', value);
+});
+
+// Apply mutations (batched for performance)
+engine.apply((state) => {
+  state.context.count += 1;
+});
+```
+
+See the [reactive counter example](./examples/reactive-counter/README.md) for a complete demonstration.
+
 ## Cloud relay (optional)
 ```ts
 import { connectRelay } from '@plures/praxis/cloud';
@@ -129,6 +161,35 @@ await relay.sync({
 });
 ```
 
+## PluresDB integration
+```ts
+import { PluresNode } from 'pluresdb';
+import { createPluresDB, createPraxisDBStore } from '@plures/praxis';
+import { PraxisRegistry } from '@plures/praxis';
+
+// Initialize the official PluresDB from npm
+const pluresdb = new PluresNode({
+  config: {
+    port: 34567,
+    dataDir: './data',
+  },
+  autoStart: true,
+});
+
+// Wrap it with the Praxis adapter
+const db = createPluresDB(pluresdb);
+
+// Use with Praxis store for local-first reactive data
+const registry = new PraxisRegistry();
+const store = createPraxisDBStore(db, registry);
+
+// Or use in-memory database for development/testing
+import { createInMemoryDB } from '@plures/praxis';
+const devDb = createInMemoryDB();
+```
+
+> **Note:** Praxis now uses the official [PluresDB package from NPM](https://www.npmjs.com/package/pluresdb), which provides P2P sync, CRDT conflict resolution, SQLite compatibility, and more. The `createPluresDB()` function wraps PluresDB to provide the `PraxisDB` interface used by Praxis.
+
 ## CLI (npx-friendly)
 ```bash
 npx praxis --help

package/dist/browser/chunk-R45WXWKH.js

@@ -0,0 +1,345 @@
+// src/core/protocol.ts
+var PRAXIS_PROTOCOL_VERSION = "1.0.0";
+
+// src/core/rules.ts
+var PraxisRegistry = class {
+  rules = /* @__PURE__ */ new Map();
+  constraints = /* @__PURE__ */ new Map();
+  /**
+   * Register a rule
+   */
+  registerRule(descriptor) {
+    if (this.rules.has(descriptor.id)) {
+      throw new Error(`Rule with id "${descriptor.id}" already registered`);
+    }
+    this.rules.set(descriptor.id, descriptor);
+  }
+  /**
+   * Register a constraint
+   */
+  registerConstraint(descriptor) {
+    if (this.constraints.has(descriptor.id)) {
+      throw new Error(`Constraint with id "${descriptor.id}" already registered`);
+    }
+    this.constraints.set(descriptor.id, descriptor);
+  }
+  /**
+   * Register a module (all its rules and constraints)
+   */
+  registerModule(module) {
+    for (const rule of module.rules) {
+      this.registerRule(rule);
+    }
+    for (const constraint of module.constraints) {
+      this.registerConstraint(constraint);
+    }
+  }
+  /**
+   * Get a rule by ID
+   */
+  getRule(id) {
+    return this.rules.get(id);
+  }
+  /**
+   * Get a constraint by ID
+   */
+  getConstraint(id) {
+    return this.constraints.get(id);
+  }
+  /**
+   * Get all registered rule IDs
+   */
+  getRuleIds() {
+    return Array.from(this.rules.keys());
+  }
+  /**
+   * Get all registered constraint IDs
+   */
+  getConstraintIds() {
+    return Array.from(this.constraints.keys());
+  }
+  /**
+   * Get all rules
+   */
+  getAllRules() {
+    return Array.from(this.rules.values());
+  }
+  /**
+   * Get all constraints
+   */
+  getAllConstraints() {
+    return Array.from(this.constraints.values());
+  }
+};
+
+// src/core/engine.ts
+function safeClone(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (typeof globalThis.structuredClone === "function") {
+    try {
+      return globalThis.structuredClone(value);
+    } catch {
+    }
+  }
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  return { ...value };
+}
+var LogicEngine = class {
+  state;
+  registry;
+  constructor(options) {
+    this.registry = options.registry;
+    this.state = {
+      context: options.initialContext,
+      facts: options.initialFacts ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+  /**
+   * Get the current state (immutable copy)
+   */
+  getState() {
+    return {
+      context: safeClone(this.state.context),
+      facts: [...this.state.facts],
+      meta: this.state.meta ? safeClone(this.state.meta) : void 0,
+      protocolVersion: this.state.protocolVersion
+    };
+  }
+  /**
+   * Get the current context
+   */
+  getContext() {
+    return safeClone(this.state.context);
+  }
+  /**
+   * Get current facts
+   */
+  getFacts() {
+    return [...this.state.facts];
+  }
+  /**
+   * Process events through the engine.
+   * Applies all registered rules and checks all registered constraints.
+   *
+   * @param events Events to process
+   * @returns Result with new state and diagnostics
+   */
+  step(events) {
+    const config = {
+      ruleIds: this.registry.getRuleIds(),
+      constraintIds: this.registry.getConstraintIds()
+    };
+    return this.stepWithConfig(events, config);
+  }
+  /**
+   * Process events with specific rule and constraint configuration.
+   *
+   * @param events Events to process
+   * @param config Step configuration
+   * @returns Result with new state and diagnostics
+   */
+  stepWithConfig(events, config) {
+    const diagnostics = [];
+    let newState = { ...this.state };
+    const newFacts = [];
+    for (const ruleId of config.ruleIds) {
+      const rule = this.registry.getRule(ruleId);
+      if (!rule) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Rule "${ruleId}" not found in registry`,
+          data: { ruleId }
+        });
+        continue;
+      }
+      try {
+        const ruleFacts = rule.impl(newState, events);
+        newFacts.push(...ruleFacts);
+      } catch (error) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Error executing rule "${ruleId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { ruleId, error }
+        });
+      }
+    }
+    newState = {
+      ...newState,
+      facts: [...newState.facts, ...newFacts]
+    };
+    for (const constraintId of config.constraintIds) {
+      const constraint = this.registry.getConstraint(constraintId);
+      if (!constraint) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Constraint "${constraintId}" not found in registry`,
+          data: { constraintId }
+        });
+        continue;
+      }
+      try {
+        const result = constraint.impl(newState);
+        if (result === false) {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: `Constraint "${constraintId}" violated`,
+            data: { constraintId, description: constraint.description }
+          });
+        } else if (typeof result === "string") {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: result,
+            data: { constraintId, description: constraint.description }
+          });
+        }
+      } catch (error) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Error checking constraint "${constraintId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { constraintId, error }
+        });
+      }
+    }
+    this.state = newState;
+    return {
+      state: newState,
+      diagnostics
+    };
+  }
+  /**
+   * Update the context directly (for exceptional cases).
+   * Generally, context should be updated through rules.
+   *
+   * @param updater Function that produces new context from old context
+   */
+  updateContext(updater) {
+    this.state = {
+      ...this.state,
+      context: updater(this.state.context)
+    };
+  }
+  /**
+   * Add facts directly (for exceptional cases).
+   * Generally, facts should be added through rules.
+   *
+   * @param facts Facts to add
+   */
+  addFacts(facts) {
+    this.state = {
+      ...this.state,
+      facts: [...this.state.facts, ...facts]
+    };
+  }
+  /**
+   * Clear all facts
+   */
+  clearFacts() {
+    this.state = {
+      ...this.state,
+      facts: []
+    };
+  }
+  /**
+   * Reset the engine to initial state
+   */
+  reset(options) {
+    this.state = {
+      context: options.initialContext,
+      facts: options.initialFacts ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+};
+function createPraxisEngine(options) {
+  return new LogicEngine(options);
+}
+
+// src/core/reactive-engine.svelte.ts
+import * as $ from "svelte/internal/client";
+var ReactiveLogicEngine = class {
+  #state = (
+    // Use Svelte's $state rune for automatic reactivity
+    $.state($.proxy({ context: {}, facts: [], meta: {} }))
+  );
+  get state() {
+    return $.get(this.#state);
+  }
+  set state(value) {
+    $.set(this.#state, value, true);
+  }
+  _engine;
+  constructor(options) {
+    this.state.context = options.initialContext;
+    this.state.facts = options.initialFacts ?? [];
+    this.state.meta = options.initialMeta ?? {};
+    if (options.registry) {
+      this._engine = createPraxisEngine({
+        initialContext: options.initialContext,
+        registry: options.registry
+      });
+    } else {
+      this._engine = createPraxisEngine({
+        initialContext: options.initialContext,
+        registry: new PraxisRegistry()
+      });
+    }
+  }
+  /**
+   * Access the reactive context.
+   * In Svelte 5 components, changes to this object will automatically trigger updates.
+   */
+  get context() {
+    return this.state.context;
+  }
+  /**
+   * Access the reactive facts list.
+   */
+  get facts() {
+    return this.state.facts;
+  }
+  /**
+   * Access the reactive metadata.
+   */
+  get meta() {
+    return this.state.meta;
+  }
+  /**
+   * Apply a mutation to the state.
+   * Changes will automatically trigger Svelte reactivity.
+   * 
+   * @param mutator A function that receives the state and modifies it.
+   */
+  apply(mutator) {
+    mutator(this.state);
+  }
+  /**
+   * Process events through the logic engine and update reactive state.
+   * 
+   * @param events Events to process
+   */
+  step(events) {
+    const result = this._engine.step(events);
+    this.state.context = result.state.context;
+    this.state.facts = result.state.facts;
+    this.state.meta = result.state.meta ?? {};
+  }
+};
+function createReactiveEngine(options) {
+  return new ReactiveLogicEngine(options);
+}
+
+export {
+  PRAXIS_PROTOCOL_VERSION,
+  PraxisRegistry,
+  LogicEngine,
+  createPraxisEngine,
+  ReactiveLogicEngine,
+  createReactiveEngine
+};