@plures/praxis 0.2.0

package/docs/guides/canvas.md

@@ -0,0 +1,389 @@
+# CodeCanvas Integration Guide
+
+CodeCanvas is the visual IDE for the Praxis framework. It provides a graphical interface for designing schemas, logic flows, and components.
+
+## 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
+- **Orchestration Visualization**: Visualize distributed systems
+- **Documentation Navigation**: Interactive documentation browser
+
+## Getting Started
+
+### Launch Canvas
+
+From your Praxis project:
+
+```bash
+praxis canvas src/schemas/app.schema.ts
+```
+
+This opens Canvas at http://localhost:3000 with your schema loaded.
+
+### Create New Schema
+
+Start Canvas without a schema:
+
+```bash
+praxis canvas --new
+```
+
+## Canvas Features
+
+### 1. Schema Editor
+
+**Model Designer**:
+- Drag models onto canvas
+- Define fields with visual editor
+- Set relationships between models
+- Configure indexes and constraints
+- Preview generated PluresDB schema
+
+**Component Designer**:
+- Create components from templates
+- Bind components to models
+- Configure props and events
+- Design layout visually
+- Preview generated Svelte components
+
+### 2. Logic Flow Editor
+
+**Flow Canvas**:
+- Visual state machine designer
+- Connect facts, events, and rules
+- Define transitions with conditions
+- Test flows interactively
+- Export to Praxis logic code
+
+**Rule Builder**:
+- Visual rule editor
+- Condition builder with drag-and-drop
+- Action designer
+- Priority management
+- Constraint visualization
+
+### 3. Component Preview
+
+**Live Preview**:
+- Real-time component rendering
+- Interactive component testing
+- Props editor
+- Event logging
+- Responsive preview modes
+
+**Code Sync**:
+- Two-way sync with files
+- Live reload on changes
+- Conflict resolution
+- Version history
+
+### 4. Orchestration View
+
+**System Topology**:
+- Node visualization
+- Connection mapping
+- State distribution view
+- Health monitoring
+- Performance metrics
+
+**DSC Designer**:
+- Visual DSC configuration
+- Node role assignment
+- State sync configuration
+- Health check setup
+
+### 5. Documentation Browser
+
+**Interactive Docs**:
+- Schema documentation
+- API reference
+- Component catalog
+- Logic flow diagrams
+- Generated from State-Docs
+
+## Workflows
+
+### Visual-First Workflow
+
+1. Design schema in Canvas
+2. Generate code with `praxis generate`
+3. Customize generated code
+4. Preview in Canvas
+5. Deploy
+
+### Code-First Workflow
+
+1. Write schema in TypeScript
+2. Open in Canvas for visualization
+3. Make visual adjustments in Canvas
+4. Sync changes back to code
+5. Continue development
+
+### Hybrid Workflow
+
+1. Start with visual design
+2. Export to code
+3. Add custom logic in code
+4. Use Canvas for visualization
+5. Iterate between visual and code
+
+## Configuration
+
+### Canvas Config File
+
+Create `canvas.config.ts`:
+
+```typescript
+import type { CanvasConfig } from '@plures/praxis/canvas';
+
+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,
+    autosave: true,
+    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',
+    includeComments: true,
+    formatting: 'prettier',
+  },
+};
+```
+
+### Launch with Config
+
+```bash
+praxis canvas --config canvas.config.ts
+```
+
+## Collaboration
+
+### Real-Time Collaboration
+
+Enable in config:
+
+```typescript
+features: {
+  collaboration: true,
+}
+```
+
+Share Canvas URL with team members. Changes sync in real-time.
+
+### Permissions
+
+Configure access:
+
+```typescript
+collaboration: {
+  enabled: true,
+  permissions: {
+    view: ['*'],
+    edit: ['team@example.com'],
+    admin: ['owner@example.com'],
+  },
+}
+```
+
+## Keyboard Shortcuts
+
+- `Ctrl/Cmd + N`: New model
+- `Ctrl/Cmd + C`: Create component
+- `Ctrl/Cmd + R`: Add rule
+- `Ctrl/Cmd + S`: Save
+- `Ctrl/Cmd + G`: Generate code
+- `Ctrl/Cmd + P`: Preview component
+- `Ctrl/Cmd + /`: Command palette
+- `Space`: Pan canvas
+- `+/-`: Zoom in/out
+
+## Tips & Tricks
+
+### Efficient Model Design
+
+1. Start with core models
+2. Add fields incrementally
+3. Use Canvas to visualize relationships
+4. Generate early and often
+5. Iterate based on generated code
+
+### Logic Flow Design
+
+1. Map business processes first
+2. Identify key events
+3. Define facts that matter
+4. Connect with rules
+5. Test flows in Canvas
+
+### Component Design
+
+1. Use templates as starting points
+2. Preview frequently
+3. Test with different data
+4. Sync to code for styling
+5. Maintain separation of concerns
+
+## Integration with VS Code
+
+### Canvas Extension
+
+Install the Praxis Canvas extension:
+
+```bash
+code --install-extension plures.praxis-canvas
+```
+
+Features:
+- Open Canvas from editor
+- Inline previews
+- Quick navigation
+- Code snippets
+
+## Troubleshooting
+
+### Canvas won't start
+
+Check:
+- Port 3000 is available
+- Schema file path is correct
+- Dependencies are installed
+
+### Changes not syncing
+
+Solutions:
+- Enable sync in config
+- Check file permissions
+- Restart Canvas with `--force-sync`
+
+### Preview not updating
+
+Try:
+- Clear browser cache
+- Disable ad blockers
+- Check preview refresh settings
+
+## Advanced Features
+
+### Custom Templates
+
+Add custom component templates:
+
+```typescript
+canvas: {
+  templates: {
+    components: [
+      {
+        name: 'CustomForm',
+        template: './templates/custom-form.svelte',
+        thumbnail: './templates/custom-form.png',
+      },
+    ],
+  },
+}
+```
+
+### Plugins
+
+Extend Canvas with plugins:
+
+```typescript
+canvas: {
+  plugins: [
+    '@plures/canvas-plugin-figma',
+    '@plures/canvas-plugin-storybook',
+    './plugins/custom-plugin.ts',
+  ],
+}
+```
+
+### AI Assistance
+
+Enable AI features:
+
+```typescript
+features: {
+  aiAssist: true,
+}
+```
+
+AI can:
+- Suggest models from descriptions
+- Generate rules from natural language
+- Optimize logic flows
+- Recommend component layouts
+
+## Export Options
+
+### Export to Code
+
+```bash
+# From Canvas UI: File > Export > TypeScript
+```
+
+Or via CLI:
+
+```bash
+praxis export --source canvas --format typescript
+```
+
+### Export Diagrams
+
+Export visual diagrams:
+- PNG/SVG for documentation
+- Mermaid for markdown
+- DOT for Graphviz
+- PDF for presentations
+
+### Export Documentation
+
+Generate State-Docs from Canvas:
+
+```bash
+praxis docs --source canvas
+```
+
+## Next Steps
+
+- Explore example Canvas projects
+- Try collaborative editing
+- Customize with plugins
+- Integrate with CI/CD
+- Share your Canvas templates
+
+## Resources
+
+- [Canvas Examples](../../examples/canvas/)
+- [Plugin Development](../api/canvas-plugins.md)
+- [Canvas API Reference](../api/canvas-api.md)
+- [Video Tutorials](https://youtube.com/plures)
+
+Canvas makes Praxis development visual, collaborative, and fun! 🎨

package/docs/guides/getting-started.md

@@ -0,0 +1,347 @@
+# Getting Started with Praxis Framework
+
+Welcome to Praxis, the full-stack application framework for the Plures ecosystem! This guide will help you get started building modern, local-first, distributed applications.
+
+## 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
+- **Visual Development**: CodeCanvas for schema and logic editing
+- **Orchestration**: Distributed system coordination with DSC/MCP
+- **Documentation**: Automatic State-Docs generation
+
+## Prerequisites
+
+- Node.js 18+ and npm
+- Basic TypeScript knowledge
+- Familiarity with Svelte (for UI)
+- Git for version control
+
+## Installation
+
+### Install Praxis CLI
+
+```bash
+npm install -g @plures/praxis
+```
+
+Verify installation:
+```bash
+praxis --version
+```
+
+## Create Your First App
+
+### 1. Create a new project
+
+```bash
+praxis create app my-first-app
+cd my-first-app
+npm install
+```
+
+This creates a basic Praxis app with:
+- Schema setup
+- Logic engine configuration
+- Svelte UI scaffolding
+- PluresDB integration
+- Development scripts
+
+### 2. Explore the structure
+
+```
+my-first-app/
+  ├── src/
+  │   ├── schemas/
+  │   │   └── app.schema.ts      # Your app schema
+  │   ├── logic/
+  │   │   └── engine.ts          # Logic engine setup
+  │   ├── components/            # UI components
+  │   ├── store/                 # Data store
+  │   └── main.ts               # Entry point
+  ├── package.json
+  └── README.md
+```
+
+### 3. Define your schema
+
+Open `src/schemas/app.schema.ts`:
+
+```typescript
+import type { PraxisSchema } from '@plures/praxis/schema';
+
+export const appSchema: PraxisSchema = {
+  version: '1.0.0',
+  name: 'MyFirstApp',
+  description: 'My first Praxis application',
+  
+  // Define data models
+  models: [
+    {
+      name: 'Task',
+      description: 'A task item',
+      fields: [
+        { name: 'id', type: 'string', description: 'Unique identifier' },
+        { name: 'title', type: 'string', description: 'Task title' },
+        { name: 'completed', type: 'boolean', default: false },
+        { name: 'createdAt', type: 'date' },
+      ],
+      indexes: [
+        { name: 'by_created', fields: ['createdAt'] },
+      ],
+    },
+  ],
+  
+  // Define UI components
+  components: [
+    {
+      name: 'TaskForm',
+      type: 'form',
+      model: 'Task',
+      description: 'Form for creating/editing tasks',
+    },
+    {
+      name: 'TaskList',
+      type: 'list',
+      model: 'Task',
+      description: 'List of all tasks',
+    },
+  ],
+  
+  // Define business logic
+  logic: [
+    {
+      id: 'task-logic',
+      description: 'Task management logic',
+      events: [
+        {
+          tag: 'TASK_CREATE',
+          payload: { title: 'string' },
+          description: 'Create a new task',
+        },
+        {
+          tag: 'TASK_COMPLETE',
+          payload: { taskId: 'string' },
+          description: 'Mark task as completed',
+        },
+      ],
+      facts: [
+        {
+          tag: 'TaskCreated',
+          payload: { taskId: 'string', title: 'string' },
+          description: 'A task was created',
+        },
+        {
+          tag: 'TaskCompleted',
+          payload: { taskId: 'string' },
+          description: 'A task was completed',
+        },
+      ],
+      rules: [
+        {
+          id: 'create-task',
+          description: 'Create a task when TASK_CREATE event occurs',
+          on: ['TASK_CREATE'],
+          then: 'emit TaskCreated fact',
+          priority: 10,
+        },
+      ],
+      constraints: [
+        {
+          id: 'task-title-required',
+          description: 'Task title must not be empty',
+          check: 'title.length > 0',
+          message: 'Task title is required',
+        },
+      ],
+    },
+  ],
+};
+```
+
+### 4. Generate code from schema
+
+```bash
+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
+- `src/logic/events.ts` - Event definitions
+- `src/logic/rules.ts` - Rule implementations
+- TypeScript types throughout
+
+### 5. Implement custom logic
+
+The generator creates stubs that you can customize. Edit `src/logic/rules.ts`:
+
+```typescript
+import { defineRule } from '@plures/praxis';
+import { TaskCreated } from './facts';
+import { TASK_CREATE } from './events';
+
+export const createTaskRule = defineRule({
+  id: 'create-task',
+  description: 'Create a task when TASK_CREATE event occurs',
+  impl: (state, events) => {
+    const createEvent = events.find(TASK_CREATE.is);
+    if (createEvent) {
+      const taskId = crypto.randomUUID();
+      return [
+        TaskCreated.create({
+          taskId,
+          title: createEvent.payload.title,
+        }),
+      ];
+    }
+    return [];
+  },
+});
+```
+
+### 6. Wire up the UI
+
+Edit `src/App.svelte`:
+
+```svelte
+<script lang="ts">
+  import { createPraxisStore } from '@plures/praxis/svelte';
+  import { engine } from './logic/engine';
+  import TaskForm from './components/TaskForm.svelte';
+  import TaskList from './components/TaskList.svelte';
+  
+  const store = createPraxisStore(engine);
+</script>
+
+<main>
+  <h1>My Task App</h1>
+  <TaskForm />
+  <TaskList />
+</main>
+
+<style>
+  main {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 2rem;
+  }
+</style>
+```
+
+### 7. Run the development server
+
+```bash
+npm run dev
+```
+
+Open http://localhost:5173 to see your app!
+
+## Core Concepts
+
+### 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
+- **Orchestration**: Distributed coordination (optional)
+
+### 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
+- **Constraints**: Invariants that must always hold
+
+### 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)
+
+### Local-First Data
+
+PluresDB provides:
+- Reactive data storage
+- Offline operation
+- Automatic sync when connected
+- Conflict resolution
+
+## Next Steps
+
+### Visual Editing with Canvas
+
+```bash
+praxis canvas src/schemas/app.schema.ts
+```
+
+Opens CodeCanvas at http://localhost:3000 for visual schema editing.
+
+### Add Authentication
+
+```bash
+praxis create component Auth --template auth
+```
+
+Generates authentication components and logic.
+
+### Enable Documentation
+
+State-Docs automatically generates documentation from your schemas:
+
+```bash
+npm run docs
+```
+
+View at http://localhost:3001
+
+### Deploy
+
+Build for production:
+
+```bash
+npm run build
+```
+
+Deploy the `dist/` folder to your hosting provider.
+
+## Examples
+
+Check out the examples in the Praxis repository:
+
+- **Offline-First Chat**: Demonstrates local-first architecture
+- **Knowledge Canvas**: Shows Canvas integration
+- **E-Commerce**: Full-featured example with auth and cart
+
+## Resources
+
+- [Framework Architecture](./FRAMEWORK.md)
+- [Schema Reference](../api/schema.md)
+- [Logic Engine Guide](../api/logic.md)
+- [Component Generation](../api/components.md)
+- [Praxis Repository](https://github.com/plures/praxis)
+
+## Getting Help
+
+- GitHub Issues: Report bugs and request features
+- Discussions: Ask questions and share your projects
+- Discord: Join the Plures community
+
+## What's Next?
+
+Now that you have a basic app running:
+
+1. Explore the generated code
+2. Add more models and components
+3. Implement complex business logic
+4. Try visual editing with Canvas
+5. Enable orchestration for distributed features
+6. Build something amazing!
+
+Welcome to the Praxis framework! 🚀