@plures/praxis 1.0.3 → 1.1.1

package/docs/core/what-is-praxis.md

@@ -7,6 +7,7 @@ Praxis is a **schema-driven application framework** that unifies data modeling,
 ### 1. Schema as Single Source of Truth
 
 In Praxis, everything starts with a schema. The **Praxis Schema Format (PSF)** defines your:
+
 - Data models and relationships
 - Business logic (facts, events, rules, constraints)
 - UI components and their behavior
@@ -14,6 +15,7 @@ In Praxis, everything starts with a schema. The **Praxis Schema Format (PSF)** d
 - Documentation and diagrams
 
 From this single schema, Praxis generates:
+
 - TypeScript types and interfaces
 - Svelte UI components
 - Database schemas for PluresDB
@@ -23,12 +25,14 @@ From this single schema, Praxis generates:
 ### 2. Pure, Functional Logic
 
 The Praxis logic engine is built on pure functions:
+
 - **Facts**: Typed propositions about your domain ("User is logged in", "Cart contains 3 items")
 - **Events**: Things that happen ("User clicked login", "Item added to cart")
 - **Rules**: Pure functions that derive facts from events
 - **Constraints**: Invariants that must always hold
 
 This makes your application logic:
+
 - Predictable and testable
 - Serializable (JSON-friendly for cross-language support)
 - Easy to reason about and debug
@@ -36,6 +40,7 @@ This makes your application logic:
 ### 3. Local-First by Default
 
 Praxis applications work offline first:
+
 - Data stored locally in PluresDB
 - Changes sync when connected
 - Conflict resolution built-in
@@ -44,6 +49,7 @@ Praxis applications work offline first:
 ### 4. Visual and Code Workflows
 
 Praxis supports both visual and code-based development:
+
 - **CodeCanvas**: Visual schema and logic editor
 - **Code-first**: Write TypeScript schemas directly
 - **Bidirectional sync**: Changes in either flow back to the other
@@ -55,36 +61,36 @@ flowchart LR
     subgraph Define["1. Define Schema"]
         PSF[schema.psf.json]
     end
-    
+
     subgraph Generate["2. Generate Code"]
         Types[Types]
         Components[Components]
         Logic[Logic]
         Docs[Docs]
     end
-    
+
     subgraph Build["3. Build App"]
         UI[UI Layer]
         Engine[Logic Engine]
         Data[Data Layer]
     end
-    
+
     subgraph Deploy["4. Deploy"]
         Web[Web]
         Desktop[Desktop]
         Mobile[Mobile]
     end
-    
+
     PSF --> Types
     PSF --> Components
     PSF --> Logic
     PSF --> Docs
-    
+
     Types --> UI
     Components --> UI
     Logic --> Engine
     Types --> Data
-    
+
     UI --> Web
     UI --> Desktop
     UI --> Mobile
@@ -162,6 +168,7 @@ console.log(engine.getContext()); // { count: 1 }
 ### Praxis Schema Format (PSF)
 
 The JSON/AST format that defines your application:
+
 - Version-controlled and diff-friendly
 - Human-readable and machine-parseable
 - Supports composition and inheritance
@@ -170,6 +177,7 @@ The JSON/AST format that defines your application:
 ### Logic Engine
 
 The pure functional core:
+
 - Processes events to produce facts
 - Maintains immutable state
 - Supports undo/redo and time-travel
@@ -178,6 +186,7 @@ The pure functional core:
 ### Component Factory
 
 Generates Svelte components:
+
 - Form components with validation
 - List and display components
 - Navigation components
@@ -186,6 +195,7 @@ Generates Svelte components:
 ### PluresDB Integration
 
 Local-first data layer:
+
 - Reactive queries and subscriptions
 - Automatic sync with conflict resolution
 - Event sourcing support
@@ -194,6 +204,7 @@ Local-first data layer:
 ### CodeCanvas
 
 Visual development environment:
+
 - Drag-and-drop schema design
 - Logic flow visualization
 - Live component preview
@@ -202,35 +213,41 @@ Visual development environment:
 ## Use Cases
 
 ### Web Applications
+
 Build modern single-page applications with reactive data and offline support.
 
 ### Desktop Applications
+
 Use Tauri to create cross-platform desktop apps from the same codebase.
 
 ### Mobile Applications
+
 Deploy to mobile with Svelte Native or Tauri Mobile.
 
 ### Distributed Systems
+
 Coordinate multiple nodes with built-in DSC/MCP orchestration.
 
 ### Knowledge Management
+
 Create interconnected data systems with PluresDB relationships.
 
 ## Comparison
 
-| Feature | Praxis | Traditional MVC | Redux | XState |
-|---------|--------|-----------------|-------|--------|
-| Schema-driven | ✅ | ❌ | ❌ | ❌ |
-| Logic engine | ✅ | ❌ | ✅ | ✅ |
-| UI generation | ✅ | ❌ | ❌ | ❌ |
-| Local-first | ✅ | ❌ | ❌ | ❌ |
-| Visual editor | ✅ | ❌ | ❌ | ✅ |
-| Cross-language | ✅ | ❌ | ❌ | ❌ |
-| Auto-docs | ✅ | ❌ | ❌ | ❌ |
+| Feature        | Praxis | Traditional MVC | Redux | XState |
+| -------------- | ------ | --------------- | ----- | ------ |
+| Schema-driven  | ✅     | ❌              | ❌    | ❌     |
+| Logic engine   | ✅     | ❌              | ✅    | ✅     |
+| UI generation  | ✅     | ❌              | ❌    | ❌     |
+| Local-first    | ✅     | ❌              | ❌    | ❌     |
+| Visual editor  | ✅     | ❌              | ❌    | ✅     |
+| Cross-language | ✅     | ❌              | ❌    | ❌     |
+| Auto-docs      | ✅     | ❌              | ❌    | ❌     |
 
 ## Getting Started
 
 Ready to build with Praxis? Check out:
+
 - [Getting Started Guide](../guides/getting-started.md)
 - [Schema Model](./schema-model.md)
 - [Example Applications](../../examples/)

package/docs/guides/canvas.md

@@ -5,6 +5,7 @@ CodeCanvas is the visual IDE for the Praxis framework. It provides a graphical i
 ## Overview
 
 CodeCanvas enables:
+
 - **Visual Schema Design**: Drag-and-drop model and component design
 - **Logic Flow Editor**: Build rules and state machines visually
 - **Component Preview**: See generated components in real-time
@@ -36,6 +37,7 @@ praxis canvas --new
 ### 1. Schema Editor
 
 **Model Designer**:
+
 - Drag models onto canvas
 - Define fields with visual editor
 - Set relationships between models
@@ -43,6 +45,7 @@ praxis canvas --new
 - Preview generated PluresDB schema
 
 **Component Designer**:
+
 - Create components from templates
 - Bind components to models
 - Configure props and events
@@ -52,6 +55,7 @@ praxis canvas --new
 ### 2. Logic Flow Editor
 
 **Flow Canvas**:
+
 - Visual state machine designer
 - Connect facts, events, and rules
 - Define transitions with conditions
@@ -59,6 +63,7 @@ praxis canvas --new
 - Export to Praxis logic code
 
 **Rule Builder**:
+
 - Visual rule editor
 - Condition builder with drag-and-drop
 - Action designer
@@ -68,6 +73,7 @@ praxis canvas --new
 ### 3. Component Preview
 
 **Live Preview**:
+
 - Real-time component rendering
 - Interactive component testing
 - Props editor
@@ -75,6 +81,7 @@ praxis canvas --new
 - Responsive preview modes
 
 **Code Sync**:
+
 - Two-way sync with files
 - Live reload on changes
 - Conflict resolution
@@ -83,6 +90,7 @@ praxis canvas --new
 ### 4. Orchestration View
 
 **System Topology**:
+
 - Node visualization
 - Connection mapping
 - State distribution view
@@ -90,6 +98,7 @@ praxis canvas --new
 - Performance metrics
 
 **DSC Designer**:
+
 - Visual DSC configuration
 - Node role assignment
 - State sync configuration
@@ -98,6 +107,7 @@ praxis canvas --new
 ### 5. Documentation Browser
 
 **Interactive Docs**:
+
 - Schema documentation
 - API reference
 - Component catalog
@@ -143,11 +153,11 @@ export const config: CanvasConfig = {
   // Server settings
   port: 3000,
   host: 'localhost',
-  
+
   // Editor settings
   mode: 'edit', // 'edit' | 'view' | 'present'
   theme: 'dark', // 'light' | 'dark' | 'auto'
-  
+
   // Features
   features: {
     collaboration: true,
@@ -155,21 +165,21 @@ export const config: CanvasConfig = {
     versionHistory: true,
     aiAssist: false,
   },
-  
+
   // Preview settings
   preview: {
     autoRefresh: true,
     refreshInterval: 1000,
     iframe: true,
   },
-  
+
   // Code sync
   sync: {
     enabled: true,
     watchFiles: true,
     conflictResolution: 'ask', // 'ask' | 'canvas' | 'code'
   },
-  
+
   // Export settings
   export: {
     format: 'typescript',
@@ -263,6 +273,7 @@ code --install-extension plures.praxis-canvas
 ```
 
 Features:
+
 - Open Canvas from editor
 - Inline previews
 - Quick navigation
@@ -273,6 +284,7 @@ Features:
 ### Canvas won't start
 
 Check:
+
 - Port 3000 is available
 - Schema file path is correct
 - Dependencies are installed
@@ -280,6 +292,7 @@ Check:
 ### Changes not syncing
 
 Solutions:
+
 - Enable sync in config
 - Check file permissions
 - Restart Canvas with `--force-sync`
@@ -287,6 +300,7 @@ Solutions:
 ### Preview not updating
 
 Try:
+
 - Clear browser cache
 - Disable ad blockers
 - Check preview refresh settings
@@ -336,6 +350,7 @@ features: {
 ```
 
 AI can:
+
 - Suggest models from descriptions
 - Generate rules from natural language
 - Optimize logic flows
@@ -358,6 +373,7 @@ praxis export --source canvas --format typescript
 ### Export Diagrams
 
 Export visual diagrams:
+
 - PNG/SVG for documentation
 - Mermaid for markdown
 - DOT for Graphviz

package/docs/guides/getting-started.md

@@ -5,6 +5,7 @@ Welcome to Praxis, the full-stack application framework for the Plures ecosystem
 ## What is Praxis?
 
 Praxis is a **schema-driven framework** that unifies:
+
 - **Logic Engine**: Facts, events, rules, and constraints for business logic
 - **Component Generation**: Auto-generate UI from schemas
 - **Local-First Data**: PluresDB for reactive, offline-capable storage
@@ -28,6 +29,7 @@ npm install -g @plures/praxis
 ```
 
 Verify installation:
+
 ```bash
 praxis --version
 ```
@@ -43,6 +45,7 @@ npm install
 ```
 
 This creates a basic Praxis app with:
+
 - Schema setup
 - Logic engine configuration
 - Svelte UI scaffolding
@@ -76,7 +79,7 @@ export const appSchema: PraxisSchema = {
   version: '1.0.0',
   name: 'MyFirstApp',
   description: 'My first Praxis application',
-  
+
   // Define data models
   models: [
     {
@@ -88,12 +91,10 @@ export const appSchema: PraxisSchema = {
         { name: 'completed', type: 'boolean', default: false },
         { name: 'createdAt', type: 'date' },
       ],
-      indexes: [
-        { name: 'by_created', fields: ['createdAt'] },
-      ],
+      indexes: [{ name: 'by_created', fields: ['createdAt'] }],
     },
   ],
-  
+
   // Define UI components
   components: [
     {
@@ -109,7 +110,7 @@ export const appSchema: PraxisSchema = {
       description: 'List of all tasks',
     },
   ],
-  
+
   // Define business logic
   logic: [
     {
@@ -168,6 +169,7 @@ praxis generate --schema src/schemas/app.schema.ts
 ```
 
 This generates:
+
 - `src/components/TaskForm.svelte` - Form component
 - `src/components/TaskList.svelte` - List component
 - `src/logic/facts.ts` - Fact definitions
@@ -213,7 +215,7 @@ Edit `src/App.svelte`:
   import { engine } from './logic/engine';
   import TaskForm from './components/TaskForm.svelte';
   import TaskList from './components/TaskList.svelte';
-  
+
   const store = createPraxisStore(engine);
 </script>
 
@@ -245,6 +247,7 @@ Open http://localhost:5173 to see your app!
 ### Schemas
 
 Schemas are the single source of truth. They define:
+
 - **Models**: Data structures and relationships
 - **Components**: UI elements and their behavior
 - **Logic**: Facts, events, rules, and constraints
@@ -253,6 +256,7 @@ Schemas are the single source of truth. They define:
 ### Logic Engine
 
 The Praxis logic engine processes:
+
 - **Events**: Things that happen (user actions, external triggers)
 - **Facts**: Derived information about the domain
 - **Rules**: Pure functions that transform events into facts
@@ -261,6 +265,7 @@ The Praxis logic engine processes:
 ### Component Generation
 
 Components are generated from schemas but can be customized:
+
 - Generated components provide scaffolding
 - Extend with custom behavior and styling
 - Regenerate safely (customizations preserved in separate files)
@@ -268,6 +273,7 @@ Components are generated from schemas but can be customized:
 ### Local-First Data
 
 PluresDB provides:
+
 - Reactive data storage
 - Offline operation
 - Automatic sync when connected

package/docs/guides/history-state-pattern.md

@@ -63,7 +63,9 @@ interface AppContext {
   page: string;
 }
 
-const engine = createPraxisEngine<AppContext>({ /* ... */ });
+const engine = createPraxisEngine<AppContext>({
+  /* ... */
+});
 const history = new HistoryStateManager<AppContext>(100);
 
 // Record initial state
@@ -174,12 +176,12 @@ Praxis provides first-class Svelte 5 support with runes:
   import { createMyEngine, Login, Logout } from './my-engine';
 
   const engine = createMyEngine();
-  const { 
-    context, 
-    dispatch, 
-    undo, 
-    redo, 
-    canUndo, 
+  const {
+    context,
+    dispatch,
+    undo,
+    redo,
+    canUndo,
     canRedo,
     snapshots,
     historyIndex
@@ -226,13 +228,13 @@ Praxis provides first-class Svelte 5 support with runes:
   import { createMyEngine } from './my-engine';
 
   const engine = createMyEngine();
-  const { context, snapshots, goToSnapshot, historyIndex } = 
+  const { context, snapshots, goToSnapshot, historyIndex } =
     usePraxisEngine(engine, { enableHistory: true });
 </script>
 
 <div class="debugger">
   <h2>Time-Travel Debugger</h2>
-  
+
   <div class="timeline">
     {#each snapshots as snapshot, index}
       <button
@@ -277,27 +279,39 @@ interface AuthContext {
 }
 
 // Define facts
-const UserAuthenticated = defineFact<'UserAuthenticated', { 
-  userId: string; 
-  name: string 
-}>('UserAuthenticated');
+const UserAuthenticated = defineFact<
+  'UserAuthenticated',
+  {
+    userId: string;
+    name: string;
+  }
+>('UserAuthenticated');
 
-const NavigatedToPage = defineFact<'NavigatedToPage', { 
-  page: string 
-}>('NavigatedToPage');
+const NavigatedToPage = defineFact<
+  'NavigatedToPage',
+  {
+    page: string;
+  }
+>('NavigatedToPage');
 
 // Define events
-const Login = defineEvent<'LOGIN', { 
-  username: string; 
-  password: string 
-}>('LOGIN');
+const Login = defineEvent<
+  'LOGIN',
+  {
+    username: string;
+    password: string;
+  }
+>('LOGIN');
 
 const Logout = defineEvent<'LOGOUT', {}>('LOGOUT');
 
-const NavigateTo = defineEvent<'NAVIGATE_TO', { 
-  page: string;
-  requiresAuth?: boolean;
-}>('NAVIGATE_TO');
+const NavigateTo = defineEvent<
+  'NAVIGATE_TO',
+  {
+    page: string;
+    requiresAuth?: boolean;
+  }
+>('NAVIGATE_TO');
 
 // Define rules
 const loginRule = defineRule<AuthContext>({
@@ -317,9 +331,7 @@ const loginRule = defineRule<AuthContext>({
       state.context.attemptedSecurePage = null;
     }
 
-    return [
-      UserAuthenticated.create({ userId: username, name: username })
-    ];
+    return [UserAuthenticated.create({ userId: username, name: username })];
   },
 });
 
@@ -394,9 +406,9 @@ export { Login, Logout, NavigateTo };
   });
 
   function login() {
-    dispatch([Login.create({ 
-      username: 'alice', 
-      password: 'secret123' 
+    dispatch([Login.create({
+      username: 'alice',
+      password: 'secret123'
     })], 'User Login');
   }
 
@@ -405,16 +417,16 @@ export { Login, Logout, NavigateTo };
   }
 
   function goToProfile() {
-    dispatch([NavigateTo.create({ 
-      page: 'profile', 
-      requiresAuth: true 
+    dispatch([NavigateTo.create({
+      page: 'profile',
+      requiresAuth: true
     })], 'Navigate to Profile');
   }
 
   function returnToPrevious() {
     if (context.previousPage) {
-      dispatch([NavigateTo.create({ 
-        page: context.previousPage 
+      dispatch([NavigateTo.create({
+        page: context.previousPage
       })], 'Return to Previous Page');
     } else if (canUndo) {
       undo();
@@ -506,7 +518,7 @@ function handleLogout() {
 // Clear when starting new workflow
 function startNewProject() {
   historyEngine.clearHistory();
-  historyEngine.dispatch([CreateProject.create({})],'New Project');
+  historyEngine.dispatch([CreateProject.create({})], 'New Project');
 }
 ```
 
@@ -516,10 +528,10 @@ function startNewProject() {
 interface AppContext {
   // Application state
   user: User | null;
-  
+
   // Built-in history tracking in context
   navigationHistory: string[];
-  
+
   // Previous state for quick back
   previousView: string | null;
 }
@@ -530,11 +542,11 @@ const navigationRule = defineRule<AppContext>({
   impl: (state, events) => {
     const nav = findEvent(events, Navigate);
     if (!nav) return [];
-    
+
     state.context.previousView = state.context.currentView;
     state.context.navigationHistory.push(nav.payload.page);
     state.context.currentView = nav.payload.page;
-    
+
     return [];
   },
 });
@@ -571,13 +583,13 @@ const errorRecoveryRule = defineRule<AppContext>({
   impl: (state, events) => {
     const error = findEvent(events, ErrorOccurred);
     if (!error) return [];
-    
+
     // Log error with context
     console.error('Error at state:', state.context);
-    
+
     // You can use history to diagnose or recover
     // historyEngine.undo() to revert to last good state
-    
+
     return [ErrorLogged.create({ error: error.payload })];
   },
 });
@@ -585,14 +597,14 @@ const errorRecoveryRule = defineRule<AppContext>({
 
 ## Comparison with XState
 
-| Feature | XState | Praxis |
-|---------|--------|--------|
-| **Built-in History States** | ✅ Native support | ✅ Pattern-based implementation |
-| **History Types** | Shallow/Deep | Configurable via HistoryStateManager |
-| **Time-Travel** | Via DevTools | ✅ Built into usePraxisEngine |
-| **Undo/Redo** | Custom implementation | ✅ Built-in with createHistoryEngine |
-| **Snapshot Support** | ✅ Via snapshot() | ✅ Via usePraxisEngine snapshots |
-| **History Size Limits** | Manual | ✅ Automatic with maxHistorySize |
+| Feature                     | XState                | Praxis                               |
+| --------------------------- | --------------------- | ------------------------------------ |
+| **Built-in History States** | ✅ Native support     | ✅ Pattern-based implementation      |
+| **History Types**           | Shallow/Deep          | Configurable via HistoryStateManager |
+| **Time-Travel**             | Via DevTools          | ✅ Built into usePraxisEngine        |
+| **Undo/Redo**               | Custom implementation | ✅ Built-in with createHistoryEngine |
+| **Snapshot Support**        | ✅ Via snapshot()     | ✅ Via usePraxisEngine snapshots     |
+| **History Size Limits**     | Manual                | ✅ Automatic with maxHistorySize     |
 
 ## Summary
 
@@ -606,6 +618,7 @@ The history state pattern in Praxis provides:
 - ✅ **Auth Flow Support**: Return to previous states after authentication
 
 The pattern is designed to be:
+
 - **Simple**: Easy to understand and use
 - **Flexible**: Works with any Praxis engine
 - **Performant**: Configurable history limits
@@ -613,6 +626,7 @@ The pattern is designed to be:
 - **Framework-Agnostic**: Use with or without Svelte
 
 For more examples, see:
+
 - [Svelte Counter Example](/src/examples/svelte-counter/index.ts)
 - [Auth Basic Example](/src/examples/auth-basic/index.ts)
 - [Svelte Integration Tests](/src/__tests__/svelte-integration.test.ts)