jsgui3-server 0.0.150 → 0.0.152

package/docs/comprehensive-documentation.md

@@ -15,7 +15,7 @@ This document provides detailed technical documentation for the JSGUI3 Server fr
 - You're troubleshooting complex issues or performance problems
 - You need to understand deployment, security, and production considerations
 
-**Note:** Start with [README.md](../README.md) for project overview and basic usage. For server API design principles, see [docs/simple-server-api-design.md](docs/simple-server-api-design.md). For bundling internals and elimination strategy research, see [docs/books/jsgui3-bundling-research-book/README.md](docs/books/jsgui3-bundling-research-book/README.md).
+**Note:** Start with [README.md](../README.md) for project overview and basic usage. For server API design principles, see [docs/simple-server-api-design.md](docs/simple-server-api-design.md). For bundling internals and elimination strategy research, see [docs/books/jsgui3-bundling-research-book/README.md](docs/books/jsgui3-bundling-research-book/README.md).
 
 # JSGUI3 Server - Comprehensive Documentation
 
@@ -27,24 +27,24 @@ The server acts as a bridge between server-side JavaScript applications and brow
 
 ## Table of Contents
 
-1. [Quick Start](#quick-start)
-2. [AI Agent Fast Start](#ai-agent-fast-start)
-3. [Architecture Overview](#architecture-overview)
-4. [Core Components](#core-components)
-5. [Installation and Setup](#installation-and-setup)
-6. [Configuration](#configuration)
-7. [API Reference](#api-reference)
-8. [Examples](#examples)
-9. [Development](#development)
-10. [Troubleshooting](#troubleshooting)
-11. [Deployment & Production](#deployment--production)
-12. [Contributing](#contributing)
-13. [Code Style Guidelines](#code-style-guidelines)
-14. [License](#license)
-15. [Changelog](#changelog)
-16. [Support](#support)
-17. [Roadmap](#roadmap)
-18. [MVVM and Full-Stack Controls](#mvvm-and-full-stack-controls)
+1. [Quick Start](#quick-start)
+2. [AI Agent Fast Start](#ai-agent-fast-start)
+3. [Architecture Overview](#architecture-overview)
+4. [Core Components](#core-components)
+5. [Installation and Setup](#installation-and-setup)
+6. [Configuration](#configuration)
+7. [API Reference](#api-reference)
+8. [Examples](#examples)
+9. [Development](#development)
+10. [Troubleshooting](#troubleshooting)
+11. [Deployment & Production](#deployment--production)
+12. [Contributing](#contributing)
+13. [Code Style Guidelines](#code-style-guidelines)
+14. [License](#license)
+15. [Changelog](#changelog)
+16. [Support](#support)
+17. [Roadmap](#roadmap)
+18. [MVVM and Full-Stack Controls](#mvvm-and-full-stack-controls)
 
 ## Quick Start
 
@@ -99,43 +99,43 @@ Server.serve({
 
 ### With API Endpoints
 
-```javascript
-Server.serve({
-    ctrl: DashboardControl,
-    src_path_client_js: require.resolve('./client.js'),
-    api: {
-        'metrics': () => ({ users: 1234, revenue: 56789 }),
-        'data': async ({ range }) => await fetchAnalytics(range)
-    },
-    port: 3000
-});
-```
-
-## AI Agent Fast Start
-
-This section is a short, task-oriented runway for AI agents that need to act quickly with minimal overhead.
-
-**Start here:**
-1. Identify the target subsystem: examples, bundlers, publishers, or controls.
-2. Jump to the focused guide: `docs/books/jsgui3-mvvm-fullstack/README.md`.
-3. For bundle-size and pruning work, use: `docs/books/jsgui3-bundling-research-book/README.md`.
-4. Make the smallest change that can pass a targeted test.
-5. Run the narrow test file first, then widen if needed.
-
-**Minimal commands:**
-```bash
-rg -n "needle" path/
-rg --files path/
-node tests/test-runner.js --test=examples-controls.e2e.test.js
-node tests/test-runner.js --test=window-examples.puppeteer.test.js
-```
-
-**Known fast checks:**
-- Render server-side quickly with `Server_Static_Page_Context`.
-- Confirm a control is exported under `jsgui.controls`.
-- Ensure composition happens only when `!spec.el`.
-
-## Architecture Overview
+```javascript
+Server.serve({
+    ctrl: DashboardControl,
+    src_path_client_js: require.resolve('./client.js'),
+    api: {
+        'metrics': () => ({ users: 1234, revenue: 56789 }),
+        'data': async ({ range }) => await fetchAnalytics(range)
+    },
+    port: 3000
+});
+```
+
+## AI Agent Fast Start
+
+This section is a short, task-oriented runway for AI agents that need to act quickly with minimal overhead.
+
+**Start here:**
+1. Identify the target subsystem: examples, bundlers, publishers, or controls.
+2. Jump to the focused guide: `docs/books/jsgui3-mvvm-fullstack/README.md`.
+3. For bundle-size and pruning work, use: `docs/books/jsgui3-bundling-research-book/README.md`.
+4. Make the smallest change that can pass a targeted test.
+5. Run the narrow test file first, then widen if needed.
+
+**Minimal commands:**
+```bash
+rg -n "needle" path/
+rg --files path/
+node tests/test-runner.js --test=examples-controls.e2e.test.js
+node tests/test-runner.js --test=window-examples.puppeteer.test.js
+```
+
+**Known fast checks:**
+- Render server-side quickly with `Server_Static_Page_Context`.
+- Confirm a control is exported under `jsgui.controls`.
+- Ensure composition happens only when `!spec.el`.
+
+## Architecture Overview
 
 ### Core Architecture
 
@@ -238,97 +238,97 @@ JSGUI3 provides a rich set of UI controls:
 - **Button**: Interactive button control
 - **Text_Input**: Text input field
 - **Checkbox**: Boolean input control
-- **Date_Picker**: Date selection control
-- **Month_View**: Calendar display
-- **Menu**: Dropdown menu control
-
-## MVVM and Full-Stack Controls
-
-For a complete, step-by-step walkthrough of MVVM binding and full-stack control usage, use:
-`docs/books/jsgui3-mvvm-fullstack/README.md`
-
-### Minimal Full-Stack Control Example
-
-```javascript
-const jsgui = require('jsgui3-client');
-const { controls } = jsgui;
-const Active_HTML_Document = require('jsgui3-server/controls/Active_HTML_Document');
-
-class Demo_UI extends Active_HTML_Document {
-    constructor(spec = {}) {
-        spec.__type_name = spec.__type_name || 'demo_ui';
-        super(spec);
-        const { context } = this;
-        if (!spec.el) {
-            const window_ctrl = new controls.Window({
-                context,
-                title: 'Hello JSGUI3'
-            });
-            this.body.add(window_ctrl);
-        }
-    }
-}
-
-controls.Demo_UI = Demo_UI;
-module.exports = jsgui;
-```
-
-```javascript
-const Server = require('jsgui3-server');
-const { Demo_UI } = require('./client').controls;
-
-Server.serve({
-    ctrl: Demo_UI,
-    src_path_client_js: require.resolve('./client.js'),
-    port: 3000
-});
-```
-
-### MVVM Binding Skeleton
-
-```javascript
-const jsgui = require('jsgui3-client');
-const { controls, Control } = jsgui;
-
-const set_model_value = (model, name, value) => {
-    if (!model) return;
-    if (typeof model.set === 'function') {
-        model.set(name, value);
-    } else {
-        model[name] = value;
-    }
-};
-
-class Profile_Panel extends Control {
-    constructor(spec = {}) {
-        spec.__type_name = spec.__type_name || 'profile_panel';
-        super(spec);
-        if (!spec.el) {
-            const { context } = this;
-            const name_input = new controls.Text_Input({ context });
-            this.add(name_input);
-            this.name_input = name_input;
-        }
-        this.setup_bindings();
-    }
-
-    setup_bindings() {
-        const data_model = this.data && this.data.model;
-        if (!data_model || !this.name_input) return;
-        this.watch(data_model, 'full_name', value => {
-            this.name_input.set_value(value || '');
-        });
-        this.name_input.on('input', () => {
-            set_model_value(data_model, 'full_name', this.name_input.get_value());
-        });
-    }
-}
-
-controls.Profile_Panel = Profile_Panel;
-module.exports = jsgui;
-```
-
-## Installation and Setup
+- **Date_Picker**: Date selection control
+- **Month_View**: Calendar display
+- **Menu**: Dropdown menu control
+
+## MVVM and Full-Stack Controls
+
+For a complete, step-by-step walkthrough of MVVM binding and full-stack control usage, use:
+`docs/books/jsgui3-mvvm-fullstack/README.md`
+
+### Minimal Full-Stack Control Example
+
+```javascript
+const jsgui = require('jsgui3-client');
+const { controls } = jsgui;
+const Active_HTML_Document = require('jsgui3-server/controls/Active_HTML_Document');
+
+class Demo_UI extends Active_HTML_Document {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'demo_ui';
+        super(spec);
+        const { context } = this;
+        if (!spec.el) {
+            const window_ctrl = new controls.Window({
+                context,
+                title: 'Hello JSGUI3'
+            });
+            this.body.add(window_ctrl);
+        }
+    }
+}
+
+controls.Demo_UI = Demo_UI;
+module.exports = jsgui;
+```
+
+```javascript
+const Server = require('jsgui3-server');
+const { Demo_UI } = require('./client').controls;
+
+Server.serve({
+    ctrl: Demo_UI,
+    src_path_client_js: require.resolve('./client.js'),
+    port: 3000
+});
+```
+
+### MVVM Binding Skeleton
+
+```javascript
+const jsgui = require('jsgui3-client');
+const { controls, Control } = jsgui;
+
+const set_model_value = (model, name, value) => {
+    if (!model) return;
+    if (typeof model.set === 'function') {
+        model.set(name, value);
+    } else {
+        model[name] = value;
+    }
+};
+
+class Profile_Panel extends Control {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'profile_panel';
+        super(spec);
+        if (!spec.el) {
+            const { context } = this;
+            const name_input = new controls.Text_Input({ context });
+            this.add(name_input);
+            this.name_input = name_input;
+        }
+        this.setup_bindings();
+    }
+
+    setup_bindings() {
+        const data_model = this.data && this.data.model;
+        if (!data_model || !this.name_input) return;
+        this.watch(data_model, 'full_name', value => {
+            this.name_input.set_value(value || '');
+        });
+        this.name_input.on('input', () => {
+            set_model_value(data_model, 'full_name', this.name_input.get_value());
+        });
+    }
+}
+
+controls.Profile_Panel = Profile_Panel;
+module.exports = jsgui;
+```
+
+## Installation and Setup
 
 ### Prerequisites
 
@@ -396,30 +396,30 @@ body {
 }
 `;
 
-controls.MyControl = MyControl;
-module.exports = jsgui;
-```
-
-    SCSS/SASS: You can also set `MyControl.scss` or `MyControl.sass` using template literals. These are compiled to CSS during bundling and removed from the JS output, just like `.css`. CSS and SCSS blocks can be mixed in a control; the bundler preserves their order during compilation. If you mix indented `.sass` with `.scss`/`.css`, each block is compiled independently to preserve order. Inline CSS sourcemaps are emitted only when a single compilation pass is used; mixed syntax skips inline maps to keep them accurate.
-
-    To enable inline CSS sourcemaps for Sass/SCSS outputs, pass a `style` configuration:
-
-    ```javascript
-    Server.serve({
-        ctrl: MyControl,
-        src_path_client_js: require.resolve('./client.js'),
-        debug: true,
-        style: {
-            sourcemaps: {
-                enabled: true,
-                inline: true,
-                include_sources: true
-            }
-        }
-    });
-    ```
-
-2. Create server:
+controls.MyControl = MyControl;
+module.exports = jsgui;
+```
+
+    SCSS/SASS: You can also set `MyControl.scss` or `MyControl.sass` using template literals. These are compiled to CSS during bundling and removed from the JS output, just like `.css`. CSS and SCSS blocks can be mixed in a control; the bundler preserves their order during compilation. If you mix indented `.sass` with `.scss`/`.css`, each block is compiled independently to preserve order. Inline CSS sourcemaps are emitted only when a single compilation pass is used; mixed syntax skips inline maps to keep them accurate.
+
+    To enable inline CSS sourcemaps for Sass/SCSS outputs, pass a `style` configuration:
+
+    ```javascript
+    Server.serve({
+        ctrl: MyControl,
+        src_path_client_js: require.resolve('./client.js'),
+        debug: true,
+        style: {
+            sourcemaps: {
+                enabled: true,
+                inline: true,
+                include_sources: true
+            }
+        }
+    });
+    ```
+
+2. Create server:
 
 ```javascript
 // server.js
@@ -490,16 +490,16 @@ Main entry point for starting the server.
 **Parameters:**
 - `options` (object): Server configuration object
 
-**Options:**
-- `ctrl` or `Ctrl`: Main control class constructor
-- `pages`: Object defining multiple pages with routes as keys
-- `api`: Object defining API endpoints
-- `resources`: Object/array of managed resource definitions
-- `events`: Enable/configure built-in SSE endpoint for resource lifecycle events
-- `src_path_client_js`: Path to client-side JavaScript file
-- `port`: Server port (default: 8080)
-- `host`: Server host (default: all IPv4 interfaces)
-- `debug`: Enable debug mode (default: false)
+**Options:**
+- `ctrl` or `Ctrl`: Main control class constructor
+- `pages`: Object defining multiple pages with routes as keys
+- `api`: Object defining API endpoints
+- `resources`: Object/array of managed resource definitions
+- `events`: Enable/configure built-in SSE endpoint for resource lifecycle events
+- `src_path_client_js`: Path to client-side JavaScript file
+- `port`: Server port (default: 8080)
+- `host`: Server host (default: all IPv4 interfaces)
+- `debug`: Enable debug mode (default: false)
 
 **Returns:** Promise that resolves to the server instance
 
@@ -530,45 +530,45 @@ const server = await Server.serve({
     port: 3000
 });
 
-// With API endpoints
-const server = await Server.serve({
-    ctrl: DashboardControl,
+// With API endpoints
+const server = await Server.serve({
+    ctrl: DashboardControl,
     src_path_client_js: require.resolve('./client.js'),
     api: {
         'status': () => ({ uptime: process.uptime() }),
         'users': async () => await getUsers()
-    },
-    port: 3000
-});
-
-// With managed resources and SSE lifecycle events
-let server_with_resources;
-server_with_resources = await Server.serve({
-    api: {
-        'resources/summary': () => server_with_resources.resource_pool.summary
-    },
-    resources: {
-        worker_direct: {
-            type: 'process',
-            command: process.execPath,
-            args: ['worker.js'],
-            autoRestart: true
-        },
-        worker_pm2: {
-            type: 'process',
-            processManager: { type: 'pm2' }, // pm2Path optional
-            command: process.execPath,
-            args: ['worker.js']
-        },
-        remote_worker: {
-            type: 'remote',
-            host: '127.0.0.1',
-            port: 3400
-        }
-    },
-    events: true // creates /events and forwards resource lifecycle events
-});
-```
+    },
+    port: 3000
+});
+
+// With managed resources and SSE lifecycle events
+let server_with_resources;
+server_with_resources = await Server.serve({
+    api: {
+        'resources/summary': () => server_with_resources.resource_pool.summary
+    },
+    resources: {
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js'],
+            autoRestart: true
+        },
+        worker_pm2: {
+            type: 'process',
+            processManager: { type: 'pm2' }, // pm2Path optional
+            command: process.execPath,
+            args: ['worker.js']
+        },
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true // creates /events and forwards resource lifecycle events
+});
+```
 
 ### Publishers API
 
@@ -1110,7 +1110,7 @@ const server = Server.serve({
     debug: false,  // Disable for production
     // Additional production settings
     max_age: 86400,  // Cache static assets for 24 hours
-    compress: true    // Enable gzip compression
+    compression: true    // Enable gzip/deflate/brotli compression
 });
 ```
 
@@ -1300,8 +1300,8 @@ Server.serve({
     src_path_client_js: require.resolve('./client.js'),
     // Cache static assets
     max_age: 86400,  // 24 hours
-    // Enable compression
-    compress: true,
+    // Enable compression (gzip/deflate/brotli via built-in middleware)
+    compression: true,
     // Optimize bundling
     debug: false
 });
@@ -1561,4 +1561,4 @@ MIT License - see LICENSE file for details.
 ---
 
 This documentation provides a comprehensive overview of JSGUI3 Server. For more detailed information about specific components, see the individual files in the `docs/` directory and the examples in `examples/`.</content>
-<parameter name="filePath">c:\\Users\\james\\Documents\\repos\\jsgui3-server\\docs\\comprehensive-documentation.md
+<parameter name="filePath">c:\\Users\\james\\Documents\\repos\\jsgui3-server\\docs\\comprehensive-documentation.md