@nervur-org/dock 0.3.0

package/dist/human/local.js

@@ -0,0 +1,10 @@
+export function local(ward, key) {
+    // A named ask names it; the empty ask says nothing at all, which is how
+    // the owner's ask says the empty ask too.
+    const one = (method, args = {}) => ward.ask('ask', method === undefined ? { being: key } : { being: key, method, args });
+    return {
+        tools: async () => (await one()),
+        call: (name, args = {}) => one(name, args),
+        ears: new Set(),
+    };
+}

package/dist/human/mark.d.ts

@@ -0,0 +1,8 @@
+export declare const RING = "<circle cx=\"32\" cy=\"32\" r=\"22\" stroke-dasharray=\"110 30\" transform=\"rotate(-60 32 32)\"/><circle cx=\"32\" cy=\"32\" r=\"5\" fill=\"currentColor\" stroke=\"none\"/>";
+export declare const MARK_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"4\" stroke-linecap=\"round\"><circle cx=\"32\" cy=\"32\" r=\"22\" stroke-dasharray=\"110 30\" transform=\"rotate(-60 32 32)\"/><circle cx=\"32\" cy=\"32\" r=\"5\" fill=\"currentColor\" stroke=\"none\"/></svg>";
+export declare const MARK: string;
+export declare const ICON_GROUND = "#3b6ef5";
+export declare const ICON_MARK = "#fbfaf7";
+export declare function markLayer(fraction?: number): string;
+export declare function groundLayer(): string;
+export declare function iconSVG(radius?: number): string;

package/dist/human/mark.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// The mark: a ring with a gap and a point at the centre, one being's voice
+// reaching another's door. It is the one mark every Quo app wears, on the
+// door page, on the desk app's dock icon and on the phone's home screen,
+// and it is drawn once here so those can never drift apart.
+//
+// The glyph is strokes on nothing, coloured by whoever draws it: the door
+// page inherits `currentColor` and the app icons are given the two colours
+// below. `app/icon/build.ts` is what makes the icons of it.
+export const RING = '<circle cx="32" cy="32" r="22" stroke-dasharray="110 30" transform="rotate(-60 32 32)"/><circle cx="32" cy="32" r="5" fill="currentColor" stroke="none"/>';
+// The mark as a page uses it: strokes in the colour of the text around it.
+export const MARK_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none" stroke="currentColor" stroke-width="4" stroke-linecap="round">${RING}</svg>`;
+// And as a data URI, since a look carries a logo that way and no request
+// for an image ever leaves a page.
+export const MARK = 'data:image/svg+xml;base64,' + btoa(MARK_SVG);
+// The app icon's two colours, the dock's own accent and paper: an icon is
+// the product's palette or it is somebody else's product.
+export const ICON_GROUND = '#3b6ef5';
+export const ICON_MARK = '#fbfaf7';
+// The mark alone on nothing, at the size a layer wants it. Android draws an
+// icon in two layers and crops both to whatever shape the phone likes, a
+// circle among them, so its foreground is the mark small enough to survive
+// the crop, roughly the middle half, and its background is the ground.
+export function markLayer(fraction = 0.5) {
+    const scale = fraction;
+    const shift = (64 - 64 * scale) / 2;
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><g transform="translate(${shift} ${shift}) scale(${scale})" fill="none" stroke="${ICON_MARK}" stroke-width="4" stroke-linecap="round" color="${ICON_MARK}">${RING}</g></svg>`;
+}
+export function groundLayer() {
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="${ICON_GROUND}"/></svg>`;
+}
+// The mark as an app icon, on its ground. `radius` is the corner in the
+// viewBox's own units: 0 for a full square, which is what iOS and Android
+// want since the platform masks it, and a rounded one for macOS, which
+// masks nothing and where every icon in the dock is a rounded square with
+// air around it.
+export function iconSVG(radius = 0) {
+    const inset = radius === 0 ? 0 : 5;
+    const size = 64 - inset * 2;
+    const glyph = radius === 0 ? '' : ` transform="translate(${inset} ${inset}) scale(${size / 64})"`;
+    return [
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">',
+        `<rect x="${inset}" y="${inset}" width="${size}" height="${size}" rx="${radius}" fill="${ICON_GROUND}"/>`,
+        `<g${glyph} fill="none" stroke="${ICON_MARK}" stroke-width="4" stroke-linecap="round" color="${ICON_MARK}">${RING}</g>`,
+        '</svg>',
+    ].join('');
+}

package/dist/human/move.d.ts

@@ -0,0 +1,17 @@
+import type { Harbor } from '@nervur-org/nervur/harbor';
+import type { Invitation } from '@nervur-org/nervur';
+import { type World } from './worlds.ts';
+export declare const COURIER = "courier";
+export type Giving = {
+    offer: string;
+    invitation: Invitation;
+    moved: Promise<string>;
+    close(): Promise<void>;
+};
+export declare function giveWorld(harbor: Harbor, world: World, at: string): Promise<Giving>;
+export declare function takeWorld(harbor: Harbor, invitation: Invitation): Promise<{
+    took: string;
+    world: World;
+} | {
+    error: string;
+}>;

package/dist/human/move.js

@@ -0,0 +1,90 @@
+import { arithmetic } from '@nervur-org/nervur/ward';
+import { Courier, MOVER } from '../beings/courier.js';
+import { link } from '../beings/link.js';
+import { localName } from './worlds.js';
+const { hex, unhex } = arithmetic;
+// The ward a device's courier lives in, minted when a move starts and gone
+// when it ends: nothing of a move outlives it.
+export const COURIER = 'courier';
+const KEY = 'courier';
+async function courier(harbor) {
+    const ward = harbor.wards.get(COURIER) ?? (await harbor.create(COURIER, 'me'));
+    if (!ward.being(KEY)) {
+        const out = (await ward.ask('boot', { key: KEY, class: 'Courier' }));
+        if (out.error)
+            throw new Error(`no courier on this device: ${out.error}`);
+    }
+    return ward.being(KEY);
+}
+const away = async (harbor) => {
+    const c = harbor.wards.get(COURIER)?.being(KEY);
+    if (c) {
+        c.giving = undefined;
+        c.gone = undefined;
+    }
+    await harbor.drop(COURIER);
+};
+// This device, offering one world to whichever device takes the offer.
+// `at` is the rendezvous this device dials, which is the world's own `quo.`
+// route: the other device has no reach to anything yet and this is what it
+// dials to answer.
+export async function giveWorld(harbor, world, at) {
+    const name = localName(world.pk);
+    if (!harbor.wards.has(name))
+        throw new Error('this device does not hold that world');
+    const c = await courier(harbor);
+    const invitation = await c.invite(MOVER);
+    if (!invitation) {
+        await away(harbor);
+        throw new Error('this device is already offering a world');
+    }
+    let landed = () => { };
+    const moved = new Promise((ok) => (landed = ok));
+    c.giving = async () => {
+        const ward = harbor.wards.get(name);
+        if (!ward)
+            return { error: 'this device no longer holds that world' };
+        await ward.save();
+        const kept = await harbor.store.load(name);
+        if (!kept)
+            return { error: 'this device no longer holds that world' };
+        // The partition crosses as the values it is: a ward's partition is
+        // I-JSON already, since that is all a ward ever writes into one.
+        return { world: world.pk, at: world.at, name: world.name, seed: hex(kept.seed), partition: kept.partition, record: kept.record };
+    };
+    c.gone = async () => {
+        const gone = await harbor.drop(name);
+        if (!gone)
+            return { error: 'this device no longer holds that world' };
+        landed(world.pk);
+        return { deleted: world.pk };
+    };
+    await harbor.wards.get(COURIER).save();
+    return { offer: link(at, invitation), invitation, moved, close: () => away(harbor) };
+}
+// This device, taking the world the other one offers. The harbor must
+// already be dialing the reach note in the offer: dialing is the shell's,
+// since only a shell knows which harbor its terrain gave it.
+export async function takeWorld(harbor, invitation) {
+    const c = await courier(harbor);
+    try {
+        const moving = await c.fetch(invitation);
+        if ('error' in moving)
+            return moving;
+        const name = localName(moving.world);
+        if (harbor.wards.has(name))
+            return { error: 'this device is already in that world' };
+        const hosted = await harbor.adopt(name, { seed: unhex(moving.seed), partition: moving.partition, record: moving.record });
+        // it is here: the other device may let go, and if that word never
+        // arrives the human is told, since two copies is what the next move
+        // has to be told about
+        const let_go = await c.landed();
+        return 'error' in let_go ? { error: `it is here, but the other device still has it: ${let_go.error}` } : { took: hosted.pk, world: { pk: moving.world, at: moving.at, name: moving.name } };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    finally {
+        await away(harbor);
+    }
+}

package/dist/human/screen.d.ts

@@ -0,0 +1,19 @@
+import { type Serving, type Subject } from '../beings/side.ts';
+import type { Invitation } from '@nervur-org/nervur';
+import { type Model, type Raw } from './html.ts';
+export type Surface = {
+    show(html: string): void;
+    onSubmit: ((ask: string, raw: Raw) => void) | undefined;
+};
+export type Options = {
+    after?: () => Promise<void>;
+    notice?: string;
+    admit?: (invitation: Invitation) => Promise<void>;
+    focus?: string;
+    at?: string;
+    ended?: () => Promise<void>;
+};
+export declare function screenSide(avatar: Subject, surface: Surface, options?: Options): Promise<Serving & {
+    model: Model;
+    refresh(): Promise<void>;
+}>;

package/dist/human/screen.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+// The human side: one avatar, one surface. The surface is the least a
+// screen can be: it shows a page and hands back a submitted form, and that
+// is all this side asks of a terrain. A DOM is one surface; a test is
+// another. The side keeps the model, speaks it as a page after every change
+// through `html.ts`, calls the avatar when a form comes back, and re-asks
+// her describe after each call, so a digest that moved is a page that
+// moved. A push is appended and shown the moment it lands.
+import { digest } from '@nervur-org/nervur';
+import { word } from '../beings/side.js';
+import { isInvitation } from '@nervur-org/nervur';
+import { page, values, hintFor, mine, asks, standing, stands } from './html.js';
+import { sanitiseTree, answersIn } from './tree.js';
+import { groups, sanitise } from '../beings/look.js';
+import { isSilence, isWord } from '@nervur-org/nervur';
+export async function screenSide(avatar, surface, options = {}) {
+    const after = options.after ?? (async () => { });
+    const notice = options.notice ?? '';
+    const model = { blueprint: null, look: {}, tree: null, pages: {}, notice, standing: 'in', answers: {}, pushes: [], ...(options.focus !== undefined ? { focus: options.focus } : {}), ...(options.at !== undefined ? { at: options.at } : {}) };
+    let seen = null;
+    const show = () => surface.show(page(model));
+    // Her describe, again: the page follows the digest.
+    const refresh = async () => {
+        const bp = await avatar.tools();
+        if ('error' in bp && !('asks' in bp)) {
+            // the last page she gave stays, with the answers under it, and the
+            // notice says where the human stands now: her relation ended, the
+            // world away for the moment, or her own error, told apart because
+            // only one of the three is over
+            model.standing = standing(bp.error);
+            model.notice = stands(bp.error);
+            if (model.standing === 'ended')
+                await options.ended?.();
+        }
+        else {
+            model.standing = 'in';
+            const d = await digest(bp);
+            const moved = d !== seen;
+            if (moved) {
+                seen = d;
+                model.blueprint = bp;
+                for (const k of Object.keys(model.answers))
+                    if (!bp.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.asks.some((a) => a.name === 'look')) {
+                    const l = await avatar.call('look');
+                    model.look = isSilence(l) || isWord(l) ? {} : sanitise(l);
+                }
+                else
+                    model.look = {};
+            }
+            // her page, after every ask: a tree of values from what she holds now, or nothing and her asks
+            // are forms. A cell moved is a page moved, and her describe need not have; so the answers the
+            // page shows are run again with it, and the page never stands more than one ask behind her
+            const trees = () => [model.tree ? answersIn(model.tree) : [], ...Object.entries(model.pages).map(([id, t]) => (t ? answersIn(t).map((n) => `${id}-${n}`) : []))].flat();
+            const shows = new Set(trees());
+            const tree = async (name) => {
+                const t = await avatar.call(name);
+                return isSilence(t) || isWord(t) ? null : sanitiseTree(t);
+            };
+            model.tree = bp.asks.some((a) => a.name === 'page') ? await tree('page') : null;
+            // and the page of every standing she carries, the same way, painted in that standing's section;
+            // a name a carried page uses is one of that standing's asks, carried, and nothing else
+            model.pages = {};
+            for (const [id, g] of Object.entries(groups(bp)))
+                if (typeof g.page === 'string' && bp.asks.some((a) => a.name === g.page))
+                    model.pages[id] = await tree(g.page);
+            const wanted = new Set(trees());
+            for (const n of shows)
+                if (wanted.has(n))
+                    delete model.answers[n];
+            // a read-only ask that needs nothing typed is run on her behalf once per digest, and one her page
+            // shows the answer of after every ask, so the page opens and stays with what it shows
+            for (const a of bp.asks) {
+                // What the side fills for itself is not something a human has to
+                // type, so an ask whose only required argument is the moment has
+                // nothing left to ask and runs like one with no arguments at all.
+                const needs = asks(a).length > 0;
+                const run = wanted.has(a.name) || (moved && hintFor(bp, model.look, a.name).readOnly);
+                if (run && !needs && !(a.name in model.answers))
+                    model.answers[a.name] = word(await avatar.call(a.name, mine(a)));
+            }
+        }
+        await after();
+        show();
+    };
+    surface.onSubmit = (name, raw) => void submit(name, raw);
+    const submit = async (name, raw) => {
+        const ask = model.blueprint?.asks.find((a) => a.name === name);
+        if (!ask)
+            return;
+        const v = values(ask, raw);
+        if ('error' in v) {
+            model.answers[name] = { word: 'error', value: { error: v.error } };
+            return show();
+        }
+        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();
+    };
+    const ear = (object) => {
+        model.pushes.push(object);
+        show();
+    };
+    avatar.ears.add(ear);
+    await refresh();
+    return {
+        model,
+        refresh,
+        close: async () => {
+            avatar.ears.delete(ear);
+            surface.onSubmit = undefined;
+        },
+    };
+}

package/dist/human/style.d.ts

@@ -0,0 +1,2 @@
+export declare const CSS: string;
+export declare const BARE: string;

package/dist/human/style.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// The stylesheet: the kit, and then what the screen alone has.
+//
+// One stylesheet for every screen there is, whatever carries it: the web
+// route serves it beside the tab's bundle, and the desk app's window
+// carries it in its own. A screen that looked like another product on
+// another terrain would be two designs to keep and one of them always
+// behind. It is one string and not four files because a screen builds its
+// own page and has nowhere to put a link.
+//
+// The kit brings the tokens, its own light and dark face, the reset, the
+// baseline, the bare controls and every piece a page is made of. The
+// painter emits those pieces and nothing else, so what follows is small:
+// the page's one column, and the few things the shells alone have, the
+// door, a local being's section, moving a world, the daemon's state line.
+// Nothing below mints a colour or a size; every one is a slot or a scale,
+// so a face swapped for another swaps the screen with it. A far being's
+// look sets the kit's slots on her own section, and the kit does the rest.
+import { CSS as KIT, TOKENS, BASE, COMPONENTS } from '@nervur-org/ui/css';
+const SCREEN = [
+    // One column that is a phone first and a desk after: the same page, more
+    // air. The insets are the phone's: an app fills the screen, corners and
+    // camera and all, so the first line of the page would otherwise sit under
+    // the clock. `env()` is zero everywhere else, so a tab and a window are
+    // laid out by the gutter alone.
+    'body{max-width:var(--nv-page-w-md);margin-inline:auto;padding-inline:calc(var(--nv-page-gutter) + env(safe-area-inset-left)) calc(var(--nv-page-gutter) + env(safe-area-inset-right));padding-block:env(safe-area-inset-top) calc(var(--nv-space-8) + env(safe-area-inset-bottom))}',
+    'main{display:flex;flex-direction:column;gap:var(--nv-space-4)}',
+    // a subsection holding a form and the answer under it, and the sections
+    // of one being's page after another
+    'main>.nv-stack>section+section,main>.nv-stack>section+.nv-standing,main>.nv-stack>.nv-standing+section{margin-block-start:var(--nv-space-3)}',
+    // a far being's logo beside her name, and the way to her own page
+    'img.logo{height:var(--nv-icon-lg)}a.open,a.back{text-decoration:none;font-weight:var(--nv-weight-medium)}a.back::before{content:"\\2190  "}',
+    // A place the side vouches for reads as a place to go. One it will not
+    // vouch for reads as what it is, an address the human may copy and weigh,
+    // and it is deliberately not underlined and not the accent: it must never
+    // look like something the page is willing to stand behind. A link that
+    // leaves the world wears the origin it goes to, out of the anchor's own
+    // data, so a human reads where she is going on the page rather than in a
+    // status bar she may never look at.
+    'a.link.out::after{content:" \\2197 " attr(data-origin);font-size:var(--nv-text-sm);color:var(--nv-color-fg-muted)}span.link.away{border:1px dashed var(--nv-color-border-strong)}',
+    // a being of the world running in the tab: her own section under the far page
+    'section.local{border-block-start:1px solid var(--nv-color-border);margin-block:var(--nv-space-5) 0;padding-block-start:var(--nv-space-3)}',
+    // moving a world to another device, and leaving one: quiet, at the foot
+    // of the page, and the offer wrapping rather than running off the side,
+    // since it is one long word
+    '.move,section.held{display:flex;flex-direction:column;gap:var(--nv-space-2);align-items:flex-start;border-block-start:1px solid var(--nv-color-border);margin-block:var(--nv-space-7) 0;padding-block-start:var(--nv-space-3);font-size:var(--nv-text-sm);color:var(--nv-color-fg-muted)}.move .invitation,section.held .invitation{font-family:var(--nv-font-mono);font-size:var(--nv-text-xs);overflow-wrap:anywhere}',
+    'section.held .worlds{display:flex;flex-wrap:wrap;gap:var(--nv-space-2)}',
+    // a foot the shell hid stays hidden: a class that lays it out would otherwise beat the attribute
+    '.move[hidden],section.held[hidden]{display:none}',
+    // the door page: one thing on air, vertically centred in the window
+    'main[data-door]{min-height:70vh;justify-content:center}main[data-door] .nv-picture{width:var(--nv-space-7);height:var(--nv-space-7);color:var(--nv-color-accent)}',
+    // the desk window: the state of the daemon behind the page, a line, and nothing when all is well
+    'p.state:empty{display:none}',
+].join('');
+export const CSS = `${KIT}\n${SCREEN}`;
+// The same screen for a world that wears a design of its own: the kit
+// without its own face, since the kit's contract says a surface loads the
+// default face or a design's and never both, and the design's stylesheet
+// is linked after it by the route that serves it.
+export const BARE = `${TOKENS}\n${BASE}\n${COMPONENTS}\n${SCREEN}`;