@nervur-org/dock 0.3.0

package/dist/human/app.js

@@ -0,0 +1,527 @@
+import { screenSide } from './screen.js';
+import { domSurface } from './dom.js';
+import { guest } from './guest.js';
+import { door, held as heldPage } from './door.js';
+import { USER } from '../beings/avatar.js';
+import { DOCK, CONSOLE, NOTIFICATIONS, settled } from '../dock/index.js';
+import { fresh, joined, localName, ordered, relations, world } from './worlds.js';
+import { giveWorld, takeWorld } from './move.js';
+import { invitationOf, reachOf } from '../beings/link.js';
+import { doorbell, drained, told, notice as noticeOf } from './wake.js';
+// 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 = 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());
+};
+const el = (tag, text = '', attrs = {}) => {
+    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) {
+    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) => (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();
+    const dial = (quo) => {
+        if (dialed.has(quo))
+            return;
+        dialed.add(quo);
+        o.harbor.dial(quo);
+    };
+    let list = o.kept.read();
+    let showing = null;
+    let side = null;
+    // How this device is woken, asked of the terrain and never decided here.
+    let heard = null;
+    const listen = async () => {
+        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 = 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, rel) => {
+        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) => 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) => say(String(e)));
+            nav.append(b);
+        }
+    };
+    const remember = (w) => {
+        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) => {
+        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 = 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, rel, notice, bp) => {
+        // 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, pk, w, isPublic) => {
+        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 () => {
+        const ward = o.harbor.wards.get(DOCK);
+        if (!ward || !ward.being(CONSOLE))
+            return null;
+        return ward;
+    };
+    const hasDevice = () => 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 () => {
+        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 }));
+        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 = 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 = null;
+    const stopGiving = async () => {
+        const g = giving;
+        giving = null;
+        offer.textContent = '';
+        await g?.close();
+        leaving();
+    };
+    const give = async (w) => {
+        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) => 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) => say(String(e)));
+            held.append(b, m);
+        }
+        held.append(offer);
+    };
+    const leave = async (pk) => {
+        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, inv, notice) => {
+        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, invitation) => {
+        let cfg = 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) => (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 () => {
+        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) => {
+        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) => bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) && bp.notes.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) => {
+    try {
+        return new URL(at).host;
+    }
+    catch {
+        return at;
+    }
+};

package/dist/human/apps.d.ts

@@ -0,0 +1,10 @@
+export type Apps = {
+    apple: string[];
+    android: {
+        package: string;
+        fingerprints: string[];
+    }[];
+};
+export declare const APPLE = "/.well-known/apple-app-site-association";
+export declare const ANDROID = "/.well-known/assetlinks.json";
+export declare function association(apps: Apps | null | undefined, path: string, notApp?: readonly string[]): string | null;

package/dist/human/apps.js

@@ -0,0 +1,29 @@
+// 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, path, notApp = []) {
+    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/dist/human/dom.d.ts

@@ -0,0 +1,2 @@
+import type { Surface } from './screen.ts';
+export declare function domSurface(root: HTMLElement): Surface;

package/dist/human/dom.js

@@ -0,0 +1,15 @@
+export function domSurface(root) {
+    const s = { show: (html) => (root.innerHTML = html), onSubmit: undefined };
+    root.addEventListener('submit', (ev) => {
+        const f = ev.target;
+        const ask = f?.dataset.ask;
+        if (!f || ask === undefined)
+            return;
+        ev.preventDefault();
+        const raw = {};
+        for (const [k, v] of new FormData(f))
+            raw[k] = typeof v === 'string' ? v : '';
+        s.onSubmit?.(ask, raw);
+    });
+    return s;
+}

package/dist/human/door.d.ts

@@ -0,0 +1,19 @@
+import { type Node, type Painter } from './tree.ts';
+export type Door = {
+    world?: string;
+    host: string;
+};
+export declare function doorTree(at: Door): Node;
+export declare function door(at: Door): string;
+export declare function heldTree(at: Door): Node;
+export declare function held(at: Door): string;
+export declare const POLICY = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; form-action 'self'; base-uri 'none'; frame-ancestors 'none'";
+export declare const ours: Painter;
+export type Landed = {
+    world?: string;
+    host: string;
+    at?: string;
+    ok: boolean;
+};
+export declare function landedTree(l: Landed): Node;
+export declare function landed(l: Landed): string;