arcadible 0.1.47 → 0.1.48

package/README.md

@@ -46,6 +46,7 @@ Your repository is the store page: `arcadible.toml` holds the game's settings, `
 | `arc inspect`  | Prints the manifest Arcadible will see, or one value from it                   |
 | `arc build`    | Runs your project's build command                                              |
 | `arc pack`     | Packages your project into the zip that `arc deploy` uploads                   |
+| `arc serve`    | Serves your game locally, framed in a play page, as Arcadible does             |
 | `arc deploy`   | Validates, builds, packages, and publishes, directly or through GitHub Actions |
 | `arc play`     | Plays a deployed game from any channel or version                              |
 | `arc open`     | Opens a game's store page                                                      |

package/bin/arc-default.js

@@ -39,6 +39,7 @@ const main = function (argv) {
       .command("validate", "Validate project")
       .command("build", "Build project")
       .command("pack", "Package project")
+      .command("serve", "Serve a game locally")
       .command("deploy", "Deploy project")
       .command("open", "Open a game's store page")
       .command("play", "Play a game")

package/bin/arc-serve.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+"use strict";
+
+// [import]
+
+const path = require("node:path");
+
+// [import]
+
+const hideBin = require("yargs/helpers").hideBin;
+const yargs = require("yargs/yargs");
+
+// [import]
+
+const args = require("../src/util/argv");
+const cfgcode = require("../src/config/code");
+const cfgpackage = require("../src/config/package");
+const cfgproduct = require("../src/config/product");
+const cfgurl = require("../src/config/url");
+const error = require("../src/util/error");
+const log = require("../src/util/log");
+const output = require("../src/util/output");
+const phrase = require("../src/phrase");
+const rc = require("../src/util/rc");
+const serve = require("../src/cli/serve");
+const shell = require("../src/util/shell");
+const spinner = require("../src/util/spinner");
+
+// [use]
+
+const abort = output.abort;
+const ArcError = error.ArcError;
+const findRc = rc.findRc;
+const launch = shell.launch;
+const launched = output.launched;
+const relative = path.relative;
+const resolve = path.resolve;
+const SpinnerWheel = spinner.SpinnerWheel;
+
+// [declare]
+
+const COMMAND = "serve";
+const PORT = 4100;
+const TOOL = cfgproduct.tool;
+const VERSION = cfgpackage.version;
+
+// [define]
+
+const conf = {
+  build: true,
+  open: false,
+  port: PORT,
+  quiet: false,
+  ...findRc(TOOL, COMMAND, process.argv),
+};
+
+// [function]
+
+// fails unless the port is one a server can listen on.
+const checkPort = function (port) {
+  if (Number.isInteger(port) && port > 0 && port < 65536) {
+    return Promise.resolve();
+  }
+  return Promise.reject(
+    new ArcError(cfgcode.ARGUMENT_INVALID, phrase.portInvalid()),
+  );
+};
+
+// [function]
+
+// the page --url names, as a URL, or a failure when it isn't an http one.
+const checkUrl = function (url) {
+  if (url === null || typeof url === "undefined") {
+    return Promise.resolve(null);
+  }
+  try {
+    const parsed = new URL(String(url));
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      return Promise.resolve(parsed.href);
+    }
+  } catch (ex) {
+    // not a URL at all: refused below, as one that isn't http.
+  }
+  return Promise.reject(
+    new ArcError(cfgcode.ARGUMENT_INVALID, phrase.urlInvalid()),
+  );
+};
+
+// [function]
+
+// warns once for each of Arcadible's files that's a kept copy, or can't be
+// had, rather than on every request.
+const remoteWarnings = function ({ quiet }) {
+  const warned = new Set();
+  return function (name, file, ex) {
+    const message = ex
+      ? phrase.remoteUnreachable(name)
+      : file?.kept && phrase.remoteKept(name, file.fetchedAt);
+    if (!message || quiet || warned.has(message)) {
+      return;
+    }
+    warned.add(message);
+    log.pw(message);
+  };
+};
+
+// [function]
+
+const start = function (argv) {
+  const quiet = argv.quiet;
+  // `.arcrc` values are strings, and a flag that isn't a number is NaN.
+  const port = Number(argv.port);
+  const root = resolve(process.cwd(), argv.cwd);
+  const sw = new SpinnerWheel("Building... %s");
+  return checkPort(port)
+    .then(() => checkUrl(argv.url))
+    .then((url) =>
+      serve({
+        build: argv.build,
+        handler: {
+          onBuild: () => sw.start(quiet),
+          onReload() {
+            if (!quiet) {
+              log.p(phrase.reloaded());
+            }
+          },
+          onRemote: remoteWarnings({ quiet }),
+        },
+        port,
+        root,
+        url,
+      }),
+    )
+    .then((served) => {
+      sw.stop(true);
+      const stop = () => {
+        served.close();
+        process.exit(0);
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+      if (!quiet) {
+        log.result(phrase.served(served), [
+          ["Play:", `${served.page}/`],
+          [phrase.serveAlone(), served.game],
+          served.url
+            ? phrase.serveNextUrl()
+            : phrase.serveNext(relative(root, served.deployDir) || "."),
+        ]);
+        if (served.probed && !served.probed.reachable) {
+          log.nlpw(phrase.urlUnreachable(served.url));
+        } else if (served.probed && !served.probed.frameable) {
+          log.nlpw(phrase.urlNotFrameable(served.url, cfgurl.SERVE_URL));
+        }
+      }
+      return argv.open ? launch(`${served.page}/`) : false;
+    })
+    .then((where) => {
+      if (where !== false && !quiet) {
+        launched(where, `http://localhost:${port}/`);
+      }
+    })
+    .catch((ex) => abort(phrase.aborted(COMMAND), ex, { sw }));
+};
+
+// [function]
+
+const main = function (argv) {
+  return start(
+    yargs(args.normalize(hideBin(argv)))
+      .scriptName(`${TOOL} ${COMMAND}`)
+      .usage("$0 [options]")
+      .option("port", {
+        alias: "p",
+        default: conf.port,
+        describe: "Port to serve on",
+        type: "number",
+      })
+      .option("build", {
+        default: conf.build,
+        describe: "Run the build command first",
+        type: "boolean",
+      })
+      .option("url", {
+        describe: "Frame another server's page instead of deploy_dir",
+        type: "string",
+      })
+      .option("open", {
+        alias: "o",
+        default: conf.open,
+        describe: "Open the play page in a web browser",
+        type: "boolean",
+      })
+      .option("quiet", { ...args.QUIET, default: conf.quiet })
+      .option("cwd", args.CWD)
+      .help("help")
+      .alias("help", "h")
+      .version(VERSION)
+      .alias("version", "v")
+      .strict()
+      .parse(),
+  );
+};
+
+// [start]
+
+if (require.main === module) {
+  main(process.argv);
+}
+
+// [export]
+
+module.exports = { main };

package/package.json

@@ -11,6 +11,7 @@
     "arc-open": "bin/arc-open.js",
     "arc-pack": "bin/arc-pack.js",
     "arc-play": "bin/arc-play.js",
+    "arc-serve": "bin/arc-serve.js",
     "arc-validate": "bin/arc-validate.js",
     "arc-whoami": "bin/arc-whoami.js"
   },
@@ -28,10 +29,12 @@
     "ini": "^6.0.0",
     "jsdom": "^27.3.0",
     "marked": "^17.0.1",
+    "mime-types": "^3.0.2",
     "mp4box": "^2.3.0",
     "open": "^8.4.2",
     "pretty-toml": "^1.0.0",
     "qrcode-terminal": "^0.12.0",
+    "range-parser": "^1.3.0",
     "semver": "^7.7.3",
     "yargs": "^17.7.2",
     "zod": "^4.1.13"
@@ -52,6 +55,7 @@
     "./pack": "./src/cli/pack.js",
     "./play": "./src/cli/play.js",
     "./predeploy": "./src/cli/predeploy.js",
+    "./serve": "./src/cli/serve.js",
     "./validate": "./src/cli/validate.js",
     "./whoami": "./src/cli/whoami.js"
   },
@@ -75,5 +79,5 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.js\""
   },
-  "version": "0.1.47"
+  "version": "0.1.48"
 }

package/src/action/serve/tool.js

@@ -0,0 +1,166 @@
+"use strict";
+// arc serve: builds the project unless told not to, then serves deploy_dir
+// framed in a local play page (src/serve), reloading the game when deploy_dir
+// changes.
+
+// [import]
+
+const path = require("node:path");
+
+// [import]
+
+const fs = require("fs-extra");
+
+// [import]
+
+const buildTool = require("../build/tool");
+const cfgcode = require("../../config/code");
+const cfgproduct = require("../../config/product");
+const cfguri = require("../../config/uri");
+const commands = require("../../util/command");
+const error = require("../../util/error");
+const files = require("../../serve/files");
+const given = require("../../parser/given");
+const os = require("../../util/os");
+const phrase = require("../../phrase");
+const reload = require("../../serve/reload");
+const remote = require("../../serve/remote");
+const server = require("../../serve/server");
+
+// [use]
+
+const ArcError = error.ArcError;
+const buildCommand = commands.buildCommand;
+const configDir = os.configDir;
+const dirFiles = files.dirFiles;
+const join = path.join;
+const pathExists = fs.pathExists;
+const relative = path.relative;
+const remoteFiles = remote.remoteFiles;
+const resolvePath = path.resolve;
+const serve = server.serve;
+const watchDir = reload.watchDir;
+
+// [declare]
+
+// what build.channel says while served locally (docs: arc-serve.md).
+const CHANNEL = "local";
+// the saves of a game with no id yet, kept apart from any other's.
+const UNNAMED = "local";
+
+// [function]
+
+// the headers a page needs for the play page to frame it: the play page is
+// cross-origin isolated, so a cross-origin frame must be too, and allow it.
+const FRAMEABLE = {
+  "cross-origin-embedder-policy": ["credentialless", "require-corp"],
+  "cross-origin-resource-policy": ["cross-origin"],
+};
+
+// [function]
+
+// what `url` says when asked: `{ reachable, frameable }`, where `frameable`
+// says whether it sends the headers the play page needs to frame it.
+const probe = async function (url) {
+  try {
+    const res = await fetch(url, { method: "GET" });
+    await res.body?.cancel();
+    const frameable = Object.entries(FRAMEABLE).every(([name, values]) =>
+      values.includes(res.headers.get(name)?.trim().toLowerCase()),
+    );
+    return { frameable, reachable: true };
+  } catch (ex) {
+    return { frameable: false, reachable: false };
+  }
+};
+
+// [function]
+
+// listens, turning a port in use into its code.
+const listen = async function (options) {
+  try {
+    return await serve(options);
+  } catch (ex) {
+    if (ex.code === "EADDRINUSE") {
+      throw new ArcError(cfgcode.PORT_IN_USE, phrase.portInUse(options.port), {
+        cause: ex,
+      });
+    }
+    throw ex;
+  }
+};
+
+// [function]
+
+// serves the project at `conf.root`. `conf.build` false skips the build, and
+// `conf.url` frames that server's page instead of serving deploy_dir.
+// `conf.handler` hears `onBuild()` as a build starts, `onRemote(name, file,
+// error)` for each of Arcadible's files, and `onReload()` for each reload.
+// resolves with `{ page, game, built, deployDir, url, probed, version,
+// close() }`, where `probed` is what `conf.url` answered.
+const main = async function (conf) {
+  const { port, root, url } = conf;
+  const handler = {
+    onBuild() {},
+    onReload() {},
+    onRemote() {},
+    ...conf.handler,
+  };
+  const project = await given(conf);
+  const game = project.game;
+  const options = {
+    info: {
+      channel: CHANNEL,
+      id: game.id ?? UNNAMED,
+      title: game.title ?? game.handle ?? cfgproduct.title,
+      version: game.version ?? null,
+    },
+    onRemote: handler.onRemote,
+    port,
+    remote: remoteFiles({
+      asset: cfguri.ARCADIBLE_ASSET,
+      dir: join(configDir(), cfgproduct.tool, "sdk"),
+      sdk: cfguri.ARCADIBLE_SDK,
+    }),
+  };
+  const version = game.version ?? null;
+  if (url) {
+    const served = await listen({ ...options, src: url });
+    const probed = await probe(url);
+    return { ...served, built: false, deployDir: null, probed, url, version };
+  }
+  const built =
+    conf.build !== false && Boolean(buildCommand(project.workflow.build));
+  if (built) {
+    handler.onBuild();
+    await buildTool({ project, root });
+  }
+  const deployDir = resolvePath(root, project.workflow.deploy_dir);
+  if (!(await pathExists(deployDir))) {
+    throw new ArcError(
+      cfgcode.DEPLOY_DIR_MISSING,
+      phrase.deployDirMissing(relative(root, deployDir) || "."),
+    );
+  }
+  const served = await listen({ ...options, files: dirFiles(deployDir) });
+  const stop = watchDir(deployDir, () => {
+    served.reload();
+    handler.onReload();
+  });
+  return {
+    ...served,
+    built,
+    close() {
+      stop();
+      served.close();
+    },
+    deployDir,
+    probed: null,
+    url: null,
+    version,
+  };
+};
+
+// [export]
+
+module.exports = main;

package/src/cli/index.js

@@ -12,6 +12,7 @@ const open = require("./open");
 const pack = require("./pack");
 const play = require("./play");
 const predeploy = require("./predeploy");
+const serve = require("./serve");
 const validate = require("./validate");
 const whoami = require("./whoami");
 
@@ -28,6 +29,7 @@ module.exports = {
   pack,
   play,
   predeploy,
+  serve,
   validate,
   whoami,
 };

package/src/cli/serve.js

@@ -0,0 +1,15 @@
+"use strict";
+
+// [import]
+
+const serveTool = require("../action/serve/tool");
+
+// [function]
+
+const main = function (conf) {
+  return serveTool(conf);
+};
+
+// [export]
+
+module.exports = main;

package/src/config/code.js

@@ -37,6 +37,7 @@ const CLI = {
   PACKAGE_UNCOMPRESSED_TOO_LARGE: "package_uncompressed_too_large",
   PARSE_FAILED: "parse_failed",
   PATH_NOT_FOUND: "path_not_found",
+  PORT_IN_USE: "port_in_use",
   PROJECT_NOT_REPO_ROOT: "project_not_repo_root",
   SESSION_EXPIRED: "session_expired",
   TEMPLATE_MISSING: "template_missing",

package/src/config/uri.js

@@ -12,6 +12,11 @@ const PROTOCOL = cfgproduct.protocol;
 // [export]
 
 module.exports = {
+  // where arc serve fetches Arcadible's own files (src/serve/remote.js): the
+  // asset site, which has the play page's host, and a build origin, any of
+  // which serves the SDK's hosted script at /arcadible/sdk/.
+  ARCADIBLE_ASSET: "https://asset.offst.net",
+  ARCADIBLE_SDK: `https://sdk.${cfgproduct.handle}.io`,
   HOST_APP_PLAY: `${PROTOCOL}://play`,
   HOST_APP_STORE: `${PROTOCOL}://store`,
   HOST_HTTP_ACCOUNT: `https://account.${DOMAIN}`,

package/src/config/url.js

@@ -15,4 +15,6 @@ module.exports = {
   ERRORS: `${cfguri.HOST_HTTP_DEVELOPER}/references/errors`,
   LINK: `${cfguri.HOST_HTTP_ACCOUNT}/link`,
   MANIFEST: `${cfguri.HOST_HTTP_DEVELOPER}/references/${HANDLE}-manifest`,
+  // how to let arc serve's play page frame another server.
+  SERVE_URL: `${cfguri.HOST_HTTP_DEVELOPER}/references/${HANDLE}-cli/arc-serve#url`,
 };

package/src/phrase.js

@@ -272,6 +272,103 @@ const packed = function () {
 
 // [function]
 
+const portInvalid = function () {
+  return "The port must be a whole number from 1 to 65535.";
+};
+
+// [function]
+
+const portInUse = function (port) {
+  return blocks(
+    `Port ${port} is in use.`,
+    "Stop what's using it, or pass another with --port.",
+  );
+};
+
+// [function]
+
+// what one of Arcadible's files is, for arc serve's warnings: `host`, the play
+// page's, or a path under /arcadible/, such as sdk/v1.js.
+const remoteName = function (name) {
+  return name === "host"
+    ? "the play page's host"
+    : `/${cfgproduct.handle}/${name}`;
+};
+
+// [function]
+
+// arc serve's copy of one of Arcadible's files, kept from `fetchedAt`.
+const remoteKept = function (name, fetchedAt) {
+  return `${TITLE} can't be reached: serving ${remoteName(name)} from ${fetchedAt.slice(0, 10)}.`;
+};
+
+// [function]
+
+const remoteUnreachable = function (name) {
+  return `${TITLE} can't be reached, and there's no copy of ${remoteName(name)} yet: the game runs without it until ${TITLE} can be.`;
+};
+
+// [function]
+
+const reloaded = function () {
+  return `Reloaded at ${new Date().toTimeString().slice(0, 8)}.`;
+};
+
+// [function]
+
+const serveAlone = function () {
+  return "The game alone, without the play page:";
+};
+
+// [function]
+
+const serveNext = function (dir) {
+  return `Reloads when ${dir}/ changes. Press Ctrl+C to stop.`;
+};
+
+// [function]
+
+const served = function ({ built, url, version }) {
+  const what = version ? `v${version}` : "the game";
+  if (url) {
+    return `Serving ${what} locally, from ${url}`;
+  }
+  return built
+    ? `Built and serving ${what} locally.`
+    : `Serving ${what} locally.`;
+};
+
+// [function]
+
+const serveNextUrl = function () {
+  return "Your server reloads the game. Press Ctrl+C to stop.";
+};
+
+// [function]
+
+const urlInvalid = function () {
+  return "The URL must be an http or https one, such as http://localhost:5173.";
+};
+
+// [function]
+
+// --url's server sent no headers that let the play page frame it. `link`
+// says how to add them.
+const urlNotFrameable = function (url, link) {
+  return blocks(
+    `⚠ ${url} can't be framed by the play page: it needs to send Cross-Origin-Embedder-Policy: require-corp and Cross-Origin-Resource-Policy: cross-origin.`,
+    ["Add them to your server, as the starters' vite.config.js does:", link],
+  );
+};
+
+// [function]
+
+const urlUnreachable = function (url) {
+  return `⚠ Nothing answers at ${url} yet. Start your server, then reload the play page.`;
+};
+
+// [function]
+
 const pressEnterToOpen = function () {
   return "Press Enter to open the URL.";
 };
@@ -971,6 +1068,8 @@ module.exports = {
   packageTooManyFiles,
   packageUncompressedTooLarge,
   packed,
+  portInUse,
+  portInvalid,
   pressEnterToOpen,
   projectNotRepoRoot,
   releaseFailed,
@@ -978,7 +1077,14 @@ module.exports = {
   releasePublished,
   releaseTimedOut,
   releaseWaiting,
+  reloaded,
+  remoteKept,
+  remoteUnreachable,
   repoNotConnected,
+  serveAlone,
+  serveNext,
+  serveNextUrl,
+  served,
   sessionExpired,
   sizeB,
   sizeGb,
@@ -1001,6 +1107,9 @@ module.exports = {
   unknownTable,
   uploadFailed,
   uploadRateLimited,
+  urlInvalid,
+  urlNotFrameable,
+  urlUnreachable,
   versionExists,
   versionPrerelease,
   versionRelease,

package/src/serve/files.js

@@ -0,0 +1,61 @@
+"use strict";
+// a game's files, read as Arcadible reads them from storage: by exact path,
+// letter case included, even on a disk that ignores it, such as a Mac's. The
+// server reads through `find`, so another source, such as a packed game,
+// can stand in for a folder.
+
+// [import]
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// [use]
+
+const createReadStream = fs.createReadStream;
+const join = path.join;
+const readdir = fs.promises.readdir;
+const stat = fs.promises.stat;
+
+// [function]
+
+// whether every segment of `segments` is named exactly so in `root`.
+const exactCase = async function (root, segments) {
+  const found = await Promise.all(
+    segments.map((segment, i) =>
+      readdir(join(root, ...segments.slice(0, i))).then((names) =>
+        names.includes(segment),
+      ),
+    ),
+  );
+  return found.every(Boolean);
+};
+
+// [function]
+
+// the files in `root`. `find(segments)` resolves with the file at that path,
+// as `{ size, mtime, open({ start, end }) }`, or null when there's none, or
+// it's a folder.
+const dirFiles = function (root) {
+  return {
+    async find(segments) {
+      const file = join(root, ...segments);
+      try {
+        const info = await stat(file);
+        if (!info.isFile() || !(await exactCase(root, segments))) {
+          return null;
+        }
+        return {
+          mtime: info.mtime,
+          open: (range) => createReadStream(file, range),
+          size: info.size,
+        };
+      } catch (ex) {
+        return null;
+      }
+    },
+  };
+};
+
+// [export]
+
+module.exports = { dirFiles };

package/src/serve/game.js

@@ -0,0 +1,185 @@
+"use strict";
+// the game's origin, as Arcadible's router and storage answer it
+// (app/src/cloudfront/io-arcadible-router): a path ending in / gets its
+// index.html, a path is found only with its exact letter case, /arcadible/
+// holds only Arcadible's own files, and each file has the type the release
+// pipeline gives it. The headers are the build origin's, but nothing is
+// cached, so a change shows on reload.
+
+// [import]
+
+const http = require("node:http");
+const path = require("node:path");
+
+// [import]
+
+const mime = require("mime-types");
+const parseRange = require("range-parser");
+
+// [use]
+
+const extname = path.extname;
+
+// [declare]
+
+const RESERVED = "arcadible";
+
+// [function]
+
+// the path's segments, decoded, or null for one that can't be a file's:
+// undecodable, or `.`, `..`, or holding a separator.
+const segmentsOf = function (pathname) {
+  const segments = pathname.slice(1).split("/");
+  try {
+    const decoded = segments.map(decodeURIComponent);
+    const unsafe = decoded.some(
+      (s, i) =>
+        s === "." ||
+        s === ".." ||
+        /[/\\\0]/u.test(s) ||
+        (s === "" && i < decoded.length - 1),
+    );
+    return unsafe ? null : decoded;
+  } catch (ex) {
+    return null;
+  }
+};
+
+// [function]
+
+const plain = function (res, status, headers = {}) {
+  res.writeHead(status, {
+    "content-type": "text/plain; charset=utf-8",
+    ...headers,
+  });
+  res.end(`${http.STATUS_CODES[status]}\n`);
+};
+
+// [function]
+
+// the headers every response from the game's origin has, as Arcadible's: the
+// game is cross-origin isolated, and only the play page can frame it.
+const baseHeaders = function (page) {
+  return {
+    "cache-control": "no-store",
+    "content-security-policy": `frame-ancestors ${page};`,
+    "cross-origin-embedder-policy": "require-corp",
+    "cross-origin-resource-policy": "cross-origin",
+    "referrer-policy": "strict-origin-when-cross-origin",
+  };
+};
+
+// [function]
+
+// a file from `files`, whole or the one range asked for. A range that can't be
+// satisfied is a 416; several ranges, or a malformed one, get the whole file.
+const sendFile = function (req, res, file, headers) {
+  const size = file.size;
+  const ranges = req.headers.range ? parseRange(size, req.headers.range) : -2;
+  if (ranges === -1) {
+    res.writeHead(416, { ...headers, "content-range": `bytes */${size}` });
+    res.end();
+    return;
+  }
+  const single =
+    Array.isArray(ranges) && ranges.length === 1 ? ranges[0] : null;
+  const range = single ?? { end: size - 1, start: 0 };
+  const length = size ? range.end - range.start + 1 : 0;
+  res.writeHead(single ? 206 : 200, {
+    ...headers,
+    "accept-ranges": "bytes",
+    "content-length": length,
+    "last-modified": file.mtime.toUTCString(),
+    ...(single
+      ? { "content-range": `bytes ${range.start}-${range.end}/${size}` }
+      : {}),
+  });
+  if (req.method === "HEAD" || !length) {
+    res.end();
+    return;
+  }
+  file.open(range).pipe(res);
+};
+
+// [function]
+
+// ends the response with `body`, or with none for a HEAD request.
+const endWith = function (req, res, body) {
+  if (req.method === "HEAD") {
+    res.end();
+    return;
+  }
+  res.end(body);
+};
+
+// [function]
+
+// one of Arcadible's files under /arcadible/, from `remote`. `onRemote` hears
+// of each, to say when it's a kept copy or can't be had.
+const sendRemote = function (req, res, { headers, name, onRemote, remote }) {
+  return remote
+    .get(name)
+    .then((file) => {
+      onRemote(name, file);
+      if (!file) {
+        plain(res, 404, headers);
+        return;
+      }
+      res.writeHead(200, {
+        ...headers,
+        "content-length": file.body.length,
+        "content-type": file.type,
+      });
+      endWith(req, res, file.body);
+    })
+    .catch((ex) => {
+      onRemote(name, null, ex);
+      plain(res, 502, headers);
+    });
+};
+
+// [function]
+
+// the request handler for the game's origin. `page` is the play page's
+// origin, the only one that may frame the game.
+const gameHandler = function ({ files, onRemote = () => null, page, remote }) {
+  return function (req, res) {
+    const headers = baseHeaders(page);
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      plain(res, 405, { ...headers, allow: "GET, HEAD" });
+      return Promise.resolve();
+    }
+    const segments = segmentsOf(new URL(req.url, "http://game").pathname);
+    if (!segments) {
+      plain(res, 404, headers);
+      return Promise.resolve();
+    }
+    // /arcadible/, in any letter case, is Arcadible's: only its exact path
+    // reaches Arcadible's files.
+    if (segments[0].toLowerCase() === RESERVED && segments.length > 1) {
+      if (segments[0] !== RESERVED) {
+        plain(res, 404, headers);
+        return Promise.resolve();
+      }
+      const name = segments.slice(1).join("/");
+      return sendRemote(req, res, { headers, name, onRemote, remote });
+    }
+    if (segments.at(-1) === "") {
+      segments[segments.length - 1] = "index.html";
+    }
+    return files.find(segments).then((file) => {
+      if (!file) {
+        plain(res, 404, headers);
+        return;
+      }
+      const type =
+        mime.contentType(extname(segments.at(-1))) ||
+        "application/octet-stream";
+      sendFile(req, res, file, { ...headers, "content-type": type });
+    });
+  };
+};
+
+// [export]
+
+module.exports = { endWith, gameHandler, segmentsOf };

package/src/serve/page.js

@@ -0,0 +1,176 @@
+"use strict";
+// the local play page: it frames the game as the play page does
+// (site/src/javascripts/arcadible/play/app/page.coffee), with the same
+// sandbox and permissions, and runs the play page's own host for the SDK,
+// so saves are kept by the page, across builds. It reloads the
+// game, and only the game, when told to.
+
+// [import]
+
+const serveGame = require("./game");
+
+// [use]
+
+const endWith = serveGame.endWith;
+
+// [declare]
+
+// the play page's iframe, word for word (test/unit/serve/page.test.js).
+const ALLOW =
+  "accelerometer; autoplay; cross-origin-isolated; fullscreen; gamepad; gyroscope; screen-wake-lock";
+const SANDBOX =
+  "allow-orientation-lock allow-pointer-lock allow-same-origin allow-scripts";
+// the page's own paths. Its origin isn't the game's, so they can't collide.
+const HOST = "/_arcadible/host.js";
+const RELOAD = "/_arcadible/reload";
+
+// [function]
+
+// `value` as JSON that's safe inside a <script>.
+const scriptJson = function (value) {
+  return JSON.stringify(value).replace(/</gu, "\\u003c");
+};
+
+// [function]
+
+const escapeHtml = function (text) {
+  return text.replace(
+    /[&<>"]/gu,
+    (c) => ({ '"': "&quot;", "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c],
+  );
+};
+
+// [function]
+
+// the page for `game`: `{ id, channel, version, title, src }`, where `src` is
+// the game's URL, on its own origin.
+const html = function (game) {
+  const config = {
+    allow: ALLOW,
+    channel: game.channel,
+    game: game.id,
+    sandbox: SANDBOX,
+    src: game.src,
+    version: game.version,
+  };
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, viewport-fit=cover">
+    <title>${escapeHtml(game.title)}</title>
+    <style>html,body{margin:0;height:100%;overflow:hidden;background:#000}iframe{display:block;width:100%;height:100%;border:0;visibility:hidden}</style>
+  </head>
+  <body>
+    <script src="${HOST}"></script>
+    <script>
+      const config = ${scriptJson(config)};
+      const frame = document.createElement("iframe");
+      frame.allow = config.allow;
+      frame.sandbox = config.sandbox;
+      frame.addEventListener("load", () => {
+        frame.style.visibility = "visible";
+        frame.focus();
+      });
+      // the host answers the game's hello, so it's created before the frame
+      // exists. Without it, the game stands alone, as off Arcadible.
+      const lib = window.arcadibleHost;
+      if (lib) {
+        try {
+          lib.createHost({
+            backend: lib.indexedDBBackend({ persist: true }),
+            channel: config.channel,
+            frame,
+            game: config.game,
+            origin: new URL(config.src).origin,
+            version: config.version,
+          });
+        } catch (err) {
+          console.error("arcadible: no host for the game:", err);
+        }
+      } else {
+        console.error("arcadible: no host for the game: the play page's host didn't load.");
+      }
+      frame.src = config.src;
+      document.body.prepend(frame);
+      new EventSource(${scriptJson(RELOAD)}).addEventListener("reload", () => {
+        frame.style.visibility = "hidden";
+        frame.src = config.src;
+      });
+    </script>
+  </body>
+</html>
+`;
+};
+
+// [function]
+
+// the headers of the page's responses, as the play page's: it's
+// cross-origin isolated, and nothing frames it.
+const HEADERS = {
+  "cache-control": "no-store",
+  "content-security-policy": "frame-ancestors 'none';",
+  "cross-origin-embedder-policy": "require-corp",
+  "cross-origin-opener-policy": "same-origin",
+};
+
+// [function]
+
+// the request handler for the page's origin. `reloads` keeps the pages
+// listening for a reload; `remote` has the host.
+const pageHandler = function ({
+  game,
+  onRemote = () => null,
+  reloads,
+  remote,
+}) {
+  return function (req, res) {
+    const pathname = new URL(req.url, "http://page").pathname;
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.writeHead(405, { ...HEADERS, allow: "GET, HEAD" }).end();
+      return Promise.resolve();
+    }
+    if (pathname === "/") {
+      res.writeHead(200, {
+        ...HEADERS,
+        "content-type": "text/html; charset=utf-8",
+      });
+      endWith(req, res, html(game));
+      return Promise.resolve();
+    }
+    if (pathname === RELOAD) {
+      reloads.listen(res);
+      return Promise.resolve();
+    }
+    if (pathname === HOST) {
+      return remote
+        .get("host")
+        .then((file) => {
+          onRemote("host", file);
+          if (!file) {
+            res.writeHead(502, HEADERS).end();
+            return;
+          }
+          res.writeHead(200, {
+            ...HEADERS,
+            "content-type": "text/javascript; charset=utf-8",
+          });
+          endWith(req, res, file.body);
+        })
+        .catch((ex) => {
+          onRemote("host", null, ex);
+          res.writeHead(502, HEADERS).end();
+        });
+    }
+    res.writeHead(404, {
+      ...HEADERS,
+      "content-type": "text/plain; charset=utf-8",
+    });
+    res.end("Not Found\n");
+    return Promise.resolve();
+  };
+};
+
+// [export]
+
+module.exports = { ALLOW, SANDBOX, html, pageHandler };

package/src/serve/reload.js

@@ -0,0 +1,63 @@
+"use strict";
+// reloading the game when its files change: a watch on the folder served,
+// which waits for the changes to settle, so a build that writes many files
+// reloads once, and the pages listening, told over server-sent events.
+
+// [import]
+
+const fs = require("node:fs");
+
+// [declare]
+
+// how long the folder must be still before the game reloads, in ms.
+const SETTLE = 100;
+
+// [function]
+
+// the pages listening for a reload. `listen(res)` keeps a response open as
+// an event stream; `reload()` tells every one; `close()` ends them.
+const reloader = function () {
+  const listening = new Set();
+  return {
+    close() {
+      for (const res of listening) {
+        res.end();
+      }
+      listening.clear();
+    },
+    listen(res) {
+      res.writeHead(200, {
+        "cache-control": "no-store",
+        "content-type": "text/event-stream",
+      });
+      res.write(": listening\n\n");
+      listening.add(res);
+      res.on("close", () => listening.delete(res));
+    },
+    reload() {
+      for (const res of listening) {
+        res.write("event: reload\ndata: \n\n");
+      }
+    },
+  };
+};
+
+// [function]
+
+// calls `onChange` once `dir` has stopped changing for SETTLE ms. Returns a
+// function that stops watching.
+const watchDir = function (dir, onChange) {
+  let timer = null;
+  const watcher = fs.watch(dir, { recursive: true }, () => {
+    clearTimeout(timer);
+    timer = setTimeout(onChange, SETTLE);
+  });
+  return () => {
+    clearTimeout(timer);
+    watcher.close();
+  };
+};
+
+// [export]
+
+module.exports = { SETTLE, reloader, watchDir };

package/src/serve/remote.js

@@ -0,0 +1,119 @@
+"use strict";
+// the files Arcadible serves itself, fetched from where Arcadible serves
+// them, so a fix reaches `arc serve` without a new CLI: the SDK's hosted
+// script, as every game's origin serves it at /arcadible/sdk/, and the play
+// page's host, as the play page runs it. Each is fetched once a session, and
+// the last copy is kept on disk for when Arcadible can't be reached.
+
+// [import]
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// [use]
+
+const join = path.join;
+const mkdir = fs.promises.mkdir;
+const readFile = fs.promises.readFile;
+const writeFile = fs.promises.writeFile;
+
+// [declare]
+
+// the play page's host, published with each web deploy beside the asset
+// site's other vendored files. Any number in /static/<n>/ is served, and each
+// is cached at Google's edge for a year, so a new one gets the current copy.
+const HOST_PATH = "/asset/arcadible/vnd/arcadible-sdk/host.min.js";
+// the files under /arcadible/ that Arcadible serves: the SDK's, such as
+// sdk/v1.js. Anything else there isn't found, as on Arcadible.
+const SDK_PATH = /^sdk\/[\w.-]+$/u;
+
+// [function]
+
+// a file kept from a fetch, or null.
+const readKept = async function (dir, name) {
+  try {
+    const [body, meta] = await Promise.all([
+      readFile(join(dir, name)),
+      readFile(join(dir, `${name}.json`), "utf8"),
+    ]);
+    return { ...JSON.parse(meta), body };
+  } catch (ex) {
+    return null;
+  }
+};
+
+// [function]
+
+// keeps `file` for later; a copy that can't be written is only skipped.
+const keep = async function (dir, name, { body, ...meta }) {
+  try {
+    await mkdir(dir, { recursive: true });
+    await Promise.all([
+      writeFile(join(dir, name), body),
+      writeFile(join(dir, `${name}.json`), JSON.stringify(meta)),
+    ]);
+  } catch (ex) {
+    // the copy is a convenience: serving goes on without it.
+  }
+};
+
+// [function]
+
+// the files from Arcadible. `asset` is the asset site's origin, `sdk` an
+// origin that serves /arcadible/sdk/, and `dir` where copies are kept.
+// `get(name)` resolves with `{ body, type, fetchedAt, kept }`, where `kept`
+// says the copy is from disk because Arcadible couldn't be reached, or null
+// when Arcadible has no such file; it rejects when Arcadible can't be reached
+// and there's no copy. `name` is `host`, or a path under /arcadible/.
+const remoteFiles = function ({ asset, dir, request = fetch, sdk }) {
+  const session = {};
+  const url = function (name) {
+    if (name === "host") {
+      return `${asset}/static/${Date.now()}${HOST_PATH}`;
+    }
+    return SDK_PATH.test(name) ? `${sdk}/arcadible/${name}` : null;
+  };
+  const load = async function (name) {
+    const target = url(name);
+    if (!target) {
+      return null;
+    }
+    const kept = name.replaceAll("/", "-");
+    try {
+      const res = await request(target);
+      if (res.status === 403 || res.status === 404) {
+        return null;
+      }
+      if (!res.ok) {
+        throw new Error(`${res.status}`);
+      }
+      const file = {
+        body: Buffer.from(await res.arrayBuffer()),
+        fetchedAt: new Date().toISOString(),
+        type: res.headers.get("content-type") ?? "text/javascript",
+      };
+      await keep(dir, kept, file);
+      return { ...file, kept: false };
+    } catch (ex) {
+      const file = await readKept(dir, kept);
+      if (!file) {
+        throw ex;
+      }
+      return { ...file, kept: true };
+    }
+  };
+  return {
+    get(name) {
+      if (!Object.hasOwn(session, name)) {
+        // a failure isn't kept, so the next request tries again.
+        session[name] = load(name);
+        session[name].catch(() => delete session[name]);
+      }
+      return session[name];
+    },
+  };
+};
+
+// [export]
+
+module.exports = { remoteFiles };

package/src/serve/server.js

@@ -0,0 +1,115 @@
+"use strict";
+// arc serve's server: a local play page and the game it frames, on one port
+// and two origins, as on Arcadible, where the play page and each build have
+// origins of their own. http://localhost:<port> is the page, and
+// http://127.0.0.1:<port> the game. It listens on loopback only, and needs
+// nothing from the CLI, so another app can run a game this way too.
+
+// [import]
+
+const http = require("node:http");
+
+// [import]
+
+const game = require("./game");
+const page = require("./page");
+const reload = require("./reload");
+
+// [use]
+
+const gameHandler = game.gameHandler;
+const pageHandler = page.pageHandler;
+const reloader = reload.reloader;
+
+// [declare]
+
+// the hostnames a browser may use for the page, on IPv4 and IPv6. `localhost`
+// is IPv6's ::1 on some systems, so both are listened on.
+const LOOPBACK = ["127.0.0.1", "::1"];
+
+// [function]
+
+// listens on `port` at `address`, resolving with the server, or rejecting with
+// the listen error, such as EADDRINUSE.
+const listen = function (handler, port, address) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(handler);
+    server.once("error", reject);
+    server.listen(port, address, () => {
+      server.off("error", reject);
+      resolve(server);
+    });
+  });
+};
+
+// [function]
+
+// starts serving `files` for `info`, `{ id, channel, version, title }`, on
+// `port`, with Arcadible's own files from `remote`. With `src`, another
+// server's page, it frames that instead, and serves no files. Resolves with
+// `{ page, game, reload(), close() }`: the page's origin, the game's URL,
+// and the controls.
+const serve = async function ({ files, info, onRemote, port, remote, src }) {
+  const origins = {
+    game: `http://127.0.0.1:${port}`,
+    page: `http://localhost:${port}`,
+  };
+  const framed = src ?? `${origins.game}/`;
+  const reloads = reloader();
+  const forGame = files
+    ? gameHandler({ files, onRemote, page: origins.page, remote })
+    : null;
+  const forPage = pageHandler({
+    game: { ...info, src: framed },
+    onRemote,
+    reloads,
+    remote,
+  });
+  // the Host header picks the origin; anything else is refused, so a page
+  // elsewhere can't reach the game's files by another name (DNS rebinding).
+  const handler = function (req, res) {
+    const host = req.headers.host;
+    const pick = {
+      [`127.0.0.1:${port}`]: forGame,
+      [`localhost:${port}`]: forPage,
+    }[host];
+    if (!pick) {
+      res.writeHead(421, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Misdirected Request\n");
+      return;
+    }
+    pick(req, res).catch(() => {
+      if (!res.headersSent) {
+        res.writeHead(500);
+      }
+      res.end();
+    });
+  };
+  const ipv4 = await listen(handler, port, LOOPBACK[0]);
+  // the IPv6 loopback is a bonus: a system without it still has 127.0.0.1.
+  let ipv6 = null;
+  try {
+    ipv6 = await listen(handler, port, LOOPBACK[1]);
+  } catch (ex) {
+    if (ex.code === "EADDRINUSE") {
+      ipv4.close();
+      throw ex;
+    }
+  }
+  return {
+    close() {
+      reloads.close();
+      for (const server of [ipv4, ipv6].filter(Boolean)) {
+        server.closeAllConnections();
+        server.close();
+      }
+    },
+    game: framed,
+    page: origins.page,
+    reload: reloads.reload,
+  };
+};
+
+// [export]
+
+module.exports = { serve };