@crowdedkingdoms/construct 0.3.11-test.1 → 0.4.0-dev.1

package/node/live-draft.test.mjs

@@ -0,0 +1,273 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import test from 'node:test';
+
+import { CheckoutDraft, gitBlobSha, isRepoPath, liveDraftPlugin } from './live-draft.mjs';
+
+function git(cwd, ...args) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 't',
+      GIT_AUTHOR_EMAIL: 't@t',
+      GIT_COMMITTER_NAME: 't',
+      GIT_COMMITTER_EMAIL: 't@t',
+    },
+  }).trim();
+}
+
+/** A bare origin and a clone of it with one commit. */
+function checkout() {
+  const dir = mkdtempSync(path.join(tmpdir(), 'live-draft-'));
+  const origin = path.join(dir, 'origin.git');
+  const work = path.join(dir, 'work');
+  git(dir, 'init', '--quiet', '--bare', '-b', 'main', origin);
+  git(dir, 'clone', '--quiet', origin, work);
+  mkdirSync(path.join(work, 'src/game'), { recursive: true });
+  writeFileSync(path.join(work, 'src/game/content.ts'), 'export default 1;\n');
+  writeFileSync(path.join(work, 'README.md'), '# Game\n');
+  writeFileSync(path.join(work, '.gitignore'), 'dist/\n');
+  git(work, 'add', '.');
+  git(work, 'commit', '--quiet', '-m', 'first');
+  git(work, 'push', '--quiet', 'origin', 'HEAD:main');
+  return { dir, origin, work, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+test('the editor sees repository files only, by the same policy as CrowdyJS', () => {
+  assert.equal(isRepoPath('src/scenes/race/RaceScene.ts'), true);
+  assert.equal(isRepoPath('src/.eslintrc.json'), true);
+  for (const refused of [
+    '.github/dependabot.yml',
+    '.gitignore',
+    '.github/workflows/ci.yml',
+    '.git/config',
+    'node_modules/x/index.js',
+    'src/.env',
+    '.env.local',
+    '../x',
+    'src/../x',
+    '/etc/passwd',
+    'a//b',
+  ]) {
+    assert.equal(isRepoPath(refused), false, refused);
+  }
+});
+
+test('lists what git would commit, dirty against HEAD, with blob ids', async (t) => {
+  const repo = checkout();
+  t.after(repo.cleanup);
+  const draft = new CheckoutDraft(repo.work);
+  mkdirSync(path.join(repo.work, 'dist'));
+  writeFileSync(path.join(repo.work, 'dist/bundle.js'), 'ignored');
+  writeFileSync(path.join(repo.work, 'src/new.ts'), 'export {};\n');
+  rmSync(path.join(repo.work, 'README.md'));
+  const tree = await draft.tree();
+  assert.equal(tree.baseCommitSha, git(repo.work, 'rev-parse', 'HEAD'));
+  const paths = tree.entries.map((entry) => entry.path);
+  assert.deepEqual(paths, ['src/game/content.ts', 'src/new.ts']);
+  assert.deepEqual(tree.deleted, ['README.md']);
+  const content = tree.entries.find((entry) => entry.path === 'src/game/content.ts');
+  assert.equal(content.hash, git(repo.work, 'hash-object', 'src/game/content.ts'));
+  assert.equal(content.dirty, false);
+  assert.equal(tree.entries.find((entry) => entry.path === 'src/new.ts').dirty, true);
+});
+
+test('writes keep their preconditions, and the dirty set shrinks again', async (t) => {
+  const repo = checkout();
+  t.after(repo.cleanup);
+  const draft = new CheckoutDraft(repo.work);
+  const original = readFileSync(path.join(repo.work, 'src/game/content.ts'));
+  await assert.rejects(draft.write('src/game/content.ts', 'x', { kind: 'createIfAbsent' }), {
+    code: 'DRAFT_STALE',
+  });
+  await assert.rejects(
+    draft.write('src/game/content.ts', 'x', { kind: 'ifHash', hash: 'f'.repeat(40) }),
+    { code: 'DRAFT_STALE' },
+  );
+  const written = await draft.write('src/game/content.ts', 'export default 2;\n', {
+    kind: 'ifHash',
+    hash: gitBlobSha(original),
+  });
+  assert.equal(written.previousHash, gitBlobSha(original));
+  assert.equal(written.revision, 1);
+  assert.equal(
+    (await draft.tree()).entries.find((entry) => entry.path === 'src/game/content.ts').dirty,
+    true,
+  );
+  const restored = await draft.write('src/game/content.ts', original.toString('utf8'));
+  assert.equal(restored.dirty, false);
+  assert.equal(
+    (await draft.tree()).entries.find((entry) => entry.path === 'src/game/content.ts').dirty,
+    false,
+  );
+  await assert.rejects(draft.write('.github/workflows/ci.yml', 'on: push'), {
+    code: 'DRAFT_PATH_REFUSED',
+  });
+});
+
+test('discard puts files back as HEAD has them and drops new ones', async (t) => {
+  const repo = checkout();
+  t.after(repo.cleanup);
+  const draft = new CheckoutDraft(repo.work);
+  await draft.write('src/game/content.ts', 'changed');
+  await draft.write('src/new.ts', 'new');
+  const removed = await draft.remove('README.md');
+  assert.equal(removed.inHead, true);
+  const result = await draft.discard();
+  assert.deepEqual(result.discarded.sort(), ['README.md', 'src/game/content.ts', 'src/new.ts']);
+  const tree = await draft.tree();
+  assert.equal(
+    tree.entries.some((entry) => entry.dirty),
+    false,
+  );
+  assert.deepEqual(tree.deleted, []);
+  assert.equal(readFileSync(path.join(repo.work, 'README.md'), 'utf8'), '# Game\n');
+});
+
+test('reads in batches, and says which files are missing or binary', async (t) => {
+  const repo = checkout();
+  t.after(repo.cleanup);
+  writeFileSync(path.join(repo.work, 'logo.png'), Buffer.from([0x89, 0x50, 0x00, 0x01]));
+  const draft = new CheckoutDraft(repo.work);
+  const result = await draft.read(['README.md', 'logo.png', 'nope.ts', '../outside']);
+  assert.deepEqual(
+    result.files.map((file) => file.path),
+    ['README.md'],
+  );
+  assert.deepEqual(result.binary, ['logo.png']);
+  assert.deepEqual(result.missing, ['nope.ts', '../outside']);
+});
+
+test('after a commit made elsewhere, sync fast-forwards HEAD and leaves the files alone', async (t) => {
+  const repo = checkout();
+  t.after(repo.cleanup);
+  const draft = new CheckoutDraft(repo.work);
+  await draft.write('src/game/content.ts', 'export default 3;\n');
+  await draft.write('src/other.ts', 'export const later = true;\n');
+  // Studio commits content.ts alone, through GitHub: model that with another clone.
+  const elsewhere = path.join(repo.dir, 'elsewhere');
+  git(repo.dir, 'clone', '--quiet', repo.origin, elsewhere);
+  writeFileSync(path.join(elsewhere, 'src/game/content.ts'), 'export default 3;\n');
+  git(elsewhere, 'commit', '--quiet', '-am', 'from studio');
+  git(elsewhere, 'push', '--quiet', 'origin', 'HEAD:main');
+  const commitSha = git(elsewhere, 'rev-parse', 'HEAD');
+  const synced = await draft.sync(commitSha);
+  assert.equal(synced.baseCommitSha, commitSha);
+  assert.equal(git(repo.work, 'rev-parse', 'HEAD'), commitSha);
+  const tree = await draft.tree();
+  assert.equal(tree.entries.find((entry) => entry.path === 'src/game/content.ts').dirty, false);
+  assert.equal(tree.entries.find((entry) => entry.path === 'src/other.ts').dirty, true);
+  assert.equal(
+    readFileSync(path.join(repo.work, 'src/other.ts'), 'utf8'),
+    'export const later = true;\n',
+  );
+});
+
+/** The plugin's middleware with a fake Vite server around it. */
+function middlewareFor(root) {
+  const plugin = liveDraftPlugin({ root, enabled: true });
+  plugin.configResolved({ root });
+  const [meta] = plugin.transformIndexHtml();
+  const sent = [];
+  let middleware;
+  plugin.configureServer({
+    config: { base: '/', logger: { info() {} } },
+    watcher: { on() {} },
+    ws: { send: (message) => sent.push(message) },
+    middlewares: { use: (fn) => (middleware = fn) },
+  });
+  const call = (method, url, { headers = {}, body, remote = '127.0.0.1' } = {}) =>
+    new Promise((resolve) => {
+      const req = Readable.from(body === undefined ? [] : [Buffer.from(JSON.stringify(body))]);
+      Object.assign(req, {
+        method,
+        url,
+        headers: { host: 'localhost:5175', ...headers },
+        socket: { remoteAddress: remote },
+      });
+      const res = {
+        statusCode: 200,
+        headers: {},
+        setHeader(name, value) {
+          this.headers[name.toLowerCase()] = value;
+        },
+        end(payload) {
+          resolve({ status: this.statusCode, body: JSON.parse(payload) });
+        },
+      };
+      void middleware(req, res, () => resolve({ status: 'next' }));
+    });
+  return { token: meta.attrs.content, call, sent };
+}
+
+test('the middleware answers only its own page, with the token, in JSON', async (t) => {
+  const repo = checkout();
+  t.after(repo.cleanup);
+  const { token, call, sent } = middlewareFor(repo.work);
+  const own = { 'sec-fetch-site': 'same-origin', 'x-construct-draft-token': token };
+  const json = { ...own, 'content-type': 'application/json' };
+  const write = { path: 'README.md', content: 'pwned' };
+
+  assert.equal(
+    (
+      await call('POST', '/__live-draft/write', {
+        headers: {
+          'sec-fetch-site': 'cross-site',
+          'x-construct-draft-token': token,
+          'content-type': 'application/json',
+        },
+        body: write,
+      })
+    ).status,
+    403,
+  );
+  assert.equal(
+    (
+      await call('POST', '/__live-draft/write', {
+        headers: {
+          origin: 'http://evil.example',
+          'x-construct-draft-token': token,
+          'content-type': 'application/json',
+        },
+        body: write,
+      })
+    ).status,
+    403,
+  );
+  assert.equal(
+    (
+      await call('POST', '/__live-draft/write', {
+        headers: { 'sec-fetch-site': 'same-origin', 'content-type': 'application/json' },
+        body: write,
+      })
+    ).status,
+    403,
+  );
+  assert.equal(
+    (
+      await call('POST', '/__live-draft/write', {
+        headers: { ...own, 'content-type': 'text/plain' },
+        body: write,
+      })
+    ).status,
+    415,
+  );
+  assert.equal(readFileSync(path.join(repo.work, 'README.md'), 'utf8'), '# Game\n');
+
+  const tree = await call('GET', '/__live-draft/tree', { headers: own });
+  assert.equal(tree.status, 200);
+  const written = await call('POST', '/__live-draft/write', {
+    headers: json,
+    body: { ...write, source: 'agent', writer: 'tab-1' },
+  });
+  assert.equal(written.status, 200);
+  assert.equal(sent.at(-1).data.source, 'agent');
+  assert.equal(sent.at(-1).data.writer, 'tab-1');
+  assert.equal((await call('GET', '/elsewhere')).status, 'next');
+});

package/node/vite-plugins.d.mts

@@ -4,3 +4,14 @@ export function constructHeaderPlugins(options: {
   dshHeaders?: Record<string, string>;
   gridProgramHeaders?: Record<string, string>;
 }): Plugin[];
+
+/**
+ * Crowdy Studio's hosted game-editor preview: the `virtual:construct-draft-host`
+ * registry and the `construct-draft-sw.js` service worker.
+ */
+export function constructDraftPlugin(options?: {
+  /** Game directories whose imports a draft may reuse (default `src`, `model`). */
+  sourceRoots?: string[];
+  /** More module specifiers a draft may import from the page. */
+  extraModules?: string[];
+}): Plugin;

package/node/vite-plugins.mjs

@@ -1,10 +1,15 @@
 /**
  * Vite plugins every Construct game needs: path-scoped security headers for
  * the two same-origin pages the game frames, the in-browser DeepSeek Harness
- * (`/dsh/*`) and the JS grid program sandbox (`/grid-program.html`). The site
- * headers (securityHeaders) are applied by Vite's `server.headers`; these
- * override them for their own paths.
+ * (`/dsh/*`) and the JS grid program sandbox (`/grid-program.html`), and the
+ * hosted preview of Crowdy Studio's game editor (`constructDraftPlugin`). The
+ * site headers (securityHeaders) are applied by Vite's `server.headers`; the
+ * header plugins override them for their own paths.
  */
+import { readdir, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /**
  * @param {string} name
@@ -15,8 +20,12 @@
 function pathHeadersPlugin(name, match, headers, options = {}) {
   /** @param {import('vite').ViteDevServer | import('vite').PreviewServer} server */
   const attach = (server) => {
+    // Matched against the path under the game's base, so `vite build --base /game/`
+    // previews `/game/dsh/` with the harness's headers.
+    const base = server.config?.base ?? '/';
     server.middlewares.use((req, res, next) => {
-      const pathname = (req.url ?? '').split('?')[0] ?? '';
+      const raw = (req.url ?? '').split('?')[0] ?? '';
+      const pathname = base !== '/' && raw.startsWith(base) ? `/${raw.slice(base.length)}` : raw;
       if (match(pathname)) {
         // The harness's packed VFS image is a .tar.gz its worker inflates with
         // DecompressionStream. Vite's static server adds `Content-Encoding: gzip`
@@ -25,11 +34,17 @@ function pathHeadersPlugin(name, match, headers, options = {}) {
         const isGzipArchive = options.keepGzipArchives && /\.gz$/i.test(pathname);
         const origSetHeader = res.setHeader.bind(res);
         res.setHeader = (header, value) => {
-          if (isGzipArchive && header.toLowerCase() === 'content-encoding') return res;
+          const lower = header.toLowerCase();
+          if (isGzipArchive && lower === 'content-encoding') return res;
+          // Its own type, so `vite preview`'s compression (which takes an untyped body
+          // for text/plain) leaves the archive alone instead of gzipping it twice.
+          if (isGzipArchive && lower === 'content-type')
+            return origSetHeader(header, 'application/gzip');
           const pinned = headers[header];
           return origSetHeader(header, pinned !== undefined ? pinned : value);
         };
         for (const [header, value] of Object.entries(headers)) origSetHeader(header, value);
+        if (isGzipArchive) origSetHeader('Content-Type', 'application/gzip');
       }
       next();
     });
@@ -100,3 +115,184 @@ export function constructHeaderPlugins({ dshHeaders, gridProgramHeaders }) {
   }
   return plugins;
 }
+
+const DRAFT_HOST_MODULES = 'virtual:construct-draft-host';
+const DRAFT_WORKER_FILE = 'construct-draft-sw.js';
+const FRAMEWORK = '@crowdedkingdoms/construct';
+const FRAMEWORK_SRC = fileURLToPath(new URL('../src/', import.meta.url));
+const DRAFT_WORKER_ENTRY = fileURLToPath(
+  new URL('../src/platform/live/draftServiceWorker.ts', import.meta.url),
+);
+/**
+ * The game editor's own machinery (the loader, the worker, the transform, the
+ * dev-server store) is not for drafts; `platform/live/content` is the contract
+ * a game's content imports.
+ */
+const forDrafts = (rel) => !rel.startsWith('platform/live/') || rel === 'platform/live/content';
+const SOURCE_FILE = /\.(ts|tsx|mts|js|mjs)$/;
+/** A bare module specifier as npm and the framework spell them. */
+const MODULE_SPECIFIER = /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*(\/[\w.-]+)*$/i;
+
+/** A JavaScript string literal for `value`, safe to splice into generated code. */
+function jsString(value) {
+  return JSON.stringify(value).replace(
+    /[<>/\u2028\u2029]/g,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`,
+  );
+}
+const TEST_FILE = /\.test\.(ts|tsx|mts|js|mjs)$/;
+
+/** @param {string} dir @returns {Promise<string[]>} */
+async function walk(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...(await walk(full)));
+    else files.push(full);
+  }
+  return files;
+}
+
+/** Every public framework module, as the specifier a game writes. */
+async function frameworkModules() {
+  const out = [];
+  for (const area of ['engine', 'platform', 'grid']) {
+    for (const file of await walk(path.join(FRAMEWORK_SRC, area))) {
+      if (!file.endsWith('.ts') || file.endsWith('.d.ts') || TEST_FILE.test(file)) continue;
+      const rel = path.relative(FRAMEWORK_SRC, file).split(path.sep).join('/').replace(/\.ts$/, '');
+      if (forDrafts(rel)) out.push(`${FRAMEWORK}/${rel}`);
+    }
+  }
+  return out;
+}
+
+/** Bare imports in the game's content sources (relative, alias and virtual ones excluded). */
+async function packageImports(root, sourceRoots) {
+  const require = createRequire(import.meta.url);
+  const { transform } = require('sucrase');
+  const { init, parse } = await import('es-module-lexer');
+  await init;
+  const found = new Set();
+  for (const sourceRoot of sourceRoots) {
+    for (const file of await walk(path.resolve(root, sourceRoot))) {
+      if (!SOURCE_FILE.test(file) || TEST_FILE.test(file)) continue;
+      let code = await readFile(file, 'utf8');
+      if (/\.(ts|tsx|mts)$/.test(file)) {
+        code = transform(code, {
+          transforms: file.endsWith('.tsx') ? ['typescript', 'jsx'] : ['typescript'],
+          disableESTransforms: true,
+          preserveDynamicImport: true,
+        }).code;
+      }
+      let imports;
+      try {
+        [imports] = parse(code, file);
+      } catch {
+        continue;
+      }
+      for (const { n } of imports) {
+        if (!n || /^(\.|\/|@\/|\0|virtual:|node:|https?:|data:)/.test(n)) continue;
+        found.add(n);
+      }
+    }
+  }
+  return [...found];
+}
+
+/** The draft service worker as one classic script (no module service worker needed). */
+async function bundleDraftWorker() {
+  const { build } = await import('vite');
+  const result = await build({
+    configFile: false,
+    logLevel: 'warn',
+    root: path.dirname(DRAFT_WORKER_ENTRY),
+    define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+    build: {
+      write: false,
+      minify: true,
+      sourcemap: false,
+      emptyOutDir: false,
+      copyPublicDir: false,
+      lib: {
+        entry: DRAFT_WORKER_ENTRY,
+        formats: ['iife'],
+        name: 'ConstructDraftWorker',
+        fileName: () => DRAFT_WORKER_FILE,
+      },
+    },
+  });
+  const outputs = (Array.isArray(result) ? result : [result]).flatMap(
+    (output) => output.output ?? [],
+  );
+  const chunk = outputs.find((file) => file.type === 'chunk');
+  if (!chunk) throw new Error('constructDraftPlugin: the draft service worker bundle is empty');
+  return chunk.code;
+}
+
+/**
+ * Crowdy Studio's hosted game-editor preview (`platform/live/draftLoader.ts`):
+ * - `virtual:construct-draft-host`, a lazy registry of what a draft module may
+ *   import from the page: every public framework module, every package the
+ *   game's content sources import (`sourceRoots`, default `src` and `model`),
+ *   and `extraModules`;
+ * - `construct-draft-sw.js`, the draft service worker, next to index.html in
+ *   the build and on the dev server.
+ *
+ * @param {{ sourceRoots?: string[], extraModules?: string[] }} [options]
+ * @returns {import('vite').Plugin}
+ */
+export function constructDraftPlugin(options = {}) {
+  const resolvedId = `\0${DRAFT_HOST_MODULES}`;
+  /** @type {import('vite').ResolvedConfig | undefined} */
+  let config;
+  /** @type {Promise<string> | null} */
+  let worker = null;
+  const workerCode = () => (worker ??= bundleDraftWorker());
+  return {
+    name: 'construct-draft',
+    configResolved(resolved) {
+      config = resolved;
+    },
+    resolveId(id) {
+      return id === DRAFT_HOST_MODULES ? resolvedId : undefined;
+    },
+    async load(id) {
+      if (id !== resolvedId || !config) return undefined;
+      const specifiers = new Set([
+        ...(await frameworkModules()),
+        ...(await packageImports(config.root, options.sourceRoots ?? ['src', 'model'])),
+        ...(options.extraModules ?? []),
+      ]);
+      const rows = [...specifiers]
+        .filter((specifier) => MODULE_SPECIFIER.test(specifier))
+        .sort()
+        .map((specifier) => `  ${jsString(specifier)}: () => import(${jsString(specifier)}),`);
+      return `export default {\n${rows.join('\n')}\n};\n`;
+    },
+    async generateBundle() {
+      if (config?.command !== 'build') return;
+      this.emitFile({ type: 'asset', fileName: DRAFT_WORKER_FILE, source: await workerCode() });
+    },
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const pathname = (req.url ?? '').split('?')[0] ?? '';
+        if (pathname !== `${server.config.base}${DRAFT_WORKER_FILE}`) return next();
+        workerCode().then(
+          (code) => {
+            res.setHeader('Content-Type', 'text/javascript; charset=utf-8');
+            res.setHeader('Cache-Control', 'no-store');
+            res.end(code);
+          },
+          (error) => next(error),
+        );
+      });
+    },
+  };
+}

package/node/vite-plugins.test.mjs

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { constructHeaderPlugins } from './vite-plugins.mjs';
+
+test('the harness headers follow the game under a Vite base', () => {
+  const [plugin] = constructHeaderPlugins({
+    dshHeaders: { 'Content-Security-Policy': "frame-ancestors 'self'" },
+  });
+  for (const [base, url, harness] of [
+    ['/the-construct/', '/the-construct/dsh/index.html', true],
+    ['/', '/dsh/index.html', true],
+    ['/the-construct/', '/the-construct/index.html', false],
+  ]) {
+    let middleware;
+    plugin.configurePreviewServer({
+      config: { base },
+      middlewares: { use: (fn) => (middleware = fn) },
+    });
+    const set = {};
+    const res = {
+      setHeader(name, value) {
+        set[name] = value;
+        return res;
+      },
+    };
+    middleware({ url }, res, () => {});
+    assert.equal('Content-Security-Policy' in set, harness, `${base} ${url}`);
+  }
+});
+
+test('the packed harness image reaches the worker as stored: typed, never re-encoded', () => {
+  const [plugin] = constructHeaderPlugins({ dshHeaders: {} });
+  let middleware;
+  plugin.configurePreviewServer({
+    config: { base: '/game/' },
+    middlewares: { use: (fn) => (middleware = fn) },
+  });
+  const set = {};
+  const res = {
+    setHeader(name, value) {
+      set[name.toLowerCase()] = value;
+      return res;
+    },
+  };
+  middleware({ url: '/game/dsh/preview/vfs-image.tar.gz' }, res, () => {});
+  res.setHeader('Content-Type', '');
+  res.setHeader('Content-Encoding', 'gzip');
+  assert.equal(set['content-type'], 'application/gzip');
+  assert.equal('content-encoding' in set, false);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/construct",
-  "version": "0.3.11-test.1",
+  "version": "0.4.0-dev.1",
   "description": "The Construct framework: the Crowded Kingdoms game platform layer (hosted sign-in, World Stores, voice/webcam/chat, Crowdy Studio dock, app and grid mods, grid programs) and engine loop, shared by the-construct starter and the games built on it. Ships TypeScript source for Vite.",
   "license": "MIT",
   "type": "module",
@@ -39,18 +39,26 @@
       "types": "./node/vite-plugins.d.mts",
       "default": "./node/vite-plugins.mjs"
     },
+    "./node/live-draft": {
+      "types": "./node/live-draft.d.mts",
+      "default": "./node/live-draft.mjs"
+    },
     "./sandbox/boot": "./sandbox/boot.ts",
     "./engine/*": "./src/engine/*.ts",
     "./platform/*": "./src/platform/*.ts",
     "./grid/*": "./src/grid/*.ts"
   },
   "peerDependencies": {
-    "@crowdedkingdoms/crowdyjs": ">=18.0.4-dev.0 <19 || >=18.1.0-dev.0 <19 || >=18.2.0-dev.0 <19 || >=18.3.0-dev.0 <19 || >=18.4.0-dev.0 <19",
-    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1 || >=0.4.3-dev.0 <1 || >=0.4.4-dev.0 <1 || >=0.4.5-dev.0 <1"
+    "@crowdedkingdoms/crowdy-dsh": ">=0.4.0-dev.0 <1 || >=0.4.1-dev.0 <1 || >=0.4.2-dev.0 <1 || >=0.4.3-dev.0 <1 || >=0.4.4-dev.0 <1 || >=0.4.5-dev.0 <1 || >=0.5.0-dev.0 <1",
+    "@crowdedkingdoms/crowdyjs": ">=18.23.0-dev.0 <19"
   },
   "peerDependenciesMeta": {
     "@crowdedkingdoms/crowdy-dsh": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "es-module-lexer": "^2.3.2",
+    "sucrase": "^3.35.1"
   }
 }

package/src/engine/SceneRouter.test.ts

@@ -77,4 +77,18 @@ describe('SceneRouter', () => {
     router.bind(context, size);
     await expect(router.load('nope')).rejects.toThrow(/No scene registered/);
   });
+
+  it('replaces every factory, so the next load after dispose builds the new content', async () => {
+    const router = new SceneRouter();
+    router.bind(context, size);
+    router.register('hub', () => fakeScene('hub', 0));
+    router.register('paint', () => fakeScene('paint', 1));
+    await router.load('hub');
+    const fresh = fakeScene('hub', 0);
+    router.replace({ hub: () => fresh, race: () => fakeScene('race', 2) });
+    expect(router.ids().sort()).toEqual(['hub', 'race']);
+    router.dispose();
+    expect(await router.load('hub')).toBe(fresh);
+    await expect(router.load('paint')).rejects.toThrow(/No scene registered as "paint"/);
+  });
 });

package/src/engine/SceneRouter.ts

@@ -26,6 +26,16 @@ export class SceneRouter {
     this.factories.set(id, factory);
   }
 
+  /**
+   * Swap every factory for a new set, e.g. when the game's content changed.
+   * Mounted and cached scenes stay until `dispose()`; the next `load()` then
+   * builds from the new factories.
+   */
+  replace(factories: Readonly<Record<string, SceneFactory>>): void {
+    this.factories.clear();
+    for (const [id, factory] of Object.entries(factories)) this.factories.set(id, factory);
+  }
+
   ids(): string[] {
     return [...this.factories.keys()];
   }

package/src/platform/exec/worldHub.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 
-import { WorldHub, configureWorldHub, worldHubAddress } from './worldHub';
+import { WorldHub, configureWorldHub, localWorldHubReply, worldHubAddress } from './worldHub';
 
 function fakeClient(connectResults: Array<'fail' | 'ok'> = ['ok']) {
   const connection = {
@@ -16,6 +16,15 @@ function fakeClient(connectResults: Array<'fail' | 'ok'> = ['ok']) {
   return { client: { exec } as never, exec, connection };
 }
 
+describe('local world hub mock', () => {
+  it('answers the reads the page polls without a hub', () => {
+    expect(localWorldHubReply('world')).toEqual({ pulses: 0 });
+    expect(localWorldHubReply('claims')).toEqual({ claims: [], total: 0 });
+    expect(localWorldHubReply('programs')).toEqual({ programs: [] });
+    expect(localWorldHubReply('status')).toMatchObject({ local: true });
+  });
+});
+
 describe('WorldHub', () => {
   it('opens one connection, on the host running the hub, for every call', async () => {
     const { client, exec, connection } = fakeClient();