jsgui3-server 0.0.147 → 0.0.149

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/client.js

@@ -0,0 +1,125 @@
+const jsgui = require('jsgui3-client');
+const { controls, Control } = jsgui;
+const Auto_Observable_UI = require('../../../client/controls/auto-observable');
+controls.Auto_Observable_UI = Auto_Observable_UI;
+
+const Active_HTML_Document = require('../../../controls/Active_HTML_Document');
+
+class Demo_Page extends Active_HTML_Document {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'demo_page';
+        super(spec);
+        const { context } = this;
+
+        if (typeof this.body.add_class === 'function') {
+            this.body.add_class('demo-page');
+        }
+
+        const compose = () => {
+            const h1 = new controls.h1({ context });
+            h1.add('Auto Observable UI Demo');
+            this.body.add(h1);
+
+            const container = new controls.div({ context, class: 'params-container' });
+            this.body.add(container);
+
+            // 1. Tick Counter (Int)
+            const ui_tick = new Auto_Observable_UI({
+                context,
+                url: '/api/tick',
+                class: 'param-ui'
+            });
+            container.add(ui_tick);
+
+            // 2. CPU Load (Gauge)
+            const ui_cpu = new Auto_Observable_UI({
+                context,
+                url: '/api/cpu',
+                class: 'param-ui'
+            });
+            container.add(ui_cpu);
+
+            // 3. System Logs (Log)
+            const ui_log = new Auto_Observable_UI({
+                context,
+                url: '/api/logs',
+                class: 'param-ui span-2'
+            });
+            container.add(ui_log);
+        };
+
+        if (!spec.el) {
+            compose();
+        }
+    }
+}
+
+Demo_Page.css = `
+body {
+    background: #222;
+    color: #eee;
+    font-family: sans-serif;
+    padding: 20px;
+}
+.params-container {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 20px;
+    max-width: 800px;
+}
+.param-ui {
+    background: #333;
+    padding: 15px;
+    border-radius: 8px;
+    box-shadow: 0 2px 10px rgba(0,0,0,0.5);
+}
+.span-2 {
+    grid-column: span 2;
+}
+.value-display {
+    text-align: center;
+}
+.value-text {
+    font-size: 3em;
+    font-weight: bold;
+    color: #4facfe;
+}
+.progress-bg {
+    background: #444;
+    height: 20px;
+    border-radius: 10px;
+    overflow: hidden;
+    margin: 10px 0;
+}
+.progress-fill {
+    background: linear-gradient(90deg, #4facfe 0%, #00f2fe 100%);
+    height: 100%;
+    width: 0%;
+    transition: width 0.3s ease;
+}
+.log-area {
+    height: 150px;
+    background: #111;
+    overflow-y: auto;
+    text-align: left;
+    padding: 10px;
+    font-family: monospace;
+    font-size: 0.9em;
+    border: 1px solid #444;
+}
+.log-entry {
+    margin-bottom: 4px;
+    border-bottom: 1px solid #222;
+}
+.status-indicator {
+    font-size: 0.8em;
+    text-transform: uppercase;
+    margin-bottom: 5px;
+    color: #888;
+}
+.status-connected { color: #0f0; }
+.status-error { color: #f00; }
+`;
+
+module.exports = jsgui;
+controls.Demo_Page = Demo_Page;

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

@@ -0,0 +1,73 @@
+const jsgui = require('./client');
+const Server = require('../../../server');
+const { Demo_Page } = jsgui.controls;
+const { observable } = require('fnl');
+
+if (require.main === module) {
+    const server = new Server({
+        Ctrl: Demo_Page,
+        src_path_client_js: require.resolve('./client.js')
+    });
+
+    server.on('ready', () => {
+        // 1. Tick Observable
+        const obs_tick = observable((next) => {
+            let i = 0;
+            const timer = setInterval(() => next(++i), 1000);
+            return () => clearInterval(timer);
+        });
+        // Attach schema manually (or could be done via helper)
+        obs_tick.schema = {
+            name: 'Uptime (Seconds)',
+            type: 'int'
+        };
+        server.publish_observable('/api/tick', obs_tick);
+
+        // 2. CPU Observable (Simulated)
+        const obs_cpu = observable((next) => {
+            const timer = setInterval(() => {
+                const load = 40 + Math.random() * 30;
+                next(Math.floor(load));
+            }, 500);
+            return () => clearInterval(timer);
+        });
+        obs_cpu.schema = {
+            name: 'CPU Load',
+            type: 'number',
+            min: 0,
+            max: 100
+        };
+        server.publish_observable('/api/cpu', obs_cpu);
+
+        // 3. Logs Observable
+        const obs_logs = observable((next) => {
+            const msgs = ['System check OK', 'Request received', 'Cache invalidated', 'User login', 'Background job started'];
+            const timer = setInterval(() => {
+                const msg = msgs[Math.floor(Math.random() * msgs.length)];
+                next({ message: msg, level: 'info' });
+            }, 2000);
+            return () => clearInterval(timer);
+        });
+        obs_logs.schema = {
+            name: 'Server Logs',
+            type: 'log'
+        };
+        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) => {
+            if (err) throw err;
+            console.log(`Demo running at http://localhost:${port}`);
+        });
+    });
+}

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