jsgui3-server 0.0.148 → 0.0.149

package/docs/books/jsgui3-bundling-research-book/07-jsgui3-html-control-and-mixin-pruning.md

@@ -0,0 +1,63 @@
+# 7. jsgui3-html Control and Mixin Pruning
+
+## Objective
+
+Allow `jsgui3-html` to grow in feature breadth while keeping simple app bundles lightweight by pruning unused controls, mixins, and helper modules.
+
+## Constraint Surface
+
+`jsgui3-html` usage often includes:
+
+- direct imports (`const {Window} = require('jsgui3-html').controls`)
+- registry-style access (`jsgui.controls.some_control`)
+- inheritance chains and mixin composition
+
+Pruning must account for all three.
+
+## Reachability Model
+
+Build a typed symbol graph with nodes:
+
+- controls
+- mixins
+- utility helpers
+- transitive runtime support modules
+
+Edges:
+
+- static import/require edges
+- inheritance edges
+- mixin application edges
+- registry publication edges
+
+A module is retained if any retained symbol depends on it.
+
+## Beyond Controls and Mixins
+
+The same graph can prune additional payload classes:
+
+- optional theme packs
+- optional icon packs
+- optional debug instrumentation
+- optional adapter layers (for features not used by the app)
+- feature-local helper modules that are only referenced by pruned controls
+
+## Packaging Recommendation
+
+Within `jsgui3-html`, define explicit boundaries:
+
+- `core` (always lightweight baseline)
+- optional feature groups (advanced controls, diagnostics, heavy widgets)
+
+Then allow bundler elimination to prune unused optional groups based on symbol reachability.
+
+## Dynamic-Access Safety
+
+When dynamic registry access is detected and symbol resolution is uncertain:
+
+- `safe` profile retains uncertain candidates
+- manifest records reason as `dynamic_access_uncertain`
+
+## Result
+
+This produces consistent APIs while allowing bundle contents to shrink significantly for narrow use cases.

package/docs/books/jsgui3-bundling-research-book/08-test-and-verification-methodology.md

@@ -0,0 +1,43 @@
+# 8. Test and Verification Methodology
+
+## Verification Principle
+
+Bundle-size optimization is valid only if behavioral equivalence is maintained for supported usage profiles.
+
+## Test Layers
+
+1. Unit tests for elimination graph logic
+2. Integration tests for bundler output and route serving
+3. E2E browser tests for real interaction flows (Puppeteer)
+4. Size-regression tests with per-fixture budgets
+
+## Bundle Correctness Tests
+
+For each fixture app:
+
+- generate baseline bundle (elimination disabled)
+- generate optimized bundle (elimination enabled)
+- compare runtime outcomes and key DOM/event traces
+- compare bundle size deltas against expected thresholds
+
+## Puppeteer Scenarios
+
+For control-heavy examples:
+
+- open page and wait for control activation markers
+- perform high-specificity interactions (drag, resize, date pick, color pick, keyboard paths)
+- assert expected UI state and emitted network/API behavior
+
+For resource-integrated flows:
+
+- verify client-visible state updates driven by server resources
+- verify SSE/event paths where applicable
+- confirm no missing-symbol/runtime errors caused by pruning
+
+## Gating Policy
+
+A prune policy cannot be promoted from experimental to default unless:
+
+- all functional suites pass
+- bundle manifest diff is stable and explainable
+- size regression thresholds are met across representative fixtures.

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