@xgamesfun/xcore 0.1.0 → 0.2.1

package/lib/files.mjs

@@ -0,0 +1,208 @@
+// `xcore files ls|put|get|rm|usage`: the game's project files (xgames.fun's STORAGE.md §2): files the developer or
+// the game's server writes, never players (replays, generated levels, content packs). On this machine by default (the
+// ones `xcore dev` gives env.GF.files, in .gamesfun/dev/files/: ./dev/files.mjs); with `live: true` the game's files on
+// xgames.fun, through the owner's routes (§8.8; each call is kept in the game's audit log there):
+//   GET    /api/kit/games/<id>/files?prefix=&after=   the list
+//   PUT    /api/kit/games/<id>/files/<path>           the raw bytes, content-type, x-gf-public: 1 for a public one
+//   GET    /api/kit/games/<id>/files/<path>           the bytes
+//   DELETE /api/kit/games/<id>/files/<path>
+//   GET    /api/kit/games/<id>/files-usage            the bytes against the cap
+// A public file is served at https://<slug>.xgamesusercontent.com/<path>, another site to the browser (here, at the
+// files origin `xcore dev` prints: another origin, though the same site). Paths are checked here as xgames.fun checks
+// them (../server/contract.mjs FILES).
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { call, studioOrigin } from './publish/client.mjs';
+import { OIDC_KIND, requireCredential } from './publish/oidc.mjs';
+import { notFromCi } from './db.mjs';
+import { readLinks } from './publish/index.mjs';
+import { FILES, STUDIO_BODY_BYTES, fileType, filePathProblem, studioFeatures } from './server/contract.mjs';
+import { createFileStore } from './dev/files.mjs';
+import { CMD } from './command.mjs';
+
+const refuse = (why, code = 'files') => Object.assign(new Error(why), { code });
+const encodePath = p => p.split('/').map(encodeURIComponent).join('/');
+
+/** The game on xgames.fun, how to sign the call, and its files' domain; refused when xgames.fun has no files yet. */
+async function target(dir, { origin, env, fetchImpl }) {
+  const known = (await readLinks(dir))[origin];
+  if (!known?.projectId)
+    throw refuse(`this folder's game is not on ${origin} yet: publish it first (${CMD} publish), then put its files`);
+  const cred = await requireCredential(origin, { env, fetchImpl });
+  const auth = await cred.auth();
+  const me = await call(origin, '/api/kit/me', { ...auth, fetchImpl });
+  if (!studioFeatures(me).has('files'))
+    throw refuse(
+      'this xgames.fun does not keep project files yet (GET /api/kit/me does not list "files"): on this machine, leave out --live',
+      'feature',
+    );
+  return {
+    id: known.projectId,
+    auth,
+    ci: cred.kind === OIDC_KIND,
+    domain: me?.files?.domain ?? FILES.domain,
+    slug: known.slug ?? null,
+  };
+}
+const base = (origin, id) => `${origin}/api/kit/games/${encodeURIComponent(id)}`;
+
+/** A call whose body or answer is a file's bytes (call() is JSON's). → the Response, refused in words when not ok */
+async function raw(url, { method, auth, body, headers = {}, fetchImpl, ci = false }) {
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method,
+      headers: { ...headers, ...(auth.headers ?? {}), authorization: `Bearer ${auth.token}` },
+      ...(body ? { body, duplex: 'half' } : {}),
+    });
+  } catch (e) {
+    throw Object.assign(new Error(`Could not reach xgames.fun (${e.cause?.code ?? e.message}).`), { status: 0 });
+  }
+  if (res.ok) return res;
+  let a = null;
+  try {
+    a = await res.json();
+  } catch {}
+  // a GitHub Actions run may list and download, not change the files
+  if (res.status === 403 && ci && (method === 'PUT' || method === 'DELETE'))
+    throw Object.assign(new Error(notFromCi(method === 'PUT' ? 'put files' : 'delete files')), {
+      status: 403,
+      code: 'ci',
+    });
+  if (res.status === 413 && !a?.code)
+    throw Object.assign(new Error(tooBigForStudio()), { status: 413, code: 'too-big' });
+  throw Object.assign(new Error(a?.why ?? a?.error ?? `xgames.fun answered ${res.status}.`), {
+    status: res.status,
+    ...(a?.code ? { code: a.code } : {}),
+  });
+}
+
+const mb = n => `${(n / 1_000_000).toFixed(1)} MB`;
+/** Why a file is too big to go through xgames.fun's Studio (its host's 4.5 MB limit on a request), and what to do. */
+const tooBigForStudio = (size = null) =>
+  `${size === null ? 'xgames.fun answered 413: the file was too big for it to take.' : `This file is ${mb(size)}.`} A file put from this machine goes through xgames.fun's Studio, whose host takes at most ${mb(STUDIO_BODY_BYTES)} a request. A bigger one (up to ${FILES.fileBytes / 1048576} MB) goes up from the game's server: env.GF.files.put(path, body) (docs/SERVER.md, "Project files").`;
+
+const local = dir => createFileStore({ dir });
+const answer = a => {
+  if (a.ok === false) throw refuse(a.why, a.code);
+  return a;
+};
+
+/** → {ok, live, items: [{path, bytes, type, public, updatedAt}], after} */
+export async function filesList(
+  dir,
+  { live = false, prefix = '', after = '', origin = studioOrigin(), env = process.env, fetchImpl = fetch } = {},
+) {
+  if (prefix && !prefix.endsWith('/')) prefix += '/';
+  if (!live) return { live: false, ...answer(await local(dir).list({ prefix, after, limit: FILES.listMax })) };
+  const t = await target(dir, { origin, env, fetchImpl });
+  const q = new URLSearchParams({ ...(prefix ? { prefix } : {}), ...(after ? { after } : {}) });
+  const route = `/api/kit/games/${encodeURIComponent(t.id)}/files${q.size ? `?${q}` : ''}`;
+  return { live: true, ...(await call(origin, route, { ...t.auth, fetchImpl })) };
+}
+
+/** A file from this machine to `to` (default: its own name). → {ok, live, path, bytes, url?} */
+export async function filesPut(
+  dir,
+  file,
+  to,
+  { live = false, isPublic = false, type = null, origin = studioOrigin(), env = process.env, fetchImpl = fetch } = {},
+) {
+  const p = to ?? path.basename(file);
+  const bad = filePathProblem(p);
+  if (bad) throw refuse(bad, 'path');
+  let size;
+  try {
+    size = (await stat(file)).size;
+  } catch {
+    throw refuse(`${file} is not there`);
+  }
+  if (size > FILES.fileBytes)
+    throw refuse(
+      `${file} is ${(size / 1048576).toFixed(1)} MB; a file may be ${FILES.fileBytes / 1048576} MB`,
+      'too-big',
+    );
+  const kind = type ?? fileType(p);
+  if (live && size > STUDIO_BODY_BYTES) throw refuse(tooBigForStudio(size), 'too-big');
+  if (!live) {
+    const { readFile } = await import('node:fs/promises');
+    return { live: false, ...answer(await local(dir).put(p, await readFile(file), { type: kind, public: isPublic })) };
+  }
+  const t = await target(dir, { origin, env, fetchImpl });
+  const res = await raw(`${base(origin, t.id)}/files/${encodePath(p)}`, {
+    method: 'PUT',
+    auth: t.auth,
+    body: Readable.toWeb(createReadStream(file)),
+    // Studio's owner route reads the length from content-length, and passes it on to the platform itself (as
+    // content-length and x-gf-length), which streams the body to R2 held to exactly that many bytes
+    headers: {
+      'content-type': kind,
+      'content-length': String(size),
+      ...(isPublic ? { 'x-gf-public': '1' } : {}),
+    },
+    fetchImpl,
+    ci: t.ci,
+  });
+  const a = await res.json().catch(() => ({}));
+  const url = a.url ?? (isPublic && t.slug ? `https://${t.slug}.${t.domain}/${p}` : null);
+  return { ok: true, live: true, path: p, bytes: a.bytes ?? size, ...(url ? { url } : {}) };
+}
+
+/** A file's bytes. → {ok, live, path, body (a Buffer), type, bytes, public} */
+export async function filesGet(
+  dir,
+  p,
+  { live = false, origin = studioOrigin(), env = process.env, fetchImpl = fetch } = {},
+) {
+  const bad = filePathProblem(p);
+  if (bad) throw refuse(bad, 'path');
+  if (!live) return { live: false, path: p, ...answer(await local(dir).get(p)) };
+  const t = await target(dir, { origin, env, fetchImpl });
+  const res = await raw(`${base(origin, t.id)}/files/${encodePath(p)}`, { method: 'GET', auth: t.auth, fetchImpl });
+  const body = Buffer.from(await res.arrayBuffer());
+  return {
+    ok: true,
+    live: true,
+    path: p,
+    body,
+    // xgames.fun sends every download as an attachment (octet-stream) and the file's own type in x-gf-type
+    type: res.headers.get('x-gf-type') ?? res.headers.get('content-type') ?? 'application/octet-stream',
+    bytes: body.length,
+    public: res.headers.get('x-gf-public') === '1',
+  };
+}
+
+/** → {ok, live, deleted} */
+export async function filesRemove(
+  dir,
+  p,
+  { live = false, origin = studioOrigin(), env = process.env, fetchImpl = fetch } = {},
+) {
+  const bad = filePathProblem(p);
+  if (bad) throw refuse(bad, 'path');
+  if (!live) return { live: false, ...answer(await local(dir).delete(p)) };
+  const t = await target(dir, { origin, env, fetchImpl });
+  const res = await raw(`${base(origin, t.id)}/files/${encodePath(p)}`, {
+    method: 'DELETE',
+    auth: t.auth,
+    fetchImpl,
+    ci: t.ci,
+  });
+  const a = await res.json().catch(() => ({}));
+  return { ok: true, live: true, deleted: a.deleted ?? true };
+}
+
+/** → {ok, live, bytes, files, cap} */
+export async function filesUsage(
+  dir,
+  { live = false, origin = studioOrigin(), env = process.env, fetchImpl = fetch } = {},
+) {
+  if (!live) return { live: false, ...answer(await local(dir).usage()) };
+  const t = await target(dir, { origin, env, fetchImpl });
+  return {
+    live: true,
+    ...(await call(origin, `/api/kit/games/${encodeURIComponent(t.id)}/files-usage`, { ...t.auth, fetchImpl })),
+  };
+}

package/lib/open.mjs

@@ -3,7 +3,7 @@
 import { spawn } from 'node:child_process';
 import { findChrome } from './browser.mjs';
 
-// `web: true` (games.fun's own sign-in page, `xcore login`) also allows an https address; nothing else ever does.
+// `web: true` (xgames.fun's own sign-in page, `xcore login`) also allows an https address; nothing else ever does.
 export function openCommand(
   url,
   { platform = process.platform, chrome = findChrome()?.path ?? null, web = false } = {},

package/lib/play-policy.mjs

@@ -1,4 +1,4 @@
-// The play origin's contract: how games.fun stores a published game's files (a file tree), which types it serves them
+// The play origin's contract: how xgames.fun stores a published game's files (a file tree), which types it serves them
 // with, and the security headers every page gets. Pure module (no Node or DOM imports), shared by the page check
 // (./publish/hosting.mjs) and the kit.
 //
@@ -144,10 +144,19 @@ export function connectOrigin(value) {
  * backendOrigins): added to connect-src, and the https ones to img-src and media-src (pictures and sounds from the
  * game's own storage). Per game: each tree's files carry only that tree's origins.
  */
-export function playHeaders({ studioOrigin, isolated = false, mime, embedders = [], connect = [], backend = [] }) {
+export function playHeaders({
+  studioOrigin,
+  isolated = false,
+  mime,
+  embedders = [],
+  connect = [],
+  backend = [],
+  files = [],
+}) {
   const own = backend.map(connectOrigin);
-  const extraConnect = [...new Set([...connect.map(connectOrigin), ...own])];
-  const media = own.filter(o => o.startsWith('https:'));
+  // the game's files domain (<slug>.xgamesusercontent.com; STORAGE.md §8.7): pictures, sounds, fonts and fetches
+  const extraConnect = [...new Set([...connect.map(connectOrigin), ...own, ...files])];
+  const media = [...own.filter(o => o.startsWith('https:')), ...files];
   const csp = [
     "default-src 'self'",
     "script-src 'self' 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' blob:",
@@ -155,7 +164,7 @@ export function playHeaders({ studioOrigin, isolated = false, mime, embedders =
     ["connect-src 'self' blob: data:", ...extraConnect].join(' '),
     ["img-src 'self' data: blob:", ...media].join(' '),
     ["media-src 'self' data: blob:", ...media].join(' '),
-    "font-src 'self' data:",
+    ["font-src 'self' data:", ...files].join(' '),
     "style-src 'self' 'unsafe-inline'",
     "object-src 'none'",
     "base-uri 'none'",

package/lib/publish/adopt.mjs

@@ -1,7 +1,7 @@
 // `xcore adopt <folder>`: bring a web game made anywhere (this package's README). It reads the folder's
 // shape (plain static files, or a project whose build makes them: Vite, Next.js static export, Astro, SvelteKit's static
 // adapter, Nuxt generate, Create React App, Parcel, Gatsby, or any `build` script), builds it, writes its record
-// (gamesfun.json → page: lib/publish/page.mjs) and reports everything that does not fit games.fun's hosting
+// (gamesfun.json → page: lib/publish/page.mjs) and reports everything that does not fit xgames.fun's hosting
 // (lib/publish/hosting.mjs), each with its fix:
 //
 //   refused   it cannot be hosted as it is: no static index.html (server-side rendering, a Node server as the
@@ -245,7 +245,7 @@ function readdirSafe(d) {
   }
 }
 
-/** A Unity or Godot project (its sources): games.fun hosts its web export, so that folder is the page. → a shape, or
+/** A Unity or Godot project (its sources): xgames.fun hosts its web export, so that folder is the page. → a shape, or
  *  null when the folder is no engine's project */
 function engineProject(dir) {
   const unity =
@@ -283,7 +283,7 @@ function engineProject(dir) {
     out: null,
     static: null,
     engine: name,
-    why: `a ${name} project with no web export in it: games.fun hosts the export (index.html and what it loads), not the project`,
+    why: `a ${name} project with no web export in it: xgames.fun hosts the export (index.html and what it loads), not the project`,
     fix: unity
       ? 'In Unity: File → Build Settings → WebGL, Player Settings → Publishing Settings: Compression Format Disabled (or Decompression Fallback on), then Build into a folder such as Builds/WebGL, and adopt again (or point adopt at it: --out Builds/WebGL)'
       : 'In Godot: Project → Export → Add… → Web, Thread Support off, export to build/web/index.html, and adopt again (or point adopt at it: --out build/web)',
@@ -295,15 +295,15 @@ function godotExportFix(preset) {
   const exportIt = `Export it: godot --headless --path . --export-release "${preset.name}" ${preset.path} (or Project → Export → ${preset.name} in the editor), then ${CMD} adopt again`;
   return preset.wrote
     ? `xcore wrote a Web export preset in export_presets.cfg (Thread Support off, to build/web/index.html, leaving xcore's folders out of the game's package; build/ has a .gdignore). ${exportIt}`
-    : `Its Web export preset is there, with nothing exported yet. ${exportIt}${preset.threads ? '. It has Thread Support on: turn it off first (a games.fun page is not cross-origin isolated)' : ''}`;
+    : `Its Web export preset is there, with nothing exported yet. ${exportIt}${preset.threads ? '. It has Thread Support on: turn it off first (an xgames.fun page is not cross-origin isolated)' : ''}`;
 }
 
 /** What a Godot project's Web preset leaves out of the game's package: xcore's and the tools' folders. */
 export const GODOT_EXCLUDE = 'build/*, evidence/*, gamesfun/*, server/*, node_modules/*, .work/*';
 
 /**
- * A Web export preset for games.fun in a Godot project that has none (export_presets.cfg made or added to): Thread
- * Support off (a games.fun page is not cross-origin isolated), exported to build/web/index.html, with xcore's folders
+ * A Web export preset for xgames.fun in a Godot project that has none (export_presets.cfg made or added to): Thread
+ * Support off (an xgames.fun page is not cross-origin isolated), exported to build/web/index.html, with xcore's folders
  * left out of the package, and a .gdignore in build/ so the editor never imports the export's own files.
  * → {wrote, name, path (its export path from the project), threads}; with a Web preset already, that one, unchanged
  */
@@ -734,7 +734,7 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
   const fromRoot = (what, own) => {
     if (fix.some(x => x.what === what)) return; // the same path twice on a line of a bundle
     if (rootPaths++ >= 3) return;
-    const long = `Use relative paths: the game is served under a folder in games.fun Studio's preview and in the kit's dev server, so /x breaks there. ${ROOT_PATH_FIX}`;
+    const long = `Use relative paths: the game is served under a folder in xgames.fun Studio's preview and in the kit's dev server, so /x breaks there. ${ROOT_PATH_FIX}`;
     fix.push({ what, fix: own ?? (fix.some(x => x.fix === long) ? 'The same fix: relative paths' : long) });
   };
   // a page written as name.html (SvelteKit's default, some others): the host serves /name.html and /name/ (from
@@ -791,7 +791,7 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
         for (const u of urls.filter(u => typeof u === 'string' && /^\/(?!\/)/.test(u)))
           fromRoot(
             `${at(f.rel)}:${lineAt(text, m.index)} has an import map entry ${u} from the root`,
-            `Use a relative path (./${u.slice(1)}): the game is served under a folder in games.fun Studio's preview and in the kit's dev server`,
+            `Use a relative path (./${u.slice(1)}): the game is served under a folder in xgames.fun Studio's preview and in the kit's dev server`,
           );
         for (const h of hosts) loadedFrom.add(h);
         if (hosts.length)
@@ -849,7 +849,7 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
       for (const m of text.matchAll(/url\(\s*["']?(\/(?!\/)[^"')]+)/gi))
         fromRoot(
           `${at(f.rel)}:${lineAt(text, m.index)} uses ${m[1]} from the root, in a style`,
-          `Use a relative path (url(./${m[1].slice(1)})): the game is served under a folder in games.fun Studio's preview and in the kit's dev server`,
+          `Use a relative path (url(./${m[1].slice(1)})): the game is served under a folder in xgames.fun Studio's preview and in the kit's dev server`,
         );
       for (const m of text.matchAll(/\b(?:src|href|poster)\s*=\s*["'](\/(?!\/)[^"']*)["']/gi)) {
         const tag = text.slice(text.lastIndexOf('<', m.index), text.indexOf('>', m.index) + 1);
@@ -870,7 +870,7 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
         if (/^\/socket\.io\//.test(m[1])) {
           fix.push({
             what: `${at(f.rel)}:${lineAt(text, m.index)} loads ${m[1]}, which your Socket.IO server serves`,
-            fix: "games.fun serves only the game's files, not your server's: copy the client (node_modules/socket.io-client/dist/socket.io.min.js) into the game and load the copy, then connect with io('https://<your server>') instead of io(), and declare that server: backend use custom --url https://<your server>",
+            fix: "xgames.fun serves only the game's files, not your server's: copy the client (node_modules/socket.io-client/dist/socket.io.min.js) into the game and load the copy, then connect with io('https://<your server>') instead of io(), and declare that server: backend use custom --url https://<your server>",
           });
           continue;
         }
@@ -925,7 +925,7 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
       ))
         fromRoot(
           `${at(f.rel)}:${lineAt(text, m.index)} loads ${m[1]} from the root, in a script`,
-          `Use a relative path (./${m[1].slice(1)}): the game is served under a folder in games.fun Studio's preview and in the kit's dev server`,
+          `Use a relative path (./${m[1].slice(1)}): the game is served under a folder in xgames.fun Studio's preview and in the kit's dev server`,
         );
     }
     if (/\.(m?js|html?)$/i.test(f.rel))
@@ -985,7 +985,7 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
   if (callsApi.length)
     fix.push({
       what: `the page calls api/ on its own origin (${callsApi.slice(0, 3).join(', ')}), and the game has no server/`,
-      fix: `games.fun answers a game's api/ only from its own server/ (a Worker, docs/SERVER.md). Either move that logic into server/, run the server on a host of your own and call it there (${CMD} backend use custom), or run the logic in the page (WebAssembly runs: Pyodide for Python, for example). Ask the person before a change of that size`,
+      fix: `xgames.fun answers a game's api/ only from its own server/ (a Worker, docs/SERVER.md). Either move that logic into server/, run the server on a host of your own and call it there (${CMD} backend use custom), or run the logic in the page (WebAssembly runs: Pyodide for Python, for example). Ask the person before a change of that size`,
     });
   const threads = devices.get('SharedArrayBuffer (threads)');
   devices.delete('SharedArrayBuffer (threads)');
@@ -993,13 +993,13 @@ export async function scanPage(out, { backend = [], limits = DEFAULT_LIMITS, pre
   const godotThreads = /\bGODOT_THREADS_ENABLED\s*=\s*true\b/.test(entry);
   if (godotThreads)
     fix.push({
-      what: `${at('index.html')} is a Godot export built with Thread Support: it needs a cross-origin isolated page, which games.fun does not give a brought game, so it stops at "missing features: Cross Origin Isolation, SharedArrayBuffer"`,
+      what: `${at('index.html')} is a Godot export built with Thread Support: it needs a cross-origin isolated page, which xgames.fun does not give a brought game, so it stops at "missing features: Cross Origin Isolation, SharedArrayBuffer"`,
       fix: 'In Godot (4.3 or later), Project → Export → Web: turn Thread Support off and export again (Godot 4.0 to 4.2 always export with threads: upgrade the project)',
     });
   else if (threads)
     warn.push({
-      what: `${threads} uses SharedArrayBuffer or Atomics.wait: a games.fun page is not cross-origin isolated, so SharedArrayBuffer is undefined there`,
-      fix: 'Keep a path without it (the game should still start), or export single-threaded: an engine built with threads (Emscripten pthreads, Godot or Unity with thread support) does not start on games.fun',
+      what: `${threads} uses SharedArrayBuffer or Atomics.wait: an xgames.fun page is not cross-origin isolated, so SharedArrayBuffer is undefined there`,
+      fix: 'Keep a path without it (the game should still start), or export single-threaded: an engine built with threads (Emscripten pthreads, Godot or Unity with thread support) does not start on xgames.fun',
     });
   if (devices.size)
     warn.push({
@@ -1087,6 +1087,22 @@ export async function adopt(
     out = saved.out;
     stat = saved.build || saved.static !== saved.out ? (saved.static ?? null) : null;
     report.fromRecord = true;
+  } else if (saved) {
+    // a flag changes its own part of the record; the rest stays as recorded (a custom build kept when only --static
+    // is given; the folder loot add chose kept when only --out is). A new --build makes its own output folder.
+    report.kept = [];
+    if (!build && saved.build) {
+      build = saved.build;
+      report.kept.push(`build (${saved.build})`);
+    }
+    if (!out && saved.out && !(build && build !== saved.build)) {
+      out = saved.out;
+      report.kept.push(`out (${saved.out})`);
+    }
+    if (!stat && saved.static && (saved.build || saved.static !== saved.out)) {
+      stat = saved.static;
+      report.kept.push(`static (${saved.static})`);
+    }
   }
   const shape = detectShape(root);
   report.shape = {
@@ -1097,7 +1113,7 @@ export async function adopt(
   };
   const given = build || out;
   if (!given && (shape.kind === 'server' || shape.kind === 'none')) {
-    // a Godot project with no Web export yet: its preset written for games.fun (single-threaded, into build/web/)
+    // a Godot project with no Web export yet: its preset written for xgames.fun (single-threaded, into build/web/)
     const preset = shape.engine === 'Godot' ? await godotWebPreset(root) : null;
     if (preset?.wrote) report.made.push('export_presets.cfg (a Web preset)', 'build/.gdignore');
     report.refused.push({ what: shape.why, fix: preset ? godotExportFix(preset) : shape.fix });
@@ -1116,7 +1132,7 @@ export async function adopt(
   )
     report.fix.push({
       what: `vite.config sets base: '${shape.base}'`,
-      fix: "Use base: './': the game is served under a folder in games.fun Studio's preview and in the kit's dev server, so paths from the root break there",
+      fix: "Use base: './': the game is served under a folder in xgames.fun Studio's preview and in the kit's dev server, so paths from the root break there",
     });
 
   if (page.build && !noBuild) {
@@ -1214,11 +1230,11 @@ export async function adopt(
   ].find(([, files]) => files.some(f => existsSync(path.join(root, f))));
   const apiFix = report.fix.find(f => /calls api\/ on its own origin/.test(f.what));
   if (apiFix && program)
-    apiFix.what += `; the folder has ${program[0]} (${program[1].find(f => existsSync(path.join(root, f)))}), which games.fun does not run`;
+    apiFix.what += `; the folder has ${program[0]} (${program[1].find(f => existsSync(path.join(root, f)))}), which xgames.fun does not run`;
   const router = pathRouter(root, report.page.out);
   if (router)
     report.warn.push({
-      what: `${router.where} routes by path (${router.how}): a deep link or a reload of a route (/level/2) answers "not found" once hosted, and under a folder (games.fun Studio's preview, the kit's dev server) no route matches`,
+      what: `${router.where} routes by path (${router.how}): a deep link or a reload of a route (/level/2) answers "not found" once hosted, and under a folder (xgames.fun Studio's preview, the kit's dev server) no route matches`,
       fix:
         router.fix ??
         'The host serves files only, with no fallback to index.html. Use hash routing: Vue createWebHashHistory(); Nuxt router: { options: { hashMode: true } } in nuxt.config; React Router createHashRouter or <HashRouter>; Angular withHashLocation() in provideRouter (or useHash: true). Links people already shared keep their old paths',
@@ -1233,12 +1249,12 @@ export async function adopt(
     report.warn.push(
       hasServer
         ? {
-            what: `its Node server (${named}) is not published; its server/ is, and games.fun runs that at /api/*`,
+            what: `its Node server (${named}) is not published; its server/ is, and xgames.fun runs that at /api/*`,
             fix: `Fine when server/ took over its work (the page talks to api/ on its own origin, not to the Node server): run both with ${CMD} dev to see. If the page still needs the Node server, keep it on your own host and declare it: ${CMD} backend use custom --url https://<your server>`,
           }
         : {
-            what: `its server (${named}) is not published: games.fun hosts ${report.page.out}/ only`,
-            fix: `Either move what it does into server/, which games.fun runs for the game (docs/SERVER.md: a Worker at /api/*, Durable Objects for rooms; ${CMD} add multiplayer starts rooms, ${CMD} add database a database; ${CMD} dev runs it here), or keep it on your own host and declare it: ${CMD} backend use custom --url https://<your server> (its wss:// origin comes with it), with the page connecting to that address instead of its own origin (io(), fetch('/api/…')); the server answers CORS for https://<slug>-play.xgames.fun`,
+            what: `its server (${named}) is not published: xgames.fun hosts ${report.page.out}/ only`,
+            fix: `Either move what it does into server/, which xgames.fun runs for the game (docs/SERVER.md: a Worker at /api/*, Durable Objects for rooms; ${CMD} add multiplayer starts rooms, ${CMD} add database a database; ${CMD} dev runs it here), or keep it on your own host and declare it: ${CMD} backend use custom --url https://<your server> (its wss:// origin comes with it), with the page connecting to that address instead of its own origin (io(), fetch('/api/…')); the server answers CORS for https://<slug>-play.xgames.fun`,
           },
     );
   }
@@ -1287,6 +1303,7 @@ export function reportLines(r, { shown = d => d } = {}) {
       `  published folder: ${r.page.out}${r.page.build ? `, made by: ${r.page.build}` : ''}${r.page.static && r.page.static !== r.page.out ? `; xcore adds its files to: ${r.page.static}` : ''}; ${r.files} files, ${mb(r.bytes)}`,
     );
   if (r.fromRecord) lines.push('  as gamesfun.json records it (give --build, --out or --static to change it)');
+  if (r.kept?.length) lines.push(`  kept from gamesfun.json: ${r.kept.join(', ')}`);
   if (r.wrote) lines.push('  wrote gamesfun.json (page: how it builds and what is published; never published itself)');
   const list = (title, items) => {
     if (!items.length) return;
@@ -1305,19 +1322,42 @@ export function reportLines(r, { shown = d => d } = {}) {
   list('Fix before publishing', r.fix);
   list('Worth a look', r.warn);
   if (r.origins.declared.length) lines.push('', `backend.json lets the page reach: ${r.origins.declared.join(', ')}`);
-  lines.push(
-    '',
-    r.refused.length
-      ? r.made?.length
-        ? `Wrote ${r.made.join(' and ')}; no record yet (gamesfun.json). Do the above and adopt again.`
-        : 'Nothing was written. Fix the above and adopt again.'
-      : r.fix.length
-        ? `Next: fix the list above, then ${CMD} check (the page in Chrome, as the host serves it).`
-        : `Next: ${CMD} check (the page in Chrome, as the host serves it); when you want it live, ${CMD} login and ${CMD} publish.`,
-  );
+  lines.push('', adoptNext(r, { shown }).words);
   return lines;
 }
 
+/**
+ * Where an adopt leaves the game, and what to do next (the report's last line, and `state` and `next` in --json):
+ *   refused (nothing recorded; `made` lists any file written to help, such as a Godot Web preset) → fix, adopt again
+ *   fix     (recorded, with problems that stop a publish)                                         → fix, then check
+ *   ready   (recorded; only "worth a look" left, if anything)                                     → check, then publish
+ * → { state, words, next (the command to run, or null while something must be fixed by hand first) }
+ */
+export function adoptNext(r, { shown = d => d } = {}) {
+  const name = shown(r.dir);
+  // the folder for the next commands, when it is not the one they run in
+  const at = name === '.' ? '' : ` ${/[\s"'$`\\]/.test(name) ? JSON.stringify(name) : name}`;
+  if (r.refused.length)
+    return {
+      state: 'refused',
+      words: r.made?.length
+        ? `Wrote ${r.made.join(' and ')}; no record yet (gamesfun.json). Do the above and adopt again.`
+        : 'Nothing was written. Fix the above and adopt again.',
+      next: null,
+    };
+  if (r.fix.length)
+    return {
+      state: 'fix',
+      words: `Next: fix the list above, then ${CMD} check${at} (the page in Chrome, as the host serves it).`,
+      next: null,
+    };
+  return {
+    state: 'ready',
+    words: `Next: ${CMD} check${at} (the page in Chrome, as the host serves it); when you want it live, ${CMD} login and ${CMD} publish${at}.`,
+    next: `${CMD} check${at}`,
+  };
+}
+
 /**
  * `xcore loot add`: where a game's economy lives and its page client (@xgamesfun/solana's, as ../economy.mjs
  * installPage copies it). A brought game keeps both in the folder its build copies as it is (gamesfun.json page.static),
@@ -1367,7 +1407,7 @@ export async function addLoot(dir, { env = process.env } = {}) {
         ...laid,
         `The page client is in ${where}gf/loot/ (a copy: never edit it; publish keeps it current).`,
         `Load it from the page at run time with a page-relative URL: const { solanaApp, walletStandardSigner } = await import(new URL('gf/loot/play/index.js', document.baseURI).href) (a bundler leaves a URL import alone; Vite: add /* @vite-ignore */), and { solanaWallets, connectWallet, PAGE_RPC } from gf/loot/wallets.js; read the economy with fetch('${name}').`,
-        "Give solanaApp rpcUrl: PAGE_RPC (the page's own /loot/v1/rpc: games.fun's relay once published, xcore dev's forward on this machine); a browser with no wallet is told so, with the game still playable.",
+        "Give solanaApp rpcUrl: PAGE_RPC (the page's own /loot/v1/rpc: xgames.fun's relay once published, xcore dev's forward on this machine); a browser with no wallet is told so, with the game still playable.",
         `From Godot, Unity or a page with gamesfun.js (${CMD} add signin): GamesFun.loot.ready(), .connect() and .call('shop'), .call('buy', key, {listing}) … do the same with JSON in and out; play it all with ${CMD} dev.`,
         `Going live is the person's own step, in their own wallet: ${CMD} loot approve (in the folder with ${name}).`,
       ]