@colyseus/core 0.18.4 → 0.18.6

package/src/Room.ts

@@ -56,6 +56,9 @@ export {
 
 const DEFAULT_PATCH_RATE = 1000 / 20; // 20fps (50ms)
 const DEFAULT_SIMULATION_INTERVAL = 1000 / 60; // 60fps (16.66ms)
+
+// Shared so the unarmed `_flushUnreliable` call site stays monomorphic.
+const NOOP = () => {};
 const noneSerializer = new NoneSerializer();
 
 /** Shared `enqueueRaw` options routing a frame onto `_pendingFrames` to ride the
@@ -276,6 +279,45 @@ export class Room<T extends RoomOptions = RoomOptions> {
   #_patchRate: number;
   #_patchInterval: NodeJS.Timeout;
 
+  /**
+   * Frequency to flush `@unreliable` state fields, in milliseconds.
+   *
+   * Those fields never ride a state patch — they go out over the transport's
+   * unreliable channel (a WebTransport datagram), so a dropped frame costs one
+   * stale value instead of stalling the reliable stream behind a retransmit.
+   * Setting this decouples them from {@link patchRate}, which is the point:
+   * 60Hz movement over a 20Hz structural patch.
+   *
+   * KNOWN COST of a rate faster than {@link patchRate}: an entity's ADD travels
+   * the reliable channel, so datagrams sent between patches can reference a
+   * refId the client hasn't been told about yet. Those frames are skipped by the
+   * client's decoder — safe (the ref graph can't desync, since `@unreliable` is
+   * primitives-only) but each one logs `"refId" not found`, and that entity's
+   * first value lands one mutation later. Measured at `patchRate/this` reports
+   * per mid-session spawn. Leave this unset and the flush rides
+   * {@link broadcastPatch}, which ships the ADD first and avoids it entirely.
+   *
+   * Requires a transport with a datagram channel — today only
+   * `@colyseus/h3-transport` (WebTransport), which is **experimental**. Every
+   * WebSocket transport lacks one, and those clients are skipped entirely (the
+   * room warns once), so `@unreliable` fields keep their join-time value there.
+   *
+   * @default null — flush alongside every {@link broadcastPatch}, and only when
+   * the state actually declares an `@unreliable` field.
+   */
+  public unreliablePatchRate: number | null = null;
+  #_unreliablePatchRate: number | null = null;
+  #_unreliablePatchInterval: NodeJS.Timeout;
+
+  /**
+   * The unreliable flush, called unconditionally at the end of every
+   * {@link broadcastPatch}. Stays {@link NOOP} unless the state actually
+   * declares an `@unreliable` field, so a room that never uses the channel
+   * pays an empty call the engine inlines away — and there is no second
+   * entry point that could drift from `broadcastPatch()`.
+   */
+  private _flushUnreliable: () => void = NOOP;
+
   /**
    * Maximum number of messages a client can send to the server per second.
    * If a client sends more messages than this, it will be disconnected.
@@ -420,6 +462,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     this.#_state = this.state;
     this.#_autoDispose = this.autoDispose;
     this.#_patchRate = this.patchRate;
+    this.#_unreliablePatchRate = this.unreliablePatchRate;
     this.#_maxClients = this.maxClients;
 
     Object.defineProperties(this, {
@@ -436,6 +479,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
           }
           this._serializer.reset(newState);
           this.#_state = newState;
+          this._armUnreliablePatches();
         },
       },
 
@@ -479,6 +523,15 @@ export class Room<T extends RoomOptions = RoomOptions> {
           }
         },
       },
+
+      unreliablePatchRate: {
+        enumerable: true,
+        get: () => this.#_unreliablePatchRate,
+        set: (milliseconds: number | null) => {
+          this.#_unreliablePatchRate = milliseconds;
+          this._armUnreliablePatches();
+        },
+      },
     });
 
     // set patch interval, now with the setter
@@ -1300,6 +1353,12 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this._inputController !== undefined ? { sNow } : undefined,
     );
 
+    // Flush `@unreliable` fields over the datagram channel, after the reliable
+    // patch so a spawn's ADD is already on the wire when the datagram mutating
+    // it goes out. No-op unless the state declares such a field, and skipped
+    // when `unreliablePatchRate` gave the flush its own timer.
+    this._flushUnreliable();
+
     // Deliver any per-client `afterNextPatch` frames as standalone frames right
     // after the patch (never coalesced into it). Iterates only the clients that
     // staged frames this cycle (`#pendingFrameClients`), never the full list.
@@ -1321,6 +1380,64 @@ export class Room<T extends RoomOptions = RoomOptions> {
     return hasChanges;
   }
 
+  /**
+   * Encode and send the `@unreliable` state fields over each client's
+   * unreliable channel. Those fields never appear in a {@link broadcastPatch}
+   * frame, and clients on a transport without a datagram channel are skipped.
+   *
+   * Driven automatically once the state declares an `@unreliable` field — right
+   * after each {@link broadcastPatch}, or on its own timer when
+   * {@link unreliablePatchRate} is set. Public so a room driving
+   * `broadcastPatch()` by hand can drive this by hand too.
+   */
+  public broadcastUnreliablePatch() {
+    if (!this.state) {
+      return false;
+    }
+    return this._serializer.applyUnreliablePatches?.(this.clients) ?? false;
+  }
+
+  /**
+   * Decide how the unreliable channel is driven — and, for the rooms that never
+   * touch it, decide to not drive it at all. Runs when the state is assigned
+   * (the serializer knows by then whether any `@unreliable` field exists) and
+   * whenever {@link unreliablePatchRate} changes.
+   *
+   * A room whose state declares no `@unreliable` field leaves
+   * {@link _flushUnreliable} at {@link NOOP}, so its patch tick costs exactly
+   * what it did before this feature existed.
+   */
+  private _armUnreliablePatches() {
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = undefined;
+    }
+
+    const armed = this._serializer?.hasUnreliableFields === true;
+    const rate = this.#_unreliablePatchRate;
+    const dedicated = armed && rate !== null && rate !== 0;
+
+    // Default mode flushes from the patch itself rather than an independent
+    // timer of the same period, which would put the datagram ahead of a spawn's
+    // ADD about half the time.
+    const inline = armed && !dedicated;
+
+    this._flushUnreliable = inline
+      ? () => { this.broadcastUnreliablePatch(); }
+      : NOOP;
+
+    if (dedicated) {
+      this.#_unreliablePatchInterval = setInterval(() => this.broadcastUnreliablePatch(), rate);
+
+    } else if (inline && !this.#_patchRate) {
+      // patchRate 0/null means no patch tick to piggyback on.
+      logger.warn(
+        "@colyseus/core: state has @unreliable fields but patchRate is disabled —" +
+        " set `room.unreliablePatchRate` to flush them, or they will never update."
+      );
+    }
+  }
+
   /**
    * Register a message handler for a specific message type.
    * This method is used to handle messages sent by clients to the room.
@@ -2078,6 +2195,11 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this.#_patchInterval = undefined;
     }
 
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = undefined;
+    }
+
     if (this._simulationInterval) {
       clearInterval(this._simulationInterval);
       this._simulationInterval = undefined;

package/src/Transport.ts

@@ -8,7 +8,8 @@ import { StateView } from '@colyseus/schema';
 import type { InputDecoder } from '@colyseus/schema/input';
 
 import { EventEmitter } from 'events';
-import { spliceOne } from './utils/Utils.ts';
+import { debugAndPrintError } from './Debug.ts';
+import { getBearerToken, spliceOne } from './utils/Utils.ts';
 import { ServerError } from './errors/ServerError.ts';
 
 import type { Room } from './Room.ts';
@@ -46,12 +47,129 @@ export abstract class Transport {
     public bindRouter?(router: Router): void;
 }
 
+/**
+ * Intercepts an incoming WebSocket upgrade request, before the handshake.
+ *
+ * Return a `Response` to answer the request instead of upgrading it. Return
+ * nothing to upgrade as usual. The handler may be async, and the handshake waits
+ * for it to resolve.
+ *
+ * `context` is the same shape `onAuth()` receives, read-only here: mutating it
+ * does not carry over to `onAuth()`.
+ *
+ * Not supported by `H3Transport`: WebTransport has no upgrade handshake.
+ *
+ * @example
+ * ```typescript
+ * new uWebSocketsTransport({
+ *   beforeUpgrade: async (request, context) => {
+ *     if (await isBanned(context.ip)) {
+ *       return new Response(null, { status: 403 });
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export type BeforeUpgradeHandler = (
+  request: Request,
+  context: Readonly<AuthContext>,
+) => Response | void | Promise<Response | void>;
+
+/**
+ * Invokes a `beforeUpgrade` handler, resolving with the `Response` to send
+ * instead of upgrading, or `undefined` to proceed with the upgrade.
+ *
+ * Every transport goes through here, so a handler written against one keeps
+ * working on the others. Never rejects: uWebSockets.js aborts the process on an
+ * upgrade handler that yields without responding, and on the other transports a
+ * raw socket left behind leaks a connection.
+ *
+ * @internal
+ */
+export async function runBeforeUpgrade(
+  handler: BeforeUpgradeHandler,
+  url: string, // path, optionally including the query string
+  context: AuthContext,
+): Promise<Response | undefined> {
+  let request: Request;
+
+  try {
+    const host = context.headers.get('host') || 'localhost';
+    request = new Request(`http://${host}${url}`, { headers: context.headers });
+
+  } catch (e: any) {
+    // a `Host` header that isn't a valid authority fails to parse as a URL
+    debugAndPrintError(e);
+    return new Response(null, { status: 400 });
+  }
+
+  try {
+    return (await handler(request, context)) ?? undefined;
+
+  } catch (e: any) {
+    debugAndPrintError(e);
+    return new Response(null, { status: 500 });
+  }
+}
+
+/** Headers as the transport has them: uWebSockets.js and Node give a plain record. */
+type RawHeaders = Headers | Record<string, string | undefined>;
+
+const readHeader = (headers: RawHeaders, name: string) =>
+  (headers instanceof Headers) ? headers.get(name) : headers[name];
+
+/**
+ * Builds the context passed to `beforeUpgrade` and `onAuth`.
+ *
+ * Every transport goes through here, so the context is identical everywhere,
+ * down to how the client address is resolved. `headers` is materialized on
+ * first read: a connection nobody inspects pays nothing for the conversion.
+ *
+ * @internal
+ */
+export function createAuthContext(options: {
+  headers: RawHeaders,
+  token?: string | null,
+  remoteAddress?: string,
+  req?: any,
+}): AuthContext {
+  const source = options.headers;
+  let headers: Headers | undefined;
+
+  return {
+    token: options.token ?? getBearerToken(readHeader(source, 'authorization')),
+    ip: resolveClientIp(source, options.remoteAddress),
+    req: options.req,
+    get headers() {
+      return headers ??= (source instanceof Headers)
+        ? source
+        : new Headers(source as Record<string, string>);
+    },
+  };
+}
+
+/**
+ * A single address, resolved the same way on every transport: `x-forwarded-for`
+ * carries the whole proxy chain, and only its first entry is the client.
+ */
+function resolveClientIp(headers: RawHeaders, remoteAddress?: string): string | undefined {
+  // an empty header counts as absent
+  const firstHop = (name: string) => readHeader(headers, name)?.split(',')[0].trim() || undefined;
+
+  return (
+    firstHop('x-real-ip') ??
+    firstHop('x-forwarded-for') ??
+    firstHop('x-client-ip') ??
+    (remoteAddress || undefined)
+  );
+}
+
 export type AuthContext = {
   token?: string,
+  /** Undefined when no proxy header carries it and the transport has no peer address. */
+  ip: string | undefined;
   headers: Headers,
-  ip: string | string[];
-  // FIXME: each transport may have its own specific properties.
-  // "req" only applies to WebSocketTransport.
+  /** Only set on the HTTP matchmaking request, where it is the `Request` itself. */
   req?: any;
 };
 
@@ -136,6 +254,16 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
   raw(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
   enqueueRaw(data: Uint8Array | Buffer, options?: ISendOptions): void;
 
+  /**
+   * Send raw bytes over the transport's UNRELIABLE channel — no delivery,
+   * ordering, or duplication guarantee. Used for `@unreliable` state patches.
+   *
+   * Absent on transports with no datagram channel (every WebSocket transport).
+   * Its presence IS the capability check — callers feature-detect rather than
+   * reading a separate flag, and skip clients that can't receive.
+   */
+  rawUnreliable?(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
+
   /**
    * Send a type of message to the client. Messages are encoded with MsgPack and can hold any
    * JSON-serializable data structure.

package/src/index.ts

@@ -56,7 +56,7 @@ export * from './matchmaker/LocalDriver/LocalDriver.ts';
 export { initializeRoomCache } from './matchmaker/driver.ts';
 
 // Transport
-export { type Client, type ClientPrivate, type AuthContext, ClientState, ClientArray, Transport, type ISendOptions, connectClientToRoom, enqueueClientRaw } from './Transport.ts';
+export { type Client, type ClientPrivate, type AuthContext, ClientState, ClientArray, Transport, type ISendOptions, type BeforeUpgradeHandler, runBeforeUpgrade, createAuthContext, connectClientToRoom, enqueueClientRaw } from './Transport.ts';
 
 // Presence
 export { type Presence } from './presence/Presence.ts';

package/src/input/RoomInput.ts

@@ -21,6 +21,20 @@ import { debugAndPrintError } from '../Debug.ts';
  */
 const _inputReflectionCache = new WeakMap<Function, Uint8Array>();
 
+/**
+ * Rebuild one `k`-length series of the unreliable stamp block: `newest` is the
+ * absolute anchor, and each wire delta walks one slot older
+ * (`out[i] = out[i+1] − Δ`). Mirrors the SDK's `_writeSeriesDeltas`.
+ */
+function readSeriesDeltas(buffer: Buffer, it: Iterator, k: number, newest: number): number[] {
+  const out = new Array<number>(k);
+  out[k - 1] = newest;
+  for (let i = k - 2; i >= 0; i--) {
+    out[i] = out[i + 1] - decode.number(buffer, it);
+  }
+  return out;
+}
+
 /**
  * Runtime behind {@link InputAPI}. A class, not a per-`define()` object literal:
  * literal (and `defineProperty`) accessors carry their closure identity in the
@@ -272,11 +286,70 @@ export class RoomInput {
   }
 
   /** Decode a `ROOM_INPUT_UNRELIABLE` redundancy ring — each slot carries its
-   *  framework seq (base seq + position) for ring dedupe, no user seqField. */
-  decodeUnreliable(client: ClientPrivate, buffer: Buffer, _modifiers: number): void {
+   *  framework seq (base seq + position) for ring dedupe, no user seqField.
+   *
+   *  With the TIMED bit, a self-contained lag-comp stamp block precedes the ring:
+   *
+   *      [varint k][uint32 newest][varint Δ]×(k−1)
+   *      [uint16 rdNewest][varint Δrd]×(k−1)        ← BOTH mode only
+   *
+   *  One stamp per slot, because a packet carries k inputs sampled at k
+   *  different instants. The anchor is absolute and the deltas never leave the
+   *  packet, so — unlike the reliable channel's running baseline — no amount of
+   *  loss or reordering can desync it, and an input recovered redundantly from a
+   *  later packet still arrives with its own instant. Stamps are paired
+   *  positionally with `decodeAll`'s oldest→newest yields; a `k` that disagrees
+   *  with the decoded slot count means a malformed packet, so the stamps are
+   *  dropped rather than misapplied (inputs still land, read live). */
+  decodeUnreliable(client: ClientPrivate, buffer: Buffer, modifiers: number): void {
     if (!client._inputDecoder) { return; }
+
+    const it: Iterator = { offset: 1 };
+    let stamps: number[] | undefined;
+    let renderDeltas: number[] | undefined;
+
+    if (modifiers & ProtocolModifier.TIMED) {
+      this.#resolveWireModes();
+      try {
+        const k = decode.number(buffer, it);
+        stamps = readSeriesDeltas(buffer, it, k, decode.uint32(buffer, it));
+        // BOTH mode trails the renderDelta series in the same shape, so each
+        // slot keeps the latency term it was actually sampled with.
+        if (this.#stampReckon && this.#stampRender) {
+          renderDeltas = readSeriesDeltas(buffer, it, k, decode.uint16(buffer, it));
+        }
+      } catch (e: any) {
+        debugAndPrintError(e);
+        return;
+      }
+    }
+
+    let i = 0;
     try {
-      client._inputDecoder.decodeAll(buffer.subarray(1), (_inst, seq) => this.capture(client, 0, 0, seq));
+      const count = client._inputDecoder.decodeAll(buffer.subarray(it.offset), (_inst, seq) => {
+        // Positional pairing — `decodeAll` yields oldest→newest, the order the
+        // block was written in.
+        const slot = i++;
+        const stamp = stamps?.[slot] ?? 0;
+        let renderTime = 0, reckonTime = 0;
+        if (stamp > 0) {
+          if (this.#stampReckon && this.#stampRender) {
+            const rd = renderDeltas?.[slot] ?? 0;
+            reckonTime = stamp;
+            renderTime = stamp > rd ? stamp - rd : 0;
+          } else if (this.#stampReckon) {
+            reckonTime = stamp;
+          } else {
+            renderTime = stamp;
+          }
+        }
+        this.capture(client, renderTime, reckonTime, seq);
+      });
+      if (stamps !== undefined && count !== stamps.length) {
+        debugAndPrintError(new Error(
+          `@colyseus/core: unreliable input stamp block declared ${stamps.length} slots, decoded ${count}`
+        ));
+      }
     } catch (e: any) {
       debugAndPrintError(e);
       return;

package/src/matchmaker/driver.ts

@@ -188,9 +188,10 @@ export interface MatchMakerDriver {
 
   /**
    * Empty the room cache. Used for testing purposes only.
+   * May be asynchronous — callers must await it.
    * @internal Do not call this method yourself.
    */
-  clear(): void;
+  clear(): void | Promise<void>;
 
   /**
    * Boot the room cache medium (if available).
@@ -199,6 +200,7 @@ export interface MatchMakerDriver {
 
   /**
    * Dispose the connection of the room cache medium.
+   * May be asynchronous — callers must await it.
    */
-  shutdown(): void;
+  shutdown(): void | Promise<void>;
 }

package/src/router/default_routes.ts

@@ -1,8 +1,7 @@
 import { createEndpoint } from "@colyseus/better-call";
 import { createRouter } from "./index.ts";
 import * as matchMaker from "../MatchMaker.ts";
-import { getBearerToken } from "../utils/Utils.ts";
-import { getTransport } from "../Transport.ts";
+import { createAuthContext, getTransport } from "../Transport.ts";
 
 export const postMatchmakeMethod = createEndpoint("/matchmake/:method/:roomName", { method: "POST" }, async (ctx) => {
   // do not accept matchmaking requests if already shutting down
@@ -21,12 +20,7 @@ export const postMatchmakeMethod = createEndpoint("/matchmake/:method/:roomName"
       method,
       roomName,
       clientOptions,
-      {
-        token: getBearerToken(ctx.request.headers.get('authorization')),
-        headers: ctx.request.headers,
-        ip: requestHeaders.get('x-forwarded-for') ?? requestHeaders.get('x-client-ip') ?? requestHeaders.get('x-real-ip'),
-        req: ctx.request as any,
-      },
+      createAuthContext({ headers: requestHeaders, req: ctx.request }),
     );
 
     //

package/src/router/index.ts

@@ -1,5 +1,7 @@
 import type express from "express";
 import type { IncomingMessage, ServerResponse } from "http";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { type Endpoint, type Router, type RouterConfig, createRouter as createBetterCallRouter, createEndpoint, createMiddleware, APIError } from "@colyseus/better-call";
 import { toNodeHandler, getRequest, setResponse } from "@colyseus/better-call/node";
@@ -250,8 +252,12 @@ export function dualModeEndpoints<E extends Record<string, Endpoint>>(
   opts: {
     /** Key in `endpoints` whose path is a catch-all. Excluded from `specificRouter` so it doesn't eat fall-through decisions. */
     catchAllKey?: keyof E;
-    /** Build the express middleware given the pre-built routers + node handlers. */
-    buildMiddleware: (helpers: DualModeHelpers) => ExpressMiddleware;
+    /** Endpoint-path prefix baked into `endpoints` (`''`, `'/monitor'`). Used by the default middleware to rebase path mounts. */
+    prefix?: string;
+    /** SPA dist dir — the default middleware dispatches catch-all requests only for files that exist here. */
+    staticDir?: string;
+    /** Build a custom express middleware given the pre-built routers + node handlers. Omit for the default SPA-panel middleware. */
+    buildMiddleware?: (helpers: DualModeHelpers) => ExpressMiddleware;
   },
 ): ExpressMiddleware & E {
   const fullRouter = createRouter(endpoints);
@@ -265,8 +271,71 @@ export function dualModeEndpoints<E extends Record<string, Endpoint>>(
   const specificRouter = createRouter(specificEndpoints as E);
   const specificHandler = toNodeHandler(specificRouter.handler) as NodeHandler;
 
-  const middleware = opts.buildMiddleware({
+  const buildMiddleware = opts.buildMiddleware ?? panelMiddleware(opts.prefix ?? '', opts.staticDir);
+  const middleware = buildMiddleware({
     specificRouter, specificHandler, fullRouter, fullHandler,
   });
   return Object.assign(middleware, endpoints) as ExpressMiddleware & E;
 }
+
+/**
+ * Default express middleware for a single-prefix SPA panel (monitor,
+ * playground). Express and the endpoint map use different coordinates: a path
+ * mount strips its prefix into `req.baseUrl`, while the endpoints keep the
+ * configured `prefix` baked into their paths. This rebases every request onto
+ * the endpoint namespace, so the panel works at any mount path — `prefix` only
+ * matters in router mode and at root mounts.
+ */
+function panelMiddleware(prefix: string, staticDir?: string) {
+  const staticRoot = staticDir && path.resolve(staticDir);
+  return ({ specificRouter, specificHandler, fullHandler }: DualModeHelpers): ExpressMiddleware =>
+    (req, res, next) => {
+      const r = req as IncomingMessage & { baseUrl?: string; originalUrl?: string };
+      const raw = r.url ?? '';
+      const q = raw.indexOf('?');
+      const url = q < 0 ? raw : raw.slice(0, q);
+      const query = q < 0 ? '' : raw.slice(q);
+
+      // Path mounts arrive stripped (`req.url` is mount-relative); root and
+      // pathless mounts arrive unstripped and already match the endpoints.
+      const dispatchPath = r.baseUrl ? prefix + url : url;
+
+      // Canonicalize the index: the SPA references its assets relatively, so
+      // they only resolve from the trailing-slash URL. The browser's address
+      // is originalUrl — 302 (not 301: browsers cache 301s across remounts).
+      if (dispatchPath === prefix || dispatchPath === `${prefix}/`) {
+        const original = (r.originalUrl ?? raw).split('?')[0]!;
+        if (r.method === 'GET' && !original.endsWith('/')) {
+          res.writeHead(302, { location: `${original}/${query}` });
+          res.end();
+          return;
+        }
+      }
+
+      const dispatch = (handler: NodeHandler) => {
+        // better-call's getRequest resolves the path as baseUrl + url
+        const wrapped = Object.create(req, {
+          url: { value: dispatchPath + query, enumerable: true, configurable: true },
+          baseUrl: { value: '', enumerable: true, configurable: true },
+          originalUrl: { value: dispatchPath + query, enumerable: true, configurable: true },
+        });
+        handler(wrapped as any, res).catch(next);
+      };
+
+      const route = specificRouter.findRoute(r.method ?? 'GET', dispatchPath);
+      // rou3 normalizes trailing slashes in findRoute but processRequest
+      // exact-matches — only trust the hit when the slashes agree.
+      if (route && (!route.data?.path?.endsWith('/') || dispatchPath.endsWith('/'))) {
+        return dispatch(specificHandler);
+      }
+
+      // Asset request — only delegate when the file exists on disk, so the
+      // catch-all's SPA fallback can't mask sibling express routes.
+      if (r.method !== 'GET' || !staticRoot || !dispatchPath.startsWith(prefix)) { return next(); }
+      const rel = dispatchPath.slice(prefix.length).replace(/^\/+/, '');
+      if (!rel || rel.includes('..')) { return next(); }
+      const filePath = path.resolve(staticRoot, rel);
+      if (!filePath.startsWith(staticRoot + path.sep)) { return next(); }
+      fs.stat(filePath).then((stat) => stat.isFile() ? dispatch(fullHandler) : next()).catch(() => next());
+    };
+}