@quo-systems/dock 0.2.0 → 0.2.1

package/dist/mcp/server.js

@@ -11,19 +11,37 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
+import { hintFor, sanitise } from '../beings/look.js';
+import { isSilence, isWord, digest } from '@quo-systems/quo';
 export const NAME = 'quo';
 export const VERSION = '0.0.0';
 // The empty ask as a tool: her describe whole, asks and notes.
 export const DESCRIBE = { name: 'describe', description: 'the empty ask: her describe, the asks and the notes', inputSchema: { type: 'object' } };
 // Her describe, spoken as tools, the empty ask first. Name, description and
-// input are verbatim; an output schema crosses when she declared one.
-export function tools(bp) {
-    const asks = bp.asks.map((a) => {
+// input are verbatim; an output schema crosses when she declared one. Her
+// look, when she has one, is the hints: a title, and the annotations a host
+// reads. The `look` ask itself is presentation, and is not a tool.
+export function tools(bp, look = {}) {
+    const asks = bp.asks
+        .filter((a) => a.name !== 'look')
+        .map((a) => {
         const t = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
         if (a.description !== undefined)
             t.description = a.description;
         if (a.output !== undefined)
             t.outputSchema = { ...a.output, type: 'object' };
+        const h = hintFor(bp, look, a.name);
+        if (h.title !== undefined)
+            t.title = h.title;
+        const notes = {};
+        if (h.readOnly !== undefined)
+            notes.readOnlyHint = h.readOnly;
+        if (h.destructive !== undefined)
+            notes.destructiveHint = h.destructive;
+        if (h.idempotent !== undefined)
+            notes.idempotentHint = h.idempotent;
+        if (Object.keys(notes).length)
+            t.annotations = notes;
         return t;
     });
     return [DESCRIBE, ...asks];
@@ -32,11 +50,24 @@ export function tools(bp) {
 // changed hooks it, since a same-ward ask never crosses the harbor.
 export async function mcpSide(avatar, transport, after = async () => { }) {
     const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
+    // Her look, asked once per digest of her describe.
+    let seen = null;
+    let look = {};
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         const bp = await avatar.tools();
         if ('error' in bp && !('asks' in bp))
             return { tools: [] }; // not joined: nothing to show, and nothing to call
-        return { tools: tools(bp) };
+        const d = await digest(bp);
+        if (d !== seen) {
+            seen = d;
+            if (bp.asks.some((a) => a.name === 'look')) {
+                const l = await avatar.call('look', {});
+                look = isSilence(l) || isWord(l) ? {} : sanitise(l);
+            }
+            else
+                look = {};
+        }
+        return { tools: tools(bp, look) };
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const w = word(req.params.name === DESCRIBE.name ? await avatar.tools() : await avatar.call(req.params.name, (req.params.arguments ?? {})));

package/dist/mcp/web/exchange.d.ts

@@ -1,14 +1,17 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { OAuth } from '../oauth.ts';
 export declare const SESSION_TTL: number;
-export type Admit = (identity: string, wake: boolean) => Promise<{
+export type Admit = (identity: string, wake: boolean, reach: boolean, ward: string) => Promise<{
     error?: string;
 }>;
 export type Options = {
     oauth: OAuth;
     password: () => string | undefined;
     admit: Admit;
-    user: string;
+    worlds: () => {
+        ward: string;
+        user: string;
+    }[];
     now?: () => number;
 };
 export declare const suggest: (name: string) => string;

package/dist/mcp/web/exchange.js

@@ -90,7 +90,7 @@ export class Exchange {
                 return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
             if (!this.valid(req))
                 return go(`/login?request=${encodeURIComponent(request)}`), true;
-            return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user)), true;
+            return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds())), true;
         }
         if (rest === '/allow' && req.method === 'POST') {
             const f = await readForm(req);
@@ -104,13 +104,17 @@ export class Exchange {
                 const out = await this.o.oauth.deny(request);
                 return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), true;
             }
+            const worlds = this.o.worlds();
+            const world = worlds.find((w) => w.ward === (f.get('ward') ?? worlds[0]?.ward));
+            if (!world)
+                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'That is not a world of this harbor.')), true;
             const identity = word(f.get('identity'));
-            if (identity === null || identity === this.o.user || identity === 'desk')
-                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user, 'An identity is one word, and not the user or the desk.')), true;
-            const admitted = await this.o.admit(identity, f.get('wake') === 'on');
+            if (identity === null || identity === world.user || identity === 'desk')
+                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'An identity is one word, and not the user or the desk.')), true;
+            const admitted = await this.o.admit(identity, f.get('wake') === 'on', f.get('reach') === 'on', world.ward);
             if (admitted.error)
                 return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
-            const out = await this.o.oauth.complete(request, identity);
+            const out = await this.o.oauth.complete(request, identity, world.ward);
             return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
         }
         return false;
@@ -125,12 +129,22 @@ ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/login"><input type="hidden" name="request" value="${esc(request)}">
 <label for="p">Owner password</label><input id="p" name="password" type="password" autocomplete="current-password" autofocus required>
 <button type="submit">Log in</button></form>`;
-const allowForm = (request, client, redirect, identity, user, err = '') => `<h1>Allow ${esc(client)}?</h1>
-<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>.</p>
+// The world is a choice when the harbor has more than one; the user named
+// is the first world's, and the page says which world each identity lands in.
+const allowForm = (request, client, redirect, identity, worlds, err = '') => {
+    const user = worlds[0]?.user ?? '';
+    const pick = worlds.length > 1
+        ? `<label for="wd">World</label><select id="wd" name="ward">${worlds.map((w) => `<option value="${esc(w.ward)}">${esc(w.ward)}, ${esc(w.user)}'s</option>`).join('')}</select>`
+        : `<input type="hidden" name="ward" value="${esc(worlds[0]?.ward ?? 'main')}">`;
+    return `<h1>Allow ${esc(client)}?</h1>
+<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>${worlds.length > 1 ? ', or of another world below' : ''}.</p>
 <p>It will see exactly what ${esc(user)} shows the identity below, and nothing else. You can remove it any time.</p>
 <p>It returns to <code>${esc(redirect)}</code>.</p></div>
 ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/allow"><input type="hidden" name="request" value="${esc(request)}">
+${pick}
 <label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
+<label for="r"><input id="r" name="reach" type="checkbox" style="width:auto"> May reach what ${esc(user)} holds: her standings, acme and the rest, as asks of hers</label>
 <label for="w"><input id="w" name="wake" type="checkbox" style="width:auto"> May wake your other devices: hand an agent an event through ${esc(user)}</label>
 <button type="submit" name="decision" value="allow">Allow</button><button type="submit" name="decision" value="deny">Deny</button></form>`;
+};

package/harbor/quo-harbor.md

@@ -88,6 +88,38 @@ the new harbor pointed at the same code. Same seed, same pk, every standing
 anyone holds still points at her. The old harbor deletes its copies first:
 two harbors holding one seed are two wards with one pk, diverging silently.
 
+What a move costs is not the three parts, which are bytes, but how many
+peers wrote down where the ward was. A pk is permanent by arithmetic; a
+location is soft state in every other harbor's directory, and only that goes
+stale. So the bill is proportional to who hard-coded it, and there are two
+kinds of ward.
+
+A ward whose harbor dials out is free. It announces what it holds when a
+line opens and whenever that changes, the listener proves each claim at the
+door and binds it, and a ward that arrives on a new box is reachable as soon
+as its harbor dials. Nobody is told and no peer acts.
+
+A ward that is dialed keeps a second name. Peers hold a hint, pk at a URL,
+in their own stores and across their own restarts, so that URL is a promise
+the same way the pk is. Moving boxes does not break it, because a hostname
+is not a location: DNS and the proxy point it wherever the harbor now runs,
+which is the whole reason the route is a hostname and not an address.
+Changing the URL itself is the move that costs, and it cannot be announced
+to a peer this ward cannot reach.
+
+When it must change, what is republished is a hint and never an invitation.
+The relation, its keys and its count are untouched, and the invitation is
+as good as it was: that is why the two travel separately, a link being one
+next to the other. Peers on a rendezvous this ward also dials relearn by
+themselves, since a binding is proven at the door and names no URL; peers
+holding a hint need a new one, and a hint is not a capability, so it may be
+published in the open to all of them at once. Nobody is invited twice.
+
+The rule, then: a dialable ward keeps two names and owes the second the same
+care as the first, and a ward that only dials keeps one, which is why a
+laptop, a tab and a phone move home without ceremony and the droplet does
+not.
+
 ### Code is a harbor decision
 
 A ward's code has an origin: a folder the owner wrote, a bundle a world
@@ -235,6 +267,11 @@ request      POST <url>/<pk>, the sealed ask as the body, the sealed reply as th
              <url> is the world's quo. route, which the proxy maps onto the daemon's /quo
              404 is "no reach for that pk" and comes back as nothing; a line lost after
              sending answers nothing at all, and the ward's bound ends the ask
+             at most 1 MiB is read, and a body over it is answered by that same 404: an
+             ask too big for this door is nothing delivered, never a silence, so it is
+             safe to send again and it will fail again. The number is this daemon's and
+             is on no wire; a caller cannot ask for it and is never told which of the
+             two a 404 was
 socket       a WebSocket at <url>, held by the dialer, used both ways
              text frame   { announce: [pk, ...] }   the ward pks this side holds
              ask frame    [0][id 4][pk 64][bytes]    a frame id matches the reply

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,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();
   };