@nervur-org/dock 0.3.0

package/human/door.ts

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// The door page: what a stranger sees where nothing lets them in. No
+// invitation in the fragment, no relation in this tab's harbor, and nobody
+// at the ward's door; or a harbor's root with no world to list. It is
+// Quo's page and not the estate's: it says what this is and that a world
+// here is entered by a link someone sends you, and it asks for nothing,
+// since there is nothing a stranger could type that would let them in. A
+// world that wants a face of its own has a public being with a page and a
+// look, or its own page on its own origin; this is the default and nothing
+// more. It is the first page written in the grammar, `tree.ts`, painted
+// with nobody behind it: no ask, no answer, no standing.
+import { paint, nobody, type Node, type Painter } from './tree.ts';
+import { escape } from './html.ts';
+import { MARK } from './mark.ts';
+
+export type Door = { world?: string; host: string };
+
+export function doorTree(at: Door): Node {
+  return {
+    kind: 'stack',
+    as: 'hero',
+    of: [
+      { kind: 'image', src: MARK, alt: '' },
+      { kind: 'text', text: 'quo', role: 'title' },
+      { kind: 'text', text: at.world ? `${at.world} at ${at.host}` : at.host, role: 'label' },
+      { kind: 'text', text: at.world ? 'This world is entered by invitation.' : 'The worlds here are entered by invitation.', role: 'lead' },
+      { kind: 'text', text: 'An invitation is a link someone sends you. Open it here, and you are in: no account, no password, nothing to type. What you can do inside is what the world shows you, and it is yours to keep on this device.' },
+      { kind: 'text', text: 'Nothing on this page asks anything of you. If you were sent here without a link, ask the person who sent you for one.', role: 'quiet' },
+    ],
+  };
+}
+
+export function door(at: Door): string {
+  return `<main data-door>${paint(doorTree(at), nobody)}</main>`;
+}
+
+// The other page with nobody behind it: what a human sees where this
+// browser already holds the harbor in another tab. A device is one harbor
+// and the lock is what says so, since two harbors over one seed would be
+// two devices claiming to be the same one, each writing the other's wards.
+// So the second tab is a page and not a device, and the page says which of
+// the two it is rather than saying `booting` until she gives up. Nothing
+// here offers to take the lock: the tab that holds it may be the one she
+// is working in.
+export function heldTree(at: Door): Node {
+  return {
+    kind: 'stack',
+    as: 'hero',
+    of: [
+      { kind: 'image', src: MARK, alt: '' },
+      { kind: 'text', text: 'Already open', role: 'title' },
+      { kind: 'text', text: at.world ? `${at.world} at ${at.host}` : at.host, role: 'label' },
+      { kind: 'text', text: 'This world is open in another tab of this browser, and one browser is one device here. That tab holds the device; this one is only a page.', role: 'lead' },
+      { kind: 'text', text: 'Go back to the tab that has it, or close that tab and reload this one. Nothing is lost either way: what this device is in every world is kept in the browser, not in a tab.' },
+    ],
+  };
+}
+
+export function held(at: Door): string {
+  return `<main data-door>${paint(heldTree(at), nobody)}</main>`;
+}
+
+// The policy every page Quo writes itself is served under, wherever it is
+// served from. These pages run no script and want none, so nothing but
+// their own form is allowed anywhere, an image is the mark and therefore
+// data, and no referer carries what brought a human here off the page.
+export const POLICY = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; form-action 'self'; base-uri 'none'; frame-ancestors 'none'";
+
+// A painter for Quo's own pages. It is `nobody` with links painted, and
+// that is sound where the other painter's caution is not: the vouching rule
+// exists because a far being names a place and the side cannot know where
+// she is sending a human. On these pages the dock wrote the address itself,
+// out of what the daemon was configured with, so there is nobody to vouch
+// for. No ask, no answer and no standing, as before.
+export const ours: Painter = {
+  ...nobody,
+  link: (href, text) => `<a class="link" href="${escape(href)}">${escape(text)}</a>`,
+};
+
+// Where a redirect lands. A vendor a world sent a human to, a checkout or a
+// consent screen, sends her back by opening a URL in her browser, and that
+// URL is the envoy's own door: the same ask in the envoy always had, with an
+// empty body and the code in the query. So a human ends a payment looking at
+// whatever that ask answered, and what it answers is JSON.
+//
+// This is the page she gets instead. It says which of the two happened,
+// because a human who has just paid needs to know, and it offers the world's
+// own page, because a browser tab opened by a vendor has no history to go
+// back through. What the envoy answered is never shown: she said `{ ok }` or
+// an error object to a machine, and neither is a sentence.
+export type Landed = { world?: string; host: string; at?: string; ok: boolean };
+
+export function landedTree(l: Landed): Node {
+  const of: Node[] = [
+    { kind: 'image', src: MARK, alt: '' },
+    { kind: 'text', text: l.ok ? 'That is done' : 'That did not finish', role: 'title' },
+    { kind: 'text', text: l.world ? `${l.world} at ${l.host}` : l.host, role: 'label' },
+    {
+      kind: 'text',
+      text: l.ok
+        ? 'You came back from somewhere this world sent you, and it heard you. Nothing else is needed here.'
+        : 'You came back from somewhere this world sent you, and it could not finish. Nothing was taken from you here, and you can try again from the world itself.',
+      role: 'lead',
+    },
+  ];
+  if (l.at) of.push({ kind: 'link', href: l.at, text: l.world ? `back to ${l.world}` : 'back to this world' });
+  else of.push({ kind: 'text', text: 'You can close this page.', role: 'quiet' });
+  return { kind: 'stack', as: 'hero', of };
+}
+
+export function landed(l: Landed): string {
+  return `<main data-door>${paint(landedTree(l), ours)}</main>`;
+}

package/human/guest.ts

@@ -0,0 +1,34 @@
+// 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, and nothing needs to: the forms are
+// drawn from whatever asks she has, and what makes one of them the way in
+// is that its answer is an invitation. She may call it anything.
+//
+// The proof way in is the one place a name is needed, since a proof arrives
+// in a link's fragment rather than typed, so there is no form to answer and
+// the shell must knock a named ask. That name is `device`, and it is a
+// convention of the dock's like `hello`, `look` and `page`: a public being
+// of any class takes proofs by writing an ask under that name, and one that
+// writes none has no proof way in and loses nothing else.
+import { isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import type { Answer, Blueprint, Invitation, JsonObject, Wanted } from '@nervur-org/nervur';
+import type { Avatar } from '../beings/avatar.ts';
+import type { Subject } from '../beings/side.ts';
+
+export function guest(avatar: Avatar, ward: string): Subject {
+  const at: Invitation = { 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 as Blueprint).asks)) return { error: 'nobody is home' };
+      return bp as Blueprint;
+    },
+    call: (name: string, args: JsonObject = {}, wanted?: Wanted): Promise<Answer> => avatar.knock(at, name, args, wanted),
+    ears: new Set(),
+  };
+}

package/human/html.ts

@@ -0,0 +1,490 @@
+// SPDX-License-Identifier: Apache-2.0
+// A blueprint spoken as HTML, and a form heard back as arguments. Pure:
+// strings in, strings out, no document, no element, no event. This is the
+// whole vocabulary of the screen, so that a page can be proven with no
+// browser at all. Nothing here knows an avatar; the side hands in what she
+// answered and reads out what the human submitted.
+//
+//   form(ask)             the ask's input schema as fields, one per property
+//   values(ask, raw)      the submitted strings back as arguments, typed by the schema
+//   view(value, schema?)  an answer as a view, ordered by the output schema
+//   page(model)           the whole page: title, notice, forms, views, pushes
+import type { Answer, Ask, Blueprint, Json, JsonObject } from '@nervur-org/nervur';
+import { SILENCE_TEXT, UNREACHED_TEXT, word, wordText, type Word } from '../beings/side.ts';
+import { hint, hintFor, sanitise, groups as grouped, presentation, type Look, type Hint } from '../beings/look.ts';
+import { paint, titled, type As, type Node, type Painter } from './tree.ts';
+import { isInvitation } from '@nervur-org/nervur';
+import { link } from '../beings/link.ts';
+
+// One property of an input schema, as the form needs it.
+export type Property = { type?: string; description?: string; enum?: Json[]; format?: string; default?: Json };
+export type Schema = { properties?: Record<string, Property>; required?: string[] };
+
+export const escape = (s: string): string => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+
+const props = (schema: JsonObject | undefined): [string, Property][] => Object.entries(((schema as Schema | undefined)?.properties ?? {}));
+const required = (schema: JsonObject | undefined): Set<string> => new Set(((schema as Schema | undefined)?.required ?? []));
+
+// ---- what a side fills for itself
+//
+// An ask says what its arguments are, and one of them a side can answer
+// better than the human can: the moment. A being may not read a clock, since
+// a being who could would be a being who could not be moved, so she takes the
+// moment as an argument and every side hands her its own. A screen is not a
+// being; it runs on a device, and a device has a clock.
+//
+// So a property whose schema says `format: "moment"` is never drawn as a
+// field and never typed by anybody. The screen fills it, and a read-only ask
+// with nothing left to ask a human then runs on its own and shows a table
+// where a form would have been. Nothing about this is presentation, which is
+// why it is read off the input schema and not off a look: the ask says what
+// the argument is, and each side decides for itself what to do with that.
+export const MOMENT = 'moment';
+export const mine = (ask: Ask, at: number = Date.now()): JsonObject => Object.fromEntries(props(ask.input).filter(([, p]) => p.format === MOMENT).map(([name]) => [name, at]));
+// What is left for a human once the side has filled its own.
+export const asks = (ask: Ask): string[] => [...required(ask.input)].filter((name) => !(name in mine(ask)));
+
+// ---- 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: string, p: Property, must: boolean): string {
+  const id = escape(name);
+  const label = `<label for="${id}">${id}${must ? ' <b>*</b>' : ''}</label>`;
+  const help = p.description ? `<p class="nv-hint">${escape(p.description)}</p>` : '';
+  const one = (control: string) => `<div class="nv-field">${label}${control}${help}</div>`;
+  const req = must ? ' required' : '';
+  if (Array.isArray(p.enum)) {
+    // An enum value is a scalar in every schema a being writes, but the
+    // schema comes from her and not from here: an object among the options
+    // is shown as what it is rather than as `[object Object]`.
+    const text = (v: Json) => (v !== null && typeof v === 'object' ? JSON.stringify(v) : String(v));
+    const options = p.enum.map((v) => `<option value="${escape(text(v))}">${escape(text(v))}</option>`).join('');
+    return one(`<select id="${id}" name="${id}"${req}>${must ? '' : '<option value=""></option>'}${options}</select>`);
+  }
+  if (p.type === 'boolean') return `<div class="nv-field" data-inline><input type="checkbox" id="${id}" name="${id}" value="true">${label}${help}</div>`;
+  if (p.type === 'number' || p.type === 'integer') return one(`<input type="number" id="${id}" name="${id}"${p.type === 'integer' ? ' step="1"' : ' step="any"'}${req}>`);
+  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 one(`<input type="${kind}" id="${id}" name="${id}"${req}>`);
+  }
+  return one(`<textarea id="${id}" name="${id}" placeholder="JSON"${req}></textarea>`);
+}
+
+// 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: Ask, h: Hint = {}): string {
+  const must = required(ask.input);
+  const own = mine(ask);
+  const fields = props(ask.input)
+    .filter(([name]) => !(name in own)) // the side fills it; nobody types a moment
+    .map(([name, p]) => field(name, p, must.has(name)))
+    .join('');
+  const label = `${h.icon ? `${escape(h.icon)} ` : ''}${escape(h.title ?? ask.name)}`;
+  const care = h.destructive ? ' data-confirm="true"' : '';
+  const said = ask.description ? `<p class="nv-hint">${escape(ask.description)}</p>` : '';
+  return `<form class="nv-stack" data-ask="${escape(ask.name)}"${care}><fieldset><legend>${label}</legend>${said}${fields}<div class="nv-row" data-align="center"><button class="nv-button"${h.destructive ? ' data-variant="danger"' : ''}>${label}</button></div></fieldset></form>`;
+}
+
+// ---- the form heard back
+
+// What the surface hands back: every field by name, as the string the
+// browser sends. A checkbox not ticked sends nothing.
+export type Raw = Record<string, string>;
+
+// 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: Ask, raw: Raw): { args: JsonObject } | { error: string } {
+  // The side's own first, so a form the human submits carries the moment it
+  // was submitted at rather than the one the page was drawn at.
+  const args: JsonObject = mine(ask);
+  const must = required(ask.input);
+  for (const [name, p] of props(ask.input)) {
+    if (name in args) continue;
+    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) as Json;
+      } 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: Json, schema?: JsonObject): string {
+  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 as JsonObject[];
+      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 `<div class="nv-table-scroll"><table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table></div>`;
+    }
+    return value.length ? `<ul class="nv-list" role="list">${value.map((v) => `<li class="nv-item">${view(v)}</li>`).join('')}</ul>` : '<p class="nv-empty">none</p>';
+  }
+  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 `<div class="nv-table-scroll"><table>${keys.map((k) => `<tr><th>${escape(k)}</th><td>${view(value[k], (props(schema).find(([n]) => n === k)?.[1] as JsonObject | undefined))}</td></tr>`).join('')}</table></div>`;
+}
+
+// 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. The
+// word is on the answer for a design and a test to read, and the tone is
+// what a reader sees: hers in red, the wire's in amber.
+export function face(w: Word, schema?: JsonObject): string {
+  if (w.word === 'object') return `<div class="nv-answer" data-word="object">${view(w.value, schema)}</div>`;
+  if (w.word === 'error') return `<div class="nv-answer" data-word="error" data-tone="danger">${view(w.value)}</div>`;
+  if (w.word === 'silence') return `<div class="nv-answer" data-word="silence" data-tone="warning">${escape(SILENCE_TEXT)}</div>`;
+  if (w.word === 'quo') return `<div class="nv-answer" data-word="quo" data-tone="warning">${escape(wordText(w.name))}</div>`;
+  return `<div class="nv-answer" data-word="unreached" data-tone="warning">${escape(UNREACHED_TEXT)}</div>`;
+}
+
+// ---- an answer of a named kind
+
+// Rows of people: a name, a line under it, and a face when she has one, on
+// one surface. A row that is not a person is shown by its own shape, so a
+// page that said `people` of a list of strings still shows the strings.
+const person = (v: Json): string => {
+  if (v === null || typeof v !== 'object' || Array.isArray(v) || typeof v.name !== 'string') return view(v);
+  const name = v.name;
+  const line = typeof v.line === 'string' ? `<p class="nv-t-quiet">${escape(v.line)}</p>` : '';
+  const pic = typeof v.picture === 'string' && /^data:image\//.test(v.picture) ? `<img alt="" src="${v.picture}">` : escape(name.trim().charAt(0).toUpperCase());
+  return `<div class="nv-person"><span class="nv-avatar">${pic}</span><div class="nv-stack"><p class="nv-t-body">${escape(name)}</p>${line}</div></div>`;
+};
+export function people(value: Json): string {
+  if (!Array.isArray(value)) return view(value);
+  if (!value.length) return '<p class="nv-empty">nobody yet</p>';
+  return `<div class="nv-list">${value.map((v) => `<div class="nv-item">${person(v)}</div>`).join('')}</div>`;
+}
+
+// What happened, in order: a moment and the words, down a line.
+const happened = (v: Json): string => {
+  if (v === null || typeof v !== 'object' || Array.isArray(v) || typeof v.text !== 'string') return view(v);
+  const at = typeof v.at === 'string' || typeof v.at === 'number' ? `<p class="nv-t-label">${escape(String(v.at))}</p>` : '';
+  return `<div class="nv-stack">${at}<p class="nv-t-body">${escape(v.text)}</p></div>`;
+};
+export function feed(value: Json): string {
+  if (!Array.isArray(value)) return view(value);
+  if (!value.length) return '<p class="nv-empty">nothing yet</p>';
+  return `<div class="nv-feed">${value.map(happened).join('')}</div>`;
+}
+
+// ---- the page
+
+// Everything the screen shows, as data. The side keeps one of these and
+// hands it here after every change; the page is a function of it.
+export type Model = {
+  blueprint: Blueprint | null; // her describe for this human, or nothing yet
+  look: Look; // her own look, from her `look` ask, or nothing
+  tree: Node | null; // her page, from her `page` ask, or nothing: then her asks are painted as forms
+  pages: Record<string, Node | null>; // the page of each standing she carries, by id, from its carried `page` ask
+  focus?: string; // one standing she carries shown as the whole page, its id: the page at `web./<ward>/<being>`
+  at?: string; // the world's page address, so a section can say where its own page is, a focused page where back is, and an invitation answered what link it makes
+  notice: string; // one line about where the human stands: in, not in, an error before an ask
+  standing: Standing; // whether her relation is live, ended, away, or answering an error
+  answers: Record<string, Word>; // the last answer per ask, shown under its form
+  pushes: JsonObject[]; // every push from the world, newest last
+};
+
+// ---- where a human stands in a world
+//
+// A describe that does not come back says one of several things, and a
+// screen that painted them alike told a human nothing she could act on. The
+// far world removing her and the box being unreachable for a minute are the
+// same line on the page, and one of them is over while the other is not.
+//
+// So the words are read apart. `removed` and `dropped` are the relation
+// ended, and so is holding no standing at all: nothing this device does
+// brings it back, and the only act left is leaving. `unreached`, `silence`,
+// `late` and `absent` are the world being away: the standing is untouched,
+// and the next ask may well answer. Anything else she said is her error and
+// is shown as her words.
+//
+// A device never acts on this by itself. `ended` is one answer from one ask
+// at one moment, and the far world is never told and never asked, so
+// nothing can ever confirm it; a device that forgot a world on this alone
+// would delete a ward holding a seed and every standing in it on the
+// strength of one reply. It says so and offers the way out, and the human
+// presses it or does not.
+export type Standing = 'in' | 'ended' | 'away' | 'error';
+const ENDED = new Set(['removed', 'dropped', 'not joined']);
+const AWAY = new Set(['unreached', 'silence', 'late', 'absent']);
+export function standing(error: string): Standing {
+  return ENDED.has(error) ? 'ended' : AWAY.has(error) ? 'away' : 'error';
+}
+// What a human reads for one, in her own terms rather than the ward's word.
+export function stands(error: string): string {
+  switch (standing(error)) {
+    case 'ended':
+      return error === 'not joined' ? 'you are not in this world' : 'this world ended it: you are out, and nothing here reaches it';
+    case 'away':
+      return `this world cannot be reached right now, and nothing was delivered (${error})`;
+    default:
+      return `not in: ${error}`;
+  }
+}
+
+// What a human reads when a way in did not let her in. A world refuses for
+// several different reasons and a shell that said one sentence for all of
+// them sent her looking for the wrong thing. One of them has an answer and
+// is the reason this exists: `id taken` is a device of that name already in
+// this world, which is exactly what a human meets on a new device after
+// losing the one that held it, since a presence is a seed and the seed went
+// with the device. The standing it left is still there, and hers to take
+// out from any device she still holds.
+//
+// The three words it knows are the dock's own beings', the desk's and the
+// user being's, and knowing them is allowed because they ship in this
+// package beside this file: what the screen may not do is invent a word a
+// being never said, and it invents none. Any other public being falls
+// through and is quoted in her own words, so a world that answers something
+// of its own is passed on rather than guessed at. That is the whole rule,
+// and it is why there is a default branch and not a table.
+export function refused(answer: Answer): string {
+  const w = word(answer);
+  if (w.word === 'silence') return SILENCE_TEXT;
+  if (w.word === 'unreached') return UNREACHED_TEXT;
+  if (w.word === 'quo') return wordText(w.name);
+  const said = w.word === 'error' && typeof w.value.error === 'string' ? w.value.error : '';
+  switch (said) {
+    case 'id taken':
+      return 'a device of that name is already in this world. If it is one you have lost, take it out of the world from a device you still hold, or come back under another name.';
+    case 'no such user':
+      return 'this world knows nobody by that way in.';
+    case 'refused':
+      return 'that way in was refused: it may be spent, or it may never have been one.';
+    default:
+      return said ? `that way in was refused: ${said}` : 'that way in was refused.';
+  }
+}
+
+// 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: Blueprint | null, l: Look = {}): string {
+  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.
+// Her tokens become the kit's slots on her section and nowhere else: her
+// accent is the accent there, her ground the raised ground, her font the
+// sans, her radius the large corner. The kit's derived slots follow from
+// the accent in the stylesheet, so one colour of hers recolours her whole
+// section and nothing outside it.
+export function look(l: Look | undefined): { style: string; head: string } {
+  if (!l) return { style: '', head: '' };
+  const vars: string[] = [];
+  if (l.accent) vars.push(`--nv-color-accent:${l.accent}`, `--nv-color-accent-hover:${l.accent}`, `--nv-color-link:${l.accent}`);
+  if (l.background) vars.push(`--nv-color-bg-raised:${l.background}`);
+  if (l.foreground) vars.push(`--nv-color-fg:${l.foreground}`, `--nv-color-fg-body:${l.foreground}`);
+  if (l.font) vars.push(`--nv-font-sans:${l.font}`, `--nv-font-display:${l.font}`);
+  if (l.radius !== undefined) vars.push(`--nv-radius-lg:${l.radius}px`, `--nv-radius-xl:${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(all: Ask[], l: Look | undefined): Ask[] {
+  const want = l?.order ?? [];
+  return [...want.map((n) => all.find((a) => a.name === n)).filter((a): a is Ask => a !== undefined), ...all.filter((a) => !want.includes(a.name))];
+}
+
+export { hintFor };
+
+export function page(m: Model): string {
+  const bp = m.blueprint;
+  const pres = presentation(bp);
+  // An answer that is an invitation is a way in, and the only thing to do
+  // with one is to open it: painted as the link it is, on this world's page
+  // address. A being does not know where her page lives and the side does,
+  // which is why the grammar carries no URL and this is not a node.
+  const shows = (w: Word, schema?: JsonObject): string => {
+    if (w.word !== 'object' || m.at === undefined || !isInvitation(w.value)) return face(w, schema);
+    const url = link(m.at, w.value);
+    return `<div class="nv-answer" data-word="object" data-way><a class="nv-key" href="${escape(url)}">${escape(url)}</a></div>`;
+  };
+  const one =(l: Look | undefined, prefix = '') => (a: Ask) => {
+    const w = m.answers[a.name];
+    const h = hint(l, a.name.startsWith(prefix) ? a.name.slice(prefix.length) : a.name);
+    return `<section class="nv-stack">${form(a, h)}${w ? shows(w, a.output) : ''}</section>`;
+  };
+  // an answer shown as the page asks: as text, as cards, as a list, as
+  // people, as a feed, or by its shape
+  const answer = (name: string, as: As): string => {
+    const a = bp?.asks.find((x) => x.name === name);
+    const w = a ? m.answers[name] : undefined;
+    if (!a || !w) return '';
+    if (w.word === 'object' && as === 'text') return `<div class="nv-answer" data-word="object">${view(w.value === null || typeof w.value !== 'object' ? w.value : JSON.stringify(w.value))}</div>`;
+    if (w.word === 'object' && as === 'cards' && Array.isArray(w.value)) return `<div class="nv-cards">${w.value.map((v) => `<div class="nv-card">${view(v)}</div>`).join('')}</div>`;
+    if (w.word === 'object' && as === 'list' && Array.isArray(w.value)) return `<ul class="nv-list" role="list">${w.value.map((v) => `<li class="nv-item">${view(v)}</li>`).join('')}</ul>`;
+    if (w.word === 'object' && as === 'people') return people(w.value);
+    if (w.word === 'object' && as === 'feed') return feed(w.value);
+    return shows(w, a.output);
+  };
+  // ---- where a being may send a human
+  //
+  // A being names a place and the side decides whether it becomes an anchor.
+  // Two origins are vouched for and no third. The world's own, which is the
+  // origin serving this very page, so a being may move a human around inside
+  // the world she already chose. And the origins she declared in her look as
+  // the ones she stands in for, which is how an envoy speaking for a payment
+  // or a booking vendor sends a human to that vendor's own checkout.
+  //
+  // The declaration is what makes the second safe to allow. A look is asked
+  // once per digest and is the same for every answer she gives, so the
+  // places she stands in for are a standing claim rather than a destination
+  // that changes under one reply. That is what bounds the attack this rule
+  // is for: a vendor's response relayed through an envoy, carrying an
+  // address nobody here wrote. It does not bound a being who is hostile
+  // herself, and nothing on a page could; what bounds her is that a human
+  // chose to hold a standing at her.
+  //
+  // An address the side will not vouch for is painted as its own words. The
+  // human sees exactly where she was being sent, in full, and goes there by
+  // her own hand or not at all. Nothing is dropped and nothing is hidden,
+  // because a link silently deleted is a page that lies about what the being
+  // said.
+  const originOf = (s: string | undefined): string | null => {
+    if (s === undefined) return null;
+    try {
+      return new URL(s).origin;
+    } catch {
+      return null;
+    }
+  };
+  const here = originOf(m.at);
+  const linkedBy =
+    (l: Look | undefined) =>
+    (href: string, text: string): string => {
+      const origin = originOf(href);
+      if (origin === null) return escape(href);
+      const vouched = (here !== null && origin === here) || (l?.stands?.includes(origin) ?? false);
+      if (!vouched) return `<span class="nv-key link away" title="${escape(href)}">${escape(href)}</span>`;
+      // `noopener` and `noreferrer` because a page opened from here is a page
+      // the world wrote, and it is handed no window and no referer of ours.
+      // The origin is on the anchor whether or not a design shows it, so what
+      // a human is about to leave for is in the page and not only in a
+      // status bar she may never see.
+      const out = origin === here ? '' : ' out';
+      return `<a class="link${out}" href="${escape(href)}" rel="noopener noreferrer" data-origin="${escape(origin)}">${escape(text)}</a>`;
+    };
+
+  const groups = grouped(bp);
+  const taken = new Set(Object.values(groups).flatMap((g) => g.asks ?? []));
+  // A standing's section. With her page, the far tree is painted inside it
+  // through a painter of her own: a name it uses is one of her asks, carried,
+  // and never one of the carrier's or another standing's, so a far page
+  // reaches nothing outside its section; her title is the page's, and the
+  // section keeps her look. Without one, her asks are forms under her name.
+  const section = (id: string, as?: 'door'): string => {
+    const g = groups[id];
+    const inGroup = bp && g ? bp.asks.filter((a) => g.asks?.includes(a.name)) : [];
+    if (!inGroup.length) return '';
+    const kept = sanitise(g.look);
+    const l = look(kept);
+    const prefix = `${id}-`;
+    const tree = m.pages[id];
+    // where her own page is, when the world's page is known and this is not it already
+    const own = m.at !== undefined && m.focus !== id ? `<p class="nv-t-quiet"><a class="open" href="${escape(`${m.at}/${encodeURIComponent(id)}`)}">open</a></p>` : '';
+    const whole = m.focus === id ? ' data-whole' : '';
+    // A door: her name and the way to her page, and nothing of hers here.
+    // Painted whole on her own page, as any standing is.
+    if (as === 'door' && m.focus !== id) {
+      const name = kept.name ?? id;
+      const count = inGroup.length;
+      return `<section class="nv-standing" data-standing="${escape(id)}" data-door${l.style}><div class="nv-person"><span class="nv-avatar">${escape(name.charAt(0).toUpperCase())}</span><div class="nv-stack"><p class="nv-t-body">${escape(name)}</p><p class="nv-t-quiet">${count} ${count === 1 ? 'thing' : 'things'} to do here, on its own page</p></div></div>${own}</section>`;
+    }
+    if (tree) {
+      const hers: Painter = {
+        form: (name) => {
+          const a = inGroup.find((x) => x.name === prefix + name);
+          return a ? one(kept, prefix)(a) : '';
+        },
+        answer: (name, as) => (inGroup.some((x) => x.name === prefix + name) ? answer(prefix + name, as) : ''),
+        link: linkedBy(kept), // a carried standing vouches by her own look and never her carrier's
+        standing: () => '',
+        standings: () => '',
+      };
+      return `<section class="nv-standing" data-standing="${escape(id)}"${whole}${l.style}>${paint(tree, hers)}${own}</section>`;
+    }
+    const want = (kept.order ?? []).map((n) => prefix + n);
+    const inOrder = ordered(inGroup, { order: want });
+    return `<section class="nv-standing" data-standing="${escape(id)}"${whole}${l.style}>${l.head || `<h2>${escape(id)}</h2>`}${inOrder.map(one(kept, prefix)).join('')}${own}</section>`;
+  };
+  const far = Object.keys(groups).map((id) => section(id)).join('');
+  // Her page, when she answered one: painted from her tree, each name it
+  // uses looked up in her describe, so a page shows nothing her gate hid.
+  const painter: Painter = {
+    form: (name) => {
+      const a = bp?.asks.find((x) => x.name === name && !taken.has(x.name) && !pres.has(x.name));
+      return a ? one(m.look)(a) : '';
+    },
+    answer: (name, as) => (pres.has(name) ? '' : answer(name, as)),
+    link: linkedBy(m.look),
+    standing: section,
+    standings: () => far,
+  };
+  const mineAsks = bp ? ordered(bp.asks.filter((a) => !taken.has(a.name) && !pres.has(a.name)), m.look).map(one(m.look)).join('') : '';
+  // A being's page: one standing she carries as the whole page, and nothing of hers around it. A key her
+  // describe does not carry paints as nothing, the way a name on a page does: the address adds no right.
+  const focused = m.focus !== undefined;
+  const body = focused ? section(m.focus!) : m.tree ? paint(m.tree, painter) : `<div class="nv-stack">${mineAsks}${far}</div>`;
+  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;
+  // her notes are shown beside her forms when she has no page: a being with
+  // a page says everything she wants said, and a note is wiring
+  const notes = bp && !m.tree && shown !== null && shown !== undefined && !(typeof shown === 'object' && !Array.isArray(shown) && !Object.keys(shown).length) ? `<aside class="nv-answer notes">${view(shown)}</aside>` : '';
+  const pushes = m.pushes.length ? `<section class="nv-stack pushes"><p class="nv-t-label">pushes</p><div class="nv-feed">${m.pushes.map((p) => `<div>${view(p)}</div>`).join('')}</div></section>` : '';
+  const styled = look(m.look);
+  // A name is said once. A page that opens with a title of its own is the
+  // name, and the bar keeps only where the human stands; a being painted
+  // as forms has no page to say it, so the bar says her name; a focused
+  // page says the way back and the standing's own tree says the rest.
+  const back = focused && m.at !== undefined ? `<a class="back" href="${escape(m.at)}">${escape(title(bp, m.look))}</a>` : '';
+  const said = focused ? (m.pages[m.focus!] ? titled(m.pages[m.focus!]) : false) : titled(m.tree);
+  const head = focused ? back : m.tree && said ? '' : `${m.look.logo ? `<img class="logo" alt="" src="${m.look.logo}">` : ''}<h1>${escape(title(bp, m.look))}</h1>`;
+  // The notice carries where she stands, so a design and a reader can tell
+  // a relation that ended from a world that is merely away without parsing
+  // a sentence; the chip's tone is that word.
+  const tone = m.standing === 'ended' || m.standing === 'error' ? 'danger' : m.standing === 'away' ? 'warning' : 'success';
+  // `data-page` is the one hook that is not the design's: a class here would
+  // be a livery's name, and a livery is worn and swapped. The door marks
+  // itself `data-door` for the same reason, and between them anything
+  // outside can say which of the two it is looking at.
+  return `<header class="nv-bar"${styled.style}>${head}<p class="nv-chip notice" data-standing="${m.standing}" data-tone="${tone}">${escape(m.notice)}</p></header>${focused ? '' : notes}<main data-page${focused ? ' class="focus"' : ''}${styled.style}>${body}</main>${pushes}`;
+}