@quo-systems/dock 0.1.0

package/dist/harbor/edge/storage.d.ts

@@ -0,0 +1,20 @@
+import { type Kept, type Store, type WardRecord } from '@quo-systems/quo/harbor';
+import type { Storage } from './platform.d.ts';
+export declare function sealKey(secret: string): Promise<CryptoKey>;
+export declare function seal(key: CryptoKey, seed: Uint8Array): Promise<string>;
+export declare function open(key: CryptoKey, sealed: string): Promise<Uint8Array>;
+export declare class DurableStorage implements Store {
+    #private;
+    readonly storage: Storage;
+    readonly key: CryptoKey;
+    readonly prefix: string;
+    constructor(storage: Storage, key: CryptoKey, prefix?: string);
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+}

package/dist/harbor/edge/storage.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store as Durable Object storage: one object per harbor, its storage
+// holding one row per ward under `ward:<name>`, seed, partition and record,
+// and one row per hint under `hint:<pk>`. The seed is kept sealed under a
+// key from the platform's secrets, `QUO_SEED_KEY`, so the storage holds
+// ciphertext and the secret store holds the one key, which is what the
+// harbor document's table says the edge does. Values cross as JSON, as
+// they do into a file, because the ward hands the partition out through a
+// guard that structured clone refuses.
+import { arithmetic } from '@quo-systems/quo/ward';
+import { values } from '@quo-systems/quo/harbor';
+// Bytes as the platform's crypto wants them: over a plain ArrayBuffer.
+const plain = (b) => new Uint8Array(b);
+const { hex, unhex } = arithmetic;
+// The seal on a seed: AES-GCM under the platform key, a fresh nonce each
+// time, nonce and ciphertext together as hex.
+export async function sealKey(secret) {
+    if (!/^[0-9a-f]{64}$/.test(secret))
+        throw new Error('QUO_SEED_KEY is 32 bytes as hex');
+    return crypto.subtle.importKey('raw', plain(unhex(secret)), 'AES-GCM', false, ['encrypt', 'decrypt']);
+}
+export async function seal(key, seed) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plain(seed)));
+    return hex(iv) + hex(ct);
+}
+export async function open(key, sealed) {
+    const b = plain(unhex(sealed));
+    return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: b.subarray(0, 12) }, key, b.subarray(12)));
+}
+// `prefix` keeps more than one harbor apart in one object's storage: the
+// exercise does that, a deployment never does.
+export class DurableStorage {
+    storage;
+    key;
+    prefix;
+    constructor(storage, key, prefix = '') {
+        this.storage = storage;
+        this.key = key;
+        this.prefix = prefix;
+    }
+    #k(kind, name) {
+        return `${this.prefix}${kind}:${name}`;
+    }
+    async list() {
+        const head = this.#k('ward', '');
+        return [...(await this.storage.list({ prefix: head })).keys()].map((k) => k.slice(head.length));
+    }
+    async load(name) {
+        const row = await this.storage.get(this.#k('ward', name));
+        return row && { seed: await open(this.key, row.seed), partition: values(row.partition), record: row.record };
+    }
+    async put(name, kept) {
+        if ((await this.storage.get(this.#k('ward', name))) !== undefined)
+            throw new Error(`ward ${name} already exists here`);
+        await this.storage.put(this.#k('ward', name), { seed: await seal(this.key, kept.seed), partition: values(kept.partition), record: kept.record });
+    }
+    async save(name, partition) {
+        const row = await this.storage.get(this.#k('ward', name));
+        if (row)
+            await this.storage.put(this.#k('ward', name), { ...row, partition: values(partition) });
+    }
+    async record(name, record) {
+        const row = await this.storage.get(this.#k('ward', name));
+        if (row)
+            await this.storage.put(this.#k('ward', name), { ...row, record });
+    }
+    async take(name) {
+        const kept = await this.load(name);
+        if (kept)
+            await this.storage.delete(this.#k('ward', name));
+        return kept;
+    }
+    async hints() {
+        const head = this.#k('hint', '');
+        return Object.fromEntries([...(await this.storage.list({ prefix: head }))].map(([k, v]) => [k.slice(head.length), v]));
+    }
+    async hint(pk, url) {
+        await this.storage.put(this.#k('hint', pk), url);
+    }
+}

package/dist/harbor/edge/worker.d.ts

@@ -0,0 +1,14 @@
+import { EdgeHarbor } from './edge.ts';
+import type { State, Env } from './platform.d.ts';
+export declare class Quo {
+    #private;
+    readonly state: State;
+    readonly env: Env;
+    constructor(state: State, env: Env);
+    harbor(): Promise<EdgeHarbor>;
+    fetch(request: Request): Promise<Response>;
+}
+declare const _default: {
+    fetch(request: Request, env: Env): Promise<Response>;
+};
+export default _default;

package/dist/harbor/edge/worker.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// The worker: the edge harbor deployed. One Durable Object class, `Quo`,
+// one instance per harbor name, and the worker routes by the first path
+// segment: `/h/<name>/...` goes to that harbor. A world's quo. route on the
+// edge is `<origin>/h/<name>/quo`, and its health `<origin>/h/<name>/health`.
+// `wrangler.toml` beside this file names the class and the secrets.
+//
+// One thing lives here for the terrain test alone: with `QUO_EXERCISE` set,
+// which no deployment sets, `/exercise` runs the library's conformance
+// suite inside the platform against two harbors in this one object, over
+// two prefixed views of its storage, reaching each other by request
+// through the worker under `/x/<sub>/quo`. One object cannot touch
+// another's storage, the platform says so, and so the two harbors share an
+// object the way two tabs share a page.
+import { EdgeHarbor } from './edge.js';
+import { exercise } from './exercise.js';
+export class Quo {
+    state;
+    env;
+    #harbor;
+    constructor(state, env) {
+        this.state = state;
+        this.env = env;
+    }
+    harbor() {
+        return (this.#harbor ??= EdgeHarbor.open(this.state, this.env));
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        const m = /^\/h\/([\w.-]+)(\/.*)?$/.exec(url.pathname);
+        if (!m)
+            return new Response(JSON.stringify({ error: 'no such route' }), { status: 404, headers: { 'content-type': 'application/json' } });
+        const path = m[2] ?? '/';
+        if (this.env.QUO_EXERCISE && (path === '/exercise' || path.startsWith('/x/')))
+            return exercise(request, `${url.origin}/h/${m[1]}`, path, this.state, this.env);
+        return (await this.harbor()).fetch(request, path);
+    }
+}
+export default {
+    async fetch(request, env) {
+        const url = new URL(request.url);
+        const m = /^\/h\/([\w.-]+)(\/.*)?$/.exec(url.pathname);
+        if (!m)
+            return new Response(JSON.stringify({ error: 'a harbor is /h/<name>/...' }), { status: 404, headers: { 'content-type': 'application/json' } });
+        return env.HARBOR.get(env.HARBOR.idFromName(m[1])).fetch(request);
+    },
+};

package/dist/harbor/files.d.ts

@@ -0,0 +1,14 @@
+import type { Kept, Store, WardRecord } from '@quo-systems/quo/harbor';
+export declare class Files implements Store {
+    #private;
+    readonly dir: string;
+    constructor(dir: string);
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+}

package/dist/harbor/files.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store as a folder on disk, one folder per ward:
+//
+//   <dir>/wards/<name>/seed             32 bytes, hex, mode 0600
+//   <dir>/wards/<name>/partition.json
+//   <dir>/wards/<name>/ward.json        the ward record
+//   <dir>/reach.json                    the directory's hints
+//
+// Every write of the partition goes through a temp file and a rename, and
+// writes are queued per ward so two calls never race on one file.
+import { mkdir, readFile, writeFile, rename, readdir, rm, chmod } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { arithmetic } from '@quo-systems/quo/ward';
+const { hex, unhex } = arithmetic;
+export class Files {
+    dir;
+    #queues = new Map();
+    constructor(dir) {
+        this.dir = dir;
+    }
+    #ward(name) {
+        return join(this.dir, 'wards', name);
+    }
+    async list() {
+        const wards = join(this.dir, 'wards');
+        return existsSync(wards) ? (await readdir(wards)).filter((n) => existsSync(join(wards, n, 'seed'))) : [];
+    }
+    async load(name) {
+        const wd = this.#ward(name);
+        if (!existsSync(join(wd, 'seed')))
+            return undefined;
+        return {
+            seed: unhex((await readFile(join(wd, 'seed'), 'utf8')).trim()),
+            partition: JSON.parse(await readFile(join(wd, 'partition.json'), 'utf8')),
+            record: JSON.parse(await readFile(join(wd, 'ward.json'), 'utf8')),
+        };
+    }
+    async put(name, kept) {
+        const wd = this.#ward(name);
+        if (existsSync(join(wd, 'seed')))
+            throw new Error(`ward ${name} already exists in ${this.dir}`);
+        await mkdir(wd, { recursive: true, mode: 0o700 });
+        await writeFile(join(wd, 'seed'), hex(kept.seed), { mode: 0o600 });
+        await chmod(join(wd, 'seed'), 0o600);
+        await writeFile(join(wd, 'partition.json'), JSON.stringify(kept.partition) + '\n', { mode: 0o600 });
+        await writeFile(join(wd, 'ward.json'), JSON.stringify(kept.record, null, 2) + '\n', { mode: 0o600 });
+    }
+    save(name, partition) {
+        const wd = this.#ward(name);
+        if (!existsSync(join(wd, 'seed')))
+            return Promise.resolve(); // a name not kept is nothing
+        const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+            const tmp = join(wd, 'partition.json.tmp');
+            await writeFile(tmp, JSON.stringify(partition) + '\n', { mode: 0o600 });
+            await rename(tmp, join(wd, 'partition.json'));
+        });
+        this.#queues.set(name, next.catch(() => { }));
+        return next;
+    }
+    async record(name, record) {
+        if (!existsSync(join(this.#ward(name), 'seed')))
+            return;
+        await writeFile(join(this.#ward(name), 'ward.json'), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+    }
+    async take(name) {
+        const kept = await this.load(name);
+        if (!kept)
+            return undefined;
+        await this.#queues.get(name);
+        await rm(this.#ward(name), { recursive: true, force: true });
+        return kept;
+    }
+    async hints() {
+        const p = join(this.dir, 'reach.json');
+        return existsSync(p) ? JSON.parse(await readFile(p, 'utf8')) : {};
+    }
+    async hint(pk, url) {
+        const all = await this.hints();
+        all[pk] = url;
+        await writeFile(join(this.dir, 'reach.json'), JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+    }
+}

package/dist/harbor/idb.d.ts

@@ -0,0 +1,15 @@
+import { type Kept, type Store, type WardRecord } from '@quo-systems/quo/harbor';
+export declare class Idb implements Store {
+    #private;
+    readonly name: string;
+    constructor(name?: string);
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+    close(): void;
+}

package/dist/harbor/idb.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store as IndexedDB, per origin: one database per harbor, one record
+// per ward holding seed, partition and record, and one record for the
+// directory's hints. The honest weakness the harbor document names: a tab
+// has no secret store for bytes, so the seed sits beside the partition,
+// guarded by the origin and nothing more. That is the price of a tab.
+import { values } from '@quo-systems/quo/harbor';
+const WARDS = 'wards', HINTS = 'hints';
+function open(name) {
+    return new Promise((ok, no) => {
+        const req = indexedDB.open(name, 1);
+        req.onupgradeneeded = () => {
+            req.result.createObjectStore(WARDS);
+            req.result.createObjectStore(HINTS);
+        };
+        req.onsuccess = () => ok(req.result);
+        req.onerror = () => no(req.error ?? new Error('indexedDB would not open'));
+    });
+}
+function done(req) {
+    return new Promise((ok, no) => {
+        req.onsuccess = () => ok(req.result);
+        req.onerror = () => no(req.error ?? new Error('indexedDB request failed'));
+    });
+}
+export class Idb {
+    name;
+    #db;
+    constructor(name = 'quo') {
+        this.name = name;
+    }
+    #open() {
+        return (this.#db ??= open(this.name));
+    }
+    async #tx(store, mode) {
+        return (await this.#open()).transaction(store, mode).objectStore(store);
+    }
+    async list() {
+        return (await done((await this.#tx(WARDS, 'readonly')).getAllKeys())).map(String);
+    }
+    async load(name) {
+        const row = (await done((await this.#tx(WARDS, 'readonly')).get(name)));
+        return row && { seed: new Uint8Array(row.seed), partition: values(row.partition), record: row.record };
+    }
+    async put(name, kept) {
+        const st = await this.#tx(WARDS, 'readwrite');
+        if ((await done(st.getKey(name))) !== undefined)
+            throw new Error(`ward ${name} already exists in ${this.name}`);
+        await done(st.put({ seed: kept.seed, partition: values(kept.partition), record: kept.record }, name));
+    }
+    async save(name, partition) {
+        const st = await this.#tx(WARDS, 'readwrite');
+        const row = (await done(st.get(name)));
+        if (!row)
+            return;
+        await done(st.put({ ...row, partition: values(partition) }, name));
+    }
+    async record(name, record) {
+        const st = await this.#tx(WARDS, 'readwrite');
+        const row = (await done(st.get(name)));
+        if (!row)
+            return;
+        await done(st.put({ ...row, record }, name));
+    }
+    async take(name) {
+        const kept = await this.load(name);
+        if (!kept)
+            return undefined;
+        await done((await this.#tx(WARDS, 'readwrite')).delete(name));
+        return kept;
+    }
+    async hints() {
+        const st = await this.#tx(HINTS, 'readonly');
+        const keys = (await done(st.getAllKeys())).map(String);
+        const vals = (await done(st.getAll()));
+        return Object.fromEntries(keys.map((k, i) => [k, vals[i]]));
+    }
+    async hint(pk, url) {
+        await done((await this.#tx(HINTS, 'readwrite')).put(url, pk));
+    }
+    close() {
+        void this.#db?.then((db) => db.close());
+        this.#db = undefined;
+    }
+}

package/dist/human/dom.d.ts

@@ -0,0 +1,2 @@
+import type { Surface } from './screen.ts';
+export declare function domSurface(root: HTMLElement): Surface;

package/dist/human/dom.js

@@ -0,0 +1,15 @@
+export function domSurface(root) {
+    const s = { show: (html) => (root.innerHTML = html), onSubmit: undefined };
+    root.addEventListener('submit', (ev) => {
+        const f = ev.target;
+        const ask = f?.dataset.ask;
+        if (!f || ask === undefined)
+            return;
+        ev.preventDefault();
+        const raw = {};
+        for (const [k, v] of new FormData(f))
+            raw[k] = typeof v === 'string' ? v : '';
+        s.onSubmit?.(ask, raw);
+    });
+    return s;
+}

package/dist/human/html.d.ts

@@ -0,0 +1,32 @@
+import type { Ask, Blueprint, Json, JsonObject } from '@quo-systems/quo';
+import { type Word } from '../beings/side.ts';
+export type Property = {
+    type?: string;
+    description?: string;
+    enum?: Json[];
+    format?: string;
+    default?: Json;
+};
+export type Schema = {
+    properties?: Record<string, Property>;
+    required?: string[];
+};
+export declare const escape: (s: string) => string;
+export declare function field(name: string, p: Property, must: boolean): string;
+export declare function form(ask: Ask): string;
+export type Raw = Record<string, string>;
+export declare function values(ask: Ask, raw: Raw): {
+    args: JsonObject;
+} | {
+    error: string;
+};
+export declare function view(value: Json, schema?: JsonObject): string;
+export declare function face(w: Word, schema?: JsonObject): string;
+export type Model = {
+    blueprint: Blueprint | null;
+    notice: string;
+    answers: Record<string, Word>;
+    pushes: JsonObject[];
+};
+export declare function title(bp: Blueprint | null): string;
+export declare function page(m: Model): string;

package/dist/human/html.js

@@ -0,0 +1,136 @@
+import { SILENCE_TEXT, UNREACHED_TEXT, wordText } from '../beings/side.js';
+export const escape = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+const props = (schema) => Object.entries((schema?.properties ?? {}));
+const required = (schema) => new Set((schema?.required ?? []));
+// ---- a schema as a form
+// A property is one field by its type. A string is a text input, and a
+// format the browser knows, `password`, `date`, `email`, is the input's
+// type. A number is a number input. A boolean is a checkbox. An enum is a
+// select. An object or an array is a box for JSON, because a form has no
+// better face for a value the schema left open. A description is the label.
+export function field(name, p, must) {
+    const id = escape(name);
+    const label = `<label for="${id}">${id}${must ? ' <b>*</b>' : ''}${p.description ? ` <small>${escape(p.description)}</small>` : ''}</label>`;
+    const req = must ? ' required' : '';
+    if (Array.isArray(p.enum)) {
+        const options = p.enum.map((v) => `<option value="${escape(String(v))}">${escape(String(v))}</option>`).join('');
+        return `<p>${label}<select id="${id}" name="${id}"${req}>${must ? '' : '<option value=""></option>'}${options}</select></p>`;
+    }
+    if (p.type === 'boolean')
+        return `<p><input type="checkbox" id="${id}" name="${id}" value="true">${label}</p>`;
+    if (p.type === 'number' || p.type === 'integer')
+        return `<p>${label}<input type="number" id="${id}" name="${id}"${p.type === 'integer' ? ' step="1"' : ' step="any"'}${req}></p>`;
+    if (p.type === 'string' || p.type === undefined) {
+        const kind = p.format === 'password' || p.format === 'date' || p.format === 'email' || p.format === 'time' ? p.format : 'text';
+        return `<p>${label}<input type="${kind}" id="${id}" name="${id}"${req}></p>`;
+    }
+    return `<p>${label}<textarea id="${id}" name="${id}" placeholder="JSON"${req}></textarea></p>`;
+}
+// The ask as a form: its name is the button, its description the legend's
+// small print, and `data-ask` is how the surface says which ask was sent.
+export function form(ask) {
+    const must = required(ask.input);
+    const fields = props(ask.input)
+        .map(([name, p]) => field(name, p, must.has(name)))
+        .join('');
+    return `<form data-ask="${escape(ask.name)}"><fieldset><legend>${escape(ask.name)}${ask.description ? ` <small>${escape(ask.description)}</small>` : ''}</legend>${fields}<p><button>${escape(ask.name)}</button></p></fieldset></form>`;
+}
+// The strings typed by the schema. An empty field that is not required is
+// left out, so the being sees what the human said and nothing else; an
+// empty required field goes as the empty string, and the being answers.
+// A JSON box that does not parse is an error the side shows before asking.
+export function values(ask, raw) {
+    const args = {};
+    const must = required(ask.input);
+    for (const [name, p] of props(ask.input)) {
+        const s = raw[name];
+        if (p.type === 'boolean') {
+            if (s === 'true')
+                args[name] = true;
+            else if (must.has(name))
+                args[name] = false;
+            continue;
+        }
+        if (s === undefined || (s === '' && !must.has(name)))
+            continue;
+        if (p.type === 'number' || p.type === 'integer') {
+            const n = Number(s);
+            if (s === '' || Number.isNaN(n))
+                return { error: `${name} is a number` };
+            args[name] = n;
+        }
+        else if (p.type === 'string' || p.type === undefined || Array.isArray(p.enum)) {
+            args[name] = s;
+        }
+        else {
+            try {
+                args[name] = JSON.parse(s);
+            }
+            catch {
+                return { error: `${name} is not JSON` };
+            }
+        }
+    }
+    return { args };
+}
+// ---- an answer as a view
+// A value has one face by its shape. A primitive is text. An object is a
+// table of its keys, in the output schema's order when she declared one and
+// her own order otherwise, each value viewed in turn. A list of objects is
+// one table with a column per key seen; any other list is a list. Null is
+// the word nothing, so that an answer of null is never a blank.
+export function view(value, schema) {
+    if (value === null)
+        return '<i>nothing</i>';
+    if (typeof value !== 'object')
+        return escape(String(value));
+    if (Array.isArray(value)) {
+        if (value.length && value.every((v) => v !== null && typeof v === 'object' && !Array.isArray(v))) {
+            const rows = value;
+            const keys = [...new Set(rows.flatMap((r) => Object.keys(r)))];
+            const head = keys.map((k) => `<th>${escape(k)}</th>`).join('');
+            const body = rows.map((r) => `<tr>${keys.map((k) => `<td>${k in r ? view(r[k]) : ''}</td>`).join('')}</tr>`).join('');
+            return `<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`;
+        }
+        return value.length ? `<ul>${value.map((v) => `<li>${view(v)}</li>`).join('')}</ul>` : '<i>none</i>';
+    }
+    const declared = props(schema).map(([k]) => k);
+    const keys = [...declared.filter((k) => k in value), ...Object.keys(value).filter((k) => !declared.includes(k))];
+    if (!keys.length)
+        return '<i>empty</i>';
+    return `<table>${keys.map((k) => `<tr><th>${escape(k)}</th><td>${view(value[k], props(schema).find(([n]) => n === k)?.[1])}</td></tr>`).join('')}</table>`;
+}
+// The three words for "no object", and the object, each with a face. An
+// error object is the answer she gave, marked; silence and unreached are
+// what the side says about them, since they carry nothing themselves.
+export function face(w, schema) {
+    if (w.word === 'object')
+        return `<div class="answer">${view(w.value, schema)}</div>`;
+    if (w.word === 'error')
+        return `<div class="answer error">${view(w.value)}</div>`;
+    if (w.word === 'silence')
+        return `<div class="answer silence">${escape(SILENCE_TEXT)}</div>`;
+    if (w.word === 'quo')
+        return `<div class="answer word">${escape(wordText(w.name))}</div>`;
+    return `<div class="answer unreached">${escape(UNREACHED_TEXT)}</div>`;
+}
+// The title is the one hint the notes may carry: a string named `name`.
+// The rest of the notes is shown as a view and read as nothing else.
+export function title(bp) {
+    const n = bp?.notes;
+    return n !== null && typeof n === 'object' && !Array.isArray(n) && typeof n.name === 'string' && n.name ? n.name : 'quo';
+}
+export function page(m) {
+    const bp = m.blueprint;
+    const asks = bp
+        ? bp.asks
+            .map((a) => {
+            const w = m.answers[a.name];
+            return `<section>${form(a)}${w ? face(w, a.output) : ''}</section>`;
+        })
+            .join('')
+        : '';
+    const notes = bp && bp.notes !== null && !(typeof bp.notes === 'object' && !Array.isArray(bp.notes) && !Object.keys(bp.notes).length) ? `<aside class="notes">${view(bp.notes)}</aside>` : '';
+    const pushes = m.pushes.length ? `<section class="pushes"><h2>pushes</h2><ol>${m.pushes.map((p) => `<li>${view(p)}</li>`).join('')}</ol></section>` : '';
+    return `<header><h1>${escape(title(bp))}</h1><p class="notice">${escape(m.notice)}</p></header>${notes}<main>${asks}</main>${pushes}`;
+}

package/dist/human/screen.d.ts

@@ -0,0 +1,11 @@
+import type { Avatar } from '../beings/avatar.ts';
+import { type Serving } from '../beings/side.ts';
+import { type Model, type Raw } from './html.ts';
+export type Surface = {
+    show(html: string): void;
+    onSubmit: ((ask: string, raw: Raw) => void) | undefined;
+};
+export declare function screenSide(avatar: Avatar, surface: Surface, after?: () => Promise<void>, notice?: string): Promise<Serving & {
+    model: Model;
+    refresh(): Promise<void>;
+}>;

package/dist/human/screen.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// The human side: one avatar, one surface. The surface is the least a
+// screen can be: it shows a page and hands back a submitted form, and that
+// is all this side asks of a terrain. A DOM is one surface; a test is
+// another. The side keeps the model, speaks it as a page after every change
+// through `html.ts`, calls the avatar when a form comes back, and re-asks
+// her describe after each call, so a digest that moved is a page that
+// moved. A push is appended and shown the moment it lands.
+import { digest } from '@quo-systems/quo';
+import { word } from '../beings/side.js';
+import { page, values } from './html.js';
+// `after` runs when a call is done, as it does for the model side: a harbor
+// that must write what the ward changed hooks it.
+export async function screenSide(avatar, surface, after = async () => { }, notice = '') {
+    const model = { blueprint: null, notice, answers: {}, pushes: [] };
+    let seen = null;
+    const show = () => surface.show(page(model));
+    // Her describe, again: the page follows the digest.
+    const refresh = async () => {
+        const bp = await avatar.tools();
+        if ('error' in bp && !('asks' in bp)) {
+            // the last page she gave stays, with the answers under it, and the
+            // notice says where the human stands now
+            model.notice = `not in: ${bp.error}`;
+        }
+        else {
+            const d = await digest(bp);
+            if (d !== seen) {
+                seen = d;
+                model.blueprint = bp;
+                for (const k of Object.keys(model.answers))
+                    if (!bp.asks.some((a) => a.name === k))
+                        delete model.answers[k];
+            }
+        }
+        show();
+    };
+    surface.onSubmit = (name, raw) => void submit(name, raw);
+    const submit = async (name, raw) => {
+        const ask = model.blueprint?.asks.find((a) => a.name === name);
+        if (!ask)
+            return;
+        const v = values(ask, raw);
+        if ('error' in v) {
+            model.answers[name] = { word: 'error', value: { error: v.error } };
+            return show();
+        }
+        model.answers[name] = word(await avatar.call(name, v.args));
+        await after();
+        await refresh();
+    };
+    const ear = (object) => {
+        model.pushes.push(object);
+        show();
+    };
+    avatar.ears.add(ear);
+    await refresh();
+    return {
+        model,
+        refresh,
+        close: async () => {
+            avatar.ears.delete(ear);
+            surface.onSubmit = undefined;
+        },
+    };
+}

package/dist/human/tab.d.ts

@@ -0,0 +1,7 @@
+import { USER } from '../beings/avatar.ts';
+export type Config = {
+    quo: string;
+    web: string;
+};
+export declare function start(cfg: Config, root?: HTMLElement): Promise<void>;
+export { USER };