jsgui3-server 0.0.151 → 0.0.155

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.

package/docs/books/website-design/04-webpage.md

@@ -0,0 +1,307 @@
+# Chapter 4: Designing the Webpage
+
+A `Webpage` represents a single page in the abstract. It holds everything needed to describe what the page *is*, without knowing how to serve it. This chapter explores three approaches with increasing richness.
+
+---
+
+## What properties should a Webpage have?
+
+Before choosing an implementation, we need to agree on what a page knows about itself.
+
+### Essential properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `name` | `string` | Human-readable identifier |
+| `title` | `string` | HTML `<title>` tag content |
+| `path` | `string` | URL route (e.g. `/about`) |
+| `content` | `Control` or constructor | The page body |
+| `meta` | `object` | SEO and social metadata |
+
+### Extended properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `client_js` | `string` | Path to client-side JS entry point |
+| `favicon` | `string` | Page-specific favicon |
+| `scripts` | `string[]` | Additional script tags |
+| `stylesheets` | `string[]` | Additional stylesheet links |
+
+### Debatable properties
+
+| Property | Type | Discussion |
+|----------|------|-----------|
+| `render_mode` | `'static'` or `'dynamic'` | See discussion below |
+| `cache_policy` | `object` | Cache headers — abstraction or server detail? |
+| `route_priority` | `number` | Ordering hint — useful or over-engineering? |
+
+### Should `render_mode` live on the page?
+
+The question: is rendering strategy a page concern or a server concern?
+
+**The case for "server concern"**: The server decides how to bundle and serve. A page author shouldn't need to think about pre-rendering vs. per-request rendering — that's infrastructure. Keeping `render_mode` off the page keeps the page purely descriptive.
+
+**The case for "page concern"**: Some pages *inherently* need dynamic rendering — a user profile that changes per-request can't be pre-rendered. The page author knows this; the server doesn't. Without a `render_mode` hint, the server either guesses (fragile) or forces all pages through the same pipeline (limiting).
+
+**The deciding argument**: Today, `is_dynamic` (Approach B below) infers rendering strategy from the content type — `typeof content === 'function'` means dynamic. But this conflates "content is a class constructor" with "content must be rendered per-request." A control constructor might produce static output that's identical for every visitor. An explicit `render_mode` separates the *how to serve* question from the *what is the content* question.
+
+**Resolution**: `render_mode` belongs on the Webpage as an **optional, recommended** field. It defaults to `undefined` (server decides based on content type, matching current behavior). When explicitly set, it overrides the server's inference. This is additive — existing code that doesn't set `render_mode` works exactly as before.
+
+---
+
+## Approach A: Enhanced Property Bag
+
+The simplest evolution of the current skeleton. Explicitly declare known properties instead of blindly `Object.assign`.
+
+```js
+const { Evented_Class } = require('jsgui3-html');
+
+class Webpage extends Evented_Class {
+    constructor(spec = {}) {
+        super();
+
+        this.name = spec.name || undefined;
+        this.title = spec.title || undefined;
+        this.path = spec.path;           // No default — explicit is safer
+        this.content = spec.content || undefined;
+        this.meta = spec.meta || {};
+        this.client_js = spec.client_js || undefined;
+    }
+}
+
+module.exports = Webpage;
+```
+
+### Discussion
+
+**What's good about this:**
+- Dead simple — 13 lines of actual code
+- Every property is visible in the constructor — excellent for discoverability
+- Extends `Evented_Class` so lifecycle events are available if needed
+- No default `path` — in a multi-page website, defaulting to `'/'` could silently create collisions
+
+**What's missing:**
+- No validation — `content` could be a string, a number, anything
+- No computed properties — can't ask "does this page have content?"
+- No serialization — no `toJSON()` for admin/tooling introspection
+- No way to tell if a spec property was explicitly set vs. just absent
+
+**Best for:** Getting started quickly. You can always add methods later without breaking anything because the base class is right.
+
+---
+
+## Approach B: With Computed Properties and Introspection
+
+Adds helpers that make the Webpage useful to servers, admin UIs, and tooling.
+
+```js
+const { Evented_Class } = require('jsgui3-html');
+
+class Webpage extends Evented_Class {
+    constructor(spec = {}) {
+        super();
+
+        this.name = spec.name || undefined;
+        this.title = spec.title || undefined;
+        this.path = spec.path;
+        this.content = spec.content || undefined;
+        this.meta = spec.meta || {};
+        this.client_js = spec.client_js || undefined;
+        this.favicon = spec.favicon || undefined;
+        this.scripts = spec.scripts || [];
+        this.stylesheets = spec.stylesheets || [];
+    }
+
+    /** Does this page have renderable content? */
+    get has_content() {
+        return this.content !== undefined && this.content !== null;
+    }
+
+    /**
+     * Is the content a constructor/function (needs instantiation)
+     * vs. an existing instance?
+     */
+    get is_dynamic() {
+        return typeof this.content === 'function';
+    }
+
+    /** Stable, deterministic serialization for admin/tooling */
+    toJSON() {
+        return {
+            name: this.name,
+            title: this.title,
+            path: this.path,
+            has_content: this.has_content,
+            is_dynamic: this.is_dynamic,
+            meta: this.meta
+        };
+    }
+}
+
+module.exports = Webpage;
+```
+
+### Discussion
+
+**What's good about this:**
+
+- `has_content` and `is_dynamic` answer questions that publishers currently figure out themselves — moves that logic to the source of truth
+- `toJSON()` gives admin UIs and diagnostic tools a stable contract to rely on — they don't need to understand the class internals
+- `scripts` and `stylesheets` arrays let pages declare additional assets beyond what the bundler produces — useful for third-party libraries, analytics scripts, etc.
+- Still very readable — the computed properties are clearly getters, not hidden magic
+
+**What's debatable:**
+
+- Should `toJSON()` include `content`? The content is usually a class constructor, which doesn't serialize. Including it could cause confusion. Excluding it means the JSON is a summary, not a full representation.
+- Are `scripts` and `stylesheets` page concerns or server concerns? Today the server/publisher decides what goes into the HTML `<head>`. Moving that to the page definition shifts responsibility.
+- `is_dynamic` currently means "content is a function" — but the term "dynamic" could also mean "rendered per-request." The naming might be confusing when `render_mode` enters the picture.
+
+**Best for:** A practical middle ground that's immediately useful without over-engineering.
+
+---
+
+## Approach C: With Validation and Lifecycle
+
+Adds input validation and lifecycle semantics.
+
+```js
+const { Evented_Class, tof } = require('jsgui3-html');
+
+class Webpage extends Evented_Class {
+    constructor(spec = {}) {
+        super();
+
+        // Validate path format
+        if (spec.path !== undefined) {
+            if (typeof spec.path !== 'string') {
+                throw new TypeError(`Webpage path must be a string, got ${tof(spec.path)}`);
+            }
+            // Normalize: ensure leading slash
+            this.path = spec.path.startsWith('/') ? spec.path : '/' + spec.path;
+        } else {
+            this.path = undefined;
+        }
+
+        // Validate content type
+        if (spec.content !== undefined) {
+            const ct = tof(spec.content);
+            if (ct !== 'function' && ct !== 'object') {
+                throw new TypeError(
+                    `Webpage content must be a Control constructor or instance, got ${ct}`
+                );
+            }
+        }
+
+        this.name = spec.name || undefined;
+        this.title = spec.title || undefined;
+        this.content = spec.content || undefined;
+        this.meta = spec.meta || {};
+        this.client_js = spec.client_js || undefined;
+        this.favicon = spec.favicon || undefined;
+        this.scripts = spec.scripts || [];
+        this.stylesheets = spec.stylesheets || [];
+
+        this._finalized = false;
+    }
+
+    get has_content() {
+        return this.content !== undefined && this.content !== null;
+    }
+
+    get is_dynamic() {
+        return typeof this.content === 'function';
+    }
+
+    /**
+     * Mark this webpage as finalized — no further mutations expected.
+     * Called by the publisher before bundling. Optional but useful
+     * for catching accidental late modifications.
+     */
+    finalize() {
+        if (this._finalized) return this;
+        this._finalized = true;
+        this.raise('finalized');
+        return this;
+    }
+
+    get finalized() {
+        return this._finalized;
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            title: this.title,
+            path: this.path,
+            has_content: this.has_content,
+            is_dynamic: this.is_dynamic,
+            finalized: this._finalized,
+            meta: this.meta
+        };
+    }
+}
+
+module.exports = Webpage;
+```
+
+### Discussion
+
+**What's good about this:**
+
+- **Path normalization** — ensures leading slash, catches non-string paths early. Today a missing `'/'` prefix would silently create a broken route.
+- **Content validation** — catches `content: 42` or `content: 'whoops'` at construction time instead of deep in the publisher pipeline where the error is confusing.
+- **`finalize()` lifecycle** — this was suggested by the OpenAI reviewer as an alternative to full reactivity. The idea: a Webpage is mutable during composition and read-mostly after `finalize()` is called. This gives publishers confidence that the page won't change under them without requiring a full event system for every property.
+- Uses `tof()` from jsgui3-html for type checking — ecosystem-consistent.
+
+**What's debatable:**
+
+- Is validation in the constructor too strict? If someone passes `content: null` temporarily and sets it later, the validation could get in the way. Counter-argument: if content is set later, `null` would pass validation (only non-null non-function/object types are rejected).
+- `finalize()` is a new concept not used elsewhere in jsgui3. It adds cognitive load. Counter-argument: it's simple enough to ignore — just don't call it.
+- Path normalization makes an opinionated choice. What about root-relative vs. absolute paths? What about paths with query strings or fragments?
+
+**Best for:** When you want construction-time safety and a clear lifecycle boundary.
+
+---
+
+## Comparison
+
+| Criterion | A (Property Bag) | B (Computed + toJSON) | C (Validation + Lifecycle) |
+|---|:---:|:---:|:---:|
+| Lines of code | ~13 | ~40 | ~65 |
+| Input validation | ☆ | ☆ | ★★★ |
+| Introspection | ☆ | ★★★ | ★★★ |
+| Lifecycle support | ☆ | ☆ | ★★ |
+| Ease of understanding | ★★★ | ★★★ | ★★☆ |
+| Catches bugs early | ☆ | ★ | ★★★ |
+| Can evolve into C | ★★★ | ★★★ | — |
+
+Note that all three extend `Evented_Class`, so they all have event capability. The difference is in how much the class *does* with that capability.
+
+---
+
+## Should `Object.assign(this, spec)` stay?
+
+The current code does `Object.assign(this, spec)`, which copies ALL spec properties onto the instance — including unknown/unexpected ones. This is a double-edged sword:
+
+**For**: Maximum flexibility. Users can put anything in spec and it "just works." Good for rapid prototyping and forward compatibility (adding new fields doesn't require class changes).
+
+**Against**: No discoverability. Typos in property names silently create wrong properties. No way to enumerate "known" vs. "extra" properties. Makes the class contract unclear.
+
+**A middle ground**: Explicitly assign known properties, then optionally store extras:
+
+```js
+// Known properties
+this.name = spec.name;
+this.title = spec.title;
+// ...
+
+// Store any additional spec properties for extensibility
+this.extra = {};
+for (const key of Object.keys(spec)) {
+    if (!['name', 'title', 'path', 'content', 'meta', 'client_js'].includes(key)) {
+        this.extra[key] = spec[key];
+    }
+}
+```
+
+This preserves flexibility while making the primary contract explicit. Whether this is worth the complexity depends on how important forward compatibility is.