@nano133/nanoterra 0.5.0 → 0.6.0

package/src/admin/store.ts

@@ -48,13 +48,13 @@ export type AdminLogin = { at: number; country: string | null; browser: string }
 export const ADMIN_LOGINS_SHOWN = 10;
 
 /**
- * The game's database, as the handler needs it. An adapter writes ONLY what these calls say: the two settings and, when the game turns it on, the deletion of the admin sessions
+ * The game's database, as the handler needs it. An adapter writes ONLY what these calls say: the three settings and, when the game turns it on, the deletion of the admin sessions
  * (`signOutEverywhere`). Nothing else.
  * (There is no call that writes a look, a price or an order: the Shelf gives text to copy, and a change of looks is a change of the repository.)
  */
 export interface AdminStore {
   /** The settings that /admin has saved. A value that is not a known word is ignored by the handler, so an adapter returns what it holds. */
-  readSettings(): Promise<{ character?: unknown; signin?: unknown }>;
+  readSettings(): Promise<{ character?: unknown; signin?: unknown; friends?: unknown }>;
   /** Saves a checked patch: all of it or none of it. */
   saveSettings(patch: GamePatch, now: number): Promise<void>;
   summary(now: number): Promise<StoreSummary>;

package/src/admin/switches.ts

@@ -1,46 +1,72 @@
-// The two switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
-// draws the card from `SWITCHES`. A switch changes ONLY these two settings; never a look, a price or an order.
+// The switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
+// draws the card from `SWITCHES` and `FRIENDS_CHOICES`. A switch changes ONLY these three settings; never a look, a price or an order.
 
 /** Which character the player is: Nanoterra's island character (the one the player has there) or the game's own. */
 export type Character = "nanoterra" | "own";
 /** How the game signs a Nanoterra player in: the code exchange, a signed ticket (a game with no server), or not at all. */
 export type Signin = "exchange" | "ticket" | "none";
-export type GameSettings = { character: Character; signin: Signin };
+/**
+ * Which friends list the game shows: Nanoterra's (the nano133 window, "@nano133/nanoterra/friends/panel"), the game's own (its own players and store), or none.
+ * A three-way choice, not an On/Off switch.
+ */
+export type Friends = "nanoterra" | "own" | "off";
+/** The game's own words for the switches. `friends` may be left out: it is "nanoterra" then (on by default). */
+export type GameSettings = { character: Character; signin: Signin; friends?: Friends };
 /** What a press can set: sign-in is on ("exchange": a game with a server) or off ("none"). */
-export type GamePatch = { character?: Character; signin?: "exchange" | "none" };
+export type GamePatch = { character?: Character; signin?: "exchange" | "none"; friends?: Friends };
 /** The settings as they are now, and which ones /admin has set (the others still have the game's default). */
-export type GameState = GameSettings & { fromAdmin: { character: boolean; signin: boolean } };
+export type GameState = { character: Character; signin: Signin; friends: Friends; fromAdmin: { character: boolean; signin: boolean; friends: boolean } };
 
 export const isCharacter = (v: unknown): v is Character => v === "nanoterra" || v === "own";
 export const isSigninChoice = (v: unknown): v is "exchange" | "none" => v === "exchange" || v === "none";
 export const isSignin = (v: unknown): v is Signin => v === "exchange" || v === "ticket" || v === "none";
+export const isFriends = (v: unknown): v is Friends => v === "nanoterra" || v === "own" || v === "off";
+/** The friends list a game shows while neither its own words nor /admin say: Nanoterra's. */
+export const DEFAULT_FRIENDS: Friends = "nanoterra";
 /** The sign-in switch is on for any way but "none". */
 export const signinOn = (s: Signin): boolean => s !== "none";
 
 /** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
 export function parsePatch(body: unknown): { ok: true; patch: GamePatch } | { ok: false; error: string } {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character" or "signin".' };
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: 'Send an object with "character", "signin" or "friends".' };
   const patch: GamePatch = {};
   for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
     if (key === "character" && isCharacter(value)) patch.character = value;
     else if (key === "signin" && isSigninChoice(value)) patch.signin = value;
+    else if (key === "friends" && isFriends(value)) patch.friends = value;
+    else if (key === "friends") return { ok: false, error: '"friends" must be "nanoterra", "own" or "off".' };
     else if (key === "character") return { ok: false, error: '"character" must be "nanoterra" or "own".' };
     else if (key === "signin") return { ok: false, error: '"signin" must be "exchange" or "none".' };
     else return { ok: false, error: `"${key}" is not a game switch.` };
   }
-  if (!Object.keys(patch).length) return { ok: false, error: 'Send "character" or "signin".' };
+  if (!Object.keys(patch).length) return { ok: false, error: 'Send "character", "signin" or "friends".' };
   return { ok: true, patch };
 }
 
 /** The settings from what the store kept and the game's defaults. A stored value that is not one of the known words is ignored. */
-export function mergeSettings(stored: { character?: unknown; signin?: unknown }, defaults: GameSettings): GameState {
+export function mergeSettings(stored: { character?: unknown; signin?: unknown; friends?: unknown }, defaults: GameSettings): GameState {
   return {
     character: isCharacter(stored.character) ? stored.character : defaults.character,
     signin: isSigninChoice(stored.signin) ? stored.signin : defaults.signin,
-    fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin) },
+    friends: isFriends(stored.friends) ? stored.friends : isFriends(defaults.friends) ? defaults.friends : DEFAULT_FRIENDS,
+    fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin), friends: isFriends(stored.friends) },
   };
 }
 
+/** The friends choice of the card: its title, and for each choice its short name (the card's three keys) and one plain sentence. Nanoterra's is the default. */
+export const FRIENDS_TITLE = "Friends list";
+export const FRIENDS_CHOICES: Record<Friends, { name: string; note: string }> = {
+  nanoterra: {
+    name: "Nanoterra",
+    note: "Nanoterra: a player signed in on nano133 sees their Nanoterra friends in a small nano133 frame in your game, and their friends see that they are playing it. The friends stay on nano133: your game gets none of them.",
+  },
+  own: {
+    name: "The game's own",
+    note: "The game's own: a friends list of this game's players, kept in this game's own database. Nanoterra friends do not show.",
+  },
+  off: { name: "Off", note: "Off: the game shows no friends list." },
+};
+
 /** One switch of the card: its title, and one plain sentence for each state. */
 export type SwitchId = "character" | "signin";
 export const SWITCHES: Record<SwitchId, { title: string; on: string; off: string }> = {

package/src/friends/adapters/d1.sql

@@ -0,0 +1,33 @@
+-- The friends tables of "@nano133/nanoterra/friends/d1". Add this file to the game's migrations (for example migrations/0005_friends.sql) and run
+-- `wrangler d1 migrations apply`. The adapter reads and writes only these three tables.
+
+-- One row for each pair of players (a < b): a request, a friendship or a block. `edge` is the opaque id the browser sees.
+CREATE TABLE IF NOT EXISTS friend_edges (
+  edge TEXT PRIMARY KEY,
+  a TEXT NOT NULL,
+  b TEXT NOT NULL,
+  from_player TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('pending', 'friend', 'blocked')),
+  blocked_by TEXT NOT NULL DEFAULT '[]',
+  at INTEGER NOT NULL,
+  invite_from TEXT,
+  invite_where TEXT,
+  invite_at INTEGER,
+  rev INTEGER NOT NULL DEFAULT 1,
+  UNIQUE (a, b)
+);
+CREATE INDEX IF NOT EXISTS friend_edges_b ON friend_edges (b);
+
+-- Where a player is now, and which tab said so. A row older than two minutes does not count.
+CREATE TABLE IF NOT EXISTS friend_presence (
+  player TEXT PRIMARY KEY,
+  place TEXT NOT NULL,
+  lease TEXT NOT NULL,
+  at INTEGER NOT NULL
+);
+
+-- A player's "show me online" choice (1 or 0). No row: shown.
+CREATE TABLE IF NOT EXISTS friend_prefs (
+  player TEXT PRIMARY KEY,
+  show_online INTEGER NOT NULL DEFAULT 1
+);

package/src/friends/adapters/d1.ts

@@ -0,0 +1,146 @@
+// The friends store for a game on Cloudflare D1. The tables are in ./d1.sql (the package ships it: "@nano133/nanoterra/friends/d1.sql"); add it to
+// the game's migrations. It reads and writes ONLY friend_edges, friend_presence and friend_prefs.
+//
+//   import { createD1Friends } from "@nano133/nanoterra/friends/d1";
+//   const friends = createD1Friends(env.DB);
+//
+// D1 has no transaction that reads and then writes, so each write is ONE statement that holds its own check: a change of an edge says which `rev`
+// it read (a row that changed in between is not written, and the player is asked to try again), and a new edge is written only while both players
+// have room (the count is in the same statement) and the pair has no row yet (UNIQUE (a, b)).
+
+import type { D1Like } from "../../admin/adapters/d1.js";
+import { buildRows, checkPulse, pairOf, planAccept, planBlock, planDecline, planInvite, planRemove, planRequest, planUnblock, shownOthers, type EdgeRec, type Plan, type PresenceRec } from "../rules.js";
+import { FRIEND_LIMIT, FRIEND_REQUEST_MS, FriendsError, type FriendView, type FriendsStore, type PlayerDirectory } from "../types.js";
+
+export type { D1Like, D1StatementLike } from "../../admin/adapters/d1.js";
+
+type Row = { edge: string; a: string; b: string; from_player: string; state: string; blocked_by: string; at: number; invite_from: string | null; invite_where: string | null; invite_at: number | null; rev: number };
+
+const COLS = "edge, a, b, from_player, state, blocked_by, at, invite_from, invite_where, invite_at, rev";
+
+function recOf(r: Row): EdgeRec {
+  let blockedBy: string[] = [];
+  try {
+    const v: unknown = JSON.parse(r.blocked_by);
+    if (Array.isArray(v)) blockedBy = v.filter((x): x is string => typeof x === "string");
+  } catch {
+    blockedBy = [];
+  }
+  const state = r.state === "friend" || r.state === "blocked" ? r.state : "pending";
+  const invite = typeof r.invite_from === "string" && typeof r.invite_where === "string" && typeof r.invite_at === "number" ? { from: r.invite_from, where: r.invite_where, at: Number(r.invite_at) } : null;
+  return { edge: r.edge, a: r.a, b: r.b, from: r.from_player, state, blockedBy, at: Number(r.at), invite, rev: Number(r.rev) };
+}
+
+const CHANGED = "That changed just now. Try again.";
+
+export function createD1Friends(db: D1Like): FriendsStore {
+  const changes = (res: unknown): number => Number((res as { meta?: { changes?: number } } | undefined)?.meta?.changes ?? 0);
+  const byEdge = async (edge: string) => {
+    const r = await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE edge = ?`).bind(edge).first<Row>();
+    return r ? recOf(r) : null;
+  };
+  const byPair = async (x: string, y: string) => {
+    const [a, b] = pairOf(x, y);
+    const r = await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE a = ? AND b = ?`).bind(a, b).first<Row>();
+    return r ? recOf(r) : null;
+  };
+  /** Live edges of a player, as SQL (?1 the player, ?2 the oldest request time that still counts). */
+  const LIVE_COUNT = "(SELECT COUNT(*) FROM friend_edges WHERE (a = ?1 OR b = ?1) AND (state != 'pending' OR at > ?2))";
+  const liveCount = async (player: string, now: number) => Number((await db.prepare(`SELECT ${LIVE_COUNT} AS n`).bind(player, now - FRIEND_REQUEST_MS).first<{ n: number }>())?.n ?? 0);
+
+  async function apply(plan: Plan, prev: EdgeRec | null, now: number): Promise<void> {
+    if ("none" in plan) return;
+    if ("drop" in plan) {
+      if (changes(await db.prepare("DELETE FROM friend_edges WHERE edge = ? AND rev = ?").bind(plan.drop.edge, plan.drop.rev).run()) !== 1) throw new FriendsError(409, CHANGED);
+      return;
+    }
+    const r = plan.put;
+    const inv = r.invite;
+    if (prev && prev.edge === r.edge) {
+      const res = await db
+        .prepare("UPDATE friend_edges SET from_player = ?, state = ?, blocked_by = ?, at = ?, invite_from = ?, invite_where = ?, invite_at = ?, rev = ? WHERE edge = ? AND rev = ?")
+        .bind(r.from, r.state, JSON.stringify(r.blockedBy), r.at, inv?.from ?? null, inv?.where ?? null, inv?.at ?? null, r.rev, r.edge, prev.rev)
+        .run();
+      if (changes(res) !== 1) throw new FriendsError(409, CHANGED);
+      return;
+    }
+    // A new edge: only while both players have room, in the same statement (the pair's UNIQUE (a, b) refuses a second row).
+    const cut = now - FRIEND_REQUEST_MS;
+    const other = r.from === r.a ? r.b : r.a;
+    const sql =
+      `INSERT INTO friend_edges (${COLS}) SELECT ?3, ?4, ?5, ?6, ?7, ?8, ?9, NULL, NULL, NULL, ?10 ` +
+      `WHERE (SELECT COUNT(*) FROM friend_edges WHERE (a = ?1 OR b = ?1) AND (state != 'pending' OR at > ?11)) < ?12 ` +
+      `AND (SELECT COUNT(*) FROM friend_edges WHERE (a = ?2 OR b = ?2) AND (state != 'pending' OR at > ?11)) < ?12 ` +
+      `ON CONFLICT (a, b) DO NOTHING`;
+    const res = await db.prepare(sql).bind(r.from, other, r.edge, r.a, r.b, r.from, r.state, JSON.stringify(r.blockedBy), r.at, r.rev, cut, FRIEND_LIMIT).run();
+    if (changes(res) !== 1) throw new FriendsError(409, CHANGED);
+  }
+
+  async function onEdge(_player: string, edge: string, plan: (rec: EdgeRec | null) => Plan, now: number) {
+    const rec = await byEdge(edge);
+    await apply(plan(rec), rec, now);
+  }
+
+  return {
+    async view(player: string, directory: PlayerDirectory, now: number): Promise<FriendView> {
+      const recs = (await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE a = ?1 OR b = ?1`).bind(player).all<Row>()).results.map(recOf);
+      // The presence and the choice of the player's friends, in one statement each (a friend's id is the other side of a friend edge).
+      const OTHER = "CASE WHEN e.a = ?1 THEN e.b ELSE e.a END";
+      const pres = (
+        await db
+          .prepare(`SELECT p.player, p.place, p.lease, p.at FROM friend_edges e JOIN friend_presence p ON p.player = ${OTHER} WHERE (e.a = ?1 OR e.b = ?1) AND e.state = 'friend'`)
+          .bind(player)
+          .all<{ player: string; place: string; lease: string; at: number }>()
+      ).results;
+      const hidden = (
+        await db.prepare(`SELECT f.player FROM friend_edges e JOIN friend_prefs f ON f.player = ${OTHER} WHERE (e.a = ?1 OR e.b = ?1) AND e.state = 'friend' AND f.show_online = 0`).bind(player).all<{ player: string }>()
+      ).results;
+      const me = await db.prepare("SELECT show_online FROM friend_prefs WHERE player = ?").bind(player).first<{ show_online: number }>();
+      const names = await directory.names(shownOthers(player, recs, now));
+      const presence = new Map<string, PresenceRec>(pres.map((p) => [p.player, { player: p.player, where: p.place, lease: p.lease, at: Number(p.at) }]));
+      const shows = new Map<string, boolean>(hidden.map((x) => [x.player, false]));
+      return { showOnline: !me || Number(me.show_online) !== 0, people: buildRows(player, recs, now, names, presence, shows) };
+    },
+
+    async request(player, other, now) {
+      const rec = await byPair(player, other);
+      const plan = await planRequest(player, other, rec, now, async () => ({ mine: await liveCount(player, now), theirs: await liveCount(other, now) }));
+      // A request that went stale is still the pair's row: it is changed in place (its count is the one just read).
+      await apply(plan, rec, now);
+    },
+    accept: (player, edge, now) => onEdge(player, edge, (r) => planAccept(player, r, now), now),
+    decline: (player, edge) => onEdge(player, edge, (r) => planDecline(player, r, Date.now()), Date.now()),
+    remove: (player, edge) => onEdge(player, edge, (r) => planRemove(player, r, Date.now()), Date.now()),
+    block: (player, edge, now) => onEdge(player, edge, (r) => planBlock(player, r, now), now),
+    unblock: (player, edge, now) => onEdge(player, edge, (r) => planUnblock(player, r, now), now),
+    invite: (player, edge, where, now) => onEdge(player, edge, (r) => planInvite(player, r, where, now), now),
+
+    async pulse(player, where, lease, now) {
+      const p = checkPulse(where, lease);
+      if (p.where !== null) {
+        await db
+          .prepare("INSERT INTO friend_presence (player, place, lease, at) VALUES (?, ?, ?, ?) ON CONFLICT (player) DO UPDATE SET place = excluded.place, lease = excluded.lease, at = excluded.at")
+          .bind(player, p.where, p.lease, now)
+          .run();
+        return;
+      }
+      // Leaving: only the tab that holds the row may clear it (planPulse's rule, in the statement).
+      await db.prepare("DELETE FROM friend_presence WHERE player = ? AND lease = ?").bind(player, p.lease).run();
+    },
+
+    async setShowOnline(player, on) {
+      const stmts = [db.prepare("INSERT INTO friend_prefs (player, show_online) VALUES (?, ?) ON CONFLICT (player) DO UPDATE SET show_online = excluded.show_online").bind(player, on ? 1 : 0)];
+      if (!on) stmts.push(db.prepare("DELETE FROM friend_presence WHERE player = ?").bind(player));
+      await db.batch(stmts);
+    },
+
+    async forget(player) {
+      const done = await db.batch([
+        db.prepare("DELETE FROM friend_edges WHERE a = ?1 OR b = ?1").bind(player),
+        db.prepare("DELETE FROM friend_presence WHERE player = ?").bind(player),
+        db.prepare("DELETE FROM friend_prefs WHERE player = ?").bind(player),
+      ]);
+      return done.reduce<number>((n, r) => n + changes(r), 0);
+    },
+  };
+}

package/src/friends/adapters/firestore.ts

@@ -0,0 +1,197 @@
+// The friends store for a game on Firestore (the Admin SDK). The package has no Firebase dependency: the adapter uses the small interface below,
+// which the Admin SDK's `Firestore` fits. It reads and writes ONLY its three collections.
+//
+//   import { createFirestoreFriends } from "@nano133/nanoterra/friends/firestore";
+//   const friends = createFirestoreFriends(getFirestore());
+//
+// The data model (the three collection names can be changed):
+//   friend_edges/{pair}       { edge, a, b, players: [a, b], from, state, blockedBy, at, invite: { from, where, at } | null, rev }
+//   friend_presence/{player}  { player, where, lease, at }
+//   friend_prefs/{player}     { player, showOnline }
+// `{pair}` and `{player}` are SHA-256 hex digests (of "a\u0000b" and of the player's id), so any id makes a valid document id, and a pair has one
+// document: two requests at the same moment meet on it in their transactions. `edge` is a random id; the browser sees only that.
+// Indexes: the single-field indexes Firestore makes by itself are enough (`players` array-contains, `edge` ==).
+
+import { buildRows, checkPulse, friendsOf, hasPlayer, liveEdge, pairOf, planAccept, planBlock, planDecline, planInvite, planPulse, planRemove, planRequest, planUnblock, shownOthers, type EdgeRec, type Plan, type PresenceRec } from "../rules.js";
+import { FriendsError, type FriendView, type FriendsStore, type PlayerDirectory } from "../types.js";
+
+export type FriendsDocSnap = { exists: boolean; data(): Record<string, unknown> | undefined };
+export interface FriendsDocRef {
+  get(): Promise<FriendsDocSnap>;
+}
+export type FriendsQuerySnap = { docs: { id: string; ref: FriendsDocRef; data(): Record<string, unknown> }[] };
+export interface FriendsQuery {
+  where(field: string, op: "==" | "array-contains", value: unknown): FriendsQuery;
+  limit(n: number): FriendsQuery;
+  get(): Promise<FriendsQuerySnap>;
+}
+export interface FriendsCollection extends FriendsQuery {
+  doc(id: string): FriendsDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface FriendsTransaction {
+  get(ref: FriendsDocRef): Promise<FriendsDocSnap>;
+  get(query: FriendsQuery): Promise<FriendsQuerySnap>;
+  set(ref: FriendsDocRef, data: Record<string, unknown>): unknown;
+  delete(ref: FriendsDocRef): unknown;
+}
+export interface FriendsBatch {
+  set(ref: FriendsDocRef, data: Record<string, unknown>, options?: { merge?: boolean }): unknown;
+  delete(ref: FriendsDocRef): unknown;
+  commit(): Promise<unknown>;
+}
+export interface FirestoreFriendsLike {
+  collection(name: string): FriendsCollection;
+  runTransaction<T>(fn: (tx: FriendsTransaction) => Promise<T>): Promise<T>;
+  batch(): FriendsBatch;
+}
+
+/** How many edges of one player a read takes at most: the limit, the blocks by others and old requests fit under it. */
+export const FIRESTORE_FRIENDS_SCAN = 1000;
+
+async function sha256(text: string): Promise<string> {
+  const bytes = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+const text = (v: unknown, fallback = ""): string => (typeof v === "string" ? v : fallback);
+const num = (v: unknown, fallback = 0): number => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
+
+function recOf(d: Record<string, unknown>): EdgeRec {
+  const inv = d.invite as Record<string, unknown> | null | undefined;
+  const state = d.state === "friend" || d.state === "blocked" ? d.state : "pending";
+  return {
+    edge: text(d.edge),
+    a: text(d.a),
+    b: text(d.b),
+    from: text(d.from),
+    state,
+    blockedBy: Array.isArray(d.blockedBy) ? d.blockedBy.filter((x): x is string => typeof x === "string") : [],
+    at: num(d.at),
+    invite: inv && typeof inv.from === "string" && typeof inv.where === "string" && typeof inv.at === "number" ? { from: inv.from, where: inv.where, at: inv.at } : null,
+    rev: num(d.rev),
+  };
+}
+
+const dataOf = (r: EdgeRec): Record<string, unknown> => ({ edge: r.edge, a: r.a, b: r.b, players: [r.a, r.b], from: r.from, state: r.state, blockedBy: r.blockedBy, at: r.at, invite: r.invite, rev: r.rev });
+
+export function createFirestoreFriends(db: FirestoreFriendsLike, collections: { edges?: string; presence?: string; prefs?: string } = {}): FriendsStore {
+  const edges = () => db.collection(collections.edges ?? "friend_edges");
+  const presenceCol = () => db.collection(collections.presence ?? "friend_presence");
+  const prefsCol = () => db.collection(collections.prefs ?? "friend_prefs");
+  const pairRef = async (x: string, y: string) => {
+    const [a, b] = pairOf(x, y);
+    return edges().doc(await sha256(`${a}\u0000${b}`));
+  };
+  const playerRef = async (col: FriendsCollection, player: string) => col.doc(await sha256(player));
+  const ofPlayer = (player: string) => edges().where("players", "array-contains", player).limit(FIRESTORE_FRIENDS_SCAN);
+
+  /** Writes a plan in the transaction, on the pair's document. */
+  async function write(tx: FriendsTransaction, plan: Plan) {
+    if ("none" in plan) return;
+    const rec = "put" in plan ? plan.put : plan.drop;
+    const ref = await pairRef(rec.a, rec.b);
+    if ("put" in plan) tx.set(ref, dataOf(plan.put));
+    else tx.delete(ref);
+  }
+
+  /** An operation on an edge the browser named: the edge is found, then read again in the transaction on its pair's document. */
+  async function onEdge(player: string, edge: string, plan: (rec: EdgeRec | null) => Plan) {
+    const found = await edges().where("edge", "==", edge).limit(2).get();
+    const first = found.docs.map((d) => recOf(d.data())).find((r) => hasPlayer(r, player));
+    if (!first) {
+      plan(null);
+      return;
+    }
+    const ref = await pairRef(first.a, first.b);
+    await db.runTransaction(async (tx) => {
+      const snap = await tx.get(ref);
+      const now = snap.exists ? recOf(snap.data() ?? {}) : null;
+      // The pair's document holds another edge now (it was removed and asked again): the old edge is gone.
+      await write(tx, plan(now && now.edge === edge ? now : null));
+    });
+  }
+
+  const liveOf = (snap: FriendsQuerySnap, now: number) => snap.docs.map((d) => recOf(d.data())).filter((r) => liveEdge(r, now)).length;
+
+  return {
+    async view(player: string, directory: PlayerDirectory, now: number): Promise<FriendView> {
+      const recs = (await ofPlayer(player).get()).docs.map((d) => recOf(d.data())).filter((r) => hasPlayer(r, player));
+      const friends = friendsOf(player, recs, now);
+      const [mePref, pres, prefs, names] = await Promise.all([
+        (await playerRef(prefsCol(), player)).get(),
+        Promise.all(friends.map(async (f) => (await playerRef(presenceCol(), f)).get())),
+        Promise.all(friends.map(async (f) => (await playerRef(prefsCol(), f)).get())),
+        directory.names(shownOthers(player, recs, now)),
+      ]);
+      const presence = new Map<string, PresenceRec>();
+      pres.forEach((s, i) => {
+        const d = s.exists ? s.data() : undefined;
+        if (d && d.player === friends[i]) presence.set(friends[i], { player: friends[i], where: text(d.where), lease: text(d.lease), at: num(d.at) });
+      });
+      const shows = new Map<string, boolean>();
+      prefs.forEach((s, i) => {
+        const d = s.exists ? s.data() : undefined;
+        if (d && d.player === friends[i] && d.showOnline === false) shows.set(friends[i], false);
+      });
+      const mine = mePref.exists ? mePref.data() : undefined;
+      return { showOnline: mine?.showOnline !== false, people: buildRows(player, recs, now, names, presence, shows) };
+    },
+
+    async request(player, other, now) {
+      if (player === other) throw new FriendsError(400, "You cannot add yourself.");
+      const ref = await pairRef(player, other);
+      await db.runTransaction(async (tx) => {
+        const snap = await tx.get(ref);
+        const rec = snap.exists ? recOf(snap.data() ?? {}) : null;
+        // The counts are read in the transaction too (every read before the first write).
+        const plan = await planRequest(player, other, rec, now, async () => {
+          const [mine, theirs] = await Promise.all([tx.get(ofPlayer(player)), tx.get(ofPlayer(other))]);
+          return { mine: liveOf(mine, now), theirs: liveOf(theirs, now) };
+        });
+        await write(tx, plan);
+      });
+    },
+    accept: (player, edge, now) => onEdge(player, edge, (r) => planAccept(player, r, now)),
+    decline: (player, edge) => onEdge(player, edge, (r) => planDecline(player, r, Date.now())),
+    remove: (player, edge) => onEdge(player, edge, (r) => planRemove(player, r, Date.now())),
+    block: (player, edge, now) => onEdge(player, edge, (r) => planBlock(player, r, now)),
+    unblock: (player, edge, now) => onEdge(player, edge, (r) => planUnblock(player, r, now)),
+    invite: (player, edge, where, now) => onEdge(player, edge, (r) => planInvite(player, r, where, now)),
+
+    async pulse(player, where, lease, now) {
+      const p = checkPulse(where, lease);
+      const ref = await playerRef(presenceCol(), player);
+      await db.runTransaction(async (tx) => {
+        const snap = await tx.get(ref);
+        const d = snap.exists ? snap.data() : undefined;
+        const was = d ? { player, where: text(d.where), lease: text(d.lease), at: num(d.at) } : null;
+        const plan = planPulse(player, p.where, p.lease, was, now);
+        if ("put" in plan) tx.set(ref, { player, where: plan.put.where, lease: plan.put.lease, at: plan.put.at });
+        else if ("drop" in plan) tx.delete(ref);
+      });
+    },
+
+    async setShowOnline(player, on) {
+      const batch = db.batch();
+      batch.set(await playerRef(prefsCol(), player), { player, showOnline: Boolean(on) });
+      if (!on) batch.delete(await playerRef(presenceCol(), player));
+      await batch.commit();
+    },
+
+    async forget(player) {
+      const docs = (await ofPlayer(player).get()).docs.filter((d) => hasPlayer(recOf(d.data()), player));
+      const [pres, pref] = await Promise.all([(await playerRef(presenceCol(), player)).get(), (await playerRef(prefsCol(), player)).get()]);
+      const refs = docs.map((d) => d.ref);
+      if (pres.exists) refs.push(await playerRef(presenceCol(), player));
+      if (pref.exists) refs.push(await playerRef(prefsCol(), player));
+      // A batch holds at most 500 writes.
+      for (let i = 0; i < refs.length; i += 400) {
+        const batch = db.batch();
+        for (const ref of refs.slice(i, i + 400)) batch.delete(ref);
+        await batch.commit();
+      }
+      return refs.length;
+    },
+  };
+}