@plures/praxis 1.1.3 → 1.2.10

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,5 +1,3 @@
-dotnet build
-dotnet test
 # Praxis
 
 **Typed, visual-first application logic for Svelte, Node, and the browser.**
@@ -10,25 +8,10 @@ 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. The library 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 unified solution for declarative application development. The framework combines typed logic modeling (facts, events, rules, constraints), component generation (Svelte 5), and local-first data persistence (PluresDB). It includes visual tools (CodeCanvas, State-Docs), distributed system support (Unum), optional cloud relay, and a CLI for scaffolding and generation.
 
----
+The library delivers unified ESM/CJS builds with curated subpath exports (`./`, `./svelte`, `./schema`, `./component`, `./cloud`, `./components`), Svelte 5 runes support, and publish-ready packages for npm and JSR.
 
-## 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 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.
-- **Cloud Relay**: Optional sync layer (GitHub-auth friendly) for distributed teams.
-- **CLI**: Scaffolding, generation, canvas helpers, and cloud commands.
 
 ## Install
 Node 18+ recommended.
@@ -43,7 +26,7 @@ pnpm add @plures/praxis
 
 JSR (Deno):
 ```bash
-const result = engine.step([Login.create({ username: 'alice' })]);
+deno add @plures/praxis
 # or via import map pointing to npm:
 # {
 #   "imports": { "@plures/praxis": "npm:@plures/praxis@^1.1.2" }
@@ -81,6 +64,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">
@@ -468,7 +509,7 @@ Demonstrates the terminal node feature for command execution:
 - Terminal adapter creation and configuration
 - Command execution and history tracking
 - YAML schema loading with terminal nodes
-- PluresDB binding configuration (ready for integration)
+- PluresDB binding configuration
 - Both text and widget input modes
 
 ```bash
@@ -603,7 +644,7 @@ Praxis integrates with the full Plures ecosystem:
 
 ### PluresDB Integration
 
-Local-first reactive datastore for offline-capable applications. **Now fully implemented** with 32 tests covering all features.
+Local-first reactive datastore for offline-capable applications. Fully implemented with 32 tests covering all features.
 
 ```typescript
 import {
@@ -652,116 +693,174 @@ adapter.subscribeToEvents((events) => {
 
 ### Unum Integration
 
-Identity and channels for distributed systems.
+Identity and channels for distributed systems. 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
 
-Architectural Decision Protocol for guardrails and governance.
+### State-Docs Integration
+
+Living documentation generated from Praxis schemas. Fully implemented with Markdown and Mermaid diagram generation.
 
 ```typescript
-import { createADP } from '@plures/adp';
+import {
+  createStateDocsGenerator,
+  generateDocs,
+} from '@plures/praxis';
 
-// Track architectural decisions from schemas
-const adp = createADP({
-  source: 'praxis-schema',
-  decisions: [
-    {
-      id: 'ADR-001',
-      title: 'Use PluresDB for local-first storage',
-      context: 'Need offline-capable data storage',
-      decision: 'Adopt PluresDB',
-      consequences: ['Offline support', 'Sync complexity'],
-    },
-  ],
+// Create generator
+const generator = createStateDocsGenerator({
+  projectTitle: 'My Praxis App',
+  target: './docs',
+  visualization: {
+    format: 'mermaid',
+    theme: 'default',
+  },
+  template: {
+    toc: true,
+    timestamp: true,
+  },
 });
 
-// Enforce guardrails
-adp.enforce({
-  rule: 'no-direct-database-access',
-  check: (code) => !code.includes('direct-sql'),
+// 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  
-**Use Cases**: Architecture documentation, compliance checking, guardrails
+**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
 
-### State-Docs Integration
+**Status**: ✅ Available (`src/integrations/state-docs.ts`)  
+**Documentation**: Auto-generates README, models.md, logic diagrams
 
-Living documentation generated from Praxis schemas.
+### CodeCanvas Integration
+
+Visual IDE for schema and logic editing. Fully implemented with schema visualization and canvas export.
 
 ```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 {
+  schemaToCanvas,
+  canvasToSchema,
+  canvasToMermaid,
+  createCanvasEditor,
+} from '@plures/praxis';
 
-// Documentation includes:
-// - Data model diagrams
-// - Logic flow diagrams
-// - Component catalog
-// - API reference
-// - Usage examples
-```
+// Convert schema to canvas document
+const canvas = schemaToCanvas(mySchema, {
+  layout: 'hierarchical',
+});
 
-**Status**: Planned  
-**Documentation**: See examples for State-Docs integration patterns
+// Export to YAML (Obsidian Canvas compatible)
+const yaml = canvasToYaml(canvas);
+await writeFile('./schema.canvas.yaml', yaml);
 
-### CodeCanvas Integration
+// Export to Mermaid diagram
+const mermaid = canvasToMermaid(canvas);
 
-Visual IDE for schema and logic editing.
+// Create canvas editor instance
+const editor = createCanvasEditor({
+  schema: mySchema,
+  enableFSM: true,
+  layout: 'hierarchical',
+});
 
-```bash
-# Open Canvas for visual editing
-praxis canvas src/schemas/app.schema.ts
+// Add nodes programmatically
+editor.addNode({
+  type: 'model',
+  label: 'User',
+  x: 100,
+  y: 100,
+  width: 150,
+  height: 60,
+  data: userModel,
+});
 
-# Features:
-# - Visual schema design
-# - Logic flow editor
-# - Component preview
-# - Real-time collaboration
-# - Export to code
+// 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`)  
 **Documentation**: [docs/guides/canvas.md](./docs/guides/canvas.md)
 
-### Svelte + Tauri Runtime
+### Svelte Integration
 
-Cross-platform runtime for web, desktop, and mobile.
+Svelte v5 integration with reactive stores.
 
 ```typescript
-// Svelte v5 integration (available now)
 import { createPraxisStore } from '@plures/praxis/svelte';
 
 const stateStore = createPraxisStore(engine);
@@ -769,15 +868,8 @@ const userStore = createDerivedStore(engine, (ctx) => ctx.currentUser);
 
 // In Svelte component:
 // $: currentUser = $userStore;
-
-// Desktop app with Tauri
-npm run tauri:dev    // Development
-npm run tauri:build  // Production
 ```
 
-**Status**: Svelte integration available, Tauri templates planned  
-**Platform Support**: Web (now), Desktop (planned), Mobile (future)
-
 ## Cross-Language Usage
 
 ### PowerShell
@@ -851,23 +943,6 @@ Console.WriteLine($"Facts: {result.State.Facts.Count}"); // Facts: 1
 
 See [csharp/Praxis/README.md](./csharp/Praxis/README.md) for complete documentation.
 
-## Roadmap
-
-### Current Focus
-
-- Full CodeCanvas integration
-- Enhanced Unum identity support
-- Advanced State-Docs generation
-- Multi-language schema support
-- Real PluresDB sync with CRDT/offline-first capabilities
-
-### Long Term
-
-- Mobile templates (iOS, Android)
-- Enterprise features
-- Advanced orchestration
-- Performance optimizations
-- Plugin ecosystem
 
 ## Cross-Language Support
 

package/dist/browser/adapter-CIMBGDC7.js

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