@nervur-org/dock 0.3.0

package/human/app.ts

@@ -0,0 +1,580 @@
+// SPDX-License-Identifier: Apache-2.0
+// The app's shell: one device, many worlds, one screen. Where the tab is a
+// page on a world's own origin and learns that world from the page it was
+// served, the app is one origin of its own and every world is somewhere
+// else, so it learns each by one fetch of its address and keeps the list of
+// them itself. Nothing of a world's code ever runs here: an app is a
+// published bundle on somebody's phone, and a world that could put code in
+// it would be a world that owns the phone.
+//
+// One harbor, whichever the terrain has, and inside it one local ward per
+// world joined, `worlds.ts`, the ward named by the far world's pk. The
+// screen shows one world's relation at a time and the switcher moves
+// between them. Everything under the switcher is `screen.ts` and a
+// surface, the same as the tab: the app adds no way of showing a being.
+import type { Harbor, Hosted } from '@nervur-org/nervur/harbor';
+import type { Blueprint, Invitation, JsonObject } from '@nervur-org/nervur';
+import { screenSide } from './screen.ts';
+import { domSurface } from './dom.ts';
+import { guest } from './guest.ts';
+import { door, held as heldPage } from './door.ts';
+import { USER } from '../beings/avatar.ts';
+import { DOCK, CONSOLE, NOTIFICATIONS, settled } from '../dock/index.ts';
+import { fresh, joined, localName, ordered, relations, world, type Joined, type Relation, type World } from './worlds.ts';
+import { giveWorld, takeWorld, type Giving } from './move.ts';
+import { invitationOf, reachOf } from '../beings/link.ts';
+import { doorbell, drained, told, notice as noticeOf, type Bell, type Held } from './wake.ts';
+import type { Token } from '../dock/index.ts';
+import type { Config } from './tab.ts';
+
+// What one world's address answers when an app asks it for JSON, and the
+// only thing an app ever reads from a world besides its wards' own bytes.
+export type Learn = (at: string) => Promise<Config>;
+
+// The fetch, as every terrain but a test does it: the world's address, its
+// own origin asking, and JSON. A world answers this to an app and to
+// nobody else, `web.ts`.
+export const learn: Learn = async (at) => {
+  const r = await fetch(at, { headers: { accept: 'application/json' } });
+  if (!r.ok) throw new Error(`${at} answered ${r.status}`);
+  return (await r.json()) as Config;
+};
+
+// A harbor the app can reach a world through: the browser's and the
+// phone's both dial, since a device behind a network nobody can address
+// reaches a world by the socket it opened and never the other way.
+export type Dialing = Harbor & { dial(url: string): unknown };
+
+// How this device is woken: one platform function handed to the shell, the
+// token being the box's and no being's. The shell knows there is an ear and
+// never what kind of ear it is.
+//
+// The ear answers the token this device is reachable at, or null, which is
+// a device with no doorbell: a terrain with no push service behind it, a
+// human who was asked and said no, or a human who has not been asked. Each
+// of those works in every other way. It is asked again on every foreground,
+// because a platform may hand a device a new token at any time and a stale
+// one rings an empty house.
+//
+// What the human reads when the device was woken while nobody was looking
+// is composed here from objects that crossed sealed, never from the ring,
+// and shown by asking the dock ward's notifications being through the
+// harbor's own pointer: the same act on every terrain, and no second body.
+export type Ear = () => Promise<Token | null>;
+
+export type AppOptions = {
+  harbor: Dialing;
+  kept: Joined;
+  root: HTMLElement;
+  learn?: Learn;
+  // A link the platform handed the app, opened before anything else: the
+  // world it names is joined, whether or not it was known.
+  opened?: { at: string; invitation?: Invitation };
+  ear?: Ear;
+  // Where this device's bell stands, as the build knows it. A shell handed
+  // none holds no doorbell and hands a world nothing, which is what a world
+  // with no bell behind it looks like.
+  bell?: Bell;
+};
+
+export type Running = {
+  // Show one world by its pk, as the switcher does.
+  show(pk: string): Promise<void>;
+  // Take a link now, as the platform hands one to a running app.
+  open(at: string, invitation?: Invitation): Promise<void>;
+  // The device is back: the terrain says so when the app comes to the
+  // foreground or a ring woke it. What it missed comes over here.
+  woken(): Promise<JsonObject[]>;
+  worlds(): World[];
+  close(): Promise<void>;
+};
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Record<string, string> = {}): HTMLElementTagNameMap[K] => {
+  const e = document.createElement(tag);
+  if (text) e.textContent = text;
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v);
+  return e;
+};
+
+export async function app(o: AppOptions): Promise<Running> {
+  const look = o.learn ?? learn;
+  const nav = el('nav', '', { class: 'worlds nv-strip' });
+  const status = el('p', 'booting', { class: 'state nv-t-quiet' });
+  const screen = el('div');
+  o.root.append(nav, status, screen);
+  const say = (s: string) => (status.textContent = s);
+
+  // A device is one harbor, and this browser may already hold it in
+  // another tab. That tab is the device; this one is the held page, as a
+  // world's tab is, and it offers nothing that takes the lock.
+  try {
+    await o.harbor.boot();
+  } catch {
+    status.remove();
+    screen.innerHTML = heldPage({ host: location.host });
+    const none = async () => {};
+    return { show: none, open: none, woken: async () => [], worlds: () => [], close: none };
+  }
+  // Every world this device holds is dialed, not only the one on screen: a
+  // world reaches a device by the socket the device opened, and a device
+  // that dialed only what it is looking at could be woken by nothing else.
+  const dialed = new Set<string>();
+  const dial = (quo: string) => {
+    if (dialed.has(quo)) return;
+    dialed.add(quo);
+    o.harbor.dial(quo);
+  };
+
+  let list = o.kept.read();
+  let showing: string | null = null;
+  let side: { close(): Promise<void> } | null = null;
+
+  // How this device is woken, asked of the terrain and never decided here.
+  let heard: Token | null = null;
+  const listen = async (): Promise<Token | null> => {
+    if (!o.ear) return null;
+    try {
+      heard = await o.ear();
+    } catch {
+      heard = null; // a device whose ear will not answer is a device with no doorbell, and everything else stands
+    }
+    return heard;
+  };
+  // This device's doorbell, at the bell the build named. It is taken once
+  // and kept, and the platform's token goes to it and to nowhere else.
+  let bellAt: Held | null = null;
+
+  // Telling one world how to wake this device, which is `wake.ts`'s and not
+  // the shell's: the shell holds the doorbell and the ear, and says where
+  // the ward is saved.
+  const tell = async (ward: Hosted, rel: Relation) => {
+    await told(rel.avatar, bellAt, heard);
+    await ward.save(); // her keys rotated on those asks
+  };
+
+  // What the switcher switches between is the human's versions of
+  // themselves, one world each and a ward each: an employee at one world, a
+  // consultant at a second, family at a third, and never one of them
+  // knowing about another. So a device with one version has no switcher at
+  // all, since a control over one thing can only do nothing. It is taken
+  // out of the page rather than hidden, because the stylesheet lays it out
+  // by class and a class beats the hidden attribute.
+  //
+  // Its last entry is never a world: it is this device, the box's own ward
+  // shown through the Console, where a human sees what the box lends and
+  // leaves a world. A box that lends nothing has no such page.
+  const switcher = () => {
+    nav.replaceChildren();
+    const device = hasDevice();
+    if (list.length + (device ? 1 : 0) < 2) {
+      nav.remove();
+      return;
+    }
+    if (!nav.isConnected) o.root.insertBefore(nav, o.root.firstChild);
+    for (const w of ordered(list)) {
+      const b = el('button', w.name || w.pk.slice(0, 8), { type: 'button', class: w.home ? 'home nv-chip' : 'nv-chip' });
+      if (w.pk === showing) b.setAttribute('aria-current', 'true');
+      b.onclick = () => void show(w.pk).catch((e: unknown) => say(String(e)));
+      nav.append(b);
+    }
+    if (device) {
+      const b = el('button', 'this device', { type: 'button', class: 'device nv-chip' });
+      if (showing === DEVICE) b.setAttribute('aria-current', 'true');
+      b.onclick = () => void showDevice().catch((e: unknown) => say(String(e)));
+      nav.append(b);
+    }
+  };
+
+  const remember = (w: World) => {
+    list = joined(list, w);
+    o.kept.write(list);
+    switcher();
+  };
+
+  // One world on screen: its ward, whoever was in it last, and her page.
+  // A world whose address will not answer is still a world: the ward and
+  // the standings are here, and the switcher keeps it.
+  const show = async (pk: string) => {
+    const w = list.find((x) => x.pk === pk);
+    if (!w) return void say('no such world');
+    showing = pk;
+    await side?.close();
+    side = null;
+    screen.replaceChildren();
+    held.remove();
+    if (!status.isConnected) o.root.insertBefore(status, screen);
+    say(`reaching ${w.name || w.at}`);
+    switcher();
+
+    let cfg: Config | null = null;
+    try {
+      cfg = await look(w.at);
+      dial(cfg.quo);
+    } catch (e) {
+      say(`${w.name || w.at} did not answer: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const ward = await world(o.harbor, pk);
+    const named = cfg ? Object.entries(cfg.wards).find(([, v]) => v.pk === pk) : undefined;
+    if (cfg && named) remember({ pk, at: w.at, name: named[0] });
+
+    const rels = relations(ward);
+    const back = rels[rels.length - 1];
+    if (back) {
+      const had = await back.avatar.tools();
+      await ward.save(); // her keys rotated on that ask, whatever it answered
+      if ('asks' in had) return inside(ward, back, `in, at ${w.name || named?.[0] || w.at}`, had);
+      say(`not in (${had.error})`);
+    }
+    await atDoor(ward, pk, w, named?.[1]?.public === true);
+  };
+
+  const inside = async (ward: Awaited<ReturnType<typeof world>>, rel: Relation, notice: string, bp: Blueprint) => {
+    // Whether this world is a home is the user being's word, in her notes,
+    // and the switcher puts home first
+    const w = list.find((x) => x.pk === showing);
+    if (w) remember({ ...w, home: isHome(bp) });
+    await side?.close();
+    // A device has no surface of its own, and nothing of it is handed to a
+    // world: what this box can do is beings of its own ward, and the being
+    // of this world who lives on this box holds standings at them. What a
+    // world reaches is her, on the standing it already holds.
+    const note = notice;
+    status.remove();
+    screen.replaceChildren();
+    // The world's page address travels with the side, since that is what an
+    // invitation she answers becomes a link on: a being knows no routes and
+    // the side is where one is composed, in an app exactly as in a tab.
+    side = await screenSide(rel.avatar, domSurface(screen), {
+      after: () => ward.save(),
+      notice: note,
+      // A world that ended the relation is over, so the list of worlds is
+      // put up with its way out in reach. Nothing is dropped: one answer at
+      // one moment cannot delete a ward, and the far world is never asked.
+      ended: async () => {
+        leaving();
+        screen.after(held);
+      },
+      ...(w ? { at: w.at } : {}),
+    });
+    // This world learns how to wake this device, and hands over whatever it
+    // pushed while nobody could be reached. Both are ordinary asks on this
+    // relation, sealed like every other, and each object lands on the avatar
+    // exactly where a push would have landed.
+    await tell(ward, rel);
+    if (showing && showing !== DEVICE) await drained(o.harbor, [showing]);
+  };
+
+  // At the door of a world this device has no standing in: the public
+  // being's page when there is one, and a form whose answer is an
+  // invitation is the way in; the door page when there is nobody, since
+  // then a link is the only way and there is nothing to type.
+  const atDoor = async (ward: Awaited<ReturnType<typeof world>>, pk: string, w: World, isPublic: boolean) => {
+    if (!isPublic) {
+      status.remove();
+      screen.innerHTML = door({ world: w.name || undefined, host: hostOf(w.at) });
+      return;
+    }
+    say(`at the door of ${w.name || hostOf(w.at)}`);
+    const rel = await fresh(ward);
+    const gate = guest(rel.avatar, pk);
+    const s = await screenSide(gate, domSurface(screen), {
+      after: () => ward.save(),
+      notice: `a guest at ${w.name || hostOf(w.at)}: what she shows strangers`,
+      at: w.at,
+      admit: async (inv) => {
+        await s.close();
+        await admit(ward, inv, `in, as a guest of ${w.name || hostOf(w.at)}`);
+      },
+    });
+    side = s;
+  };
+
+  // The box's own ward, as its harbor stood it: the Console carrying every
+  // faculty this box lends. A box that lends nothing stands none, and there
+  // is no page of its own to show.
+  const deviceWard = async (): Promise<Hosted | null> => {
+    const ward = o.harbor.wards.get(DOCK);
+    if (!ward || !ward.being(CONSOLE)) return null;
+    return ward;
+  };
+  const hasDevice = (): boolean => o.harbor.wards.get(DOCK)?.being(CONSOLE) !== undefined;
+
+  // The device shown by itself: the last entry of the switcher, and the
+  // whole screen of a device that has joined no world. A fresh install has
+  // no world's page to carry her forms, and a first screen that says only
+  // "open a link someone sent you" is an app with permissions in its
+  // manifest and nothing that ever asks for them, which is a store
+  // reviewer's first question and a human's second.
+  //
+  // She is shown by the ordinary screen and by no other way: one avatar in
+  // the box's own ward holding her standing under the name a world's user
+  // being would stand under, so the side sees what it always sees. The root
+  // places it, because the root is the box.
+  const deviceScreen = async (): Promise<{ ward: Hosted; rel: Relation } | null> => {
+    const ward = await deviceWard();
+    if (!ward) return null;
+    const had = relations(ward)[0];
+    if (had) return { ward, rel: had };
+    const rel = await fresh(ward);
+    const inv = await ward.ask('invite', { being: CONSOLE, id: rel.key });
+    if (!inv || typeof inv !== 'object') throw new Error('this device is already held under that name');
+    const took = (await ward.ask('knock', { being: rel.key, id: USER, invitation: inv as unknown as JsonObject })) as { taken?: string; error?: string };
+    if (took.taken !== USER) throw new Error(took.error ?? 'the shell could not take this device');
+    await ward.save();
+    return { ward, rel };
+  };
+
+  // The device's page: what the box lends, as forms that ask the faculty
+  // and show its answer, a refusal included; the worlds this device is in,
+  // each with a way out; and the one sentence about custody a human needs.
+  const showDevice = async () => {
+    let found: { ward: Hosted; rel: Relation } | null = null;
+    try {
+      found = await deviceScreen();
+    } catch (e) {
+      return void say(`this device would not answer: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!found) return void say('this device lends nothing');
+    const { ward, rel } = found;
+    showing = DEVICE;
+    await side?.close();
+    side = null;
+    screen.replaceChildren();
+    if (!status.isConnected) o.root.insertBefore(status, screen);
+    say('');
+    switcher();
+    side = await screenSide(rel.avatar, domSurface(screen), { after: () => ward.save(), notice: CUSTODY });
+    leaving();
+    screen.after(held);
+  };
+
+  // The worlds this device is in, each with a way out and a way to another
+  // device. Leaving is the local ward dropped whole, seed and every
+  // standing in it, and the world forgotten from the list: the far world
+  // is never asked and never told, as WORLDS says of a lost phone, and it
+  // sees one device gone. Moving is the Courier: this device offers, the
+  // human carries the offer to the other device, and this copy goes the
+  // moment the other one says it landed.
+  const held = el('section', '', { class: 'held' });
+  const offer = el('p', '', { class: 'invitation' });
+  let giving: Giving | null = null;
+  const stopGiving = async () => {
+    const g = giving;
+    giving = null;
+    offer.textContent = '';
+    await g?.close();
+    leaving();
+  };
+  const give = async (w: World) => {
+    if (giving) return stopGiving();
+    const cfg = await look(w.at);
+    dial(cfg.quo);
+    giving = await giveWorld(o.harbor, w, cfg.quo);
+    offer.textContent = giving.offer;
+    leaving();
+    void giving.moved.then(async () => {
+      // it is on the other device now, and this one is out of the world
+      giving = null;
+      offer.textContent = '';
+      list = list.filter((x) => x.pk !== w.pk);
+      o.kept.write(list);
+      leaving();
+      switcher();
+    });
+  };
+  const leaving = () => {
+    held.replaceChildren();
+    if (list.length === 0) return;
+    held.append(el('p', 'the worlds this device is in', { class: 'quiet' }));
+    for (const w of list) {
+      const name = w.name || w.pk.slice(0, 8);
+      const b = el('button', `leave ${name}`, { type: 'button', 'data-leave': w.pk, class: 'nv-button', 'data-variant': 'danger' });
+      b.onclick = () => void leave(w.pk).catch((e: unknown) => say(String(e)));
+      const m = el('button', giving ? 'stop offering it' : `move ${name} to another device`, { type: 'button', 'data-give': w.pk, class: 'nv-button', 'data-variant': 'quiet' });
+      m.onclick = () => void give(w).catch((e: unknown) => say(String(e)));
+      held.append(b, m);
+    }
+    held.append(offer);
+  };
+  const leave = async (pk: string) => {
+    const name = localName(pk);
+    if (o.harbor.wards.has(name)) await o.harbor.drop(name);
+    list = list.filter((w) => w.pk !== pk);
+    o.kept.write(list);
+    leaving();
+    switcher();
+  };
+
+  const cold = async () => {
+    await showDevice();
+    say('no worlds yet: open a link someone sent you');
+  };
+
+  const admit = async (ward: Awaited<ReturnType<typeof world>>, inv: Invitation, notice: string) => {
+    say('knocking');
+    const rel = await fresh(ward);
+    let got = await rel.avatar.join(inv);
+    await ward.save(); // the knock went through her own door, which the harbor never sees
+    if (!('asks' in got)) return void say(`not in: ${got.error}`);
+    // What came back is the far being as she was during the knock. If
+    // anything on this device was still landing then, she read a device that
+    // can do nothing and carries that, and the empty ask is the only way
+    // anyone learns a shape moved: nothing pushes. So the page asks once
+    // more, with this box quiet, and paints what is there rather than what
+    // was there a moment ago. A page paints once, so asking once more here
+    // is the difference between a device with its faculties on screen and a
+    // device that looks empty until the person navigates away and back.
+    await settled();
+    const now = await rel.avatar.tools();
+    if ('asks' in now) got = now;
+    await inside(ward, rel, notice, got);
+  };
+
+  // A link, whether the app was opened by it or handed it while running.
+  // The invitation names its ward by pk, so the address in the link is
+  // where to reach that world and never which world it is.
+  const open = async (at: string, invitation?: Invitation) => {
+    let cfg: Config | null = null;
+    try {
+      cfg = await look(at);
+    } catch (e) {
+      return void say(`${at} did not answer: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    dial(cfg.quo);
+    const pk = invitation?.ward ?? (cfg.ward ? cfg.wards[cfg.ward]?.pk : undefined);
+    if (!pk) return void say('that link names no world');
+    const name = Object.entries(cfg.wards).find(([, v]) => v.pk === pk)?.[0] ?? '';
+    remember({ pk, at, name });
+    if (!invitation) return show(pk);
+    showing = pk;
+    switcher();
+    if (!status.isConnected) o.root.insertBefore(status, screen);
+    screen.replaceChildren();
+    await admit(await world(o.harbor, pk), invitation, 'in, by the link');
+  };
+
+  // Taking a world from another device. The device that holds the world
+  // shows an offer, an invitation next to the rendezvous to reach it
+  // through; the human carries it here, by eye or by camera, and the ward
+  // arrives whole: the avatars, the standings, everything won there, with
+  // the far world never asked and never told. This device dials the note
+  // first, because a device reaches a pk only through a listener it holds
+  // a socket to, and one that has joined no world dials nothing at all.
+  const taking = el('form', '', { class: 'move' });
+  const field = el('input', '', { name: 'offer', placeholder: 'the offer the other device shows', autocomplete: 'off', spellcheck: 'false' });
+  const said = el('p', '', { class: 'quiet' });
+  taking.append(el('label', 'take a world from another device'), field, el('button', 'take it', { type: 'submit', class: 'nv-button', 'data-variant': 'quiet' }), said);
+  o.root.append(taking);
+  taking.onsubmit = (e) => {
+    e.preventDefault();
+    const inv = invitationOf(field.value);
+    if (!inv) return void (said.textContent = 'that is not an offer');
+    const note = reachOf(field.value);
+    if (note) dial(note);
+    said.textContent = 'taking it…';
+    void (async () => {
+      const out = await takeWorld(o.harbor, inv);
+      if ('error' in out) return void (said.textContent = out.error);
+      said.textContent = '';
+      field.value = '';
+      remember(out.world);
+      await show(out.world.pk);
+    })().catch((why: unknown) => (said.textContent = String(why)));
+  };
+
+  // The device is back. A ring carries nothing, so waking is three moves and
+  // the harbor already made the first: it told its dialers, since a socket
+  // that died while the device slept died silently. What is left is to say
+  // the token again, because a platform may have handed out a new one, and
+  // to ask every world what it missed.
+  //
+  // Every world and not only the one on screen: a device is woken for
+  // whichever world had something to say, and one that drained only what it
+  // was looking at would leave the rest waiting for a second wake that may
+  // never come.
+  const woken = async (): Promise<JsonObject[]> => {
+    await listen();
+    // The token goes to this device's doorbell and to nobody else, which is
+    // the whole of a rotation: one write, and no world is told. A world
+    // that has no doorbell yet, because it was down when this device joined
+    // it, is given one here.
+    if (heard) await bellAt?.keep(heard);
+    for (const w of list) {
+      const ward = o.harbor.wards.get(localName(w.pk));
+      if (!ward) continue;
+      for (const rel of relations(ward)) await tell(ward, rel);
+    }
+    const got = await drained(o.harbor, list.map((w) => w.pk));
+    // What the human reads, composed here from what crossed sealed. Only
+    // when nobody was looking: a page that is open already shows every one
+    // of these where the push would have landed, and a banner over it would
+    // be the same news twice.
+    if (got.length && globalThis.document?.visibilityState !== 'visible') await shown(noticeOf(got));
+    return got;
+  };
+
+  // The line the human reads, shown by the box's own notifications being.
+  // A box that lends none shows nothing, and a refusal is hers to answer;
+  // the shell asks and does not read the answer, since the news is already
+  // on the page where the push landed.
+  const shown = async (line: { title: string; body: string }) => {
+    const dock = o.harbor.wards.get(DOCK);
+    if (!dock) return;
+    await dock.ask('ask', { being: NOTIFICATIONS, method: 'notify', args: line }).catch(() => {});
+  };
+
+  // The device ward before anything is dialed: a harbor announces the wards
+  // it hosts when it opens a socket, and a ward made after that is a pk the
+  // far world cannot knock. A device whose ward will not stand is a device
+  // with no grounds and a shell that works in every other way, so nothing
+  // here stops the app; the cold screen is where that is said out loud.
+  try {
+    await deviceWard();
+  } catch {
+    /* said by the cold screen, which is the one place a device speaks for itself */
+  }
+  await listen();
+  // The bell is dialed like a world, because a device reaches a pk only
+  // through a listener it holds a socket to; then the doorbell, taken the
+  // first time this device ever ran and kept from then on, and the
+  // platform's token said to it.
+  if (o.bell) {
+    dial(o.bell.at);
+    bellAt = await doorbell(o.harbor, o.bell);
+    if (heard) await bellAt?.keep(heard);
+  }
+  switcher();
+  if (o.opened) await open(o.opened.at, o.opened.invitation);
+  else if (list.length) await show(list[list.length - 1].pk);
+  else await cold();
+
+  return {
+    show,
+    open,
+    woken,
+    worlds: () => list,
+    close: async () => {
+      await side?.close();
+      side = null;
+    },
+  };
+}
+
+// What the switcher shows when the device's own page is up: not a pk, and
+// never a world.
+const DEVICE = 'device';
+
+// A world is a home when the being reached there says so: the user being
+// writes `home` in her notes, and no other being does.
+const isHome = (bp: Blueprint): boolean => bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) && (bp.notes as { home?: unknown }).home === true;
+
+// The one sentence about custody a human needs, on the device's page.
+const CUSTODY = 'this device: what it lends, and the worlds it is in. A reinstall starts fresh, so a world that holds nothing of you elsewhere must invite you again.';
+
+const hostOf = (at: string) => {
+  try {
+    return new URL(at).host;
+  } catch {
+    return at;
+  }
+};

package/human/apps.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// What a hostname says where the two platforms look before they let an app
+// claim its links. The claim is a file, the platform fetches it over TLS,
+// and a hostname that names no app is a hostname whose links open a
+// browser.
+//
+// Two hostnames say it and neither may say it differently. A world's web
+// route says it for the estate that ships an app of its own, and the Quo
+// app's own domain says it for the app the stores carry, which serves no
+// world and has no route. So the words are here, once, and both fetch them
+// from the same place: Apple's format and Google's are the platforms' and
+// change on their schedule, not ours, and a second copy would be a second
+// thing to remember on the day one of them moves.
+export type Apps = {
+  // `<team>.<bundle id>`, as Apple's file calls an app
+  apple: string[];
+  // the package and the signing certificates Android verifies it by
+  android: { package: string; fingerprints: string[] }[];
+};
+
+// The two paths, which are the platforms' and not ours.
+export const APPLE = '/.well-known/apple-app-site-association';
+export const ANDROID = '/.well-known/assetlinks.json';
+
+// The claim `path` should answer with, or `null` when this hostname claims
+// no app there: no apps at all, none of that platform, or a path that is
+// neither file. `null` is a 404 and not an empty file, because an empty
+// claim and no claim mean the same thing to a phone and only one of them
+// is honest about a hostname that ships no app.
+//
+// `notApp` is the paths on this hostname that are the browser's even when
+// the app is installed. A world's route has one, the credential exchange,
+// which belongs in the browser that started it; the app's own domain has
+// none, since it has no pages at all.
+export function association(apps: Apps | null | undefined, path: string, notApp: readonly string[] = []): string | null {
+  if (!apps) return null;
+  if (path === ANDROID) {
+    if (!apps.android.length) return null;
+    return JSON.stringify(apps.android.map((a) => ({ relation: ['delegate_permission/common.handle_all_urls'], target: { namespace: 'android_app', package_name: a.package, sha256_cert_fingerprints: a.fingerprints } })));
+  }
+  if (path === APPLE) {
+    if (!apps.apple.length) return null;
+    const components = [...notApp.map((p) => ({ '/': p, exclude: true })), { '/': '/*' }];
+    return JSON.stringify({ applinks: { details: [{ appIDs: apps.apple, components }] } });
+  }
+  return null;
+}

package/human/dom.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+// The surface on a document: a page is the root's HTML, and a submit
+// anywhere under it is the form's fields as strings, handed to the side
+// under the ask the form names. The one file under `human/` that touches an
+// element, and it knows nothing of what the page says.
+import type { Surface } from './screen.ts';
+import type { Raw } from './html.ts';
+
+export function domSurface(root: HTMLElement): Surface {
+  const s: Surface = { show: (html) => (root.innerHTML = html), onSubmit: undefined };
+  root.addEventListener('submit', (ev) => {
+    const f = ev.target as HTMLFormElement | null;
+    const ask = f?.dataset.ask;
+    if (!f || ask === undefined) return;
+    ev.preventDefault();
+    const raw: Raw = {};
+    for (const [k, v] of new FormData(f)) raw[k] = typeof v === 'string' ? v : '';
+    s.onSubmit?.(ask, raw);
+  });
+  return s;
+}