@xgamesfun/xcore 0.2.1 → 0.4.0

package/lib/dev/files.mjs

@@ -12,11 +12,84 @@ import { createReadStream, existsSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import path from 'node:path';
-import { FILES, filePathProblem, fileType, servedType } from '../server/contract.mjs';
+import { FILES, filePathProblem, servedType } from '../server/contract.mjs';
 import { stateFolder } from '../state-folder.mjs';
 
 const no = (code, why) => ({ ok: false, code, why });
 
+// ---- public files: the types a file may be public as, each known by its first bytes, as xgames.fun checks them ----
+// A public file is media or data a page loads: an image, audio, video, a font, JSON or plain text, whose first bytes
+// are plainly that type. Never a document a browser runs (HTML, SVG, XML, JavaScript, CSS, PDF) nor a download
+// (programs, archives, application/octet-stream): those stay private, and the game's own server serves them.
+const at = (b, offset, sig) => b.length >= offset + sig.length && sig.every((x, i) => b[offset + i] === x);
+const word = (b, offset, text) =>
+  at(
+    b,
+    offset,
+    [...text].map(c => c.charCodeAt(0)),
+  );
+/** The first byte that is not whitespace (after a UTF-8 byte order mark), or -1. */
+function firstVisible(b) {
+  let i = at(b, 0, [0xef, 0xbb, 0xbf]) ? 3 : 0;
+  while (i < b.length && (b[i] === 0x20 || b[i] === 0x09 || b[i] === 0x0a || b[i] === 0x0d)) i++;
+  return i < b.length ? b[i] : -1;
+}
+const riff = (b, kind) => word(b, 0, 'RIFF') && word(b, 8, kind);
+const ftyp = (b, brands = null) => word(b, 4, 'ftyp') && (!brands || brands.some(x => word(b, 8, x)));
+const mpegAudio = b => word(b, 0, 'ID3') || (b[0] === 0xff && (b[1] & 0xe0) === 0xe0);
+const ogg = b => word(b, 0, 'OggS'),
+  webm = b => at(b, 0, [0x1a, 0x45, 0xdf, 0xa3]),
+  wave = b => riff(b, 'WAVE');
+export const PUBLIC_TYPES = Object.freeze({
+  'image/png': b => at(b, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+  'image/jpeg': b => at(b, 0, [0xff, 0xd8, 0xff]),
+  'image/gif': b => word(b, 0, 'GIF87a') || word(b, 0, 'GIF89a'),
+  'image/webp': b => riff(b, 'WEBP'),
+  'image/avif': b => ftyp(b, ['avif', 'avis']),
+  'audio/mpeg': mpegAudio,
+  'audio/ogg': ogg,
+  'video/ogg': ogg,
+  'audio/wav': wave,
+  'audio/wave': wave,
+  'audio/x-wav': wave,
+  'audio/webm': webm,
+  'video/webm': webm,
+  'audio/mp4': b => ftyp(b),
+  'audio/x-m4a': b => ftyp(b),
+  'video/mp4': b => ftyp(b),
+  'audio/aac': b => b[0] === 0xff && (b[1] & 0xf6) === 0xf0,
+  'audio/flac': b => word(b, 0, 'fLaC'),
+  'font/woff': b => word(b, 0, 'wOFF'),
+  'font/woff2': b => word(b, 0, 'wOF2'),
+  'font/ttf': b => at(b, 0, [0, 1, 0, 0]) || word(b, 0, 'true'),
+  'font/otf': b => word(b, 0, 'OTTO'),
+  'font/collection': b => word(b, 0, 'ttcf'),
+  'application/json': b => {
+    const c = firstVisible(b);
+    return c >= 0 && '{["-0123456789tfn'.includes(String.fromCharCode(c));
+  },
+  'text/plain': b => !b.includes(0) && firstVisible(b) !== 0x3c,
+});
+/** How many leading bytes the public check reads. */
+const SNIFF_BYTES = 512;
+const PUBLIC_WORDS =
+  'an image (PNG, JPEG, WebP, GIF, AVIF), audio (MP3, Ogg, WAV, WebM, MP4, AAC, FLAC), video (MP4, WebM, Ogg), a font (WOFF, WOFF2, TTF, OTF), JSON or plain text';
+/** A type's essence: "Image/PNG; x=y" → "image/png". */
+const essenceOf = type =>
+  String(type ?? '')
+    .split(';')[0]
+    .trim()
+    .toLowerCase();
+const MEDIA_TYPE =
+  /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*(\s*;\s*[a-z0-9_-]+=("[^"\\]*"|[a-z0-9_.+-]+))*$/i;
+/** The type a put names (lower case), application/octet-stream for none, or null when it is not a media type. */
+const typeOf = type =>
+  type == null || type === ''
+    ? 'application/octet-stream'
+    : typeof type === 'string' && type.length <= 128 && MEDIA_TYPE.test(type)
+      ? type.trim().toLowerCase()
+      : null;
+
 /** One game's files. `origin`: where the public ones are served (a function: the files server's port comes later). */
 export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes, fileBytes = FILES.fileBytes }) {
   const root = path.join(dir, '.gamesfun', 'dev', 'files');
@@ -56,7 +129,10 @@ export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes
 
   return {
     root,
-    /** body: a string, bytes (ArrayBuffer, a typed array, a Buffer). → {ok, path, bytes, url?} */
+    /**
+     * body: a string, bytes (ArrayBuffer, a typed array, a Buffer). `type`: a media type (none: application/octet-stream);
+     * `public`: served on the files origin, for the public types only (PUBLIC_TYPES). → {ok, path, bytes, url?}
+     */
     put(p, body, { type, public: isPublic = false } = {}) {
       return queued(async () => {
         const bad = filePathProblem(p);
@@ -70,6 +146,20 @@ export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes
                 ? Buffer.from(body.buffer, body.byteOffset, body.byteLength)
                 : null;
         if (!bytes) return no('body', 'A file is a string, an ArrayBuffer or a stream of bytes.');
+        const t = typeOf(type);
+        if (t === null) return no('type', 'A file’s type is a media type, like image/png or application/json.');
+        // a public file is media or data the game's page loads, plainly so by its first bytes
+        const shown = isPublic === true;
+        if (shown && !PUBLIC_TYPES[essenceOf(t)])
+          return no(
+            'type',
+            `A public file is ${PUBLIC_WORDS}; this one is ${essenceOf(t)}. Keep it private (public: false) and serve it from the game’s server.`,
+          );
+        if (shown && !PUBLIC_TYPES[essenceOf(t)](bytes.subarray(0, SNIFF_BYTES)))
+          return no(
+            'type',
+            `This file’s first bytes are not ${essenceOf(t)}, so it can’t be public as that. A public file is ${PUBLIC_WORDS}.`,
+          );
         if (bytes.length > fileBytes)
           return no(
             'too-big',
@@ -88,8 +178,10 @@ export function createFileStore({ dir, origin = () => null, cap = FILES.capBytes
         await rename(`${file}.gf-tmp`, file);
         m[p] = {
           bytes: bytes.length,
-          type: typeof type === 'string' && type ? type.slice(0, 200) : fileType(p),
-          public: !!isPublic,
+          type: t,
+          public: shown,
+          // the type its first bytes showed: only a file so marked is served as itself
+          ...(shown ? { checked: essenceOf(t) } : {}),
           updatedAt: Date.now(),
           etag: createHash('sha256').update(bytes).digest('hex').slice(0, 32),
         };
@@ -206,7 +298,12 @@ export function serveFiles(store, { port = 0, host = '127.0.0.1' } = {}) {
     if (filePathProblem(p)) return send(404, { 'content-type': 'text/plain' }, 'No such file.');
     const f = await store.served(p);
     if (!f) return send(404, { 'content-type': 'text/plain' }, 'No such file.');
-    const { type, inline } = servedType(f.meta.type);
+    // as itself only when its first bytes were checked as its type; anything else (a file kept before the check) is a
+    // download
+    const { type, inline } =
+      f.meta.checked && f.meta.checked === essenceOf(f.meta.type)
+        ? servedType(f.meta.type)
+        : { type: 'application/octet-stream', inline: false };
     const etag = `"${f.meta.etag}"`;
     const head = {
       'content-type': type,

package/lib/dev/gf-local.js

@@ -67,6 +67,10 @@ class Scores extends RpcTarget {
   drop(board) {
     return call(this.#env, 'scores.drop', [board]);
   }
+  /** The game's boards (who made each: 'server' or 'page') and rules, as xgames.fun's GF.scores.list answers. */
+  list() {
+    return call(this.#env, 'scores.list', []);
+  }
 }
 class Loot extends RpcTarget {
   #env;

package/lib/dev/index.mjs

@@ -3,7 +3,11 @@
 //   /game/*            the published files (gamesfun.json page.out), with the play host's headers (../check.mjs servePage)
 //   /game/api/*        the game's own server/ under workerd (./server.mjs), WebSockets too, sent on as /api/*; for a
 //                      game with a database and no server/, xcore's stock server, with a local D1 (./d1.mjs)
-//   /platform/v1/*     sign-in, saves and leaderboards (./platform.mjs), the store env.GF reads as well
+//   /platform/v1/*     sign-in, saves and leaderboards (./platform.mjs), the store env.GF reads as well, held to the
+//                      limits of the plan it imitates (./plans.mjs: Free unless `plan` says another)
+//   /platform/v1/live  the game's announcement, config and maintenance, from .gamesfun/live.json (./live.mjs); while
+//                      maintenance is on there, the holding page for its HTML and 503 'maintenance' for its api/
+//                      and platform calls, as xgames.fun's play edge does
 //   <files origin>/*   the game's public project files (env.GF.files, xcore files), on a port of its own: another
 //                      origin to the browser (cross-origin, though same-site: both are 127.0.0.1), as
 //                      <slug>.xgamesusercontent.com is live, where it is another site too (./files.mjs)
@@ -20,7 +24,9 @@ import { ownOrigins } from '../publish/client.mjs';
 import { readServerConfig, API_PREFIX } from '../server/contract.mjs';
 import { PAGE_RPC, rpcWords, solanaRpc } from '../solana-rpc.mjs';
 import { handlePlatform, createPlatformStore } from './platform.mjs';
+import { createLiveRoutes, readLive, LIVE_FILE } from './live.mjs';
 import { createLimitWatch } from './limits.mjs';
+import { devPlan, planLine } from './plans.mjs';
 import { serveFiles } from './files.mjs';
 
 const readJson = file => {
@@ -102,20 +108,27 @@ async function body(req, cap = 256 * 1024) {
   return Buffer.concat(chunks);
 }
 
-/**
- * Start the dev host for `dir`. Options: port (default 8787; 0 any), filesPort (default the next one; 0 any), noBuild,
- * log, env, fetchImpl (the RPC forward's).
- * → {url, origin, files (the public files' origin), rpc, server (the game server's status, or null), store, reload(),
- * close()}
- */
+/** What xcore dev does not imitate, said once when it starts. */
+export const NOT_IMITATED =
+  "platform: not imitated, only said in this log when a page passes them: one player's requests to the game's " +
+  "server a minute and its CPU a request, and one address's reads of /platform/v1; not imitated at all: the " +
+  "network's delays and the owner's moderation (bans, blocked words); a board's player ids are this machine's own";
+
 /** A Host header naming this machine: localhost, 127.0.0.1, [::1] or a name under .localhost, with any port. */
 export const isLocalHost = host =>
   /^(localhost|127\.0\.0\.1|\[::1\]|[a-z0-9-]+\.localhost)(:\d{1,5})?$/i.test(String(host ?? ''));
 
+/**
+ * Start the dev host for `dir`. Options: port (default 8787; 0 any), filesPort (default the next one; 0 any), noBuild,
+ * plan (the plan imitated: 'free', the default, 'creator' or 'scale'), log, env, fetchImpl (the RPC forward's).
+ * → {url, origin, files (the public files' origin), rpc, plan, server (the game server's status, or null), store,
+ * reload(), close()}
+ */
 export async function startDev(
   dir,
   {
     port = 8787,
+    plan: planName = 'free',
     filesPort = port ? port + 1 : 0,
     noBuild = false,
     log = m => console.log(m),
@@ -124,6 +137,7 @@ export async function startDev(
   } = {},
 ) {
   const game = path.resolve(dir);
+  const plan = devPlan(planName);
   const roots = pageRoots(game);
   if (roots.build && !noBuild) {
     log(`build: ${roots.build}`);
@@ -138,7 +152,9 @@ export async function startDev(
       `no index.html in ${path.relative(game, roots.out) || '.'}: ${roots.build ? 'build the game first' : "export the game for the Web there first (or adopt it again with --out <the export's folder>)"}`,
     );
 
-  const store = createPlatformStore({ dir: game, log: m => log(`platform: ${m}`) });
+  const store = createPlatformStore({ dir: game, plan, log: m => log(`platform: ${m}`) });
+  log(planLine(plan));
+  log(NOT_IMITATED);
   // the game's public files on an origin of their own, as <slug>.xgamesusercontent.com is to the published game:
   // another port is another origin (no sign-in, no calls to the game's api/), though the same site here (both are
   // 127.0.0.1); live, xgamesusercontent.com is another site as well
@@ -215,8 +231,16 @@ export async function startDev(
     res.end(text);
   }
 
-  const limits = createLimitWatch({ log });
+  const limits = createLimitWatch({ log, plan });
   const apiAt = `/game${API_PREFIX}`; // the page's api/ beside it: /game/api/
+  const live = createLiveRoutes({ dir: game, apiAt, say: problems => log(`live: ${problems.join('; ')}`) });
+  const said = await readLive(game);
+  if (said.exists) {
+    const l = said.live;
+    log(
+      `live: ${LIVE_FILE}${l.maintenance ? ' (maintenance on: the game shows its holding page)' : ''}${l.announcement ? ', an announcement' : ''}${l.version ? `, config v${l.version}` : ''}`,
+    );
+  }
   const route = async (req, res, url) => {
     // only this machine's own names: a page on another site that points a name of its own at 127.0.0.1 (DNS rebinding)
     // must not reach the platform, its sign-in tokens or the game's server here
@@ -226,6 +250,17 @@ export async function startDev(
       return true;
     }
     if (url.pathname === PAGE_RPC) return (await forwardRpc(req, res), true);
+    if (await live.handle(req, res, url)) return true;
+    // the play edge holds one address's reads of /platform/v1 to a number a minute; a board read with no
+    // Authorization header may come from its cache, which is not counted
+    const p = url.pathname;
+    if (
+      (req.method === 'GET' || req.method === 'HEAD') &&
+      p.startsWith('/platform/v1/') &&
+      !p.startsWith('/platform/v1/dev/') &&
+      !(/^\/platform\/v1\/scores\/[^/]+$/.test(p) && !req.headers.authorization)
+    )
+      limits.platformRead(`${req.method} ${p}`);
     if (await handlePlatform(req, res, url, store)) return true;
     if (url.pathname.startsWith(apiAt) || url.pathname === apiAt.slice(0, -1)) {
       const rest = url.pathname.slice('/game'.length) + url.search;
@@ -259,9 +294,12 @@ export async function startDev(
     await files.close();
     throw e;
   }
-  site.server.on('upgrade', (req, socket, head) => {
+  site.server.on('upgrade', async (req, socket, head) => {
     if (!isLocalHost(req.headers.host)) return socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
     const u = new URL(req.url, 'http://x');
+    // paused (.gamesfun/live.json maintenance): refused, as xgames.fun refuses the game's api/ then
+    if (await live.refuseUpgrade(u.pathname))
+      return socket.end('HTTP/1.1 503 Service Unavailable\r\nRetry-After: 60\r\nConnection: close\r\n\r\n');
     if (server && u.pathname.startsWith(apiAt)) {
       limits.upgrade(u.pathname.slice('/game'.length));
       server.upgrade(req, socket, head, u.pathname.slice('/game'.length) + u.search);
@@ -338,6 +376,7 @@ export async function startDev(
     origin: site.origin,
     files: files.origin,
     rpc: rpcWords(rpc),
+    plan: plan.key,
     server: server ? server.status() : null,
     store,
     reload: () => server?.reload(),

package/lib/dev/limits.mjs

@@ -1,26 +1,39 @@
-// What `xcore dev` says about xgames.fun's plan limits (README §5, `xcore plan`). The local server runs with no CPU or
-// request limits, so a page that polls its server ten times a second works here and is refused once published. This
-// counts the page's requests to its server and times each one, and says so in the dev log, once a minute at most for
-// the rate and once per route for the time. It never refuses anything itself.
+// What `xcore dev` says about xgames.fun's limits that depend on the network, not on the game's store: one player's
+// requests to the game's server a minute and the CPU each may take (by plan), and one address's reads of the page's
+// /platform/v1 at the play edge. The local server runs with no CPU or request limits, and here every tab is the same
+// address, so these are said in the dev log, never refused: once a minute at most for a rate, once per route for the
+// time. The platform's own limits (saves, scores, reads and writes a minute) are refused as published: ./platform.mjs.
 //
-// The numbers are xgames.fun's plans; xgames.fun is the source and can change them.
-export const PLAN_LIMITS = Object.freeze({
-  free: Object.freeze({ name: 'Free', perPlayer: 120, cpuMs: 50 }),
-  creator: Object.freeze({ name: 'Creator', perPlayer: 600, cpuMs: 200 }),
-});
+// The numbers are ./plans.mjs's, one table with the rest.
+import { PLANS, PLAN_NAMES, RULES, devPlan } from './plans.mjs';
+
+/** The plans' request numbers, as this watch reads them (kept for callers of an earlier version). */
+export const PLAN_LIMITS = Object.freeze(
+  Object.fromEntries(
+    PLAN_NAMES.map(k => [
+      k,
+      Object.freeze({ name: PLANS[k].name, perPlayer: PLANS[k].rate.player, cpuMs: PLANS[k].cpuMs }),
+    ]),
+  ),
+);
 const MINUTE = 60_000;
 
 /**
- * A watch over one dev session's server requests. `log(line)` takes what it has to say.
- * → {request(method, pathname) → done(), upgrade(pathname)}: request() before the server is called, done() when it
- *   has answered (its headers).
+ * A watch over one dev session's server requests. `log(line)` takes what it has to say; `plan`: the plan imitated.
+ * → {request(method, pathname) → done(), upgrade(pathname), platformRead(what)}: request() before the server is
+ *   called, done() when it has answered (its headers).
  */
-export function createLimitWatch({ log, now = () => Date.now() }) {
-  const { free, creator } = PLAN_LIMITS;
+export function createLimitWatch({ log, now = () => Date.now(), plan = 'free' }) {
+  const key = typeof plan === 'object' && plan?.key ? plan.key : devPlan(plan).key;
+  const here = PLAN_LIMITS[key];
+  const up = PLAN_LIMITS[PLAN_NAMES[PLAN_NAMES.indexOf(key) + 1]] ?? null;
   let start = now();
   let count = 0;
-  let said = 0; // the highest plan already named this minute: 0 none, 1 Free, 2 Creator
+  let said = 0; // what is already said this minute: 0 nothing, 1 past this plan's, 2 past the next plan's too
   const slow = new Set();
+  let readStart = now(),
+    reads = 0,
+    readSaid = false;
 
   function count1(what) {
     const t = now();
@@ -30,21 +43,21 @@ export function createLimitWatch({ log, now = () => Date.now() }) {
       said = 0;
     }
     count++;
-    if (count > creator.perPlayer && said < 2) {
+    if (up && count > up.perPlayer && said < 2) {
       said = 2;
       log(
         `limits: ${count} requests to the game's server within a minute (the last: ${what}). Published, one player's ` +
-          `requests past ${creator.perPlayer} a minute are refused even on Creator (${free.perPlayer} on Free): its ` +
+          `requests past ${up.perPlayer} a minute are refused even on ${up.name} (${here.perPlayer} on ${here.name}): its ` +
           `server answers 429 with retry-after 60. Send frequent updates (positions, state) over a WebSocket ` +
           `(docs/SERVER.md, "A room over a WebSocket"); a socket is one request for its whole life.`,
       );
-    } else if (count > free.perPlayer && said < 1) {
+    } else if (count > here.perPlayer && said < 1) {
       said = 1;
       log(
         `limits: ${count} requests to the game's server within a minute (the last: ${what}). Published on ` +
-          `${free.name}, one player's requests past ${free.perPlayer} a minute are refused (429, retry-after 60); ` +
-          `${creator.name} allows ${creator.perPlayer}. Poll less often, or send frequent updates over a WebSocket ` +
-          `(docs/SERVER.md). Two tabs here count as one player.`,
+          `${here.name}, one player's requests past ${here.perPlayer} a minute are refused (429, retry-after 60)` +
+          `${up ? `; ${up.name} allows ${up.perPlayer}` : ''}. Poll less often, or send frequent updates over a ` +
+          `WebSocket (docs/SERVER.md). Two tabs here count as one player.`,
       );
     }
   }
@@ -56,11 +69,11 @@ export function createLimitWatch({ log, now = () => Date.now() }) {
       const t0 = now();
       return () => {
         const ms = now() - t0;
-        if (ms <= free.cpuMs || slow.has(what)) return;
+        if (ms <= here.cpuMs || slow.has(what)) return;
         slow.add(what);
         log(
-          `limits: ${what} took ${ms} ms here. Published, a request gets ${free.cpuMs} ms of CPU on ${free.name} ` +
-            `(${creator.cpuMs} on ${creator.name}). Waiting on storage or fetch does not count, but if this is ` +
+          `limits: ${what} took ${ms} ms here. Published, a request gets ${here.cpuMs} ms of CPU on ${here.name}` +
+            `${up ? ` (${up.cpuMs} on ${up.name})` : ''}. Waiting on storage or fetch does not count, but if this is ` +
             `computing, it can pass a few times live and then answer 503 ("went over its limit"). Do less a ` +
             `request, or split the work.`,
         );
@@ -69,5 +82,23 @@ export function createLimitWatch({ log, now = () => Date.now() }) {
     upgrade(pathname) {
       count1(`WebSocket ${pathname}`);
     },
+    /** A read of /platform/v1 that the play edge would count against the address it came from. */
+    platformRead(what) {
+      const t = now(),
+        max = RULES.edge.platformReadsPerCallerMinute;
+      if (t - readStart >= MINUTE) {
+        readStart = t;
+        reads = 0;
+        readSaid = false;
+      }
+      if (++reads <= max || readSaid) return;
+      readSaid = true;
+      log(
+        `limits: ${reads} reads of /platform/v1 within a minute (the last: ${what}). Published, the play edge ` +
+          `refuses one address's reads past ${max} a minute (429 'rate'), on every plan; a board read with no ` +
+          `token may come from its 5 s cache and is not counted. Here every tab shares one address, so this is only ` +
+          `said: read less often (a board after a score, not on a timer).`,
+      );
+    },
   };
 }

package/lib/dev/live.mjs

@@ -0,0 +1,162 @@
+// The game's live operations on this machine, for `xcore dev`. Hosted, the game's owner sets an announcement, a remote
+// config and maintenance mode on xgames.fun/console (the Live tab), and the play edge answers GET /platform/v1/live
+// itself (gamesfun.js's gf.live). Here they come from a file the creator writes, read again on every request:
+//
+//   <game>/.gamesfun/live.json   (a hidden folder: never published)
+//   {
+//     "announcement": {"text": "Double XP all weekend!", "level": "info", "startsAt": "2026-11-09T18:00:00Z", "endsAt": null},
+//     "config": {"difficulty": "hard", "event": true},
+//     "maintenance": {"message": "Back at 7pm"}          // or true, or null / left out: not paused
+//   }
+//
+// The rules are the hosted ones (xgames.fun's play edge, parseLive): the announcement only between its start and end,
+// plain text cut to 280 characters, info or warning; the config a JSON object of at most 8,192 bytes (a bigger one, or
+// one that is not an object, is left out here and said in the log: xgames.fun refuses it). While maintenance is on, the
+// dev host serves the holding page for the game's HTML pages and answers 503 {ok: false, code: 'maintenance'} to its
+// /game/api/* and /platform/v1/* (but /platform/v1/live and the local sign-in), as xgames.fun does.
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+// Shown to people as written (the same on Windows); path.join(dir, LIVE_FILE) still reads it there.
+export const LIVE_FILE = '.gamesfun/live.json';
+export const LIVE_TEXT_CHARS = 280;
+export const LIVE_CONFIG_BYTES = 8192;
+export const MAINTENANCE_DEFAULT = 'This game is paused for maintenance. It will be back soon.';
+export const LIVE_EMPTY = Object.freeze({ announcement: null, config: {}, version: 0, maintenance: null });
+
+// eslint-disable-next-line no-control-regex -- control characters never reach a player's screen (tabs and new lines may)
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
+const text = (v, max) => (typeof v === 'string' ? v.replace(CONTROL, '').trim().slice(0, max) : '');
+const time = v => {
+  const t = typeof v === 'number' ? v : typeof v === 'string' && v ? Date.parse(v) : NaN;
+  return Number.isFinite(t) && t > 0 ? t : null;
+};
+
+/**
+ * The file's value → {live: {announcement, config, version, maintenance} as players would get it at `now`, problems:
+ * [words]}. Times may be ms or ISO text here (the console sends ms).
+ */
+export function parseLiveFile(value, now = Date.now()) {
+  const problems = [];
+  if (value === null || value === undefined) return { live: LIVE_EMPTY, problems };
+  if (typeof value !== 'object' || Array.isArray(value))
+    return { live: LIVE_EMPTY, problems: [`${LIVE_FILE} is a JSON object: {announcement, config, maintenance}.`] };
+  let announcement = null;
+  const a = value.announcement;
+  if (a && typeof a === 'object' && text(a.text, LIVE_TEXT_CHARS)) {
+    const startsAt = time(a.startsAt),
+      endsAt = time(a.endsAt);
+    if ([...a.text].length > LIVE_TEXT_CHARS)
+      problems.push(`the announcement is cut to ${LIVE_TEXT_CHARS} characters (xgames.fun refuses a longer one)`);
+    if (a.level !== undefined && a.level !== 'info' && a.level !== 'warning')
+      problems.push(`an announcement's level is info or warning, not ${JSON.stringify(a.level)}`);
+    if ((startsAt === null || startsAt <= now) && (endsAt === null || endsAt > now))
+      announcement = {
+        id: createHash('sha256').update(`${a.text}\n${startsAt}\n${endsAt}`).digest('hex').slice(0, 12),
+        text: text(a.text, LIVE_TEXT_CHARS),
+        level: a.level === 'warning' ? 'warning' : 'info',
+        startsAt,
+        endsAt,
+      };
+  } else if (a) problems.push('the announcement needs its text: {"text": "…"}');
+  let config = {};
+  const c = value.config;
+  if (c !== undefined && c !== null) {
+    const bytes = Buffer.byteLength(JSON.stringify(c));
+    if (typeof c !== 'object' || Array.isArray(c)) problems.push('the config is a JSON object: {"difficulty": "hard"}');
+    else if (bytes > LIVE_CONFIG_BYTES)
+      problems.push(`the config is ${bytes} bytes as JSON; xgames.fun takes ${LIVE_CONFIG_BYTES} at most`);
+    else config = c;
+  }
+  const m = value.maintenance;
+  const maintenance =
+    m === true || (m && typeof m === 'object')
+      ? { message: text(m?.message, LIVE_TEXT_CHARS) || MAINTENANCE_DEFAULT, since: time(m?.since) ?? null }
+      : null;
+  const version = Object.keys(config).length ? (Number.isSafeInteger(value.version) ? value.version : 1) : 0;
+  return { live: { announcement, config, version, maintenance }, problems };
+}
+
+/** Reads <game>/.gamesfun/live.json now. → {live, problems, exists}; never throws (a broken file is said, not fatal). */
+export async function readLive(dir, now = Date.now()) {
+  let raw;
+  try {
+    raw = await readFile(path.join(dir, LIVE_FILE), 'utf8');
+  } catch {
+    return { live: LIVE_EMPTY, problems: [], exists: false };
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (e) {
+    return { live: LIVE_EMPTY, problems: [`${LIVE_FILE} is not JSON: ${e.message}`], exists: true };
+  }
+  return { ...parseLiveFile(value, now), exists: true };
+}
+
+/** The holding page xgames.fun's play edge serves for the game's HTML while it is paused (503, never cached). */
+export function maintenancePage(maintenance) {
+  const esc = s =>
+    s.replace(/[&<>"']/g, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+  return (
+    '<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta http-equiv="refresh" content="60"><title>Back soon</title>' +
+    '<body style="margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0e;color:#d0d0d8;font:16px/1.5 system-ui,sans-serif">' +
+    `<main style="max-width:32rem;padding:24px;text-align:center"><p style="margin:0 0 8px;font-weight:600;color:#fff">Paused for maintenance</p><p style="margin:0">${esc(maintenance.message)}</p>` +
+    `<p style="margin:16px 0 0;font-size:13px;opacity:.6">xcore dev: ${LIVE_FILE} has maintenance on.</p></main></body>`
+  );
+}
+/** The refusal of /api/* and /platform/v1/* while paused, as xgames.fun's play edge answers it. */
+export const maintenanceBody = m => ({ ok: false, code: 'maintenance', why: m.message, since: m.since });
+
+const LIVE_PATH = '/platform/v1/live';
+/**
+ * The dev host's live routes (./index.mjs route, tried before the platform's): GET /platform/v1/live from the file, and
+ * while maintenance is on, the holding page for the game's HTML under /game/ and 503 'maintenance' for /game/api/* and
+ * /platform/v1/* (not /platform/v1/live, nor the local sign-in /platform/v1/dev/*). → true when it answered.
+ * `say(problems)`: the file's problems, each time they change.
+ */
+export function createLiveRoutes({ dir, apiAt = '/game/api/', say = () => {}, now = () => Date.now() }) {
+  let said = '';
+  const current = async () => {
+    const r = await readLive(dir, now());
+    const words = r.problems.join('; ');
+    if (words !== said) {
+      said = words;
+      if (words) say(r.problems);
+    }
+    return r.live;
+  };
+  const isApi = p => p.startsWith(apiAt) || p === apiAt.slice(0, -1);
+  const isPlatform = p => p.startsWith('/platform/v1/') && p !== LIVE_PATH && !p.startsWith('/platform/v1/dev/');
+  const isPage = (p, method) =>
+    (method === 'GET' || method === 'HEAD') &&
+    p.startsWith('/game/') &&
+    !isApi(p) &&
+    (p.endsWith('/') || /\.html?$/i.test(p));
+  const send = (res, status, type, body, extra = {}) => {
+    res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store', ...extra });
+    res.end(body);
+    return true;
+  };
+  return {
+    current,
+    /** Whether a WebSocket upgrade to `pathname` is refused now (the game is paused). */
+    async refuseUpgrade(pathname) {
+      return isApi(pathname) && !!(await current()).maintenance;
+    },
+    async handle(req, res, url) {
+      const p = url.pathname;
+      if (p === LIVE_PATH && (req.method === 'GET' || req.method === 'HEAD'))
+        return send(res, 200, 'application/json; charset=utf-8', JSON.stringify({ ok: true, ...(await current()) }));
+      if (!isApi(p) && !isPlatform(p) && !isPage(p, req.method)) return false;
+      const m = (await current()).maintenance;
+      if (!m) return false;
+      if (isPage(p, req.method))
+        return send(res, 503, 'text/html; charset=utf-8', maintenancePage(m), { 'retry-after': '60' });
+      return send(res, 503, 'application/json; charset=utf-8', JSON.stringify(maintenanceBody(m)), {
+        'retry-after': '60',
+      });
+    },
+  };
+}