jsgui3-server 0.0.147 → 0.0.149

package/docs/books/jsgui3-bundling-research-book/09-roadmap-and-rollout.md

@@ -0,0 +1,42 @@
+# 9. Roadmap and Rollout
+
+## Phase A: Baseline Instrumentation
+
+- emit module graph manifest without pruning
+- add CI artifact publishing for manifests
+- add docs for reading retention reasons
+
+Exit criteria:
+- manifests generated for all target example fixtures
+- no behavior changes
+
+## Phase B: Safe Pruning Profile
+
+- implement `safe` elimination profile
+- prune only proven unreachable and side-effect-safe modules
+- add fail-fast option for uncertain prune attempts
+
+Exit criteria:
+- full test suite green
+- measurable JS size reductions on simple apps
+- zero runtime regressions
+
+## Phase C: jsgui3-html Symbol-Aware Pruning
+
+- add control/mixin symbol graph pass
+- integrate registry publication edge tracking
+- support optional feature-group retention manifests
+
+Exit criteria:
+- significant size reductions for minimal-control apps
+- controlled retention for dynamic access cases
+
+## Phase D: Operational Hardening
+
+- add deterministic chunk/hash strategy if route model evolves
+- enforce size budgets in CI
+- document migration path for package authors to declare side effects explicitly
+
+## Non-Goal
+
+Runtime hot-switching of elimination profiles is not required. Build-time consistency with predictable APIs is the target.

package/docs/books/jsgui3-bundling-research-book/10-further-research-strategies-and-upgrades.md

@@ -0,0 +1,211 @@
+# 10. Further Research: Strategies and Upgrades
+
+## Purpose
+
+This chapter extends the initial roadmap with additional strategies validated against current official tooling documentation. The goal is to improve both:
+
+- elimination quality (more dead code removed safely)
+- operational confidence (clear reason codes and controlled risk)
+
+## A. Strengthen Existing Esbuild-Centric Strategy
+
+### A1. Turn Build Metadata into First-Class Artifact
+
+Current proposal already introduces a manifest. Upgrade it to include:
+
+- esbuild `metafile` `inputs` and `outputs` mapping
+- importer chains for each retained module
+- side-effect reason code (`annotation`, `package_side_effects`, `plugin_side_effects`, `unknown`)
+- unresolved dynamic-import reason code where relevant
+
+Why: esbuild exposes a structured metadata graph and textual analysis hooks suitable for deterministic retention explanations.
+
+### A2. Add Plugin-Level Side-Effect Overrides (Safe Allowlist Only)
+
+Esbuild plugin `onResolve` supports returning `sideEffects: false`. Use this only through a strict allowlist generated from audited modules, never broad regex defaults.
+
+Why: this provides precision beyond package-level `sideEffects` fields and enables selective pruning of known-safe internal modules.
+
+### A3. Improve Annotation Fault Tolerance
+
+Support an explicit fallback mode for bad third-party annotations:
+
+- default: respect annotations (`/* @__PURE__ */`, `package.json sideEffects`)
+- safe fallback: set `ignoreAnnotations: true` for known-problem dependency subsets
+
+Why: esbuild documents annotation misuse as a real breakage source; controlled fallback prevents production outages.
+
+### A4. Prefer ESM Paths Where Safe
+
+For packages that expose both CommonJS and ESM, prefer ESM paths where validated to improve tree shaking.
+
+Why: esbuild explicitly notes tree shaking depends on ESM `import`/`export` and does not work on CommonJS modules the same way.
+
+## B. Add Multi-Chunk Strategy (Not Just Single /js/js.js)
+
+### B1. Optional ESM Split Build Profile
+
+Add an optional bundler profile that emits ESM with splitting enabled (`format: 'esm'`, `splitting: true`) and chunk names with content hashes.
+
+Use for:
+
+- multi-page apps
+- heavy optional controls loaded by `import()`
+
+Do not force this profile for simple examples where a single file remains desirable.
+
+### B2. Route and HTML Preparation Upgrade
+
+Current static route assigner assumes one JS and one CSS file. Add a preparer mode that:
+
+- maps every emitted JS/CSS asset to static routes
+- injects `<script type="module">` plus chunk graph references where required
+- supports content-hash file names for cache correctness
+
+## C. Use Safety Ladder from Rollup Research as Policy Design Input
+
+Even if the implementation remains esbuild-first, Rollup's treeshake policy surface is a useful design model:
+
+- `safest`
+- `recommended`
+- `smallest`
+
+Adopt equivalent policy semantics in `jsgui3-server` elimination config:
+
+- `safe` (strict side-effect conservatism)
+- `balanced` (some side-effect assumptions)
+- `aggressive` (max pruning, stronger contracts)
+
+Include explicit controls for assumptions analogous to:
+
+- module side effects
+- property-read side effects
+- try/catch deoptimization behavior
+- manually pure function sets
+
+## D. Package Boundary Strategy for jsgui3-html
+
+### D1. Subpath Exports for Feature Addressability
+
+Restructure `jsgui3-html` package exports so controls and mixins have stable subpath entry points (for example, `./controls/date_picker.js`, `./mixins/draggable.js`, `./core/...`).
+
+Why: Node package `exports` and subpath exports give explicit package contracts and allow bundlers to consume narrow entry points instead of broad index hubs.
+
+### D2. Core vs Optional Feature Groups
+
+Define package layers:
+
+- `core` minimal runtime
+- optional groups (`advanced-controls`, `diagnostics`, `themes`, etc.)
+
+Then bind elimination policies to these boundaries for predictable pruning.
+
+### D3. Internal Imports Field for Maintainability
+
+Use package `imports` (private `#...` aliases) inside `jsgui3-html` to stabilize internal paths while allowing refactors that do not leak into public imports.
+
+## E. Compression and Minification Escalation Path
+
+### E1. Keep Esbuild as Default Minifier
+
+Esbuild is very fast and adequate for most builds.
+
+### E2. Optional High-Compression Pass
+
+For release artifacts that need additional byte reduction, provide an optional second minification pass profile (e.g., Terser pure-function tuning). Keep this opt-in due to risk/perf tradeoffs.
+
+### E3. Experimental Extreme Profile
+
+Document (not default) an experimental path for Closure Compiler `ADVANCED_OPTIMIZATIONS` for controlled targets only, with strict compatibility guardrails.
+
+## F. Coverage-Guided Optimization (Puppeteer + CDP)
+
+### F1. Coverage Collection Pipeline
+
+Use Puppeteer coverage APIs in E2E suites:
+
+- `page.coverage.startJSCoverage(...)`
+- `page.coverage.startCSSCoverage(...)`
+- stop coverage and persist per-script ranges
+
+Enable block-level coverage for high resolution.
+
+### F2. Precise CDP Coverage for Deep Diagnostics
+
+For targeted diagnostics, integrate CDP Profiler precise coverage APIs (`startPreciseCoverage`, `takePreciseCoverage`) in controlled runs.
+
+### F3. Correct Interpretation Rule
+
+Coverage is advisory, not authoritative:
+
+- never auto-prune solely from observed runtime coverage
+- use coverage to identify candidates for lazy loading or refactor, then validate with static safety rules
+
+## G. Concrete Upgrades to Existing jsgui3-server Plan
+
+### G1. New Config Surface (Proposed)
+
+```js
+bundler: {
+  elimination: {
+    enabled: true,
+    profile: 'safe', // safe | balanced | aggressive
+    emit_manifest: true,
+    include_importer_chains: true,
+    fail_on_uncertain_prune: true,
+    plugin_side_effect_overrides: {
+      allowlist: []
+    }
+  },
+  chunking: {
+    profile: 'single', // single | esm_split
+    chunk_names: 'chunks/[name]-[hash]'
+  }
+}
+```
+
+### G2. Manifest Enrichment (Proposed)
+
+Add fields:
+
+- `retained_reason_code`
+- `side_effect_source`
+- `importer_chain`
+- `dynamic_access_risk`
+- `runtime_coverage_seen` (optional diagnostic field)
+
+### G3. Test Expansion
+
+- policy conformance tests per profile (`safe`, `balanced`, `aggressive`)
+- split profile routing/injection tests
+- manifest stability snapshots
+- Puppeteer coverage capture and diff reporting
+
+## H. Prioritized Execution Order
+
+1. Implement manifest enrichment on top of current esbuild flow.
+2. Add safe plugin-side-effect allowlist mechanism.
+3. Add ESM split profile behind feature flag.
+4. Add package-boundary changes in `jsgui3-html` (`exports`/subpaths/core layering).
+5. Add optional secondary minifier profile.
+6. Integrate coverage-guided diagnostics into CI reports.
+
+## Source Notes
+
+External strategies in this chapter are based on current official docs for esbuild, Rollup, webpack, Node package exports/imports, Puppeteer coverage APIs, and Chrome DevTools Protocol coverage APIs.
+
+Primary references:
+
+- https://esbuild.github.io/api/
+- https://esbuild.github.io/plugins/
+- https://rollupjs.org/configuration-options/
+- https://webpack.js.org/guides/tree-shaking/
+- https://webpack.js.org/plugins/split-chunks-plugin/
+- https://nodejs.org/api/packages.html
+- https://babeljs.io/docs/babel-plugin-transform-modules-commonjs
+- https://terser.org/docs/options/#compress-options
+- https://developers.google.com/closure/compiler/docs/compilation_levels
+- https://developers.google.com/closure/compiler/docs/api-tutorial3
+- https://pptr.dev/api/puppeteer.coverage.startjscoverage
+- https://pptr.dev/api/puppeteer.coverage.startcsscoverage
+- https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#method-startPreciseCoverage

package/docs/books/jsgui3-bundling-research-book/README.md

@@ -0,0 +1,35 @@
+# JSGUI3 Bundling Research Book
+
+This book documents how JS and CSS bundling currently works in `jsgui3-server`, then defines a practical path to remove unused modules, controls, mixins, and related code from final bundles without breaking runtime behavior.
+
+## Scope
+
+- Current runtime bundling semantics (implementation-first, file-path grounded)
+- Existing optimization surface and current limits
+- Dead-module elimination strategy for application code and `jsgui3-html`
+- Control/mixin reachability and pruning model
+- Verification strategy (unit, integration, e2e, and size-regression)
+
+## Intended Readers
+
+- Maintainers changing bundling internals
+- Contributors adding controls or mixins to `jsgui3-html`
+- Agents implementing bundle-size reduction work
+
+## Reading Order
+
+1. [00 Table of Contents](00-table-of-contents.md)
+2. [01 Pipeline and Runtime Semantics](01-pipeline-and-runtime-semantics.md)
+3. [02 JavaScript Bundling Core](02-javascript-bundling-core.md)
+4. [03 Style Extraction and CSS Compilation](03-style-extraction-and-css-compilation.md)
+5. [04 Static Publishing and Delivery](04-static-publishing-and-delivery.md)
+6. [05 Current Limits and Size-Bloat Vectors](05-current-limits-and-size-bloat-vectors.md)
+7. [06 Unused Module Elimination Strategy](06-unused-module-elimination-strategy.md)
+8. [07 jsgui3-html Control and Mixin Pruning](07-jsgui3-html-control-and-mixin-pruning.md)
+9. [08 Test and Verification Methodology](08-test-and-verification-methodology.md)
+10. [09 Roadmap and Rollout](09-roadmap-and-rollout.md)
+11. [10 Further Research: Strategies and Upgrades](10-further-research-strategies-and-upgrades.md)
+
+## Status
+
+This is a working research book. It is designed to be updated as the bundling system evolves.

package/docs/bundling-system-deep-dive.md

@@ -1,6 +1,11 @@
-# Bundling System Deep Dive
-
-## When to Read
+# Bundling System Deep Dive
+
+## Research Track
+
+For the active, chaptered research track on lightweight bundle strategy and unused-module elimination, use:
+`docs/books/jsgui3-bundling-research-book/README.md`
+
+## When to Read
 
 This document provides detailed technical documentation of JSGUI3 Server's bundling system. Read this when:
 - You need to understand how JavaScript and CSS bundling works internally
@@ -522,4 +527,4 @@ Key takeaways:
 - **Debugging**: Use debug mode and logging for troubleshooting
 - **Performance**: Fast for development, optimizable for production
 
-For issues not covered here, check the [troubleshooting guide](docs/troubleshooting.md) or create an issue in the repository.
+For issues not covered here, check the [troubleshooting guide](docs/troubleshooting.md) or create an issue in the repository.

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).
+**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
 
@@ -118,8 +118,9 @@ This section is a short, task-oriented runway for AI agents that need to act qui
 **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. Make the smallest change that can pass a targeted test.
-4. Run the narrow test file first, then widen if needed.
+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
@@ -489,14 +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
-- `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
 
@@ -527,17 +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
-});
-```
+    },
+    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
 

package/docs/configuration-reference.md

@@ -129,7 +129,7 @@ Configuration values are resolved in this order (later sources override earlier
   });
   ```
 
-### API Configuration
+### API Configuration
 
 #### `api`
 - **Type:** `object`
@@ -154,9 +154,81 @@ Configuration values are resolved in this order (later sources override earlier
           'echo': (data) => data
       }
   });
-  ```
-
-### Static File Serving
+  ```
+
+### Resource and Event Options
+
+#### `resources`
+- **Type:** `object | array`
+- **Description:** Resource definitions to register in the server resource pool and start after server startup.
+- **Lifecycle:** Resources are started automatically after the HTTP server is listening and stopped automatically during `server.close()`.
+- **Supported forms:**
+  - In-process resource instance
+  - In-process resource constructor/class config
+  - Process resource config (`type: 'process'` or inferred from `command`)
+  - Remote process resource config (`type: 'remote'` or inferred from `host`/`endpoints`)
+- **Example:**
+  ```javascript
+  Server.serve({
+      resources: {
+          // In-process resource instance
+          cache: new In_Process_Cache_Resource({ name: 'cache' }),
+
+          // Process_Resource in direct mode (default)
+          worker_direct: {
+              type: 'process',
+              command: process.execPath,
+              args: ['worker.js'],
+              autoRestart: true
+          },
+
+          // Process_Resource in PM2 mode (pm2Path optional)
+          worker_pm2: {
+              type: 'process',
+              processManager: { type: 'pm2' },
+              command: process.execPath,
+              args: ['worker.js']
+          },
+
+          // Remote_Process_Resource
+          remote_worker: {
+              type: 'remote',
+              host: '127.0.0.1',
+              port: 3400,
+              pollIntervalMs: 30000
+          }
+      }
+  });
+  ```
+
+**Process resource notes:**
+- `processManager` defaults to `direct`.
+- PM2 works without explicitly setting `pm2Path`:
+  - `processManager.pm2Path` (if provided)
+  - `PM2_PATH` env var (if provided)
+  - local `node_modules/.bin/pm2` (if present)
+  - `pm2` from `PATH`
+
+#### `events`
+- **Type:** `boolean | object`
+- **Description:** Enables a built-in SSE endpoint for resource lifecycle events.
+- **Default:** `false`
+- **When `true`:**
+  - Registers `HTTP_SSE_Publisher` at `/events`
+  - Forwards resource pool lifecycle events (`resource_state_change`, `crashed`, `unhealthy`, `unreachable`, `recovered`)
+- **When object:** Supports publisher options such as `route`, `name`, `keepaliveIntervalMs`, `maxClients`.
+- **Example:**
+  ```javascript
+  Server.serve({
+      events: {
+          route: '/events',
+          keepaliveIntervalMs: 15000,
+          maxClients: 200
+      }
+  });
+  ```
+
+### Static File Serving
 
 #### `static`
 - **Type:** `object`
@@ -349,21 +421,70 @@ Server.serve({
 });
 ```
 
-### Resource Pools
-
-```javascript
-Server.serve({
-    resources: {
-        database: new DatabaseResource({
-            connectionString: process.env.DATABASE_URL
-        }),
-        cache: new RedisResource({
-            host: 'localhost',
-            port: 6379
-        })
-    }
-});
-```
+### Resource Pools
+
+```javascript
+let server;
+server = await Server.serve({
+    resources: {
+        cache: new In_Process_Cache_Resource({
+            name: 'cache'
+        }),
+        worker_direct: {
+            type: 'process',
+            command: process.execPath,
+            args: ['worker.js']
+        },
+        remote_worker: {
+            type: 'remote',
+            host: '127.0.0.1',
+            port: 3400
+        }
+    },
+    events: true,
+    api: {
+        'resources/summary': () => server.resource_pool.summary,
+        'resources/restart': async ({ name }) => {
+            const resource = server.resource_pool.get_resource(name);
+            if (!resource || typeof resource.restart !== 'function') {
+                return { ok: false, error: 'Resource restart not supported' };
+            }
+            await resource.restart();
+            return { ok: true, status: resource.status };
+        }
+    }
+});
+```
+
+For strongly typed in-process resources you can also provide constructor-based entries:
+
+```javascript
+Server.serve({
+    resources: {
+        in_process_metrics: {
+            type: 'resource',
+            class: In_Process_Metrics_Resource,
+            spec: {
+                sampleIntervalMs: 1000
+            }
+        },
+        in_process_events: {
+            constructor_fn: In_Process_Event_Bus_Resource,
+            spec: {
+                maxHistory: 500
+            }
+        },
+        in_process_cache: {
+            resource: new In_Process_Cache_Resource({
+                name: 'in_process_cache'
+            })
+        },
+        in_process_singleton: new In_Process_Registry_Resource({
+            name: 'in_process_singleton'
+        })
+    }
+});
+```
 
 ### Middleware
 
@@ -402,14 +523,18 @@ Server.serve({ port: 'not-a-number' });
 - **Required:** None (auto-discovery provides defaults)
 - **Optional:** All options have sensible defaults
 
-### Validation Rules
-
-- `port`: Must be number between 1-65535 or 0 (ephemeral)
-- `host`: Must be valid IPv4 address or hostname
-- `debug`: Converted to boolean using truthy() function
-- `pages`: Each page must have `content` property
-- `api`: Values must be functions
-- `static`: Values must be strings (directory paths)
+### Validation Rules
+
+- `port`: Must be number between 1-65535 or 0 (ephemeral)
+- `host`: Must be valid IPv4 address or hostname
+- `debug`: Converted to boolean using truthy() function
+- `pages`: Each page must have `content` property
+- `api`: Values must be functions
+- `static`: Values must be strings (directory paths)
+- `resources`: Must be an object map or array of supported resource entries
+- `resources.<name>.type`: Supported values include `process`, `remote`, `resource`, `in_process`, `in-process`
+- `resources.<name>.processManager.type`: Supported values include `direct`, `pm2`
+- `events`: Must be boolean or object
 
 ## Configuration Patterns
 

package/docs/core/README.md

@@ -0,0 +1,19 @@
+# Core Documentation
+
+This directory contains dense, implementation-first documentation for the active reliability surface of `jsgui3-server`.
+
+Current focus:
+
+- server startup and readiness semantics
+- unified resource model (in-process, direct process, remote process)
+- resource pool lifecycle and event forwarding
+- SSE event transport for resource telemetry
+- end-to-end browser testing methodology for control + resource integration
+
+Primary text:
+
+- `docs/core/jsgui3-server-core-book/00-table-of-contents.md`
+
+Related deep-dive:
+
+- `docs/books/jsgui3-bundling-research-book/README.md`

package/docs/core/jsgui3-server-core-book/00-table-of-contents.md

@@ -0,0 +1,21 @@
+# jsgui3-server Core Book
+
+## Purpose
+
+This book specifies the currently critical execution path: `Server.serve(...)` startup, resource lifecycle control, resource event publication, and browser-level verification of those behaviors.
+
+## Chapter Map
+
+1. `01-startup-readiness-state-machine.md`
+2. `02-resource-abstraction-and-lifecycle.md`
+3. `03-resource-pool-and-event-topology.md`
+4. `04-sse-publisher-semantics.md`
+5. `05-serve-factory-resource-wiring.md`
+6. `06-e2e-testing-methodology.md`
+7. `07-defect-detection-and-hardening-loop.md`
+
+## Reader Contract
+
+- This text is dense by design.
+- It assumes familiarity with Node.js HTTP servers, async control flow, and event-driven architecture.
+- It prioritizes invariants, failure modes, and testability over introductory narrative.