@quo-systems/dock 0.2.0 → 0.2.2

package/harbor/quo.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// The quo. route: the socket door, served by the daemon under `/quo` and
+// mapped by the proxy from the quo. hostname, so a URL of that route is the
+// base of every reach. POST `/quo/<pk>` carries one ask to a pk this harbor
+// holds or holds a socket for; an upgrade at `/quo` is a dialer's held
+// socket, announcing its pks to be bound. Bytes from here go to an own door
+// or a held socket, never onward. The listener half of the socket reach is
+// the terrain's own, `ws` on Node, and lives here with it.
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { Socket as Held, SUITE, type Line } from '@quo-systems/quo/harbor';
+import type { DiskHarbor } from './disk.ts';
+import { readAll, type Handler, type Quo } from '../cli/http.ts';
+
+export function quoRoute(harbor: DiskHarbor, server: HttpServer, quo: Quo): Handler {
+  const pks = () => [...harbor.doors.keys()];
+  const wss = new WebSocketServer({ noServer: true });
+  server.on('upgrade', (req: IncomingMessage, socket, head) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname.replace(/\/$/, '') !== '/quo') return void socket.destroy(); // the proxy rewrites the route root to /quo/
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      const s: Held = new Held(
+        ws as unknown as Line,
+        (pk, bytes) => harbor.deliver(pk, bytes),
+        (far) => void harbor.bind(far, s, true), // a dialer's claims, each proven at its door: held here, reachable through this socket
+        () => {
+          harbor.unbind(s);
+          quo.sockets.delete(s);
+        },
+      );
+      quo.sockets.add(s);
+      s.announce(pks());
+    });
+  });
+  // The route is public and carries sealed bytes, so any origin may POST
+  // to it: a tab on a world's web. reaching another world's quo. is the
+  // ordinary case, and a binary POST needs the preflight answered.
+  const open = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'POST, OPTIONS', 'access-control-allow-headers': 'content-type, quo-suite' };
+  return async (req, res, rest) => {
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, open);
+      return void res.end();
+    }
+    // The wire suite the caller speaks. Absent is this one, because a caller
+    // older than the header is this one. Anything else this door cannot open
+    // and says so as nothing delivered, rather than taking bytes that will
+    // never open and answering a silence that names no reason.
+    const suite = req.headers['quo-suite'];
+    if (suite !== undefined && suite !== String(SUITE)) {
+      res.writeHead(404, { 'content-type': 'application/json', ...open });
+      return void res.end(JSON.stringify({ error: `this door speaks wire suite ${SUITE}` }));
+    }
+    const pk = rest.slice(1);
+    if (req.method !== 'POST' || !/^[0-9a-f]{128}$/.test(pk)) {
+      res.writeHead(404, { 'content-type': 'application/json', ...open });
+      return void res.end(JSON.stringify({ error: 'POST /quo/<pk>' }));
+    }
+    const raw = await readAll(req as AsyncIterable<Buffer>);
+    const back = raw === undefined ? undefined : await harbor.deliver(pk, new Uint8Array(raw));
+    if (back === undefined) {
+      res.writeHead(404, { 'content-type': 'application/json', ...open });
+      return void res.end(JSON.stringify({ error: 'no reach for that pk' }));
+    }
+    res.writeHead(200, { 'content-type': 'application/octet-stream', ...open });
+    res.end(Buffer.from(back));
+  };
+}

package/human/door.ts

@@ -0,0 +1,26 @@
+// 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 look, or
+// its own page on its own origin; this is the default and nothing more.
+// Pure, strings in and strings out, under the tab's policy: no script, no
+// image that is not a data URI, styles from the one stylesheet.
+import { escape } from './html.ts';
+
+// The mark: a ring with a gap, one being's voice reaching another's door.
+const MARK =
+  'data:image/svg+xml;base64,' +
+  btoa(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" stroke="currentColor" stroke-width="4" stroke-linecap="round"><circle cx="32" cy="32" r="22" stroke-dasharray="110 30" transform="rotate(-60 32 32)"/><circle cx="32" cy="32" r="5" fill="currentColor" stroke="none"/></svg>`,
+  );
+
+export type Door = { world?: string; host: string };
+
+export function door(at: Door): string {
+  const where = at.world ? `<p class="where">${escape(at.world)} <span>at ${escape(at.host)}</span></p>` : `<p class="where">${escape(at.host)}</p>`;
+  return `<main class="door"><img class="mark" alt="" src="${MARK}"><h1>quo</h1>${where}<p class="lead">${at.world ? 'This world is entered by invitation.' : 'The worlds here are entered by invitation.'}</p><p>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.</p><p class="quiet">Nothing on this page asks anything of you. If you were sent here without a link, ask the person who sent you for one.</p></main>`;
+}

package/human/guest.ts

@@ -0,0 +1,26 @@
+// 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';
+import type { Answer, Blueprint, Invitation, JsonObject, Wanted } from '@quo-systems/quo';
+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

@@ -11,6 +11,7 @@
 //   page(model)           the whole page: title, notice, forms, views, pushes
 import type { Ask, Blueprint, Json, JsonObject } from '@quo-systems/quo';
 import { SILENCE_TEXT, UNREACHED_TEXT, wordText, type Word } from '../beings/side.ts';
+import { hint, hintFor, sanitise, groups as grouped, type Look, type Hint } from '../beings/look.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 };
@@ -47,12 +48,14 @@ export function field(name: string, p: Property, must: boolean): string {
 
 // 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): string {
+export function form(ask: Ask, h: Hint = {}): string {
   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 form heard back
@@ -136,6 +139,7 @@ export function face(w: Word, schema?: JsonObject): string {
 // 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
   notice: string; // one line about where the human stands: in, not in, an error before an ask
   answers: Record<string, Word>; // the last answer per ask, shown under its form
   pushes: JsonObject[]; // every push from the world, newest last
@@ -143,22 +147,66 @@ export type Model = {
 
 // 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): string {
+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.
+export function look(l: Look | undefined): { style: string; head: string } {
+  if (!l) return { style: '', head: '' };
+  const vars: string[] = [];
+  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: Ask[], l: Look | undefined): Ask[] {
+  const want = l?.order ?? [];
+  return [...want.map((n) => asks.find((a) => a.name === n)).filter((a): a is Ask => a !== undefined), ...asks.filter((a) => !want.includes(a.name))];
+}
+
+export { hintFor };
+
 export function page(m: Model): string {
   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: 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>${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 as Json)}</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/human/quo-human.md

@@ -1,86 +1,177 @@
 # The human side
 
 This is how a Quo world speaks to a human, and how a human speaks back. It
-is one side of the avatar described in `packages/dock/beings/quo-dock.md`, which
-owns the avatar, the front desk, the credential exchange and the shared
-invariants; this document assumes all of that and adds only what a screen
-needs. It names no transport and no model. A tab is a device with a harbor
-of its own, and where its bytes go is `packages/dock/harbor/quo-harbor.md`.
+is one side of the avatar described in `packages/dock/beings/quo-dock.md`,
+which owns the avatar, the front desk, the credential exchange, carrying,
+the look and the shared invariants; this document assumes all of that and
+adds only what a screen needs. It names no transport and no model. A tab is
+a device with a harbor of its own, and where its bytes go is
+`packages/dock/harbor/quo-harbor.md`.
 
-The claim it will make good on: a human needs no page written for them. A
-screen is a blueprint spoken as HTML. The user being's describe for this
-asker becomes the forms the human sees, a submitted form becomes a named
-ask, an answer becomes a view, a push becomes a notification, and the three
-words for "no object" each have a face. Nothing the screen shows exists
-anywhere but in a blueprint, so every world gets a screen for free and no
-world gets a screen it did not describe.
+The claim, made good on: a human needs no page written for them. A screen
+is a blueprint spoken as HTML. A being's describe for this asker becomes the
+forms the human sees, a submitted form becomes a named ask, an answer
+becomes a view, a push becomes a notification, and the three words for "no
+object" each have a face. Nothing the screen shows exists anywhere but in a
+blueprint and a look, so every world gets a screen for free and no world
+gets a screen it did not describe.
 
-What this document decides, in its own sitting:
+Three sides, one describe. The CLI, the model side and the screen are three
+views of the same beings, and the screen adds no vocabulary of its own:
+what a being can be asked is her blueprint, how she wants to be shown is
+her `look`, and both are values that travel through the relation. A world
+that wants a page of its own writes any HTML, CSS and JavaScript it likes on
+its own origin, against the avatar's handles and nothing else; a world that
+writes none gets this screen.
 
-- how a JSON Schema input becomes a form without a designer;
-- how an output schema, and an answer, become a view;
-- what the blueprint's notes may carry as rendering hints without becoming
-  state, and what they may never carry;
-- how a standing is a page, and a digest change is a refreshed page;
-- how the same screen is a guest one minute and an occupant the next, and
-  what the human sees at each of the three words;
-- how a native app shows many worlds: one screen per ward, a switcher
-  between them, and the device's own beings offered to each through gates;
-- what one avatar class, one `side` implementation and one suite look like
-  for a screen, proven on the memory harbor with no browser at all.
+## How a screen is made
 
-Until that sitting, the only rule in force is the one law from the trunk:
-the human is an occupant, reached through an avatar, seeing what the gate
-shows.
+Read with the trunk's "Carrying" and "The look", which this applies.
 
-## The screen today, minimal on purpose
+- **A form from a schema, without a designer.** An input schema is a form
+  with one field per property by type: a string is a text input, and
+  `password`, `date`, `email` and `time` are the input's type; a number is a
+  number input; a boolean a checkbox; an enum a select; an object or an
+  array a box for JSON. The submitted strings come back as arguments typed by
+  the schema, an empty optional field left out. A hint from her look puts a
+  title and an icon on the button and marks a destructive ask.
+- **A view from an answer.** A primitive is text, an object a table of its
+  keys in the output schema's order when she declared one, a list of objects
+  one table, null the word nothing. An error object is marked; silence and
+  each of the ward's words say what the side says of them.
+- **A standing is a section.** The user being carries her standings, and
+  her notes say which asks are whose. The page draws her own asks first,
+  then one section per standing, headed by that being's name and logo and
+  painted with her tokens as CSS variables on that section and nowhere
+  else. A form in acme's section is an ask on the human's standing at acme,
+  and acme sees the human, never the device. The same section appears on
+  acme's own web, under the same look: one component, two relations.
+- **The page follows the digest.** The side asks the describe again after
+  every call and asks `look` once per digest; a digest that moved is a page
+  that moved. A read-only ask with nothing to type is run on open, so a page
+  can open with what it shows and not only with buttons. Every one of those
+  asks rotates her keys, so the side saves after each, not only after a
+  form: a relation brought back from a reload with a stale count is refused
+  at the far door and hears silence.
+- **What a look may carry, and never.** The trunk's table is the whole
+  list: a name, a logo as a data URI, three colours, a font, a radius, an
+  order, a hint per ask. No CSS, no URL, no script, ever. A token that fails
+  its shape is dropped. The page owns layout, typography and its own
+  palette; a far being paints inside her section and cannot reach out of it.
+- **The tab shell.** One stylesheet honouring the variables, light and dark,
+  served by the daemon beside the bundle. Nothing else is designed.
+- **A world is a ward with a public being, and the guest page is her
+  describe.** Whatever class she is. The tab knocks the ward's public
+  invitation, its pk alone, with the empty ask, and renders what she shows
+  strangers with this same screen: the desk shows `hello` and `device`, a
+  shop could show its availability, a garden its `enter`. A form on that
+  page is a knock on the public invitation, and an answer that is an
+  invitation is the way in: the side hands it to `admit`, the avatar joins,
+  and the page becomes hers. Nothing in the screen knows the word desk.
+- **Worlds have addresses.** `web./<ward>` is that world's page, `web./`
+  lists the worlds, and a hostname per world is one proxy line, the
+  estate's choice. `quo.` stays one per harbor, since bytes route by pk.
+- **A link is the page with the invitation in the fragment**, under the one
+  reserved key `quo`, the invitation compact as `ward.heir.secret` or
+  `ward` alone: `web.acme.com/shop#quo=...`. The fragment never leaves the
+  browser, where a query string would reach the server, its logs and every
+  referer. The tab reads it, strips it from the address bar before anything
+  else runs, and joins. A page's own routing keeps the query, the path and
+  the rest of the fragment; only `quo` is taken. `beings/link.ts`.
+- **An invitation is self-addressing.** It names its ward by pk, so the
+  path of the page it was opened on is a hint for humans and nothing more:
+  the tab joins in the local ward of the ward the invitation names, and
+  the address follows. `web./#quo=...` is a complete way in for anyone
+  holding an invitation to any ward the harbor hosts, and every ward has a
+  page, whether or not anyone is at its door, so that a link into one has
+  somewhere to land; a ward with no public being says it admits by
+  invitation only.
+- **The tab is a browser of worlds, and of the relations in each.** One
+  harbor per origin, one local ward per world joined, and inside it one
+  avatar per relation, since an avatar is one standing: a fresh invitation
+  is always a fresh avatar, never a join on one that already holds hers. A
+  link opened while in is one more relation; two humans on one family
+  tablet are two relations in one world; a switcher over worlds and
+  another over relations, and a switch is a switch of avatar and nothing
+  more. A world on another origin is another page, and the switcher links
+  there. `worlds.ts` is this without a document, and the memory harbor
+  proves it.
+- **The policy.** The page carries a content security policy: scripts from
+  its origin only and never inline, connections to its origin and the `quo.`
+  route it dials, images from data URIs and its origin, no frames, no base.
+  The config crosses in a JSON script, which the policy allows. A bug in a
+  renderer cannot become a script, and no look can reach a server.
 
-The sitting above has not happened. What stands is the least screen that
-speaks a blueprint as HTML with no page written for any world, so that the
-rest of the dock is not held up by a design. Three pieces under
-`packages/dock/human/`, and the tab that holds them:
+## The pieces
+
+Eight files under `packages/dock/human/`:
 
 - `html.ts` is pure, strings in and strings out, and is the screen's whole
-  vocabulary. An input schema is a form with one field per property by
-  type: a string is a text input, and `password`, `date`, `email` and
-  `time` are 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.
-  The submitted strings come back as arguments typed by the schema, an
-  empty optional field left out. An answer is a view: a primitive is text,
-  an object a table of its keys in the output schema's order when she
-  declared one, a list of objects one table, null the word nothing. The
-  three words for "no object" each have a face, an error object marked,
-  silence and each of the ward's words saying what the side says of them.
-  The notes may carry one hint, a string `name` that titles the page; the
-  rest is shown as a view and read as nothing else.
+  vocabulary: `form`, `values`, `view`, `face`, `look`, `page`. It reads the
+  look's vocabulary from `beings/look.ts` and adds none.
 - `screen.ts` is the side: one avatar and one surface, where a surface can
-  only show a page and hand back a submitted form. The side keeps the
-  model, speaks it as a page after every change, calls her when a form
-  comes back, and re-asks her describe after every call, so a digest that
-  moved is a page that moved. A push is appended and shown as it lands. A
-  describe that fails leaves the last page standing and says so in the
-  notice.
+  only show a page and hand back a submitted form. It keeps the model,
+  speaks it as a page after every change, calls her when a form comes back,
+  re-asks her describe after every call, asks her look once per digest, and
+  runs her read-only asks on open. A push is appended and shown as it
+  lands. A describe that fails leaves the last page standing and says so in
+  the notice.
 - `dom.ts` is the surface on an element, the one file that touches one.
-- `tab.ts` is the harbor in the tab and the exchange, unchanged from the
-  first screen, and hands the avatar to the side.
+- `guest.ts` is a world's public being as a subject the screen renders:
+  her describe for a stranger, a form as a knock on the public invitation.
+- `worlds.ts` is the tab's worlds and relations with no document in
+  sight: the local ward for a far pk, the relations in it, and a fresh
+  avatar for the next way in.
+- `door.ts` is the door page, pure: what a stranger sees where nothing
+  lets them in, Quo's page and not the estate's, asking for nothing.
+- `tab.ts` is the shell: the harbor in the tab, the config, the two
+  switchers and the two ways in, and hands one avatar at a time to the
+  side.
+- `web.ts` is the web route the daemon mounts under `/web`: the list of
+  worlds or the door page at the root, a world's page with its config, the
+  bundle built from `tab.ts`, the policy header and the stylesheet. It
+  authenticates nothing and admits nobody; the knock is the tab's. Paths
+  it does not take fall through to the exchange pages.
 
 Proven in `packages/dock/test/human.test.ts` on the memory harbor with a fake
-surface and no browser, and in `packages/dock/test/terrain/browser.test.ts` in a
-real Chromium against a daemon on loopback, behind `npm run check:terrain`.
+surface and no browser: the user being carrying a shop with a look, a guest
+at a door that is not a desk let in by a form, the link read, stripped and
+refused, and the worlds and relations on a harbor core over the memory
+store, two invitations into one world being two avatars; and in
+`packages/dock/test/terrain/browser.test.ts` in a real Chromium against a
+daemon on loopback, behind `npm run check:terrain`: the guest page, the
+way in by a link the root minted, a push, a reload, the policy header, a
+link while in as a second relation and the switch back, a link into another
+ward landing on that ward's page, the door page where nobody is at the
+door, and a link at the root.
+
+## Security, by structure
 
-What it leaves to the sitting above, deliberately: any design, a switcher
-between worlds, the guest's page before the exchange, the native app, and
-every rendering hint beyond `name`. None of it blocks a world from having
-a screen today.
+- Nothing executable crosses. What a screen receives is I-JSON, by the
+  spec: asks, args, answers, the three words, and a look. Every string is
+  escaped before it is written into the page; a JSON box is parsed and never
+  evaluated.
+- A look is a closed vocabulary held to shapes. A logo is a data URI, so no
+  request leaves the page towards a far being's server; a colour is a hex
+  colour; there is no token for a stylesheet, a URL or a script.
+- The gate is the permission. What a page can ask is what the being shows
+  that device, already. No page adds a right, and a form for an ask she does
+  not show is nothing.
+- Origin is the boundary. A world's own page runs only on that world's
+  origin; on the human's own web only the dock's bundle and the estate's
+  classes run. A world can only ever damage itself.
 
 ## The tab
 
-The tab is a device. The page boots a browser harbor on a seed minted into
-the tab's store the first time, one ward with one avatar in it, and dials
-the world's `quo.` route. The exchange happens once: the owner password
-goes to `/tab/login`, which answers a nonce and the ward pk, and the
-avatar in the tab knocks the front desk over the socket with the nonce
-under the `tab` proof kind, is handed the invitation the user being minted,
-and joins her. From then on there is no cookie and no token anywhere, and
-a reload asks nothing: the seed and the standing are in the tab's store.
-Live on the lab at `web.lab.quo.systems/tab`.
+The tab is a device. The page at `web./<ward>` boots a browser harbor on a
+seed minted into the tab's store the first time, one local ward for this
+world with an avatar per relation in it, and dials the world's `quo.`
+route. Two ways in, one act, each a fresh avatar: a link's invitation,
+joined at once in the ward it names; and a guest form on the public being's
+page whose answer is an invitation. Nothing is typed to get in, no password
+and no account, the root included: the root mints its own first invitation
+on the box and opens the link. 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, and a reload asks nothing: the seed and the
+standings are in the tab's store, and the relation last on screen is the
+one shown.

package/human/screen.ts

@@ -8,9 +8,13 @@
 // moved. A push is appended and shown the moment it lands.
 import { digest } from '@quo-systems/quo';
 import type { Blueprint, JsonObject } from '@quo-systems/quo';
-import type { Avatar } from '../beings/avatar.ts';
-import { word, type Serving } from '../beings/side.ts';
-import { page, values, type Model, type Raw } from './html.ts';
+import { word, type Serving, type Subject } from '../beings/side.ts';
+import { isInvitation } from '../beings/link.ts';
+import type { Invitation } from '@quo-systems/quo';
+import { page, values, hintFor, type Model, type Raw } from './html.ts';
+import { sanitise } from '../beings/look.ts';
+import { isSilence, isWord } from '@quo-systems/quo';
+import type { Json } from '@quo-systems/quo';
 
 export type Surface = {
   show(html: string): void;
@@ -19,10 +23,19 @@ export type Surface = {
   onSubmit: ((ask: string, raw: Raw) => void) | undefined;
 };
 
-// `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: Avatar, surface: Surface, after: () => Promise<void> = async () => {}, notice = ''): Promise<Serving & { model: Model; refresh(): Promise<void> }> {
-  const model: Model = { blueprint: null, notice, answers: {}, pushes: [] };
+// `after` runs after every ask the side makes, a submitted form, her
+// describe, her look and the read-only asks run on open alike, as it does
+// for the model side: every ask rotates her keys, and a harbor that must
+// write what the ward changed hooks it. A side that saved only after a form
+// would bring her back from a reload with a stale count, and the far door
+// would refuse her. `admit` is what to do
+// with an answer that is an invitation: a guest at a world's door is let in
+// by it, and a side with no `admit` shows it as any answer.
+export type Options = { after?: () => Promise<void>; notice?: string; admit?: (invitation: Invitation) => Promise<void> };
+export async function screenSide(avatar: Subject, surface: Surface, options: Options = {}): Promise<Serving & { model: Model; refresh(): Promise<void> }> {
+  const after = options.after ?? (async () => {});
+  const notice = options.notice ?? '';
+  const model: Model = { blueprint: null, look: {}, notice, answers: {}, pushes: [] };
   let seen: string | null = null;
   const show = () => surface.show(page(model));
 
@@ -39,8 +52,19 @@ export async function screenSide(avatar: Avatar, surface: Surface, after: () =>
         seen = d;
         model.blueprint = bp as Blueprint;
         for (const k of Object.keys(model.answers)) if (!(bp as Blueprint).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 as Blueprint).asks.some((a) => a.name === 'look')) {
+          const l = await avatar.call('look');
+          model.look = isSilence(l) || isWord(l) ? {} : sanitise(l as Json);
+        } 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 as Blueprint).asks) {
+          const needs = ((a.input as { required?: string[] }).required ?? []).length > 0;
+          if (hintFor(bp as Blueprint, model.look, a.name).readOnly && !needs && !(a.name in model.answers)) model.answers[a.name] = word(await avatar.call(a.name, {}));
+        }
       }
     }
+    await after();
     show();
   };
 
@@ -53,8 +77,10 @@ export async function screenSide(avatar: Avatar, surface: Surface, after: () =>
       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();
   };