@colyseus/playground 0.17.12 → 0.18.1

package/build/serve-static.mjs

@@ -0,0 +1,72 @@
+// src-backend/serve-static.ts
+import fs from "fs/promises";
+import path from "path";
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".map": "application/json; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8"
+};
+async function serveStatic(root, relPath) {
+  const safe = sanitize(relPath ?? "");
+  const filePath = safe ? path.join(root, safe) : path.join(root, "index.html");
+  const resolved = path.resolve(filePath);
+  const resolvedRoot = path.resolve(root);
+  if (!resolved.startsWith(resolvedRoot + path.sep) && resolved !== resolvedRoot) {
+    return new Response("forbidden", { status: 403 });
+  }
+  const data = await tryRead(resolved);
+  if (data) {
+    return fileResponse(data, mimeOf(resolved));
+  }
+  if (!path.extname(safe)) {
+    const index = await tryRead(path.join(resolvedRoot, "index.html"));
+    if (index) {
+      return fileResponse(index, "text/html; charset=utf-8");
+    }
+  }
+  return new Response("not found", { status: 404 });
+}
+function sanitize(p) {
+  return p.replace(/^\/+/, "").split("/").filter((seg) => seg && seg !== ".." && seg !== ".").join("/");
+}
+function mimeOf(filePath) {
+  return MIME[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+async function tryRead(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) {
+      return null;
+    }
+    return await fs.readFile(filePath);
+  } catch {
+    return null;
+  }
+}
+function fileResponse(buf, contentType) {
+  return new Response(new Uint8Array(buf), {
+    status: 200,
+    headers: {
+      "content-type": contentType,
+      "content-length": String(buf.length),
+      "cache-control": "no-cache",
+      "connection": "close"
+    }
+  });
+}
+export {
+  serveStatic
+};

package/build/serve-static.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src-backend/serve-static.ts"],
+  "sourcesContent": ["// Static-file helper for the built playground SPA. Mirrors the helper used by\n// @colyseus/admin (kept duplicated for now \u2014 both consumers are framework-owned\n// and the helper is small + stable).\nimport fs from 'fs/promises';\nimport path from 'path';\n\nconst MIME: Record<string, string> = {\n  '.html': 'text/html; charset=utf-8',\n  '.js':   'application/javascript; charset=utf-8',\n  '.mjs':  'application/javascript; charset=utf-8',\n  '.css':  'text/css; charset=utf-8',\n  '.json': 'application/json; charset=utf-8',\n  '.svg':  'image/svg+xml',\n  '.png':  'image/png',\n  '.jpg':  'image/jpeg',\n  '.jpeg': 'image/jpeg',\n  '.gif':  'image/gif',\n  '.ico':  'image/x-icon',\n  '.woff': 'font/woff',\n  '.woff2': 'font/woff2',\n  '.ttf':  'font/ttf',\n  '.map':  'application/json; charset=utf-8',\n  '.txt':  'text/plain; charset=utf-8',\n};\n\nexport async function serveStatic(root: string, relPath: string | undefined): Promise<Response> {\n  const safe = sanitize(relPath ?? '');\n  const filePath = safe ? path.join(root, safe) : path.join(root, 'index.html');\n\n  const resolved = path.resolve(filePath);\n  const resolvedRoot = path.resolve(root);\n  if (!resolved.startsWith(resolvedRoot + path.sep) && resolved !== resolvedRoot) {\n    return new Response('forbidden', { status: 403 });\n  }\n\n  const data = await tryRead(resolved);\n  if (data) { return fileResponse(data, mimeOf(resolved)); }\n\n  // SPA fallback \u2014 serve index.html for any non-asset request\n  if (!path.extname(safe)) {\n    const index = await tryRead(path.join(resolvedRoot, 'index.html'));\n    if (index) { return fileResponse(index, 'text/html; charset=utf-8'); }\n  }\n\n  return new Response('not found', { status: 404 });\n}\n\nfunction sanitize(p: string): string {\n  return p.replace(/^\\/+/, '').split('/').filter((seg) => seg && seg !== '..' && seg !== '.').join('/');\n}\n\nfunction mimeOf(filePath: string): string {\n  return MIME[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream';\n}\n\nasync function tryRead(filePath: string): Promise<Buffer | null> {\n  try {\n    const stat = await fs.stat(filePath);\n    if (!stat.isFile()) { return null; }\n    return await fs.readFile(filePath);\n  } catch {\n    return null;\n  }\n}\n\nfunction fileResponse(buf: Buffer, contentType: string): Response {\n  return new Response(new Uint8Array(buf) as any, {\n    status: 200,\n    headers: {\n      'content-type': contentType,\n      'content-length': String(buf.length),\n      'cache-control': 'no-cache',\n      'connection': 'close',\n    },\n  });\n}\n"],
+  "mappings": ";AAGA,OAAO,QAAQ;AACf,OAAO,UAAU;AAEjB,IAAM,OAA+B;AAAA,EACnC,SAAS;AAAA,EACT,OAAS;AAAA,EACT,QAAS;AAAA,EACT,QAAS;AAAA,EACT,SAAS;AAAA,EACT,QAAS;AAAA,EACT,QAAS;AAAA,EACT,QAAS;AAAA,EACT,SAAS;AAAA,EACT,QAAS;AAAA,EACT,QAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,QAAS;AAAA,EACT,QAAS;AAAA,EACT,QAAS;AACX;AAEA,eAAsB,YAAY,MAAc,SAAgD;AAC9F,QAAM,OAAO,SAAS,WAAW,EAAE;AACnC,QAAM,WAAW,OAAO,KAAK,KAAK,MAAM,IAAI,IAAI,KAAK,KAAK,MAAM,YAAY;AAE5E,QAAM,WAAW,KAAK,QAAQ,QAAQ;AACtC,QAAM,eAAe,KAAK,QAAQ,IAAI;AACtC,MAAI,CAAC,SAAS,WAAW,eAAe,KAAK,GAAG,KAAK,aAAa,cAAc;AAC9E,WAAO,IAAI,SAAS,aAAa,EAAE,QAAQ,IAAI,CAAC;AAAA,EAClD;AAEA,QAAM,OAAO,MAAM,QAAQ,QAAQ;AACnC,MAAI,MAAM;AAAE,WAAO,aAAa,MAAM,OAAO,QAAQ,CAAC;AAAA,EAAG;AAGzD,MAAI,CAAC,KAAK,QAAQ,IAAI,GAAG;AACvB,UAAM,QAAQ,MAAM,QAAQ,KAAK,KAAK,cAAc,YAAY,CAAC;AACjE,QAAI,OAAO;AAAE,aAAO,aAAa,OAAO,0BAA0B;AAAA,IAAG;AAAA,EACvE;AAEA,SAAO,IAAI,SAAS,aAAa,EAAE,QAAQ,IAAI,CAAC;AAClD;AAEA,SAAS,SAAS,GAAmB;AACnC,SAAO,EAAE,QAAQ,QAAQ,EAAE,EAAE,MAAM,GAAG,EAAE,OAAO,CAAC,QAAQ,OAAO,QAAQ,QAAQ,QAAQ,GAAG,EAAE,KAAK,GAAG;AACtG;AAEA,SAAS,OAAO,UAA0B;AACxC,SAAO,KAAK,KAAK,QAAQ,QAAQ,EAAE,YAAY,CAAC,KAAK;AACvD;AAEA,eAAe,QAAQ,UAA0C;AAC/D,MAAI;AACF,UAAM,OAAO,MAAM,GAAG,KAAK,QAAQ;AACnC,QAAI,CAAC,KAAK,OAAO,GAAG;AAAE,aAAO;AAAA,IAAM;AACnC,WAAO,MAAM,GAAG,SAAS,QAAQ;AAAA,EACnC,QAAE;AACA,WAAO;AAAA,EACT;AACF;AAEA,SAAS,aAAa,KAAa,aAA+B;AAChE,SAAO,IAAI,SAAS,IAAI,WAAW,GAAG,GAAU;AAAA,IAC9C,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,kBAAkB,OAAO,IAAI,MAAM;AAAA,MACnC,iBAAiB;AAAA,MACjB,cAAc;AAAA,IAChB;AAAA,EACF,CAAC;AACH;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/playground",
-  "version": "0.17.12",
+  "version": "0.18.1",
   "main": "./build/index.cjs",
   "module": "./build/index.mjs",
   "typings": "./build/index.d.ts",
@@ -23,12 +23,15 @@
     "src-backend"
   ],
   "peerDependencies": {
-    "express": ">=4.16.0",
+    "cpupro": "^0.7.0",
     "zod": "^4.1.12",
-    "@colyseus/auth": "^0.17.8",
-    "@colyseus/core": "^0.17.38"
+    "@colyseus/auth": "^0.18.1",
+    "@colyseus/core": "^0.18.1"
   },
   "peerDependenciesMeta": {
+    "cpupro": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
@@ -58,6 +61,7 @@
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vitejs/plugin-react": "^4.2.1",
     "autoprefixer": "^10.4.16",
+    "cpupro": "^0.7.0",
     "esbuild": "^0.17.19",
     "fast-glob": "^3.2.12",
     "jsoneditor": "^9.10.2",
@@ -71,19 +75,22 @@
     "react-transition-group": "^4.4.5",
     "react18-json-view": "^0.0.8",
     "tailwindcss": "^3.3.2",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vite": "^5.0.11",
     "vitest": "^1.1.3",
     "web-vitals": "^2.1.4",
-    "@colyseus/sdk": "^0.17.34"
+    "@colyseus/sdk": "^0.18.1"
   },
   "dependencies": {
     "@colyseus/better-call": "^1.3.1"
   },
+  "publishConfig": {
+    "tag": "next"
+  },
   "scripts": {
     "start": "vite",
     "build": "vite build && node build.mjs",
     "preview": "vite preview",
-    "test-todo": "vitest"
+    "test": "vitest run"
   }
 }

package/src-backend/colyseus.ext.ts

@@ -1,6 +1,14 @@
 import { Room, Client, ClientState, ClientPrivate, AuthContext } from '@colyseus/core';
 
+let __patched = false;
+
 export async function applyMonkeyPatch() {
+  // Idempotent: playground() may be invoked multiple times (e.g. once for
+  // createRouter spread, once for the express middleware) — stacking
+  // _onJoin wrappers would leak.
+  if (__patched) { return; }
+  __patched = true;
+
   /**
    * Optional: if zod is available, we can use toJSONSchema() for body and query types
    */

package/src-backend/index.ts

@@ -1,11 +1,15 @@
+import fs from 'fs/promises';
 import path from 'path';
-import express, { Router } from 'express';
+import { fileURLToPath } from 'url';
+import inspector from 'node:inspector/promises';
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import { createRequire } from 'node:module';
+import type { IncomingMessage, ServerResponse } from 'http';
+import { createEndpoint, dualModeEndpoints, isDevMode, logger, matchMaker, Server, type IRoomCache, type Endpoint } from '@colyseus/core';
 import { auth, JWT } from '@colyseus/auth';
-import { matchMaker, IRoomCache, __globalEndpoints } from '@colyseus/core';
-import type { Endpoint } from "@colyseus/better-call";
 import { applyMonkeyPatch } from './colyseus.ext.js';
-
-import { fileURLToPath } from 'url'; // required for ESM build (see build.mjs)
+import { serveStatic } from './serve-static.js';
 
 export type AuthConfig = {
   oauth: string[],
@@ -13,62 +17,291 @@ export type AuthConfig = {
   anonymous: boolean,
 };
 
-export function playground(): Router {
-  applyMonkeyPatch();
-
-  const router = express.Router();
+export interface PlaygroundOptions {
+  /** Mount prefix used when spread into `createRouter`. Ignored in express-middleware mode (express strips its mount path). Defaults to `''`. */
+  prefix?: string;
+  /** Better-call middleware applied to every playground endpoint — use for auth gating. */
+  use?: any[];
+}
 
-  // serve static frontend
-  router.use("/", express.static(path.resolve(__dirname, "..", "build")));
+const SPA_DIST = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'build');
 
-  // expose matchmaking stats
-  router.get("/rooms", async (req, res) => {
-    const rooms = await matchMaker.driver.query({});
+// CPU profiling state — single process, single active session. The captured
+// `.cpuprofile` and the cpupro-generated standalone HTML report are kept in
+// memory (latest only); a process restart clears them, which is fine for a
+// dev tool. See the `/profiling/*` endpoints below.
+let profilingSession: inspector.Session | null = null;
+let profilingStartedAt = 0;
+let lastProfile: string | null = null;
+let lastReportHtml: string | null = null;
+let lastProfilingError: string | null = null;
 
-    const roomsByType: { [roomName: string]: number } = {};
-    const roomsById: { [roomName: string]: IRoomCache } = {};
+// cpupro is an OPTIONAL peer dependency — it pulls in a native addon
+// (v8-profiler-next) we don't use, so it's opt-in. Resolve its CLI bin if
+// installed, else null. cpupro's `exports` map hides `bin/cpupro`, so resolve
+// the package dir via its (exported) package.json and join the bin path.
+function resolveCpuproBin(): string | null {
+  try {
+    const require = createRequire(import.meta.url);
+    return path.join(path.dirname(require.resolve('cpupro/package.json')), 'bin', 'cpupro');
+  } catch {
+    return null;
+  }
+}
 
-    rooms.forEach((room) => {
-      if (!roomsByType[room.name]) { roomsByType[room.name] = 0; }
-      roomsByType[room.name]++;
-      roomsById[room.roomId] = room;
+// Render an existing `.cpuprofile` (JSON string) into a standalone,
+// self-contained cpupro HTML report by shelling out to the cpupro CLI. The
+// CLI is the documented, format-stable path and is agnostic to our cjs/esm
+// dual build.
+async function generateCpuproReport(profileJson: string): Promise<string> {
+  const bin = resolveCpuproBin();
+  if (!bin) {
+    throw new Error("cpupro is not installed — run `npm install cpupro` to render reports in the playground. The .cpuprofile is still available to download.");
+  }
+  const stamp = Date.now();
+  const profilePath = path.join(os.tmpdir(), `colyseus-profile-${stamp}.cpuprofile`);
+  const reportName = `colyseus-report-${stamp}.html`;
+  const reportPath = path.join(os.tmpdir(), reportName);
+  await fs.writeFile(profilePath, profileJson);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const child = spawn(process.execPath, [bin, profilePath, '-n', '-o', os.tmpdir(), '-f', reportName], { stdio: 'ignore' });
+      child.on('error', reject);
+      child.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`cpupro exited with code ${code}`)));
     });
+    return patchCpuproReport(await fs.readFile(reportPath, 'utf8'));
+  } finally {
+    await fs.rm(profilePath, { force: true }).catch(() => {});
+    await fs.rm(reportPath, { force: true }).catch(() => {});
+  }
+}
 
-    res.json({
-      rooms: Object.keys(matchMaker.getAllHandlers()),
+// cpupro@0.7.0 ships a `build/report.html` template configured to fetch its
+// data from a sibling `model.data` URL (`dataSource:"url"`), yet `report.js`
+// appends the actual profile inline as `discoveryLoader.push()` chunks — a
+// mechanism only wired up when `dataSource==="push"`. As shipped the file is
+// therefore not self-contained: it requests `model.data` (404s through our
+// SPA) and throws `discoveryLoader is not defined`. Flip the data source to
+// `push` so the embedded chunks are consumed and the report stands alone.
+function patchCpuproReport(html: string): string {
+  return html.replace(/dataSource:"url",data:[A-Za-z_$][\w$]*\.model\.data/, 'dataSource:"push",data:1');
+}
 
-      roomsByType,
-      roomsById,
+export function playground(opts: PlaygroundOptions = {}) {
+  applyMonkeyPatch();
 
-      auth: {
-        // list of OAuth providers
-        oauth: Object.keys(auth.oauth.providers),
-        register: typeof(auth.settings.onRegisterWithEmailAndPassword) === "function",
-        anonymous: typeof(JWT.settings.secret) === "string",
-      } as AuthConfig
-    });
-  });
+  const prefix = opts.prefix ?? '';
+  const use = opts.use ?? [];
 
-  // serve API docs for playground
-  // (workaround to use better-call route inside express.Router)
-  router.get("/__apidocs", async (_, res) => {
-    /**
-     * Optional: if zod is available, we can use toJSONSchema() for body and query types
-     */
-    let z: any = undefined;
-    try { z = await import("zod"); } catch (e: any) { /* zod not installed  */ }
+  // Data endpoints leak internals (room listing + auth config, API schemas,
+  // CPU profiles/stack frames). Open during local dev (devMode or a
+  // non-production NODE_ENV); on production mounts require a `use:` guard —
+  // the guard is the opt-in. 404 hides the routes' existence.
+  let warnedGuardedProd = false;
+  const guardedDenied = () => {
+    if (isDevMode || process.env.NODE_ENV !== 'production') { return null; }
+    if (use.length === 0) { return new Response('Not found', { status: 404 }); }
+    if (!warnedGuardedProd) {
+      warnedGuardedProd = true;
+      logger.warn('@colyseus/playground: serving in production behind `use:` middleware — make sure at least one enforces authentication.');
+    }
+    return null;
+  };
 
-    res.json(Object.values(__globalEndpoints).map((endpoint: Endpoint) => {
+  const endpoints: Record<string, Endpoint> = {
+    'playground-rooms': createEndpoint(`${prefix}/rooms`, { method: 'GET', use }, async () => {
+      const denied = guardedDenied(); if (denied) { return denied; }
+      const rooms = await matchMaker.driver.query({});
+      const roomsByType: Record<string, number> = {};
+      const roomsById: Record<string, IRoomCache> = {};
+      rooms.forEach((room) => {
+        roomsByType[room.name] = (roomsByType[room.name] ?? 0) + 1;
+        roomsById[room.roomId] = room;
+      });
       return {
-        method: endpoint.options.method,
-        path: endpoint.path,
-        body: z && endpoint.options.body && z.toJSONSchema(endpoint.options.body),
-        query: z && endpoint.options.query && z.toJSONSchema(endpoint.options.query),
-        metadata: endpoint.options.metadata,
-        description: endpoint.options.metadata?.openapi?.description,
+        rooms: Object.keys(matchMaker.getAllHandlers()),
+        roomsByType,
+        roomsById,
+        auth: {
+          oauth: Object.keys(auth.oauth.providers),
+          register: typeof auth.settings.onRegisterWithEmailAndPassword === 'function',
+          anonymous: typeof JWT.settings.secret === 'string',
+        } as AuthConfig,
       };
-    }));
-  });
+    }),
+
+    'playground-apidocs': createEndpoint(`${prefix}/__apidocs`, { method: 'GET', use }, async () => {
+      const denied = guardedDenied(); if (denied) { return denied; }
+
+      let z: any;
+      try { z = await import('zod'); } catch { /* zod is an optional peer */ }
+      const routerEndpoints: Record<string, any> = (Server.current?.router as any)?.endpoints ?? {};
+      return Object.values(routerEndpoints)
+        // SERVER_ONLY endpoints aren't routable — don't list them either
+        .filter((endpoint: any) => !endpoint.options.metadata?.SERVER_ONLY)
+        .map((endpoint: any) => ({
+          method: endpoint.options.method,
+          path: endpoint.path,
+          body: z && endpoint.options.body && z.toJSONSchema(endpoint.options.body),
+          query: z && endpoint.options.query && z.toJSONSchema(endpoint.options.query),
+          metadata: endpoint.options.metadata,
+          description: endpoint.options.metadata?.openapi?.description,
+        }));
+    }),
+
+    'profiling-start': createEndpoint(`${prefix}/profiling/start`, { method: 'POST', use }, async (ctx) => {
+      const denied = guardedDenied(); if (denied) { return denied; }
+      if (profilingSession) {
+        return { status: 'running', startedAt: profilingStartedAt, error: 'already running' };
+      }
+      const interval = Number((ctx.query as any)?.interval) || 100;
+      const session = new inspector.Session();
+      session.connect();
+      await session.post('Profiler.enable');
+      await session.post('Profiler.setSamplingInterval', { interval });
+      await session.post('Profiler.start');
+      profilingSession = session;
+      profilingStartedAt = Date.now();
+      lastProfile = null;
+      lastReportHtml = null;
+      lastProfilingError = null;
+      return { status: 'started', startedAt: profilingStartedAt, interval };
+    }),
+
+    'profiling-stop': createEndpoint(`${prefix}/profiling/stop`, { method: 'POST', use }, async () => {
+      const denied = guardedDenied(); if (denied) { return denied; }
+      if (!profilingSession) {
+        return { status: 'idle', error: 'not running' };
+      }
+      const session = profilingSession;
+      profilingSession = null;
+      const durationMs = Date.now() - profilingStartedAt;
+      const { profile } = await session.post('Profiler.stop');
+      session.disconnect();
+      lastProfile = JSON.stringify(profile);
+      lastReportHtml = null;
+      lastProfilingError = null;
+      try {
+        lastReportHtml = await generateCpuproReport(lastProfile);
+      } catch (e: any) {
+        lastProfilingError = e?.message ?? String(e);
+      }
+      return {
+        status: 'stopped',
+        durationMs,
+        profileBytes: lastProfile.length,
+        reportReady: !!lastReportHtml,
+        error: lastProfilingError,
+      };
+    }),
 
-  return router;
+    'profiling-status': createEndpoint(`${prefix}/profiling/status`, { method: 'GET', use }, async () => {
+      const denied = guardedDenied(); if (denied) { return denied; }
+      return {
+        running: !!profilingSession,
+        startedAt: profilingSession ? profilingStartedAt : 0,
+        hasProfile: !!lastProfile,
+        hasReport: !!lastReportHtml,
+        // false when the optional `cpupro` peer dep isn't installed — the UI
+        // uses this to warn up front that captures are download-only.
+        reportSupported: !!resolveCpuproBin(),
+        error: lastProfilingError,
+      };
+    }),
+
+    'profiling-profile': createEndpoint(`${prefix}/profiling/profile.cpuprofile`, { method: 'GET', use }, async () => {
+      const denied = guardedDenied(); if (denied) { return denied; }
+      if (!lastProfile) { return new Response('No profile captured', { status: 404 }); }
+      const buf = Buffer.from(lastProfile, 'utf8');
+      return new Response(new Uint8Array(buf) as any, {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+          'content-length': String(buf.length),
+          'content-disposition': 'attachment; filename="profile.cpuprofile"',
+          'cache-control': 'no-cache',
+          // serve-static.ts sets this for the same reason: better-call's node
+          // adapter doesn't call res.end() on a backpressured single-chunk
+          // body, so a keep-alive response is left unterminated and browsers
+          // spin. Closing the connection terminates it cleanly.
+          'connection': 'close',
+        },
+      });
+    }),
+
+    'profiling-report': createEndpoint(`${prefix}/profiling/report.html`, { method: 'GET', use }, async () => {
+      const denied = guardedDenied(); if (denied) { return denied; }
+      if (!lastReportHtml) { return new Response('No report available', { status: 404 }); }
+      const buf = Buffer.from(lastReportHtml, 'utf8');
+      return new Response(new Uint8Array(buf) as any, {
+        status: 200,
+        headers: {
+          'content-type': 'text/html; charset=utf-8',
+          'content-length': String(buf.length),
+          'cache-control': 'no-cache',
+          // see profiling-profile above — `connection: close` so the browser
+          // doesn't spin on better-call's unterminated keep-alive response.
+          'connection': 'close',
+        },
+      });
+    }),
+
+    'playground-index': createEndpoint(`${prefix}/`, { method: 'GET', use }, async () => {
+      return serveStatic(SPA_DIST, '');
+    }),
+
+    'playground-static': createEndpoint(`${prefix}/**:splat`, { method: 'GET', use }, async (ctx) => {
+      return serveStatic(SPA_DIST, (ctx.params as any).splat);
+    }),
+  };
+
+  const SPA_DIST_RESOLVED = path.resolve(SPA_DIST);
+
+  return dualModeEndpoints(endpoints, {
+    catchAllKey: 'playground-static',
+    buildMiddleware: ({ fullHandler }) => {
+      // Strip express's `baseUrl` so the inner router sees the request
+      // relative to its mount point — playground's endpoint paths assume
+      // a `''` prefix, so a sub-mount like `app.use("/foo", playground())`
+      // needs the leading `/foo` stripped before dispatch.
+      const dispatch = (req: IncomingMessage, res: ServerResponse, next: (e?: any) => void) => {
+        const stripped = Object.create(req, {
+          baseUrl: { value: '', enumerable: true, configurable: true },
+          originalUrl: { value: req.url, enumerable: true, configurable: true },
+        });
+        fullHandler(stripped as any, res as any).catch(next);
+      };
+
+      return (req, res, next) => {
+        const url = (req.url ?? '').split('?')[0]!;
+        const isProfiling = url.startsWith('/profiling');
+
+        // Profiling start/stop are POSTs; everything else here is GET-only.
+        if (req.method === 'POST') {
+          return isProfiling ? dispatch(req, res, next) : next();
+        }
+        if (req.method !== 'GET') { return next(); }
+
+        if (url === '/' || url === '/rooms' || url === '/__apidocs' || isProfiling) {
+          return dispatch(req, res, next);
+        }
+
+        // Asset request — only delegate if the file actually exists on
+        // disk. Avoids the catch-all's SPA fallback (which would serve
+        // index.html for unknown paths, masking sibling express routes).
+        const rel = url.replace(/^\/+/, '');
+        if (!rel || rel.includes('..')) { return next(); }
+        const filePath = path.resolve(SPA_DIST_RESOLVED, rel);
+        if (!filePath.startsWith(SPA_DIST_RESOLVED + path.sep)) { return next(); }
+
+        fs.stat(filePath).then((stat) => {
+          if (stat.isFile()) {
+            dispatch(req, res, next);
+          } else {
+            next();
+          }
+        }).catch(() => next());
+      };
+    },
+  });
 }

package/src-backend/serve-static.ts

@@ -0,0 +1,76 @@
+// Static-file helper for the built playground SPA. Mirrors the helper used by
+// @colyseus/admin (kept duplicated for now — both consumers are framework-owned
+// and the helper is small + stable).
+import fs from 'fs/promises';
+import path from 'path';
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'application/javascript; charset=utf-8',
+  '.mjs':  'application/javascript; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg':  'image/svg+xml',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.ico':  'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf':  'font/ttf',
+  '.map':  'application/json; charset=utf-8',
+  '.txt':  'text/plain; charset=utf-8',
+};
+
+export async function serveStatic(root: string, relPath: string | undefined): Promise<Response> {
+  const safe = sanitize(relPath ?? '');
+  const filePath = safe ? path.join(root, safe) : path.join(root, 'index.html');
+
+  const resolved = path.resolve(filePath);
+  const resolvedRoot = path.resolve(root);
+  if (!resolved.startsWith(resolvedRoot + path.sep) && resolved !== resolvedRoot) {
+    return new Response('forbidden', { status: 403 });
+  }
+
+  const data = await tryRead(resolved);
+  if (data) { return fileResponse(data, mimeOf(resolved)); }
+
+  // SPA fallback — serve index.html for any non-asset request
+  if (!path.extname(safe)) {
+    const index = await tryRead(path.join(resolvedRoot, 'index.html'));
+    if (index) { return fileResponse(index, 'text/html; charset=utf-8'); }
+  }
+
+  return new Response('not found', { status: 404 });
+}
+
+function sanitize(p: string): string {
+  return p.replace(/^\/+/, '').split('/').filter((seg) => seg && seg !== '..' && seg !== '.').join('/');
+}
+
+function mimeOf(filePath: string): string {
+  return MIME[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+
+async function tryRead(filePath: string): Promise<Buffer | null> {
+  try {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) { return null; }
+    return await fs.readFile(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function fileResponse(buf: Buffer, contentType: string): Response {
+  return new Response(new Uint8Array(buf) as any, {
+    status: 200,
+    headers: {
+      'content-type': contentType,
+      'content-length': String(buf.length),
+      'cache-control': 'no-cache',
+      'connection': 'close',
+    },
+  });
+}