jsgui3-server 0.0.151 → 0.0.152

package/README.md

@@ -33,6 +33,27 @@ Server.serve(MyControl);
 Server.serve(MyControl, { port: 3000 });
 ```
 
+### Port Conflict Fallback
+
+```javascript
+Server.serve({
+  Ctrl: MyControl,
+  port: 52000,
+  on_port_conflict: 'auto-loopback' // retry on 127.0.0.1 with a free port
+});
+```
+
+With manual `server.start(...)`, you can print the effective endpoint:
+
+```javascript
+server.start(52000, (err) => {
+  if (err) throw err;
+  server.print_endpoints({ include_index: true });
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
 ### Single Page with Metadata
 
 ```javascript

package/admin-ui/v1/controls/admin_shell.js

@@ -647,6 +647,39 @@ class Admin_Shell extends Active_HTML_Document {
                 panel.add(this._create_kv_row('Node Version', node_version));
                 panel.add(this._create_kv_row('Platform', platform + ' / ' + arch));
 
+                const primary_endpoint = (status && status.server && status.server.primary_endpoint) || '—';
+                const listening_endpoints = (status && status.server && status.server.listening_endpoints) || [];
+                const startup_diagnostics = (status && status.server && status.server.startup_diagnostics) || null;
+
+                const startup_panel = this._create_panel('Startup & Network');
+                startup_panel.add(this._create_kv_row('Primary Endpoint', primary_endpoint));
+                startup_panel.add(this._create_kv_row('Listening Endpoints', listening_endpoints.length));
+
+                if (Array.isArray(listening_endpoints) && listening_endpoints.length > 0) {
+                    const endpoints_list = new controls.div({ context: this.context, 'class': 'as-kv-stack' });
+                    listening_endpoints.forEach((endpoint, index) => {
+                        const endpoint_url = endpoint && endpoint.url ? endpoint.url : '';
+                        endpoints_list.add(this._create_kv_row('Endpoint ' + (index + 1), endpoint_url));
+                    });
+                    startup_panel.add(endpoints_list);
+                }
+
+                if (startup_diagnostics) {
+                    startup_panel.add(this._create_kv_row('Requested Port', startup_diagnostics.requested_port));
+                    if (startup_diagnostics.fallback_port) {
+                        startup_panel.add(this._create_kv_row('Fallback Port', startup_diagnostics.fallback_port));
+                    }
+                    if (startup_diagnostics.fallback_host) {
+                        startup_panel.add(this._create_kv_row('Fallback Host', startup_diagnostics.fallback_host));
+                    }
+                    const attempted = Array.isArray(startup_diagnostics.addresses_attempted)
+                        ? startup_diagnostics.addresses_attempted.join(', ')
+                        : '';
+                    startup_panel.add(this._create_kv_row('Addresses Attempted', attempted || '—'));
+                }
+
+                panel.add(startup_panel);
+
                 const logout_btn = new controls.button({ context: this.context, 'class': 'as-logout-btn' });
                 logout_btn.dom.attributes.type = 'button';
                 logout_btn.add('Log Out');

package/admin-ui/v1/server.js

@@ -205,6 +205,16 @@ class Admin_Module_V1 {
         const mem = process.memoryUsage();
         const pool_summary = this._safe_pool_summary(server);
 
+        const listening_endpoints = (server && typeof server.get_listening_endpoints === 'function')
+            ? server.get_listening_endpoints()
+            : [];
+        const primary_endpoint = (server && typeof server.get_primary_endpoint === 'function')
+            ? server.get_primary_endpoint()
+            : null;
+        const startup_diagnostics = (server && typeof server.get_startup_diagnostics === 'function')
+            ? server.get_startup_diagnostics()
+            : null;
+
         return {
             process: {
                 pid: process.pid,
@@ -222,7 +232,10 @@ class Admin_Module_V1 {
             },
             server: {
                 port: (server && server.port) || null,
-                name: (server && server.name) || 'jsgui3-server'
+                name: (server && server.name) || 'jsgui3-server',
+                primary_endpoint,
+                listening_endpoints,
+                startup_diagnostics
             },
             telemetry: {
                 request_count: this._request_count,

package/docs/api-reference.md

@@ -93,18 +93,32 @@ jsgui.Resource.Remote_Process;
 
 ## Server Instance Methods
 
-### server.start(port, callback)
+### server.start(port, callback, options)
 
 Starts the HTTP server (legacy API).
 
 **Signature:**
 ```javascript
-server.start(port?: number, callback?: (err?: Error) => void): void
+server.start(
+  port?: number,
+  callback?: (err?: Error) => void,
+  options?: {
+    on_port_conflict?: 'error' | 'auto-loopback'
+  }
+): void
 ```
 
 **Parameters:**
 - `port` (number, optional): Port to listen on (default: 8080)
 - `callback` (function, optional): Called when server starts or fails
+- `options` (object, optional): Startup behavior options
+  - `on_port_conflict: 'error' | 'auto-loopback'`
+    - `error` (default): Return startup error as usual.
+    - `auto-loopback`: If all requested interface binds fail with `EADDRINUSE`,
+      retry once on `127.0.0.1` using a free port.
+
+When startup fails, the returned error may include `error.startup_diagnostics`
+containing attempted addresses and per-address errors.
 
 ### server.publish(route, handler)
 
@@ -151,6 +165,106 @@ server.close(callback?: (err?: Error | null) => void): void
 - Stops `sse_publisher` when present
 - Closes all HTTP listeners
 
+### server.get_listening_endpoints()
+
+Returns the active listener endpoints (protocol, host, port, url) for the
+current process. Useful when startup falls back from a requested fixed port to
+an auto-selected loopback port.
+
+**Signature:**
+```javascript
+server.get_listening_endpoints(): Array<{
+  protocol: 'http' | 'https';
+  host: string;
+  port: number;
+  url: string;
+}>
+```
+
+**Example:**
+```javascript
+server.start(52000, (err) => {
+  if (err) throw err;
+  console.log('Listening at', server.get_primary_endpoint());
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
+### server.get_primary_endpoint()
+
+Returns the primary endpoint URL string (first endpoint) or `null` if the
+server is not listening.
+
+**Signature:**
+```javascript
+server.get_primary_endpoint(): string | null
+```
+
+**Example:**
+```javascript
+const url = server.get_primary_endpoint();
+if (url) {
+  console.log('Primary endpoint:', url);
+}
+```
+
+### server.print_endpoints(options)
+
+Prints listening endpoint URLs and returns the printed lines.
+
+**Signature:**
+```javascript
+server.print_endpoints(options?: {
+  logger?: (line: string) => void;
+  include_index?: boolean;
+  prefix?: string;
+}): string[]
+```
+
+**Parameters:**
+- `options.logger` (function, optional): Line logger (default: `console.log`)
+- `options.include_index` (boolean, optional): Include endpoint index in output
+- `options.prefix` (string, optional): Prefix text (default: `"listening endpoint"`)
+
+**Example:**
+```javascript
+server.start(52000, (err) => {
+  if (err) throw err;
+  server.print_endpoints({ include_index: true });
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
+### server.get_startup_diagnostics()
+
+Returns startup diagnostics information or `null` when unavailable.
+
+**Signature:**
+```javascript
+server.get_startup_diagnostics(): {
+  requested_port: number;
+  fallback_port?: number;
+  fallback_host?: string;
+  addresses_attempted: string[];
+  errors_by_address: Record<string, { code?: string; message?: string }>;
+} | null
+```
+
+**Example:**
+```javascript
+server.start(52000, (err) => {
+  if (err) {
+    console.error(server.get_startup_diagnostics());
+    throw err;
+  }
+  console.log(server.get_startup_diagnostics());
+}, {
+  on_port_conflict: 'auto-loopback'
+});
+```
+
 ### server.use(fn)
 
 Register middleware to run before every request is routed. Middleware is executed
@@ -992,6 +1106,10 @@ interface ServerOptions {
   src_path_client_js?: string;
   port?: number;
   host?: string;
+  on_port_conflict?: 'error' | 'auto-loopback';
+  start?: {
+    on_port_conflict?: 'error' | 'auto-loopback';
+  };
   debug?: boolean;
   name?: string;
   root?: string;

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