@nano133/nanoterra 0.5.0 → 0.6.0

package/dist/friends/rules.js

@@ -0,0 +1,180 @@
+// The rules of the friends list, as pure functions: every adapter (memory, D1, Firestore) reads its rows, asks these what to write, and writes it
+// in one step. So the rules live in one place, and the conformance suite (./conformance.ts) proves that an adapter keeps them.
+//
+// One pair of players has at most one edge. An edge is a request ("pending", from one of them), a friendship, or a block (by one or both).
+// - A block hides the pair from the player who is blocked, both ways, and wins over a friendship or a request. The player who blocked sees a
+//   "blocked" row, so that they can unblock it.
+// - A request that nobody answered goes after FRIEND_REQUEST_MS: it is not shown and does not count.
+// - Every live edge counts toward FRIEND_LIMIT for both players.
+import { FRIEND_INVITE_MS, FRIEND_LIMIT, FRIEND_LIVE_MS, FRIEND_REQUEST_MS, FRIEND_WHERE_MAX, FriendsError } from "./types.js";
+/** The two ids of a pair in the order an adapter keeps them. */
+export const pairOf = (x, y) => (x < y ? [x, y] : [y, x]);
+export const otherOf = (rec, me) => (rec.a === me ? rec.b : rec.a);
+export const hasPlayer = (rec, me) => rec.a === me || rec.b === me;
+/** A request that nobody answered in time is gone; anything else is live. */
+export const liveEdge = (rec, now) => rec.state !== "pending" || now - rec.at < FRIEND_REQUEST_MS;
+/** A new opaque edge id: random, never made from a player id. */
+export function newEdgeId() {
+    return globalThis.crypto.randomUUID();
+}
+/** An edge id as the browser may send one: letters, digits, "-" and "_", 8 to 64. Anything else is refused before a store is asked. */
+export const EDGE_PATTERN = /^[A-Za-z0-9_-]{8,64}$/;
+/** A tab's lease, as for an edge. */
+export const LEASE_PATTERN = /^[A-Za-z0-9_-]{8,64}$/;
+/**
+ * The game's `where` text as a store keeps it: control characters removed, spaces at the ends trimmed, cut to FRIEND_WHERE_MAX characters
+ * (whole characters, not halves of one). Null when nothing is left, or when it is not text.
+ */
+export function cleanWhere(where) {
+    if (typeof where !== "string")
+        return null;
+    // eslint-disable-next-line no-control-regex
+    const plain = where.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "").trim();
+    const cut = Array.from(plain).slice(0, FRIEND_WHERE_MAX).join("").trim();
+    return cut ? cut : null;
+}
+/** The state of an edge for one of its players, or null when they must not see it (a block by the other, an old request). */
+export function stateFor(rec, me, now) {
+    if (!hasPlayer(rec, me) || !liveEdge(rec, now))
+        return null;
+    if (rec.state === "blocked")
+        return rec.blockedBy.includes(me) ? "blocked" : null;
+    if (rec.state === "friend")
+        return "friend";
+    return rec.from === me ? "outgoing" : "incoming";
+}
+const NOT_HERE = "This player is not on your list any more.";
+/** The edge that `me` named, or a refusal: an edge of other players, or one they must not see, reads as gone (it says nothing about why). */
+function mine(rec, me, now) {
+    if (!rec || stateFor(rec, me, now) === null)
+        throw new FriendsError(404, NOT_HERE);
+    return rec;
+}
+/**
+ * A request from `me` to `other`. `rec` is the pair's edge (or null); `counts` are the live edges of each, which the adapter reads only when a new
+ * edge would be made (it passes a function).
+ */
+export async function planRequest(me, other, rec, now, counts) {
+    if (me === other)
+        throw new FriendsError(400, "You cannot add yourself.");
+    const live = rec && liveEdge(rec, now) ? rec : null;
+    if (live?.state === "blocked")
+        throw new FriendsError(409, "This player is not available.");
+    if (live?.state === "friend")
+        return { none: true };
+    if (live?.state === "pending") {
+        if (live.from === me)
+            return { none: true };
+        // The other player already asked: this is an accept.
+        return { put: { ...live, from: me, state: "friend", at: now, invite: null, rev: live.rev + 1 } };
+    }
+    const c = await counts();
+    if (c.mine >= FRIEND_LIMIT)
+        throw new FriendsError(409, "Your friends list is full. Remove someone first.");
+    if (c.theirs >= FRIEND_LIMIT)
+        throw new FriendsError(409, "That player's friends list is full.");
+    const [a, b] = pairOf(me, other);
+    // An old request of the same pair is replaced (same row), so the pair still has one edge.
+    return { put: { edge: rec?.edge ?? newEdgeId(), a, b, from: me, state: "pending", blockedBy: [], at: now, invite: null, rev: (rec?.rev ?? 0) + 1 } };
+}
+export function planAccept(me, rec, now) {
+    const r = mine(rec, me, now);
+    const s = stateFor(r, me, now);
+    if (s === "friend")
+        return { none: true };
+    if (s !== "incoming")
+        throw new FriendsError(409, s === "outgoing" ? "Wait for the other player to accept." : "This request is no longer open.");
+    return { put: { ...r, from: me, state: "friend", at: now, invite: null, rev: r.rev + 1 } };
+}
+/** Declines a request to `me`, or takes back a request of `me`'s. */
+export function planDecline(me, rec, now) {
+    const r = mine(rec, me, now);
+    const s = stateFor(r, me, now);
+    if (s !== "incoming" && s !== "outgoing")
+        throw new FriendsError(409, "This is not a request.");
+    return { drop: r };
+}
+/** Ends a friendship (or a request, either way). A block is ended by unblock, not by remove. */
+export function planRemove(me, rec, now) {
+    const r = mine(rec, me, now);
+    if (stateFor(r, me, now) === "blocked")
+        throw new FriendsError(409, "Unblock this player first.");
+    return { drop: r };
+}
+export function planBlock(me, rec, now) {
+    const r = mine(rec, me, now);
+    if (r.blockedBy.includes(me))
+        return { none: true };
+    const blockedBy = r.state === "blocked" ? [...r.blockedBy, me] : [me];
+    return { put: { ...r, from: me, state: "blocked", blockedBy, at: now, invite: null, rev: r.rev + 1 } };
+}
+/** Takes `me`'s block away. With no block left the pair has no edge (they are not friends again: either may ask). */
+export function planUnblock(me, rec, now) {
+    const r = mine(rec, me, now);
+    if (!r.blockedBy.includes(me))
+        throw new FriendsError(409, "This player is not blocked.");
+    const left = r.blockedBy.filter((p) => p !== me);
+    if (!left.length)
+        return { drop: r };
+    return { put: { ...r, blockedBy: left, at: now, rev: r.rev + 1 } };
+}
+export function planInvite(me, rec, where, now) {
+    const r = mine(rec, me, now);
+    if (stateFor(r, me, now) !== "friend")
+        throw new FriendsError(409, "You can invite only a friend.");
+    const place = cleanWhere(where);
+    if (!place)
+        throw new FriendsError(400, "Say where to meet.");
+    return { put: { ...r, invite: { from: me, where: place, at: now }, rev: r.rev + 1 } };
+}
+/** The lease and the place of a pulse, checked. `where` null means the tab is leaving (it clears the row only when the lease is the same). */
+export function checkPulse(where, lease) {
+    if (typeof lease !== "string" || !LEASE_PATTERN.test(lease))
+        throw new FriendsError(400, "A pulse needs a lease of 8 to 64 letters or digits.");
+    if (where === null)
+        return { where: null, lease };
+    const place = cleanWhere(where);
+    if (!place)
+        throw new FriendsError(400, "Say where you are, or send null to leave.");
+    return { where: place, lease };
+}
+/** What a pulse does to the presence row `was`: the new row, a deletion, or nothing (an old tab that leaves after a newer one came). */
+export function planPulse(player, where, lease, was, now) {
+    if (where !== null)
+        return { put: { player, where, lease, at: now } };
+    if (was && was.lease === lease)
+        return { drop: true };
+    return { none: true };
+}
+/** A presence row that still counts. */
+export const presenceLive = (p, now) => Boolean(p) && now - p.at < FRIEND_LIVE_MS && now - p.at >= -FRIEND_LIVE_MS;
+/** The order of the list: requests to answer first, then friends who are online, friends, requests sent, blocks; each by name. */
+const RANK = { incoming: 0, friend: 1, outgoing: 3, blocked: 4 };
+/**
+ * The browser's view of `me`'s edges. `presence` and `showOnline` are of the OTHER players (only friends' are read). `names` comes from the game's
+ * directory; a player it does not know reads "A player". No player id goes into a row.
+ */
+export function buildRows(me, recs, now, names, presence, showOnline) {
+    const rows = [];
+    for (const rec of recs) {
+        const state = stateFor(rec, me, now);
+        if (!state)
+            continue;
+        const other = otherOf(rec, me);
+        const p = state === "friend" && showOnline.get(other) !== false ? presence.get(other) : undefined;
+        const online = presenceLive(p, now);
+        const invite = state === "friend" && rec.invite && rec.invite.from !== me && now - rec.invite.at < FRIEND_INVITE_MS && now - rec.invite.at >= -FRIEND_INVITE_MS ? { where: rec.invite.where, at: rec.invite.at } : null;
+        const name = names.get(other);
+        rows.push({ edge: rec.edge, name: typeof name === "string" && name ? name : "A player", state, online, where: online ? p.where : null, invite, rank: state === "friend" && online ? 0.5 : RANK[state] });
+    }
+    rows.sort((x, y) => x.rank - y.rank || x.name.localeCompare(y.name) || (x.edge < y.edge ? -1 : 1));
+    return rows.map(({ rank: _rank, ...row }) => row);
+}
+/** The other players whose names a view needs: every edge `me` can see. */
+export function shownOthers(me, recs, now) {
+    return [...new Set(recs.filter((r) => stateFor(r, me, now) !== null).map((r) => otherOf(r, me)))];
+}
+/** The friends of `me` (their presence is read for the view). */
+export function friendsOf(me, recs, now) {
+    return recs.filter((r) => stateFor(r, me, now) === "friend").map((r) => otherOf(r, me));
+}

package/dist/friends/types.d.ts

@@ -0,0 +1,58 @@
+/** A row of a player's list, as the browser gets it. `edge` is the store's opaque id for the pair (never a player id). */
+export type FriendState = "friend" | "incoming" | "outgoing" | "blocked";
+export type FriendRow = {
+    edge: string;
+    name: string;
+    state: FriendState;
+    online: boolean;
+    where: string | null;
+    invite: {
+        where: string;
+        at: number;
+    } | null;
+};
+export type FriendView = {
+    showOnline: boolean;
+    people: FriendRow[];
+};
+/** Live rows a player may have (friends, requests both ways, blocks), as the island. */
+export declare const FRIEND_LIMIT = 100;
+/** A pulse counts as online this long. */
+export declare const FRIEND_LIVE_MS = 120000;
+/** An invite shows this long. */
+export declare const FRIEND_INVITE_MS = 600000;
+/** An unanswered request goes after this. */
+export declare const FRIEND_REQUEST_MS: number;
+/** The longest `where` a store keeps (after trimming and removing control characters). */
+export declare const FRIEND_WHERE_MAX = 64;
+/** The game's players, which only the game knows: its sign-in id for a name, and the names to show. */
+export interface PlayerDirectory {
+    byName(name: string): Promise<string | null>;
+    names(ids: string[]): Promise<Map<string, string>>;
+}
+/** The game's database for friends. An adapter writes ONLY friend rows, presence rows and the show-online choice. */
+export interface FriendsStore {
+    view(player: string, directory: PlayerDirectory, now: number): Promise<FriendView>;
+    /** A request by the other player's id; an accept when the other already asked. Refuses: self, a full list, a block. */
+    request(player: string, other: string, now: number): Promise<void>;
+    accept(player: string, edge: string, now: number): Promise<void>;
+    decline(player: string, edge: string): Promise<void>;
+    remove(player: string, edge: string): Promise<void>;
+    block(player: string, edge: string, now: number): Promise<void>;
+    unblock(player: string, edge: string, now: number): Promise<void>;
+    /** Only between friends; `where` is the game's own text (a room, a level), at most 64 characters. */
+    invite(player: string, edge: string, where: string, now: number): Promise<void>;
+    /** Presence: here now (`where` or null), kept FRIEND_LIVE_MS; a `lease` per tab, so an old tab cannot clear a new one. */
+    pulse(player: string, where: string | null, lease: string, now: number): Promise<void>;
+    setShowOnline(player: string, on: boolean): Promise<void>;
+    /** A player's "delete my data": every row of theirs; returns how many. */
+    forget(player: string): Promise<number>;
+}
+/**
+ * A refusal of a store or the handler: the status to answer and words a player can read. A store throws it for a rule (a block, a full list, an edge
+ * that is not theirs); anything else it throws is a fault, and the handler answers a plain 500.
+ */
+export declare class FriendsError extends Error {
+    status: 400 | 401 | 403 | 404 | 409 | 413 | 429;
+    constructor(status: 400 | 401 | 403 | 404 | 409 | 413 | 429, message: string);
+}

package/dist/friends/types.js

@@ -0,0 +1,24 @@
+// The friends list of a game's OWN players: the types, the limits and the store contract. The package never sees a Nanoterra account here: a
+// player is the game's own id, and a name comes from the game's own directory. (Nanoterra's friends are another thing: the nano133 window, ./panel.)
+/** Live rows a player may have (friends, requests both ways, blocks), as the island. */
+export const FRIEND_LIMIT = 100;
+/** A pulse counts as online this long. */
+export const FRIEND_LIVE_MS = 120_000;
+/** An invite shows this long. */
+export const FRIEND_INVITE_MS = 600_000;
+/** An unanswered request goes after this. */
+export const FRIEND_REQUEST_MS = 30 * 86_400_000;
+/** The longest `where` a store keeps (after trimming and removing control characters). */
+export const FRIEND_WHERE_MAX = 64;
+/**
+ * A refusal of a store or the handler: the status to answer and words a player can read. A store throws it for a rule (a block, a full list, an edge
+ * that is not theirs); anything else it throws is a fault, and the handler answers a plain 500.
+ */
+export class FriendsError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "FriendsError";
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nano133/nanoterra",
-  "version": "0.5.0",
-  "description": "Nanoterra for a creator's game, in one package: the player's sign-in ticket, the player's character (a toon body on the island's skeleton) and the looks ladder.",
+  "version": "0.6.0",
+  "description": "Nanoterra for a creator's game, in one package: the player's sign-in ticket, the player's character (a toon body on the island's skeleton), the looks ladder, the admin and the friends list.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,14 @@
     "./admin/d1": { "types": "./dist/admin/adapters/d1.d.ts", "import": "./dist/admin/adapters/d1.js" },
     "./admin/firestore": { "types": "./dist/admin/adapters/firestore.d.ts", "import": "./dist/admin/adapters/firestore.js" },
     "./admin/panel": { "types": "./dist/admin/panel/index.d.ts", "import": "./dist/admin/panel/index.js" },
-    "./admin/style.css": "./src/admin/panel/style.css"
+    "./admin/style.css": "./src/admin/panel/style.css",
+    "./friends": { "types": "./dist/friends/index.d.ts", "import": "./dist/friends/index.js" },
+    "./friends/conformance": { "types": "./dist/friends/conformance.d.ts", "import": "./dist/friends/conformance.js" },
+    "./friends/d1": { "types": "./dist/friends/adapters/d1.d.ts", "import": "./dist/friends/adapters/d1.js" },
+    "./friends/d1.sql": "./src/friends/adapters/d1.sql",
+    "./friends/firestore": { "types": "./dist/friends/adapters/firestore.d.ts", "import": "./dist/friends/adapters/firestore.js" },
+    "./friends/panel": { "types": "./dist/friends/panel/index.d.ts", "import": "./dist/friends/panel/index.js" },
+    "./friends/style.css": "./src/friends/panel/style.css"
   },
   "sideEffects": false,
   "files": ["dist", "src", "README.md", "CHANGELOG.md", "LICENSE", "ai"],
@@ -46,5 +53,5 @@
   },
   "homepage": "https://nano133.com/build/nanoterra",
   "license": "MIT",
-  "keywords": ["nano", "gltf", "glb", "model check", "xno", "nanoterra", "sign in", "ticket", "character", "avatar", "three", "three.js", "toon", "looks", "cosmetics"]
+  "keywords": ["nano", "gltf", "glb", "model check", "xno", "nanoterra", "sign in", "ticket", "character", "avatar", "three", "three.js", "toon", "looks", "cosmetics", "friends", "friends list"]
 }

package/src/admin/adapters/d1.ts

@@ -1,5 +1,5 @@
 // The admin store for a game on Cloudflare D1, with the tables of the game starter (migrations/0001_init.sql): `meta`, `orders` and `owned`.
-// It writes ONLY the two settings (`setting:character`, `setting:signin` in `meta`); everything else it does is a read, except when the game turns the sign-in list on
+// It writes ONLY the three settings (`setting:character`, `setting:signin`, `setting:friends` in `meta`); everything else it does is a read, except when the game turns the sign-in list on
 // (`logins: true`): then the one other write is `DELETE FROM sessions WHERE scope = 'admin'` ("sign out everywhere").
 //
 //   import { createD1Store } from "@nano133/nanoterra/admin/d1";
@@ -21,7 +21,7 @@ export interface D1Like {
   batch(statements: D1StatementLike[]): Promise<unknown[]>;
 }
 
-export const D1_KEYS = { character: "setting:character", signin: "setting:signin" } as const;
+export const D1_KEYS = { character: "setting:character", signin: "setting:signin", friends: "setting:friends" } as const;
 
 type Row = { id: string; player: string; look_id: string; usd: string; amount: string; status: string; created_at: number; expires_at: number; paid_at: number | null; payer: string | null; hash: string | null };
 
@@ -34,9 +34,9 @@ type Row = { id: string; player: string; look_id: string; usd: string; amount: s
 export function createD1Store(db: D1Like, options: { logins?: boolean } = {}): AdminStore {
   const store: AdminStore = {
     async readSettings() {
-      const rows = (await db.prepare("SELECT key, value FROM meta WHERE key IN (?, ?)").bind(D1_KEYS.character, D1_KEYS.signin).all<{ key: string; value: string }>()).results;
+      const rows = (await db.prepare("SELECT key, value FROM meta WHERE key IN (?, ?, ?)").bind(D1_KEYS.character, D1_KEYS.signin, D1_KEYS.friends).all<{ key: string; value: string }>()).results;
       const row = (key: string) => rows.find((r) => r.key === key)?.value;
-      return { character: row(D1_KEYS.character), signin: row(D1_KEYS.signin) };
+      return { character: row(D1_KEYS.character), signin: row(D1_KEYS.signin), friends: row(D1_KEYS.friends) };
     },
 
     async saveSettings(patch: GamePatch, now: number) {
@@ -45,6 +45,7 @@ export function createD1Store(db: D1Like, options: { logins?: boolean } = {}): A
       const batch = [];
       if (patch.character) batch.push(write(D1_KEYS.character, patch.character));
       if (patch.signin) batch.push(write(D1_KEYS.signin, patch.signin));
+      if (patch.friends) batch.push(write(D1_KEYS.friends, patch.friends));
       if (batch.length) await db.batch(batch);
     },
 

package/src/admin/adapters/firestore.ts

@@ -1,8 +1,8 @@
 // The admin 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 writes ONLY the two settings; everything else it does is a read.
+// Admin SDK's `Firestore` fits. It writes ONLY the three settings; everything else it does is a read.
 //
 // The data model (the names a game must have; only the three collection names can be changed):
-//   meta/{key}          { value: string, at: number }          keys "setting:character", "setting:signin", "rate" (value is JSON { usd, sources })
+//   meta/{key}          { value: string, at: number }          keys "setting:character", "setting:signin", "setting:friends", "rate" (value is JSON { usd, sources })
 //   orders/{id}         { player, lookId, usd, amount, status, createdAt, expiresAt, paidAt, payer, hash }   `amount` is the raw amount as text
 //   owned/{player__lookId}  { player, lookId, orderId, grantedAt }
 //
@@ -33,7 +33,7 @@ export interface FirestoreLike {
 }
 
 export const FIRESTORE_SCAN_LIMIT = 5000;
-export const FIRESTORE_KEYS = { character: "setting:character", signin: "setting:signin" } as const;
+export const FIRESTORE_KEYS = { character: "setting:character", signin: "setting:signin", friends: "setting:friends" } as const;
 
 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);
@@ -49,8 +49,8 @@ export function createFirestoreStore(db: FirestoreLike, collections: { meta?: st
   };
   return {
     async readSettings() {
-      const [character, signin] = await Promise.all([valueOf(FIRESTORE_KEYS.character), valueOf(FIRESTORE_KEYS.signin)]);
-      return { character: character?.value, signin: signin?.value };
+      const [character, signin, friends] = await Promise.all([valueOf(FIRESTORE_KEYS.character), valueOf(FIRESTORE_KEYS.signin), valueOf(FIRESTORE_KEYS.friends)]);
+      return { character: character?.value, signin: signin?.value, friends: friends?.value };
     },
 
     async saveSettings(patch: GamePatch, now: number) {
@@ -58,6 +58,7 @@ export function createFirestoreStore(db: FirestoreLike, collections: { meta?: st
       let n = 0;
       if (patch.character) (batch.set(db.collection(meta).doc(FIRESTORE_KEYS.character), { value: patch.character, at: now }), n++);
       if (patch.signin) (batch.set(db.collection(meta).doc(FIRESTORE_KEYS.signin), { value: patch.signin, at: now }), n++);
+      if (patch.friends) (batch.set(db.collection(meta).doc(FIRESTORE_KEYS.friends), { value: patch.friends, at: now }), n++);
       if (n) await batch.commit();
     },
 

package/src/admin/conformance.ts

@@ -97,7 +97,7 @@ async function read(res: Response): Promise<{ status: number; text: string; json
 const REFUSAL_KEYS = new Set(["error", "reason", "signedInAs"]);
 
 /** Words of the game's data that a refusal or an answer to a visitor must never hold. */
-const DATA_WORDS = /"orders"|"players"|"totals"|"counts"|"character"|"signin"|"warnings"/;
+const DATA_WORDS = /"orders"|"players"|"totals"|"counts"|"character"|"signin"|"friends"|"warnings"/;
 
 export function adminConformance(host: ConformanceHost): ConformanceCase[] {
   const cases: ConformanceCase[] = [];
@@ -332,7 +332,7 @@ export function adminConformance(host: ConformanceHost): ConformanceCase[] {
 export type StoreHarness = {
   store: AdminStore;
   seed(data: { orders?: OrderRow[]; owned?: { player: string; lookId: string; at: number }[]; rate?: { value: string; at: number } }): Promise<void>;
-  /** Every row that the store could change by mistake, as one text: the orders, the owned looks and the meta rows that are NOT the two settings. Same rows, same text. */
+  /** Every row that the store could change by mistake, as one text: the orders, the owned looks and the meta rows that are NOT the three settings. Same rows, same text. */
   snapshot(): Promise<string>;
   /** Only for a store with `recentLogins` and `signOutEverywhere`: put admin sign-ins in the game's database (the store only reads them). */
   seedLogins?(rows: { at: number; country: string | null; browser: string }[]): Promise<void>;
@@ -358,7 +358,16 @@ export function adminStoreConformance(make: () => Promise<StoreHarness>): Confor
 
   add("a new store has no settings of its own", async ({ store }) => {
     const s = await store.readSettings();
-    check(s.character === undefined && s.signin === undefined, `expected no settings, got ${JSON.stringify(s)}`);
+    check(s.character === undefined && s.signin === undefined && s.friends === undefined, `expected no settings, got ${JSON.stringify(s)}`);
+  });
+
+  add("the friends list is kept as its own setting: each of its three words, and a patch of it leaves the other two", async ({ store }) => {
+    await store.saveSettings({ signin: "none", character: "own" }, NOW);
+    for (const [i, friends] of (["own", "off", "nanoterra"] as const).entries()) {
+      await store.saveSettings({ friends }, NOW + 1 + i);
+      const s = await store.readSettings();
+      check(s.friends === friends && s.signin === "none" && s.character === "own", `after friends ${friends}: ${JSON.stringify(s)}`);
+    }
   });
 
   add("a patch saves only what it names; the next patch keeps the rest", async ({ store }) => {
@@ -376,13 +385,13 @@ export function adminStoreConformance(make: () => Promise<StoreHarness>): Confor
   add("an empty patch writes nothing and does not fail", async ({ store }) => {
     await store.saveSettings({}, NOW);
     const s = await store.readSettings();
-    check(s.character === undefined && s.signin === undefined, "an empty patch must save nothing");
+    check(s.character === undefined && s.signin === undefined && s.friends === undefined, "an empty patch must save nothing");
   });
 
-  add("saving changes nothing but the two settings: no order, no owned look, no other meta row", async (h) => {
+  add("saving changes nothing but the settings: no order, no owned look, no other meta row", async (h) => {
     await h.seed({ orders: [order("1", {}), order("2", { status: "open" })], owned: [{ player: A, lookId: "mint-cap", at: NOW }], rate: { value: JSON.stringify({ usd: 1.2, sources: ["x"] }), at: NOW } });
     const before = await h.snapshot();
-    await h.store.saveSettings({ character: "own", signin: "none" }, NOW + 5);
+    await h.store.saveSettings({ character: "own", signin: "none", friends: "off" }, NOW + 5);
     check((await h.snapshot()) === before, "the rows of the game changed after saving the settings");
   });
 

package/src/admin/handler.ts

@@ -1,8 +1,8 @@
 // The admin handler: the routes of /admin on the Web `Request` and `Response` types, so it fits a Worker, Firebase Functions and Node.
 //
 //   GET  {base}/summary   the numbers: status, orders, the looks that players own
-//   GET  {base}/game      the two switches
-//   POST {base}/game      a press: { character } or { signin } (only the two known words)
+//   GET  {base}/game      the game switches
+//   POST {base}/game      a press: { character }, { signin } or { friends } (only the known words)
 //   POST {base}/check     the payment check, when the game gives one
 //
 // EVERY request under the base goes through `adminAccess` first, before the route is even looked up: a visitor who is not the owner gets 401 or 403
@@ -190,7 +190,7 @@ export function createAdminHandler(options: AdminHandlerOptions): AdminHandler {
   return { routes, basePath: options.basePath ?? "/api/admin", handle };
 }
 
-/** The settings as the game's own routes need them (the listing file, the character): the stored words, or the game's defaults. A fault in the store gives the defaults. */
+/** The settings as the game's own routes need them (the listing file, the character, the friends list): the stored words, or the game's defaults. A fault in the store gives the defaults. */
 export async function loadGameSettings(store: Pick<AdminStore, "readSettings">, defaults: GameSettings): Promise<GameState> {
   try {
     return mergeSettings(await store.readSettings(), defaults);

package/src/admin/index.ts

@@ -2,7 +2,7 @@
 //
 //   adminAccess            the guard: one pure function, who may open /admin
 //   createAdminHandler     the routes, on Request and Response
-//   loadGameSettings       the two switches for the game's own routes
+//   loadGameSettings       the game switches for the game's own routes
 //   createMemoryStore      a store in memory, for tests
 //   (the conformance suite is its own path: "@nano133/nanoterra/admin/conformance"; the adapters are "/admin/d1" and "/admin/firestore")
 
@@ -17,5 +17,5 @@ export type { AdminLogin, AdminOrder, AdminPlayer, AdminStatus, AdminStore, Admi
 export { ORDERS_SHOWN, moneyOf, parseRate, shapeOrders, shapePlayers, statusOf, summarize } from "./summary.js";
 export type { OrderRow } from "./summary.js";
 export { RAW_PER_XNO, xnoText } from "./amount.js";
-export { CHARACTER_NEEDS_SIGNIN, CHARACTER_SIGNIN_OFF, REVIEW_LINK, REVIEW_NOTE, SWITCHES, isCharacter, isSignin, isSigninChoice, mergeSettings, parsePatch, pressOf, signinOn, stateOf } from "./switches.js";
-export type { Character, GamePatch, GameSettings, GameState, Signin, SwitchId } from "./switches.js";
+export { CHARACTER_NEEDS_SIGNIN, CHARACTER_SIGNIN_OFF, DEFAULT_FRIENDS, FRIENDS_CHOICES, FRIENDS_TITLE, REVIEW_LINK, REVIEW_NOTE, SWITCHES, isCharacter, isFriends, isSignin, isSigninChoice, mergeSettings, parsePatch, pressOf, signinOn, stateOf } from "./switches.js";
+export type { Character, Friends, GamePatch, GameSettings, GameState, Signin, SwitchId } from "./switches.js";

package/src/admin/memory.ts

@@ -35,11 +35,12 @@ export function createMemoryStore(seed: { orders?: OrderRow[]; owned?: { player:
     pendingAdminRequests: 0,
     pendingGameRequests: 0,
     async readSettings() {
-      return { character: store.rows.get("setting:character"), signin: store.rows.get("setting:signin") };
+      return { character: store.rows.get("setting:character"), signin: store.rows.get("setting:signin"), friends: store.rows.get("setting:friends") };
     },
     async saveSettings(patch: GamePatch) {
       if (patch.character) store.rows.set("setting:character", patch.character);
       if (patch.signin) store.rows.set("setting:signin", patch.signin);
+      if (patch.friends) store.rows.set("setting:friends", patch.friends);
       store.writes++;
     },
     async summary(now: number): Promise<StoreSummary> {

package/src/admin/panel/gameCard.ts

@@ -1,14 +1,15 @@
-// The "Game" card of /admin: two switches, "Players can play as their Nanoterra character" and "Players can sign in with Nanoterra". A press saves at once
-// (POST {api}/game, behind the same admin guard as every admin call) and the game reads the setting at run time, so the creator pushes and deploys
-// nothing. The words are in ../switches.ts. The card changes ONLY these two settings: never a look, a price or an order.
+// The "Game" card of /admin: two switches, "Players can play as their Nanoterra character" and "Players can sign in with Nanoterra", and one three-way
+// choice, "Friends list: Nanoterra / The game's own / Off". A press saves at once (POST {api}/game, behind the same admin guard as every admin call) and
+// the game reads the setting at run time, so the creator pushes and deploys nothing. The words are in ../switches.ts. The card changes ONLY these three
+// settings: never a look, a price or an order.
 
-import { CHARACTER_NEEDS_SIGNIN, CHARACTER_SIGNIN_OFF, REVIEW_LINK, REVIEW_NOTE, SWITCHES, pressOf, signinOn, stateOf, type GameState, type SwitchId } from "../switches.js";
+import { CHARACTER_NEEDS_SIGNIN, CHARACTER_SIGNIN_OFF, FRIENDS_CHOICES, FRIENDS_TITLE, REVIEW_LINK, REVIEW_NOTE, SWITCHES, pressOf, signinOn, stateOf, type Friends, type GameState, type SwitchId } from "../switches.js";
 import { ApiError, type Api } from "./api.js";
 import { h } from "./dom.js";
 
 /**
  * The card for the settings `initial`. It keeps its own state: a press shows "Saving…", then "Saved." or the server's words. `defaultsFile` is where the game's defaults are
- * written ("game.config.json"). `onChange` hears each saved state (the panel's Overview shows the two switches too).
+ * written ("game.config.json"). `onChange` hears each saved state (the panel's Overview shows the switches too).
  */
 export function gameCard(api: Api, initial: GameState, defaultsFile = "the game's own settings", onChange?: (state: GameState) => void): HTMLElement {
   let state = initial;
@@ -16,7 +17,11 @@ export function gameCard(api: Api, initial: GameState, defaultsFile = "the game'
   /** Under the character switch: it works only through sign-in, so it says so, and says what a player gets while sign-in is Off. */
   const needs = h("p", { class: "fine switch-needs" });
   const card = h("section", { class: "admin-card game-card", "aria-labelledby": "game-title" }, h("div", { class: "card-head" }, h("h2", { id: "game-title" }, "Game")));
-  card.append(h("p", { class: "fine card-intro" }, `Two choices about your game. A press saves at once: you push nothing and deploy nothing. They start from ${defaultsFile}, and a press here wins.`));
+  card.append(h("p", { class: "fine card-intro" }, `Three choices about your game. A press saves at once: you push nothing and deploy nothing. They start from ${defaultsFile}, and a press here wins.`));
+  /** The friends choice: a radio group of three keys (arrow keys move between them, as a radio group does). */
+  const friendsKeys = new Map<Friends, HTMLButtonElement>();
+  const friendsNote = h("p", { class: "switch-note", id: "switch-friends-note" });
+  const friendsStatus = h("span", { class: "fine", role: "status", "aria-live": "polite" });
 
   const draw = () => {
     for (const [id, row] of rows) {
@@ -28,6 +33,29 @@ export function gameCard(api: Api, initial: GameState, defaultsFile = "the game'
     }
     needs.hidden = !stateOf("character", state);
     needs.textContent = signinOn(state.signin) ? CHARACTER_NEEDS_SIGNIN : CHARACTER_SIGNIN_OFF;
+    for (const [id, key] of friendsKeys) {
+      const on = state.friends === id;
+      key.setAttribute("aria-checked", on ? "true" : "false");
+      key.tabIndex = on ? 0 : -1;
+      key.classList.toggle("is-on", on);
+    }
+    friendsNote.textContent = FRIENDS_CHOICES[state.friends]?.note ?? "";
+  };
+
+  const choose = async (id: Friends) => {
+    if (state.friends === id) return;
+    for (const key of friendsKeys.values()) key.disabled = true;
+    friendsStatus.textContent = "Saving…";
+    try {
+      state = await api.post<GameState>("/game", { friends: id });
+      friendsStatus.textContent = "Saved.";
+      draw();
+      onChange?.(state);
+    } catch (e) {
+      friendsStatus.textContent = e instanceof ApiError ? e.message : "The game's server did not answer. Nothing was changed.";
+    } finally {
+      for (const key of friendsKeys.values()) key.disabled = false;
+    }
   };
 
   const press = async (id: SwitchId) => {
@@ -62,6 +90,24 @@ export function gameCard(api: Api, initial: GameState, defaultsFile = "the game'
     // The sign-in word is part of the listing file: Nanoterra's review decides what Nanoterra shows. This page cannot see that review.
     if (id === "signin") card.append(h("p", { class: "fine switch-review" }, REVIEW_NOTE, " ", h("a", { href: REVIEW_LINK, target: "_blank", rel: "noopener noreferrer" }, "Open the launch page")));
   }
+
+  const order = Object.keys(FRIENDS_CHOICES) as Friends[];
+  const group = h("div", { class: "seg friends-choice", role: "radiogroup", "aria-labelledby": "switch-friends-label", "aria-describedby": "switch-friends-note" });
+  for (const id of order) {
+    const key = h("button", { class: "seg-btn", type: "button", role: "radio", "aria-checked": "false", "data-friends": id }, FRIENDS_CHOICES[id].name);
+    key.addEventListener("click", () => void choose(id));
+    key.addEventListener("keydown", (e) => {
+      const step = e.key === "ArrowRight" || e.key === "ArrowDown" ? 1 : e.key === "ArrowLeft" || e.key === "ArrowUp" ? -1 : 0;
+      if (!step) return;
+      e.preventDefault();
+      const next = order[(order.indexOf(id) + step + order.length) % order.length];
+      friendsKeys.get(next)!.focus();
+      void choose(next);
+    });
+    friendsKeys.set(id, key);
+    group.append(key);
+  }
+  card.append(h("div", { class: "switch-row friends-row" }, h("div", { class: "switch-head" }, h("span", { class: "switch-title", id: "switch-friends-label" }, FRIENDS_TITLE), group), friendsNote, friendsStatus));
   draw();
   return card;
 }

package/src/admin/panel/mount.ts

@@ -69,7 +69,7 @@ export function mountAdmin(root: HTMLElement, options: MountOptions): MountedAdm
   let gameState: GameState | null = null;
   let dash: Dashboard | null = null;
 
-  /** The card, made once. A fault in reading the two switches must not hide the orders: the card is left out and the rest still shows. */
+  /** The card, made once. A fault in reading the game switches must not hide the orders: the card is left out and the rest still shows. */
   async function gameSection(): Promise<HTMLElement | null> {
     if (game) return game;
     try {

package/src/admin/panel/overview.ts

@@ -4,7 +4,7 @@
 import type { Look } from "../../looks/look.js";
 import { priceText } from "../../looks/ladder.js";
 import type { AdminSummary } from "../store.js";
-import { SWITCHES, stateOf, type GameState } from "../switches.js";
+import { FRIENDS_CHOICES, FRIENDS_TITLE, SWITCHES, stateOf, type GameState } from "../switches.js";
 import { dollars, h, plural } from "./dom.js";
 import { icon } from "./icons.js";
 import { orderRow, type OrderFilter } from "./orders.js";
@@ -29,7 +29,7 @@ export function bestSellers(s: Pick<AdminSummary, "orders" | "players">, looks:
 export type OverviewView = {
   el: HTMLElement;
   update(s: AdminSummary): void;
-  /** The two switches as they are now (null: they could not be read). */
+  /** The game switches as they are now (null: they could not be read). */
   setGame(state: GameState | null): void;
 };
 
@@ -51,9 +51,10 @@ export function overviewView(looks: readonly Look[], colourOf: (lookId: string)
       const on = game ? stateOf(id, game) : null;
       return h("li", {}, h("span", {}, SWITCHES[id].title), on === null ? h("span", { class: "pill" }, "Unknown") : h("span", { class: `pill ${on ? "pill-on" : "pill-off"}` }, on ? "On" : "Off"));
     });
+    if (game) rows.push(h("li", {}, h("span", {}, FRIENDS_TITLE), h("span", { class: `pill ${game.friends === "off" ? "pill-off" : "pill-on"}` }, FRIENDS_CHOICES[game.friends]?.name ?? "Unknown")));
     gameBox.replaceChildren(
       h("div", { class: "card-head" }, h("h2", { id: "n133-glance-game" }, "Game switches"), linkKey("Change", () => go("settings"))),
-      game ? h("ul", { class: "glance-list" }, ...rows) : h("p", { class: "fine" }, "The two switches could not be read. Reload the page to try again."),
+      game ? h("ul", { class: "glance-list" }, ...rows) : h("p", { class: "fine" }, "The game switches could not be read. Reload the page to try again."),
     );
   }
 

package/src/admin/panel/style.css

@@ -1679,7 +1679,16 @@
   font-size: 12px;
 }
 
-/* ---- The "Game" card: two switches (gameCard.ts). Each is a button of at least 44 px ---- */
+/* ---- The "Game" card: two switches and the friends choice (gameCard.ts). Each is a button of at least 44 px ---- */
+
+/* The friends choice: three keys in a row that wraps on a narrow phone, each 44 px tall. */
+.n133-admin .game-card .friends-row .switch-head {
+  flex-wrap: wrap;
+}
+
+.n133-admin .game-card .friends-choice .seg-btn {
+  min-height: 44px;
+}
 
 .n133-admin .game-card .switch-row {
   display: grid;