jsgui3-server 0.0.148 → 0.0.149

package/docs/resources-guide.md

@@ -17,19 +17,26 @@ Resources are JSGUI3 Server's abstraction layer for accessing data, functionalit
 
 ## Resource Types
 
-### Server_Resource_Pool
-
-**Purpose:** Manages collections of resources with access control and lifecycle management.
-
-**Key Features:**
-- Resource registration and discovery
-- Access control through permission systems
-- Lifecycle management (start/stop/cleanup)
-- Resource dependency resolution
-
-**Usage:**
-```javascript
-const pool = new Server_Resource_Pool({
+### Server_Resource_Pool
+
+**Purpose:** Manages collections of resources with access control and lifecycle management.
+
+**Key Features:**
+- Resource registration and discovery
+- Access control through permission systems
+- Lifecycle management (`start()`, `stop()`, `remove(name)`)
+- Type filtering with `get_resources_by_type(type)`
+- Aggregated `summary` view of resource states
+- Resource event forwarding:
+  - `resource_state_change`
+  - `crashed`
+  - `unhealthy`
+  - `unreachable`
+  - `recovered`
+
+**Usage:**
+```javascript
+const pool = new Server_Resource_Pool({
     access: {
         full: ['admin'],
         read: ['user']
@@ -37,14 +44,117 @@ const pool = new Server_Resource_Pool({
 });
 
 pool.add(myResource);
-pool.start((err) => {
-    // Pool is ready
-});
-```
-
-### Website_Resource
-
-**Purpose:** Wraps website objects for integration with the server's resource system.
+pool.start((err) => {
+    // Pool is ready
+});
+
+const summary = pool.summary;
+const process_resources = pool.get_resources_by_type('Process_Resource');
+await pool.remove('legacy_worker');
+```
+
+### Process_Resource
+
+**Purpose:** Represents a local long-running process as a resource.
+
+**Key Features:**
+- State machine lifecycle:
+  - `stopped`
+  - `starting`
+  - `running`
+  - `stopping`
+  - `restarting`
+  - `crashed`
+- Emits:
+  - `state_change`
+  - `stdout`
+  - `stderr`
+  - `exit`
+  - `health_check`
+  - `unhealthy`
+  - `crashed`
+- Auto-restart with exponential backoff (when `autoRestart: true`)
+- Optional health checks (`http`, `tcp`, `custom`)
+- Consistent status shape for direct and PM2-backed processes
+
+**Process Manager Modes:**
+- `direct` (default): Uses `child_process.spawn()`
+- `pm2`: Uses PM2 CLI commands
+
+**PM2 Path Resolution:**
+- If `processManager.pm2Path` is set, it is used
+- Else `PM2_PATH` env var is used (if set)
+- Else local `node_modules/.bin/pm2` is used if present
+- Else `pm2` is resolved from system `PATH`
+
+**Usage:**
+```javascript
+const Process_Resource = require('jsgui3-server/resources/process-resource');
+
+// Direct mode (default)
+const worker_direct = new Process_Resource({
+    name: 'worker_direct',
+    command: process.execPath,
+    args: ['worker.js'],
+    autoRestart: true
+});
+
+// PM2 mode (pm2Path optional)
+const worker_pm2 = new Process_Resource({
+    name: 'worker_pm2',
+    processManager: { type: 'pm2' },
+    command: process.execPath,
+    args: ['worker.js']
+});
+
+await worker_direct.start();
+console.log(worker_direct.status);
+await worker_direct.stop();
+```
+
+### Remote_Process_Resource
+
+**Purpose:** Represents a remote process controlled via HTTP API while keeping a resource-compatible interface.
+
+**Key Features:**
+- Same high-level lifecycle API as `Process_Resource`:
+  - `start()`
+  - `stop()`
+  - `restart()`
+  - `status`
+  - `get_abstract()`
+- Periodic polling of remote status endpoint
+- Emits:
+  - `state_change`
+  - `unreachable`
+  - `recovered`
+- Maintains bounded history snapshots for diagnostics
+
+**Usage:**
+```javascript
+const Remote_Process_Resource = require('jsgui3-server/resources/remote-process-resource');
+
+const remote_worker = new Remote_Process_Resource({
+    name: 'remote_worker',
+    host: '192.168.1.100',
+    port: 3400,
+    pollIntervalMs: 30000,
+    httpTimeoutMs: 6000,
+    endpoints: {
+        status: '/',
+        start: '/api/start',
+        stop: '/api/stop',
+        health: '/api/health'
+    }
+});
+
+await remote_worker.start();
+console.log(remote_worker.status);
+```
+
+### Website_Resource
+
+**Purpose:** Wraps website objects for integration with the server's resource system.
 
 **Key Features:**
 - Website object encapsulation
@@ -110,16 +220,34 @@ class Custom_Resource extends Resource {
 }
 ```
 
-### Lifecycle Management
-
-Resources follow a consistent lifecycle:
+### Lifecycle Management
+
+Resources follow a consistent lifecycle:
 
 1. **Construction**: Resource is instantiated with configuration
 2. **Registration**: Added to resource pool
 3. **Start**: Resource becomes active and available
 4. **Usage**: Resource handles requests and operations
 5. **Stop**: Resource is deactivated
-6. **Cleanup**: Resources are released
+6. **Cleanup**: Resources are released
+
+For process resources, consumers can rely on the same lifecycle API regardless of execution mode (`direct`, `pm2`, or `remote`).
+
+### Unified Process Status
+
+Both `Process_Resource` and `Remote_Process_Resource` expose a compatible `status` shape:
+
+```javascript
+{
+    state: 'running',
+    pid: 12345,
+    uptime: 61520,
+    restartCount: 1,
+    lastHealthCheck: null,
+    memoryUsage: { rssBytes: 104857600 },
+    processManager: { type: 'direct' } // or 'pm2' / 'remote'
+}
+```
 
 ### Configuration Patterns
 
@@ -171,18 +299,39 @@ class Database_Resource extends Resource {
 }
 ```
 
-### Integration with Server
-
-```javascript
-// Add to resource pool
-server.resource_pool.add(databaseResource);
+### Integration with Server
+
+```javascript
+// Add to resource pool
+server.resource_pool.add(databaseResource);
 
 // Access from other components
 const db = server.resource_pool.get_resource('Database_Resource');
-db.query('SELECT * FROM users', [], (err, results) => {
-    // Handle results
-});
-```
+db.query('SELECT * FROM users', [], (err, results) => {
+    // Handle results
+});
+```
+
+With `Server.serve()` you can register resources declaratively:
+
+```javascript
+const server = await Server.serve({
+    resources: {
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js']
+        },
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        },
+        local_cache: new In_Process_Cache_Resource({ name: 'local_cache' })
+    },
+    events: true
+});
+```
 
 ## Resource Communication Patterns
 
@@ -612,4 +761,4 @@ class Logged_Resource extends Resource {
 
 ---
 
-This guide provides the foundation for understanding and extending the resource system. For specific resource implementations, refer to their individual source files in the `resources/` directory.
+This guide provides the foundation for understanding and extending the resource system. For specific resource implementations, refer to their individual source files in the `resources/` directory.

package/docs/simple-server-api-design.md

@@ -21,7 +21,7 @@ This document explains the design principles and implementation of the simplifie
 2. **Convention Over Configuration** – Smart defaults; minimal required config
 3. **Consistent Patterns** – Same API shape at every scale
 4. **Zero-to-Hero Path** – Clear upgrade path from simple to advanced
-5. **Composable** – Mix and match features (pages, APIs, static files)
+5. **Composable** – Mix and match features (pages, APIs, static files, managed resources, SSE events)
 
 ---
 
@@ -218,7 +218,59 @@ Server.serve({
 
 ---
 
-### Layer 5: Shorthand Routes (Mixed Types)
+### Layer 5: Managed Resources + Lifecycle Events
+
+**Use Case:** Run and supervise background workers alongside your web app, with optional SSE event streaming.
+
+```javascript
+let server;
+server = await Server.serve({
+    page: {
+        content: DashboardControl,
+        title: 'Ops Dashboard'
+    },
+    resources: {
+        // In-process resource object
+        cache: new In_Process_Cache_Resource({ name: 'cache' }),
+
+        // Local process resource (default manager: direct)
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js'],
+            autoRestart: true
+        },
+
+        // PM2-backed local process (pm2Path optional)
+        worker_pm2: {
+            type: 'process',
+            processManager: { type: 'pm2' },
+            command: process.execPath,
+            args: ['worker.js']
+        },
+
+        // Remote HTTP-controlled process
+        remote_agent: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true, // enables /events SSE endpoint
+    api: {
+        'resources/summary': () => server.resource_pool.summary
+    }
+});
+```
+
+**Lifecycle conventions:**
+- Process-like resources expose the same API shape: `start()`, `stop()`, `restart()`, `status`, `get_abstract()`
+- Resource pool forwards lifecycle events (`resource_state_change`, `crashed`, `unhealthy`, `unreachable`, `recovered`)
+- `server.close()` stops managed resources and SSE publisher cleanly
+
+---
+
+### Layer 6: Shorthand Routes (Mixed Types)
 
 **Use Case:** Mix controls, functions, and static content flexibly
 
@@ -242,7 +294,7 @@ Server.serve({
 
 ---
 
-### Layer 6: Full Website Object
+### Layer 7: Full Website Object
 
 **Use Case:** Complex multi-page sites, existing `Website` instances
 
@@ -283,7 +335,7 @@ Server.serve({
 
 ---
 
-### Layer 7: Legacy/Advanced (Current API)
+### Layer 8: Legacy/Advanced (Current API)
 
 **Still fully supported for maximum control:**
 
@@ -542,12 +594,14 @@ require('../../../server').serve(require('./client').controls.Demo_UI);
 - [x] Return a Promise that resolves with the server instance
 - [x] Support Promise/async and callback patterns
 
-### Phase 2: API & Static (Partially Complete)
-- [x] `api` option for function publishing
-- [x] Auto-prefix `/api/` routes
-- [x] JSON/text content-type detection
-- [ ] `static` option for directory serving
-- [ ] MIME type detection for static files
+### Phase 2: API & Static (Partially Complete)
+- [x] `api` option for function publishing
+- [x] Auto-prefix `/api/` routes
+- [x] JSON/text content-type detection
+- [x] `resources` option for in-process/process/remote managed resources
+- [x] `events` option for built-in SSE lifecycle publisher
+- [ ] `static` option for directory serving
+- [ ] MIME type detection for static files
 
 ### Phase 3: Enhanced Features (Partially Complete)
 - [x] ENV var support (PORT, HOST, JSGUI_DEBUG)
@@ -706,10 +760,11 @@ server.on('ready', () => {
 - Promise/async support
 - Still 100% backwards compatible
 
-### Key Benefits
-1. **Faster prototyping** – from idea to running in seconds
-2. **Less boilerplate** – 90% reduction for simple cases
-3. **Better defaults** – works out of the box
-4. **Clearer intent** – code reads like configuration
-5. **Easy scaling** – simple projects grow naturally
-6. **Zero breaking changes** – all existing code still works
+### Key Benefits
+1. **Faster prototyping** – from idea to running in seconds
+2. **Less boilerplate** – 90% reduction for simple cases
+3. **Better defaults** – works out of the box
+4. **Clearer intent** – code reads like configuration
+5. **Easy scaling** – simple projects grow naturally
+6. **Zero breaking changes** – all existing code still works
+7. **Unified runtime operations** – consistent process/resource lifecycle APIs with optional SSE observability

package/docs/system-architecture.md

@@ -32,25 +32,29 @@ JSGUI3 Server is a Node.js-based web framework that serves modern JavaScript GUI
 
 **Purpose:** Handles conversion of various content types to HTTP responses.
 
-**Key Publishers:**
-- `HTTP_Webpage_Publisher`: Serves bundled JSGUI3 controls as complete web pages
-- `HTTP_Website_Publisher`: Manages multi-page websites
-- `HTTP_Function_Publisher`: Exposes JavaScript functions as REST API endpoints
-- `HTTP_CSS_Publisher`: Serves CSS stylesheets
-- `HTTP_JS_Publisher`: Serves JavaScript bundles
-- `HTTP_Image_Publisher`: Handles image file serving
+**Key Publishers:**
+- `HTTP_Webpage_Publisher`: Serves bundled JSGUI3 controls as complete web pages
+- `HTTP_Website_Publisher`: Manages multi-page websites
+- `HTTP_Function_Publisher`: Exposes JavaScript functions as REST API endpoints
+- `HTTP_Observable_Publisher`: Streams observable-backed SSE
+- `HTTP_SSE_Publisher`: General-purpose SSE fan-out publisher
+- `HTTP_CSS_Publisher`: Serves CSS stylesheets
+- `HTTP_JS_Publisher`: Serves JavaScript bundles
+- `HTTP_Image_Publisher`: Handles image file serving
 
 ### 3. Resource Management Layer
 **Directory:** `resources/`
 
 **Purpose:** Provides abstractions for accessing different types of data and functionality.
 
-**Key Resources:**
-- `Server_Resource_Pool`: Manages collections of resources with lifecycle management
-- `Website_Resource`: Wraps website objects for server integration
-- `File_System_Resource`: Provides file system access
-- `Data_Resource`: Handles data storage and retrieval
-- `Local_Server_Info_Resource`: Provides server environment information
+**Key Resources:**
+- `Server_Resource_Pool`: Manages collections of resources with lifecycle management
+- `Process_Resource`: Local process resource (`direct` default, optional `pm2`)
+- `Remote_Process_Resource`: HTTP-controlled remote process resource
+- `Website_Resource`: Wraps website objects for server integration
+- `File_System_Resource`: Provides file system access
+- `Data_Resource`: Handles data storage and retrieval
+- `Local_Server_Info_Resource`: Provides server environment information
 
 ### 4. Processing Layer
 **Directory:** `resources/processors/`
@@ -272,4 +276,4 @@ Add new processing pipelines for assets and data.
 
 ---
 
-This architecture document provides the foundation for understanding how JSGUI3 Server components work together. For detailed implementation of specific components, refer to their individual documentation files.
+This architecture document provides the foundation for understanding how JSGUI3 Server components work together. For detailed implementation of specific components, refer to their individual documentation files.

package/examples/controls/15) window, observable SSE/server.js

@@ -64,13 +64,18 @@ if (require.main === module) {
         });
 
         // Register the SSE endpoint with the server's router
+        // You can use the manual approach (full control):
         server.server_router.set_route('/api/tick-stream', tick_publisher, tick_publisher.handle_http);
         console.log('  ✓ /api/tick-stream - Hot tick stream (SSE)');
 
+        // Or use the simplified API (auto-prefixes /api/ for simple names):
+        // server.publish_observable('tick-stream', tick_observable);
+
         // ========================================
         // Also publish a simple JSON API endpoint for comparison
         // ========================================
-        server.publish('/api/status', () => {
+        // Simple name (auto-prefixes /api/)
+        server.publish('status', () => {
             return {
                 status: 'ok',
                 tick_count: tick_count,

package/examples/controls/19) window, auto observable ui/server.js

@@ -54,6 +54,15 @@ if (require.main === module) {
         };
         server.publish_observable('/api/logs', obs_logs);
 
+        // Expose Status Diagram
+        server.publish('/dev-status.svg', (req, res) => {
+            const fs = require('fs');
+            const path = require('path');
+            const filePath = path.join(__dirname, '../../../../dev-status.svg');
+            res.setHeader('Content-Type', 'image/svg+xml');
+            fs.createReadStream(filePath).pipe(res);
+        });
+
         // Start
         const port = 52100;
         server.start(port, (err) => {

package/examples/controls/20) window, task manager app/README.md

@@ -0,0 +1,133 @@
+# 20) Task Manager Application
+
+A comprehensive example demonstrating a multi-window task management application built with jsgui3.
+
+## Features
+
+- **Multiple Windows**: Main task manager window + floating quick-add window
+- **Tabbed Interface**: Tasks, Projects, and Stats tabs in the main window
+- **Data Binding**: Uses `Data_Object` and `field()` for reactive state management
+- **API Integration**: Full CRUD operations via `server.publish()` endpoints
+- **Interactive Controls**: Checkboxes, text inputs, select dropdowns, buttons
+- **Real-time Updates**: UI updates immediately after API responses
+- **Statistics Dashboard**: Tracks completion rates with visual progress bar
+
+## Running the Example
+
+```bash
+cd examples/controls/20) window, task manager app
+node server.js
+```
+
+Then open http://localhost:52021 in your browser.
+
+## Architecture
+
+### Client (`client.js`)
+
+The `Task_Manager_App` class extends `Active_HTML_Document` and demonstrates:
+
+1. **Data Model Setup**:
+   ```javascript
+   this.data = { model: new Data_Object({ context }) };
+   field(this.data.model, 'tasks');
+   field(this.data.model, 'projects');
+   field(this.data.model, 'stats');
+   ```
+
+2. **Multiple Windows**:
+   ```javascript
+   const main_window = new controls.Window({ context, title: 'Task Manager', pos: [20, 20] });
+   const quick_add_window = new controls.Window({ context, title: 'Quick Add Task', pos: [540, 20] });
+   ```
+
+3. **Tabbed Panel**:
+   ```javascript
+   const main_tabs = new controls.Tabbed_Panel({
+       context,
+       tabs: [
+           ['Tasks', this._create_tasks_panel(context)],
+           ['Projects', this._create_projects_panel(context)],
+           ['Stats', this._create_stats_panel(context)]
+       ]
+   });
+   ```
+
+4. **API Calls**:
+   ```javascript
+   async _add_task() {
+       const response = await fetch('/api/tasks/add', {
+           method: 'POST',
+           headers: { 'Content-Type': 'application/json' },
+           body: JSON.stringify({ text, project })
+       });
+       const result = await response.json();
+       // Update UI...
+   }
+   ```
+
+### Server (`server.js`)
+
+Uses the simple `server.publish()` API for endpoints:
+
+```javascript
+// GET /api/tasks/list
+server.publish('tasks/list', () => ({ tasks: get_tasks() }));
+
+// POST /api/tasks/add
+server.publish('tasks/add', (data) => {
+    const new_task = { id: next_id++, text: data.text, ... };
+    tasks.push(new_task);
+    return { success: true, tasks: get_tasks() };
+});
+```
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/tasks/list` | Get all tasks |
+| POST | `/api/tasks/add` | Add a new task |
+| POST | `/api/tasks/toggle` | Toggle task completion |
+| POST | `/api/tasks/delete` | Delete a task |
+| POST | `/api/tasks/clear-completed` | Remove completed tasks |
+| GET | `/api/stats` | Get statistics by project |
+
+## UI Components Used
+
+- `Window` - Draggable, resizable window containers
+- `Tabbed_Panel` - Tab navigation between views
+- `Text_Field` - Text input for task descriptions
+- `Select_Options` - Dropdown for project selection
+- `Button` - Action buttons with click handlers
+- `Checkbox` - Task completion (rendered dynamically)
+
+## Key Patterns Demonstrated
+
+1. **Control References**: Storing component references for later access
+   ```javascript
+   this._ctrl_fields = { main_window, main_tabs, quick_add_window };
+   ```
+
+2. **Conditional Composition**: Only compose if not hydrating from DOM
+   ```javascript
+   if (!spec.el) { compose(); }
+   ```
+
+3. **Activation Guard**: Prevent double-activation
+   ```javascript
+   if (!this.__active) { super.activate(); ... }
+   ```
+
+4. **CSS as Static Property**: Scoped styles
+   ```javascript
+   Task_Manager_App.css = `...`;
+   ```
+
+## Customization Ideas
+
+- Add task due dates with `Date_Picker`
+- Implement drag-and-drop task reordering
+- Add task priority levels
+- Connect to a real database instead of in-memory store
+- Add real-time updates with `publish_observable` for multi-user sync