@quo-systems/dock 0.1.0 → 0.2.1

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,143 @@
 # 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.
+## What the twelfth sitting decided
 
-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 it 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.
+- **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`.
+- **The tab is a browser of worlds.** One harbor per origin, one ward per
+  world joined, each on the tab's seed with one avatar, and a switcher over
+  them. A world on another origin is another page, and the switcher links
+  there.
+- **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
+
+Three files under `packages/dock/human/`, and the tab that holds them:
 
 - `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.
+- `tab.ts` is the harbor in the tab, the worlds and the three ways in, and
+  hands the avatar to the side.
 
 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, and the link read, stripped
+and refused; 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 password way in, a push, a reload, and the policy header.
+
+## 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
+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 ward for this world
+with one avatar in it, and dials the world's `quo.` route. Three ways in,
+one act: a link's invitation, joined at once; a guest form on the public
+being's page whose answer is an invitation; and, when the desk is at the
+door, the dock's own way, the owner password to `web./<ward>/login` for a
+nonce, and the desk's `device` form submitted with it under the `tab` proof
+kind. A tab opened with the owner password reaches what she holds, since the
+owner opened it. 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`.
+Live on the lab at `web.lab.quo.systems/main`.

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;
@@ -20,9 +24,14 @@ export type Surface = {
 };
 
 // `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: [] };
+// that must write what the ward changed hooks it. `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,6 +48,16 @@ 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, {}));
+        }
       }
     }
     show();
@@ -53,8 +72,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();
   };
 

package/human/tab.ts

@@ -1,23 +1,58 @@
 // SPDX-License-Identifier: Apache-2.0
-// The tab: a page in a tab that is a world. The tab boots a browser harbor
-// on a seed minted into IndexedDB the first time, a ward with one avatar in
-// it, and dials the world's quo. route. The exchange, once: the owner
-// password goes to the web route, which mints a nonce the desk honours
-// under the `tab` proof kind; the avatar in the tab knocks the desk over the
-// socket with it, joins the user being, and from then on there is no cookie
-// and no token anywhere. The second time the page opens, she already holds
-// `user` and nothing is asked.
+// 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 keeps one ward per world it has joined, each with one avatar, so the
+// tab is a browser of worlds: a switcher between them is a switch of ward
+// and nothing more. It dials the world's quo. route.
 //
-// The screen itself is the human side in `screen.ts` over the DOM surface
-// in `dom.ts`: her describe as forms, an answer as a view, a push on the
-// page. This file is the harbor and the exchange, and hands her over.
-import type { Invitation } from '@quo-systems/quo';
+// Three ways in, all the same act, a knock that ends in a standing:
+//
+//   a link      the page with the invitation in its fragment, `#quo=...`,
+//               read and stripped before anything else runs, then joined.
+//   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.
+//   a password  the dock's own way, when the public being shows `device`:
+//               the owner password goes to the web route for a nonce the
+//               front desk honours under the `tab` proof kind, and the
+//               guest form `device({ proof })` is submitted for the human.
+//
+// From then on there is no cookie and no token anywhere; the seed and the
+// standing 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 harbor, the worlds and the ways in, and hands the avatar over.
+import type { Invitation, JsonObject } from '@quo-systems/quo';
 import { BrowserHarbor } from '../harbor/browser.ts';
 import { Avatar, USER } from '../beings/avatar.ts';
+import { parse, strip, isInvitation } from '../beings/link.ts';
 import { screenSide } from './screen.ts';
 import { domSurface } from './dom.ts';
+import { guest } from './guest.ts';
+import { escape } from './html.ts';
+
+// What the page is told by the daemon that served it: the world's routes,
+// this ward's name on that harbor, and its pk.
+export type Config = { quo: string; web: string; ward: string; pk: string };
 
-export type Config = { quo: string; web: string };
+// The worlds this tab has joined, by pk: where each lives and what it is
+// called, kept beside the harbor so the switcher can list them. A world on
+// another origin is another page, and the switcher links to it.
+type Worlds = Record<string, { url: string; name: string }>;
+const WORLDS = 'quo-worlds';
+const worlds = (): Worlds => {
+  try {
+    return JSON.parse(localStorage.getItem(WORLDS) ?? '{}') as Worlds;
+  } catch {
+    return {};
+  }
+};
+const remember = (pk: string, url: string, name: string) => {
+  try {
+    localStorage.setItem(WORLDS, JSON.stringify({ ...worlds(), [pk]: { url, name } }));
+  } catch {
+    /* a tab with no storage still works, and forgets */
+  }
+};
 
 const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Record<string, string> = {}): HTMLElementTagNameMap[K] => {
   const e = document.createElement(tag);
@@ -27,58 +62,125 @@ const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Rec
 };
 
 export async function start(cfg: Config, root: HTMLElement = document.body): Promise<void> {
+  // The link, first and once: the invitation leaves the address bar before
+  // any other code sees it.
+  const linked = parse(location.hash);
+  if (linked) history.replaceState(null, '', location.pathname + location.search + strip(location.hash));
+
+  const nav = el('nav', '', { class: 'worlds' });
   const status = el('p', 'booting');
   const screen = el('div');
-  root.append(status, screen);
+  root.append(nav, status, screen);
   const say = (s: string) => (status.textContent = s);
 
-  // The harbor in the tab: one database, one ward, one avatar, for good.
+  // The harbor in the tab: one database per origin, one ward per world.
   const harbor = new BrowserHarbor('quo');
   await harbor.boot();
-  const main = harbor.wards.get('main') ?? (await harbor.create('main', 'me'));
-  if (!main.being('me')) await main.ask('boot', { key: 'me', class: 'Avatar' });
-  const me = main.being('me') as Avatar;
+  const name = `w-${cfg.pk.slice(0, 16)}`;
+  const ward = harbor.wards.get(name) ?? (await harbor.create(name, 'me'));
+  if (!ward.being('me')) await ward.ask('boot', { key: 'me', class: 'Avatar' });
+  const me = ward.being('me') as Avatar;
   harbor.dial(cfg.quo);
 
-  // The screen: every call rotates her keys and a same-ward ask never
+  const switcher = () => {
+    nav.replaceChildren();
+    const known = worlds();
+    for (const [pk, w] of Object.entries(known)) {
+      const a = el('a', w.name || pk.slice(0, 8), { href: w.url });
+      if (pk === cfg.pk) a.setAttribute('aria-current', 'page');
+      nav.append(a);
+    }
+    const here = worlds()[cfg.pk];
+    if (!here) nav.append(el('span', `${cfg.ward} at ${new URL(cfg.web).host}`));
+  };
+  switcher();
+
+  // Joined: her page. Every call rotates her keys and a same-ward ask never
   // crosses the harbor, so the side saves after each one.
-  const show = async (notice: string) => {
+  const inside = async (notice: string) => {
     status.remove();
-    await screenSide(me, domSurface(screen), () => main.save(), notice);
+    screen.replaceChildren();
+    const side = await screenSide(me, domSurface(screen), { after: () => ward.save(), notice });
+    remember(cfg.pk, location.origin + location.pathname, side.model.look.name || (typeof (side.model.blueprint?.notes as JsonObject | null)?.name === 'string' ? ((side.model.blueprint!.notes as JsonObject).name as string) : cfg.ward));
+    switcher();
   };
 
-  // Already in: reconnect, nothing minted.
-  const had = await me.tools();
-  if ('asks' in had) return show('in, as before');
-
-  // The exchange, once: the owner password for a nonce, the nonce for an
-  // invitation the user being mints, the invitation for a standing.
-  const form = el('form');
-  const identity = el('input', '', { name: 'identity', value: 'tab', placeholder: 'identity' });
-  const password = el('input', '', { name: 'password', type: 'password', placeholder: 'owner password' });
-  const go = el('button', 'enter');
-  form.append(identity, password, go);
-  root.insertBefore(form, screen);
-  say(`not in (${had.error}): the owner password opens the world`);
-  form.onsubmit = async (ev) => {
-    ev.preventDefault();
-    say('asking the world');
-    let res: Response;
-    try {
-      res = await fetch(`${cfg.web}/tab/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: password.value, identity: identity.value }) });
-    } catch (e) {
-      return say(`the world did not answer: ${(e as Error).message}`);
-    }
-    if (!res.ok) return say(`refused: ${(await res.json().catch(() => ({ error: res.status })) as { error?: string }).error ?? res.status}`);
-    const { nonce, ward } = (await res.json()) as { nonce: string; ward: string };
-    password.value = '';
+  // The way in, from any of the three: join, save, and be inside.
+  const admit = async (inv: Invitation, notice: string) => {
     say('knocking');
-    const got = await me.enter({ ward } as Invitation, { kind: 'tab', nonce });
-    await main.save(); // the knock went through her own door, which the harbor never sees
-    if (!('asks' in got)) return say(`not in: ${got.error}`);
-    form.remove();
-    await show(`in, as ${identity.value}`);
+    const got = await me.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;
+    }
+    await inside(notice);
   };
+
+  // Already in: reconnect, nothing minted.
+  if (me.standings[USER]) {
+    const had = await me.tools();
+    if ('asks' in had) return inside('in, as before');
+    say(`not in (${had.error})`);
+  }
+  if (linked) return admit(linked, 'in, by the link');
+
+  // A guest: the public being's describe as a page; a form whose answer is
+  // an invitation lets the guest in.
+  say(`at the door of ${cfg.ward}`);
+  const door = guest(me, cfg.pk);
+  const side = await screenSide(door, domSurface(screen), {
+    after: () => ward.save(),
+    notice: `a guest at ${cfg.ward}: what she shows strangers`,
+    admit: async (inv) => {
+      await side.close();
+      await admit(inv, `in, as a guest of ${cfg.ward}`);
+    },
+  });
+
+  // The dock's own way in, when the desk is at the door: the owner password
+  // for a nonce, and the desk's `device` form submitted with it.
+  if (side.model.blueprint?.asks.some((a) => a.name === 'device')) {
+    const form = el('form', '', { class: 'password' });
+    const identity = el('input', '', { name: 'identity', value: 'tab', placeholder: 'identity' });
+    const password = el('input', '', { name: 'password', type: 'password', placeholder: 'owner password' });
+    const go = el('button', 'enter as the owner');
+    form.append(identity, password, go);
+    root.insertBefore(form, screen);
+    form.onsubmit = (ev) => {
+      ev.preventDefault();
+      void (async () => {
+        say('asking the world');
+        let res: Response;
+        try {
+          res = await fetch(`${cfg.web}/${encodeURIComponent(cfg.ward)}/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: password.value, identity: identity.value }) });
+        } catch (e) {
+          say(`the world did not answer: ${(e as Error).message}`);
+          return;
+        }
+        password.value = '';
+        if (!res.ok) {
+          say(`refused: ${((await res.json().catch(() => ({ error: res.status }))) as { error?: string }).error ?? res.status}`);
+          return;
+        }
+        const { nonce } = (await res.json()) as { nonce: string };
+        const inv = await door.call('device', { proof: { kind: 'tab', nonce } });
+        await ward.save();
+        if (!isInvitation(inv)) {
+          say(`not in: ${escape(JSON.stringify(inv))}`);
+          return;
+        }
+        form.remove();
+        await side.close();
+        await admit(inv, `in, as ${identity.value}`);
+      })();
+    };
+  }
 }
 
+// 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 };