@nano133/nanoterra 0.4.0 → 0.6.0

package/src/friends/panel/style.css

@@ -0,0 +1,303 @@
+/* The Friends key and panel (mountFriends in ./mount.ts). Every rule is under .n133-friends, so nothing leaks into the game's page.
+   Phone first: every key is 44 px or more. On a phone held upright the panel is a sheet from the bottom; on a wide or sideways screen it is a
+   sheet on the right. In "nanoterra" mode the nano133 window stays in the page while the panel is closed (it holds the live connection): the
+   closed panel is hidden and moved off the screen, never display: none.
+   To theme it, set the --n133-* custom properties on the element that holds the key (or a parent): --n133-ink, --n133-ink-soft, --n133-paper,
+   --n133-line, --n133-gem, --n133-gem-dark, --n133-radius, --n133-font and --n133-friends-z (the panel's z-index, default 1000). */
+
+.n133-friends {
+  --font: var(--n133-font, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);
+  --gem: var(--n133-gem, #20c9a6);
+  --gem-dark: var(--n133-gem-dark, #0e8a72);
+  --ink: var(--n133-ink, #16202e);
+  --ink-soft: var(--n133-ink-soft, #4a5568);
+  --line: var(--n133-line, #dbe4ee);
+  --paper: var(--n133-paper, #ffffff);
+  --radius: var(--n133-radius, 18px);
+  display: inline-block;
+  color: var(--ink);
+  font: 15px/1.4 var(--font);
+}
+
+.n133-friends *,
+.n133-friends *::before,
+.n133-friends *::after {
+  box-sizing: border-box;
+}
+
+.n133-friends .n133f-key {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 14px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: var(--paper);
+  color: var(--ink);
+  font: 650 15px/1 var(--font);
+  cursor: pointer;
+  touch-action: manipulation;
+}
+
+.n133-friends .n133f-badge {
+  min-width: 20px;
+  height: 20px;
+  padding: 0 6px;
+  border-radius: 10px;
+  background: #d92d4b;
+  color: #fff;
+  font: 700 12px/20px var(--font);
+  text-align: center;
+}
+
+/* No requests: the badge counts the friends online, in the gem colour. */
+.n133-friends .n133f-badge.is-online {
+  background: var(--gem-dark);
+}
+
+.n133-friends .n133f-panel {
+  position: fixed;
+  z-index: var(--n133-friends-z, 1000);
+  right: 0;
+  bottom: 0;
+  left: 0;
+  display: flex;
+  flex-direction: column;
+  height: min(80vh, 640px);
+  height: min(80dvh, 640px);
+  border: 1px solid var(--line);
+  border-radius: var(--radius) var(--radius) 0 0;
+  background: var(--paper);
+  box-shadow: 0 -8px 30px rgb(16 24 40 / 0.18);
+  padding-bottom: env(safe-area-inset-bottom);
+}
+
+/* Closed: not shown, off the screen and out of the tab order, but still in the page (the window keeps its connection). */
+.n133-friends .n133f-panel[data-open="false"] {
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(110%);
+}
+
+@media (min-width: 640px), (orientation: landscape) and (max-height: 520px) {
+  .n133-friends .n133f-panel {
+    top: 0;
+    left: auto;
+    width: min(380px, 100vw);
+    height: auto;
+    border-radius: var(--radius) 0 0 var(--radius);
+    box-shadow: -8px 0 30px rgb(16 24 40 / 0.18);
+    padding-bottom: 0;
+    padding-right: env(safe-area-inset-right);
+  }
+
+  .n133-friends .n133f-panel[data-open="false"] {
+    transform: translateX(110%);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .n133-friends .n133f-panel {
+    transition: transform 180ms ease-out, visibility 0s linear 180ms;
+  }
+
+  .n133-friends .n133f-panel[data-open="true"] {
+    transition: transform 180ms ease-out, visibility 0s;
+  }
+}
+
+.n133-friends .n133f-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 8px 8px 8px 18px;
+  border-bottom: 1px solid var(--line);
+}
+
+.n133-friends .n133f-title {
+  margin: 0;
+  font: 750 18px/1.2 var(--font);
+}
+
+.n133-friends .n133f-close {
+  display: grid;
+  place-items: center;
+  width: 44px;
+  height: 44px;
+  border: 0;
+  border-radius: 12px;
+  background: transparent;
+  color: var(--ink);
+  cursor: pointer;
+}
+
+.n133-friends .n133f-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+}
+
+.n133-friends .n133f-nanoterra .n133f-body {
+  overflow: hidden;
+}
+
+.n133-friends .n133f-window {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+
+.n133-friends .n133f-own .n133f-body {
+  padding: 12px 16px 16px;
+}
+
+.n133-friends .n133f-add {
+  display: flex;
+  gap: 8px;
+}
+
+.n133-friends .n133f-input {
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 44px;
+  padding: 0 12px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  background: var(--paper);
+  color: var(--ink);
+  font: 16px/1 var(--font);
+}
+
+.n133-friends .n133f-btn {
+  min-height: 44px;
+  padding: 0 14px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  background: var(--paper);
+  color: var(--ink);
+  font: 650 14px/1 var(--font);
+  white-space: nowrap;
+  cursor: pointer;
+  touch-action: manipulation;
+}
+
+.n133-friends .n133f-primary {
+  border-color: var(--gem-dark);
+  background: var(--gem-dark);
+  color: #fff;
+}
+
+.n133-friends .n133f-quiet {
+  color: var(--ink-soft);
+}
+
+.n133-friends :is(.n133f-key, .n133f-close, .n133f-btn, .n133f-input, .n133f-check):focus-visible {
+  outline: 3px solid var(--gem);
+  outline-offset: 2px;
+}
+
+.n133-friends .n133f-status:empty {
+  display: none;
+}
+
+.n133-friends .n133f-status {
+  margin: 8px 0 0;
+  color: var(--ink-soft);
+  font-size: 14px;
+}
+
+.n133-friends .n133f-group {
+  margin: 16px 0 6px;
+  color: var(--ink-soft);
+  font: 700 13px/1.2 var(--font);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.n133-friends .n133f-rows {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.n133-friends .n133f-row {
+  display: grid;
+  grid-template-columns: 12px minmax(0, 1fr);
+  gap: 4px 10px;
+  align-items: start;
+  padding: 10px 12px;
+  border: 1px solid var(--line);
+  border-radius: 14px;
+}
+
+.n133-friends .n133f-dot {
+  width: 10px;
+  height: 10px;
+  margin-top: 6px;
+  border-radius: 50%;
+  background: var(--line);
+}
+
+.n133-friends .n133f-row.is-online .n133f-dot {
+  background: var(--gem);
+}
+
+.n133-friends .n133f-who {
+  display: grid;
+  min-width: 0;
+}
+
+.n133-friends .n133f-who strong {
+  overflow-wrap: anywhere;
+}
+
+.n133-friends .n133f-line,
+.n133-friends .n133f-invite {
+  margin: 0;
+  color: var(--ink-soft);
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}
+
+.n133-friends .n133f-invite {
+  color: var(--gem-dark);
+  font-weight: 650;
+}
+
+.n133-friends .n133f-keys {
+  display: flex;
+  flex-wrap: wrap;
+  grid-column: 2;
+  gap: 6px;
+}
+
+.n133-friends .n133f-keys:empty {
+  display: none;
+}
+
+.n133-friends .n133f-empty {
+  margin: 16px 0;
+  color: var(--ink-soft);
+}
+
+.n133-friends .n133f-show {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 44px;
+  margin-top: 16px;
+  cursor: pointer;
+}
+
+.n133-friends .n133f-check {
+  width: 22px;
+  height: 22px;
+}

package/src/friends/panel/window.ts

@@ -0,0 +1,79 @@
+// The nano133 friends window: the contract between the kit and nano133's page /embed/friends (contract v1, accepted by the site on 2026-10-30).
+// The window holds the player's Nanoterra friends and their live connection; the game gets none of them. It says only its height, two counts for
+// the badge, that it needs a tap (Storage Access), and a friend's https address to join (the kit asks the player first). No message carries an
+// address, a pass or a player id.
+
+/** The `source` of every message, both ways. A message with another `source` is not for this contract. */
+export const WINDOW_SOURCE = "nanoterra-friends";
+/** The version of the messages. A message with another `v` is ignored. */
+export const WINDOW_V = 1;
+
+type Head = { source: "nanoterra-friends"; v: 1 };
+
+/** Messages from the game's page to the window (sent with the window's origin as the target). */
+export type ToWindow = Head & ({ type: "open" } | { type: "closed" } | { type: "where"; where: string | null });
+
+/** Messages from the window that the kit acts on. Anything else is ignored. */
+export type FromWindow = Head &
+  ({ type: "ready" } | { type: "size"; height: number } | { type: "badge"; online: number; requests: number } | { type: "join"; url: string } | { type: "signin" });
+
+/** The window's address for a game. */
+export function windowUrl(origin: string, game: string): string {
+  return `${origin}/embed/friends?game=${encodeURIComponent(game)}&v=${WINDOW_V}`;
+}
+
+/** A message to the window. */
+export function toWindow(m: { type: "open" } | { type: "closed" } | { type: "where"; where: string | null }): ToWindow {
+  return { source: WINDOW_SOURCE, v: WINDOW_V, ...m };
+}
+
+/**
+ * The game's `where` as the kit sends it: plain text, control characters removed, trimmed, at most 64 characters (the site does the same again and
+ * shows it as text only). Null when nothing is left.
+ */
+export function whereText(where: unknown): string | null {
+  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, 64).join("").trim();
+  return cut || null;
+}
+
+const count = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.min(99, Math.floor(v)) : null);
+
+/** A message from the window, checked: its source, its version, its type and each field. Null for anything else (a bad field too). */
+export function readWindowMessage(data: unknown): FromWindow | null {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const m = data as Record<string, unknown>;
+  if (m.source !== WINDOW_SOURCE || m.v !== WINDOW_V || typeof m.type !== "string") return null;
+  const head: Head = { source: WINDOW_SOURCE, v: WINDOW_V };
+  switch (m.type) {
+    case "ready":
+    case "signin":
+      return { ...head, type: m.type };
+    case "size": {
+      if (typeof m.height !== "number" || !Number.isFinite(m.height) || m.height < 0) return null;
+      return { ...head, type: "size", height: Math.min(10_000, Math.ceil(m.height)) };
+    }
+    case "badge": {
+      const online = count(m.online);
+      const requests = count(m.requests);
+      if (online === null || requests === null) return null;
+      return { ...head, type: "badge", online, requests };
+    }
+    case "join": {
+      if (typeof m.url !== "string" || m.url.length > 2048) return null;
+      let url: URL;
+      try {
+        url = new URL(m.url);
+      } catch {
+        return null;
+      }
+      // https only: an island friend's room on nano133, or a friend's game at its listed address. No name or password in it.
+      if (url.protocol !== "https:" || url.username || url.password) return null;
+      return { ...head, type: "join", url: url.href };
+    }
+    default:
+      return null;
+  }
+}

package/src/friends/rules.ts

@@ -0,0 +1,196 @@
+// 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, type FriendRow, type FriendState } from "./types.js";
+
+/** An edge as an adapter keeps it. `a` and `b` are the two players' ids, `a < b`. `rev` grows with each write (an adapter may use it to refuse a write on a row that changed). */
+export type EdgeRec = {
+  edge: string;
+  a: string;
+  b: string;
+  from: string;
+  state: "pending" | "friend" | "blocked";
+  blockedBy: string[];
+  at: number;
+  invite: { from: string; where: string; at: number } | null;
+  rev: number;
+};
+
+/** What an adapter does after a rule: write this edge (new or changed), delete it, or nothing. */
+export type Plan = { put: EdgeRec } | { drop: EdgeRec } | { none: true };
+
+/** A presence row: where a player is, which tab said so, and when. */
+export type PresenceRec = { player: string; where: string; lease: string; at: number };
+
+/** The two ids of a pair in the order an adapter keeps them. */
+export const pairOf = (x: string, y: string): [string, string] => (x < y ? [x, y] : [y, x]);
+export const otherOf = (rec: EdgeRec, me: string): string => (rec.a === me ? rec.b : rec.a);
+export const hasPlayer = (rec: EdgeRec, me: string): boolean => rec.a === me || rec.b === me;
+
+/** A request that nobody answered in time is gone; anything else is live. */
+export const liveEdge = (rec: EdgeRec, now: number): boolean => rec.state !== "pending" || now - rec.at < FRIEND_REQUEST_MS;
+
+/** A new opaque edge id: random, never made from a player id. */
+export function newEdgeId(): string {
+  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: unknown): string | null {
+  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: EdgeRec, me: string, now: number): FriendState | null {
+  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: EdgeRec | null, me: string, now: number): EdgeRec {
+  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: string, other: string, rec: EdgeRec | null, now: number, counts: () => Promise<{ mine: number; theirs: number }>): Promise<Plan> {
+  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: string, rec: EdgeRec | null, now: number): Plan {
+  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: string, rec: EdgeRec | null, now: number): Plan {
+  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: string, rec: EdgeRec | null, now: number): Plan {
+  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: string, rec: EdgeRec | null, now: number): Plan {
+  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: string, rec: EdgeRec | null, now: number): Plan {
+  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: string, rec: EdgeRec | null, where: unknown, now: number): Plan {
+  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: unknown, lease: unknown): { where: string | null; lease: string } {
+  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: string, where: string | null, lease: string, was: PresenceRec | null, now: number): { put: PresenceRec } | { drop: true } | { none: true } {
+  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: PresenceRec | null | undefined, now: number): p is PresenceRec => 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: Record<FriendState, number> = { 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: string, recs: EdgeRec[], now: number, names: Map<string, string>, presence: Map<string, PresenceRec>, showOnline: Map<string, boolean>): FriendRow[] {
+  const rows: (FriendRow & { rank: number })[] = [];
+  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: string, recs: EdgeRec[], now: number): string[] {
+  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: string, recs: EdgeRec[], now: number): string[] {
+  return recs.filter((r) => stateFor(r, me, now) === "friend").map((r) => otherOf(r, me));
+}

package/src/friends/types.ts

@@ -0,0 +1,57 @@
+// 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.)
+
+/** 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 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;
+
+/** 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 class FriendsError extends Error {
+  constructor(
+    public status: 400 | 401 | 403 | 404 | 409 | 413 | 429,
+    message: string,
+  ) {
+    super(message);
+    this.name = "FriendsError";
+  }
+}