@entrinsik/vite-plugin-informer 2.11.0 → 2.13.0

package/src/dev-channel-handlers.js

@@ -1,9 +1,11 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 import { parse as parseUrl } from 'node:url';
 import { createDevBagBuilder, buildDevUser } from './dev-bag.js';
+import { devPlatform } from './dev-platform.js';
 import { filePathToRoute, matchRoute, walkJsFiles } from './server-routes.js';
 import { createDevChannels, isChannelName, isWildcardName, isEventName, isReservedEvent, channelError, USER_CHANNEL_PREFIX } from './dev-channels.js';
+import { createDevActors, isActorModule, memberIdFor, ACTOR_LIFECYCLE } from './dev-channel-actors.js';
 
 /**
  * The dev counterpart of app-channel-handlers.js: a page's `channel()` mock
@@ -11,8 +13,9 @@ import { createDevChannels, isChannelName, isWildcardName, isEventName, isReserv
  * the matching `channels/` file runs in-process the way a deployed handler
  * runs in the sandbox — `join` decides admission, `joined` runs after it,
  * `leave` runs on unsubscribe, and an event-named export answers `send()`.
- * Frames still ride Vite's websocket to every page; admission is what tells
- * the page which frames it may dispatch.
+ * A file with `config.actor` runs as a channel actor instead (see
+ * dev-channel-actors.js). Frames still ride Vite's websocket to every page;
+ * admission is what tells the page which frames it may dispatch.
  */
 
 export const CHANNELS_DIR = 'channels';
@@ -20,8 +23,12 @@ export const CHANNELS_DIR = 'channels';
 export const CHANNEL_METHOD = 'CHANNEL';
 // The deployment's joinTimeoutMs cap; a file's `config.timeout` may only lower it.
 export const HANDLER_TIMEOUT_MS = 5000;
-// Per-user inbound send budget (token bucket).
+// Per-user inbound budget (token bucket): send() and the replay reads a reconnect makes.
 export const SEND_RATE = Object.freeze({ perSecond: 10, burst: 30 });
+// The server's separate, larger send() budget for actor channels (a game's inputs).
+export const ACTOR_SEND_RATE = Object.freeze({ perSecond: 30, burst: 60 });
+// Edits under these directories can change what an actor runs: its file, or what it imports.
+const ACTOR_SOURCE_DIRS = ['channels', 'shared', 'lib', 'server'];
 // Exports with a fixed meaning; every other export must be an event name.
 export const LIFECYCLE_EXPORTS = Object.freeze(['config', 'join', 'joined', 'leave']);
 
@@ -101,11 +108,13 @@ export async function validateChannelHandlers(projectRoot) {
     return problems;
 }
 
-// Does a handler route cover some channel strictly under `prefix` segments?
-// (`/rooms/:room` and `/rooms/east/members` both cover names under `rooms/`.)
-function coversUnder(routePath, prefix) {
+// Does a handler route cover some channel deeper than `minDepth` segments
+// under `prefix`? (`/rooms/:room` and `/rooms/east/members` both cover names
+// under `rooms/`.) `minDepth` is what the wildcard's own handler already gates:
+// the prefix length for an unmatched wildcard, one more for a matched one.
+function coversUnder(routePath, prefix, minDepth) {
     const segments = routePath.split('/').filter(Boolean);
-    return segments.length > prefix.length && prefix.every((seg, i) => segments[i].startsWith(':') || segments[i] === seg);
+    return segments.length > minDepth && prefix.every((seg, i) => segments[i].startsWith(':') || segments[i] === seg);
 }
 
 function readJson(req) {
@@ -147,13 +156,45 @@ function sendJson(res, status, body) {
  * @param {() => number} [opts.now] - clock, for the rate limiter
  * @returns {Function} Connect middleware
  */
-export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), user, roles = [], logPrefix = '[app-channel]', timeoutMs = HANDLER_TIMEOUT_MS, rate = SEND_RATE, now = Date.now }) {
+export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), user, roles = [], logPrefix = '[app-channel]', timeoutMs = HANDLER_TIMEOUT_MS, rate = SEND_RATE, now = Date.now, platform = devPlatform(), appId = null }) {
     const devUser = buildDevUser(user);
-    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]' });
-    // clientId → channel name → { clientId, channel, params, file }
+    // The same merged descriptor the page and the server/ bag see: a channels/
+    // handler reading platform.capabilities.embeddings must not disagree with
+    // the route beside it, and its embed() must be bound when they agree.
+    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]', platform, appId });
+    // clientId → channel name → { clientId, channel, params, file, actor }
     const subscriptions = new Map();
-    // username → { tokens, ts }
+    // username (or `actor:` + username) → { tokens, ts }
     const buckets = new Map();
+    const actors = createDevActors({
+        viteServer,
+        bagFor: async () => (await bagBuilder.build()).bag,
+        logPrefix,
+        callTimeoutMs: Math.min(timeoutMs, 1000)
+    });
+    // A Vite restart (a config edit) closes this server and builds another:
+    // without this the old server's actors keep their tick loops and module
+    // instances running forever, so two config edits leave three copies of the
+    // same game ticking.
+    if (viteServer.httpServer && typeof viteServer.httpServer.once === 'function') {
+        viteServer.httpServer.once('close', () => {
+            actors.stopAll().catch(err => console.error(`${logPrefix} stopping actors on shutdown failed:`, err));
+        });
+    }
+    // An edit to a file actors load restarts them on the new code, from their snapshots.
+    if (viteServer.watcher && typeof viteServer.watcher.on === 'function') {
+        viteServer.watcher.on('change', file => {
+            const rel = relative(projectRoot, file);
+            if (rel.startsWith('..') || !ACTOR_SOURCE_DIRS.includes(rel.split(sep)[0])) return;
+            for (const mod of (viteServer.moduleGraph && viteServer.moduleGraph.getModulesByFile(file)) || []) {
+                viteServer.moduleGraph.invalidateModule(mod);
+            }
+            actors.restartAll().catch(err => console.error(`${logPrefix} restarting actors after an edit failed:`, err));
+        });
+    }
+
+    // The `request` a handler sees: the page's member id, and the mocked viewer.
+    const requestFor = clientId => ({ member: memberIdFor(clientId), user: { ...devUser }, roles });
 
     function recordsFor(clientId) {
         let records = subscriptions.get(clientId);
@@ -164,14 +205,15 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         return records;
     }
 
-    function takeSendToken(username) {
+    function takeSendToken(username, budget = rate) {
         const at = now();
-        let bucket = buckets.get(username);
+        const key = budget === rate ? username : `actor:${username}`;
+        let bucket = buckets.get(key);
         if (!bucket) {
-            bucket = { tokens: rate.burst, ts: at };
-            buckets.set(username, bucket);
+            bucket = { tokens: budget.burst, ts: at };
+            buckets.set(key, bucket);
         }
-        bucket.tokens = Math.min(rate.burst, bucket.tokens + (Math.max(0, at - bucket.ts) / 1000) * rate.perSecond);
+        bucket.tokens = Math.min(budget.burst, bucket.tokens + (Math.max(0, at - bucket.ts) / 1000) * budget.perSecond);
         bucket.ts = at;
         if (bucket.tokens < 1) return false;
         bucket.tokens -= 1;
@@ -179,9 +221,9 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
     }
 
     // The handler file covering a channel name, or null for an open channel.
-    // A wildcard resolves with `*` as the param; when no file takes the
-    // wildcard itself but some file gates a name under its prefix, the
-    // wildcard is refused rather than letting it listen around the gate.
+    // A wildcard resolves with `*` as the param and is admitted only when
+    // nothing sits deeper than the file that took it (or, unmatched, deeper
+    // than its prefix): a deeper file's gate would otherwise be listened around.
     async function resolveChannel(channel) {
         const table = (await scanChannelHandlers(projectRoot)).map(h => ({ ...h, method: CHANNEL_METHOD }));
         let match;
@@ -191,23 +233,25 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
             if (err instanceof URIError) throw channelError('app_channel_invalid_name', 400);
             throw err;
         }
-        if (match) return { params: match.params, file: match.route };
         if (isWildcardName(channel)) {
             const prefix = channel.slice(0, -2).split('/');
-            if (table.some(route => coversUnder(route.path, prefix))) throw channelError('app_channel_wildcard_gated', 403);
+            // an unmatched wildcard gates nothing; a matched one gates its own
+            // depth, and a file deeper than that would go ungated either way
+            const gatedTo = match ? prefix.length + 1 : prefix.length;
+            if (table.some(route => coversUnder(route.path, prefix, gatedTo))) throw channelError('app_channel_wildcard_gated', 403);
         }
-        return null;
+        return match ? { params: match.params, file: match.route } : null;
     }
 
     // Run one export with the channel bag under the handler's timeout. A thrown
     // channel error keeps its status; anything else is 500 app_channel_<export>_failed.
-    async function runExport(mod, exportName, { channel, params, payload }) {
+    async function runExport(mod, exportName, { channel, params, payload, clientId }) {
         const { bag } = await bagBuilder.build();
         const invocation = {
             ...bag,
             channel: { name: channel, params, broadcast: async (event, body, options) => await bag.broadcast(channel, event, body, options) },
             payload: payload === undefined ? null : payload,
-            request: { user: { ...devUser }, roles }
+            request: requestFor(clientId)
         };
         const cap = Math.min(Number(mod.config && mod.config.timeout) || timeoutMs, timeoutMs);
         let timer;
@@ -244,12 +288,17 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         if (Array.isArray(required) && required.length > 0 && !required.some(r => roles.includes(r))) {
             throw channelError('app_channel_role_required', 403);
         }
-        if (typeof mod.join === 'function') {
+        if (isActorModule(mod)) {
+            // the channel's actor runs join itself (and starts on the first one)
+            if (isWildcardName(channel)) throw channelError('app_channel_actor_wildcard', 403);
+            await actors.join({ channel, params: record.params, filePath: resolved.file.filePath, clientId, request: requestFor(clientId) });
+            record.actor = true;
+        } else if (typeof mod.join === 'function') {
             // admitted only when the handler returned exactly true
             if (await runExport(mod, 'join', record) !== true) throw channelError('app_channel_join_refused', 403);
         }
         recordsFor(clientId).set(channel, record);
-        console.log(`${logPrefix} join("${channel}") admitted${typeof mod.join === 'function' ? '' : ' (no join export)'}`);
+        console.log(`${logPrefix} join("${channel}") admitted${record.actor ? ' (actor)' : typeof mod.join === 'function' ? '' : ' (no join export)'}`);
         return mod;
     }
 
@@ -259,6 +308,10 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         if (!record) return;
         records.delete(channel);
         if (!record.file) return;
+        if (record.actor) {
+            await actors.leave({ channel, clientId }).catch(err => console.warn(`${logPrefix} leave("${channel}") failed: ${err.message}`));
+            return;
+        }
         try {
             const mod = await viteServer.ssrLoadModule(record.file.filePath);
             if (typeof mod.leave === 'function') await runExport(mod, 'leave', record);
@@ -274,6 +327,12 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         if (!isEventName(event)) throw channelError('app_channel_invalid_event', 400);
         if (isReservedEvent(event)) throw channelError('app_channel_reserved_event', 400);
         if (!record.file) throw channelError('app_channel_no_handler', 404);
+        if (record.actor) {
+            if (LIFECYCLE_EXPORTS.includes(event) || ACTOR_LIFECYCLE.includes(event)) throw channelError('app_channel_no_handler', 404);
+            if (!takeSendToken(devUser.username, ACTOR_SEND_RATE)) throw channelError('app_channel_rate_limited', 429);
+            const result = await actors.send({ channel, params: record.params, filePath: record.file.filePath, clientId, request: requestFor(clientId), event, payload });
+            return result === undefined ? null : result;
+        }
         const mod = await viteServer.ssrLoadModule(record.file.filePath);
         if (LIFECYCLE_EXPORTS.includes(event) || typeof mod[event] !== 'function') throw channelError('app_channel_no_handler', 404);
         if (!takeSendToken(devUser.username)) throw channelError('app_channel_rate_limited', 429);
@@ -282,7 +341,7 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         return result === undefined ? null : result;
     }
 
-    return async function devChannelHandlersMiddleware(req, res, next) {
+    async function devChannelHandlersMiddleware(req, res, next) {
         const parsed = parseUrl(req.url, true);
         const route = `${req.method} ${parsed.pathname}`;
         let body = {};
@@ -290,6 +349,8 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
             if (route === 'GET /replay') {
                 const { channel, since } = parsed.query;
                 if (!isChannelName(channel)) throw channelError('app_channel_invalid_name', 400);
+                // the same per-user bucket as send(), spent before anything else, as on the server
+                if (!takeSendToken(devUser.username)) throw channelError('app_channel_rate_limited', 429);
                 return sendJson(res, 200, channels.replay(channel, Number(since) || 0));
             }
             if (!['POST /subscribe', 'POST /unsubscribe', 'POST /send'].includes(route)) return next();
@@ -305,7 +366,10 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
                 if (mod && typeof mod.joined === 'function') {
                     const record = recordsFor(body.clientId).get(body.channel);
                     setImmediate(() => {
-                        runExport(mod, 'joined', record).catch(err => console.warn(`${logPrefix} joined("${body.channel}") failed: ${err.message}`));
+                        const run = record.actor
+                            ? actors.joined({ channel: body.channel, clientId: body.clientId, request: requestFor(body.clientId) })
+                            : runExport(mod, 'joined', record);
+                        run.catch(err => console.warn(`${logPrefix} joined("${body.channel}") failed: ${err.message}`));
                     });
                 }
                 return;
@@ -314,12 +378,16 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
                 await unsubscribe(body);
                 return sendJson(res, 200, { ok: true });
             }
-            return sendJson(res, 200, { result: await send(body) });
+            // `now`, as the server stamps it: the page's serverNow() reads it
+            return sendJson(res, 200, { result: await send(body), now: Date.now() });
         } catch (err) {
             const status = typeof err.statusCode === 'number' ? err.statusCode : 500;
             if (status === 500) console.error(logPrefix, err);
             else if (route === 'POST /subscribe') console.log(`${logPrefix} join("${body.channel}") refused (${err.code || err.message})`);
             sendJson(res, status, { error: err.code || err.message });
         }
-    };
+    }
+    // the running actors, for tests and the terminal
+    devChannelHandlersMiddleware.actors = actors;
+    return devChannelHandlersMiddleware;
 }

package/src/dev-channel-shim.js

@@ -8,8 +8,8 @@ import { CHANNEL_NAME, CHANNEL_NAME_MAX_LENGTH, EVENT_NAME, EVENT_NAME_MAX_LENGT
  *   var ch = __INFORMER__.channel('rooms/east', { since: 12 });  // sync; throws join_refused on a bad name
  *   ch.on('created', function (payload, frame) {});   // first handler subscribes
  *   ch.on('connected', function (info) {});           // { replayed: n } after each (re)subscribe
- *   ch.on('error', function (err) {});                // err.code: join_refused | rate_limited | disconnected | replay_gap
- *   ch.send(event, payload).then(result);             // rejects: send_refused | rate_limited | disconnected
+ *   ch.on('error', function (err) {});                // err.code: join_refused | rate_limited | budget_exhausted | handler_failed | disconnected | replay_gap
+ *   ch.send(event, payload).then(result);             // rejects: send_refused | rate_limited | budget_exhausted | handler_failed | disconnected
  *   ch.close();
  *
  * Transport: production subscribes each channel over a nes socket; dev POSTs
@@ -75,10 +75,14 @@ export function generateDevChannelShim() {
         }
 
         // A refused subscribe maps the server's status the way nes errors do.
+        // A handler that threw is its own code: 'disconnected' would make a
+        // typo in a join handler read exactly like a dropped network.
         function mapStatus(status) {
             if (status === 403) return 'join_refused';
             if (status === 429) return 'rate_limited';
+            if (status === 402) return 'budget_exhausted';
             if (status >= 400 && status < 500) return 'join_refused';
+            if (status >= 500) return 'handler_failed';
             return 'disconnected';
         }
 
@@ -130,16 +134,43 @@ export function generateDevChannelShim() {
             hot.on('vite:ws:connect', subscribeAll);
         }
 
+        // A page that goes away (closed, reloaded, navigated off) leaves its
+        // channels, as its socket closing does on the server, or an actor
+        // would keep it as a member and never go idle. One the browser keeps
+        // and brings back (the back/forward cache) joins them again.
+        if (hot && typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+            window.addEventListener('pagehide', function () {
+                open.forEach(function (ch) {
+                    if (!ch._admitted) return;
+                    ch._admitted = false;
+                    ch._resume = true;
+                    try {
+                        fetch(API + '/unsubscribe', {
+                            method: 'POST', keepalive: true, credentials: 'same-origin',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ clientId: clientId, channel: ch.name })
+                        }).catch(function () {});
+                    } catch (e) { /* the page is going regardless */ }
+                });
+            });
+            window.addEventListener('pageshow', function (e) {
+                if (e.persisted) subscribeAll();
+            });
+        }
+
         function Channel(name, opts) {
             this.name = name;
-            this._handlers = {};
+            // null-prototype: an event name admits 'constructor' and 'toString',
+            // which resolve through Object.prototype on a plain object
+            this._handlers = Object.create(null);
             this._closed = false;
             this._unavailable = false;
             this._admitted = false;
             this._subscribing = null;   // in-flight subscribe (never rejects)
             this._replaying = false;    // live frames queue behind an in-flight replay
             this._pending = [];
-            this._lastSeq = {};         // concrete channel → last seq delivered
+            this._lastSeq = Object.create(null);          // concrete channel → highest seq seen
+            this._replayedThrough = Object.create(null);  // → how far a replay caught it up
             this._since = (opts && typeof opts.since === 'number') ? opts.since : null;
             this._resume = this._since !== null;   // replay on the next subscribe
         }
@@ -153,12 +184,15 @@ export function generateDevChannelShim() {
             });
         };
 
-        // A frame at or below the last seq delivered for its channel is a
-        // duplicate. Returns whether it was dispatched.
+        // Only a frame the replay already handed over is a duplicate. Seq is
+        // allocated atomically but published separately, so on a real server two
+        // concurrent broadcasts can arrive out of seq order; deduping against
+        // the running max would drop the lower one for good.
+        // Returns whether it was dispatched.
         Channel.prototype._accept = function (frame) {
             if (typeof frame.seq === 'number') {
-                if (frame.seq <= (this._lastSeq[frame.channel] || 0)) return false;
-                this._lastSeq[frame.channel] = frame.seq;
+                if (frame.seq <= (this._replayedThrough[frame.channel] || 0)) return false;
+                if (frame.seq > (this._lastSeq[frame.channel] || 0)) this._lastSeq[frame.channel] = frame.seq;
             }
             this._dispatch(frame.event, frame.payload, frame);
             return true;
@@ -229,15 +263,29 @@ export function generateDevChannelShim() {
                         var current = typeof data.current === 'number' ? data.current : 0;
                         var oldest = typeof data.oldest === 'number' ? data.oldest : null;
                         if (current < last) {
-                            // the channel's counter restarted (idle channel): nothing seen applies
+                            // the counter restarted (an idle channel's key expired,
+                            // or redis was flushed): nothing seen applies
                             delete self._lastSeq[concrete];
+                            delete self._replayedThrough[concrete];
                             last = 0;
                         } else if (current > last && (oldest === null || oldest > last + 1)) {
                             self._emitError(channelError('replay_gap', 'Frames on "' + concrete + '" after seq ' + last + ' are no longer buffered', concrete));
                         }
+                        // the mark queued live frames dedupe against: what the
+                        // page already held, raised as the replay hands frames
+                        // over. Set before the loop, so a frame at or below
+                        // that seq is dropped rather than dispatched twice.
+                        self._replayedThrough[concrete] = last;
                         (data.frames || []).forEach(function (frame) {
-                            if (!self._closed && frame && frame.channel === concrete && self._accept(frame)) delivered++;
+                            if (self._closed || !frame || frame.channel !== concrete) return;
+                            if (self._accept(frame)) delivered++;
+                            if (typeof frame.seq === 'number' && frame.seq > self._replayedThrough[concrete]) self._replayedThrough[concrete] = frame.seq;
                         });
+                    }).catch(function (err) {
+                        // a read refused for one channel (over the inbound rate,
+                        // say) is reported on that channel and must not throw
+                        // away the others, as on the server
+                        self._emitError(err && err.code ? err : channelError('disconnected', String((err && err.message) || err), concrete));
                     });
                 });
             }, Promise.resolve()).then(function () {
@@ -307,7 +355,9 @@ export function generateDevChannelShim() {
                 if (res.ok) return res.body ? res.body.result : null;
                 var message = (res.body && res.body.error) || ('Send refused (' + res.status + ')');
                 if (res.status === 429) throw channelError('rate_limited', message, self.name);
+                if (res.status === 402) throw channelError('budget_exhausted', message, self.name);
                 if (res.status >= 400 && res.status < 500) throw channelError('send_refused', message, self.name);
+                if (res.status >= 500) throw channelError('handler_failed', message, self.name);
                 throw channelError('disconnected', message, self.name);
             });
         };
@@ -317,7 +367,7 @@ export function generateDevChannelShim() {
             this._closed = true;
             var i = open.indexOf(this);
             if (i !== -1) open.splice(i, 1);
-            this._handlers = {};
+            this._handlers = Object.create(null);
             var pending = this._subscribing;
             var subscribed = this._admitted || pending;
             this._admitted = false;
@@ -329,6 +379,10 @@ export function generateDevChannelShim() {
             }).catch(function () {});
         };
 
+        // the page and the dev server share this machine's clock
+        informer.serverNow = function () { return Date.now(); };
+        Channel.prototype.serverNow = function () { return Date.now(); };
+
         informer.channel = function (name, opts) {
             if (typeof name !== 'string' || name.length > CHANNEL_NAME_MAX_LENGTH || !CHANNEL_NAME.test(name)) {
                 throw channelError('join_refused', 'Invalid channel name: ' + name);

package/src/dev-channels.js

@@ -18,9 +18,10 @@ import { EventEmitter } from 'node:events';
 // plus the subscribe-side wildcard `rooms/*` (an ordinary name whose LAST
 // segment is `*`; `*` alone is not a name). Everything after `@user/` is one
 // username, verbatim — the server compares the whole remainder to the
-// socket's own — so `@user/*` is refused rather than read as a wildcard.
+// socket's own — so `@user/*` is a valid name for a user called `*`, refused
+// on subscribe as someone else's channel rather than read as a wildcard.
 export const USER_CHANNEL_PREFIX = '@user/';
-export const CHANNEL_NAME = /^(@user\/(?!\*$)\S+|[\w.-]+(\/[\w.-]+)*(\/\*)?)$/;
+export const CHANNEL_NAME = /^(@user\/\S+|[\w.-]+(\/[\w.-]+)*(\/\*)?)$/;
 export const CHANNEL_NAME_MAX_LENGTH = 128;
 // `created`, `order_created`
 export const EVENT_NAME = /^[\w.-]+$/;
@@ -31,8 +32,10 @@ export const EVENT_NAME_MAX_LENGTH = 64;
 export const RESERVED_EVENTS = Object.freeze(['error', 'connected']);
 // config-factory.js app.channels.maxFrameBytes default
 export const MAX_FRAME_BYTES = 65536;
-// Frames kept per channel for `replay(channel, since)`.
+// Frames kept per channel for `replay(channel, since)`, and for how long after
+// the channel's last write (config-factory.js app.channels.replay defaults).
 export const REPLAY_FRAMES = 50;
+export const REPLAY_TTL_MS = 60000;
 // deploy.js CHANNELS_SCHEMA description cap
 const DESCRIPTION_MAX_LENGTH = 500;
 
@@ -59,9 +62,9 @@ export function isChannelName(name) {
     return typeof name === 'string' && name.length <= CHANNEL_NAME_MAX_LENGTH && CHANNEL_NAME.test(name);
 }
 
-/** `rooms/*`: a subscribe-only name covering every channel one level under `rooms/`. */
+/** `rooms/*`: a subscribe-only name covering every channel under `rooms/`. Any trailing `/*` counts, as on the server (`@user/*` too, so nothing can broadcast to it). */
 export function isWildcardName(name) {
-    return isChannelName(name) && !name.startsWith(USER_CHANNEL_PREFIX) && name.endsWith('/*');
+    return typeof name === 'string' && name.endsWith('/*');
 }
 
 export function isEventName(name) {
@@ -156,23 +159,32 @@ export function validateChannels(block) {
  * @param {string} [opts.tenant] - frame tenant (the plugin knows none; defaults to 'dev')
  * @param {string} [opts.appId] - the dev app id (the mocked `report.id`)
  * @param {string} [opts.logPrefix] - console prefix
+ * @param {Function} [opts.now] - clock in ms (tests)
  * @returns {{ emitter: EventEmitter, broadcast: Function, relay: Function, replay: Function, tenant: string, appId: string }}
  */
-export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', logPrefix = '[app-channel]' } = {}) {
+export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', logPrefix = '[app-channel]', now = Date.now } = {}) {
     const emitter = new EventEmitter();
-    // channel name → { seq, frames }: the monotonic counter and the last
-    // REPLAY_FRAMES frames, oldest first.
+    // channel name → { seq, frames, writtenAt }: the monotonic counter and the
+    // last REPLAY_FRAMES frames, oldest first, with the time of the last write.
     const buffers = new Map();
 
     function bufferFor(channel) {
         let buffer = buffers.get(channel);
         if (!buffer) {
-            buffer = { seq: 0, frames: [] };
+            buffer = { seq: 0, frames: [], writtenAt: 0 };
             buffers.set(channel, buffer);
         }
         return buffer;
     }
 
+    // The server's PEXPIRE on the buffer key: the whole buffer goes
+    // REPLAY_TTL_MS after its last write, while the seq counter stays (it has
+    // its own, far longer life).
+    function liveFrames(buffer) {
+        if (buffer.frames.length && now() - buffer.writtenAt >= REPLAY_TTL_MS) buffer.frames = [];
+        return buffer.frames;
+    }
+
     // Validate and publish one §1.1 frame. Synchronous so the manifest relay
     // can run inside a synchronous emit(); throws the server's error codes.
     // `replay: false` keeps the frame out of the channel's replay buffer (it
@@ -196,10 +208,13 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
 
         const buffer = bufferFor(channel);
         buffer.seq += 1;
-        const frame = { tenant, appId, channel, event, payload: message, seq: buffer.seq, at: Date.now() };
+        const at = now();
+        const frame = { tenant, appId, channel, event, payload: message, seq: buffer.seq, at };
         if (replay !== false) {
-            buffer.frames.push(frame);
-            if (buffer.frames.length > REPLAY_FRAMES) buffer.frames.shift();
+            const frames = liveFrames(buffer);
+            frames.push(frame);
+            if (frames.length > REPLAY_FRAMES) frames.shift();
+            buffer.writtenAt = at;
         }
         emitter.emit(BROADCAST_EVENT, frame);
         return frame;
@@ -241,7 +256,9 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
      * first, with the smallest seq still buffered (null when nothing is) and
      * the channel's current seq (0 before its first frame), so the page can
      * tell a gap from a quiet channel. Dev counters never restart, so
-     * `current >= since` for any seq the page has seen.
+     * `current >= since` for any seq the page has seen. An expired buffer
+     * answers no frames and no oldest with the counter intact, which a page
+     * that saw an earlier seq reads as a gap.
      *
      * @param {string} channel
      * @param {number} [since] - the last seq the page has seen
@@ -250,10 +267,11 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
     function replay(channel, since = 0) {
         const buffer = buffers.get(channel);
         if (!buffer) return { frames: [], oldest: null, current: 0 };
+        const frames = liveFrames(buffer);
         const from = Number(since) || 0;
         return {
-            frames: buffer.frames.filter(f => f.seq > from),
-            oldest: buffer.frames.length ? buffer.frames[0].seq : null,
+            frames: frames.filter(f => f.seq > from),
+            oldest: frames.length ? frames[0].seq : null,
             current: buffer.seq
         };
     }