jsgui3-server 0.0.148 → 0.0.150

package/docs/publishers-guide.md

@@ -100,7 +100,7 @@ const publisher = new HTTP_Function_Publisher({
 - Support for common image formats (JPEG, PNG, SVG, etc.)
 - Efficient streaming for large files
 
-### HTTP_Observable_Publisher
+### HTTP_Observable_Publisher
 
 **Purpose:** Streams observable data to clients using Server-Sent Events (SSE).
 
@@ -190,9 +190,64 @@ data: {"tick":1,"timestamp":1234567890,"message":"Server tick #1"}
 data: {"tick":2,"timestamp":1234567891,"message":"Server tick #2"}
 ```
 
-**See Also:** [Observable SSE Demo](../examples/controls/15)%20window,%20observable%20SSE/) for a complete working example.
-
-## Publisher Architecture
+**See Also:** [Observable SSE Demo](../examples/controls/15)%20window,%20observable%20SSE/) for a complete working example.
+
+### HTTP_SSE_Publisher
+
+**Purpose:** General-purpose Server-Sent Events publisher for manual event fan-out (not tied to an observable source).
+
+**Key Features:**
+- SSE client connection registry with `client_count`
+- `broadcast(event_name, data)` for fan-out to all clients
+- `send(client_id, event_name, data)` for targeted delivery
+- Keepalive comments (`:keepalive`) to prevent idle proxy timeouts
+- Last-Event-ID replay support for reconnecting clients
+- Optional max-client limit
+- Emits:
+  - `client_connected`
+  - `client_disconnected`
+
+**Usage:**
+```javascript
+const HTTP_SSE_Publisher = require('jsgui3-server/publishers/http-sse-publisher');
+
+const sse_publisher = new HTTP_SSE_Publisher({
+    name: 'events',
+    keepaliveIntervalMs: 15000,
+    maxClients: 100
+});
+
+server.server_router.set_route('/events', sse_publisher, sse_publisher.handle_http);
+
+sse_publisher.broadcast('resource_state_change', {
+    resourceName: 'worker_1',
+    from: 'running',
+    to: 'crashed'
+});
+```
+
+**With `Server.serve()` Auto Wiring:**
+```javascript
+const server = await Server.serve({
+    events: true,
+    resources: {
+        worker_1: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js']
+        }
+    }
+});
+
+// SSE endpoint is available at /events by default.
+```
+
+### Choosing an SSE Publisher
+
+- Use `HTTP_Observable_Publisher` when your source is an observable stream.
+- Use `HTTP_SSE_Publisher` when you need explicit event push control (`broadcast`/`send`) from arbitrary server logic.
+
+## Publisher Architecture
 
 ### Base Publisher Class
 

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/docs/troubleshooting.md

@@ -197,14 +197,14 @@ input.js:1:0: ERROR: Expected identifier but found "}"
 
 2. **Verify CSS definition:**
    ```javascript
-   MyControl.css = `
-   .my-control {
-       padding: 20px;
-       background: #f0f0f0;
-   }
-   `;
-   ```
-   You can also use `MyControl.scss` or `MyControl.sass` with template literals; these compile to CSS during bundling (ensure the `sass` dependency is installed). To see inline CSS sourcemaps in devtools, enable `style.sourcemaps` (or run with `debug: true`).
+   MyControl.css = `
+   .my-control {
+       padding: 20px;
+       background: #f0f0f0;
+   }
+   `;
+   ```
+   You can also use `MyControl.scss` or `MyControl.sass` with template literals; these compile to CSS during bundling (ensure the `sass` dependency is installed). To see inline CSS sourcemaps in devtools, enable `style.sourcemaps` (or run with `debug: true`).
 
 3. **Check activation:**
    ```javascript
@@ -540,6 +540,37 @@ from origin 'http://localhost:3000' has been blocked by CORS policy
    delete require.cache[require.resolve('./client.js')];
    ```
 
+### Generated `.jsgui3-server-cache` Shim Files
+
+**Symptoms:**
+- You see many changed files under `.jsgui3-server-cache/jsgui3-html-shims/`
+- Shim files contain absolute machine-specific paths
+- Git status looks noisy after running examples or admin pages
+
+**What this is:**
+- These are generated cache artifacts created by the bundling/render pipeline.
+- They are performance helpers, not source-of-truth project files.
+
+**Expected behavior:**
+1. They may be regenerated when controls, environment, or module resolution changes.
+2. They can differ across machines (for example, local `node_modules` path vs NVM/global path).
+3. They are safe to delete; they will be recreated when needed.
+
+**Recommended project hygiene:**
+1. Ignore cache directories in `.gitignore`:
+   ```gitignore
+   .jsgui3-server-cache/
+   **/.jsgui3-server-cache/
+   ```
+2. If accidentally changed, revert generated shims:
+   ```bash
+   git restore -- .jsgui3-server-cache/jsgui3-html-shims/*.js
+   ```
+3. If a nested example cache appears, remove it:
+   ```bash
+   rm -rf "examples/controls/1) window/.jsgui3-server-cache"
+   ```
+
 ### Source Maps Not Working
 
 **Symptoms:**
@@ -743,48 +774,48 @@ controls.MinimalControl = MinimalControl;
 module.exports = jsgui;
 ```
 
-This minimal setup helps isolate whether the issue is with your specific code or the framework itself.
-
----
-
-## Bundling and Test Failures
-
-### `waiting for wp_publisher ready` or Publisher Ready Timeout
-
-**Symptoms:**
-- Tests hang while starting servers
-- Logs show `waiting for wp_publisher ready`
-- Tests time out without a clear stack trace
-
-**Likely cause:** the JS/CSS bundler failed before emitting `ready`.
-
-**What to check:**
-1. Look earlier in the log for bundler errors (esbuild, Sass, file resolution).
-2. Confirm `sass` is installed if you are running Sass tests.
-3. Validate the client entry path passed to `src_path_client_js`.
-
-### esbuild platform mismatch (Windows vs WSL)
-
-**Symptoms:**
-- Error: `You installed esbuild for another platform than the one you're currently using`
-
-**Cause:** `node_modules` was installed on a different OS and reused in this environment.
-
-**Fix:**
-1. Remove the existing `node_modules` from the current workspace.
-2. Reinstall dependencies in the current environment:
-   ```bash
-   npm install
-   ```
-3. If you prefer to keep the lockfile untouched, use:
-   ```bash
-   npm ci
-   ```
-4. As a fast workaround, you can try:
-   ```bash
-   npm rebuild esbuild
-   ```
-
----
-
-Remember: Most issues can be resolved by carefully checking the console output, verifying file paths, and ensuring proper control lifecycle management. Start with the basics and work systematically through the possible causes.
+This minimal setup helps isolate whether the issue is with your specific code or the framework itself.
+
+---
+
+## Bundling and Test Failures
+
+### `waiting for wp_publisher ready` or Publisher Ready Timeout
+
+**Symptoms:**
+- Tests hang while starting servers
+- Logs show `waiting for wp_publisher ready`
+- Tests time out without a clear stack trace
+
+**Likely cause:** the JS/CSS bundler failed before emitting `ready`.
+
+**What to check:**
+1. Look earlier in the log for bundler errors (esbuild, Sass, file resolution).
+2. Confirm `sass` is installed if you are running Sass tests.
+3. Validate the client entry path passed to `src_path_client_js`.
+
+### esbuild platform mismatch (Windows vs WSL)
+
+**Symptoms:**
+- Error: `You installed esbuild for another platform than the one you're currently using`
+
+**Cause:** `node_modules` was installed on a different OS and reused in this environment.
+
+**Fix:**
+1. Remove the existing `node_modules` from the current workspace.
+2. Reinstall dependencies in the current environment:
+   ```bash
+   npm install
+   ```
+3. If you prefer to keep the lockfile untouched, use:
+   ```bash
+   npm ci
+   ```
+4. As a fast workaround, you can try:
+   ```bash
+   npm rebuild esbuild
+   ```
+
+---
+
+Remember: Most issues can be resolved by carefully checking the console output, verifying file paths, and ensuring proper control lifecycle management. Start with the basics and work systematically through the possible causes.

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,