@nervur-org/dock 0.3.0

package/human/local.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// A being in the tab's own ward, as a subject the screen renders: a world's
+// code running on the device, booted from the bundle that world serves on
+// its origin. Her cells are in the tab's store and migrate with the ward;
+// her asks are the forms; her page is computed from her cells at every
+// digest, the same painter and the same side as a far being's, so one
+// grammar has two sources and no second verb. A push never reaches her:
+// nothing outside the tab holds her.
+//
+// The tab holds the ward's ask pointer, so the tab is the root owner, and
+// the subject is the owner's `ask` and nothing else: no standing and no
+// relation, since the local ward is the human's and she is on it. The ward
+// names the asker, bounds the wait, judges her answer and saves before the
+// pointer returns, so this file holds an id nobody minted no longer.
+import type { Answer, Blueprint, JsonObject } from '@nervur-org/nervur';
+import type { Subject } from '../beings/side.ts';
+
+// The ward as its root holds it: the ask pointer, and nothing else of it.
+type Owner = { ask(method?: string, args?: JsonObject): Promise<unknown> };
+
+export function local(ward: Owner, key: string): Subject {
+  // 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?: string, args: JsonObject = {}) => ward.ask('ask', method === undefined ? { being: key } : { being: key, method, args });
+  return {
+    tools: async () => (await one()) as Blueprint,
+    call: (name: string, args: JsonObject = {}) => one(name, args) as Promise<Answer>,
+    ears: new Set(),
+  };
+}

package/human/mark.ts

@@ -0,0 +1,53 @@
+// 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): string {
+  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(): string {
+  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): string {
+  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/human/move.ts

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: Apache-2.0
+// Moving a world from one device to another, as both shells do it. A device
+// holds one local ward per world, on its own seed, and everything it is in
+// that world is in there: the avatars, their standings, what each was told.
+// So a human moving a world to a new device moves that ward, whole, and
+// nothing else happens: the far world is never asked, never told and never
+// notices, because a pk is permanent and every standing still points at the
+// same ward.
+//
+// Two halves, and the being between them is `beings/courier.ts`. The device
+// giving offers: a courier in a ward of her own, an invitation minted on
+// her, and beside it the reach note of the rendezvous this device dials,
+// since the other one may dial nothing yet and a device reaches a pk only
+// through a listener it holds a socket to. Both travel as one link, and a
+// human carries them by eye or by camera. The device taking dials that
+// note, knocks, puts the ward on its harbor, and says so; the copy on the
+// device giving goes at that word and not before.
+//
+// The ward that travels is not the courier's, on either side, because a
+// ward cannot carry itself.
+import type { Harbor } from '@nervur-org/nervur/harbor';
+import type { Invitation, JsonObject } from '@nervur-org/nervur';
+import { arithmetic } from '@nervur-org/nervur/ward';
+import { Courier, MOVER } from '../beings/courier.ts';
+import { link } from '../beings/link.ts';
+import { localName, type World } from './worlds.ts';
+
+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: Harbor): Promise<Courier> {
+  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' })) as { error?: string };
+    if (out.error) throw new Error(`no courier on this device: ${out.error}`);
+  }
+  return ward.being(KEY) as Courier;
+}
+
+const away = async (harbor: Harbor) => {
+  const c = harbor.wards.get(COURIER)?.being(KEY) as Courier | undefined;
+  if (c) {
+    c.giving = undefined;
+    c.gone = undefined;
+  }
+  await harbor.drop(COURIER);
+};
+
+export type Giving = {
+  // The one thing the human carries to the other device: the invitation and
+  // the rendezvous to reach this one through, written as a link. Single-use,
+  // so one offer moves one ward.
+  offer: string;
+  invitation: Invitation;
+  // Whether the ward has gone, once the other device says it landed.
+  moved: Promise<string>;
+  // Stop offering: the courier and her ward are gone, and a knock arriving
+  // after this reaches nobody. The world stays here unless it was taken.
+  close(): Promise<void>;
+};
+
+// 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: Harbor, world: World, at: string): Promise<Giving> {
+  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: (pk: string) => void = () => {};
+  const moved = new Promise<string>((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 as JsonObject, record: kept.record as unknown as JsonObject };
+  };
+  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: Harbor, invitation: Invitation): Promise<{ took: string; world: World } | { error: string }> {
+  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 as unknown as { pk: string; code: string; user: string } });
+    // 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);
+  }
+}