@plures/praxis 1.1.2 → 1.2.0

package/FRAMEWORK.md

@@ -143,28 +143,104 @@ PluresDB provides the data storage and synchronization layer.
 - Logic engine fact/event storage
 - Component data binding
 - Distributed state management
+- CRDT-based synchronization
+- Event sourcing and replay
 
-### 5. Visual IDE (CodeCanvas Integration)
+**Status**: ✅ Fully implemented with comprehensive test coverage
 
-CodeCanvas provides visual development capabilities.
+### 5. Identity & Channels (Unum Integration)
+
+Unum provides identity management and channel-based communication for distributed systems.
 
 **Features:**
 
-- Visual schema editor
-- Logic flow designer
-- Component preview
-- Orchestrator visualization
-- Documentation navigation
+- Identity creation and management
+- Channel-based messaging
+- Event and fact broadcasting
+- Member management
+- Real-time synchronization with PluresDB
+
+**Use Cases:**
+
+- Multi-user collaboration
+- Distributed event streaming
+- Node-to-node communication
+- Identity-based access control
+- Real-time state synchronization
+
+**Integration Points:**
+
+- Praxis event broadcasting to channels
+- Fact synchronization across nodes
+- PluresDB backend for persistence
+- Engine attachment for automatic distribution
+
+**Status**: ✅ Fully implemented with comprehensive API
+
+### 6. Documentation (State-Docs Integration)
+
+State-Docs generates living documentation from Praxis schemas and logic definitions.
+
+**Features:**
+
+- Auto-generated Markdown documentation
+- Mermaid and DOT diagram generation
+- Model and component catalogs
+- Logic flow visualization
+- Event → Rule → Fact diagrams
+- Customizable templates
+
+**Use Cases:**
+
+- API documentation
+- Architecture diagrams
+- Onboarding documentation
+- Design reviews
+- GitHub Pages integration
+
+**Integration Points:**
+
+- Schema documentation generation
+- Registry introspection
+- Automatic ToC and index generation
+- Diagram export (Mermaid, DOT)
+
+**Status**: ✅ Fully implemented with CLI support (`praxis docs`)
+
+### 7. Visual IDE (CodeCanvas Integration)
+
+CodeCanvas provides visual development capabilities for schemas and logic flows.
+
+**Features:**
+
+- Visual schema editor with node-based UI
+- Schema ↔ Canvas bi-directional sync
+- Mermaid and YAML export
+- Obsidian Canvas compatibility
+- FSM visualization
+- Guardian pre-commit validation
+- Activity lifecycle tracking
 
 **Use Cases:**
 
 - Design schemas visually
-- Build logic flows with drag-and-drop
-- Preview generated components
-- Visualize distributed orchestration
-- Navigate living documentation
+- Build logic flows with visual tools
+- Export schemas to diagrams
+- Integrate with Obsidian workflows
+- Visualize state machines
+- Enforce development lifecycle
 
-### 6. Orchestration (DSC/MCP Support)
+**Integration Points:**
+
+- Schema conversion (`schemaToCanvas`)
+- Canvas export (YAML, Mermaid, JSON)
+- Visual editor API
+- FSM lifecycle management
+- Guardian validation hooks
+
+**Status**: ✅ Fully implemented with CLI support (`praxis canvas`)
+
+### 8. Orchestration (DSC/MCP Support)
 
 Support for distributed system coordination.
 
@@ -213,17 +289,32 @@ Generate code from schemas.
 
 Options:
 
-- `--target`: Generation target (components, models, docs, all)
+- `--target`: Generation target (components, models, pluresdb, docs, all)
 - `--watch`: Watch for schema changes
+- `--auto-index`: Auto-indexing strategy for PluresDB
+
+#### `praxis docs [schema]`
+
+Generate documentation from schemas or registries.
+
+Options:
+
+- `--output`: Output directory (default: ./docs)
+- `--title`: Documentation title
+- `--format`: Diagram format (mermaid, dot)
+- `--no-toc`: Disable table of contents
+- `--from-registry`: Generate from registry instead of schema
 
 #### `praxis canvas [schema]`
 
-Open CodeCanvas for visual editing.
+Open CodeCanvas for visual editing or export schemas to canvas formats.
 
 Options:
 
-- `--port`: Port for Canvas server
+- `--port`: Port for Canvas server (default: 3000)
 - `--mode`: Mode (edit, view, present)
+- `--export`: Export format (yaml, mermaid, json)
+- `--output`: Output file for export
 
 #### `praxis orchestrate`
 

package/README.md

@@ -1,6 +1,6 @@
 dotnet build
 dotnet test
-# Praxis 1.1.2
+# Praxis
 
 **Typed, visual-first application logic for Svelte, Node, and the browser.**
 
@@ -10,24 +10,37 @@ 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.2** delivers a unified ESM/CJS build, curated subpath exports, Svelte runes support, and a slimmer, publish-ready package for npm and JSR.
+Praxis is **the unified solution for declarative application development**, combining:
+
+- **Logic Modeling**: Typed facts, events, rules, and constraints for domain logic
+- **Component Auto-Generation**: Svelte 5 components generated from schemas  
+- **Data Persistence**: PluresDB for local-first, reactive data storage
+- **Documentation**: Auto-generated docs with State-Docs and visual diagrams
+- **Visual Editing**: CodeCanvas for schema design and FSM visualization
+- **Distributed Systems**: Unum for identity and multi-node communication
+
+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.2
+## 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.
+- **Local-First Data**: PluresDB integration for offline-first, reactive state with full persistence.
+- **Distributed Systems**: Unum integration for identity management and multi-node channels.
+- **Documentation**: State-Docs integration for auto-generated Markdown docs and Mermaid diagrams.
+- **Visual Editing**: CodeCanvas integration for visual schema design and FSM visualization.
 - **Cloud Relay**: Optional sync layer (GitHub-auth friendly) for distributed teams.
-- **CLI**: Scaffolding, generation, canvas helpers, and cloud commands.
+- **CLI**: Scaffolding, generation, canvas helpers, docs generation, and cloud commands.
 
 ## Install
 Node 18+ recommended.
@@ -80,6 +93,64 @@ const engine = createPraxisEngine({ initialContext: { currentUser: null }, regis
 engine.step([Login.create({ username: 'alex' })]);
 ```
 
+## Unified workflow example
+
+See all Praxis integrations working together - from schema definition to persistence, documentation, and distributed communication:
+
+```ts
+import {
+  createPraxisEngine,
+  PraxisRegistry,
+  defineRule,
+  createInMemoryDB,
+  createPluresDBAdapter,
+  createUnumAdapter,
+  createStateDocsGenerator,
+  schemaToCanvas,
+} from '@plures/praxis';
+
+// 1. Define logic with Praxis engine
+const registry = new PraxisRegistry();
+registry.registerRule(/* your rules */);
+const engine = createPraxisEngine({ initialContext: {}, registry });
+
+// 2. Add PluresDB for local-first persistence
+const db = createInMemoryDB();
+const pluresAdapter = createPluresDBAdapter({ db, registry });
+pluresAdapter.attachEngine(engine);
+
+// 3. Add Unum for distributed communication
+const unum = await createUnumAdapter({
+  db,
+  identity: { name: 'node-1' },
+  realtime: true,
+});
+const channel = await unum.createChannel('app-sync');
+
+// Subscribe to distribute events across nodes
+unum.subscribeToEvents(channel.id, (event) => {
+  engine.step([event]);
+});
+
+// 4. Generate documentation with State-Docs
+const docsGenerator = createStateDocsGenerator({
+  projectTitle: 'My App',
+  target: './docs',
+});
+const docs = docsGenerator.generateFromModule(registry.module);
+
+// 5. Export schema to CodeCanvas for visual editing
+const canvas = schemaToCanvas(mySchema);
+// Canvas can be edited visually and converted back to schema
+
+// Now you have:
+// ✅ Logic engine running
+// ✅ Auto-persisting to PluresDB
+// ✅ Distributing events across nodes via Unum
+// ✅ Auto-generated documentation
+// ✅ Visual schema representation
+```
+
 ## Svelte integration (runes-ready)
 ```svelte
 <script lang="ts">
@@ -100,16 +171,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 +231,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
@@ -591,32 +722,55 @@ adapter.subscribeToEvents((events) => {
 
 ### Unum Integration
 
-Identity and channels for distributed systems.
+Identity and channels for distributed systems. **Now fully implemented** with comprehensive channel and identity management.
 
 ```typescript
-import { createUnumIdentity, createChannel } from '@plures/unum';
+import {
+  createUnumAdapter,
+  attachUnumToEngine,
+} from '@plures/praxis';
 
-// Create identity
-const identity = await createUnumIdentity({
-  name: 'my-app-node',
-  keys: await generateKeys(),
+// Create Unum adapter with identity
+const unum = await createUnumAdapter({
+  db: pluresDB,
+  identity: {
+    name: 'my-app-node',
+    metadata: { role: 'coordinator' },
+  },
+  realtime: true,
 });
 
-// Create channel for messaging
-const channel = await createChannel({
-  name: 'app-events',
-  participants: [identity.id],
+// Create a channel for messaging
+const channel = await unum.createChannel('app-events', ['member-1', 'member-2']);
+
+// Broadcast Praxis events to channel
+await unum.broadcastEvent(channel.id, {
+  tag: 'USER_JOINED',
+  payload: { userId: 'alice' },
 });
 
-// Integrate with Praxis actors
-const unumActor = createActor('unum-bridge', identity, async (event) => {
-  // Bridge Praxis events to Unum channels
-  await channel.publish(event);
+// Subscribe to events from channel
+const unsubscribe = unum.subscribeToEvents(channel.id, (event) => {
+  console.log('Received event:', event);
+  // Feed into local Praxis engine
+  engine.step([event]);
 });
+
+// Attach to engine for automatic event broadcasting
+attachUnumToEngine(engine, unum, channel.id);
 ```
 
-**Status**: Planned  
-**Use Cases**: Distributed messaging, identity management, authentication
+**Features:**
+
+- **Identity Management**: Create and manage user/node identities
+- **Channel Communication**: Real-time messaging between distributed nodes
+- **Event Broadcasting**: Share Praxis events across channels
+- **Fact Synchronization**: Distribute facts to connected participants
+- **PluresDB Integration**: Persists identities and messages
+
+**Status**: ✅ Available (`src/integrations/unum.ts`)  
+**Tests**: Comprehensive integration tests  
+**Use Cases**: Distributed messaging, identity management, multi-user collaboration
 
 ### ADP Integration
 
@@ -651,48 +805,116 @@ adp.enforce({
 
 ### State-Docs Integration
 
-Living documentation generated from Praxis schemas.
+Living documentation generated from Praxis schemas. **Now fully implemented** with Markdown and Mermaid diagram generation.
 
 ```typescript
-import { generateStateDocs } from '@plures/state-docs';
-
-// Generate documentation from schema
-const docs = await generateStateDocs({
-  schema: appSchema,
-  logic: logicDefinitions,
-  components: componentDefinitions,
-  output: './docs',
-  format: 'markdown', // or 'html', 'pdf'
+import {
+  createStateDocsGenerator,
+  generateDocs,
+} from '@plures/praxis';
+
+// Create generator
+const generator = createStateDocsGenerator({
+  projectTitle: 'My Praxis App',
+  target: './docs',
+  visualization: {
+    format: 'mermaid',
+    theme: 'default',
+  },
+  template: {
+    toc: true,
+    timestamp: true,
+  },
 });
 
-// Documentation includes:
-// - Data model diagrams
-// - Logic flow diagrams
-// - Component catalog
-// - API reference
-// - Usage examples
+// Generate docs from schema
+const docs = generator.generateFromSchema(appSchema);
+
+// Or from registry
+const registryDocs = generator.generateFromModule(myModule);
+
+// Write generated docs
+for (const doc of docs) {
+  await writeFile(doc.path, doc.content);
+}
+
+// Quick helper
+const allDocs = generateDocs(appSchema, {
+  projectTitle: 'My App',
+  target: './docs',
+});
 ```
 
-**Status**: Planned  
-**Documentation**: See examples for State-Docs integration patterns
+**Features:**
+
+- **Schema Documentation**: Auto-generate docs from Praxis schemas
+- **Mermaid Diagrams**: Visual state machine and flow diagrams
+- **Markdown Output**: GitHub-ready documentation
+- **Model & Component Docs**: Detailed API documentation
+- **Logic Flow Visualization**: Event → Rule → Fact diagrams
+- **Table of Contents**: Automatic ToC generation
+
+**Status**: ✅ Available (`src/integrations/state-docs.ts`)  
+**CLI**: Use `praxis generate` with `--docs` flag (coming soon)  
+**Documentation**: Auto-generates README, models.md, logic diagrams
 
 ### CodeCanvas Integration
 
-Visual IDE for schema and logic editing.
+Visual IDE for schema and logic editing. **Now fully implemented** with schema visualization and canvas export.
 
-```bash
-# Open Canvas for visual editing
-praxis canvas src/schemas/app.schema.ts
+```typescript
+import {
+  schemaToCanvas,
+  canvasToSchema,
+  canvasToMermaid,
+  createCanvasEditor,
+} from '@plures/praxis';
+
+// Convert schema to canvas document
+const canvas = schemaToCanvas(mySchema, {
+  layout: 'hierarchical',
+});
 
-# Features:
-# - Visual schema design
-# - Logic flow editor
-# - Component preview
-# - Real-time collaboration
-# - Export to code
+// Export to YAML (Obsidian Canvas compatible)
+const yaml = canvasToYaml(canvas);
+await writeFile('./schema.canvas.yaml', yaml);
+
+// Export to Mermaid diagram
+const mermaid = canvasToMermaid(canvas);
+
+// Create canvas editor instance
+const editor = createCanvasEditor({
+  schema: mySchema,
+  enableFSM: true,
+  layout: 'hierarchical',
+});
+
+// Add nodes programmatically
+editor.addNode({
+  type: 'model',
+  label: 'User',
+  x: 100,
+  y: 100,
+  width: 150,
+  height: 60,
+  data: userModel,
+});
+
+// Convert back to schema
+const updatedSchema = editor.toSchema();
 ```
 
-**Status**: Planned  
+**Features:**
+
+- **Visual Schema Design**: Node-based schema editor
+- **Canvas Export**: YAML and Mermaid diagram formats
+- **Obsidian Compatible**: Works with Obsidian Canvas format
+- **FSM Visualization**: State machine and flow diagrams
+- **Bi-directional Sync**: Canvas ↔ Schema round-tripping
+- **Guardian Validation**: Pre-commit lifecycle checks
+
+**Status**: ✅ Available (`src/integrations/code-canvas.ts`)  
+**CLI**: Use `praxis canvas` commands (coming soon)  
 **Documentation**: [docs/guides/canvas.md](./docs/guides/canvas.md)
 
 ### Svelte + Tauri Runtime

package/dist/browser/adapter-TM4IS5KT.js

@@ -0,0 +1,12 @@
+import {
+  InMemoryPraxisDB,
+  PluresDBPraxisAdapter,
+  createInMemoryDB,
+  createPluresDB
+} from "./chunk-JQ64KMLN.js";
+export {
+  InMemoryPraxisDB,
+  PluresDBPraxisAdapter,
+  createInMemoryDB,
+  createPluresDB
+};