@nano133/nanoterra 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.6.0 (2026-10-30)
+
+- **A friends list for the game's players** (`@nano133/nanoterra/friends`, `/friends/d1`, `/friends/firestore`, `/friends/conformance`, `/friends/panel` and
+  `/friends/style.css`). The admin's Game card has a third choice, **"Friends list: Nanoterra / The game's own / Off"** (Nanoterra by default):
+  - **Nanoterra:** `mountFriends(el, { mode: "nanoterra", game })` puts a Friends key in the game and holds nano133's friends window
+    (`https://nano133.com/embed/friends?game=<id>&v=1`) in its panel. The friends stay on nano133; the game gets none of them, only the window's height, two
+    counts for the badge (requests, else friends online) and a friend's https address to join (the kit asks the player first). The window
+    is loaded at once and kept while the panel is closed, because it holds the player's live connection ("Playing <game>" for their friends). The messages
+    are contract v1 with the site, `{ source: "nanoterra-friends", v: 1, type }` (README, "The nano133 window").
+  - **The game's own:** a full friends list of the game's own players on the game's own database: requests (by name, through the game's `PlayerDirectory`),
+    accept, decline, remove, block and unblock, invites ("come to Level 2"), and online with a place. `createFriendsHandler` gives the routes (GET the view,
+    POST an op; same origin, 30 calls a minute for each player; no answer holds a player id). The stores: `createMemoryFriends`, `createD1Friends` (with the
+    migration `@nano133/nanoterra/friends/d1.sql`) and `createFirestoreFriends` (a small interface the Admin SDK fits). `friendsStoreConformance` proves the
+    rules on any store; the package runs it on all three (and on the Firestore emulator through the Admin SDK). The panel polls the view every 20 s while open
+    and pulses every 45 s with a lease for each tab.
+  - **Off:** nothing is drawn.
+- **The admin's settings have a third word, `friends`** (`"nanoterra" | "own" | "off"`): `GameState` has `friends` and `fromAdmin.friends`, a press may send
+  `{ friends }`, the stores keep `setting:friends` (D1 and Firestore beside the two settings), and `GameSettings.friends` is optional (Nanoterra when left out).
+  A game that compares the whole `GameState` (a test with `deepEqual`) adds the two new fields.
+
+## 0.5.0 (2026-10-30)
+
+- **Wear slots** (`@nano133/nanoterra/looks`, and the Shelf of `/admin/panel`): a look fills one wear slot, and a player wears one look in each slot at once. An outfit (no
+  `wear`, or `"outfit"`: `OUTFIT`) is the character's own look, with its `change` (the body colour and the hat), as before. Any other `wear` is the game's own slot (a tool's
+  skin, a charm: `"wear": "shovel"`): an item there has no `change`. `lookProblems` refuses a bad slot name (field `wear`) and a `change` on an item (field `change`), and
+  now asks for one free OUTFIT (a list of outfits only keeps the starter's words); `checkLooks` leaves `wear` out for an outfit and `change` out for an item; `looksJson`
+  writes `wear` after `priceUsd`; `removalProblems` refuses a changed wear slot on an owned look (field `wear`); `diffLooks` lists `"wear"`. New: `OUTFIT`, `wearOf`,
+  `isOutfit`, the type `Change`. **`Look.change` is optional in the type now** (read an outfit's colours after `isOutfit`): a game that reads `look.change.body` directly
+  changes that line. The Shelf shows an item's slot and a tag picture, edits its wear slot (locked for an owned look and the last free outfit) in place of the body and hat,
+  and its message for an AI assistant names the wear rule. A file of outfits only reads and writes exactly as before. Echo Island sells shovel and Pinger skins and charms
+  with it (Wes, 2026-10-30).
+
 ## 0.4.0 (2026-10-30)
 
 - **The admin panel (`@nano133/nanoterra/admin/panel`) has a new layout: the game at a glance, in tabs.** A top bar (who is signed in, Live or Test mode, the bot

package/README.md

@@ -10,6 +10,7 @@ themselves. This package gives your game four things:
 - **The player's character** (`/character`): the same toon body that the player has on the island, drawn with Three.js. Six bases, faces, hair, clothes, sizes and colours.
 - **The looks ladder** (`/looks`): the rules of `looks.json`, the price steps, and what a change does to the players who own a look.
 - **Held input that does not stick** (`/input`, since 0.3.1): lets go of the keys and the stick when the player leaves the page, so the character never walks on by itself, and pauses a free round.
+- **A friends list** (`/friends`, unreleased): a Friends key that holds the player's Nanoterra friends (a nano133 window), or a full friends list of the game's own players on the game's own database, as the admin's Game card chooses.
 
 It replaces `@nano133/character` 0.1.0, `@nano133/ticket` 0.1.0 and `@nano133/looks` 0.1.0
 (see "Moving from the three old packages"). Sign-in, checkout and late returns stay in their own packages
@@ -68,8 +69,12 @@ Each path loads only what it needs. A page that reads a ticket loads no Three.js
 | `@nano133/nanoterra/admin/d1`, `/admin/firestore` | the admin store for D1 (the starter's tables) or Firestore (a small interface, no Firebase dependency): `createD1Store`, `createFirestoreStore` (since 0.2.0) | no | 1.5 kB each |
 | `@nano133/nanoterra/admin/panel` | the admin page, drawn in the browser into one element, and its stylesheet `@nano133/nanoterra/admin/style.css` (since 0.2.0) | no | 18.9 kB with the tabbed layout (10.6 kB on 0.3.0, 8.5 kB on 0.2.0) + 5.9 kB of CSS (minified) |
 | `@nano133/nanoterra/admin/conformance` | test cases that a game runs against its own admin (a dev dependency in practice; since 0.2.0) | no | n/a |
+| `@nano133/nanoterra/friends` | the game's own friends list: the handler, the rules, a memory store (server code; unreleased) | no | 3.7 kB |
+| `@nano133/nanoterra/friends/d1`, `/friends/firestore` | the friends store for D1 (with the migration `/friends/d1.sql`) or Firestore (a small interface, no Firebase dependency): `createD1Friends`, `createFirestoreFriends` (unreleased) | no | 3.0 kB each |
+| `@nano133/nanoterra/friends/panel` | the Friends key and panel: the nano133 window, or the game's own list, and its stylesheet `@nano133/nanoterra/friends/style.css` (unreleased) | no | 5.0 kB + 4.8 kB of CSS (minified) |
+| `@nano133/nanoterra/friends/conformance` | the friends rules as test cases, for a store a game writes itself (unreleased) | no | n/a |
 
-Measured 2026-10-26: `esbuild --bundle --minify --format=esm --external:three`, then `gzip -9`, without Three.js.
+Measured 2026-10-26 (the friends paths 2026-10-30): `esbuild --bundle --minify --format=esm --external:three`, then `gzip -9`, without Three.js.
 All four paths together: 23.6 kB. A test of the package proves that the record, the ticket, the looks and the small part import no package at all.
 
 ## The character
@@ -380,11 +385,38 @@ type Look = {
   id: string; // 1 to 40 lowercase letters, digits or dashes: "mint-cap"
   name: string; // 1 to 40 characters
   priceUsd: number; // US dollars, at most 2 decimals; 0 is the free look
-  change: { body: string; hat?: "cap" | "beanie" | "crown" | "tophat"; hatColor?: string }; // colours are "#rrggbb"
+  wear?: string; // the wear slot it fills: none (an outfit), or your game's own slot ("shovel"): see "Wear slots" below
+  change?: { body: string; hat?: "cap" | "beanie" | "crown" | "tophat"; hatColor?: string }; // an outfit's colours ("#rrggbb"); an item of another slot has none
   slots?: Record<string, string>; // what YOUR game defines for itself: see "Slots" below. Optional.
 };
 ```
 
+### Wear slots: an outfit, and the items beside it
+
+A look fills one **wear slot**, and a player wears one look in each slot at once. An **outfit** (no `wear`, or `"wear": "outfit"`) is the character's own look: its body colour and
+its hat (`change`). Every other wear slot is **your game's own**: a tool's skin, a charm, a trail. An item there has **no `change`** (it does not change the body); your game knows
+what it is from its id or its `slots`:
+
+```json
+{ "id": "classic", "name": "Classic", "priceUsd": 0, "change": { "body": "#4aa8ff" } },
+{ "id": "toy-spade", "name": "Toy Spade", "priceUsd": 0.1, "wear": "shovel" },
+{ "id": "echo-bat", "name": "Echo Bat", "priceUsd": 1, "wear": "pinger", "slots": { "ring": "ripples" } }
+```
+
+- A wear slot's name is like a slot's: 1 to 24 lowercase letters, digits or dashes, starting with a letter (`SLOT_NAME_PATTERN`); `outfit` (`OUTFIT`) is the outfit's.
+- **Keep one free OUTFIT:** every player starts with it. A free item is fine beside it, but it does not count.
+- `"change"` on an item is a mistake (`lookProblems`, field `change`): an item never changes the body. An outfit still needs its `change.body`.
+- `checkLooks` leaves `wear` out for an outfit (no `wear` and `"wear": "outfit"` are the same look) and `change` out for an item; `looksJson` writes `wear` after `priceUsd`, on the
+  look's own line. `wearOf(look)` gives the slot (`OUTFIT` for an outfit); `isOutfit(look)` tells an outfit (with its `change`) from an item.
+- **Players own a look by its id, so the wear slot of a look that a player owns must not change:** a shovel that a player owns stays a shovel. `removalProblems` reports it with the
+  field `"wear"`; `diffLooks` lists it as `"wear"`.
+- The Shelf shows an item's slot on its card ("Worn in the shovel slot") and a tag in place of the character picture (give the Shelf your own `picture` to draw the real item), and
+  its editor has a **Wear slot** field (locked for an owned look and the last free outfit) in place of the body and hat of an outfit.
+- What a player wears in each slot is your game's to keep (the starter keeps the outfit in the browser); ownership stays by id, as before.
+
+A file of outfits only reads and writes exactly as it did. `change` is optional in the type now: read an outfit's colours after `isOutfit(look)` (or `look.change?.body`). This is a
+minor change (0.5.0); a game on 0.4 or before drops `wear`, so a game with items must move to the new version in the game, the server and the Shelf.
+
 ### Slots: what your game defines on a look
 
 A game with its own parts (a pair of wings, a trail colour) needs a place for them on a look. That place is `slots`, an optional object of names and values:
@@ -453,7 +485,7 @@ import { createAdminHandler } from "@nano133/nanoterra/admin";
 
 const admin = createAdminHandler({
   store,                                   // your database: readSettings(), saveSettings(patch, now), summary(now)  (a memory store is in the package, for tests)
-  defaults: { character: "nanoterra", signin: "exchange" },   // what the two switches are until /admin sets them (your game.config.json)
+  defaults: { character: "nanoterra", signin: "exchange", friends: "nanoterra" },   // what the switches are until /admin sets them (your game.config.json; friends may be left out)
   owner: ownerAddress,                     // "nano_..." lowercase, its checksum checked by you; null when none is set
   session: (req, now) => readAdminSession(req, now),          // YOUR admin login: its own cookie; return { address, createdAt, via: "wallet" } or null
   status: (now, summary) => ({ address: ownerAddress, testMode, warnings }),   // what only your game knows (the store's numbers come too, for a warning like "2 payments came late")
@@ -479,7 +511,7 @@ neither header (curl) and the browser's own address bar (`Sec-Fetch-Site: none`)
 **The handler** sends every request under the base path (`/api/admin` by default) through the guard first, before the route is looked up: a visitor who is not the owner
 gets 401 or 403 for any path, so nothing about the routes leaks. A POST must come from the game's own page (`Origin`, else `Sec-Fetch-Site: same-origin`). It sets no CORS
 header, always sends `Cache-Control: no-store`, reads at most 512 bytes of a press, and limits presses to 30 a minute. A fault in your store gives a plain 500 that shows
-nothing of the fault (`onError` hears it). The only writes are the two settings (and, when the game turns on the sign-in list, the deletion of the admin sessions), **never a look, a price or an order**: a change of looks stays a change of your repository.
+nothing of the fault (`onError` hears it). The only writes are the three settings (and, when the game turns on the sign-in list, the deletion of the admin sessions), **never a look, a price or an order**: a change of looks stays a change of your repository.
 
 **Your own routes read the switches** with `loadGameSettings(store, defaults)` (for the listing file's `signin` word and for the character): the stored word, else your default,
 and your defaults when the store fails.
@@ -527,8 +559,8 @@ admin may make an admin login, and never from another sign-in. A security read f
 
 ### The store (an adapter for your database)
 
-`createAdminHandler` needs a store: three calls, `readSettings()`, `saveSettings(patch, now)` and `summary(now)`. Two adapters come with the package, and **both write only the two settings** (the D1 store also deletes the admin sessions, but only when the game turns on the sign-in list: see below)
-(`setting:character` and `setting:signin`); every other call they make is a read. Both must pass the same **store contract**, `adminStoreConformance(make)` in
+`createAdminHandler` needs a store: three calls, `readSettings()`, `saveSettings(patch, now)` and `summary(now)`. Two adapters come with the package, and **both write only the three settings** (the D1 store also deletes the admin sessions, but only when the game turns on the sign-in list: see below)
+(`setting:character`, `setting:signin` and `setting:friends`); every other call they make is a read. Both must pass the same **store contract**, `adminStoreConformance(make)` in
 `@nano133/nanoterra/admin/conformance`: the settings are kept and accumulate, saving changes no order, no owned look and no other row, an open order past its expiry counts as expired,
 the money is totalled right, the newest 500 orders come first, and a bad rate row is ignored. A game with another database writes its own store and runs the same contract.
 
@@ -587,10 +619,10 @@ mountAdmin(document.getElementById("admin")!, {
 
 The panel draws, from the top: a bar with who is signed in (the short address and a copy key), Live or Test mode, the bot check and Sign out; what is still off (the
 status warnings, one banner); four numbers (Earned, Open now, To send back, Players: a press opens the list behind each); then five tabs. **Overview**: the best-selling
-looks with their share of the money, the last five orders, the two switches as On or Off and the shelf in numbers (a game with no order yet gets three first steps).
+looks with their share of the money, the last five orders, the switches as On or Off (and the friends list's choice) and the shelf in numbers (a game with no order yet gets three first steps).
 **Cosmetics**: the **Shelf** (below). **Orders**: a filter by status with its count, a search (a look, an address or a block), "Check payments now" when the game gave a
 check, "Paid late" with the address to send the money back to, 20 orders at a time; a card each on a phone, a table on a wide panel. **Players**: each player who owns a
-look, with their looks. **Settings**: the **Game** card (the two switches), the Sign-ins card and the facts (the address, the mode, the nodes, the last price). The tabs are
+look, with their looks. **Settings**: the **Game** card (the two switches and the friends list's three-way choice), the Sign-ins card and the facts (the address, the mode, the nodes, the last price). The tabs are
 real tabs (the arrow keys, Home and End work); every tab is made once, so a draft, a search and a switch keep their state, and the panel never writes the page's address.
 A visitor who is signed out gets the game's sign-in; a wrong wallet, a Nanoterra sign-in and a missing owner address each get their own screen and see no data (a sign-out
 takes the drawn data off the page). Options: `api` (the handler's base path), `noAddressHelp`, `lookPicture(look)` (your own picture of a look for the Shelf), `repoHelp`,
@@ -625,7 +657,7 @@ flat picture stays. `createLookPreview({ size?, body?, record?, background?, key
 
 **The Shelf never writes.** It edits a draft in the owner's browser and gives text to copy (`looks.json`, or a message for an AI assistant): there is no call in the panel that
 changes a look, a price or an order, and a test proves that editing the Shelf sends no request. A change of looks is a change of your repository. The **Game** card writes only the
-two settings. The stylesheet is scoped under `.n133-admin`, so it cannot leak into your page; to theme it set `--n133-ink`, `--n133-ink-soft`, `--n133-paper`, `--n133-line`,
+three settings. The stylesheet is scoped under `.n133-admin`, so it cannot leak into your page; to theme it set `--n133-ink`, `--n133-ink-soft`, `--n133-paper`, `--n133-line`,
 `--n133-gem`, `--n133-gem-dark`, `--n133-sea`, `--n133-radius`, `--n133-font`, `--n133-ground` (the wells inside a card), `--n133-warn`, `--n133-bad` or `--n133-shadow` on the
 element that holds it. The keys, inputs, switches, swatches and price steps are 44 px or more; the tabs, filter keys and copy keys 40 px. The layout follows the panel's own
 width (a container query), not the window's: on a phone two cards a row and the five tabs as icons over their words; three cards a row and the orders as a table from
@@ -633,6 +665,126 @@ width (a container query), not the window's: on a phone two cards a row and the
 
 The wallet sign-in stays yours (`signIn`), because only your game can start a request in the ADMIN scope with its own cookie. The panel never signs anyone in.
 
+## The friends list (`/friends`; unreleased)
+
+A Friends key for the game, and a list behind it. The admin's **Game** card chooses which list (`friends` in the settings; Nanoterra by default):
+
+| Choice | The word | What the player gets |
+|---|---|---|
+| Nanoterra | `"nanoterra"` | their **Nanoterra friends**, in a small nano133 window in the game. Friends on Nano Island see "Playing <game>" with Join. The friends stay on nano133: the game gets none of them. |
+| The game's own | `"own"` | a friends list of **the game's own players**, on the game's own database (this package's handler and stores). Nanoterra friends do not show. |
+| Off | `"off"` | nothing. |
+
+```ts
+import { mountFriends } from "@nano133/nanoterra/friends/panel";
+import "@nano133/nanoterra/friends/style.css";
+
+const settings = await (await fetch("/api/settings")).json();       // your route: loadGameSettings(store, defaults) from "@nano133/nanoterra/admin"
+const friends = mountFriends(document.getElementById("friends")!, {
+  mode: settings.friends,          // "nanoterra" | "own" | "off"
+  game: "echo-island",             // your game's id on Nanoterra (its listing's id)
+  where: "Lobby",                  // where the player is, in your words: friends see it
+  onJoin: (target) => go(target),  // optional: "nanoterra" gives a friend's https address, "own" an invite's place (and the friend's name)
+});
+friends.setWhere("Level 2");       // when the player moves; null for no place
+// friends.open(), friends.close(), friends.destroy()
+```
+
+The key is 44 px, with a badge (the requests, or else the friends online). The panel is a sheet from the bottom on a phone held upright and from the right on a wide or sideways screen;
+Escape and its close key close it. Theme it with the same `--n133-*` properties as the admin panel, and `--n133-friends-z` for its z-index (default 1000).
+
+### The nano133 window (contract v1 with the site)
+
+In `"nanoterra"` mode the panel holds an `<iframe>` of `https://nano133.com/embed/friends?game=<gameId>&v=1` (`origin` changes the host, for a test). The site lets
+only a **listed** game's own address frame it. This is the contract between the kit and the site, version 1 (accepted by the site on 2026-10-30):
+
+- **Loaded at once, kept while closed.** The window is made when `mountFriends` runs (no lazy loading) and stays while the panel is closed: it holds the player's
+  live connection to nano133's room server, which shows "Playing <game>" to their friends and keeps the badge true. Closed, it is hidden (`visibility: hidden`, moved
+  off the screen, `aria-hidden="true"` and `tabindex="-1"`), never `display: none` and never removed. `open` and `closed` change only the window's own view.
+  `destroy()` removes it.
+- **The frame:** `title="Friends"`, `referrerpolicy="origin"`, `allow="storage-access"`, and
+  `sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-storage-access-by-user-activation"`: no top navigation,
+  so the window can never move the game's page.
+- **Messages** are objects `{ source: "nanoterra-friends", v: 1, type, ... }`, both ways. The window sends with `parent.postMessage(msg, <the game's origin>)`; the kit
+  sends with `iframe.contentWindow.postMessage(msg, <nano133's origin>)`. Both sides check `event.origin` and `event.source`. A message with another `source`, another
+  `v`, another type or a bad field is ignored. **No message carries an address, a pass or a player id.**
+
+| Direction | `type` | Fields | What the other side does |
+|---|---|---|---|
+| window → game | `ready` | | the window has loaded. The kit answers at once with `where`, then `open` or `closed` (it sends nothing before `ready`). |
+| window → game | `size` | `height` (CSS pixels its content needs) | the kit sets the frame's height to it, at most the panel's own height |
+| window → game | `badge` | `online`, `requests` (each 0 to 99) | the key's badge shows the requests (the thing to do) when there are any, else the friends online in the gem colour; "9+" from 10. The key's name says both ("Friends, 2 requests, 5 online"). |
+| window → game | `join` | `url` | the player chose Join on a friend. The kit asks "Leave this game to join your friend?" (the window sends no name), then calls `onJoin(url)`, or goes to the address when there is no `onJoin`. |
+| window → game | `signin` | | the window needs a tap for Storage Access, inside itself. The panel stays as it is; the kit does nothing else. |
+| game → window | `where` | `where` (text or null) | after `ready`, and again on each `setWhere` |
+| game → window | `open`, `closed` | | after `ready` (after `where`), and when the panel opens or closes |
+
+- **`where` is plain text, and friends see it.** The kit removes control characters, trims it and cuts it to 64 characters before it sends it; it may send null (no
+  place). The site does the same again and shows it as text only.
+- **Join:** `url` is **https only** (no user name or password in it): an island friend gives `https://nano133.com/nanoterra?room=<code>`, a friend in a game gives that
+  game's listed address.
+- **Safari, and any browser that blocks third-party cookies:** the window needs one "Show my friends" tap (the Storage Access API) on each page load of the game
+  before the player shows online there (the window says `signin` when it shows that tap). Chrome with third-party cookies on needs none.
+
+### The game's own list
+
+The server part, `@nano133/nanoterra/friends`, has no database and reads no cookie: **the game gives a store, a directory of its players and its signed-in player**.
+
+```ts
+import { createFriendsHandler } from "@nano133/nanoterra/friends";
+import { createD1Friends } from "@nano133/nanoterra/friends/d1";
+
+const friends = createFriendsHandler({
+  store: createD1Friends(env.DB),                  // or createFirestoreFriends(getFirestore()), or createMemoryFriends() for a test
+  directory: {
+    byName: (name) => findPlayerIdByName(name),    // your players: an id for a name, or null
+    names: (ids) => namesOf(ids),                  // a Map of id -> the name to show
+  },
+  player: (req) => signedInPlayerId(req),         // YOUR player's sign-in (not the admin's): an id, or null
+  base: "/friends",                                // the default
+});
+const answer = await friends.handle(request);      // null when the request is not for /friends
+if (answer) return answer;
+```
+
+- `GET /friends` gives `{ showOnline, people }`: one row a person, `{ edge, name, state, online, where, invite }`, `state` one of `"friend"`, `"incoming"`,
+  `"outgoing"`, `"blocked"`. **No answer holds a player id:** a row names a player by the directory's name and an opaque `edge`.
+- `POST /friends` takes one `{ op, ... }`: `request { name }`, `accept`, `decline`, `remove`, `block`, `unblock { edge }`, `invite { edge, where }`, `pulse { where, lease }`
+  (`where` null: this tab leaves) and `visibility { showOnline }`. It answers the new view (a pulse answers `{ ok: true }`), or `{ error }` with words a player can read.
+- 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 (403). Each player has 30 calls a
+  minute (429); a body is at most 1 KB. A fault in the store is a plain 500 that shows nothing of it (`onError` hears it).
+
+**The rules** (every store keeps them; `friendsStoreConformance` proves it):
+
+- A pair of players has at most one edge: a request (from one of them), a friendship or a block. A request to a player who already asked you is an accept.
+- **A block wins** over a friendship or a request, and hides the pair from the player who is blocked, both ways. The player who blocked sees a "blocked" row, to
+  unblock it; unblock leaves no edge (not friends again). Neither can ask while a block stands.
+- `FRIEND_LIMIT` (100) live rows a player (friends, requests both ways, blocks): a full list refuses a new request, on either side.
+- A request nobody answers goes after `FRIEND_REQUEST_MS` (30 days): not shown, not counted.
+- An invite is only between friends, and the friend sees it for `FRIEND_INVITE_MS` (10 minutes). Its place is plain text, cut to 64 characters.
+- A friend is online only for `FRIEND_LIVE_MS` (2 minutes) after a pulse, and only while they show online. A pulse carries a lease for each tab, so an old tab that
+  leaves cannot clear a newer tab's place.
+- `forget(player)` (for "Delete my data") leaves no row of the player.
+
+**The stores.** Each writes ONLY its friend rows, presence rows and the show-online choice:
+
+- **D1:** add `@nano133/nanoterra/friends/d1.sql` to your migrations (the tables `friend_edges`, `friend_presence`, `friend_prefs`). D1 has no transaction that reads and
+  then writes, so each write is one statement with its own check: a change says which `rev` it read (a row that changed in between is refused, 409, "Try again"), and a
+  new edge counts both players' rows in the same INSERT.
+- **Firestore:** `createFirestoreFriends(db, { edges, presence, prefs })` (the default names `friend_edges`, `friend_presence`, `friend_prefs`). A pair is one document named
+  by a SHA-256 digest, so two requests at the same moment meet in their transactions; the indexes Firestore makes by itself are enough.
+- **Your own database:** write a `FriendsStore` and run the rules on it:
+
+```ts
+import { friendsStoreConformance } from "@nano133/nanoterra/friends/conformance";
+for (const c of friendsStoreConformance(async () => ({ store: newEmptyStore(), dump: () => allRowsAsText() }))) it(c.name, c.run);
+```
+
+**The panel in `"own"` mode** reads the view at once, every 20 s while open and every 60 s while closed (for the badge), pulses every 45 s while it has a `where`, and
+sends a leaving pulse when the page goes away. It draws Requests (Accept, Decline), Friends (online and the place, Invite to your `where`, Join an invite when you
+give `onJoin`, Remove, Block), Sent (Cancel) and Blocked (Unblock), an add-by-name field and the "show friends when I am online" choice. The game's own friends have
+no live connection: only Nanoterra's do.
+
 ## Moving from the three old packages
 
 | Before | Now |

package/ai/SPEC.md

@@ -1,8 +1,8 @@
 # Nanoterra for a game: implementation spec
 
 Package: `@nano133/nanoterra` (0.1.0 or later). Follow these steps in order. Each step ends with a check. Ask the owner when a step says
-"ask". The package has four parts, on four paths: the sign-in ticket (`/ticket`), the player's character (`/character`, Three.js), the
-looks ladder (`/looks`) and held input that does not stick (`/input`). Use only the parts the game needs. It has no network, wallet or Nano code. Read the package README first.
+"ask". The package has five parts: the sign-in ticket (`/ticket`), the player's character (`/character`, Three.js), the
+looks ladder (`/looks`), held input that does not stick (`/input`) and the friends list (`/friends`, with its panel). Use only the parts the game needs. It has no network, wallet or Nano code. Read the package README first.
 
 ## 0. What the owner decides (ask)
 
@@ -13,6 +13,7 @@ looks ladder (`/looks`) and held input that does not stick (`/input`). Use only
 3. The quality: `"high"` (toon body and ink outline, 2 draws) or `"low"` (no outline, 1 draw, for slow phones).
 4. How the game moves the character: speed in metres a second, gravity and jump. The package animates; it does not move the object.
 5. Does the game sell looks? If yes, the game is the seller (its own checkout); see step 7.
+6. The friends list (step 9): Nanoterra's (the default), the game's own, or none. It is the admin's `friends` setting; ask which one the game starts with.
 
 **Check:** the owner has named the server (yes or no), the source of the character and the quality.
 
@@ -100,9 +101,10 @@ export const LOOKS = checkLooks(rawLooksJson); // throws with the first mistake
 - One free look (`priceUsd: 0`) at least. Never change or remove the id of a look that someone owns. Prices in US dollars with at most 2 decimals; the server reads the price from the file.
 - A look only changes how the character looks. No random look, no loot box, no look that changes a score.
 - `slots` (optional, at most 8: a name and a word or a `#rrggbb` colour) is where the game keeps its own parts of a look. Read `look.slots` from `checkLooks`. Never change the slots of a look that someone owns: add a new look.
+- `wear` (optional) is the wear slot a look fills: none for an outfit (the character's colours and hat, `change`), or the game's own slot (`"shovel"`, `"charm"`) for an item, which has no `change`. A player wears one look in each slot. Keep one free outfit. Never change the wear slot of a look that someone owns. Read outfits with `isOutfit(look)`.
 - The game is the seller. Never send looks, prices or sales to another site.
 
-**Check:** `checkLooks` passes at start; a removed look that is owned is refused; a changed slot on an owned look is refused.
+**Check:** `checkLooks` passes at start; a removed look that is owned is refused; a changed slot or wear slot on an owned look is refused.
 
 ## 8. Leaving the page (any game that a player walks in with keys or a stick)
 
@@ -116,7 +118,28 @@ import { pauseWhenLeft, releaseWhenLost, swallowsKeyup } from "@nano133/nanoterr
 
 **Check:** hold a move key, hide the tab or switch windows, come back: the character stands still until the key is pressed again.
 
-## 9. Do not
+## 9. The friends list (the admin's `friends` setting)
+
+```ts
+import { mountFriends } from "@nano133/nanoterra/friends/panel";
+import "@nano133/nanoterra/friends/style.css";
+```
+
+- Read the setting on the server with `loadGameSettings(store, defaults)` (`friends` is `"nanoterra"`, `"own"` or `"off"`) and pass it as `mode`. Do not read it in a
+  second place.
+- `"nanoterra"`: `mountFriends(el, { mode, game })` with the game's id on Nanoterra. Mount it when the game starts, not when the key is pressed: the window holds the
+  player's live connection. Never hide its element with `display: none` or remove it; `destroy()` is for the end of the game. Call `setWhere(text)` when the player moves
+  (plain text, friends see it). Give `onJoin` only to save the game before it leaves; the kit asks the player first and accepts only https addresses.
+- `"own"`: add `createFriendsHandler({ store, directory, player })` from `@nano133/nanoterra/friends` to the server, with `createD1Friends(env.DB)` (add
+  `@nano133/nanoterra/friends/d1.sql` to the migrations) or `createFirestoreFriends(db)`. `player(req)` reads the game's own PLAYER sign-in, never the admin's.
+  `directory.byName` and `directory.names` read the game's own player names. Call `store.forget(player)` from the game's "Delete my data".
+- A store of the game's own (another database) passes `friendsStoreConformance` from `@nano133/nanoterra/friends/conformance` before it is used.
+
+**Check:** with `"nanoterra"`, the key shows and the window loads at once (the network tab shows `/embed/friends` before the key is pressed). With `"own"`, two players
+in two browsers: one adds the other by name, the other accepts, both show online with their place, an invite shows, a block hides the blocker from the other. With
+`"off"`, no key.
+
+## 10. Do not
 
 - Do not edit the geometry, the skeleton or the toon and ink materials.
 - Do not add the katana, the headband or other brands' art. A game's own worn model goes on a socket (`c.socket("head" | "hand" | "back")` or

package/dist/admin/adapters/d1.d.ts

@@ -15,6 +15,7 @@ export interface D1Like {
 export declare const D1_KEYS: {
     readonly character: "setting:character";
     readonly signin: "setting:signin";
+    readonly friends: "setting:friends";
 };
 /**
  * The admin store for D1. With `logins: true` it also lists the last admin sign-ins (the table `admin_logins`: at, country, browser) and can sign the owner out everywhere

package/dist/admin/adapters/d1.js

@@ -1,11 +1,11 @@
 // 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";
 //   const store = createD1Store(env.DB);
 import { ORDERS_SHOWN, moneyOf, parseRate, shapeOrders, shapePlayers } from "../summary.js";
-export const D1_KEYS = { character: "setting:character", signin: "setting:signin" };
+export const D1_KEYS = { character: "setting:character", signin: "setting:signin", friends: "setting:friends" };
 /**
  * The admin store for D1. With `logins: true` it also lists the last admin sign-ins (the table `admin_logins`: at, country, browser) and can sign the owner out everywhere
  * (`DELETE FROM sessions WHERE scope = 'admin'`, and `UPDATE signin_requests SET delivered = 1, expires_at = 0 WHERE scope = 'admin' AND delivered = 0` so that a request signed a moment ago
@@ -15,9 +15,9 @@ export const D1_KEYS = { character: "setting:character", signin: "setting:signin
 export function createD1Store(db, options = {}) {
     const store = {
         async readSettings() {
-            const rows = (await db.prepare("SELECT key, value FROM meta WHERE key IN (?, ?)").bind(D1_KEYS.character, D1_KEYS.signin).all()).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()).results;
             const row = (key) => 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, now) {
             const write = (key, value) => db.prepare("INSERT INTO meta (key, value, at) VALUES (?, ?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value, at = excluded.at").bind(key, value, now);
@@ -26,6 +26,8 @@ export function createD1Store(db, options = {}) {
                 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/dist/admin/adapters/firestore.d.ts

@@ -32,6 +32,7 @@ export declare const FIRESTORE_SCAN_LIMIT = 5000;
 export declare const FIRESTORE_KEYS: {
     readonly character: "setting:character";
     readonly signin: "setting:signin";
+    readonly friends: "setting:friends";
 };
 export declare function createFirestoreStore(db: FirestoreLike, collections?: {
     meta?: string;

package/dist/admin/adapters/firestore.js

@@ -1,15 +1,15 @@
 // 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 }
 //
 // The summary reads the newest 5000 orders (the counts and the totals are over those) and every owned look: for a small game. A big game should keep running totals.
 import { parseRate, summarize } from "../summary.js";
 export const FIRESTORE_SCAN_LIMIT = 5000;
-export const FIRESTORE_KEYS = { character: "setting:character", signin: "setting:signin" };
+export const FIRESTORE_KEYS = { character: "setting:character", signin: "setting:signin", friends: "setting:friends" };
 const text = (v, fallback = "") => (typeof v === "string" ? v : fallback);
 const num = (v, fallback = 0) => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
 const orNull = (v) => (typeof v === "string" ? v : null);
@@ -23,8 +23,8 @@ export function createFirestoreStore(db, collections = {}) {
     };
     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, now) {
             const batch = db.batch();
@@ -33,6 +33,8 @@ export function createFirestoreStore(db, collections = {}) {
                 (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/dist/admin/conformance.d.ts

@@ -71,7 +71,7 @@ export type StoreHarness = {
             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: {

package/dist/admin/conformance.js

@@ -40,7 +40,7 @@ async function read(res) {
 /** A refusal carries words and a reason and nothing else: no data of the game. */
 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) {
     const cases = [];
     const add = (name, run) => cases.push({ name, run });
@@ -264,7 +264,15 @@ export function adminStoreConformance(make) {
     const order = (id, over) => ({ id, player: A, lookId: "mint-cap", usd: "0.25", amountRaw: rawOf(0.25), status: "paid", createdAt: NOW - 1000, expiresAt: NOW + 1000, paidAt: NOW - 500, payer: A, hash: `H${id}`, ...over });
     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"].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 }) => {
         await store.saveSettings({ signin: "none" }, NOW);
@@ -280,12 +288,12 @@ export function adminStoreConformance(make) {
     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");
     });
     add("the summary counts the orders by status, reads an open order past its expiry as expired, and totals the money", async ({ store, seed }) => {

package/dist/admin/handler.d.ts

@@ -59,5 +59,5 @@ export declare const ADMIN_LIMITS: {
     readonly gameBodyMax: 512;
 };
 export declare function createAdminHandler(options: AdminHandlerOptions): AdminHandler;
-/** 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 declare function loadGameSettings(store: Pick<AdminStore, "readSettings">, defaults: GameSettings): Promise<GameState>;

package/dist/admin/handler.js

@@ -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
@@ -159,7 +159,7 @@ export function createAdminHandler(options) {
     }
     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, defaults) {
     try {
         return mergeSettings(await store.readSettings(), defaults);

package/dist/admin/index.d.ts

@@ -9,5 +9,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/dist/admin/index.js

@@ -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")
 export { ADMIN_SESSION_MS, CLOCK_SKEW_MS, OWNER_PATTERN, adminAccess } from "./guard.js";
@@ -11,4 +11,4 @@ export { createMemoryStore } from "./memory.js";
 export { ADMIN_LOGINS_SHOWN } from "./store.js";
 export { ORDERS_SHOWN, moneyOf, parseRate, shapeOrders, shapePlayers, statusOf, summarize } 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 { 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";

package/dist/admin/memory.js

@@ -14,13 +14,15 @@ export function createMemoryStore(seed = {}) {
         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) {
             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) {

package/dist/admin/panel/gameCard.d.ts

@@ -2,6 +2,6 @@ import { type GameState } from "../switches.js";
 import { type Api } from "./api.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 declare function gameCard(api: Api, initial: GameState, defaultsFile?: string, onChange?: (state: GameState) => void): HTMLElement;