jsgui3-server 0.0.150 → 0.0.152

package/docs/books/creating-a-new-admin-ui/README.md

@@ -6,9 +6,9 @@
 
 ## About This Book
 
-This book documents the design, architecture, and implementation of a rich administration interface for jsgui3-server. The admin UI is built entirely with jsgui3 controls — dogfooding the framework to create a production-quality dashboard that provides real-time visibility into server internals, process health, resource pools, routing tables, build outputs, and configuration.
-
-The admin UI lives at `admin-ui/v1/` and is served automatically at the `/admin/v1` route of any running jsgui3-server instance.
+This book documents the design, architecture, and implementation of a rich administration interface for jsgui3-server. The admin UI is built entirely with jsgui3 controls — dogfooding the framework to create a production-quality dashboard that provides real-time visibility into server internals, process health, resource pools, routing tables, build outputs, and configuration.
+
+The admin UI lives at `admin-ui/v1/` and is served automatically at the `/admin/v1` route of any running jsgui3-server instance.
 
 ## Design Reference
 
@@ -30,16 +30,16 @@ The visual design is inspired by a Windows Aero-era aesthetic — glass-effect t
 | 10 | [Domain Controls — Build Status & Bundle Inspector](10-domain-controls-build-status-and-bundle-inspector.md) | Bundle size cards, module count, build timing, source map status |
 | 11 | [Domain Controls — Configuration Panel](11-domain-controls-configuration-panel.md) | Read-only and editable config fields, port/debug/entry-point display |
 | 12 | [The Admin Shell — Layout, Sidebar, & Navigation](12-admin-shell-layout-sidebar-navigation.md) | Window chrome, sidebar navigation, toolbar, status bar, content area routing |
-| 13 | [Integrating with the Server — Telemetry Endpoints](13-telemetry-integration.md) | Modifying `server.js` and `Admin_Module` to expose new telemetry APIs |
-| 14 | [Real-Time Updates — SSE & Observable Integration](14-realtime-sse-observable-integration.md) | Connecting the UI to `HTTP_SSE_Publisher` and `HTTP_Observable_Publisher` for live data |
-| 15 | [Styling & Theming — The Aero-Inspired Design System](15-styling-theming-aero-design-system.md) | Token definitions, gradient recipes, glass effects, typography, and density |
+| 13 | [Integrating with the Server — Telemetry Endpoints](13-telemetry-integration.md) | Modifying `server.js` and `Admin_Module` to expose new telemetry APIs |
+| 14 | [Real-Time Updates — SSE & Observable Integration](14-realtime-sse-observable-integration.md) | Connecting the UI to `HTTP_SSE_Publisher` and `HTTP_Observable_Publisher` for live data |
+| 15 | [Styling & Theming — The Aero-Inspired Design System](15-styling-theming-aero-design-system.md) | Token definitions, gradient recipes, glass effects, typography, and density |
 | 16 | [Testing & Quality Assurance](16-testing-and-quality-assurance.md) | Unit tests, integration tests, viewport matrix testing, and acceptance criteria |
 | 17 | [Next Steps — Process/Resource Roadmap](17-next-steps-process-resource-roadmap.md) | Handoff-grade implementation plan for process-centric admin capabilities, auth boundaries, and test gates |
 
 ## Key Principles
 
 1. **Dogfooding** — The admin UI is built entirely with jsgui3 controls. Every pattern used here validates the framework.
-2. **Zero Configuration** — The admin UI is available at `/admin/v1` on every jsgui3-server instance with no extra setup.
+2. **Zero Configuration** — The admin UI is available at `/admin/v1` on every jsgui3-server instance with no extra setup.
 3. **Read Before Write** — The admin UI primarily reads and displays server state. Write operations (restart, config change) are guarded and opt-in.
 4. **Incremental Delivery** — Each domain control is independently functional. The shell composes them, but each can be developed and tested in isolation.
 5. **Real Data Only** — No mock data in production. Every number shown comes from actual server telemetry.
@@ -53,16 +53,16 @@ The visual design is inspired by a Windows Aero-era aesthetic — glass-effect t
 ## Directory Structure
 
 ```
-admin-ui/
-├── v1/
-│   ├── client.js              # Client-side entry point (registers Admin_Shell)
-│   ├── server.js              # Admin module (adapter layer + auth + telemetry)
-│   ├── admin_auth_service.js  # Session auth service
-│   ├── admin_user_store.js    # In-memory user store
-│   ├── controls/
-│   │   ├── admin_shell.js     # Main shell with sidebar + content
-│   │   ├── stat_card.js       # Stat card control
-│   │   └── group_box.js       # Reusable grouped panel container
-│   └── utils/
-│       └── formatters.js      # Shared formatting helpers
-```
+admin-ui/
+├── v1/
+│   ├── client.js              # Client-side entry point (registers Admin_Shell)
+│   ├── server.js              # Admin module (adapter layer + auth + telemetry)
+│   ├── admin_auth_service.js  # Session auth service
+│   ├── admin_user_store.js    # In-memory user store
+│   ├── controls/
+│   │   ├── admin_shell.js     # Main shell with sidebar + content
+│   │   ├── stat_card.js       # Stat card control
+│   │   └── group_box.js       # Reusable grouped panel container
+│   └── utils/
+│       └── formatters.js      # Shared formatting helpers
+```

package/docs/books/website-design/01-introduction.md

@@ -0,0 +1,73 @@
+# Chapter 1: Introduction & Vision
+
+## The Problem
+
+`jsgui3-server` can serve web pages. You give it a control, it bundles it, wraps it in HTML, and serves it. That works well for single-page apps:
+
+```js
+Server.serve(My_Control);
+```
+
+But what about a website with multiple pages, API endpoints, static assets, metadata, and navigation? Today you pass a flat options object:
+
+```js
+Server.serve({
+    pages: {
+        '/': { content: Home },
+        '/about': { content: About }
+    },
+    api: {
+        'get-users': () => db.get_users()
+    }
+});
+```
+
+This works, but it's just configuration — a bag of options that the server interprets. There's no object you can hold, inspect, pass around, or ask questions of. You can't say "how many pages does this site have?" or "what are its API endpoints?" without knowing the internal structure of the options object.
+
+## The Vision
+
+Two sibling NPM packages — `jsgui3-website` and `jsgui3-webpage` — should provide **abstract representations** of websites and webpages. They describe *what* a site is, independent of *how* it gets served.
+
+```
+jsgui3-webpage    →   "a page has a path, title, content, and metadata"
+jsgui3-website    →   "a website has pages, API endpoints, assets, and metadata"
+jsgui3-server     →   "I know how to serve those"
+```
+
+## The Core Design Tension
+
+There's a fundamental tension in this design:
+
+### Simplicity vs. Capability
+
+A Webpage could be as simple as:
+```js
+{ path: '/about', content: About_Control, title: 'About' }
+```
+
+Or as rich as an evented, observable, lifecycle-managed object with change tracking, validation, and introspection. The question is: how much machinery earns its keep?
+
+### Abstraction vs. Coupling
+
+These modules should be useful *without* jsgui3-server — maybe for a static site generator, a build tool, or just as a way to describe a site structure. But they also need to work well *with* jsgui3-server. More features means more coupling.
+
+### Convention vs. Configuration
+
+Should a Webpage default its path to `'/'`? Should it assume static rendering? Every default is convenient for the common case but can mask errors in complex cases.
+
+## The Constraint
+
+**These abstractions must remain optional.** `jsgui3-server` works today without them and must continue to do so. A developer who just wants `Server.serve(MyCtrl)` should never need to know about `Website` or `Webpage`. They are a useful layer for developers who want richer website definitions.
+
+## How This Book is Organized
+
+Each chapter explores a specific design dimension with multiple approaches. The goal is not to pick a winner but to lay out the tradeoffs clearly, so the best combination can emerge from informed discussion.
+
+- **Chapter 2** documents what exists today
+- **Chapters 3–7** explore specific design choices (base class, webpage, website, pages, API)
+- **Chapter 8** covers server-side integration
+- **Chapter 9** presents a cross-agent review
+- **Chapter 10** lists open questions
+- **Chapter 11** converges the discussion into a concrete recommended baseline
+
+No code will be implemented until the design discussion converges.

package/docs/books/website-design/02-current-state.md

@@ -0,0 +1,195 @@
+# Chapter 2: Current State
+
+Both repos exist on NPM at version 0.0.8. Both are near-empty skeletons. This chapter documents the **exact, complete** code in each, and how `jsgui3-server` uses them today.
+
+---
+
+## 2.1 jsgui3-webpage
+
+**Repository**: `github.com/metabench/jsgui3-webpage`  
+**Version**: 0.0.8  
+**Total source files**: 3 (Webpage.js, package.json, README.md)
+
+### Webpage.js — the entire module
+
+```js
+/*
+    Probably does not need to do very much apart from hold info for the moment.
+    Could make subclasses do things like generare its specific parts from spec.
+*/
+
+class Webpage {
+    constructor(spec) {
+        Object.assign(this, spec);
+    }
+}
+
+module.exports = Webpage;
+```
+
+That's it. A class that copies spec properties onto itself. No methods, no validation, no dependencies.
+
+### package.json
+
+```json
+{
+    "name": "jsgui3-webpage",
+    "main": "Webpage.js",
+    "license": "MIT",
+    "comments": [
+        "Just depend on jsgui3-html for the moment. This would be a website in the abstract sense.",
+        { "jsgui3-html": "^0.0.139" }
+    ],
+    "dependencies": {},
+    "version": "0.0.8"
+}
+```
+
+`jsgui3-html` is mentioned in `comments` but is NOT an actual dependency. There are zero runtime dependencies.
+
+### README.md
+
+```
+# jsgui3-webpage
+A class that represents a webpage.
+```
+
+---
+
+## 2.2 jsgui3-website
+
+**Repository**: `github.com/metabench/jsgui3-website`  
+**Version**: 0.0.8  
+**Total source files**: 4 (Website.js, API.js, package.json, README.md)
+
+### Website.js
+
+```js
+/*
+    Probably does not need to do very much apart from hold info for the moment.
+    Could make subclasses do things like generare its specific parts from spec.
+*/
+const API = require('./API');
+
+class Website {
+    constructor(spec) {
+        Object.assign(this, spec);
+        this.api = new API({ server: this.server });
+    }
+}
+
+module.exports = Website;
+```
+
+Copies spec properties, then creates an API instance. The `this.server` reference comes from whatever was passed in the spec.
+
+### API.js — contains a bug
+
+```js
+class API {
+    constructor(spec) {
+        this.server = spec.server;
+    }
+
+    publish(name, fn) {
+        // Need to access the appropriate resource publisher.
+        const {server} = this;
+    }
+}
+
+MediaSourceHandle.exports = API
+```
+
+**Bug**: The last line says `MediaSourceHandle.exports` instead of `module.exports`. This is a typo (likely an autocomplete error) that will crash at runtime with `ReferenceError: MediaSourceHandle is not defined`. Any code that `require('./API')` will fail.
+
+### package.json
+
+```json
+{
+    "name": "jsgui3-website",
+    "main": "Website.js",
+    "license": "MIT",
+    "comments": [
+        "Just depend on jsgui3-html for the moment. This would be a website in the abstract sense.",
+        { "jsgui3-html": "^0.0.139" }
+    ],
+    "dependencies": {},
+    "version": "0.0.8"
+}
+```
+
+Same pattern — zero actual dependencies.
+
+### README.md
+
+```
+# jsgui3-website
+A class that represents a website. Also has functionality to deploy the website.
+```
+
+---
+
+## 2.3 How jsgui3-server Uses Them Today
+
+`jsgui3-server` declares both as dependencies (`^0.0.8`) and uses them in several places:
+
+### The re-export wrappers
+
+```
+jsgui3-server/website/website.js  →  module.exports = require('jsgui3-website')
+jsgui3-server/website/webpage.js  →  module.exports = require('jsgui3-webpage')
+```
+
+Both files also contain dead code — `Obselete_Style_Website` and `Obselete_Style_Webpage` classes that are defined but never used elsewhere.
+
+### Usage in server.js
+
+**When a control is provided** (line 354):
+```js
+const wp_app = new Webpage({ content: Ctrl });
+```
+Creates a Webpage as a thin wrapper around a control constructor. The Webpage is then handed to `HTTP_Webpage_Publisher` for bundling.
+
+**When no control is provided** (line 428):
+```js
+const ws_app = new Website(opts_website);
+```
+Creates a Website as a placeholder. Handed to `HTTP_Website_Publisher`.
+
+### Usage in serve-factory.js
+
+When multi-page serving is configured via the `pages` option:
+```js
+const webpage = new Webpage({ name, title, content, path });
+```
+Creates a Webpage per route and hands each to `prepare_webpage_route`.
+
+### Usage in publishers
+
+`http-website-publisher.js` type-checks:
+```js
+spec.website instanceof Website
+```
+
+And iterates pages via the internal `website.pages._arr` (Collection internals).
+
+### The Admin UI pattern
+
+The admin UI in `server.js` (lines 108–134, 167–327) shows a real-world pattern for adding a multi-route "app" to the server:
+
+1. Create a `Webpage` with a control as content
+2. Create an `HTTP_Webpage_Publisher` with that webpage
+3. Listen for the publisher's `'ready'` event
+4. Register the bundled output as static routes on the router
+
+This pattern — Webpage → Publisher → Router — is the pipeline that any Website/Webpage design needs to work with.
+
+---
+
+## 2.4 What This Tells Us
+
+1. **The classes are property bags** — `Object.assign(this, spec)` means anything goes in, nothing is validated
+2. **The server constructs them internally** — users don't currently create Website/Webpage objects; the server does it behind the scenes
+3. **The publisher pipeline is the real work** — the interesting code is in the publishers, not in the domain classes
+4. **The API.js bug means Website construction actually crashes** — the `require('./API')` in Website.js will fail due to the export typo, meaning `new Website()` in the server only works because the API module isn't actually loadable (this is masked because the server may catch or not reach that code path)
+5. **There's significant dead code** — the `Obselete_Style_*` classes and most of `http-website-publisher.js` (580+ lines of comments/stubs) are inactive

package/docs/books/website-design/03-base-class.md

@@ -0,0 +1,181 @@
+# Chapter 3: The Base Class Question
+
+The most foundational design decision for both `Webpage` and `Website` is what they inherit from. This choice shapes everything that follows — how properties work, whether events exist, what ecosystem patterns are available.
+
+---
+
+## Option 1: Plain Class
+
+```js
+class Webpage {
+    constructor(spec = {}) {
+        this.name = spec.name;
+        this.title = spec.title;
+        this.path = spec.path;
+        this.content = spec.content;
+    }
+}
+```
+
+### The case for it
+
+- **Maximum simplicity** — anyone reading it knows exactly what it does
+- **Zero dependencies** — doesn't import anything from jsgui3-html
+- **Easy to test** — no setup, no teardown, no event system to mock
+- **Familiar** — looks like any plain JavaScript class
+
+### The case against it
+
+- **Inconsistent with the ecosystem** — nearly every non-trivial object in jsgui3 extends `Evented_Class`. Controls do. The server does. Resources, publishers, routers — all evented. A plain `Webpage` would be the odd one out.
+- **Can't add events later without breaking** — if you later want `Webpage` to emit events (e.g. `'ready'`), changing the base class is a breaking change for any subclasses.
+- **No `.on()` / `.raise()` pattern** — these are the fundamental building blocks of jsgui3's event system, widely used for lifecycle coordination.
+
+### When it makes sense
+
+When the object is purely a data structure with no lifecycle, no reactivity, and no expectation that it will ever need events. A config object. A DTO.
+
+---
+
+## Option 2: `obext` Properties
+
+```js
+const { prop } = require('obext');
+
+class Webpage {
+    constructor(spec = {}) {
+        prop(this, 'name', spec.name);
+        prop(this, 'title', spec.title);
+        prop(this, 'path', spec.path);
+        prop(this, 'content', spec.content);
+    }
+}
+```
+
+### The case for it
+
+- **Consistent with jsgui3-server** — `server.js` uses `obext` extensively for its own properties (`disk_path_client_js`, `Ctrl`, `name`)
+- **Encapsulation** — properties go through getter/setter, so behavior can be added later without changing the public API
+- **Already in the dependency tree** — `jsgui3-html` depends on `obext`, so it's available at zero cost
+
+### The case against it
+
+- **Not a base class decision** — `obext` is a property mechanism, not a class hierarchy choice. You can use `obext` properties *and* extend `Evented_Class`. They're orthogonal.
+- **Adds a layer of indirection** — every property access goes through a getter/setter. Usually negligible, but it's hidden complexity.
+- **Not widely understood** — `obext` is a jsgui3 ecosystem tool, not a standard JS pattern. New contributors need to learn it.
+
+### When it makes sense
+
+When you want encapsulated properties but don't need (or aren't sure about) full event support. Good for a "grow into it" strategy.
+
+---
+
+## Option 3: Extend `Evented_Class`
+
+```js
+const { Evented_Class } = require('jsgui3-html');
+
+class Webpage extends Evented_Class {
+    constructor(spec = {}) {
+        super();
+        this.name = spec.name;
+        this.title = spec.title;
+        this.path = spec.path;
+        this.content = spec.content;
+    }
+}
+```
+
+### The case for it
+
+- **It's the ecosystem standard** — nearly everything in jsgui3 extends `Evented_Class`. Using it here means `Webpage` and `Website` participate in the same patterns as controls, resources, and the server itself.
+- **The capability is free** — extending `Evented_Class` doesn't force you to fire events on every property. You get `.on()` and `.raise()` as available tools. If nobody listens, the cost is a few extra bytes of prototype chain.
+- **Future-proof** — once you ship without `Evented_Class`, adding it later is a breaking change. Starting with it costs almost nothing.
+- **Real use cases exist** — a Website could raise `'page-added'`, `'ready'`, or `'error'`. A Webpage could raise `'content-changed'` for live reload. The admin UI already watches resources via events.
+- **Doesn't require per-property events** — this is a crucial distinction. Extending `Evented_Class` does NOT mean wrapping every property in a change-event-firing setter. You can have simple `this.name = spec.name` assignments and only raise events for meaningful lifecycle moments.
+
+### The case against it
+
+- **Couples to jsgui3-html** — `Evented_Class` comes from `jsgui3-html`. If someone wanted to use `Webpage` without `jsgui3-html`, they couldn't.
+- **Perceived complexity** — someone reading the code might think "events? for a webpage?" and assume it's over-engineered, even if no events are actually used.
+- **Boilerplate concern** — if you do decide to fire change events on properties, each one needs a manual getter/setter with `this.raise()`.
+
+### When it makes sense
+
+When the object participates in a lifecycle, when other parts of the system might want to observe it, or when you're building within an ecosystem where `Evented_Class` is the norm.
+
+---
+
+## Option 4: Combined — Evented_Class + obext
+
+```js
+const { Evented_Class } = require('jsgui3-html');
+const { prop } = require('obext');
+
+class Webpage extends Evented_Class {
+    constructor(spec = {}) {
+        super();
+        prop(this, 'name', spec.name);
+        prop(this, 'title', spec.title);
+        prop(this, 'path', spec.path);
+        prop(this, 'content', spec.content);
+        prop(this, 'meta', spec.meta || {});
+    }
+}
+```
+
+### The case for it
+
+- **Best of both** — event system for lifecycle, encapsulated properties for cleanliness
+- **Matches server.js exactly** — the server itself uses `Evented_Class` as a base and `obext` for properties
+- **Maximum future flexibility** — events AND property interception available
+
+### The case against it
+
+- **Most complex option** — two dependency systems in play
+- **Is the combination actually needed?** — if nobody is observing property changes on webpages, `obext` adds machinery without a use case
+
+---
+
+## Discussion: Boilerplate vs. Capability
+
+A common concern with `Evented_Class` is the boilerplate needed for per-property change events:
+
+```js
+get title() { return this._title; }
+set title(v) {
+    const old = this._title;
+    this._title = v;
+    this.raise('change', { field: 'title', old, value: v });
+}
+```
+
+But this is a **false dilemma**. You don't have to choose between "no events" and "events on every property." The pragmatic approach:
+
+1. **Extend `Evented_Class`** — get the capability for free
+2. **Use simple property assignment** — `this.title = spec.title`
+3. **Raise events only for meaningful actions** — `this.raise('page-added', page)`, `this.raise('ready')`
+
+This is exactly how the server works. It extends `Evented_Class` and raises `'ready'`, `'listening'`, `'starting'` — not per-property change events.
+
+---
+
+## Comparison Table
+
+| Criterion | Plain | obext | Evented | Combined |
+|---|:---:|:---:|:---:|:---:|
+| Simplicity | ★★★ | ★★☆ | ★★☆ | ★★☆ |
+| Ecosystem consistency | ★☆☆ | ★★☆ | ★★★ | ★★★ |
+| Zero jsgui3-html coupling | ★★★ | ★★☆ | ☆☆☆ | ☆☆☆ |
+| Future event support | ☆☆☆ | ★☆☆ | ★★★ | ★★★ |
+| Property encapsulation | ☆☆☆ | ★★★ | ★☆☆ | ★★★ |
+| Matches server.js pattern | ☆☆☆ | ★★☆ | ★★☆ | ★★★ |
+
+---
+
+## The Author's View
+
+Both modules will depend on `jsgui3-html` (this is a stated requirement). Given that, the coupling argument against `Evented_Class` disappears — you're already importing `jsgui3-html`.
+
+In an ecosystem where `Evented_Class` is the norm, not using it requires justification. The justification would need to be "this object will never participate in lifecycle events" — but a Website with pages, API endpoints, and a publishing pipeline absolutely will.
+
+The recommended starting point is **Option 3** (Evented_Class with simple properties), with the option to add `obext` for specific properties if encapsulation needs arise.