@quo-systems/dock 0.2.0 → 0.2.1

package/beings/user.ts

@@ -5,8 +5,9 @@
 // special only by the id the root chose for them: `desk`, the front desk,
 // who may ask her to invite a device; and each device, whose id is the
 // client identity the desk established.
-import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { isSilence, isWord, wordOf } from '@quo-systems/quo';
 import type { Asker, Invitation, JsonObject, OccupantRecord } from '@quo-systems/quo';
+import { Carrier } from './carry.ts';
 
 export const DESK = 'desk';
 const isDesk = (occ: OccupantRecord | undefined) => occ?.id === DESK;
@@ -15,14 +16,22 @@ const client = (occ: OccupantRecord | undefined) => (typeof occ?.notes.client ==
 // A device the human allowed to wake her other devices: the note says so.
 const mayWake = (occ: OccupantRecord | undefined) => isDesk(occ) || occ?.notes.wake === true;
 
-export class User extends Being {
+// She carries her standings, acme, the calendar, the house, for a device the
+// human allowed to reach them at the exchange: the note says so. A device
+// without the note sees her own asks alone, and a model sees acme only
+// because the human said it may.
+export class User extends Carrier {
+  static override carries(occ: OccupantRecord | undefined): boolean {
+    return isDevice(occ) && occ?.notes.reach === true;
+  }
   static override cells = { name: '', reports: [] as JsonObject[] };
   static override asks = {
     hello: { description: 'say hello, and hand back an invitation so she can reach you', input: { type: 'object', properties: { invitation: { type: 'object' } } } },
     whoami: { description: 'who she thinks you are', input: { type: 'object' }, for: isDevice },
-    device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
+    device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' }, reach: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
     push: { description: 'push an object to a device: wake it with an event', input: { type: 'object', properties: { client: { type: 'string' }, object: { type: 'object' } }, required: ['client', 'object'] }, for: mayWake },
     chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ: OccupantRecord | undefined) => client(occ) === 'agent' },
+    forget: { description: 'revoke a device: drop its way in and her way back to it, in one act', input: { type: 'object', properties: { client: { type: 'string' } }, required: ['client'] }, for: isDesk },
     report: { description: 'what a run of yours found', input: { type: 'object', properties: { event: { type: 'object' }, result: {} }, required: ['event', 'result'] }, for: isDevice },
   };
 
@@ -43,7 +52,8 @@ export class User extends Being {
 
   // The front desk asks; she mints. The client identity goes into the
   // occupant's notes, and that is what every gate reads. `wake` is the
-  // human's word at the exchange that this device may wake her others.
+  // human's word at the exchange that this device may wake her others, and
+  // `reach` that it may see and ask what she holds: her standings, carried.
   async device(args: JsonObject) {
     const c = typeof args.client === 'string' ? args.client : null;
     if (c === null) return { error: 'client is a string' };
@@ -53,18 +63,34 @@ export class User extends Being {
     if (rec) {
       rec.notes.client = c;
       if (args.wake === true) rec.notes.wake = true;
+      if (args.reach === true) rec.notes.reach = true;
     }
     return inv as unknown as JsonObject;
   }
 
+  // Her way out and the device's way in are two relations, and Quo keeps
+  // them apart. She joins them herself, here, as her own rule: she does
+  // not reach a device she no longer admits. Without it a revoked device
+  // stops being able to ask her and keeps receiving everything she pushes.
   async push(args: JsonObject) {
     const c = typeof args.client === 'string' ? args.client : null;
-    const st = c === null ? undefined : this.standings[`to:${c}`];
+    const st = c === null || !this.cells.occupants[c] ? undefined : this.standings[`to:${c}`];
     if (!st) return { error: 'no such device, or it gave no way back' };
     const out = await st.ask('notify', (args.object as JsonObject) ?? {});
     return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
   }
 
+  // Revocation is one act at her, because only she knows both ids. A side
+  // that had to remove two relations by hand could leave half of one
+  // standing, and every side would have to remember which half.
+  forget(args: JsonObject) {
+    const c = typeof args.client === 'string' ? args.client : null;
+    if (c === null) return { error: 'client is a string' };
+    this.occupants.remove(c);
+    this.standings.remove(`to:${c}`);
+    return { forgot: c };
+  }
+
   chores() {
     return { chores: ['census', 'report'] };
   }

package/cli/daemon.ts

@@ -102,7 +102,7 @@ export const sidePath = (dir: string) => socketPath(dir, 'side');
 // them: `local`, for a side that reached side.sock, and `web`, for a human
 // who passed the exchange pages. Both are the daemon vouching for someone it
 // saw itself; a proof of either kind arriving any other way names no nonce.
-const NONCES = new Map<string, { kind: string; user: string; client: string; wake?: boolean }>();
+const NONCES = new Map<string, { kind: string; user: string; client: string; wake?: boolean; reach?: boolean }>();
 // A nonce is minted for one kind and honoured under that kind alone: a tab's
 // nonce offered as a `local` proof names no nonce, so a proof of a kind still
 // arrives only the one way that kind is made.
@@ -138,7 +138,7 @@ async function readAll(req: AsyncIterable<Buffer>): Promise<Buffer | undefined>
 // `user` and nothing is minted, so `wake`, the human's word that this
 // device may wake her others, is read the first time only; to change it,
 // remove the occupant and allow again. The one path for every side.
-export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake = false): Promise<{ avatar?: Avatar; error?: string }> {
+export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake = false, reach = false): Promise<{ avatar?: Avatar; error?: string }> {
   if (!/^[\w.-]+$/.test(identity) || identity === hosted.record.user || identity === 'desk') return { error: 'an identity is a word, and not a being of the ward' };
   const key = `avatar:${identity}`;
   let avatar = hosted.being(key) as Avatar | undefined;
@@ -148,7 +148,7 @@ export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'w
     avatar = hosted.being(key) as Avatar;
   }
   const nonce = randomBytes(16).toString('hex');
-  NONCES.set(nonce, wake ? { kind, user: hosted.record.user, client: identity, wake: true } : { kind, user: hosted.record.user, client: identity });
+  NONCES.set(nonce, { kind, user: hosted.record.user, client: identity, ...(wake ? { wake: true } : {}), ...(reach ? { reach: true } : {}) });
   const entered = await avatar.enter({ ward: hosted.pk }, { kind, nonce });
   NONCES.delete(nonce);
   await hosted.save(); // the knock went through the ward's own door, which the harbor never sees
@@ -196,30 +196,43 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
       mountQuo(harbor, http, server, quo);
       const routes = options.routes ?? (await readRoutes(harbor.dir));
       const password = options.password ?? (() => process.env.QUO_OWNER_PASSWORD);
-      const main = harbor.wards.get('main');
       const here = `http://${http.host}:${http.port}`;
-      // the tab page: always, on the daemon's own door when no route names a public one
-      const tab = main ? tabPages(main, { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` }, password) : null;
+      // the worlds' pages: always, on the daemon's own door when no route names a public one
+      const tab = worldPages(harbor, { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` }, password);
       if (routes) {
-        // the MCP endpoint: a bearer names an identity, the identity names her avatar, the side runs beside her
-        mcp = main ? new McpHttp((identity) => admit(main, identity, 'web'), () => main.save()) : null;
+        // the worlds a client may be allowed into: every ward with a public being, main first
+        const worlds = () =>
+          [...harbor.wards]
+            .filter(([, h]) => (h.partition as { public?: string | null }).public !== null)
+            .sort(([a], [b]) => (a === 'main' ? -1 : b === 'main' ? 1 : a.localeCompare(b)))
+            .map(([ward, h]) => ({ ward, user: h.record.user }));
+        // the MCP endpoint: a bearer names an identity in a world, the identity names her avatar there, the side runs beside her
+        mcp = new McpHttp(
+          async (identity, ward) => {
+            const hosted = harbor.wards.get(ward);
+            return hosted ? admit(hosted, identity, 'web') : { error: 'no such world' };
+          },
+          async () => {
+            for (const h of harbor.wards.values()) await h.save();
+          },
+        );
         oauth = await mountOAuth(harbor.dir, http, routes, mcp);
-        if (mcp) mcp.gone = (identity) => oauth!.revoke(identity); // removal at the ward ends the grant at the route
-        if (main) {
-          exchange = new Exchange({
-            oauth,
-            password,
-            user: main.record.user,
-            admit: async (identity, wake) => {
-              const r = await admit(main, identity, 'web', wake);
-              return r.error ? { error: r.error } : {};
-            },
-          });
-        }
+        mcp.gone = (identity, ward) => oauth!.revoke(identity, ward); // removal at the ward ends the grant at the route
+        exchange = new Exchange({
+          oauth,
+          password,
+          worlds,
+          admit: async (identity, wake, reach, ward) => {
+            const hosted = harbor.wards.get(ward);
+            if (!hosted) return { error: 'no such world' };
+            const r = await admit(hosted, identity, 'web', wake, reach);
+            return r.error ? { error: r.error } : {};
+          },
+        });
       }
       const ex = exchange;
       http.mount('/web', async (req, res, rest) => {
-        if (tab && (await tab(req, res, rest))) return;
+        if (await tab(req, res, rest)) return;
         if (ex && (await ex.handle(req, res, rest))) return;
         res.writeHead(404, { 'content-type': 'text/plain' });
         res.end('no such page');
@@ -419,15 +432,23 @@ async function readRoutes(dir: string): Promise<Routes | null> {
   return out;
 }
 
-// The tab page, `estate/human/tab.ts`, on the web route: the page, its
-// bundle built once from the source, and the one call of the exchange a tab
-// makes: the owner password for a nonce the desk honours under `tab`. The
-// avatar that knocks with it lives in the tab, not here, so nothing is
-// admitted on this side; the tab's harbor announces its ward and the user
-// being knocks back down that socket.
-function tabPages(main: Hosted, at: { quo: string; web: string }, password: () => string | undefined): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
-  // The tab's source sits beside this file: `.ts` in the tree, `.js` once
-  // emitted into the package's dist. The bundler takes whichever is there.
+// The worlds on the web route. A world is a ward with a public being, and
+// its address is `/web/<ward>`: the tab page, `human/tab.ts`, told which
+// ward and which pk, so that its guest is that ward's public being rendered
+// by the screen, whatever class she is. `/web/` lists the worlds. The bundle
+// is built once from the source beside this file, `.ts` in the tree, `.js`
+// once emitted into the package's dist. `/web/<ward>/login` is the one call
+// of the dock's own way in a tab makes: the owner password for a nonce the
+// desk honours under `tab`. The avatar that knocks with it lives in the tab,
+// not here, so nothing is admitted on this side.
+//
+// The page carries a content security policy: scripts from this origin
+// only and never inline, connections to this origin and the quo. route the
+// tab dials, images from data URIs and this origin, and nothing else. So
+// even a bug in a renderer cannot become a script, and no look can reach a
+// server. The config crosses in a JSON script, which the policy allows.
+const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
+function worldPages(harbor: DiskHarbor, at: { quo: string; web: string }, password: () => string | undefined): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
   const tabEntry = () => {
     const js = fileURLToPath(new URL('../human/tab.js', import.meta.url));
     return existsSync(js) ? js : fileURLToPath(new URL('../human/tab.ts', import.meta.url));
@@ -435,21 +456,49 @@ function tabPages(main: Hosted, at: { quo: string; web: string }, password: () =
   let bundle: Promise<string> | undefined;
   const built = () =>
     (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((o) => o.outputFiles[0]!.text));
-  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
-<style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem;color:#222}input,button{font:inherit;padding:.4rem;margin:.2rem}pre{background:#f4f4f4;padding:.75rem;overflow:auto}</style>
-</head><body><script type="module">import { start } from './tab.js'; start(${JSON.stringify(at)});</script></body></html>`;
+  const quoOrigin = (() => {
+    try {
+      const u = new URL(at.quo);
+      return `${u.origin} ${u.origin.replace(/^http/, 'ws')}`;
+    } catch {
+      return '';
+    }
+  })();
+  const policy = `default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ${quoOrigin}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`;
+  const shell = (body: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+<style>${CSS}</style>
+</head><body>${body}</body></html>`;
+  const esc = (v: string) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+  const publicOf = (h: Hosted) => (h.partition as { public?: string | null }).public ?? null;
+  const html = (status: number, res: ServerResponse, body: string) => {
+    res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': policy, 'referrer-policy': 'no-referrer' });
+    res.end(shell(body));
+    return true;
+  };
   return async (req, res, rest) => {
-    if (rest === '/tab' && req.method === 'GET') {
-      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
-      res.end(html);
-      return true;
+    const parts = rest.split('/').filter(Boolean);
+    if (req.method === 'GET' && (rest === '' || rest === '/')) {
+      const list = [...harbor.wards]
+        .filter(([, h]) => publicOf(h) !== null)
+        .map(([n, h]) => `<li><a href="${at.web}/${encodeURIComponent(n)}">${esc(n)}</a> <small>${esc(publicOf(h) ?? '')} at the door, <code>${h.pk.slice(0, 16)}…</code></small></li>`)
+        .join('');
+      return html(200, res, `<h1>worlds</h1>${list ? `<ul>${list}</ul>` : '<p>no ward here has a public being</p>'}`);
     }
     if (rest === '/tab.js' && req.method === 'GET') {
       res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
       res.end(await built());
       return true;
     }
-    if (rest === '/tab/login' && req.method === 'POST') {
+    const wardName = parts[0] ?? '';
+    if (!wardName || RESERVED_PATHS.has(wardName)) return false;
+    const hosted = harbor.wards.get(wardName);
+    if (!hosted) return html(404, res, `<h1>no such world</h1><p>no ward named ${esc(wardName)} on this harbor.</p>`);
+    if (parts.length === 1 && req.method === 'GET') {
+      if (publicOf(hosted) === null) return html(404, res, `<h1>not a world</h1><p>ward ${esc(wardName)} has no public being, so nobody is at its door.</p>`);
+      const cfg = { quo: at.quo, web: at.web, ward: wardName, pk: hosted.pk };
+      return html(200, res, `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${at.web}/tab.js"></script>`);
+    }
+    if (parts.length === 2 && parts[1] === 'login' && req.method === 'POST') {
       const raw = await readAll(req as AsyncIterable<Buffer>);
       let body: { password?: unknown; identity?: unknown } = {};
       try {
@@ -470,15 +519,20 @@ function tabPages(main: Hosted, at: { quo: string; web: string }, password: () =
         return json(401, { error: 'that is not the password' });
       }
       const identity = typeof body.identity === 'string' ? body.identity : '';
-      if (!/^[\w.-]{1,40}$/.test(identity) || identity === main.record.user || identity === 'desk') return json(400, { error: 'an identity is one word, and not the user or the desk' });
+      if (!/^[\w.-]{1,40}$/.test(identity) || identity === hosted.record.user || identity === 'desk') return json(400, { error: 'an identity is one word, and not the user or the desk' });
       const nonce = randomBytes(16).toString('hex');
-      NONCES.set(nonce, { kind: 'tab', user: main.record.user, client: identity });
-      return json(200, { nonce, ward: main.pk });
+      NONCES.set(nonce, { kind: 'tab', user: hosted.record.user, client: identity, reach: true });
+      return json(200, { nonce, ward: hosted.pk });
     }
     return false;
   };
 }
 
+// The tab's stylesheet: one, light and dark, honouring the variables a look
+// sets on a section. The page owns layout; a far being paints inside her
+// section and nowhere else.
+const CSS = ":root{color-scheme:light dark;--accent:#3b6ef5;--bg:transparent;--fg:inherit;--font:system-ui,sans-serif;--radius:6px}body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}nav.worlds{display:flex;flex-wrap:wrap;gap:.5rem 1rem;font-size:.9rem;opacity:.8}nav.worlds a[aria-current]{font-weight:600}header,main{background:var(--bg);color:var(--fg);font-family:var(--font)}header{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1rem}header .notice{width:100%;margin:0}input,select,textarea,button{font:inherit;padding:.4rem;margin:.2rem;border-radius:var(--radius)}button{background:var(--accent);color:#fff;border:0;padding:.4rem .9rem}fieldset{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);margin:.5rem 0}section.standing{background:var(--bg);color:var(--fg);font-family:var(--font);border-left:4px solid var(--accent);border-radius:var(--radius);padding:.25rem 1rem;margin:1.5rem 0}section.standing h2{display:flex;align-items:center;gap:.5rem;font-size:1.1rem}img.logo{height:1.6rem}table{border-collapse:collapse}td,th{padding:.15rem .5rem;text-align:left}.answer{margin:.5rem 0 1rem;padding:.5rem;border-left:3px solid var(--accent)}.answer.error{border-color:#c33}.answer.silence,.answer.word,.answer.unreached{border-color:#c93}pre{padding:.75rem;overflow:auto}";
+
 // The quo. route. A request carries one ask to a pk; an upgrade is a held
 // socket. Bytes from here go to an own door or a held socket, never onward.
 function mountQuo(harbor: DiskHarbor, http: Http, server: HttpServer, quo: Quo): void {
@@ -571,9 +625,9 @@ async function mountOAuth(dir: string, http: Http, routes: Routes, mcp: McpHttp
   http.mount('/mcp', async (req, res, rest) => {
     if (await oauth.handle(req, res, rest)) return;
     if (rest === '/mcp') {
-      const identity = oauth.bearer(req);
-      if (identity === null || !mcp) return oauth.challenge(res);
-      return mcp.handle(req, res, identity);
+      const grant = oauth.bearer(req);
+      if (grant === null || !mcp) return oauth.challenge(res);
+      return mcp.handle(req, res, grant.identity, grant.ward);
     }
     res.writeHead(404, { 'content-type': 'application/json' });
     res.end(JSON.stringify({ error: 'no such route' }));

package/cli/quo.ts

@@ -11,6 +11,7 @@
 //   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }
 //   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
 //   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
+//   quo unboot [--dir D] [--ward W] [--via S] <json> { being }: a being out of the ward, with every relation she holds
 //   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
 //   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
 //   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
@@ -34,7 +35,7 @@ import { ask, side, reach, type Run } from './client.ts';
 import { pilotSide } from '../mcp/pilot.ts';
 import { estate } from './estate.ts';
 
-const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove']);
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove', 'unboot']);
 
 function parse(argv: string[]) {
   const flags: Record<string, string> = {};
@@ -121,7 +122,7 @@ async function main(argv: string[]): Promise<number> {
     const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
     return failed ? 1 : 0;
   }
-  console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+  console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|unboot|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
   return 2;
 }
 

package/dist/beings/avatar.js

@@ -47,8 +47,11 @@ export class Avatar extends Being {
             return inv ?? { error: 'no invitation' };
         return this.join(inv);
     }
-    // Knock with an invitation, hand the user being one back so she can push,
-    // and take her as `user`. The only moment a standing is born here.
+    // Knock with an invitation, hand the far being one back so she can push,
+    // and take her as `user`. The only moment a standing is born here. A being
+    // who answers the hello with an error object is a being who answered: she
+    // is taken all the same, and the way back she did not take is dropped, so
+    // any world's public being may admit a guest, hello or not.
     async join(invitation) {
         if (this.standings[USER])
             return this.tools();
@@ -60,6 +63,8 @@ export class Avatar extends Being {
             this.occupants.remove(PUSHER);
             return { error: isSilence(out) ? 'silence' : wordOf(out) };
         }
+        if (out !== null && typeof out === 'object' && !Array.isArray(out) && 'error' in out)
+            this.occupants.remove(PUSHER);
         await this.take(USER, invitation);
         return this.tools();
     }

package/dist/beings/carry.d.ts

@@ -0,0 +1,10 @@
+import { Being } from '@quo-systems/quo';
+import type { Asker, Blueprint, JsonObject, OccupantRecord, Reply } from '@quo-systems/quo';
+export declare class Carrier extends Being {
+    static carries(_occupant: OccupantRecord | undefined, _asker: Asker): boolean;
+    static hidden(id: string): boolean;
+    private get carried();
+    private get looks();
+    blueprint(asker: Asker): Promise<Blueprint>;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+}

package/dist/beings/carry.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier: a being who shows the asks of the standings she holds as asks
+// of her own, and forwards. Whoever she carries for sees, in one describe,
+// what she can be asked and what every being she holds can be asked, each
+// under that standing's name; asking one is an ask on that standing, in her
+// name, so the far being sees her and never who is behind her. A user being
+// carries acme for the human's devices; a house being could carry its
+// rooms; nothing here knows what she is.
+//
+// A carried ask is `<id>-<name>`, and the mapping back is kept in her cells
+// and never parsed from the name, so an id with a dash in it is no trouble.
+// The notes say which asks are whose, `standings: { id: { asks, look? } }`,
+// so a screen draws one section per standing and a model side keeps the
+// flat list it needs. Her own asks come first and are never shadowed: a
+// carried name that collides with one of hers is dropped.
+//
+// She asks a standing's describe again when its digest moved, and its
+// `look` once per digest, and keeps both in her cells. So a describe of
+// hers may cost one ask per stale standing, which is the price of a page
+// that is never more than one ask behind.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { sanitise } from './look.js';
+export class Carrier extends Being {
+    // Who sees what she carries. Nobody, until a subclass says who.
+    static carries(_occupant, _asker) {
+        return false;
+    }
+    // Standings she never carries: a way back to a device is one, by the
+    // dock's own convention, and a subclass may name more.
+    static hidden(id) {
+        return id.startsWith('to:');
+    }
+    get carried() {
+        return (this.cells.carried ??= {});
+    }
+    get looks() {
+        return (this.cells.looks ??= {});
+    }
+    // Her describe with her standings carried into it, for an asker who may
+    // see them. Every other asker gets her describe alone.
+    async blueprint(asker) {
+        const C = this.constructor;
+        const bp = this.describe(asker);
+        if (!C.carries(this.occupant(asker), asker))
+            return bp;
+        const own = new Set(bp.asks.map((a) => a.name));
+        const carried = {};
+        const groups = {};
+        for (const [id, rec] of Object.entries(this.cells.standings)) {
+            if (C.hidden(id))
+                continue;
+            const st = this.standings[id];
+            if (!st)
+                continue;
+            if (!rec.blueprint || rec.seen !== rec.digest)
+                await st.ask(); // her ward writes the record
+            if (!rec.blueprint)
+                continue;
+            const names = [];
+            for (const a of rec.blueprint.asks) {
+                if (a.name === 'look')
+                    continue;
+                const name = `${id}-${a.name}`;
+                if (own.has(name))
+                    continue;
+                carried[name] = { id, ask: a.name };
+                names.push(name);
+                bp.asks.push({ ...a, name });
+            }
+            const group = { asks: names };
+            if (rec.blueprint.asks.some((a) => a.name === 'look')) {
+                const kept = this.looks[id];
+                if (!kept || kept.digest !== rec.digest) {
+                    const l = await st.ask('look');
+                    this.looks[id] = { digest: rec.digest, look: isSilence(l) || isWord(l) ? {} : sanitise(l) };
+                }
+                group.look = this.looks[id].look;
+            }
+            groups[id] = group;
+        }
+        for (const id of Object.keys(this.looks))
+            if (!(id in groups))
+                delete this.looks[id];
+        this.cells.carried = carried;
+        const notes = bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? bp.notes : {};
+        return { asks: bp.asks, notes: { ...notes, standings: groups } };
+    }
+    async answer(asker, method, args = {}) {
+        if (method === undefined)
+            return this.blueprint(asker);
+        const C = this.constructor;
+        const to = Object.hasOwn(this.carried, method) ? this.carried[method] : undefined;
+        if (to && C.carries(this.occupant(asker), asker)) {
+            const st = this.standings[to.id];
+            if (!st)
+                return { error: 'unknown ask' };
+            const out = await st.ask(to.ask, args);
+            if (isSilence(out))
+                return out;
+            if (isWord(out))
+                return { error: wordOf(out) };
+            return out;
+        }
+        return super.answer(asker, method, args);
+    }
+}

package/dist/beings/desk.d.ts

@@ -8,6 +8,7 @@ export type Verified = {
     user: string;
     client: string;
     wake?: boolean;
+    reach?: boolean;
 };
 export type Verifier = (proof: Proof) => Promise<Verified | null> | Verified | null;
 export declare class Desk extends Being {

package/dist/beings/desk.js

@@ -33,7 +33,7 @@ export class Desk extends Being {
         const user = this.standings[`user:${who.user}`];
         if (!user)
             return { error: 'no such user' };
-        const inv = await user.ask('device', who.wake === true ? { client: who.client, wake: true } : { client: who.client });
+        const inv = await user.ask('device', { client: who.client, ...(who.wake === true ? { wake: true } : {}), ...(who.reach === true ? { reach: true } : {}) });
         if (isSilence(inv))
             return { error: 'silence' };
         if (isWord(inv))

package/dist/beings/index.d.ts

@@ -1,3 +1,5 @@
 export { User, DESK } from './user.ts';
 export { Desk, type Proof, type Verified, type Verifier } from './desk.ts';
 export { Avatar, USER, PUSHER } from './avatar.ts';
+export { Carrier } from './carry.ts';
+export { sanitise, hint, hintFor, groups, type Look, type Hint } from './look.ts';

package/dist/beings/index.js

@@ -3,3 +3,5 @@
 export { User, DESK } from './user.js';
 export { Desk } from './desk.js';
 export { Avatar, USER, PUSHER } from './avatar.js';
+export { Carrier } from './carry.js';
+export { sanitise, hint, hintFor, groups } from './look.js';

package/dist/beings/link.d.ts

@@ -0,0 +1,7 @@
+import type { Invitation } from '@quo-systems/quo';
+export declare const KEY = "quo";
+export declare function format(inv: Invitation): string;
+export declare function parse(hash: string): Invitation | null;
+export declare function strip(hash: string): string;
+export declare function link(page: string, inv: Invitation): string;
+export declare function isInvitation(v: unknown): v is Invitation;

package/dist/beings/link.js

@@ -0,0 +1,42 @@
+export const KEY = 'quo';
+const HEX = (n) => `[0-9a-f]{${n}}`;
+const FULL = new RegExp(`^(${HEX(128)})\\.(${HEX(64)})\\.(${HEX(64)})$`);
+const PUBLIC = new RegExp(`^${HEX(128)}$`);
+export function format(inv) {
+    return inv.heir && inv.secret ? `${inv.ward}.${inv.heir}.${inv.secret}` : inv.ward;
+}
+// The invitation in a fragment, or null. Anything else in the fragment is
+// the page's own and is left alone.
+export function parse(hash) {
+    const m = /(?:^#|&)quo=([^&]+)/.exec(hash.startsWith('#') ? hash : `#${hash}`);
+    if (!m)
+        return null;
+    const v = decodeURIComponent(m[1]);
+    const full = FULL.exec(v);
+    if (full)
+        return { ward: full[1], heir: full[2], secret: full[3] };
+    return PUBLIC.test(v) ? { ward: v } : null;
+}
+// The fragment without the invitation, so the page keeps whatever else it
+// put there and the capability is gone from the address bar.
+export function strip(hash) {
+    const rest = (hash.startsWith('#') ? hash.slice(1) : hash)
+        .split('&')
+        .filter((p) => !p.startsWith(`${KEY}=`))
+        .join('&');
+    return rest ? `#${rest}` : '';
+}
+export function link(page, inv) {
+    return `${page}#${KEY}=${format(inv)}`;
+}
+// Whether an answer is an invitation: a ward pk, and a heir with its secret
+// or neither. What a guest's form answers with to be let in.
+export function isInvitation(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    if (typeof o.ward !== 'string' || !PUBLIC.test(o.ward))
+        return false;
+    const heir = typeof o.heir === 'string', secret = typeof o.secret === 'string';
+    return (heir && secret) || (!heir && !secret && !('heir' in o) && !('secret' in o));
+}

package/dist/beings/look.d.ts

@@ -0,0 +1,27 @@
+import type { Blueprint, Json } from '@quo-systems/quo';
+export type Hint = {
+    title?: string;
+    readOnly?: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    icon?: string;
+};
+export type Look = {
+    name?: string;
+    logo?: string;
+    accent?: string;
+    background?: string;
+    foreground?: string;
+    font?: string;
+    radius?: number;
+    order?: string[];
+    asks?: Record<string, Hint>;
+};
+export declare function sanitise(v: Json | undefined): Look;
+export declare const hint: (l: Look | undefined, name: string) => Hint;
+export type Group = {
+    asks?: string[];
+    look?: Json;
+};
+export declare function groups(bp: Blueprint | null): Record<string, Group>;
+export declare function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint;