@nervur-org/dock 0.3.0

package/human/tab.ts

@@ -0,0 +1,446 @@
+// SPDX-License-Identifier: Apache-2.0
+// The tab: a page on a world's web. that is a device of its own. The tab
+// boots a browser harbor on a seed minted into IndexedDB the first time,
+// and is a browser of worlds and of the relations in them, `worlds.ts`: one
+// local ward per far world, one avatar per relation, a switcher over both.
+// A switch is a switch of avatar and nothing more.
+//
+// Three ways in and there is no fourth, the same act each time, a knock
+// that ends in a standing, and each one a fresh avatar:
+//
+//   a link      the page with the invitation in its fragment, `#quo=...`,
+//               read and stripped before anything else runs, then joined.
+//               The invitation names its ward, so it is joined in that
+//               world's local ward whatever page it was opened on, and a
+//               link opened while already in is one more relation.
+//   a proof     the page with a proof in its fragment, `#proof=<kind>.<token>`,
+//               read and stripped the same way. A proof names no ward, so it
+//               is for the world whose page it was opened on: the tab knocks
+//               at that world's public being with it, and what she trades it
+//               for is an invitation, joined like any other. This is the way
+//               in a world sent out itself, by mail or by message.
+//   a guest     the world's public being, whatever class she is, rendered
+//               as a page by the same screen; a form on it whose answer is
+//               an invitation is the way in.
+//
+// Nothing is typed to get in, ever: no password, no account. A ward with
+// nobody at its door shows the door page, `door.ts`, and a link is the only
+// way. From then on there is no cookie and no token anywhere; the seed and
+// the standings are in the tab's store, and a reload asks nothing. The screen
+// is the human side in `screen.ts` over the DOM surface in `dom.ts`. This
+// file is the shell: the harbor, the config, the switcher and the ways in,
+// and it hands one avatar at a time to the side.
+import type { Invitation, JsonObject } from '@nervur-org/nervur';
+import { BrowserHarbor } from '../harbor/browser.ts';
+import { USER } from '../beings/avatar.ts';
+import { isInvitation } from '@nervur-org/nervur';
+import { parse, parseProof, strip } from '../beings/link.ts';
+import { giveWorld, type Giving } from './move.ts';
+import { drained, subscribe } from './wake.ts';
+import { screenSide } from './screen.ts';
+import { refused } from './html.ts';
+import { domSurface } from './dom.ts';
+import { guest } from './guest.ts';
+import { door, held } from './door.ts';
+import { world, relations, fresh, localName, type Relation } from './worlds.ts';
+import { local } from './local.ts';
+import type { BeingClass } from '@nervur-org/nervur';
+
+// What the page is told by the daemon that served it: the world's routes,
+// every ward on that harbor by name, its pk and whether a public being is
+// at its door, which of them this page is, if it is one's, and whether the
+// world serves code for the tab.
+// `bell` is the world's doorbell key, the public half of its VAPID pair,
+// which a page subscribes to a push service with. A world with no doorbell
+// sends none, and a device there is reachable only while it holds a line.
+export type Config = { quo: string; web: string; wards: Record<string, { pk: string; public: boolean }>; ward?: string; being?: string; beings?: boolean; bell?: string };
+
+// What the tab remembers between pages, beside the harbor: the worlds it
+// has joined, by pk, where each lives and what it is called; which relation
+// is on screen in each; and what each relation is called. A tab with no
+// storage still works, and forgets.
+type Worlds = Record<string, { url: string; name: string }>;
+const kept = <T>(key: string, fallback: T): T => {
+  try {
+    return (JSON.parse(localStorage.getItem(key) ?? 'null') as T | null) ?? fallback;
+  } catch {
+    return fallback;
+  }
+};
+const keep = (key: string, value: unknown) => {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    /* forgets */
+  }
+};
+const WORLDS = 'quo-worlds';
+const worlds = (): Worlds => kept(WORLDS, {});
+const remember = (pk: string, url: string, name: string) => keep(WORLDS, { ...worlds(), [pk]: { url, name } });
+const AT = (pk: string) => `quo-at:${pk}`;
+const NAMES = (pk: string) => `quo-names:${pk}`;
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Record<string, string> = {}): HTMLElementTagNameMap[K] => {
+  const e = document.createElement(tag);
+  if (text) e.textContent = text;
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v);
+  return e;
+};
+
+export async function start(cfg: Config, root: HTMLElement = document.body): Promise<void> {
+  // The link, first and once: the invitation, or the proof a world sent
+  // out, leaves the address bar before any other code sees it.
+  const linked = parse(location.hash);
+  const proved = parseProof(location.hash);
+  if (linked || proved) history.replaceState(null, '', location.pathname + location.search + strip(location.hash));
+
+  const nav = el('nav', '', { class: 'worlds nv-strip' });
+  const who = el('nav', '', { class: 'relations nv-row' });
+  const status = el('p', 'booting', { class: 'state nv-t-quiet' });
+  const screen = el('div');
+  root.append(nav, who, status, screen);
+  const say = (s: string) => (status.textContent = s);
+
+  // The harbor in the tab: one database per origin, one ward per world.
+  // The world's code first, when its origin serves any: the classes for
+  // the tab, handed to the harbor beside the built-in ones before any ward
+  // boots, since a being kept from the last visit is booted by class name.
+  // A world that serves none has no beings in the tab, and the page is the
+  // far being's alone.
+  const harbor = new BrowserHarbor('quo');
+  const classes = cfg.beings
+    ? await import(`${cfg.web}/beings.js`).then((mod: Record<string, unknown>) => {
+        const out: Record<string, BeingClass> = {};
+        for (const [name, v] of Object.entries(mod)) if (typeof v === 'function' && 'prototype' in v) out[name] = v as BeingClass;
+        return out;
+      })
+    : {};
+  Object.assign(harbor.classes, classes);
+  // A device is one harbor, and this browser may already be holding it in
+  // another tab. That tab is the device; this one is a page, and it says
+  // so here rather than sitting on the word `booting` with the refusal in a
+  // console nobody has open.
+  try {
+    await harbor.boot();
+  } catch (e) {
+    status.remove();
+    screen.innerHTML = held({ world: cfg.ward, host: new URL(cfg.web).host });
+    throw e; // the terrain still hears it: a page that says so is not a page that succeeded
+  }
+  harbor.dial(cfg.quo);
+
+  // The doorbell. A world with a bell key is a world that can wake this
+  // device when it is closed, and the ear is the service worker on this
+  // origin; a device already subscribed says so again silently, and one
+  // that has never been asked is offered a button rather than a prompt on
+  // arrival. The ring arrives at the worker: with this page open the worker
+  // hands it a port, and the page wakes its dialers, drains and answers
+  // what it found, since the harbor is held here and nowhere else.
+  const pks = Object.values(cfg.wards).map((w) => w.pk);
+  let bell = cfg.bell ? await subscribe(cfg.web, cfg.bell) : null;
+  globalThis.navigator?.serviceWorker?.addEventListener('message', (e: MessageEvent) => {
+    if ((e.data as { quo?: string } | null)?.quo !== 'wake') return;
+    const port = e.ports[0];
+    void (async () => {
+      harbor.wake();
+      port?.postMessage({ missed: await drained(harbor, pks) });
+    })();
+  });
+
+  // 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: string) => 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: string) => `${new URL(cfg.web).pathname.replace(/\/$/, '')}/${encodeURIComponent(name)}`;
+  // The same page, whole. What leaves this tab, a remembered world or a link
+  // for another device, carries the address and not the path.
+  const addressOf = (name: string) => location.origin + pageOf(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, class: 'nv-chip' });
+      if (k === pk) a.setAttribute('aria-current', 'page');
+      nav.append(a);
+    }
+    // a world this device is not in yet is named by its own page, not by the strip
+    if (!nav.childElementCount) nav.remove();
+    else if (!nav.isConnected) root.insertBefore(nav, root.firstChild);
+  };
+  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: { close(): Promise<void> } | null = null;
+  let current: Relation | null = null;
+  const names = () => kept<Record<string, string>>(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', class: 'nv-chip' });
+      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);
+    }
+    if (rels.length) {
+      const more = el('button', 'another way in', { type: 'button', class: 'another nv-chip' });
+      more.onclick = () => void atDoor();
+      who.append(more);
+    }
+    moving.hidden = rels.length === 0; // there is nothing to move out of a world this device is not in
+  };
+
+  // The world's beings in the tab, for one relation: one of each class,
+  // booted under her key the first time and found there after, since their
+  // cells are in the ward and come back with it. Each is a subject of her
+  // own with her own side in her own section, so a note she keeps and a
+  // form she shows are hers, painted by the same painter as the far page.
+  const locals: { close(): Promise<void> }[] = [];
+  const boot = async (rel: Relation) => {
+    for (const name of Object.keys(classes)) {
+      const key = `${rel.key}-${name}`;
+      // Booted the first time and found after. Boot refuses a key that has a
+      // row, so asking is how a caller learns she is already there, and a
+      // refusal is the same nothing-to-do as finding her.
+      if (!ward.being(key)) {
+        const out = (await ward.ask('boot', { key, class: name })) as { error?: string };
+        if (out.error) continue;
+        await ward.save();
+      }
+      if (!ward.being(key)) continue;
+      const section = el('section', '', { class: 'local', 'data-being': key });
+      screen.append(section);
+      // The ask pointer saves before it returns, so the side has nothing to do after one.
+      locals.push(await screenSide(local(ward, key), domSurface(section), { at: addressOf(at.name) }));
+    }
+  };
+
+  // In, as one relation: her page, then the world's beings for her. Every
+  // call rotates her keys and a same-ward ask never crosses the harbor, so
+  // the side saves after each.
+  const inside = async (rel: Relation, notice: string, called: string) => {
+    await side?.close();
+    for (const l of locals.splice(0)) await l.close();
+    status.remove();
+    root.querySelector('form.password')?.remove();
+    screen.replaceChildren();
+    current = rel;
+    keep(AT(pk), rel.key);
+    const mine = el('div', '', { class: 'far' });
+    screen.append(mine);
+    // the page's address: the world's page, or one being she carries as the whole page
+    const s = await screenSide(rel.avatar, domSurface(mine), {
+      after: () => ward.save(),
+      notice,
+      at: addressOf(at.name),
+      // A world that ended the relation is over, and the one act left is
+      // leaving. The tab says so and puts the way out where she is looking;
+      // it drops nothing, since one answer at one moment is never enough to
+      // delete a ward and the far world can never be asked to confirm it.
+      ended: async () => {
+        leave.textContent = 'leave this world';
+        leave.classList.add('only');
+        moving.scrollIntoView({ block: 'nearest' });
+      },
+      ...(cfg.being ? { focus: cfg.being } : {}),
+    });
+    side = s;
+    const bp = s.model.blueprint;
+    const notesName = typeof (bp?.notes as JsonObject | null)?.name === 'string' ? ((bp!.notes as JsonObject).name as string) : '';
+    remember(pk, addressOf(at.name), s.model.look.name || notesName || at.name);
+    if (!names()[rel.key]) keep(NAMES(pk), { ...names(), [rel.key]: called });
+    // How this world wakes this device, said again whenever a relation comes
+    // on screen: a push service may hand a browser a new endpoint at any
+    // time, and a stale one rings an empty house.
+    if (bell) await rel.avatar.call('bell', { token: bell }).then(() => ward.save());
+    // The device is back, so it drains: whatever was pushed while this tab
+    // was closed is on her under this relation, and it lands on the avatar
+    // where a push would have landed. A tab with nothing waiting spends one
+    // ask and shows the same page.
+    await drained(harbor, [pk]);
+    switcher();
+    people();
+    if (!cfg.being) await boot(rel); // a being's page is hers alone: the world's tab beings stay on the world's page
+  };
+
+  // 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: Invitation, notice: string, called: string) => {
+    say('knocking');
+    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();
+    for (const l of locals.splice(0)) await l.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`,
+      at: addressOf(at.name),
+      admit: async (inv) => {
+        await s.close();
+        await admit(inv, `in, as a guest of ${at.name}`, 'guest');
+      },
+    });
+    side = s;
+    status.remove(); // her page is up and says where the human stands; the status was for the wait
+  };
+
+  // Moving this world to another device. What the tab holds of a world is
+  // one local ward, and every standing won here is in it, so the move is
+  // that ward and nothing else: the world is never asked and never told.
+  // The other device shows an invitation, the human carries it here, and
+  // this tab is out of the world the moment the other one has it.
+  // Leaving. What this tab holds of a world is one local ward, and every
+  // standing won here is in it, so leaving is that ward dropped whole, seed
+  // and all, and the world forgotten from the list. The far world is never
+  // asked and never told, as WORLDS has it of a lost phone: it sees one
+  // device gone and nothing else. Nothing here is recoverable afterwards, so
+  // it is one press and never a consequence of an answer: a world that says
+  // the relation ended offers this and does not take it.
+  const forget = async () => {
+    await side?.close();
+    for (const l of locals.splice(0)) await l.close();
+    side = null;
+    keep(
+      WORLDS,
+      Object.fromEntries(Object.entries(worlds()).filter(([k]) => k !== pk)),
+    );
+    localStorage.removeItem(AT(pk));
+    localStorage.removeItem(NAMES(pk));
+  };
+  const leave = el('button', 'leave this world', { type: 'button', class: 'leave nv-button', 'data-variant': 'danger' });
+  leave.onclick = () =>
+    void (async () => {
+      await forget();
+      await harbor.drop(localName(pk));
+      location.reload(); // at the door of a world this device is out of
+    })();
+
+  const moving = el('div', '', { class: 'move' });
+  const offer = el('p', '', { class: 'invitation' });
+  const said = el('p', '', { class: 'quiet' });
+  const give = el('button', 'move this world to another device', { type: 'button', class: 'nv-button', 'data-variant': 'quiet' });
+  // Being woken is asked for and never sprung: a page that asks a browser
+  // for notifications the moment it opens is a page every browser punishes,
+  // and a human who has not said yet is offered a button instead.
+  const doorbell = el('button', 'let this world wake me', { type: 'button', class: 'doorbell nv-button', 'data-variant': 'quiet' });
+  doorbell.hidden = !cfg.bell || bell !== null;
+  doorbell.onclick = () =>
+    void (async () => {
+      bell = cfg.bell ? await subscribe(cfg.web, cfg.bell, true) : null;
+      doorbell.hidden = bell !== null;
+      if (bell && current) await current.avatar.call('bell', { token: bell }).then(() => ward.save());
+    })();
+  moving.append(give, leave, offer, said, doorbell);
+  let giving: Giving | null = null;
+  const stopGiving = async () => {
+    const g = giving;
+    giving = null;
+    offer.textContent = '';
+    give.textContent = 'move this world to another device';
+    await g?.close();
+  };
+  give.onclick = () =>
+    void (async () => {
+      if (giving) return stopGiving();
+      said.textContent = '';
+      giving = await giveWorld(harbor, { pk, at: addressOf(at.name), name: at.name }, cfg.quo);
+      offer.textContent = giving.offer;
+      give.textContent = 'stop offering it';
+      void giving.moved.then(async () => {
+        // it is on the other device now, and this one is out of the world:
+        // the standings went with the ward and nothing here is in it
+        await forget(); // the ward went with the move, so nothing is dropped here
+        location.reload(); // the page reloads at the door of a world this device is out of
+      });
+    })().catch((e: unknown) => (said.textContent = String(e)));
+  root.append(moving);
+
+  // A proof: the world's own way in, spent at her door. A proof names no
+  // ward, so it is for the world this page is, and what she trades it for
+  // is an invitation, joined like any other.
+  //
+  // `device` is the ask, and that name is a convention of the dock's rather
+  // than the desk's alone: a proof arrives in a fragment and not as a form,
+  // so there is nothing to draw and a name is the only way to hand it over.
+  // A public being of any class takes proofs by writing that ask; one that
+  // writes none answers this as an unknown ask, which is a world with no
+  // proof way in and is refused like any other refusal. What a proof is worth is the
+  // way in's word and never the desk's: the desk routes it by kind, and the
+  // being who verifies it says who it is for, how far she may go and
+  // whether it may be spent again. A world with nobody at her door trades
+  // nothing, and a refusal of any of those kinds leaves the human at the
+  // door with nothing taken and one line saying so.
+  if (proved && at.public) {
+    say('at the door');
+    const rel = await fresh(ward);
+    const got = await rel.avatar.knock({ ward: pk }, 'device', { proof: { kind: proved.kind, token: proved.token } });
+    await ward.save();
+    if (isInvitation(got) && (await admit(got, 'in, by the link', 'link'))) return;
+    // What came back and not a guess at it. A world refuses a way in for
+    // several different reasons and only one of them is that it was spent;
+    // `id taken` in particular is a device of that name already in this
+    // world, which is what a human meets when she has lost the device that
+    // held it, and telling her it was spent sends her looking for the wrong
+    // thing.
+    say(refused(got));
+  }
+
+  // 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<string | null>(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) as Config);
+
+export { USER };

package/human/tree.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: Apache-2.0
+// The page grammar: a page as a tree of values, and its painter. One
+// grammar, two sources: a far being answers `page` with a tree, values
+// only, the way she answers `look`; a being running in the tab computes one
+// from her cells. The screen paints either with the painter below, and a
+// being that answers nothing gets the forms `html.ts` paints on its own.
+//
+// The vocabulary is closed, and a node that fails its shape is dropped, not
+// fixed: nothing here can carry a selector, a stylesheet or a script, and an
+// image is a data URI, so a far being can design her page and can never
+// reach out of it. What a node names, an ask or a standing, must exist in
+// her describe for this asker, or it paints as nothing: a page adds no
+// right.
+//
+// One node names a place, and it is the one the side holds rather than the
+// grammar. A `link` carries an address, because a human who must buy
+// something, sign something or come back from a vendor has to be able to go
+// there, and a being who could not say so would be a being every world
+// works around. So the shape here admits only an absolute `http` or `https`
+// address, and where it may point is not decided here: the painter is the
+// side's, and the side is what knows which places this human already
+// reaches. A painter that will not vouch for an address paints the address
+// as words, so the human sees where she was being sent and goes there by
+// her own hand or not at all.
+//
+//   stack      children one under another            { kind: 'stack', of: [...], as?: list | grid | hero | feed }
+//   row        children side by side, wrapping       { kind: 'row', of: [...], as?: person }
+//   text       words with a role                     { kind: 'text', text, role?: title | lead | body | quiet | label }
+//   image      a picture as a data URI, never a URL  { kind: 'image', src, alt? }
+//   link       somewhere to go, held by the side     { kind: 'link', href, text? }
+//   form       one of her asks as a form             { kind: 'form', ask }
+//   answer     one of her asks' last answer, shown   { kind: 'answer', ask, as?: auto | text | table | cards | list | people | feed }
+//   standing   one standing she carries, a section   { kind: 'standing', id, as?: door }
+//   standings  every standing she carries            { kind: 'standings' }
+//
+// A container may say what kind of thing it holds, and never how it looks:
+// `list` is several of one thing as rows on one surface, `grid` is cards,
+// `hero` is one thing on a lot of air, `feed` is what happened in order,
+// and a row that is a `person` is a face and the words beside it. The
+// painter holds every opinion about what each kind is on a screen, so
+// every world's people, requests and contacts are one shape everywhere, and
+// a being never carries a layout. An answer says its kind the same way:
+// `people` are rows of { name, line?, picture? }, and `feed` is rows of
+// { at, text }; a value that is not that shape is shown by its own shape.
+import type { Json } from '@nervur-org/nervur';
+import { escape } from './html.ts';
+
+export type Role = 'title' | 'lead' | 'body' | 'quiet' | 'label';
+export type As = 'auto' | 'text' | 'table' | 'cards' | 'list' | 'people' | 'feed';
+export type Layout = 'list' | 'grid' | 'hero' | 'feed';
+export type Node =
+  | { kind: 'stack'; of: Node[]; as?: Layout }
+  | { kind: 'row'; of: Node[]; as?: 'person' }
+  | { kind: 'text'; text: string; role?: Role }
+  | { kind: 'image'; src: string; alt?: string }
+  | { kind: 'link'; href: string; text?: string }
+  | { kind: 'form'; ask: string }
+  | { kind: 'answer'; ask: string; as?: As }
+  | { kind: 'standing'; id: string; as?: 'door' }
+  | { kind: 'standings' };
+
+const ROLES = new Set<Role>(['title', 'lead', 'body', 'quiet', 'label']);
+const AS = new Set<As>(['auto', 'text', 'table', 'cards', 'list', 'people', 'feed']);
+const LAYOUTS = new Set<Layout>(['list', 'grid', 'hero', 'feed']);
+const TEXT = 4000; // characters a text node may carry
+const DEPTH = 12; // how deep a tree may nest
+const WIDE = 200; // children a container may have
+// A name in the grammar is a name in her describe, spelled as she spells
+// it: an ask of her own, a standing's id, or a carried ask, `<id>-<name>`.
+// A standing's id is the dock's to choose and carries a colon where the
+// dock's own convention puts one, a way back to a device being `to:<id>`,
+// so a shape that refused a colon would drop the section a device's own
+// faculties are painted in. It stays a name and never a path: no slash, no
+// space, and it is looked up in her describe before anything is painted.
+const NAME = /^[\w.:-]{1,80}$/;
+const HREF = 2000; // characters an address may be
+
+// A value held to the grammar, or null. Children that fail are dropped and
+// the container kept; a container with nothing left is kept empty, since an
+// empty region is a design and not a fault.
+export function sanitiseTree(v: Json, depth = 0): Node | null {
+  if (depth > DEPTH || v === null || typeof v !== 'object' || Array.isArray(v)) return null;
+  const o = v as Record<string, Json>;
+  switch (o.kind) {
+    case 'stack':
+    case 'row': {
+      const of = Array.isArray(o.of) ? o.of.slice(0, WIDE).map((c) => sanitiseTree(c, depth + 1)).filter((c): c is Node => c !== null) : [];
+      if (o.kind === 'row') return typeof o.as === 'string' && o.as === 'person' ? { kind: 'row', of, as: 'person' } : { kind: 'row', of };
+      return typeof o.as === 'string' && LAYOUTS.has(o.as as Layout) ? { kind: 'stack', of, as: o.as as Layout } : { kind: 'stack', of };
+    }
+    case 'text': {
+      if (typeof o.text !== 'string') return null;
+      const n: Node = { kind: 'text', text: o.text.slice(0, TEXT) };
+      if (typeof o.role === 'string' && ROLES.has(o.role as Role)) n.role = o.role as Role;
+      return n;
+    }
+    case 'image': {
+      if (typeof o.src !== 'string' || !/^data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+$/i.test(o.src)) return null;
+      const n: Node = { kind: 'image', src: o.src };
+      if (typeof o.alt === 'string') n.alt = o.alt.slice(0, 200);
+      return n;
+    }
+    case 'link': {
+      // The shape only: an absolute address on the web, parsed rather than
+      // matched, so nothing that merely looks like one gets through. Where
+      // it may point is the painter's, not this file's.
+      if (typeof o.href !== 'string' || o.href.length > HREF) return null;
+      let url: URL;
+      try {
+        url = new URL(o.href);
+      } catch {
+        return null;
+      }
+      if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
+      const n: Node = { kind: 'link', href: url.href };
+      if (typeof o.text === 'string' && o.text.trim()) n.text = o.text.slice(0, 200);
+      return n;
+    }
+    case 'form':
+      return typeof o.ask === 'string' && NAME.test(o.ask) ? { kind: 'form', ask: o.ask } : null;
+    case 'answer': {
+      if (typeof o.ask !== 'string' || !NAME.test(o.ask)) return null;
+      const n: Node = { kind: 'answer', ask: o.ask };
+      if (typeof o.as === 'string' && AS.has(o.as as As)) n.as = o.as as As;
+      return n;
+    }
+    case 'standing':
+      if (typeof o.id !== 'string' || !NAME.test(o.id)) return null;
+      return o.as === 'door' ? { kind: 'standing', id: o.id, as: 'door' } : { kind: 'standing', id: o.id };
+    case 'standings':
+      return { kind: 'standings' };
+    default:
+      return null;
+  }
+}
+
+// The names a tree asks the answers of: what a side runs on her behalf so
+// the page opens with what it shows, when the ask needs nothing typed.
+export function answersIn(n: Node, out: string[] = []): string[] {
+  if (n.kind === 'answer') out.push(n.ask);
+  if (n.kind === 'stack' || n.kind === 'row') for (const c of n.of) answersIn(c, out);
+  return out;
+}
+
+// What the painter needs from whoever holds the describe and the answers:
+// each returns HTML for a name it knows, and the empty string for one it
+// does not, so a page can never show what the gate did not.
+export type Painter = {
+  // An address the being named, and the words she wants on it. The painter
+  // vouches or it does not: an anchor where this human already reaches, and
+  // the address as words where she does not, so nothing is hidden either
+  // way.
+  link(href: string, text: string): string;
+  form(ask: string): string;
+  answer(ask: string, as: As): string;
+  // A standing as her section, or as a door: named, with the way to her
+  // own page, and nothing of hers on this one.
+  standing(id: string, as?: 'door'): string;
+  standings(): string;
+};
+
+const ROLE_TAG: Record<Role, string> = { title: 'h1', lead: 'p', body: 'p', quiet: 'p', label: 'p' };
+
+// Whether a tree opens with a title of its own, at its top or one level
+// in: then the page's bar says no name, since the page says it once.
+export function titled(n: Node | null, depth = 0): boolean {
+  if (!n || depth > 2) return false;
+  if (n.kind === 'text') return n.role === 'title';
+  if (n.kind === 'stack' || n.kind === 'row') return n.of.some((c) => titled(c, depth + 1));
+  return false;
+}
+
+// Each kind on the kit's pieces, and the painter holds the opinion: a list
+// wraps each child as a row, a grid as a card, a person puts her picture in
+// the round place a face has.
+export function paint(n: Node, p: Painter): string {
+  switch (n.kind) {
+    case 'stack': {
+      const inner = (wrap: string) => n.of.map((c) => `<div class="${wrap}">${paint(c, p)}</div>`).join('');
+      if (n.as === 'list') return `<div class="nv-list">${inner('nv-item')}</div>`;
+      if (n.as === 'grid') return `<div class="nv-cards">${inner('nv-card')}</div>`;
+      if (n.as === 'hero') return `<div class="nv-hero">${n.of.map((c) => paint(c, p)).join('')}</div>`;
+      if (n.as === 'feed') return `<div class="nv-feed">${n.of.map((c) => paint(c, p)).join('')}</div>`;
+      return `<div class="nv-stack">${n.of.map((c) => paint(c, p)).join('')}</div>`;
+    }
+    case 'row': {
+      if (n.as === 'person') {
+        const face = n.of.find((c) => c.kind === 'image');
+        const rest = n.of.filter((c) => c !== face).map((c) => paint(c, p)).join('');
+        const words = n.of.find((c) => c.kind === 'text');
+        const initial = words && words.kind === 'text' ? escape(words.text.trim().charAt(0).toUpperCase()) : '';
+        return `<div class="nv-person"><span class="nv-avatar">${face ? paint(face, p) : initial}</span><div class="nv-stack">${rest}</div></div>`;
+      }
+      return `<div class="nv-row" data-align="center">${n.of.map((c) => paint(c, p)).join('')}</div>`;
+    }
+    case 'text': {
+      const role = n.role ?? 'body';
+      return `<${ROLE_TAG[role]} class="nv-t-${role}">${escape(n.text)}</${ROLE_TAG[role]}>`;
+    }
+    case 'image':
+      return `<img class="nv-picture" alt="${escape(n.alt ?? '')}" src="${n.src}">`;
+    case 'link':
+      return p.link(n.href, n.text ?? n.href);
+    case 'form':
+      return p.form(n.ask);
+    case 'answer':
+      return p.answer(n.ask, n.as ?? 'auto');
+    case 'standing':
+      return p.standing(n.id, n.as);
+    case 'standings':
+      return p.standings();
+  }
+}
+
+// A painter with nothing behind it: for a page that names no ask, the door
+// page and any page painted before anyone is in.
+export const nobody: Painter = { link: () => '', form: () => '', answer: () => '', standing: () => '', standings: () => '' };