@nano133/nanoterra 0.1.0 → 0.3.0

package/dist/model/index.d.ts

@@ -0,0 +1,2 @@
+export { checkModel, modelSummary, sniffTexture, type ModelCheck, type ModelFacts, type ModelProblem, type ModelRule, type TextureFact, type Vec3 } from "./check.js";
+export { BACK_ITEM, COSMETIC_LIMITS, HAND_ITEM, HEAD_ITEM, ISLAND_MODEL, PLAIN_EXTENSIONS, type MarkerRule, type ModelLimits, type ZoneBox, type ZoneDisc } from "./limits.js";

package/dist/model/index.js

@@ -0,0 +1,5 @@
+// "@nano133/nanoterra/model": the 3D model check. Pure: no Three.js, no network, no DOM. It reads a .glb from its bytes and says what is
+// wrong with it (with a fix for each), what it measured and how to make it lighter, against a preset of limits: an island model, or a
+// cosmetic for one of the character's three sockets (head, hand, back).
+export { checkModel, modelSummary, sniffTexture } from "./check.js";
+export { BACK_ITEM, COSMETIC_LIMITS, HAND_ITEM, HEAD_ITEM, ISLAND_MODEL, PLAIN_EXTENSIONS } from "./limits.js";

package/dist/model/limits.d.ts

@@ -0,0 +1,103 @@
+/** A named node the model must (or may) have. `empty`: a node with no mesh (a point, as `nano_door`); `mesh`: a node with a mesh that is never drawn (a collider). */
+export type MarkerRule = {
+    name: string;
+    required: boolean;
+    kind: "empty" | "mesh"; /** A `mesh` marker's own triangle limit (it is not counted in `maxTriangles`). */
+    maxTriangles?: number; /** What the marker is for, in plain words, for a fix line. */
+    purpose: string;
+};
+export type ZoneBox = {
+    width: number;
+    depth: number;
+    height: number;
+    below: number;
+};
+export type ZoneDisc = {
+    radius: number;
+    height: number;
+    below: number;
+};
+export type ModelLimits = {
+    /** What the model is, for a fix line ("island model"). */
+    what: string;
+    /** The whole .glb, in bytes. */
+    maxBytes: number;
+    /** The JSON chunk, in bytes (the model's description; the data is in the BIN chunk). */
+    maxJsonBytes: number;
+    /** Triangles drawn, every mesh instance counted, the `mesh` markers left out. */
+    maxTriangles: number;
+    /** Draw calls: each part (glTF primitive) of each drawn mesh instance. Left out: no limit. */
+    maxDraws?: number;
+    /** Images in the file. */
+    maxTextures: number;
+    /** The longest side of each image, in pixels. */
+    maxTextureSide: number;
+    /**
+     * The build zone, in metres, in the model's own axes (glTF: +Y up). A box: x from -width/2 to width/2, z from -depth/2
+     * to depth/2. A disc: every point at most `radius` from the y axis (x and z together). Both: y from -below to height.
+     * The model's origin is the middle of the plot, on the ground.
+     */
+    zone: ZoneBox | ZoneDisc;
+    markers: readonly MarkerRule[];
+    /**
+     * A marker whose origin is the attach point (a hand item's `grip_R`): when the file has it, the zone is measured from it, not from the
+     * file's origin. It should be one of `markers` too (so a misspelt name gets a fix line).
+     */
+    anchor?: string;
+    /** The glTF extensions the file may use (plain data only). Every other one is refused. */
+    extensions: readonly string[];
+    /** Animations, skins and morph targets: refused unless allowed. When allowed, the zone is checked in the rest pose only. */
+    allowAnimations: boolean;
+    allowSkins: boolean;
+    allowMorphTargets: boolean;
+    /** Caps on the description, so a hostile file costs little to read. */
+    maxNodes: number;
+    maxMeshes: number;
+    maxPrimitives: number;
+    maxAccessors: number;
+    maxBufferViews: number;
+    maxMaterials: number;
+    /** The node tree's depth. */
+    maxDepth: number;
+    /** Vertex reads for the exact zone check (every rotated instance reads its vertices); past it, the box of each instance is used (larger, never smaller). */
+    maxVertexWork: number;
+    /** The whole check ends by then (ms). */
+    maxMs: number;
+};
+/** The texture compression and material extensions three.js reads as plain data. */
+export declare const PLAIN_EXTENSIONS: readonly ["KHR_texture_transform", "KHR_texture_basisu", "EXT_texture_webp", "KHR_mesh_quantization", "KHR_materials_emissive_strength", "KHR_materials_unlit", "KHR_materials_ior", "KHR_materials_specular", "KHR_materials_clearcoat", "KHR_materials_sheen", "KHR_materials_transmission", "KHR_materials_volume", "KHR_materials_iridescence", "KHR_materials_anisotropy", "KHR_materials_dispersion", "KHR_xmp_json_ld"];
+/**
+ * A creator's island model (the creator islands gameplan, phase 2; Wes approved it on 2026-10-27): the entry of their
+ * game on their plot. 5 MB, 50,000 triangles, 8 textures of at most 1,024 px, inside a disc of 10 m radius (20 m across)
+ * and 18 m high on the plot's middle: the plot's free middle (PLOT_FREE_R in app/nanoterra/wheel/plots.ts; Wes chose the
+ * disc over a 24 x 24 m box on 2026-10-28, as the box reached the gates' standing places); an empty `nano_door` where Play stands, an optional empty `nano_spawn` (the arrival point) and an
+ * optional simple `nano_collide` mesh. No lights, no scripts, nothing outside the file. A still model for now.
+ */
+export declare const ISLAND_MODEL: ModelLimits;
+/**
+ * A worn thing on the character's head socket (@nano133/nanoterra/character, `socket("head")`; Wes approved the cosmetic limits on
+ * 2026-10-28). The origin is the socket's point, the middle of the hat frame of the Classic's head, in metres for a character
+ * 2.29 m tall (the socket scales it to every other head). The zone is 0.9 x 0.9 m and 0.8 m high, from 0.1 m below the origin.
+ * 3,000 triangles, 1 texture of at most 512 px, 2 draws, 300 KB. Rigid: no skin, no animation (it rides its bone).
+ */
+export declare const HEAD_ITEM: ModelLimits;
+/**
+ * A worn thing in the character's right hand (`socket("hand")`). Its attach point is its `grip_R` marker (an empty node where the right
+ * hand holds it), else the file's origin; a `grip_L` marker (where a left hand would hold it) is allowed. The zone is 0.96 x 0.68 m and
+ * 1.6 m long, from 1.17 m below the grip to 0.43 m above it: a tool held near its top, as a shovel by its T-handle (Wes chose this zone on
+ * 2026-10-28 over the first 0.4 x 0.4 m from 0.3 m below, which the example shovel did not fit). 3,000 triangles, 1 texture of at most
+ * 512 px, 2 draws, 300 KB.
+ */
+export declare const HAND_ITEM: ModelLimits;
+/**
+ * A worn thing on the character's back (`socket("back")`). The origin is the socket's point, on the back of the torso at the chest's
+ * height; the side that touches the body is at the origin and the bulk goes back (-Z). The zone is 1.0 m wide, 0.6 m deep (its middle at
+ * the origin) and 1.2 m high, from 0.6 m below. 4,000 triangles, 1 texture of at most 512 px, 2 draws, 400 KB.
+ */
+export declare const BACK_ITEM: ModelLimits;
+/** The cosmetic preset of each socket. */
+export declare const COSMETIC_LIMITS: {
+    readonly head: ModelLimits;
+    readonly hand: ModelLimits;
+    readonly back: ModelLimits;
+};

package/dist/model/limits.js

@@ -0,0 +1,132 @@
+// The limits a 3D model is checked against (@nano133/nanoterra/model; the README's "Model check"; on nano133.com
+// docs/agents/launch.md, "The island model"). The checker (check.ts) is general: it takes one of these objects, so each
+// kind of model (an island, a cosmetic on each socket) is a preset here with the same code. Pure data: no network, no DOM.
+/** The texture compression and material extensions three.js reads as plain data. */
+export const PLAIN_EXTENSIONS = [
+    "KHR_texture_transform",
+    "KHR_texture_basisu",
+    "EXT_texture_webp",
+    "KHR_mesh_quantization",
+    "KHR_materials_emissive_strength",
+    "KHR_materials_unlit",
+    "KHR_materials_ior",
+    "KHR_materials_specular",
+    "KHR_materials_clearcoat",
+    "KHR_materials_sheen",
+    "KHR_materials_transmission",
+    "KHR_materials_volume",
+    "KHR_materials_iridescence",
+    "KHR_materials_anisotropy",
+    "KHR_materials_dispersion",
+    "KHR_xmp_json_ld",
+];
+/**
+ * A creator's island model (the creator islands gameplan, phase 2; Wes approved it on 2026-10-27): the entry of their
+ * game on their plot. 5 MB, 50,000 triangles, 8 textures of at most 1,024 px, inside a disc of 10 m radius (20 m across)
+ * and 18 m high on the plot's middle: the plot's free middle (PLOT_FREE_R in app/nanoterra/wheel/plots.ts; Wes chose the
+ * disc over a 24 x 24 m box on 2026-10-28, as the box reached the gates' standing places); an empty `nano_door` where Play stands, an optional empty `nano_spawn` (the arrival point) and an
+ * optional simple `nano_collide` mesh. No lights, no scripts, nothing outside the file. A still model for now.
+ */
+export const ISLAND_MODEL = {
+    what: "island model",
+    maxBytes: 5 * 1024 * 1024,
+    maxJsonBytes: 1024 * 1024,
+    maxTriangles: 50_000,
+    maxTextures: 8,
+    maxTextureSide: 1024,
+    zone: { radius: 10, height: 18, below: 0 },
+    markers: [
+        { name: "nano_door", required: true, kind: "empty", purpose: "where Play stands" },
+        { name: "nano_spawn", required: false, kind: "empty", purpose: "where players arrive" },
+        { name: "nano_collide", required: false, kind: "mesh", maxTriangles: 5_000, purpose: "the simple shape players walk on" },
+    ],
+    extensions: PLAIN_EXTENSIONS,
+    allowAnimations: false,
+    allowSkins: false,
+    allowMorphTargets: false,
+    maxNodes: 4096,
+    maxMeshes: 1024,
+    maxPrimitives: 4096,
+    maxAccessors: 16_384,
+    maxBufferViews: 16_384,
+    maxMaterials: 256,
+    maxDepth: 64,
+    maxVertexWork: 4_000_000,
+    maxMs: 2_000,
+};
+/**
+ * The caps on the description of a cosmetic: a worn thing is small, so a file far past these is not one (and costs little to refuse).
+ */
+const COSMETIC_CAPS = {
+    maxJsonBytes: 256 * 1024,
+    extensions: PLAIN_EXTENSIONS,
+    allowAnimations: false,
+    allowSkins: false,
+    allowMorphTargets: false,
+    maxNodes: 256,
+    maxMeshes: 32,
+    maxPrimitives: 64,
+    maxAccessors: 1024,
+    maxBufferViews: 1024,
+    maxMaterials: 16,
+    maxDepth: 32,
+    maxVertexWork: 500_000,
+    maxMs: 1_000,
+};
+/**
+ * A worn thing on the character's head socket (@nano133/nanoterra/character, `socket("head")`; Wes approved the cosmetic limits on
+ * 2026-10-28). The origin is the socket's point, the middle of the hat frame of the Classic's head, in metres for a character
+ * 2.29 m tall (the socket scales it to every other head). The zone is 0.9 x 0.9 m and 0.8 m high, from 0.1 m below the origin.
+ * 3,000 triangles, 1 texture of at most 512 px, 2 draws, 300 KB. Rigid: no skin, no animation (it rides its bone).
+ */
+export const HEAD_ITEM = {
+    ...COSMETIC_CAPS,
+    what: "head item",
+    maxBytes: 300 * 1024,
+    maxTriangles: 3_000,
+    maxDraws: 2,
+    maxTextures: 1,
+    maxTextureSide: 512,
+    zone: { width: 0.9, depth: 0.9, height: 0.7, below: 0.1 },
+    markers: [],
+};
+/**
+ * A worn thing in the character's right hand (`socket("hand")`). Its attach point is its `grip_R` marker (an empty node where the right
+ * hand holds it), else the file's origin; a `grip_L` marker (where a left hand would hold it) is allowed. The zone is 0.96 x 0.68 m and
+ * 1.6 m long, from 1.17 m below the grip to 0.43 m above it: a tool held near its top, as a shovel by its T-handle (Wes chose this zone on
+ * 2026-10-28 over the first 0.4 x 0.4 m from 0.3 m below, which the example shovel did not fit). 3,000 triangles, 1 texture of at most
+ * 512 px, 2 draws, 300 KB.
+ */
+export const HAND_ITEM = {
+    ...COSMETIC_CAPS,
+    what: "hand item",
+    maxBytes: 300 * 1024,
+    maxTriangles: 3_000,
+    maxDraws: 2,
+    maxTextures: 1,
+    maxTextureSide: 512,
+    zone: { width: 0.96, depth: 0.68, height: 0.43, below: 1.17 },
+    markers: [
+        { name: "grip_R", required: false, kind: "empty", purpose: "where the right hand holds it" },
+        { name: "grip_L", required: false, kind: "empty", purpose: "where a left hand would hold it" },
+    ],
+    anchor: "grip_R",
+};
+/**
+ * A worn thing on the character's back (`socket("back")`). The origin is the socket's point, on the back of the torso at the chest's
+ * height; the side that touches the body is at the origin and the bulk goes back (-Z). The zone is 1.0 m wide, 0.6 m deep (its middle at
+ * the origin) and 1.2 m high, from 0.6 m below. 4,000 triangles, 1 texture of at most 512 px, 2 draws, 400 KB.
+ */
+export const BACK_ITEM = {
+    ...COSMETIC_CAPS,
+    what: "back item",
+    maxBytes: 400 * 1024,
+    maxTriangles: 4_000,
+    maxDraws: 2,
+    maxTextures: 1,
+    maxTextureSide: 512,
+    zone: { width: 1.0, depth: 0.6, height: 0.6, below: 0.6 },
+    markers: [],
+};
+/** The cosmetic preset of each socket. */
+export const COSMETIC_LIMITS = { head: HEAD_ITEM, hand: HAND_ITEM, back: BACK_ITEM };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano133/nanoterra",
-  "version": "0.1.0",
+  "version": "0.3.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.",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,14 @@
     "./character": { "types": "./dist/character/index.d.ts", "import": "./dist/character/index.js" },
     "./character/record": { "types": "./dist/character/pure.d.ts", "import": "./dist/character/pure.js" },
     "./ticket": { "types": "./dist/ticket/index.d.ts", "import": "./dist/ticket/index.js" },
-    "./looks": { "types": "./dist/looks/index.d.ts", "import": "./dist/looks/index.js" }
+    "./looks": { "types": "./dist/looks/index.d.ts", "import": "./dist/looks/index.js" },
+    "./model": { "types": "./dist/model/index.d.ts", "import": "./dist/model/index.js" },
+    "./admin": { "types": "./dist/admin/index.d.ts", "import": "./dist/admin/index.js" },
+    "./admin/conformance": { "types": "./dist/admin/conformance.d.ts", "import": "./dist/admin/conformance.js" },
+    "./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"
   },
   "sideEffects": false,
   "files": ["dist", "src", "README.md", "CHANGELOG.md", "LICENSE", "ai"],
@@ -25,6 +32,7 @@
   "devDependencies": {
     "@types/node": "^26.6.3",
     "@types/three": "^0.186.0",
+    "happy-dom": "^20.14.6",
     "three": "^0.186.0",
     "tsx": "^4.23.15",
     "typescript": "5.9"
@@ -37,5 +45,5 @@
   },
   "homepage": "https://nano133.com/build/nanoterra",
   "license": "MIT",
-  "keywords": ["nano", "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"]
 }

package/src/admin/adapters/d1.ts

@@ -0,0 +1,94 @@
+// 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
+// (`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, type OrderRow } from "../summary.js";
+import type { AdminStore, StoreSummary } from "../store.js";
+import type { GamePatch } from "../switches.js";
+
+/** The part of D1 that the adapter uses. Cloudflare's `D1Database` fits it. */
+export interface D1StatementLike {
+  bind(...values: unknown[]): D1StatementLike;
+  all<T = unknown>(): Promise<{ results: T[] }>;
+  first<T = unknown>(): Promise<T | null>;
+  run(): Promise<unknown>;
+}
+export interface D1Like {
+  prepare(query: string): D1StatementLike;
+  batch(statements: D1StatementLike[]): Promise<unknown[]>;
+}
+
+export const D1_KEYS = { character: "setting:character", signin: "setting:signin" } 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 };
+
+/**
+ * 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
+ * cannot make a new login afterwards, and a wallet app that is answered later is told that the request has ended): the game's `sessions` and `signin_requests` tables must have a `scope` column ('admin' for an admin login or request) and the game must write
+ * `admin_logins` when it makes an admin login. Without the option the store has neither call, so a game that has not made those tables is not broken by it.
+ */
+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 row = (key: string) => rows.find((r) => r.key === key)?.value;
+      return { character: row(D1_KEYS.character), signin: row(D1_KEYS.signin) };
+    },
+
+    async saveSettings(patch: GamePatch, now: number) {
+      const write = (key: string, value: string) =>
+        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);
+      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 (batch.length) await db.batch(batch);
+    },
+
+    async summary(now: number): Promise<StoreSummary> {
+      // The game starter's own queries: the counts and the totals are over ALL orders, the list is the newest ORDERS_SHOWN.
+      const orders = (
+        await db
+          .prepare("SELECT id, player, look_id, usd, amount, status, created_at, expires_at, paid_at, payer, hash FROM orders ORDER BY created_at DESC LIMIT ?")
+          .bind(ORDERS_SHOWN)
+          .all<Row>()
+      ).results;
+      const owned = (await db.prepare("SELECT player, look_id, granted_at FROM owned ORDER BY player, granted_at").all<{ player: string; look_id: string; granted_at: number }>()).results;
+      const sums = (await db.prepare("SELECT status, amount, usd FROM orders WHERE status IN ('paid', 'paid_late')").all<{ status: string; amount: string; usd: string }>()).results;
+      const grouped = (await db.prepare("SELECT status, expires_at < ? AS past, COUNT(*) AS n FROM orders GROUP BY status, past").bind(now).all<{ status: string; past: number; n: number }>()).results;
+      const rate = await db.prepare("SELECT value, at FROM meta WHERE key = 'rate'").first<{ value: string; at: number }>();
+
+      const counts = { open: 0, paid: 0, expired: 0, paid_late: 0 };
+      for (const c of grouped) {
+        const key = c.status === "open" && c.past ? "expired" : c.status;
+        if (Object.hasOwn(counts, key)) counts[key as keyof typeof counts] += c.n;
+      }
+      const money = (status: string) => moneyOf(sums.filter((s) => s.status === status).map((s) => ({ amountRaw: s.amount, usd: s.usd })));
+      const rows: OrderRow[] = orders.map((o) => ({ id: o.id, player: o.player, lookId: o.look_id, usd: o.usd, amountRaw: o.amount, status: o.status, createdAt: o.created_at, expiresAt: o.expires_at, paidAt: o.paid_at, payer: o.payer, hash: o.hash }));
+      return {
+        counts,
+        totals: { paid: money("paid"), paidLate: money("paid_late") },
+        orders: shapeOrders(rows, now),
+        players: shapePlayers(owned.map((o) => ({ player: o.player, lookId: o.look_id, at: o.granted_at }))),
+        rate: parseRate(rate?.value, rate?.at),
+      };
+    },
+  };
+  if (options.logins) {
+    store.recentLogins = async (limit) => {
+      const n = Math.min(Math.max(Math.floor(Number(limit)) || 0, 0), 50);
+      const rows = (await db.prepare("SELECT at, country, browser FROM admin_logins ORDER BY at DESC, id DESC LIMIT ?").bind(n).all<{ at: number; country: string | null; browser: string }>()).results;
+      return rows.map((r) => ({ at: r.at, country: r.country, browser: r.browser }));
+    };
+    // One batch: the admin sessions are deleted, AND every admin sign-in request that was started but not delivered is marked delivered, so a request that the owner signed a moment
+    // ago cannot make a new admin login after "Sign out everywhere" (its check would answer "used").
+    store.signOutEverywhere = async () => {
+      const done = (await db.batch([db.prepare("DELETE FROM sessions WHERE scope = 'admin'"), db.prepare("UPDATE signin_requests SET delivered = 1, expires_at = 0 WHERE scope = 'admin' AND delivered = 0")])) as ({ meta?: { changes?: number } } | undefined)[];
+      return done[0]?.meta?.changes ?? 0;
+    };
+  }
+  return store;
+}

package/src/admin/adapters/firestore.ts

@@ -0,0 +1,78 @@
+// 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.
+//
+// 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 })
+//   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, type OrderRow } from "../summary.js";
+import type { AdminStore, StoreSummary } from "../store.js";
+import type { GamePatch } from "../switches.js";
+
+export interface FirestoreDocLike {
+  get(): Promise<{ exists: boolean; data(): Record<string, unknown> | undefined }>;
+}
+export interface FirestoreQueryLike {
+  orderBy(field: string, direction?: "asc" | "desc"): FirestoreQueryLike;
+  limit(n: number): FirestoreQueryLike;
+  get(): Promise<{ docs: { id: string; data(): Record<string, unknown> }[] }>;
+}
+export interface FirestoreCollectionLike extends FirestoreQueryLike {
+  doc(id: string): FirestoreDocLike;
+}
+export interface FirestoreBatchLike {
+  set(doc: FirestoreDocLike, data: Record<string, unknown>, options?: { merge?: boolean }): unknown;
+  commit(): Promise<unknown>;
+}
+export interface FirestoreLike {
+  collection(name: string): FirestoreCollectionLike;
+  batch(): FirestoreBatchLike;
+}
+
+export const FIRESTORE_SCAN_LIMIT = 5000;
+export const FIRESTORE_KEYS = { character: "setting:character", signin: "setting:signin" } 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);
+const orNull = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+export function createFirestoreStore(db: FirestoreLike, collections: { meta?: string; orders?: string; owned?: string } = {}): AdminStore {
+  const meta = collections.meta ?? "meta";
+  const orders = collections.orders ?? "orders";
+  const owned = collections.owned ?? "owned";
+  const valueOf = async (key: string) => {
+    const snap = await db.collection(meta).doc(key).get();
+    return snap.exists ? snap.data() : undefined;
+  };
+  return {
+    async readSettings() {
+      const [character, signin] = await Promise.all([valueOf(FIRESTORE_KEYS.character), valueOf(FIRESTORE_KEYS.signin)]);
+      return { character: character?.value, signin: signin?.value };
+    },
+
+    async saveSettings(patch: GamePatch, now: number) {
+      const batch = db.batch();
+      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 (n) await batch.commit();
+    },
+
+    async summary(now: number): Promise<StoreSummary> {
+      const [orderDocs, ownedDocs, rate] = await Promise.all([
+        db.collection(orders).orderBy("createdAt", "desc").limit(FIRESTORE_SCAN_LIMIT).get(),
+        db.collection(owned).get(),
+        valueOf("rate"),
+      ]);
+      const rows: OrderRow[] = orderDocs.docs.map((d) => {
+        const o = d.data();
+        return { id: d.id, player: text(o.player), lookId: text(o.lookId), usd: text(o.usd, "0"), amountRaw: text(o.amount, "0"), status: text(o.status, "open"), createdAt: num(o.createdAt), expiresAt: num(o.expiresAt), paidAt: typeof o.paidAt === "number" ? o.paidAt : null, payer: orNull(o.payer), hash: orNull(o.hash) };
+      });
+      const list = ownedDocs.docs.map((d) => ({ player: text(d.data().player), lookId: text(d.data().lookId), at: num(d.data().grantedAt) }));
+      return summarize(rows, list, parseRate(rate?.value, rate?.at), now);
+    },
+  };
+}

package/src/admin/amount.ts

@@ -0,0 +1,14 @@
+// Nano amounts for the summary. 1 XNO is 10^30 raw, more than a JavaScript number holds exactly, so amounts are decimal strings and the sums are BigInt.
+
+export const RAW_PER_XNO = 10n ** 30n;
+
+/** A raw amount as XNO with every significant digit: "0.2512". Throws on text that is not a whole number. */
+export function xnoText(raw: string): string {
+  const n = BigInt(raw);
+  const whole = n / RAW_PER_XNO;
+  const frac = (n % RAW_PER_XNO).toString().padStart(30, "0").replace(/0+$/, "");
+  return frac ? `${whole}.${frac}` : `${whole}`;
+}
+
+/** A raw amount that can be added: digits only, at most 39 of them. Anything else is not counted (a bad row must not break the summary). */
+export const isRawText = (s: unknown): s is string => typeof s === "string" && /^[0-9]{1,39}$/.test(s);