getbotons 0.0.0-stage → 0.1.0

package/payload/shared/handoff.ts

@@ -0,0 +1,97 @@
+/*
+ * A Boton's handoff of its managed browser to the owner, as data: the Boton asks (browser_handoff, with a short
+ * reason) when a step is the owner's (a sign-in, a captcha, a code), the chat shows a card with Take over, and the
+ * owner drives the browser in an overlay over the chat until they hand it back. The card is one chat event whose meta
+ * holds this record; the server moves it through these states and nothing else does:
+ *
+ *   requested ──take──▶ taken ──hand back──▶ handed-back
+ *       └──────close──▶ closed (the Boton asked again, its browser was turned off, or nobody took it in time)
+ *
+ * Taking over is the existing handover (browser-handover.ts), with all of its rules: the Boton's browser closes and its
+ * tools are refused until the owner finishes, and what the owner types goes into the page and nowhere else. Handing
+ * back (or the handover ending any other way) wakes the Boton with a note of where the page is now.
+ *
+ * This file is shared by the server and the web app, and imports nothing.
+ */
+
+export type HandoffState = 'requested' | 'taken' | 'handed-back' | 'closed';
+
+export interface BrowserHandoff {
+  state: HandoffState;
+  /** The Boton's own words for why, cleaned and short: shown as its words, never as the server's. */
+  reason: string;
+  /** Where its browser was when it asked (origin and path only), or null. */
+  url: string | null;
+  requestedAt: string;
+  /** A request nobody took by then is closed. */
+  expiresAt: string;
+  takenAt?: string;
+  /** The device that took it over, as the server names it. */
+  takenBy?: string;
+  handedBackAt?: string;
+  /** Where the owner left the page (origin and path only), or null when no page was open. */
+  page?: string | null;
+  /** How the handover ended: `finished` when the owner handed it back, else why it ended on its own. */
+  how?: string;
+  /** closed: why, in the server's words. */
+  why?: string;
+}
+
+export type HandoffEvent =
+  | { type: 'take'; at: string; by: string }
+  | { type: 'hand-back'; at: string; page: string | null; how: string }
+  | { type: 'close'; at: string; why: string };
+
+export const HANDOFF_REASON_MAX = 200;
+/** How long a request waits to be taken. */
+export const HANDOFF_TTL_MS = 24 * 3_600_000;
+
+/** The reason a Boton gave, cleaned (control and invisible characters out, one line, trimmed), or why it can't be used. */
+export function handoffReason(raw: unknown): string | { why: string } {
+  if (typeof raw !== 'string') return { why: 'reason must be a short text, such as "Sign in to example.com"' };
+  const t = raw
+    .replace(/[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!t) return { why: 'reason must say what the owner should do, such as "Sign in to example.com"' };
+  if (t.length > HANDOFF_REASON_MAX) return { why: `reason is too long (at most ${HANDOFF_REASON_MAX} characters)` };
+  return t;
+}
+
+/** A new request, as the Boton made it. */
+export function requestHandoff(reason: string, url: string | null, at: Date): BrowserHandoff {
+  return { state: 'requested', reason, url, requestedAt: at.toISOString(), expiresAt: new Date(at.getTime() + HANDOFF_TTL_MS).toISOString() };
+}
+
+/** Still waiting on the owner to take it: requested and not past its expiry. */
+export function handoffWaiting(h: BrowserHandoff, now: string): boolean {
+  return h.state === 'requested' && h.expiresAt > now;
+}
+
+/** Open: waiting to be taken, or taken and not yet handed back. */
+export function handoffOpen(h: BrowserHandoff, now: string): boolean {
+  return handoffWaiting(h, now) || h.state === 'taken';
+}
+
+/**
+ * The record after `e`, or null when `e` can't happen from where it stands: only a waiting request is taken (a
+ * second take of a taken one changes nothing and is null too), only a taken one is handed back, and only a waiting
+ * one is closed. A request past its expiry can only be closed.
+ */
+export function handoffStep(h: BrowserHandoff, e: HandoffEvent): BrowserHandoff | null {
+  switch (e.type) {
+    case 'take':
+      return handoffWaiting(h, e.at) ? { ...h, state: 'taken', takenAt: e.at, takenBy: e.by } : null;
+    case 'hand-back':
+      return h.state === 'taken' ? { ...h, state: 'handed-back', handedBackAt: e.at, page: e.page, how: e.how } : null;
+    case 'close':
+      return h.state === 'requested' ? { ...h, state: 'closed', why: e.why } : null;
+  }
+}
+
+/** What the Boton reads when it is woken by the hand-back: the server's words, never the owner's. */
+export function handBackNote(owner: string, h: BrowserHandoff): string {
+  const done = h.how === 'finished' ? `${owner} finished in your browser and handed it back` : `${owner}'s turn in your browser ended (${h.how ?? 'it ended'})`;
+  const page = h.page ? ` The page is now ${h.page}: open it to go on.` : ' No page was open.';
+  return `(From the Botons server: ${done}. You asked for: “${h.reason}”.${page} Read it before you assume the step worked.)`;
+}

package/payload/shared/install-commands.ts

@@ -0,0 +1,7 @@
+export type InstallType = 'managed' | 'docker' | 'service';
+/** Arguments are hints for a human, never executed by a shell. */
+export function installCommand(type: InstallType, action: 'pair' | 'backup' | 'restore' | 'doctor' | 'repair' | 'serve', args = ''): string {
+  if (action === 'repair') return type === 'service' ? 'npm run build' : type === 'docker' ? 'docker compose up -d --build botons' : '~/.local/bin/botons repair';
+  const base = type === 'docker' ? `docker compose exec botons botons ${action}` : type === 'managed' ? `~/.local/bin/botons ${action}` : `npm run ${action}`;
+  return base + (args ? `${type === 'service' ? ' --' : ''} ${args}` : '');
+}

package/payload/shared/legacy-names.d.mts

@@ -0,0 +1,35 @@
+// Types for legacy-names.mjs (see there).
+export interface LegacyEnvNotice {
+  /** The earlier name that is set. */
+  old: string;
+  /** Its current name. */
+  name: string;
+  /** Both are set, to different values: `name`'s is used. */
+  conflict: boolean;
+}
+export const ENV_PREFIXES: readonly (readonly [old: string, now: string])[];
+export function currentEnvName(name: string): string | null;
+export function earlierEnvNames(name: string): string[];
+export function applyLegacyEnv(env: Record<string, string | undefined>): LegacyEnvNotice[];
+export function legacyEnvNoticeText(n: LegacyEnvNotice): string;
+export function isLegacySetting(name: string): boolean;
+export function withLegacyTurnNames(env: Record<string, string>): Record<string, string>;
+export function rewriteEnvText(text: string, moves?: readonly (readonly [from: string, to: string])[]): string;
+export const DATA_DIRS: readonly string[];
+export const CONFIG_DIRS: readonly string[];
+export const SHARE_DIRS: readonly string[];
+export const DB_FILE: string;
+export const UNITS: readonly { readonly service: string; readonly backup: string }[];
+export const CLI_NAMES: readonly string[];
+export const IMAGE_CLI_NAMES: readonly string[];
+export const PATH_BLOCK_NAMES: readonly string[];
+export const RENAMED: Readonly<Record<string, string>>;
+export function earlierName(now: string): string | null;
+export function currentName(value: string): string;
+export function storedValue(storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>, key: string): string | null;
+export function currentPortable<T>(file: T): T;
+export const PRIVATE_TERMS_FILES: readonly string[];
+export function earlierStorageKey(key: string): string | null;
+export const OLD_TEXT: RegExp;
+export const OLD_WORD: RegExp;
+export const FORMERLY: RegExp;

package/payload/shared/legacy-names.mjs

@@ -0,0 +1,244 @@
+// LEGACY NAMES: the one place that knows what Botons was called before (Minions, then Tots).
+//
+// Everything that still reads, accepts or moves an earlier name gets it from this file, for one release after the
+// rename. To drop them: delete this file and legacy-names.d.mts, delete server/src/legacy-upgrade.ts,
+// scripts/migrate-names.ts, docker/legacy-names.sh and server/test/legacy-names.test.ts, then fix what the type
+// checker lists. None of these names may appear in docs, help text or the app; doctor names them once, as
+// deprecated. Plain JavaScript with no imports, so the server, its scripts, the web app and the installer (which
+// may run on an older Node) can all load it.
+
+/** The earlier names as words in text, in any case (check:firstrun looks for them on every screen). */
+export const OLD_TEXT = /\b(minions?|tots?)\b/i;
+
+/** Earlier setting prefixes and their current ones, newest first: where two are set, the newer one wins. */
+export const ENV_PREFIXES = Object.freeze([
+  ['TOTS_', 'BOTONS_'],
+  ['TOT_', 'BOTON_'],
+  ['MINIONS_', 'BOTONS_'],
+  ['MINION_', 'BOTON_'],
+]);
+
+/** The current name of an earlier setting name, or null when `name` is not one. */
+export function currentEnvName(name) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(name)) return null;
+  for (const [old, now] of ENV_PREFIXES) if (name.startsWith(old) && name.length > old.length) return now + name.slice(old.length);
+  return null;
+}
+
+/** The earlier names of a current setting name, newest first (none when it has no earlier names). */
+export function earlierEnvNames(name) {
+  const out = [];
+  for (const [old, now] of ENV_PREFIXES) if (name.startsWith(now) && name.length > now.length) out.push(old + name.slice(now.length));
+  return out;
+}
+
+const isSet = (v) => v !== undefined && v !== null && String(v).trim() !== '';
+const rank = (name) => ENV_PREFIXES.findIndex(([old]) => name.startsWith(old));
+
+/**
+ * Reads each earlier setting name as its current one, in place: where the current name is unset, it gets the
+ * newest earlier name's value. Earlier names are left as they are. Idempotent. One notice per earlier name that is
+ * set: `conflict` when its value differs from the one used. Notices name variables, never values.
+ */
+export function applyLegacyEnv(env) {
+  const notices = [];
+  const olds = Object.keys(env)
+    .filter((k) => currentEnvName(k) && isSet(env[k]))
+    .sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : 1));
+  for (const old of olds) {
+    const name = currentEnvName(old);
+    if (!isSet(env[name])) {
+      env[name] = env[old];
+      notices.push({ old, name, conflict: false });
+    } else notices.push({ old, name, conflict: String(env[name]).trim() !== String(env[old]).trim() });
+  }
+  return notices;
+}
+
+/** Doctor's one line about a notice: names only. */
+export function legacyEnvNoticeText(n) {
+  return n.conflict
+    ? `${n.old} (deprecated) and ${n.name} are both set, to different values: ${n.name} is used. Remove ${n.old}.`
+    : `${n.old} is deprecated and works for this release only: rename it to ${n.name}.`;
+}
+
+/** True for an earlier setting name. */
+export const isLegacySetting = (name) => currentEnvName(name) !== null;
+
+/**
+ * A turn's variables under their earlier names too (BOTON_TOKEN also as the two earlier names), for one release,
+ * so an agent's own scripts and saved procedures keep working. The values are the same, so nothing more is exposed.
+ */
+export function withLegacyTurnNames(env) {
+  const out = { ...env };
+  for (const [k, v] of Object.entries(env)) for (const old of earlierEnvNames(k)) if (out[old] === undefined) out[old] = v;
+  return out;
+}
+
+/**
+ * An env file's text with each earlier setting name written as its current one, and each path in `moves`
+ * ([from, to]) as its new path. Where a setting is set under more than one name, only the line the server would use
+ * stays (the current name, else the newest earlier one), so the file means what it meant.
+ */
+export function rewriteEnvText(text, moves = []) {
+  const lines = text.split('\n');
+  const parse = (line) => /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+  const valueOf = (raw) => (/^"(.*)"$/.test(raw) || /^'(.*)'$/.test(raw) ? raw.slice(1, -1) : raw);
+  // The line whose value the server uses for each setting: the current name's, else the newest earlier name's, and
+  // an empty value counts as unset (as applyLegacyEnv reads them). The last of the same name wins, as in a shell.
+  // A name assigned twice means its last assignment (an empty one too): only that line counts.
+  const last = new Map();
+  lines.forEach((line, i) => {
+    const m = parse(line);
+    if (m) last.set(m[1], i);
+  });
+  const winner = new Map();
+  lines.forEach((line, i) => {
+    const m = parse(line);
+    if (!m || last.get(m[1]) !== i) return;
+    const now = currentEnvName(m[1]) ?? m[1];
+    const r = currentEnvName(m[1]) ? rank(m[1]) : -1;
+    const set = isSet(valueOf(m[2]));
+    const best = winner.get(now);
+    const better = !best || (set && !best.set) || (set === best.set && (r < best.r || (r === best.r && i > best.i)));
+    if (better) winner.set(now, { i, r, set, legacy: (best?.legacy ?? false) || r >= 0 });
+    else best.legacy ||= r >= 0;
+  });
+  for (const [name] of last) if (currentEnvName(name)) winner.get(currentEnvName(name)).legacy = true;
+  const out = [];
+  lines.forEach((line, i) => {
+    const m = parse(line);
+    let next = line;
+    if (m) {
+      const now = currentEnvName(m[1]) ?? m[1];
+      // Only settings with an earlier name lose lines; anything else stays as it was written.
+      if (winner.get(now).legacy && winner.get(now).i !== i) return;
+      if (now !== m[1]) next = line.replace(m[1], now);
+      for (const [from, to] of moves) next = replacePathPrefix(next, from, to);
+    }
+    out.push(next);
+  });
+  return out.join('\n');
+}
+
+/** `text` with each whole-path occurrence of `from` (followed by /, a quote, a separator or the end) as `to`. */
+function replacePathPrefix(text, from, to) {
+  const esc = from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return text.replace(new RegExp(`${esc}(?=$|[/"':;\\s])`, 'g'), to);
+}
+
+/** Earlier data folders under the user's home, newest first. The current one is ~/.botons. */
+export const DATA_DIRS = Object.freeze(['.tots', '.minions']);
+/** Earlier settings folders under XDG_CONFIG_HOME (~/.config), each with an `env` file. */
+export const CONFIG_DIRS = Object.freeze(['tots', 'minions']);
+/** Earlier release roots under ~/.local/share (deploy's and the installer's). */
+export const SHARE_DIRS = Object.freeze(['tots', 'minions']);
+/** The database's earlier file name. */
+export const DB_FILE = 'minions.db';
+/** Earlier systemd user units: the server's, and its nightly backup's (a .service and a .timer). */
+export const UNITS = Object.freeze([
+  { service: 'tots', backup: 'tots-backup' },
+  { service: 'minions', backup: 'minions-backup' },
+]);
+/** Earlier names of the Botons command (the agents' CLI and the installer's admin command). */
+export const CLI_NAMES = Object.freeze(['tots', 'minion']);
+/** Earlier names in the marked PATH block the installer adds to a shell's rc file. */
+export const PATH_BLOCK_NAMES = Object.freeze(['tots']);
+/** Earlier names of check:public's private terms list in ~/.config/private-terms (outside the repo). */
+export const PRIVATE_TERMS_FILES = Object.freeze(['minions.txt']);
+/** Earlier names of the image's admin command (docker/botons); the Dockerfile links each to it. */
+export const IMAGE_CLI_NAMES = Object.freeze(['tots', 'minions']);
+
+/**
+ * Earlier names of what the server stores, sends and reads back, by their current name: an actor's kind (audit
+ * events, reactions, turn tokens), the managed browser's connector, export file formats, webhook and callback
+ * headers. Data under them is moved by the schema upgrade, read on import, accepted or sent beside the current one.
+ */
+export const RENAMED = Object.freeze({
+  boton: 'minion',
+  botons_browser: 'minions_browser',
+  'botons-config': 'minions-config',
+  'botons-sidebar': 'minions-sidebar',
+  'botons-reactions': 'minions-reactions',
+  'x-boton-key': 'x-minion-key',
+  'x-boton-signature': 'x-minion-signature',
+  'x-boton-run': 'x-minion-run',
+});
+/** The earlier name of a renamed value, or null. */
+export const earlierName = (now) => (Object.hasOwn(RENAMED, now) ? RENAMED[now] : null);
+/** The current name of a value, if it is an earlier one; otherwise the value itself. */
+export function currentName(value) {
+  for (const [now, old] of Object.entries(RENAMED)) if (value === old) return now;
+  return value;
+}
+
+/** Earlier keys of the web app's own storage on a device, by current key (or key prefix, ending in "."). */
+const STORAGE = Object.freeze({
+  'botons.deviceToken': 'minions.deviceToken',
+  'botons.avatarMotion': 'minions.avatarMotion',
+  'botons.webAccessSuggestion.': 'tots.webAccessSuggestion.',
+  'botons.theme': 'tots.theme',
+});
+/** A storage key's earlier name, or null (for web/index.html's first paint, which runs before any module loads). */
+export const earlierStorageKey = (key) => (Object.hasOwn(STORAGE, key) ? STORAGE[key] : null);
+/**
+ * `key`'s value in `storage`, taken over from its earlier key the first time (written under `key`, the earlier one
+ * removed), so a device stays paired and keeps its choices. Null when neither is set.
+ */
+export function storedValue(storage, key) {
+  const now = storage.getItem(key);
+  if (now !== null) return now;
+  const entry = Object.entries(STORAGE).find(([k]) => k === key || (k.endsWith('.') && key.startsWith(k)));
+  if (!entry) return null;
+  const old = entry[0] === key ? entry[1] : entry[1] + key.slice(entry[0].length);
+  const value = storage.getItem(old);
+  if (value === null) return null;
+  try {
+    storage.setItem(key, value);
+    storage.removeItem(old);
+  } catch {}
+  return value;
+}
+
+/**
+ * A configuration export made under an earlier name, with the names this server reads: its format, its Botons'
+ * list and the primary Boton's setting, its sidebar's format, a skill's author kind and the managed browser's
+ * connector id. Anything
+ * else is left as it is; a file under the current names comes back unchanged.
+ */
+export function currentPortable(file) {
+  if (!file || typeof file !== 'object' || Array.isArray(file) || file.format !== RENAMED['botons-config']) return file;
+  const browser = `lib:${RENAMED.botons_browser}`;
+  const out = { ...file, format: 'botons-config' };
+  // An owner's own connector already named as the browser is now takes a free name first, with every grant of it.
+  const map = new Map([[browser, 'lib:botons_browser']]);
+  const connectors = Array.isArray(out.connectors) ? out.connectors : [];
+  if (connectors.some((c) => c && (c.id === 'lib:botons_browser' || c.name === 'botons_browser'))) {
+    const used = new Set(connectors.map((c) => c && c.name));
+    let n = 2;
+    while (used.has(`botons_browser_${n}`)) n++;
+    map.set('lib:botons_browser', `lib:botons_browser_${n}`);
+    out.connectors = connectors.map((c) => (c && (c.id === 'lib:botons_browser' || c.name === 'botons_browser') ? { ...c, id: `lib:botons_browser_${n}`, name: `botons_browser_${n}` } : c));
+  }
+  const ids = (v) => (Array.isArray(v) ? v.map((x) => map.get(x) ?? x) : v);
+  if (Array.isArray(out.connectors)) out.connectors = out.connectors.map((c) => (c && c.id === browser ? { ...c, id: 'lib:botons_browser', name: 'botons_browser' } : c));
+  if ('minions' in out) {
+    out.botons = Array.isArray(out.minions) ? out.minions.map((m) => (m && typeof m === 'object' && !Array.isArray(m) ? { ...m, connections: ids(m.connections) } : m)) : out.minions;
+    delete out.minions;
+  }
+  if (out.settings && typeof out.settings === 'object' && !Array.isArray(out.settings) && 'primaryMinion' in out.settings) {
+    const { primaryMinion, ...settings } = out.settings;
+    out.settings = { ...settings, primaryBoton: primaryMinion };
+  }
+  if (out.sidebar && typeof out.sidebar === 'object' && out.sidebar.format === RENAMED['botons-sidebar']) out.sidebar = { ...out.sidebar, format: 'botons-sidebar' };
+  if (Array.isArray(out.skills)) {
+    out.skills = out.skills.map((k) => (k && typeof k === 'object' && k.author && typeof k.author === 'object' && k.author.kind === RENAMED.boton ? { ...k, author: { ...k.author, kind: 'boton' } } : k));
+  }
+  if (Array.isArray(out.templates)) out.templates = out.templates.map((t) => (t && typeof t === 'object' && t.bot && typeof t.bot === 'object' ? { ...t, bot: { ...t.bot, connections: ids(t.bot.connections) } } : t));
+  return out;
+}
+
+/** The earlier names themselves, as words: check:public refuses them anywhere this module doesn't allow (oldNames). */
+export const OLD_WORD = /^(minions?|tots?)$/i;
+/** The changelog's one line that says what the product was called before. */
+export const FORMERLY = /\(formerly Minions, and then Tots\)/;

package/payload/shared/live-view.ts

@@ -0,0 +1,94 @@
+/*
+ * The live view of a handover (the owner driving a Boton's browser), as pure parts both sides use: the stream's
+ * chunks, and where a point on the owner's screen lands in the page.
+ *
+ * The stream is one long response of chunks, each a kind byte, a 4-byte big-endian length, then that many bytes:
+ * LIVE_FRAME is a frame (2 bytes each of its CSS width and height, then the JPEG), LIVE_NOTICE a notice (UTF-8
+ * JSON, a HandoverNotice). It imports nothing.
+ */
+
+export const LIVE_FRAME = 1;
+export const LIVE_NOTICE = 2;
+/** No chunk is longer (a frame of the largest page at twice its pixels is far less). */
+export const LIVE_CHUNK_MAX = 16 * 1024 * 1024;
+
+function chunk(kind: number, payload: Uint8Array): Uint8Array {
+  const out = new Uint8Array(5 + payload.length);
+  out[0] = kind;
+  new DataView(out.buffer).setUint32(1, payload.length);
+  out.set(payload, 5);
+  return out;
+}
+
+export function liveFrame(jpeg: Uint8Array, width: number, height: number): Uint8Array {
+  const body = new Uint8Array(4 + jpeg.length);
+  const v = new DataView(body.buffer);
+  v.setUint16(0, Math.max(0, Math.min(0xffff, Math.round(width))));
+  v.setUint16(2, Math.max(0, Math.min(0xffff, Math.round(height))));
+  body.set(jpeg, 4);
+  return chunk(LIVE_FRAME, body);
+}
+
+export function liveNotice(notice: unknown): Uint8Array {
+  return chunk(LIVE_NOTICE, new TextEncoder().encode(JSON.stringify(notice)));
+}
+
+export type LiveChunk = { kind: 'frame'; width: number; height: number; jpeg: Uint8Array } | { kind: 'notice'; notice: unknown };
+
+/** Reads chunks from the stream's bytes as they arrive, in whatever pieces the network gives them. */
+export class LiveParser {
+  #buf = new Uint8Array(0);
+
+  push(piece: Uint8Array): LiveChunk[] {
+    const joined = new Uint8Array(this.#buf.length + piece.length);
+    joined.set(this.#buf);
+    joined.set(piece, this.#buf.length);
+    const out: LiveChunk[] = [];
+    let at = 0;
+    while (joined.length - at >= 5) {
+      const v = new DataView(joined.buffer, joined.byteOffset + at);
+      const kind = v.getUint8(0);
+      const len = v.getUint32(1);
+      if (len > LIVE_CHUNK_MAX) throw new Error('The live view sent a chunk too large to be one');
+      if (joined.length - at - 5 < len) break;
+      const body = joined.slice(at + 5, at + 5 + len);
+      at += 5 + len;
+      if (kind === LIVE_FRAME && body.length >= 4) {
+        const b = new DataView(body.buffer);
+        out.push({ kind: 'frame', width: b.getUint16(0), height: b.getUint16(2), jpeg: body.slice(4) });
+      } else if (kind === LIVE_NOTICE) {
+        try {
+          out.push({ kind: 'notice', notice: JSON.parse(new TextDecoder().decode(body)) });
+        } catch {}
+      }
+    }
+    this.#buf = joined.slice(at);
+    return out;
+  }
+}
+
+export interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Where the owner's pointer at (`clientX`, `clientY`) lands in the page: `box` is the view's box on screen, in which
+ * the frame is drawn whole and centred (object-fit: contain, so a frame of another shape leaves bands), and `page` the
+ * page's size in CSS pixels that the frame shows. Null on a band or outside the frame. Screen pixel ratios cancel out:
+ * the box and the client point are both CSS pixels of the owner's screen, and the page is CSS pixels of the page.
+ */
+export function toPagePoint(clientX: number, clientY: number, box: Rect, page: { width: number; height: number }): { x: number; y: number } | null {
+  if (!(box.width > 0 && box.height > 0 && page.width > 0 && page.height > 0)) return null;
+  const scale = Math.min(box.width / page.width, box.height / page.height);
+  const drawnW = page.width * scale;
+  const drawnH = page.height * scale;
+  const left = box.left + (box.width - drawnW) / 2;
+  const top = box.top + (box.height - drawnH) / 2;
+  const x = (clientX - left) / scale;
+  const y = (clientY - top) / scale;
+  if (x < 0 || y < 0 || x >= page.width || y >= page.height) return null;
+  return { x: Math.min(page.width - 1, Math.floor(x)), y: Math.min(page.height - 1, Math.floor(y)) };
+}