@quo-systems/dock 0.2.0 → 0.2.2

package/dist/human/guest.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// A guest at a world's door: the world's public being, whatever class she
+// is, as a subject the screen can render. Her describe for a stranger is the
+// guest page; a form on it is a knock on the public invitation; and an
+// answer that is an invitation is the way in, which the tab takes by
+// joining. Nothing here knows the desk: the desk's `device` is one ask
+// that answers an invitation, and any being may write another.
+import { isSilence, isWord, wordOf } from '@quo-systems/quo';
+export function guest(avatar, ward) {
+    const at = { ward };
+    return {
+        tools: async () => {
+            const bp = await avatar.knock(at);
+            if (isSilence(bp))
+                return { error: 'silence' };
+            if (isWord(bp))
+                return { error: wordOf(bp) };
+            if (bp === null || typeof bp !== 'object' || Array.isArray(bp) || !Array.isArray(bp.asks))
+                return { error: 'nobody is home' };
+            return bp;
+        },
+        call: (name, args = {}, wanted) => avatar.knock(at, name, args, wanted),
+        ears: new Set(),
+    };
+}

package/dist/human/html.d.ts

@@ -1,5 +1,6 @@
 import type { Ask, Blueprint, Json, JsonObject } from '@quo-systems/quo';
 import { type Word } from '../beings/side.ts';
+import { hintFor, type Look, type Hint } from '../beings/look.ts';
 export type Property = {
     type?: string;
     description?: string;
@@ -13,7 +14,7 @@ export type Schema = {
 };
 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 declare function form(ask: Ask, h?: Hint): string;
 export type Raw = Record<string, string>;
 export declare function values(ask: Ask, raw: Raw): {
     args: JsonObject;
@@ -24,9 +25,16 @@ export declare function view(value: Json, schema?: JsonObject): string;
 export declare function face(w: Word, schema?: JsonObject): string;
 export type Model = {
     blueprint: Blueprint | null;
+    look: Look;
     notice: string;
     answers: Record<string, Word>;
     pushes: JsonObject[];
 };
-export declare function title(bp: Blueprint | null): string;
+export declare function title(bp: Blueprint | null, l?: Look): string;
+export declare function look(l: Look | undefined): {
+    style: string;
+    head: string;
+};
+export declare function ordered(asks: Ask[], l: Look | undefined): Ask[];
+export { hintFor };
 export declare function page(m: Model): string;

package/dist/human/html.js

@@ -1,4 +1,5 @@
 import { SILENCE_TEXT, UNREACHED_TEXT, wordText } from '../beings/side.js';
+import { hint, hintFor, sanitise, groups as grouped } from '../beings/look.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 ?? []));
@@ -28,12 +29,14 @@ export function field(name, p, must) {
 }
 // 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) {
+export function form(ask, h = {}) {
     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>`;
+    const label = `${h.icon ? `${escape(h.icon)} ` : ''}${escape(h.title ?? ask.name)}`;
+    const care = h.destructive ? ' data-confirm="true"' : '';
+    return `<form data-ask="${escape(ask.name)}"${care}><fieldset><legend>${label}${ask.description ? ` <small>${escape(ask.description)}</small>` : ''}</legend>${fields}<p><button>${label}</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
@@ -116,21 +119,69 @@ export function face(w, schema) {
 }
 // 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) {
+export function title(bp, l = {}) {
+    if (l.name)
+        return l.name;
     const n = bp?.notes;
     return n !== null && typeof n === 'object' && !Array.isArray(n) && typeof n.name === 'string' && n.name ? n.name : 'quo';
 }
+// ---- a look
+// A look as the page paints it: the tokens become CSS variables on one
+// section, and the name and the logo its heading. The shape of every token
+// is the dock's, `beings/look.ts`; this only writes what survived it.
+export function look(l) {
+    if (!l)
+        return { style: '', head: '' };
+    const vars = [];
+    if (l.accent)
+        vars.push(`--accent:${l.accent}`);
+    if (l.background)
+        vars.push(`--bg:${l.background}`);
+    if (l.foreground)
+        vars.push(`--fg:${l.foreground}`);
+    if (l.font)
+        vars.push(`--font:${l.font}`);
+    if (l.radius !== undefined)
+        vars.push(`--radius:${l.radius}px`);
+    const logo = l.logo ? `<img class="logo" alt="" src="${l.logo}">` : '';
+    const name = l.name ? escape(l.name) : '';
+    return { style: vars.length ? ` style="${vars.join(';')}"` : '', head: logo || name ? `<h2>${logo}${name}</h2>` : '' };
+}
+// Her asks in the order her look asks for, the rest after in her own order.
+export function ordered(asks, l) {
+    const want = l?.order ?? [];
+    return [...want.map((n) => asks.find((a) => a.name === n)).filter((a) => a !== undefined), ...asks.filter((a) => !want.includes(a.name))];
+}
+export { hintFor };
 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>`;
+    const one = (l, prefix = '') => (a) => {
+        const w = m.answers[a.name];
+        const h = hint(l, a.name.startsWith(prefix) ? a.name.slice(prefix.length) : a.name);
+        return `<section>${form(a, h)}${w ? face(w, a.output) : ''}</section>`;
+    };
+    const groups = grouped(bp);
+    const taken = new Set(Object.values(groups).flatMap((g) => g.asks ?? []));
+    const own = bp ? ordered(bp.asks.filter((a) => !taken.has(a.name) && a.name !== 'look'), m.look).map(one(m.look)).join('') : '';
+    const far = bp
+        ? Object.entries(groups)
+            .map(([id, g]) => {
+            const asks = bp.asks.filter((a) => g.asks?.includes(a.name));
+            if (!asks.length)
+                return '';
+            const kept = sanitise(g.look);
+            const l = look(kept);
+            const prefix = `${id}-`;
+            const want = (kept.order ?? []).map((n) => prefix + n);
+            const inOrder = ordered(asks, { order: want });
+            return `<section class="standing" data-standing="${escape(id)}"${l.style}>${l.head || `<h2>${escape(id)}</h2>`}${inOrder.map(one(kept, prefix)).join('')}</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 asks = own + far;
+    const shown = bp && bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? Object.fromEntries(Object.entries(bp.notes).filter(([k]) => k !== 'standings' && k !== 'name')) : bp?.notes;
+    const notes = bp && shown !== null && shown !== undefined && !(typeof shown === 'object' && !Array.isArray(shown) && !Object.keys(shown).length) ? `<aside class="notes">${view(shown)}</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}`;
+    const mine = look(m.look);
+    return `<header${mine.style}>${m.look.logo ? `<img class="logo" alt="" src="${m.look.logo}">` : ''}<h1>${escape(title(bp, m.look))}</h1><p class="notice">${escape(m.notice)}</p></header>${notes}<main${mine.style}>${asks}</main>${pushes}`;
 }

package/dist/human/screen.d.ts

@@ -1,11 +1,16 @@
-import type { Avatar } from '../beings/avatar.ts';
-import { type Serving } from '../beings/side.ts';
+import { type Serving, type Subject } from '../beings/side.ts';
+import type { Invitation } from '@quo-systems/quo';
 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 & {
+export type Options = {
+    after?: () => Promise<void>;
+    notice?: string;
+    admit?: (invitation: Invitation) => Promise<void>;
+};
+export declare function screenSide(avatar: Subject, surface: Surface, options?: Options): Promise<Serving & {
     model: Model;
     refresh(): Promise<void>;
 }>;

package/dist/human/screen.js

@@ -8,11 +8,14 @@
 // 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: [] };
+import { isInvitation } from '../beings/link.js';
+import { page, values, hintFor } from './html.js';
+import { sanitise } from '../beings/look.js';
+import { isSilence, isWord } from '@quo-systems/quo';
+export async function screenSide(avatar, surface, options = {}) {
+    const after = options.after ?? (async () => { });
+    const notice = options.notice ?? '';
+    const model = { blueprint: null, look: {}, notice, answers: {}, pushes: [] };
     let seen = null;
     const show = () => surface.show(page(model));
     // Her describe, again: the page follows the digest.
@@ -31,8 +34,22 @@ export async function screenSide(avatar, surface, after = async () => { }, notic
                 for (const k of Object.keys(model.answers))
                     if (!bp.asks.some((a) => a.name === k))
                         delete model.answers[k];
+                // her look, once per digest: how she wants her page painted, and what each ask is
+                if (bp.asks.some((a) => a.name === 'look')) {
+                    const l = await avatar.call('look');
+                    model.look = isSilence(l) || isWord(l) ? {} : sanitise(l);
+                }
+                else
+                    model.look = {};
+                // a read-only ask that needs nothing typed is run on her behalf, so the page opens with what it shows
+                for (const a of bp.asks) {
+                    const needs = (a.input.required ?? []).length > 0;
+                    if (hintFor(bp, model.look, a.name).readOnly && !needs && !(a.name in model.answers))
+                        model.answers[a.name] = word(await avatar.call(a.name, {}));
+                }
             }
         }
+        await after();
         show();
     };
     surface.onSubmit = (name, raw) => void submit(name, raw);
@@ -45,8 +62,11 @@ export async function screenSide(avatar, surface, after = async () => { }, notic
             model.answers[name] = { word: 'error', value: { error: v.error } };
             return show();
         }
-        model.answers[name] = word(await avatar.call(name, v.args));
+        const out = await avatar.call(name, v.args);
         await after();
+        if (options.admit && isInvitation(out))
+            return options.admit(out);
+        model.answers[name] = word(out);
         await refresh();
     };
     const ear = (object) => {

package/dist/human/tab.d.ts

@@ -2,6 +2,11 @@ import { USER } from '../beings/avatar.ts';
 export type Config = {
     quo: string;
     web: string;
+    wards: Record<string, {
+        pk: string;
+        public: boolean;
+    }>;
+    ward?: string;
 };
 export declare function start(cfg: Config, root?: HTMLElement): Promise<void>;
 export { USER };

package/dist/human/tab.js

@@ -1,7 +1,32 @@
 import { BrowserHarbor } from '../harbor/browser.js';
-import { Avatar, USER } from '../beings/avatar.js';
+import { USER } from '../beings/avatar.js';
+import { parse, strip } from '../beings/link.js';
 import { screenSide } from './screen.js';
 import { domSurface } from './dom.js';
+import { guest } from './guest.js';
+import { door } from './door.js';
+import { world, relations, fresh } from './worlds.js';
+const kept = (key, fallback) => {
+    try {
+        return JSON.parse(localStorage.getItem(key) ?? 'null') ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+};
+const keep = (key, value) => {
+    try {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        /* forgets */
+    }
+};
+const WORLDS = 'quo-worlds';
+const worlds = () => kept(WORLDS, {});
+const remember = (pk, url, name) => keep(WORLDS, { ...worlds(), [pk]: { url, name } });
+const AT = (pk) => `quo-at:${pk}`;
+const NAMES = (pk) => `quo-names:${pk}`;
 const el = (tag, text = '', attrs = {}) => {
     const e = document.createElement(tag);
     if (text)
@@ -11,58 +36,151 @@ const el = (tag, text = '', attrs = {}) => {
     return e;
 };
 export async function start(cfg, root = document.body) {
+    // The link, first and once: the invitation leaves the address bar before
+    // any other code sees it.
+    const linked = parse(location.hash);
+    if (linked)
+        history.replaceState(null, '', location.pathname + location.search + strip(location.hash));
+    const nav = el('nav', '', { class: 'worlds' });
+    const who = el('nav', '', { class: 'relations' });
     const status = el('p', 'booting');
     const screen = el('div');
-    root.append(status, screen);
+    root.append(nav, who, status, screen);
     const say = (s) => (status.textContent = s);
-    // The harbor in the tab: one database, one ward, one avatar, for good.
+    // The harbor in the tab: one database per origin, one ward per world.
     const harbor = new BrowserHarbor('quo');
     await harbor.boot();
-    const main = harbor.wards.get('main') ?? (await harbor.create('main', 'me'));
-    if (!main.being('me'))
-        await main.ask('boot', { key: 'me', class: 'Avatar' });
-    const me = main.being('me');
     harbor.dial(cfg.quo);
-    // The screen: every call rotates her keys and a same-ward ask never
-    // crosses the harbor, so the side saves after each one.
-    const show = async (notice) => {
-        status.remove();
-        await screenSide(me, domSurface(screen), () => main.save(), notice);
+    // The world this page is about: the link's, since an invitation names
+    // its ward, or the page's own. A link for a world not on this harbor is
+    // a link to the wrong page, and says so.
+    const nameOf = (pk) => Object.keys(cfg.wards).find((n) => cfg.wards[n].pk === pk);
+    const pk = linked?.ward ?? (cfg.ward ? cfg.wards[cfg.ward]?.pk : undefined);
+    const wardName = pk ? nameOf(pk) : undefined;
+    const pageOf = (name) => `${new URL(cfg.web).pathname.replace(/\/$/, '')}/${encodeURIComponent(name)}`;
+    const switcher = () => {
+        nav.replaceChildren();
+        const known = worlds();
+        for (const [k, w] of Object.entries(known)) {
+            const a = el('a', w.name || k.slice(0, 8), { href: w.url });
+            if (k === pk)
+                a.setAttribute('aria-current', 'page');
+            nav.append(a);
+        }
+        if (pk && !known[pk] && wardName)
+            nav.append(el('span', `${wardName} at ${new URL(cfg.web).host}`));
     };
-    // Already in: reconnect, nothing minted.
-    const had = await me.tools();
-    if ('asks' in had)
-        return show('in, as before');
-    // The exchange, once: the owner password for a nonce, the nonce for an
-    // invitation the user being mints, the invitation for a standing.
-    const form = el('form');
-    const identity = el('input', '', { name: 'identity', value: 'tab', placeholder: 'identity' });
-    const password = el('input', '', { name: 'password', type: 'password', placeholder: 'owner password' });
-    const go = el('button', 'enter');
-    form.append(identity, password, go);
-    root.insertBefore(form, screen);
-    say(`not in (${had.error}): the owner password opens the world`);
-    form.onsubmit = async (ev) => {
-        ev.preventDefault();
-        say('asking the world');
-        let res;
-        try {
-            res = await fetch(`${cfg.web}/tab/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: password.value, identity: identity.value }) });
+    switcher();
+    if (!pk || !wardName) {
+        say(linked ? 'this link is for a world that does not live here' : 'choose a world');
+        return;
+    }
+    if (linked && location.pathname !== pageOf(wardName))
+        history.replaceState(null, '', pageOf(wardName) + location.search + location.hash);
+    const ward = await world(harbor, pk);
+    const at = { name: wardName, pk, public: cfg.wards[wardName].public };
+    // The relations in this world, and which one is on screen.
+    let side = null;
+    let current = null;
+    const names = () => kept(NAMES(pk), {});
+    const people = () => {
+        who.replaceChildren();
+        const rels = relations(ward);
+        const called = names();
+        for (const r of rels) {
+            const b = el('button', called[r.key] ?? r.key, { type: 'button' });
+            if (r.key === current?.key)
+                b.setAttribute('aria-current', 'true');
+            b.onclick = () => void inside(r, `in, as ${called[r.key] ?? r.key}`, called[r.key] ?? r.key);
+            who.append(b);
         }
-        catch (e) {
-            return say(`the world did not answer: ${e.message}`);
+        if (rels.length) {
+            const more = el('button', 'another way in', { type: 'button', class: 'another' });
+            more.onclick = () => void atDoor();
+            who.append(more);
         }
-        if (!res.ok)
-            return say(`refused: ${(await res.json().catch(() => ({ error: res.status }))).error ?? res.status}`);
-        const { nonce, ward } = (await res.json());
-        password.value = '';
+    };
+    // In, as one relation: her page. Every call rotates her keys and a
+    // same-ward ask never crosses the harbor, so the side saves after each.
+    const inside = async (rel, notice, called) => {
+        await side?.close();
+        status.remove();
+        root.querySelector('form.password')?.remove();
+        screen.replaceChildren();
+        current = rel;
+        keep(AT(pk), rel.key);
+        const s = await screenSide(rel.avatar, domSurface(screen), { after: () => ward.save(), notice });
+        side = s;
+        const bp = s.model.blueprint;
+        const notesName = typeof bp?.notes?.name === 'string' ? bp.notes.name : '';
+        remember(pk, location.origin + pageOf(at.name), s.model.look.name || notesName || at.name);
+        if (!names()[rel.key])
+            keep(NAMES(pk), { ...names(), [rel.key]: called });
+        switcher();
+        people();
+    };
+    // The way in, from any of the three: a fresh avatar joins, the ward is
+    // saved, and she is the one on screen.
+    const admit = async (inv, notice, called) => {
         say('knocking');
-        const got = await me.enter({ ward }, { kind: 'tab', nonce });
-        await main.save(); // the knock went through her own door, which the harbor never sees
-        if (!('asks' in got))
-            return say(`not in: ${got.error}`);
-        form.remove();
-        await show(`in, as ${identity.value}`);
+        const rel = await fresh(ward);
+        const got = await rel.avatar.join(inv);
+        await ward.save(); // the knock went through her own door, which the harbor never sees
+        if (!('asks' in got)) {
+            say(`not in: ${got.error}`);
+            return false;
+        }
+        await inside(rel, notice, called);
+        return true;
+    };
+    // At the door. With a public being there, her describe as a page, and a
+    // form whose answer is an invitation lets the guest in. With nobody
+    // there, the door page: a link is the only way in, and nothing to type.
+    const atDoor = async () => {
+        await side?.close();
+        side = null;
+        current = null;
+        screen.replaceChildren();
+        if (!status.isConnected)
+            root.insertBefore(status, screen);
+        people();
+        if (!at.public) {
+            status.remove();
+            screen.innerHTML = door({ world: at.name, host: new URL(cfg.web).host });
+            return;
+        }
+        say(`at the door of ${at.name}`);
+        const rel = await fresh(ward);
+        const gate = guest(rel.avatar, pk);
+        const s = await screenSide(gate, domSurface(screen), {
+            after: () => ward.save(),
+            notice: `a guest at ${at.name}: what she shows strangers`,
+            admit: async (inv) => {
+                await s.close();
+                await admit(inv, `in, as a guest of ${at.name}`, 'guest');
+            },
+        });
+        side = s;
     };
+    // A link: one more relation, whoever else is in. Then whoever was on
+    // screen last, or the door.
+    if (linked && (await admit(linked, 'in, by the link', 'link')))
+        return;
+    const rels = relations(ward);
+    const last = kept(AT(pk), null);
+    const back = rels.find((r) => r.key === last) ?? rels[rels.length - 1];
+    if (back) {
+        const had = await back.avatar.tools();
+        await ward.save(); // her keys rotated on that ask, whatever it answered
+        if ('asks' in had)
+            return inside(back, linked ? `not in by the link; in, as before` : 'in, as before', names()[back.key] ?? back.key);
+        say(`not in (${had.error})`);
+    }
+    await atDoor();
 }
+// The page hands the config in a JSON script, which a content security
+// policy allows where an inline script is not.
+const config = document.getElementById('quo');
+if (config?.textContent)
+    void start(JSON.parse(config.textContent));
 export { USER };

package/dist/human/web.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DiskHarbor } from '../harbor/disk.ts';
+export type WebOptions = {
+    at: {
+        quo: string;
+        web: string;
+    };
+};
+export declare function webRoute(harbor: DiskHarbor, o: WebOptions): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean>;

package/dist/human/web.js

@@ -0,0 +1,95 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import { door } from './door.js';
+// The paths under `/web` that are the exchange's, never a ward's name.
+const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
+export function webRoute(harbor, o) {
+    const tabEntry = () => {
+        const js = fileURLToPath(new URL('./tab.js', import.meta.url));
+        return existsSync(js) ? js : fileURLToPath(new URL('./tab.ts', import.meta.url));
+    };
+    let bundle;
+    const built = () => (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((out) => out.outputFiles[0].text));
+    const quoOrigin = (() => {
+        try {
+            const u = new URL(o.at.quo);
+            return `${u.origin} ${u.origin.replace(/^http/, 'ws')}`;
+        }
+        catch {
+            return '';
+        }
+    })();
+    const host = (() => {
+        try {
+            return new URL(o.at.web).host;
+        }
+        catch {
+            return o.at.web;
+        }
+    })();
+    const policy = `default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ${quoOrigin}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`;
+    const shell = (body) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+<style>${CSS}</style>
+</head><body>${body}</body></html>`;
+    const esc = (v) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+    const publicOf = (h) => h.partition.public ?? null;
+    const html = (status, res, body) => {
+        res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': policy, 'referrer-policy': 'no-referrer' });
+        res.end(shell(body));
+        return true;
+    };
+    const wards = () => Object.fromEntries([...harbor.wards].map(([n, h]) => [n, { pk: h.pk, public: publicOf(h) !== null }]));
+    const tab = (ward) => {
+        const cfg = { quo: o.at.quo, web: o.at.web, wards: wards(), ...(ward ? { ward } : {}) };
+        return `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${o.at.web}/tab.js"></script>`;
+    };
+    return async (req, res, rest) => {
+        const parts = rest.split('/').filter(Boolean);
+        if (req.method === 'GET' && (rest === '' || rest === '/')) {
+            const list = [...harbor.wards]
+                .filter(([, h]) => publicOf(h) !== null)
+                .map(([n, h]) => `<li><a href="${o.at.web}/${encodeURIComponent(n)}">${esc(n)}</a> <small>${esc(publicOf(h) ?? '')} at the door, <code>${h.pk.slice(0, 16)}…</code></small></li>`)
+                .join('');
+            return html(200, res, `${list ? `<h1>worlds</h1><ul>${list}</ul>` : door({ host })}${tab()}`);
+        }
+        if (rest === '/tab.js' && req.method === 'GET') {
+            res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
+            res.end(await built());
+            return true;
+        }
+        const wardName = parts[0] ?? '';
+        if (!wardName || RESERVED_PATHS.has(wardName))
+            return false;
+        const hosted = harbor.wards.get(wardName);
+        if (!hosted)
+            return html(404, res, `<h1>no such world</h1><p>no ward named ${esc(wardName)} on this harbor.</p>`);
+        if (parts.length === 1 && req.method === 'GET')
+            return html(200, res, tab(wardName));
+        return false;
+    };
+}
+// The tab's stylesheet: one, light and dark, honouring the variables a look
+// sets on a section. The page owns layout; a far being paints inside her
+// section and nowhere else. The door page is the one designed thing in it.
+const CSS = [
+    ':root{color-scheme:light dark;--accent:#3b6ef5;--bg:transparent;--fg:inherit;--font:system-ui,sans-serif;--radius:6px;--ink:#1c1b22;--paper:#fbfaf7;--mute:#6b6a73}',
+    '@media(prefers-color-scheme:dark){:root{--ink:#ecebe6;--paper:#141318;--mute:#9a99a2}}',
+    'html{background:var(--paper);color:var(--ink)}',
+    'body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}',
+    'nav.worlds{display:flex;flex-wrap:wrap;gap:.5rem 1rem;font-size:.9rem;opacity:.8}nav.worlds a[aria-current]{font-weight:600}',
+    'nav.relations{display:flex;flex-wrap:wrap;gap:.25rem;margin:.5rem 0}nav.relations button{background:transparent;color:inherit;border:1px solid color-mix(in srgb,currentColor 30%,transparent)}nav.relations button[aria-current]{border-color:var(--accent);font-weight:600}',
+    'header,main{background:var(--bg);color:var(--fg);font-family:var(--font)}header{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1rem}header .notice{width:100%;margin:0}',
+    'input,select,textarea,button{font:inherit;padding:.4rem;margin:.2rem;border-radius:var(--radius)}button{background:var(--accent);color:#fff;border:0;padding:.4rem .9rem}',
+    'fieldset{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);margin:.5rem 0}',
+    'section.standing{background:var(--bg);color:var(--fg);font-family:var(--font);border-left:4px solid var(--accent);border-radius:var(--radius);padding:.25rem 1rem;margin:1.5rem 0}section.standing h2{display:flex;align-items:center;gap:.5rem;font-size:1.1rem}img.logo{height:1.6rem}',
+    'table{border-collapse:collapse}td,th{padding:.15rem .5rem;text-align:left}.answer{margin:.5rem 0 1rem;padding:.5rem;border-left:3px solid var(--accent)}.answer.error{border-color:#c33}.answer.silence,.answer.word,.answer.unreached{border-color:#c93}pre{padding:.75rem;overflow:auto}',
+    // the door page: one column, generous air, the mark, a word, a sentence
+    'main.door{min-height:70vh;display:flex;flex-direction:column;justify-content:center;align-items:flex-start;max-width:32rem;margin:0 auto;padding:3rem 0;font-family:ui-serif,Georgia,"Times New Roman",serif}',
+    'main.door .mark{width:3.5rem;height:3.5rem;color:var(--ink);opacity:.9;margin-bottom:1.25rem}',
+    'main.door h1{font-size:3rem;font-weight:400;letter-spacing:-.02em;line-height:1;margin:0 0 .5rem}',
+    'main.door .where{font-family:system-ui,sans-serif;font-size:.85rem;letter-spacing:.08em;text-transform:uppercase;color:var(--mute);margin:0 0 2rem}main.door .where span{text-transform:none;letter-spacing:0}',
+    'main.door .lead{font-size:1.5rem;line-height:1.3;margin:0 0 1rem}',
+    'main.door p{font-size:1.05rem;line-height:1.6;margin:0 0 1rem;max-width:30rem}',
+    'main.door .quiet{color:var(--mute);font-size:.95rem;border-top:1px solid color-mix(in srgb,currentColor 15%,transparent);padding-top:1rem;margin-top:1rem}',
+].join('');

package/dist/human/worlds.d.ts

@@ -0,0 +1,10 @@
+import type { Harbor, Hosted } from '@quo-systems/quo/harbor';
+import { Avatar } from '../beings/avatar.ts';
+export declare const localName: (pk: string) => string;
+export declare function world(harbor: Harbor, pk: string): Promise<Hosted>;
+export type Relation = {
+    key: string;
+    avatar: Avatar;
+};
+export declare function relations(ward: Hosted): Relation[];
+export declare function fresh(ward: Hosted): Promise<Relation>;

package/dist/human/worlds.js

@@ -0,0 +1,38 @@
+import { Avatar, USER } from '../beings/avatar.js';
+// The local ward for a far world, by its pk: created on first sight, on
+// the tab's own seed, empty.
+export const localName = (pk) => `w-${pk.slice(0, 16)}`;
+export async function world(harbor, pk) {
+    const name = localName(pk);
+    return harbor.wards.get(name) ?? (await harbor.create(name, 'me'));
+}
+export function relations(ward) {
+    const beings = ward.partition.beings ?? {};
+    const out = [];
+    for (const key of Object.keys(beings)) {
+        const a = ward.being(key);
+        if (a instanceof Avatar && a.standings[USER])
+            out.push({ key, avatar: a });
+    }
+    return out;
+}
+// An avatar for a relation not yet made: one who holds no standing, whether
+// left by a guest who never came in or booted now under the next free key.
+// She is the one who knocks, as a guest or with an invitation, and she
+// becomes a relation the moment she takes her standing.
+export async function fresh(ward) {
+    const beings = ward.partition.beings ?? {};
+    for (const key of Object.keys(beings)) {
+        const a = ward.being(key);
+        if (a instanceof Avatar && !a.standings[USER])
+            return { key, avatar: a };
+    }
+    let n = 1;
+    while (beings[`r${n}`])
+        n++;
+    const key = `r${n}`;
+    const out = (await ward.ask('boot', { key, class: 'Avatar' }));
+    if (out.error)
+        throw new Error(`the tab could not boot an avatar: ${out.error}`);
+    return { key, avatar: ward.being(key) };
+}