@nano133/nanoterra 0.5.0 → 0.6.1

package/src/friends/conformance.ts

@@ -0,0 +1,260 @@
+// The conformance suite of the friends rules: a game that writes its own store (another database) runs it, and so proves that its store keeps
+// every rule the package's adapters keep. The package runs it on the memory store, D1 (on SQLite) and Firestore.
+//
+//   import { friendsStoreConformance } from "@nano133/nanoterra/friends/conformance";
+//   for (const c of friendsStoreConformance(async () => ({ store: myStore(), rows: () => countMyRows() }))) it(c.name, c.run);
+//
+// Each case gets a NEW, empty store from `make`. The suite names players with ids that it can find in a text (so it can prove that no view holds one)
+// and gives the store its own directory.
+
+import { FRIEND_INVITE_MS, FRIEND_LIMIT, FRIEND_LIVE_MS, FRIEND_REQUEST_MS, FriendsError, type FriendRow, type FriendView, type FriendsStore, type PlayerDirectory } from "./types.js";
+
+export type FriendsHarness = {
+  store: FriendsStore;
+  /** Every row the store keeps (edges, presence, prefs) as one text. `forget` must leave none that holds the player's id. */
+  dump(): Promise<string>;
+};
+
+export type FriendsConformanceCase = { name: string; run: () => Promise<void> };
+
+function check(ok: boolean, message: string): void {
+  if (!ok) throw new Error(message);
+}
+
+/** A player id the suite can find in any text. */
+const id = (n: string) => `player-id-${n}-7f3e`;
+const NAMES: Record<string, string> = {};
+const directory: PlayerDirectory = {
+  async byName(name) {
+    return Object.entries(NAMES).find(([, v]) => v === name)?.[0] ?? null;
+  },
+  async names(ids) {
+    return new Map(ids.filter((i) => NAMES[i]).map((i) => [i, NAMES[i]] as const));
+  },
+};
+for (const n of ["ann", "bob", "cyd", "dee"]) NAMES[id(n)] = n[0].toUpperCase() + n.slice(1);
+
+const ANN = id("ann");
+const BOB = id("bob");
+const CYD = id("cyd");
+
+async function rejects(p: Promise<unknown>, status: number, what: string): Promise<void> {
+  try {
+    await p;
+  } catch (e) {
+    check(e instanceof FriendsError, `${what}: expected a FriendsError, got ${String(e)}`);
+    check((e as FriendsError).status === status, `${what}: expected ${status}, got ${(e as FriendsError).status} (${(e as Error).message})`);
+    return;
+  }
+  throw new Error(`${what}: expected a refusal`);
+}
+
+export function friendsStoreConformance(make: () => Promise<FriendsHarness>): FriendsConformanceCase[] {
+  const cases: FriendsConformanceCase[] = [];
+  const add = (name: string, run: (h: FriendsHarness, now: number) => Promise<void>) => cases.push({ name, run: async () => run(await make(), Date.now()) });
+  const view = (h: FriendsHarness, who: string, now: number): Promise<FriendView> => h.store.view(who, directory, now);
+  const row = async (h: FriendsHarness, who: string, name: string, now: number): Promise<FriendRow | undefined> => (await view(h, who, now)).people.find((r) => r.name === name);
+  const friends = async (h: FriendsHarness, x: string, y: string, now: number) => {
+    await h.store.request(x, y, now);
+    await h.store.request(y, x, now + 1);
+  };
+
+  add("a request shows as outgoing to the sender and incoming to the other, with the other's name and no id", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const a = await row(h, ANN, "Bob", now);
+    const b = await row(h, BOB, "Ann", now);
+    check(a?.state === "outgoing" && b?.state === "incoming", `states: ${JSON.stringify([a, b])}`);
+    check(a!.edge === b!.edge && a!.edge.length >= 8, "the two rows name the same edge");
+    check(!a!.online && a!.where === null && a!.invite === null, "a request is not online and has no invite");
+  });
+
+  add("a request when the other already asked is an accept: both are friends, on one edge", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const a = (await view(h, ANN, now + 2)).people;
+    const b = (await view(h, BOB, now + 2)).people;
+    check(a.length === 1 && b.length === 1 && a[0].state === "friend" && b[0].state === "friend", `views: ${JSON.stringify([a, b])}`);
+  });
+
+  add("a request twice, or to a friend, changes nothing: one edge for the pair", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    await h.store.request(ANN, BOB, now + 1);
+    check((await view(h, ANN, now + 2)).people.length === 1, "one row after two requests");
+    await h.store.request(BOB, ANN, now + 3);
+    await h.store.request(ANN, BOB, now + 4);
+    const v = await view(h, ANN, now + 5);
+    check(v.people.length === 1 && v.people[0].state === "friend", `still one friend row: ${JSON.stringify(v)}`);
+  });
+
+  add("a player cannot ask themself", async (h, now) => {
+    await rejects(h.store.request(ANN, ANN, now), 400, "a request to self");
+  });
+
+  add("accept: only the player who was asked can accept; then both are friends", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now))!.edge;
+    await rejects(h.store.accept(ANN, edge, now + 1), 409, "the sender accepts their own request");
+    await h.store.accept(BOB, edge, now + 2);
+    check((await row(h, ANN, "Bob", now + 3))?.state === "friend", "Ann sees a friend");
+  });
+
+  add("decline takes the request away for both; the sender may also take it back", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    let edge = (await row(h, BOB, "Ann", now))!.edge;
+    await h.store.decline(BOB, edge);
+    check((await view(h, ANN, now + 1)).people.length === 0 && (await view(h, BOB, now + 1)).people.length === 0, "no rows after a decline");
+    await h.store.request(ANN, BOB, now + 2);
+    edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await h.store.decline(ANN, edge);
+    check((await view(h, BOB, now + 3)).people.length === 0, "no rows after the sender takes it back");
+  });
+
+  add("remove ends a friendship for both", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.remove(BOB, (await row(h, BOB, "Ann", now + 2))!.edge);
+    check((await view(h, ANN, now + 3)).people.length === 0 && (await view(h, BOB, now + 3)).people.length === 0, "no rows after remove");
+  });
+
+  add("a block wins: the blocker sees a blocked row, the other sees nothing, and neither can ask again", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.block(ANN, (await row(h, ANN, "Bob", now + 2))!.edge, now + 3);
+    check((await row(h, ANN, "Bob", now + 4))?.state === "blocked", "Ann sees Bob as blocked");
+    check((await view(h, BOB, now + 4)).people.length === 0, "Bob does not see Ann at all");
+    await rejects(h.store.request(BOB, ANN, now + 5), 409, "a request by the blocked player");
+    await rejects(h.store.request(ANN, BOB, now + 5), 409, "a request by the blocker");
+  });
+
+  add("the blocked player cannot use the old edge for anything", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, BOB, "Ann", now + 2))!.edge;
+    await h.store.block(ANN, edge, now + 3);
+    await rejects(h.store.accept(BOB, edge, now + 4), 404, "accept on a blocked edge");
+    await rejects(h.store.invite(BOB, edge, "Room 1", now + 4), 404, "invite on a blocked edge");
+    await rejects(h.store.remove(BOB, edge), 404, "remove on a blocked edge");
+    await rejects(h.store.unblock(BOB, edge, now + 4), 404, "unblock by the one who did not block");
+    check((await row(h, ANN, "Bob", now + 5))?.state === "blocked", "the block stands");
+  });
+
+  add("unblock leaves no edge (not friends again); only the player who blocked can unblock", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await h.store.block(ANN, edge, now + 3);
+    await h.store.unblock(ANN, edge, now + 4);
+    check((await view(h, ANN, now + 5)).people.length === 0 && (await view(h, BOB, now + 5)).people.length === 0, "no edge after unblock");
+    // Bob blocks this time: Ann sees nothing, so she cannot unblock his block.
+    await friends(h, ANN, BOB, now + 11);
+    const e3 = (await row(h, BOB, "Ann", now + 13))!.edge;
+    await h.store.block(BOB, e3, now + 14);
+    check((await view(h, ANN, now + 15)).people.length === 0, "Ann does not see Bob's block");
+    await rejects(h.store.unblock(ANN, e3, now + 16), 404, "Ann cannot unblock Bob's block");
+    await h.store.unblock(BOB, e3, now + 17);
+    check((await view(h, ANN, now + 18)).people.length === 0 && (await view(h, BOB, now + 18)).people.length === 0, "nothing left after Bob unblocks");
+  });
+
+  add(`a full list (${FRIEND_LIMIT} live rows) refuses a new request, both ways`, async (h, now) => {
+    for (let i = 0; i < FRIEND_LIMIT; i++) {
+      const other = id(`fan${i}`);
+      NAMES[other] = `Fan${i}`;
+      await h.store.request(other, ANN, now + i);
+    }
+    await rejects(h.store.request(ANN, BOB, now + FRIEND_LIMIT), 409, "Ann asks with a full list");
+    await rejects(h.store.request(CYD, ANN, now + FRIEND_LIMIT), 409, "Cyd asks Ann, whose list is full");
+    // An answer to one of the requests is not a new row: it is allowed.
+    const edge = (await row(h, ANN, "Fan0", now + FRIEND_LIMIT))!.edge;
+    await h.store.accept(ANN, edge, now + FRIEND_LIMIT + 1);
+  });
+
+  add("a request nobody answers goes after its time: not shown, not counted, and it may be sent again", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const later = now + FRIEND_REQUEST_MS + 1;
+    check((await view(h, ANN, later)).people.length === 0 && (await view(h, BOB, later)).people.length === 0, "the old request is gone");
+    await h.store.request(BOB, ANN, later);
+    const v = await view(h, ANN, later + 1);
+    check(v.people.length === 1 && v.people[0].state === "incoming", `a new request after the old one went: ${JSON.stringify(v)}`);
+  });
+
+  add("an invite works only between friends; the other sees it for its time, the sender does not", async (h, now) => {
+    await h.store.request(ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now))!.edge;
+    await rejects(h.store.invite(ANN, edge, "Room 1", now + 1), 409, "an invite to a request");
+    await h.store.accept(BOB, edge, now + 2);
+    await h.store.invite(ANN, edge, "Room 1", now + 3);
+    const b = await row(h, BOB, "Ann", now + 4);
+    check(b?.invite?.where === "Room 1" && b.invite.at === now + 3, `Bob sees the invite: ${JSON.stringify(b)}`);
+    check((await row(h, ANN, "Bob", now + 4))?.invite === null, "Ann does not see her own invite");
+    check((await row(h, BOB, "Ann", now + 3 + FRIEND_INVITE_MS))?.invite === null, "the invite is gone after its time");
+  });
+
+  add("an invite's place is plain text: control characters go and it is cut to 64 characters; an empty one is refused", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await h.store.invite(ANN, edge, `  Lev\u0000el\n 3 ${"x".repeat(100)}`, now + 3);
+    const w = (await row(h, BOB, "Ann", now + 4))!.invite!.where;
+    check(!/[\u0000-\u001f]/.test(w) && Array.from(w).length <= 64 && w.startsWith("Level 3"), `the place: ${JSON.stringify(w)}`);
+    await rejects(h.store.invite(ANN, edge, " \n\t ", now + 5), 400, "an empty place");
+  });
+
+  add("online only within its time, only to friends, and only while the friend shows online", async (h, now) => {
+    await h.store.request(ANN, CYD, now);
+    await friends(h, ANN, BOB, now);
+    await h.store.pulse(BOB, "Room 2", "lease-bob-1", now + 2);
+    await h.store.pulse(CYD, "Room 3", "lease-cyd-1", now + 2);
+    const b = await row(h, ANN, "Bob", now + 3);
+    check(b?.online === true && b.where === "Room 2", `Bob is online: ${JSON.stringify(b)}`);
+    const c = await row(h, ANN, "Cyd", now + 3);
+    check(c?.online === false && c.where === null, "a player who is only asked is not shown online");
+    check((await row(h, ANN, "Bob", now + 2 + FRIEND_LIVE_MS))?.online === false, "a pulse is old after its time");
+    await h.store.pulse(BOB, "Room 2", "lease-bob-1", now + 4);
+    await h.store.setShowOnline(BOB, false);
+    const hidden = await row(h, ANN, "Bob", now + 5);
+    check(hidden?.online === false && hidden.where === null, "a friend who hides is not online");
+    check((await view(h, BOB, now + 5)).showOnline === false && (await view(h, ANN, now + 5)).showOnline === true, "each player's own choice");
+    await h.store.setShowOnline(BOB, true);
+    check((await row(h, ANN, "Bob", now + 6))?.online === false, "hiding cleared the old pulse");
+  });
+
+  add("presence: a tab that leaves clears only its own pulse, so an old tab cannot clear a new one", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.pulse(BOB, "Room 1", "lease-old-tab", now + 2);
+    await h.store.pulse(BOB, "Room 2", "lease-new-tab", now + 3);
+    await h.store.pulse(BOB, null, "lease-old-tab", now + 4);
+    check((await row(h, ANN, "Bob", now + 5))?.where === "Room 2", "the new tab's place stands");
+    await h.store.pulse(BOB, null, "lease-new-tab", now + 6);
+    check((await row(h, ANN, "Bob", now + 7))?.online === false, "the new tab left");
+    await rejects(h.store.pulse(BOB, "Room 1", "short", now + 8), 400, "a lease that is too short");
+  });
+
+  add("a player cannot use an edge of two other players", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    const edge = (await row(h, ANN, "Bob", now + 2))!.edge;
+    await rejects(h.store.remove(CYD, edge), 404, "remove");
+    await rejects(h.store.block(CYD, edge, now + 3), 404, "block");
+    await rejects(h.store.invite(CYD, edge, "Room", now + 3), 404, "invite");
+    await rejects(h.store.accept(CYD, "no-such-edge-1", now + 3), 404, "an edge that does not exist");
+  });
+
+  add("no view holds a player id", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.request(CYD, ANN, now + 2);
+    await h.store.pulse(BOB, "Room 9", "lease-bob-9", now + 3);
+    await h.store.invite(BOB, (await row(h, BOB, "Ann", now + 3))!.edge, "Room 9", now + 4);
+    for (const who of [ANN, BOB, CYD]) {
+      const text = JSON.stringify(await view(h, who, now + 5));
+      check(!/player-id-/.test(text), `a view holds an id: ${text}`);
+    }
+  });
+
+  add("forget leaves nothing of the player: no edge, no presence, no choice; the others' lists lose them", async (h, now) => {
+    await friends(h, ANN, BOB, now);
+    await h.store.request(CYD, ANN, now + 2);
+    await h.store.pulse(ANN, "Room", "lease-ann-1", now + 3);
+    await h.store.setShowOnline(ANN, false);
+    await h.store.pulse(BOB, "Room", "lease-bob-1", now + 3);
+    const n = await h.store.forget(ANN);
+    check(n >= 3, `forget said ${n}`);
+    check(!(await h.dump()).includes(ANN), "a row still holds the player's id");
+    check((await view(h, BOB, now + 4)).people.length === 0 && (await view(h, CYD, now + 4)).people.length === 0, "the others no longer see the player");
+    check((await h.dump()).includes(BOB), "the other players' own rows stay");
+  });
+
+  return cases;
+}

package/src/friends/handler.ts

@@ -0,0 +1,144 @@
+// The routes of the game's own friends list, on the Web `Request` and `Response` types (a Worker, Firebase Functions, Node).
+//
+//   GET  {base}   the player's view: { showOnline, people }
+//   POST {base}   one operation, { op, ... }:
+//                   request { name }                   (the name through the game's directory)
+//                   accept | decline | remove | block | unblock { edge }
+//                   invite { edge, where }
+//                   pulse { where (text, or null to leave), lease }
+//                   visibility { showOnline: boolean }
+//
+// The player is the game's own signed-in player (`player(request)`); a visitor who is not signed in gets 401. A POST must come from the game's own
+// page, and a read must not come from another page. Each player has 30 calls a minute. No answer ever holds a player id: a row names a player by
+// the directory's name and an opaque edge.
+
+import { fail, foreignOrigin, json, memoryLimiter, readLimited, sameOrigin } from "../admin/http.js";
+import { EDGE_PATTERN } from "./rules.js";
+import { FriendsError, type FriendsStore, type PlayerDirectory } from "./types.js";
+
+export type FriendsOp = "request" | "accept" | "decline" | "remove" | "block" | "unblock" | "invite" | "pulse" | "visibility";
+
+export type FriendsHandlerOptions = {
+  store: FriendsStore;
+  directory: PlayerDirectory;
+  /** The game's signed-in player of this request (its own id), or null. */
+  player(request: Request): Promise<string | null>;
+  /** Where the routes are. Default "/friends". */
+  base?: string;
+  /** A limiter: false means "too many". Default: a fixed window in memory, 30 calls a minute for each player. */
+  limit?: (key: string, limit: number, windowMs: number, now: number) => boolean | Promise<boolean>;
+  /** The time now in ms. Default Date.now. */
+  now?: () => number;
+  /** Told about a fault in the store or the directory. The player gets a plain 500 and never sees it. */
+  onError?: (e: unknown) => void;
+};
+
+export const FRIENDS_LIMITS = {
+  /** Calls of one player (reads and writes together). */
+  calls: { limit: 30, windowMs: 60_000 },
+  /** The biggest body of a POST. */
+  bodyMax: 1024,
+  /** The longest name a request may send: room for a whole Nano address (65 characters with "nano_"), which a directory may accept as a name. */
+  nameMax: 80,
+} as const;
+
+const sharedLimit = memoryLimiter();
+const OPS = new Set<FriendsOp>(["request", "accept", "decline", "remove", "block", "unblock", "invite", "pulse", "visibility"]);
+
+export function createFriendsHandler(options: FriendsHandlerOptions): { base: string; handle(request: Request): Promise<Response | null> } {
+  const base = options.base ?? "/friends";
+  if (!base.startsWith("/") || base.length < 2 || base.endsWith("/")) throw new Error('base must start with "/" and not end with "/", like "/friends"');
+  const now = options.now ?? (() => Date.now());
+  const limit = options.limit ?? sharedLimit;
+  const report = (e: unknown) => {
+    try {
+      options.onError?.(e);
+    } catch {
+      // nothing more can be done
+    }
+  };
+
+  async function run(req: Request, player: string, at: number): Promise<Response> {
+    if (req.method === "GET") return json(await options.store.view(player, options.directory, at));
+    const text = await readLimited(req, FRIENDS_LIMITS.bodyMax);
+    if (text === null) return fail(413, "That is too much to send.");
+    let body: Record<string, unknown>;
+    try {
+      const v: unknown = JSON.parse(text);
+      if (!v || typeof v !== "object" || Array.isArray(v)) return fail(400, "Send an object with an op.");
+      body = v as Record<string, unknown>;
+    } catch {
+      return fail(400, "Send JSON.");
+    }
+    const op = body.op as FriendsOp;
+    if (typeof op !== "string" || !OPS.has(op)) return fail(400, "Unknown op.");
+    const store = options.store;
+    const edge = (): string => {
+      if (typeof body.edge !== "string" || !EDGE_PATTERN.test(body.edge)) throw new FriendsError(400, "Choose a player on your list.");
+      return body.edge;
+    };
+    switch (op) {
+      case "request": {
+        const name = typeof body.name === "string" ? body.name.trim() : "";
+        if (!name || name.length > FRIENDS_LIMITS.nameMax) return fail(400, "Enter a player's name.");
+        const other = await options.directory.byName(name);
+        if (!other) return fail(404, "No player has that name.");
+        await store.request(player, other, at);
+        break;
+      }
+      case "accept":
+        await store.accept(player, edge(), at);
+        break;
+      case "decline":
+        await store.decline(player, edge());
+        break;
+      case "remove":
+        await store.remove(player, edge());
+        break;
+      case "block":
+        await store.block(player, edge(), at);
+        break;
+      case "unblock":
+        await store.unblock(player, edge(), at);
+        break;
+      case "invite":
+        await store.invite(player, edge(), typeof body.where === "string" ? body.where : "", at);
+        break;
+      case "pulse":
+        await store.pulse(player, body.where === null ? null : typeof body.where === "string" ? body.where : "", typeof body.lease === "string" ? body.lease : "", at);
+        // A pulse needs no list back: the panel reads the view on its own clock.
+        return json({ ok: true });
+      case "visibility":
+        if (typeof body.showOnline !== "boolean") return fail(400, "Send showOnline as true or false.");
+        await store.setShowOnline(player, body.showOnline);
+        break;
+    }
+    return json(await store.view(player, options.directory, now()));
+  }
+
+  async function handle(req: Request): Promise<Response | null> {
+    const url = new URL(req.url);
+    if (url.pathname !== base) return null;
+    try {
+      if (req.method !== "GET" && req.method !== "POST") return fail(405, "Not allowed.", {}, { Allow: "GET, POST" });
+      if (req.method === "POST" ? !sameOrigin(req) : foreignOrigin(req)) return fail(403, "This call must come from the game's own page.");
+      let player: string | null;
+      try {
+        player = await options.player(req);
+      } catch (e) {
+        report(e);
+        return fail(503, "The game's server could not check your sign-in. Try again.");
+      }
+      if (typeof player !== "string" || !player) return fail(401, "Sign in to see your friends.");
+      const at = now();
+      if (!(await limit(`${base}|friends|${player}`, FRIENDS_LIMITS.calls.limit, FRIENDS_LIMITS.calls.windowMs, at))) return fail(429, "Too many calls. Wait a minute.");
+      return await run(req, player, at);
+    } catch (e) {
+      if (e instanceof FriendsError) return fail(e.status, e.message);
+      report(e);
+      return fail(500, "The game's server could not do that. Try again.");
+    }
+  }
+
+  return { base, handle };
+}

package/src/friends/index.ts

@@ -0,0 +1,17 @@
+// "@nano133/nanoterra/friends": the friends list of a game's OWN players (the setting "The game's own" of the admin's Game card). No database, no
+// cookie, no Nanoterra account: the game gives its store, its directory of players and its signed-in player.
+//
+//   createFriendsHandler   the routes (GET the view, POST an op), on Request and Response
+//   createMemoryFriends    a store in memory, for tests
+//   (the adapters are "/friends/d1" and "/friends/firestore", the conformance suite "/friends/conformance", the browser panel "/friends/panel")
+//
+// Nanoterra's own friends list (the setting "Nanoterra") is not here: the panel holds the nano133 window for it, and the friends stay on nano133.
+
+export { FRIEND_INVITE_MS, FRIEND_LIMIT, FRIEND_LIVE_MS, FRIEND_REQUEST_MS, FRIEND_WHERE_MAX, FriendsError } from "./types.js";
+export type { FriendRow, FriendState, FriendView, FriendsStore, PlayerDirectory } from "./types.js";
+export { FRIENDS_LIMITS, createFriendsHandler } from "./handler.js";
+export type { FriendsHandlerOptions, FriendsOp } from "./handler.js";
+export { createMemoryFriends } from "./memory.js";
+export type { MemoryFriends } from "./memory.js";
+export { EDGE_PATTERN, LEASE_PATTERN, cleanWhere } from "./rules.js";
+export type { EdgeRec, PresenceRec } from "./rules.js";

package/src/friends/memory.ts

@@ -0,0 +1,83 @@
+// A friends store in memory, for tests (and for a game's first try). Nothing is kept after the process ends. It uses the same rules as the real
+// adapters (./rules.ts), so it is the reference for what a store does.
+
+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 type { FriendView, FriendsStore, PlayerDirectory } from "./types.js";
+
+export type MemoryFriends = FriendsStore & {
+  /** The rows as an adapter would keep them. */
+  readonly edges: Map<string, EdgeRec>;
+  readonly presence: Map<string, PresenceRec>;
+  readonly prefs: Map<string, boolean>;
+};
+
+export function createMemoryFriends(): MemoryFriends {
+  const edges = new Map<string, EdgeRec>();
+  const presence = new Map<string, PresenceRec>();
+  const prefs = new Map<string, boolean>();
+  const of = (player: string) => [...edges.values()].filter((r) => hasPlayer(r, player));
+  const byPair = (x: string, y: string) => {
+    const [a, b] = pairOf(x, y);
+    return [...edges.values()].find((r) => r.a === a && r.b === b) ?? null;
+  };
+  const live = (player: string, now: number) => of(player).filter((r) => liveEdge(r, now)).length;
+  const apply = (plan: Plan) => {
+    if ("put" in plan) edges.set(plan.put.edge, plan.put);
+    else if ("drop" in plan) edges.delete(plan.drop.edge);
+  };
+
+  return {
+    edges,
+    presence,
+    prefs,
+    async view(player: string, directory: PlayerDirectory, now: number): Promise<FriendView> {
+      const recs = of(player);
+      const names = await directory.names(shownOthers(player, recs, now));
+      const friends = friendsOf(player, recs, now);
+      const pres = new Map(friends.flatMap((f) => (presence.has(f) ? [[f, presence.get(f)!] as const] : [])));
+      const shows = new Map(friends.map((f) => [f, prefs.get(f) !== false] as const));
+      return { showOnline: prefs.get(player) !== false, people: buildRows(player, recs, now, names, pres, shows) };
+    },
+    async request(player, other, now) {
+      apply(await planRequest(player, other, byPair(player, other), now, async () => ({ mine: live(player, now), theirs: live(other, now) })));
+    },
+    async accept(player, edge, now) {
+      apply(planAccept(player, edges.get(edge) ?? null, now));
+    },
+    async decline(player, edge) {
+      apply(planDecline(player, edges.get(edge) ?? null, Date.now()));
+    },
+    async remove(player, edge) {
+      apply(planRemove(player, edges.get(edge) ?? null, Date.now()));
+    },
+    async block(player, edge, now) {
+      apply(planBlock(player, edges.get(edge) ?? null, now));
+    },
+    async unblock(player, edge, now) {
+      apply(planUnblock(player, edges.get(edge) ?? null, now));
+    },
+    async invite(player, edge, where, now) {
+      apply(planInvite(player, edges.get(edge) ?? null, where, now));
+    },
+    async pulse(player, where, lease, now) {
+      const p = checkPulse(where, lease);
+      const plan = planPulse(player, p.where, p.lease, presence.get(player) ?? null, now);
+      if ("put" in plan) presence.set(player, plan.put);
+      else if ("drop" in plan) presence.delete(player);
+    },
+    async setShowOnline(player, on) {
+      prefs.set(player, Boolean(on));
+      if (!on) presence.delete(player);
+    },
+    async forget(player) {
+      let n = 0;
+      for (const r of of(player)) {
+        edges.delete(r.edge);
+        n++;
+      }
+      if (presence.delete(player)) n++;
+      if (prefs.delete(player)) n++;
+      return n;
+    },
+  };
+}

package/src/friends/panel/index.ts

@@ -0,0 +1,13 @@
+// "@nano133/nanoterra/friends/panel": the Friends key and panel of a game, drawn in the browser. Plain DOM, no framework, no Three.js.
+//
+//   import { mountFriends } from "@nano133/nanoterra/friends/panel";
+//   import "@nano133/nanoterra/friends/style.css";
+//   const friends = mountFriends(document.getElementById("friends")!, { mode: settings.friends, game: "my-game" });
+//   friends.setWhere("Level 2");
+//
+// The server part is "@nano133/nanoterra/friends" (the handler and the stores): it must not load this one.
+
+export { FRIENDS_TIMING, mountFriends } from "./mount.js";
+export type { FriendsMode, FriendsMountOptions, MountedFriends } from "./mount.js";
+export { WINDOW_SOURCE, WINDOW_V, readWindowMessage, toWindow, whereText, windowUrl } from "./window.js";
+export type { FromWindow, ToWindow } from "./window.js";