jsgui3-server 0.0.148 → 0.0.150

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

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.