jsgui3-server 0.0.150 → 0.0.152

package/docs/books/website-design/07-api-layer.md

@@ -0,0 +1,285 @@
+# Chapter 7: The API Layer
+
+A Website can describe API endpoints — functions that return data rather than HTML pages. This chapter discusses how those endpoints should be represented in the abstract, before the server gets involved.
+
+---
+
+## What the Server Does Today
+
+`jsgui3-server` already supports API endpoints in two ways:
+
+### 1. The `api` option in `Server.serve()`
+
+```js
+Server.serve({
+    api: {
+        'get-users': () => db.get_users(),
+        'create-user': (data) => db.create_user(data)
+    }
+});
+```
+
+Each key becomes a route at `/api/<name>`. The value is a handler function. This is simple and effective for basic APIs.
+
+### 2. The `server.publish()` method
+
+```js
+server.publish('get-users', () => db.get_users());
+```
+
+This creates an `HTTP_Function_Publisher` and registers it at `/api/<name>`. If the name starts with `/`, it's used as a full route.
+
+Both approaches are just `name → function` mappings. There's no metadata — no HTTP method, no description, no authentication spec, no documentation.
+
+---
+
+## What Should a Website's API Know?
+
+### Minimal: name + handler
+
+```js
+site.api = {
+    'get-users': () => db.get_users()
+};
+```
+
+This mirrors `Server.serve({ api: {...} })` exactly. The server already knows how to consume this format.
+
+### With method
+
+```js
+site.api = {
+    'get-users':    { handler: () => db.get_users(), method: 'GET' },
+    'create-user':  { handler: (data) => db.create_user(data), method: 'POST' }
+};
+```
+
+HTTP method matters for RESTful APIs. Today's server publishes everything as `GET` by default. Adding method information lets the server set up more correct routing.
+
+### With metadata
+
+```js
+site.api = {
+    'get-users': {
+        handler: () => db.get_users(),
+        method: 'GET',
+        description: 'Returns all users',
+        auth: 'required',
+        tags: ['users', 'read']
+    }
+};
+```
+
+Full metadata enables admin dashboards to show API documentation, access control to be enforced at the server level, and potentially OpenAPI/Swagger spec generation.
+
+---
+
+## Option 1: Plain Object (Status Quo)
+
+```js
+class Website extends Evented_Class {
+    constructor(spec = {}) {
+        super();
+        this.api = {};
+        if (spec.api) Object.assign(this.api, spec.api);
+    }
+}
+
+// Usage
+site.api['get-users'] = () => db.get_users();
+```
+
+### Discussion
+
+**Pro**: 
+- Perfectly mirrors what `Server.serve()` already accepts
+- Zero learning curve — it's a plain JavaScript object
+- Easy to iterate: `Object.entries(site.api)`
+- Can hold functions directly OR objects with metadata — flexible
+
+**Con**:
+- No validation — you can put anything in
+- No way to distinguish "handler function" from "endpoint config object" without inspecting each value
+- No `.add()` or `.get()` convenience methods
+- No introspection API — admin UI would need to understand the mixed format
+
+---
+
+## Option 2: Dedicated API Object with `add_endpoint()`
+
+```js
+class Website extends Evented_Class {
+    constructor(spec = {}) {
+        super();
+        this._api = new Map();
+
+        if (spec.api) {
+            for (const [name, value] of Object.entries(spec.api)) {
+                if (typeof value === 'function') {
+                    this.add_endpoint(name, value);
+                } else {
+                    this.add_endpoint(name, value.handler, value);
+                }
+            }
+        }
+    }
+
+    add_endpoint(name, handler, options = {}) {
+        this._api.set(name, {
+            handler,
+            method: options.method || 'GET',
+            description: options.description || undefined,
+            auth: options.auth || undefined
+        });
+        return this;
+    }
+
+    get_endpoint(name) {
+        return this._api.get(name);
+    }
+
+    get api_endpoints() {
+        return [...this._api.entries()].map(([name, cfg]) => ({
+            name, ...cfg
+        }));
+    }
+}
+```
+
+### Discussion
+
+**Pro**:
+- Consistent, structured storage — every endpoint has the same shape
+- Auto-normalizes bare functions: `add_endpoint('x', fn)` becomes `{ handler: fn, method: 'GET' }`
+- Accepts the plain object format from spec for backward compatibility
+- `api_endpoints` getter provides a stable introspection surface for admin/tooling
+- Easy to add validation (handler must be function, method must be valid HTTP verb)
+
+**Con**:
+- More code than Option 1
+- The constructor does normalization work — functions vs. config objects need to be detected
+- `api_endpoints` returns a new array each time (same minor issue as `pages`)
+
+---
+
+## Option 3: Separate API Class
+
+Move API concerns into a dedicated class, keeping Website focused.
+
+```js
+class Website_API extends Evented_Class {
+    constructor() {
+        super();
+        this._endpoints = new Map();
+    }
+
+    publish(name, handler, options = {}) {
+        if (typeof handler !== 'function') {
+            throw new TypeError(`API handler for "${name}" must be a function`);
+        }
+        this._endpoints.set(name, {
+            handler,
+            method: options.method || 'GET',
+            path: options.path || undefined,
+            description: options.description || undefined,
+            auth: options.auth || undefined
+        });
+        this.raise('endpoint-added', { name, ...options });
+        return this;
+    }
+
+    get(name)     { return this._endpoints.get(name); }
+    has(name)     { return this._endpoints.has(name); }
+    remove(name)  { return this._endpoints.delete(name); }
+
+    get endpoints() {
+        return [...this._endpoints.entries()].map(([name, cfg]) => ({
+            name, ...cfg
+        }));
+    }
+
+    get count() {
+        return this._endpoints.size;
+    }
+
+    toJSON() {
+        return this.endpoints.map(({ name, method, path, description }) => ({
+            name, method, path, description
+        }));
+    }
+
+    [Symbol.iterator]() {
+        return this._endpoints[Symbol.iterator]();
+    }
+}
+```
+
+### Discussion
+
+**Pro**:
+- **Single Responsibility** — API concerns are encapsulated, not mixed into Website
+- **Own event system** — `'endpoint-added'` events without polluting Website's event namespace
+- **`.publish()` method** — matches the existing `API.js` stub's method name, so it's a natural evolution
+- **`toJSON()`** — stable serialization for admin/docs
+- **Iterable** — `for (const [name, endpoint] of site.api)` works
+- **Validation** — handler type-checking at registration time
+- The existing `jsgui3-website/API.js` already establishes this class's existence — it just needs to be fleshed out
+
+**Con**:
+- Another class to maintain and understand
+- More indirection: `site.api.publish(name, fn)` vs. `site.api[name] = fn`
+- Extends `Evented_Class` — do API endpoint registrations need events?
+- The current server's `server.publish()` method has the same name, which might be confusing. "Is this the website's publish or the server's publish?"
+
+---
+
+## The `publish()` Name Question
+
+Both the existing `API.js` stub and `server.js` use a method called `publish()`. This creates potential confusion:
+
+```js
+// Website API — declares an endpoint exists
+site.api.publish('get-users', handler);
+
+// Server — actually makes it available over HTTP
+server.publish('get-users', handler);
+```
+
+Should the Website API use a different name to distinguish declaration from activation?
+
+| Name | Meaning | Example |
+|------|---------|---------|
+| `publish()` | Matches existing stub, familiar | `site.api.publish('x', fn)` |
+| `add()` | Explicit about what it does | `site.api.add('x', fn)` |
+| `define()` | Emphasizes declaration over action | `site.api.define('x', fn)` |
+| `register()` | Common in routing frameworks | `site.api.register('x', fn)` |
+| `endpoint()` | Noun-verb clarity | `site.api.endpoint('x', fn)` |
+
+`define()` or `register()` make the clearest distinction: the Website *defines* endpoints, the Server *publishes* them.
+
+---
+
+## Comparison
+
+| Criterion | Plain Object | On Website Map | Separate API Class |
+|---|:---:|:---:|:---:|
+| Simplicity | ★★★ | ★★☆ | ★☆☆ |
+| Server compat | ★★★ | ★★★ | ★★☆ |
+| Validation | ☆ | ★★ | ★★★ |
+| Introspection | ★☆☆ | ★★☆ | ★★★ |
+| Metadata support | ★☆☆ | ★★★ | ★★★ |
+| Event support | ☆ | ★★ | ★★★ |
+| Continuation of API.js | ☆ | ☆ | ★★★ |
+
+---
+
+## What About the Existing API.js?
+
+The current `jsgui3-website/API.js` has:
+- A constructor that takes `spec.server`
+- An empty `publish(name, fn)` stub
+- A fatal export-statement bug
+
+If we go with Option 3 (separate API class), the natural path is to fix and evolve `API.js` into `Website_API`. The server reference would be removed (the API class shouldn't know about the server — that's a deployment concern, not a definition concern), and `publish()` might be renamed to `define()` or `register()`.
+
+If we go with Option 1 or 2, `API.js` becomes dead code and should be removed.

package/docs/books/website-design/08-server-integration.md

@@ -0,0 +1,271 @@
+# Chapter 8: Server Integration
+
+This chapter discusses how `jsgui3-server` would consume Website and Webpage objects — without requiring them.
+
+---
+
+## The Constraint
+
+`jsgui3-server` must continue to work in all its current modes:
+
+```js
+// Mode 1: Single control
+Server.serve(MyCtrl);
+
+// Mode 2: Multi-page options
+Server.serve({ pages: { '/': { content: Home } } });
+
+// Mode 3: API-only
+Server.serve({ api: { 'get-data': handler } });
+
+// Mode 4: Full options
+Server.serve({ Ctrl: MyCtrl, api: {...}, middleware: [...] });
+```
+
+Website and Webpage support is **additive** — new input shapes that the server learns to accept alongside the existing ones.
+
+---
+
+## Detection Strategy
+
+### Option A: `instanceof` checks
+
+```js
+const Website = require('jsgui3-website');
+const Webpage = require('jsgui3-webpage');
+
+if (input instanceof Website) { ... }
+if (input instanceof Webpage) { ... }
+```
+
+**Pro**: Clean, readable, unambiguous.  
+**Con**: Breaks when packages are duplicated (npm link, workspaces, multiple installs). Two copies of `jsgui3-website` will have different class references, so `instanceof` fails even when the object is shape-compatible.
+
+### Option B: Duck typing / capability checks
+
+```js
+function is_website(input) {
+    return input
+        && typeof input.add_page === 'function'
+        && typeof input.get_page === 'function'
+        && (input._pages instanceof Map || Array.isArray(input.pages));
+}
+
+function is_webpage(input) {
+    return input
+        && input.hasOwnProperty('path')
+        && input.hasOwnProperty('content');
+}
+```
+
+**Pro**: Works across duplicate installs, works with subclasses, works with compatible plain objects.  
+**Con**: Could false-positive on objects that happen to have the right properties. More code.
+
+### Option C: Both — `instanceof` first, duck type as fallback
+
+```js
+function is_website(input) {
+    try {
+        const Website = require('jsgui3-website');
+        if (input instanceof Website) return true;
+    } catch (e) { /* jsgui3-website not installed */ }
+
+    // Fallback: duck typing
+    return input && typeof input.add_page === 'function'
+        && typeof input.get_page === 'function';
+}
+```
+
+**Pro**: Best of both. `instanceof` when available (fastest, most reliable), duck typing as a safety net.  
+**Con**: Most code. The `try/catch` around `require` is somewhat unusual.
+
+### Option D: Explicit type marker
+
+```js
+// In jsgui3-website:
+class Website {
+    get [Symbol.for('jsgui.type')]() { return 'Website'; }
+}
+
+// In jsgui3-server:
+function is_website(input) {
+    return input && input[Symbol.for('jsgui.type')] === 'Website';
+}
+```
+
+**Pro**: Works across duplicate installs. No false positives. Clean.  
+**Con**: Requires coordination between packages. Symbol-based type markers aren't a common JavaScript pattern.
+
+---
+
+## Integration Points
+
+### Where `serve-factory.js` would change
+
+Today, `Server.serve()` inspects its input to determine the mode:
+
+```js
+if (typeof input === 'function') → single control
+if (input.Ctrl) → control from options
+if (input.pages) → multi-page
+if (input.api) → API mode
+```
+
+Adding Website/Webpage support means adding branches:
+
+```js
+if (is_website(input)) {
+    // Extract pages, register each route
+    // Extract API endpoints, publish each
+    // Apply site-wide metadata
+}
+
+if (is_webpage(input)) {
+    // Single-page shorthand — extract path and content
+}
+```
+
+### The Normalization Approach
+
+Rather than adding more `if` branches, an alternative design normalizes all inputs into a common internal format first:
+
+```js
+function normalize_serve_input(input) {
+    const manifest = {
+        pages: [],
+        api: [],
+        meta: {},
+        assets: {}
+    };
+
+    if (is_website(input)) {
+        manifest.pages = input.pages.map(normalize_page);
+        manifest.api = input.api_endpoints || [];
+        manifest.meta = input.meta || {};
+    } else if (is_webpage(input)) {
+        manifest.pages = [normalize_page(input)];
+    } else if (typeof input === 'function') {
+        manifest.pages = [{ path: '/', content: input }];
+    } else if (input.pages) {
+        // Existing multi-page format
+        for (const [path, cfg] of Object.entries(input.pages)) {
+            manifest.pages.push({ path, ...cfg });
+        }
+    }
+    // ... etc
+
+    return manifest;
+}
+```
+
+All publishers then consume the normalized manifest, not the raw input. This has two benefits:
+
+1. **Single place for input handling** — all format detection and conversion lives in one function
+2. **Publishers are simpler** — they don't need to handle multiple input shapes
+
+The OpenAI reviewer's server support document proposed this approach in detail (see Chapter 9).
+
+---
+
+## What Changes in the Server?
+
+### Minimal approach
+
+Add Website/Webpage detection to `serve-factory.js`. When detected, iterate pages and call the existing `prepare_webpage_route()` for each. Register API endpoints using the existing `server.publish()`.
+
+```js
+if (is_website(input)) {
+    const website = input;
+    const page_routes = [];
+
+    for (const page of website.pages) {
+        page_routes.push(
+            prepare_webpage_route(server, page.path, {
+                content: page.content,
+                title: page.title,
+                name: page.name,
+                client_js: page.client_js
+            }, defaults)
+        );
+    }
+
+    if (website.api_endpoints) {
+        for (const endpoint of website.api_endpoints) {
+            server.publish(endpoint.name, endpoint.handler);
+        }
+    }
+
+    await Promise.all(page_routes);
+}
+```
+
+**Pro**: Minimal change to the server. Reuses existing pipeline.  
+**Con**: Doesn't surface website-level metadata. No normalization layer — the special-casing stays.
+
+### Full approach
+
+Introduce the normalization layer, refactor publishers to consume manifests, add introspection APIs.
+
+**Pro**: Cleaner architecture, better admin support.  
+**Con**: Significant refactoring of working code such as the publisher pipeline.
+
+### Pragmatic recommendation
+
+Start minimal. Get Website/Webpage objects flowing through the existing pipeline. Add normalization and publisher refactoring as a follow-up when the basic integration proves out.
+
+---
+
+## Recommended Contract (Converged)
+
+From the tradeoffs in this chapter and the cross-agent review, a practical contract emerges:
+
+1. **Normalize first** — convert all `Server.serve(...)` input variants into one internal manifest
+2. **Publish second** — publishers consume only normalized manifests, never raw user input
+3. **Detect by capability** — avoid hard `instanceof` dependence at server boundaries
+4. **Keep compatibility** — legacy inputs (`Ctrl`, `pages`, `api`) must map cleanly into the manifest
+5. **Expose introspection** — surface manifest/publication summaries for admin tooling
+
+This keeps the integration additive and reduces future complexity in publisher code.
+
+---
+
+## Admin UI Opportunities
+
+The admin UI already introspects the resource pool, router, and publishers. With Website/Webpage objects, it could show:
+
+1. **Website manifest** — name, base path, page count
+2. **Page catalog** — path, title, content control name, render mode
+3. **API endpoint catalog** — name, method, description
+4. **Route table** — which routes are static vs. dynamic, which have bundles
+
+This requires the server to expose `server.website_manifest` or equivalent. The `toJSON()` methods on Website and Webpage make this straightforward.
+
+---
+
+## Integration with the Publisher Pipeline
+
+Today's pipeline:
+
+```
+Ctrl → Webpage → HTTP_Webpage_Publisher → bundled output → router
+```
+
+With Website support:
+
+```
+Website → for each page:
+    Webpage → HTTP_Webpage_Publisher → bundled output → router
+  for each API endpoint:
+    → server.publish() → HTTP_Function_Publisher → router
+```
+
+The Website itself doesn't need a publisher — it's a container that the server iterates. Each page gets its own publisher, and each API endpoint gets its own publisher. The Website provides the structure; the server provides the pipeline.
+
+This means `HTTP_Website_Publisher` might become a thin coordinator rather than a monolithic publisher. It would:
+
+1. Accept a Website
+2. Create per-page publishers
+3. Wait for all publishers to be ready
+4. Emit a combined `'ready'` event
+
+This is much simpler than the current 580-line stub with NYI comments.