jsgui3-server 0.0.148 → 0.0.149

package/docs/api-reference.md

@@ -32,13 +32,30 @@ Server.serve(options?: ServerOptions): Promise<Server>
 - `DiscoveryError`: Cannot find client files or controls
 - `BindingError`: Cannot bind to specified host/port
 
-**Example:**
-```javascript
-const server = await Server.serve({
-    port: 3000,
-    ctrl: MyControl
-});
-```
+**Example:**
+```javascript
+const server = await Server.serve({
+    port: 3000,
+    ctrl: MyControl,
+    resources: {
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js']
+        },
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true
+});
+```
+
+**Serve-specific options:**
+- `resources`: Registers managed resources (in-process resource objects, local process resources, remote HTTP process resources).
+- `events`: Enables built-in SSE publisher for resource lifecycle events (`/events` by default).
 
 ### Server Constructor
 
@@ -54,12 +71,27 @@ new Server(options?: ServerOptions)
 
 **Returns:** Server instance
 
-**Events:**
-- `'ready'`: Emitted when bundling is complete
-- `'started'`: Emitted when HTTP server is listening
-- `'error'`: Emitted on server errors
-
-## Server Instance Methods
+**Events:**
+- `'ready'`: Emitted when bundling is complete
+- `'started'`: Emitted when HTTP server is listening
+- `'error'`: Emitted on server errors
+
+### Module Exports
+
+```javascript
+const jsgui = require('jsgui3-server');
+
+// Top-level exports
+jsgui.Process_Resource;
+jsgui.Remote_Process_Resource;
+jsgui.HTTP_SSE_Publisher;
+
+// Resource namespace aliases
+jsgui.Resource.Process;
+jsgui.Resource.Remote_Process;
+```
+
+## Server Instance Methods
 
 ### server.start(port, callback)
 
@@ -74,7 +106,7 @@ server.start(port?: number, callback?: (err?: Error) => void): void
 - `port` (number, optional): Port to listen on (default: 8080)
 - `callback` (function, optional): Called when server starts or fails
 
-### server.publish(route, handler)
+### server.publish(route, handler)
 
 Adds an API endpoint (legacy API).
 
@@ -83,13 +115,45 @@ Adds an API endpoint (legacy API).
 server.publish(route: string, handler: Function): void
 ```
 
-**Parameters:**
-- `route` (string): Route path (automatically prefixed with `/api/`)
-- `handler` (Function): Request handler function
-
-### server.use(middleware)
-
-Adds middleware to the server.
+**Parameters:**
+- `route` (string): Route path (automatically prefixed with `/api/`)
+- `handler` (Function): Request handler function
+
+### server.publish_observable(route, observable, options)
+
+Adds an observable-backed SSE endpoint.
+
+**Signature:**
+```javascript
+server.publish_observable(route: string, observable: Observable, options?: object): HTTP_Observable_Publisher
+```
+
+**Parameters:**
+- `route` (string): Route path. If it does not start with `/`, it is prefixed with `/api/`.
+- `observable` (Observable): Source observable stream.
+- `options` (object, optional): Publisher options.
+
+**Returns:** `HTTP_Observable_Publisher` instance.
+
+**Alias:** `server.publishObservable(route, observable, options)`
+
+### server.close(callback)
+
+Stops managed resources and closes all bound HTTP servers.
+
+**Signature:**
+```javascript
+server.close(callback?: (err?: Error | null) => void): void
+```
+
+**Behavior:**
+- Calls `resource_pool.stop()` when available
+- Stops `sse_publisher` when present
+- Closes all HTTP listeners
+
+### server.use(middleware)
+
+Adds middleware to the server.
 
 **Signature:**
 ```javascript
@@ -443,7 +507,7 @@ Serves CSS files.
 serve(request: IncomingMessage, response: ServerResponse): Promise<void>
 ```
 
-### HTTP_API_Publisher
+### HTTP_API_Publisher
 
 Handles API endpoints.
 
@@ -461,13 +525,162 @@ new HTTP_API_Publisher(spec?: PublisherSpec)
 Handles API requests.
 
 **Signature:**
-```javascript
-serve(request: IncomingMessage, response: ServerResponse): Promise<void>
-```
-
-## Resource Classes
-
-### File_System_Resource
+```javascript
+serve(request: IncomingMessage, response: ServerResponse): Promise<void>
+```
+
+### HTTP_SSE_Publisher
+
+General-purpose SSE publisher for explicit event fan-out.
+
+**Extends:** `HTTP_Publisher`
+
+**Constructor:**
+```javascript
+new HTTP_SSE_Publisher(spec?: {
+    name?: string,
+    keepaliveIntervalMs?: number,
+    maxClients?: number,
+    eventHistorySize?: number
+})
+```
+
+**Methods:**
+- `handle_http(req, res)`
+- `broadcast(event_name, data_value)`
+- `send(client_id, event_name, data_value)`
+- `stop(callback?)`
+
+**Properties:**
+- `client_count` (number)
+
+## Resource Classes
+
+### Process_Resource
+
+Represents a local process as a resource with a unified lifecycle API.
+
+**Extends:** `Resource`
+
+**Constructor:**
+```javascript
+new Process_Resource(spec?: {
+    name?: string,
+    command?: string,
+    args?: string[],
+    cwd?: string,
+    env?: object,
+    autoRestart?: boolean,
+    maxRestarts?: number,
+    processManager?: 'direct' | {
+        type: 'direct' | 'pm2',
+        pm2Path?: string,
+        ecosystem?: string
+    },
+    healthCheck?: {
+        type: 'http' | 'tcp' | 'custom',
+        url?: string,
+        host?: string,
+        port?: number,
+        fn?: Function,
+        intervalMs?: number,
+        timeoutMs?: number,
+        failuresBeforeUnhealthy?: number
+    }
+})
+```
+
+**Core Methods:**
+- `start(callback?)`
+- `stop(callback?)`
+- `restart(callback?)`
+- `get_abstract()`
+
+**Status:**
+```javascript
+{
+    state: 'stopped' | 'starting' | 'running' | 'stopping' | 'restarting' | 'crashed',
+    pid: number | null,
+    uptime: number,
+    restartCount: number,
+    lastHealthCheck: object | null,
+    memoryUsage: object | null,
+    processManager: { type: 'direct' | 'pm2' }
+}
+```
+
+**Events:**
+- `state_change`
+- `stdout`
+- `stderr`
+- `exit`
+- `health_check`
+- `unhealthy`
+- `crashed`
+
+### Remote_Process_Resource
+
+Represents a remote HTTP-controlled process using the same lifecycle-oriented API style as `Process_Resource`.
+
+**Extends:** `Resource`
+
+**Constructor:**
+```javascript
+new Remote_Process_Resource(spec?: {
+    name?: string,
+    host: string,
+    port: number,
+    protocol?: 'http' | 'https',
+    pollIntervalMs?: number,
+    httpTimeoutMs?: number,
+    historySize?: number,
+    unreachableFailuresBeforeEvent?: number,
+    endpoints?: {
+        status?: string,
+        start?: string,
+        stop?: string,
+        health?: string
+    }
+})
+```
+
+**Core Methods:**
+- `start(callback?)`
+- `stop(callback?)`
+- `restart(callback?)`
+- `get_abstract()`
+
+**Status:** Includes `state`, `pid`, `uptime`, `restartCount`, `lastHealthCheck`, `memoryUsage`, and `processManager: { type: 'remote' }`.
+
+**Events:**
+- `state_change`
+- `unreachable`
+- `recovered`
+
+### Server_Resource_Pool
+
+Server-specific resource pool with lifecycle orchestration and event forwarding.
+
+**Extends:** `Resource_Pool`
+
+**Methods:**
+- `add(resource)`
+- `remove(name, callback?)`
+- `start(callback?)`
+- `stop(callback?)`
+- `get_resources_by_type(type)`
+
+**Properties:**
+- `summary`: Aggregated state summary grouped by resource type.
+
+**Forwarded Events:**
+- `resource_state_change`
+- `crashed`
+- `unhealthy`
+- `unreachable`
+- `recovered`
+
+### File_System_Resource
 
 Provides access to local file system.
 
@@ -699,10 +912,10 @@ ensure_route_leading_slash(route: string): string
 ### ServerOptions
 
 ```typescript
-interface ServerOptions {
-  ctrl?: Function;
-  Ctrl?: Function;
-  src_path_client_js?: string;
+interface ServerOptions {
+  ctrl?: Function;
+  Ctrl?: Function;
+  src_path_client_js?: string;
   port?: number;
   host?: string;
   debug?: boolean;
@@ -715,15 +928,60 @@ interface ServerOptions {
   api?: Record<string, Function>;
   static?: Record<string, string>;
 
-  // Advanced options
-  cors?: CorsConfig;
-  https?: HttpsConfig;
-  middleware?: Function[];
-  publishers?: Record<string, Publisher>;
-  resources?: Record<string, Resource>;
-  bundler?: BundlerConfig;
-}
-```
+  // Advanced options
+  cors?: CorsConfig;
+  https?: HttpsConfig;
+  middleware?: Function[];
+  publishers?: Record<string, Publisher>;
+  resources?: ResourceEntries;
+  events?: boolean | EventsOptions;
+  bundler?: BundlerConfig;
+}
+```
+
+```typescript
+type ResourceEntries = Record<string, ResourceEntry> | ResourceEntry[];
+
+type ResourceEntry =
+  | Resource
+  | {
+      type?: 'process' | 'local';
+      command?: string;
+      args?: string[];
+      processManager?: 'direct' | {
+        type?: 'direct' | 'pm2';
+        pm2Path?: string;
+        ecosystem?: string;
+      };
+      [key: string]: any;
+    }
+  | {
+      type?: 'remote' | 'http';
+      host?: string;
+      port?: number;
+      protocol?: 'http' | 'https';
+      endpoints?: Record<string, string>;
+      [key: string]: any;
+    }
+  | {
+      type?: 'resource' | 'in_process' | 'in-process';
+      instance?: Resource;
+      resource?: Resource;
+      class?: new (spec?: any) => Resource;
+      Ctor?: new (spec?: any) => Resource;
+      constructor_fn?: new (spec?: any) => Resource;
+      spec?: Record<string, any>;
+      [key: string]: any;
+    };
+
+interface EventsOptions {
+  route?: string;
+  name?: string;
+  keepaliveIntervalMs?: number;
+  maxClients?: number;
+  eventHistorySize?: number;
+}
+```
 
 ### PageConfig
 
@@ -1029,4 +1287,4 @@ const server = await Server.serve({
 
 ---
 
-This API reference provides comprehensive technical documentation for JSGUI3 Server internals. For practical usage examples and tutorials, refer to the user-facing documentation.
+This API reference provides comprehensive technical documentation for JSGUI3 Server internals. For practical usage examples and tutorials, refer to the user-facing documentation.

package/docs/books/jsgui3-bundling-research-book/00-table-of-contents.md

@@ -0,0 +1,35 @@
+# 0. Table of Contents
+
+## Part I: What the Bundler Does Today
+
+1. [Pipeline and Runtime Semantics](01-pipeline-and-runtime-semantics.md)
+2. [JavaScript Bundling Core](02-javascript-bundling-core.md)
+3. [Style Extraction and CSS Compilation](03-style-extraction-and-css-compilation.md)
+4. [Static Publishing and Delivery](04-static-publishing-and-delivery.md)
+
+## Part II: Why Bundles Are Still Larger Than Needed
+
+5. [Current Limits and Size-Bloat Vectors](05-current-limits-and-size-bloat-vectors.md)
+
+## Part III: How to Get to Lightweight Bundles
+
+6. [Unused Module Elimination Strategy](06-unused-module-elimination-strategy.md)
+7. [jsgui3-html Control and Mixin Pruning](07-jsgui3-html-control-and-mixin-pruning.md)
+8. [Test and Verification Methodology](08-test-and-verification-methodology.md)
+9. [Roadmap and Rollout](09-roadmap-and-rollout.md)
+10. [Further Research: Strategies and Upgrades](10-further-research-strategies-and-upgrades.md)
+
+## Primary Code Surfaces Referenced
+
+- `publishers/http-webpageorsite-publisher.js`
+- `publishers/http-webpage-publisher.js`
+- `publishers/helpers/preparers/static/bundle/Static_Routes_Responses_Webpage_Bundle_Preparer.js`
+- `publishers/helpers/assigners/static-routes/Single_Control_Webpage_Server_Static_Routes_Assigner.js`
+- `publishers/helpers/assigners/static-uncompressed-response-buffers/Single_Control_Webpage_Server_Static_Uncompressed_Response_Buffers_Assigner.js`
+- `publishers/helpers/assigners/static-compressed-response-buffers/Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner.js`
+- `publishers/helpers/assigners/static-headers/Single_Control_Webpage_Server_Static_Headers_Assigner.js`
+- `resources/processors/bundlers/js/esbuild/Advanced_JS_Bundler_Using_ESBuild.js`
+- `resources/processors/bundlers/js/esbuild/Core_JS_Non_Minifying_Bundler_Using_ESBuild.js`
+- `resources/processors/bundlers/js/esbuild/Core_JS_Single_File_Minifying_Bundler_Using_ESBuild.js`
+- `resources/processors/extractors/js/css_and_js/AST_Node/CSS_And_JS_From_JS_String_Using_AST_Node_Extractor.js`
+- `resources/processors/bundlers/style-bundler.js`

package/docs/books/jsgui3-bundling-research-book/01-pipeline-and-runtime-semantics.md

@@ -0,0 +1,34 @@
+# 1. Pipeline and Runtime Semantics
+
+## System Entry Point
+
+For webpage/site publishing, the active bundling entry path is:
+
+1. `HTTP_Webpage_Publisher.get_ready()`
+2. `HTTP_Webpageorsite_Publisher.get_ready()`
+3. `JS_Bundler.bundle(src_path_client_js)`
+4. static route/response preparation
+
+The concrete orchestrator is `publishers/http-webpageorsite-publisher.js`, which constructs `JS_Bundler` and awaits `js_bundler.bundle(...)`.
+
+## Bundle Payload Contract
+
+The bundle object is `Bundle` (a `Collection`) from `resources/processors/bundlers/bundle.js`. Effective convention is:
+
+- bundle array with one `Bundle` instance
+- `Bundle._arr` containing items such as:
+  - `{ type: 'JavaScript', extension: 'js', text: '...' }`
+  - `{ type: 'CSS', extension: 'css', text: '...' }`
+  - `{ type: 'HTML', extension: 'html', text: '...' }` (added by webpage publisher)
+
+This contract is implicit and shared by publishers/assigners.
+
+## Readiness and Failure Semantics
+
+`HTTP_Webpage_Publisher` starts an async readiness flow in constructor and emits `'ready'` on success. On error, it emits `'error'` and then still emits `'ready'` with `{}` so upstream startup can continue.
+
+`HTTP_Webpageorsite_Publisher.get_ready()` also has defensive fallback for missing `src_path_client_js`, returning placeholder JS/CSS text items.
+
+## Consequence
+
+The current design prioritizes startup continuity over hard failure. This is operationally useful, but for strict production correctness a separate "fail-fast bundling" mode should exist.

package/docs/books/jsgui3-bundling-research-book/02-javascript-bundling-core.md

@@ -0,0 +1,36 @@
+# 2. JavaScript Bundling Core
+
+## Active JS Bundler Chain
+
+`resources/processors/bundlers/js-bundler.js` exports `./js/JS_Bundler`, which exports `./esbuild/Advanced_JS_Bundler_Using_ESBuild`.
+
+That advanced bundler composes two core stages:
+
+1. `Core_JS_Non_Minifying_Bundler_Using_ESBuild`
+2. `Core_JS_Single_File_Minifying_Bundler_Using_ESBuild` (production branch)
+
+## Stage A: Non-Minifying Bundle
+
+`Core_JS_Non_Minifying_Bundler_Using_ESBuild` executes `esbuild.build` with:
+
+- `bundle: true`
+- `treeShaking: true`
+- `write: false`
+- optional sourcemap, controlled by `sourcemaps.enabled`, `debug`, and `includeInProduction`
+
+It returns a one-item `Bundle` containing JavaScript text.
+
+## Stage B: Style-Assignment Removal
+
+`Advanced_JS_Bundler_Using_ESBuild` parses the Stage A JS, extracts style assignments, and produces CSS-free JS text for a second JS pass.
+
+## Stage C: Debug/Production Split
+
+- Debug path: re-bundle CSS-free JS without minification.
+- Production path: re-bundle CSS-free JS, then run minifier bundler.
+
+Minifier behavior is configurable by `bundler.minify` with levels `conservative | normal | aggressive` and option overrides.
+
+## Existing Optimization Character
+
+The current model is "bundle then sanitize" rather than "module graph first with explicit retained-module manifest." It relies heavily on esbuild tree shaking plus post-bundle style extraction.

package/docs/books/jsgui3-bundling-research-book/03-style-extraction-and-css-compilation.md

@@ -0,0 +1,35 @@
+# 3. Style Extraction and CSS Compilation
+
+## Extraction Target
+
+`CSS_And_JS_From_JS_String_Using_AST_Node_Extractor` scans bundled JS AST and finds assignment expressions where:
+
+- left side is a member expression ending in `css`, `scss`, or `sass`
+- right side is a template literal
+
+Matched style source is collected, and assignment source spans are removed from JS output.
+
+## Output Shape
+
+Extractor returns:
+
+- `css` (concatenated)
+- `scss` (concatenated)
+- `sass` (concatenated)
+- `style_segments` (ordered typed segments)
+- `js` (style-assignment-free JS)
+
+## Compilation Phase
+
+`resources/processors/bundlers/style-bundler.js` compiles style payloads via `SASS_Compiler` when SCSS/SASS is present (or when CSS is configured to compile through sass). It supports:
+
+- mixed segment compilation
+- load paths
+- output style
+- optional inline sourcemaps
+
+The compiled CSS is appended as a `CSS` bundle item.
+
+## Current Limits
+
+Extraction currently depends on a specific syntactic shape (`AssignmentExpression` + template literal). Non-matching style declaration patterns can evade extraction and remain in JS, which both bloats JS and risks duplicate style semantics.

package/docs/books/jsgui3-bundling-research-book/04-static-publishing-and-delivery.md

@@ -0,0 +1,39 @@
+# 4. Static Publishing and Delivery
+
+## Preparation Chain
+
+`Static_Routes_Responses_Webpage_Bundle_Preparer.prepare(...)` runs:
+
+1. route assignment
+2. identity buffer assignment
+3. compressed buffer assignment
+4. response header assignment
+
+## Route Model
+
+`Single_Control_Webpage_Server_Static_Routes_Assigner` maps by type:
+
+- JavaScript -> `/js/js.js`
+- CSS -> `/css/css.css`
+- HTML -> `/`
+
+This is deterministic but static; no fingerprinted asset paths yet.
+
+## Encoding Model
+
+`Single_Control_Webpage_Server_Static_Uncompressed_Response_Buffers_Assigner` writes `response_buffers.identity`.
+
+`Single_Control_Webpage_Server_Static_Compressed_Response_Buffers_Assigner` optionally adds:
+
+- `response_buffers.gzip`
+- `response_buffers.br`
+
+Configurable controls include `enabled`, `algorithms`, `gzip.level`, `brotli.quality`, and `threshold`.
+
+## Header Model
+
+`Single_Control_Webpage_Server_Static_Headers_Assigner` writes headers per encoding variant under `item.response_headers[encoding]`, including `Content-Length`, `Content-Type`, and `Content-Encoding` where applicable.
+
+## Practical Implication
+
+The delivery layer is currently path-stable and content-encoding-aware but not cache-fingerprint-aware. Lightweight bundles can still be produced, but CDN/browser cache efficiency is constrained by fixed asset names.

package/docs/books/jsgui3-bundling-research-book/05-current-limits-and-size-bloat-vectors.md

@@ -0,0 +1,25 @@
+# 5. Current Limits and Size-Bloat Vectors
+
+## Bloat Vector 1: Entry-Point Over-Inclusion
+
+If the client entry imports a broad namespace (or re-export hub), esbuild includes reachable modules conservatively. Tree shaking helps, but side-effect ambiguity limits elimination.
+
+## Bloat Vector 2: Side Effects and Dynamic Access
+
+Patterns like dynamic member access, side-effectful module initialization, or broad registry mutation make safe elimination harder. Bundlers retain uncertain modules by design.
+
+## Bloat Vector 3: Post-Bundle Style Extraction Cost
+
+Current strategy performs non-minifying bundle first, then AST style extraction, then JS rebundle/minify. This gives clean CSS separation but incurs additional processing and can retain JS content not representable as removable style assignments.
+
+## Bloat Vector 4: Fixed Aggregate Assets
+
+Everything converges to a single `/js/js.js` and `/css/css.css` asset pair. This simplifies runtime, but does not naturally support granular shared-chunk caching.
+
+## Bloat Vector 5: Startup-Continuity Fallbacks
+
+Bundling fallback behavior favors server startup continuity. If fallback text assets are accepted too loosely in operational workflows, latent size/perf regressions may go unnoticed.
+
+## Core Observation
+
+The system is robust and functionally coherent, but it lacks a first-class "reachability report + elimination policy" layer that explains exactly what was retained and why.

package/docs/books/jsgui3-bundling-research-book/06-unused-module-elimination-strategy.md

@@ -0,0 +1,77 @@
+# 6. Unused Module Elimination Strategy
+
+## Design Goal
+
+Add deterministic dead-module elimination while preserving runtime correctness and keeping current high-level APIs stable.
+
+## Phase 1: Observability First
+
+Introduce a bundle analysis artifact per build:
+
+- `module_graph_manifest.json`
+- fields: module path, retained/pruned flag, retention reason, side-effect classification, importer chain
+
+Use esbuild `metafile` as baseline graph input. Do not prune yet in this phase.
+
+## Phase 2: Policy-Based Pruning
+
+Add pruning policies:
+
+- `safe`: prune only modules proven side-effect free and unreachable from entry exports
+- `balanced`: allow package-level side-effect allowlists
+- `aggressive`: opt-in broader pruning with explicit risk declaration
+
+Each pruned module must carry an auditable reason code.
+
+## Phase 3: Runtime Safety Guardrails
+
+Add optional runtime checks in debug mode:
+
+- missing symbol trap hooks for known registries
+- warning when dynamic lookup requests pruned modules
+
+## Proposed Configuration Surface
+
+```js
+bundler: {
+  elimination: {
+    enabled: true,
+    profile: 'safe',
+    emit_manifest: true,
+    fail_on_uncertain_prune: true
+  }
+}
+```
+
+## Contract
+
+The contract must be: "No silent pruning." Every elimination decision is traceable in emitted metadata.
+
+## Current Implementation (Initial)
+
+`jsgui3-server` now includes an initial `jsgui3-html` control scan-and-package path in the advanced esbuild bundler.
+
+Enable it with:
+
+```js
+bundler: {
+  elimination: {
+    enabled: true,
+    jsgui3_html_controls: {
+      enabled: true
+    }
+  }
+}
+```
+
+Behavior:
+
+- scans reachable source files from the entry file
+- detects static `jsgui3-html` control usage patterns
+- builds a lightweight shim exporting only selected controls
+- aliases `require('jsgui3-html')` to that shim during bundling
+- attaches scan metadata at `bundle.bundle_analysis.jsgui3_html_control_scan`
+
+Safety:
+
+- if dynamic control indexing is detected (`controls[some_var]`), optimization is disabled by default