@entrinsik/vite-plugin-informer 2.10.0 → 2.11.0

package/src/dev-channel-shim.js

@@ -1,25 +1,32 @@
-import { CHANNEL_NAME, CHANNEL_NAME_MAX_LENGTH, DEV_CHANNEL_EVENT } from './dev-channels.js';
+import { CHANNEL_NAME, CHANNEL_NAME_MAX_LENGTH, EVENT_NAME, EVENT_NAME_MAX_LENGTH, RESERVED_EVENTS, USER_CHANNEL_PREFIX, DEV_CHANNEL_EVENT, DEV_CHANNEL_API } from './dev-channels.js';
 
 /**
- * The dev `__INFORMER__.channel(name)` mock: the App Channels client surface
- * (App API v2 §1.9) with the same synchronous name check, `on(event, fn)` →
- * `fn(payload, frame)` dispatch by `frame.event`, unsubscribe fn, `error`
- * codes (`join_refused` | `disconnected` | `not_supported`; `rate_limited`
- * never happens locally), phase-1 `send()` rejection and idempotent
- * `close()` as the origin-mode shim in html-utils.js generateChannelShim.
+ * The dev `__INFORMER__.channel(name, opts)` mock: the App Channels client
+ * surface (App API v2 §1.9) as the origin-mode shim in html-utils.js
+ * generateChannelShim implements it —
  *
- * Transport: production subscribes each channel over a nes socket minted
- * from `/_socket`. Dev has no such socket, and opening one would mean a
- * second websocket, a `ws: true` proxy and a credential the dev server
- * cannot mint. Frames instead ride Vite's own dev websocket as the custom
- * event DEV_CHANNEL_EVENT (`server.ws.send({ type: 'custom', ... })` on the
- * node side, `import.meta.hot.on(...)` here) and are filtered by channel
- * name on the page. Vite owns reconnection; a drop surfaces to every open
- * channel as `disconnected`, the way a lost nes socket does.
+ *   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.close();
+ *
+ * Transport: production subscribes each channel over a nes socket; dev POSTs
+ * subscribe / unsubscribe / send to DEV_CHANNEL_API, where the matching
+ * channels/ handler runs (dev-channel-handlers.js). Frames ride Vite's own dev
+ * websocket as the custom event DEV_CHANNEL_EVENT and reach every page; a
+ * channel dispatches only once its subscribe was admitted, matching frames by
+ * exact name or, for a `rooms/*` wildcard, by the frame's wildcard parents.
+ * Every frame carries a per-channel `seq`; after a dropped socket the shim
+ * re-subscribes on `vite:ws:connect` (or the next `on()`), replays from the
+ * last seq it saw via GET /replay, drops what it already delivered, and
+ * reports `replay_gap` when the buffer no longer reaches back that far.
  *
  * Returned as source (an `installDevChannels(hot, informer)` function
  * declaration) so it can be evaluated in a test `vm` against a fake hot
- * context, the same way the server spec drives the production shim.
+ * context and a fake fetch, the same way the server spec drives the
+ * production shim.
  */
 export function generateDevChannelShim() {
     return `
@@ -27,50 +34,143 @@ export function generateDevChannelShim() {
     function installDevChannels(hot, informer, unavailableReason) {
         var CHANNEL_NAME = /${CHANNEL_NAME.source}/;
         var CHANNEL_NAME_MAX_LENGTH = ${CHANNEL_NAME_MAX_LENGTH};
+        var EVENT_NAME = /${EVENT_NAME.source}/;
+        var EVENT_NAME_MAX_LENGTH = ${EVENT_NAME_MAX_LENGTH};
+        var RESERVED_EVENTS = ${JSON.stringify(RESERVED_EVENTS)};
+        var USER_PREFIX = '${USER_CHANNEL_PREFIX}';
         var FRAME_EVENT = '${DEV_CHANNEL_EVENT}';
-        var open = [];          // channels holding at least one handler
+        var API = '${DEV_CHANNEL_API}';
+        var clientId = newClientId();   // identifies this page to the dev server
+        var open = [];                  // channels holding at least one handler
+
+        function newClientId() {
+            var c = typeof crypto !== 'undefined' ? crypto : null;
+            if (c && typeof c.randomUUID === 'function') return c.randomUUID();
+            return Math.random().toString(36).slice(2) + Date.now().toString(36);
+        }
 
-        function channelError(code, message) {
+        function channelError(code, message, channel) {
             var e = new Error(message);
             e.code = code;
+            if (channel) e.channel = channel;
             return e;
         }
 
+        function isWildcard(name) {
+            return name.indexOf(USER_PREFIX) !== 0 && name.slice(-2) === '/*';
+        }
+
+        // The wildcard names a frame on \`channel\` also belongs to: a/b/c → a/b/*, a/*.
+        function wildcardParents(channel) {
+            if (channel.indexOf(USER_PREFIX) === 0) return [];
+            var segments = channel.split('/');
+            var parents = [];
+            for (var i = segments.length - 1; i >= 1; i--) parents.push(segments.slice(0, i).join('/') + '/*');
+            return parents;
+        }
+
+        function covers(ch, frameChannel) {
+            if (ch.name === frameChannel) return true;
+            return isWildcard(ch.name) && wildcardParents(frameChannel).indexOf(ch.name) !== -1;
+        }
+
+        // A refused subscribe maps the server's status the way nes errors do.
+        function mapStatus(status) {
+            if (status === 403) return 'join_refused';
+            if (status === 429) return 'rate_limited';
+            if (status >= 400 && status < 500) return 'join_refused';
+            return 'disconnected';
+        }
+
+        function call(method, path, body) {
+            var opts = { method: method, credentials: 'same-origin', headers: {} };
+            if (body !== undefined) {
+                opts.headers['Content-Type'] = 'application/json';
+                opts.body = JSON.stringify(body);
+            }
+            return fetch(API + path, opts).then(function (res) {
+                return res.text().then(function (text) {
+                    var data = null;
+                    try { data = text ? JSON.parse(text) : null; } catch (e) { data = null; }
+                    return { ok: res.ok, status: res.status, body: data };
+                });
+            }, function (e) {
+                throw channelError('disconnected', 'The dev server could not be reached: ' + ((e && e.message) || e));
+            });
+        }
+
+        function refusal(res, channel, fallback) {
+            return channelError(mapStatus(res.status), (res.body && res.body.error) || (fallback + ' (' + res.status + ')'), channel);
+        }
+
         function deliver(frame) {
             if (!frame || typeof frame.channel !== 'string') return;
             open.slice().forEach(function (ch) {
-                if (ch.name === frame.channel) ch._deliver(frame);
+                if (covers(ch, frame.channel)) ch._deliver(frame);
             });
         }
 
+        // A dropped socket: every open channel reports it and re-subscribes on
+        // reconnect, replaying from the last seq it saw.
         function dropAll() {
             open.slice().forEach(function (ch) {
-                ch._emitError(channelError('disconnected', 'The dev server connection was lost'));
+                ch._admitted = false;
+                ch._resume = true;
+                ch._emitError(channelError('disconnected', 'The dev server connection was lost', ch.name));
             });
         }
 
+        function subscribeAll() {
+            open.slice().forEach(function (ch) { ch._subscribe(); });
+        }
+
         if (hot) {
             hot.on(FRAME_EVENT, deliver);
             hot.on('vite:ws:disconnect', dropAll);
+            hot.on('vite:ws:connect', subscribeAll);
         }
 
-        function Channel(name) {
+        function Channel(name, opts) {
             this.name = name;
             this._handlers = {};
             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._since = (opts && typeof opts.since === 'number') ? opts.since : null;
+            this._resume = this._since !== null;   // replay on the next subscribe
         }
 
-        Channel.prototype._deliver = function (frame) {
-            if (this._closed) return;
-            var list = this._handlers[frame.event];
+        Channel.prototype._dispatch = function (event, payload, frame) {
+            var list = this._handlers[event];
             if (!list) return;
             list.slice().forEach(function (fn) {
-                try { fn(frame.payload, frame); }
+                try { fn(payload, frame); }
                 catch (e) { console.error('[Informer] channel handler failed:', e); }
             });
         };
 
+        // A frame at or below the last seq delivered for its channel is a
+        // duplicate. 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;
+            }
+            this._dispatch(frame.event, frame.payload, frame);
+            return true;
+        };
+
+        // A live frame in: only once admitted, and behind any in-flight replay.
+        Channel.prototype._deliver = function (frame) {
+            if (this._closed || !this._admitted) return false;
+            if (this._replaying) { this._pending.push(frame); return false; }
+            return this._accept(frame);
+        };
+
         Channel.prototype._emitError = function (err) {
             if (this._closed) return;
             var list = this._handlers.error;
@@ -84,6 +184,75 @@ export function generateDevChannelShim() {
             });
         };
 
+        Channel.prototype._subscribe = function () {
+            var self = this;
+            if (!hot || this._closed || this._admitted || this._subscribing) return;
+            this._subscribing = call('POST', '/subscribe', { clientId: clientId, channel: this.name }).then(function (res) {
+                if (!res.ok) throw refusal(res, self.name, 'Subscribe refused');
+                if (self._closed) return 0;
+                self._admitted = true;
+                return self._replay();
+            }).then(function (replayed) {
+                self._subscribing = null;
+                if (self._closed || !self._admitted) return;
+                self._dispatch('connected', { replayed: replayed || 0 });
+            }, function (err) {
+                self._subscribing = null;
+                self._emitError(err);
+            });
+        };
+
+        // Catch up from the dev server's buffer: the concrete channels this
+        // handle has seen frames from (or itself, from \`since\` on a first
+        // subscribe). Live frames arriving meanwhile queue behind the replay so
+        // the seq dedupe sees the buffered frames first. Resolves the count delivered.
+        Channel.prototype._replay = function () {
+            var self = this;
+            var since = this._since;
+            this._since = null;
+            var targets = [];
+            if (this._resume) {
+                if (isWildcard(this.name)) targets = Object.keys(this._lastSeq);
+                else if (since !== null || this._lastSeq[this.name] !== undefined) targets = [this.name];
+            }
+            this._resume = false;
+            if (!targets.length) return Promise.resolve(0);
+            var delivered = 0;
+            this._replaying = true;
+            return targets.reduce(function (chain, concrete) {
+                return chain.then(function () {
+                    var last = self._lastSeq[concrete] || 0;
+                    if (since !== null && since > last) last = since;
+                    return call('GET', '/replay?channel=' + encodeURIComponent(concrete) + '&since=' + last).then(function (res) {
+                        if (!res.ok) throw refusal(res, concrete, 'Replay refused');
+                        var data = res.body || {};
+                        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
+                            delete self._lastSeq[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));
+                        }
+                        (data.frames || []).forEach(function (frame) {
+                            if (!self._closed && frame && frame.channel === concrete && self._accept(frame)) delivered++;
+                        });
+                    });
+                });
+            }, Promise.resolve()).then(function () {
+                self._replaying = false;
+                var queued = self._pending;
+                self._pending = [];
+                queued.forEach(function (frame) { self._deliver(frame); });
+                return delivered;
+            }, function (err) {
+                self._replaying = false;
+                self._pending = [];
+                throw err;
+            });
+        };
+
         Channel.prototype.on = function (event, fn) {
             if (this._closed) throw channelError('disconnected', 'The channel is closed');
             if (typeof event !== 'string' || !event) throw new TypeError('channel.on: event name required');
@@ -91,14 +260,29 @@ export function generateDevChannelShim() {
             var list = this._handlers[event] || (this._handlers[event] = []);
             list.push(fn);
             if (open.indexOf(this) === -1) open.push(this);
-            if (!hot && !this._unavailable) {
-                // Not served by the Vite dev server: no frames can ever arrive.
-                // Reported once, asynchronously, like a failed connection.
-                this._unavailable = true;
-                var self = this;
-                Promise.resolve().then(function () {
-                    self._emitError(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available'));
-                });
+            var self = this;
+            if (!hot) {
+                if (!this._unavailable) {
+                    // Not served by the Vite dev server: no frames can ever arrive.
+                    // Reported once, asynchronously, like a failed connection.
+                    this._unavailable = true;
+                    Promise.resolve().then(function () {
+                        self._emitError(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available', self.name));
+                    });
+                }
+            } else if (this._admitted) {
+                // A late listener still learns the channel is up.
+                if (event === 'connected') {
+                    Promise.resolve().then(function () {
+                        if (self._closed || list.indexOf(fn) === -1) return;
+                        try { fn({ replayed: 0 }); }
+                        catch (e) { console.error('[Informer] channel handler failed:', e); }
+                    });
+                }
+            } else {
+                // A use: after a dropped socket, bring every open channel back
+                // before this one registers its own handlers.
+                subscribeAll();
             }
             return function () {
                 var i = list.indexOf(fn);
@@ -106,8 +290,26 @@ export function generateDevChannelShim() {
             };
         };
 
-        Channel.prototype.send = function () {
-            return Promise.reject(channelError('not_supported', 'Sending on a channel is not supported yet'));
+        Channel.prototype.send = function (event, payload) {
+            var self = this;
+            if (this._closed) return Promise.reject(channelError('disconnected', 'The channel is closed', this.name));
+            if (typeof event !== 'string' || !event || event.length > EVENT_NAME_MAX_LENGTH || !EVENT_NAME.test(event) || RESERVED_EVENTS.indexOf(event) !== -1) {
+                return Promise.reject(channelError('send_refused', 'Invalid event name: ' + event, this.name));
+            }
+            if (isWildcard(this.name)) {
+                return Promise.reject(channelError('send_refused', 'Cannot send on a wildcard channel; send to a concrete channel instead', this.name));
+            }
+            if (!hot) return Promise.reject(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available', this.name));
+            // a send right after the first on(): let the subscribe land first
+            return (this._subscribing || Promise.resolve()).then(function () {
+                return call('POST', '/send', { clientId: clientId, channel: self.name, event: event, payload: payload === undefined ? null : payload });
+            }).then(function (res) {
+                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 >= 400 && res.status < 500) throw channelError('send_refused', message, self.name);
+                throw channelError('disconnected', message, self.name);
+            });
         };
 
         Channel.prototype.close = function () {
@@ -116,13 +318,22 @@ export function generateDevChannelShim() {
             var i = open.indexOf(this);
             if (i !== -1) open.splice(i, 1);
             this._handlers = {};
+            var pending = this._subscribing;
+            var subscribed = this._admitted || pending;
+            this._admitted = false;
+            if (!hot || !subscribed) return;
+            var self = this;
+            // after an in-flight subscribe lands, so the server forgets what it just recorded
+            (pending || Promise.resolve()).then(function () {
+                return call('POST', '/unsubscribe', { clientId: clientId, channel: self.name });
+            }).catch(function () {});
         };
 
-        informer.channel = function (name) {
+        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);
             }
-            return new Channel(name);
+            return new Channel(name, opts);
         };
     }`;
 }

package/src/dev-channels.js

@@ -2,8 +2,9 @@ import { EventEmitter } from 'node:events';
 
 /**
  * App Channels in dev: the `broadcast(channel, event, payload)` verb for
- * in-process handlers, and the `channels:` manifest relay that mirrors
- * `emitAppEvent` on the server.
+ * in-process handlers, the `channels:` manifest relay that mirrors
+ * `emitAppEvent` on the server, and the per-channel replay buffer the page
+ * catches up from after a dropped dev websocket.
  *
  * A broadcast validates exactly like the server's `broadcastAppMessage`
  * (app-channel-broadcast.js) — same regexes, limits and error messages — and
@@ -13,21 +14,33 @@ import { EventEmitter } from 'node:events';
  * server-cluster concerns and have no dev counterpart.
  */
 
-// Mirrors of app-channel-broadcast.js: `orders`, `orders/east`, `@user/brad`.
-// Everything after `@user/` is one username, verbatim — the server compares the
-// whole remainder to the socket's own.
-export const CHANNEL_NAME = /^(@user\/\S+|[\w.-]+(\/[\w.-]+)*)$/;
+// Mirrors of app-channel-broadcast.js: `orders`, `orders/east`, `@user/brad`,
+// 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.
+export const USER_CHANNEL_PREFIX = '@user/';
+export const CHANNEL_NAME = /^(@user\/(?!\*$)\S+|[\w.-]+(\/[\w.-]+)*(\/\*)?)$/;
 export const CHANNEL_NAME_MAX_LENGTH = 128;
 // `created`, `order_created`
 export const EVENT_NAME = /^[\w.-]+$/;
 export const EVENT_NAME_MAX_LENGTH = 64;
+// Event names the client owns: `connected` is dispatched after a subscribe is
+// admitted, `error` carries refusals and drops. A handler cannot broadcast,
+// send or export either.
+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)`.
+export const REPLAY_FRAMES = 50;
 // deploy.js CHANNELS_SCHEMA description cap
 const DESCRIPTION_MAX_LENGTH = 500;
 
 // The Vite custom event a frame rides to the page (`hot.on(DEV_CHANNEL_EVENT, ...)`).
 export const DEV_CHANNEL_EVENT = 'informer:channel';
+// Where the page's subscribe / unsubscribe / send / replay calls land on the
+// dev server (see dev-channel-handlers.js).
+export const DEV_CHANNEL_API = '/_dev/channels';
 // The plugin has no tenant identity; frames carry this until it does.
 export const DEV_TENANT = 'dev';
 
@@ -46,23 +59,53 @@ 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/`. */
+export function isWildcardName(name) {
+    return isChannelName(name) && !name.startsWith(USER_CHANNEL_PREFIX) && name.endsWith('/*');
+}
+
 export function isEventName(name) {
     return typeof name === 'string' && name.length <= EVENT_NAME_MAX_LENGTH && EVENT_NAME.test(name);
 }
 
+export function isReservedEvent(name) {
+    return RESERVED_EVENTS.includes(name);
+}
+
+/**
+ * The wildcard names a frame on `channel` is also delivered to, nearest first:
+ * `a/b/c` → `['a/b/*', 'a/*']`. A one-segment name has none, and a `@user/`
+ * channel never matches a wildcard.
+ *
+ * @param {string} channel
+ * @returns {string[]}
+ */
+export function wildcardParents(channel) {
+    if (typeof channel !== 'string' || channel.startsWith(USER_CHANNEL_PREFIX)) return [];
+    const segments = channel.split('/');
+    const parents = [];
+    for (let i = segments.length - 1; i >= 1; i--) {
+        parents.push(`${segments.slice(0, i).join('/')}/*`);
+    }
+    return parents;
+}
+
 // Shaped like the boom error the server throws: message === code, plus the
 // HTTP status it would carry, so a handler can branch on either in dev.
-function channelError(code, statusCode) {
+export function channelError(code, statusCode) {
     const err = new Error(code);
     err.code = code;
     err.statusCode = statusCode;
     return err;
 }
 
+const onRequired = (name) => `channels.${name}: "on" is required — list the events to relay; a channel with nothing to relay needs no declaration`;
+
 /**
  * Validate the shape of a parsed `channels:` block. Returns human-readable
  * error strings (empty when valid). Mirrors deploy.js CHANNELS_SCHEMA so an
- * author sees at boot what the deploy would 400 on.
+ * author sees at boot what the deploy would 400 on: the block declares
+ * relays only, so every entry needs a non-empty `on`.
  *
  * @param {*} block - The raw `channels:` value
  * @returns {string[]} Error messages, one per problem
@@ -71,16 +114,19 @@ export function validateChannels(block) {
     const errors = [];
     if (block === undefined || block === null) return errors;
     if (typeof block !== 'object' || Array.isArray(block)) {
-        return ['channels: must be a map of channel name → { description?, on? }'];
+        return ['channels: must be a map of channel name → { on, description? }'];
     }
     for (const [name, def] of Object.entries(block)) {
-        if (!isChannelName(name)) {
+        if (!isChannelName(name) || isWildcardName(name)) {
             errors.push(`channels: invalid channel name "${name}" (use segments of letters, digits, _ . -, joined by /, max ${CHANNEL_NAME_MAX_LENGTH} chars)`);
             continue;
         }
-        if (def === null || def === undefined) continue;
+        if (def === null || def === undefined) {
+            errors.push(onRequired(name));
+            continue;
+        }
         if (typeof def !== 'object' || Array.isArray(def)) {
-            errors.push(`channels.${name}: must be a map with optional "description" and "on"`);
+            errors.push(`channels.${name}: must be a map with "on" and an optional "description"`);
             continue;
         }
         for (const key of Object.keys(def)) {
@@ -89,12 +135,14 @@ export function validateChannels(block) {
         if (def.description !== undefined && (typeof def.description !== 'string' || def.description.length > DESCRIPTION_MAX_LENGTH)) {
             errors.push(`channels.${name}.description: must be a string of at most ${DESCRIPTION_MAX_LENGTH} chars`);
         }
-        if (def.on !== undefined) {
-            const events = Array.isArray(def.on) ? def.on : [def.on];
-            for (const event of events) {
-                if (!isEventName(event)) {
-                    errors.push(`channels.${name}.on: invalid event name ${JSON.stringify(event)} (letters, digits, _ . -, max ${EVENT_NAME_MAX_LENGTH} chars)`);
-                }
+        const events = def.on === undefined || def.on === null ? [] : [].concat(def.on);
+        if (events.length === 0) {
+            errors.push(onRequired(name));
+            continue;
+        }
+        for (const event of events) {
+            if (!isEventName(event)) {
+                errors.push(`channels.${name}.on: invalid event name ${JSON.stringify(event)} (letters, digits, _ . -, max ${EVENT_NAME_MAX_LENGTH} chars)`);
             }
         }
     }
@@ -108,16 +156,31 @@ 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
- * @returns {{ emitter: EventEmitter, broadcast: Function, relay: Function, tenant: string, appId: string }}
+ * @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]' } = {}) {
     const emitter = new EventEmitter();
+    // channel name → { seq, frames }: the monotonic counter and the last
+    // REPLAY_FRAMES frames, oldest first.
+    const buffers = new Map();
+
+    function bufferFor(channel) {
+        let buffer = buffers.get(channel);
+        if (!buffer) {
+            buffer = { seq: 0, frames: [] };
+            buffers.set(channel, buffer);
+        }
+        return buffer;
+    }
 
     // Validate and publish one §1.1 frame. Synchronous so the manifest relay
     // can run inside a synchronous emit(); throws the server's error codes.
-    function publish(channel, event, payload) {
-        if (!isChannelName(channel)) throw channelError('app_channel_invalid_name', 400);
+    // `replay: false` keeps the frame out of the channel's replay buffer (it
+    // still takes a seq), as broadcastAppMessage does in production.
+    function publish(channel, event, payload, { replay } = {}) {
+        if (!isChannelName(channel) || isWildcardName(channel)) throw channelError('app_channel_invalid_name', 400);
         if (!isEventName(event)) throw channelError('app_channel_invalid_event', 400);
+        if (isReservedEvent(event)) throw channelError('app_channel_reserved_event', 400);
 
         const message = payload === undefined ? null : payload;
         let serialized;
@@ -131,17 +194,24 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
         if (serialized === undefined) throw channelError('app_channel_invalid_payload', 400);
         if (Buffer.byteLength(serialized) > MAX_FRAME_BYTES) throw channelError('app_channel_frame_too_large', 413);
 
-        const frame = { tenant, appId, channel, event, payload: message, at: Date.now() };
+        const buffer = bufferFor(channel);
+        buffer.seq += 1;
+        const frame = { tenant, appId, channel, event, payload: message, seq: buffer.seq, at: Date.now() };
+        if (replay !== false) {
+            buffer.frames.push(frame);
+            if (buffer.frames.length > REPLAY_FRAMES) buffer.frames.shift();
+        }
         emitter.emit(BROADCAST_EVENT, frame);
         return frame;
     }
 
     // The bag member. Async like the sandbox's, so a bad name/event/payload
-    // rejects rather than throws, exactly as it does in production.
-    async function broadcast(channel, event, payload) {
-        const frame = publish(channel, event, payload);
+    // rejects rather than throws, exactly as it does in production; resolves
+    // `{ ok, seq }` like the server, and honors `options.replay`.
+    async function broadcast(channel, event, payload, options) {
+        const frame = publish(channel, event, payload, options && typeof options === 'object' ? options : {});
         console.log(`${logPrefix} broadcast("${channel}", "${event}", ${previewPayload(frame.payload)})`);
-        return { ok: true };
+        return { ok: true, seq: frame.seq };
     }
 
     /**
@@ -166,7 +236,29 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
         }
     }
 
-    return { emitter, broadcast, relay, tenant, appId };
+    /**
+     * The buffered frames of one channel published after `since`, oldest
+     * 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.
+     *
+     * @param {string} channel
+     * @param {number} [since] - the last seq the page has seen
+     * @returns {{ frames: Object[], oldest: number|null, current: number }}
+     */
+    function replay(channel, since = 0) {
+        const buffer = buffers.get(channel);
+        if (!buffer) return { frames: [], oldest: null, current: 0 };
+        const from = Number(since) || 0;
+        return {
+            frames: buffer.frames.filter(f => f.seq > from),
+            oldest: buffer.frames.length ? buffer.frames[0].seq : null,
+            current: buffer.seq
+        };
+    }
+
+    return { emitter, broadcast, relay, replay, tenant, appId };
 }
 
 /**

package/src/dev-platform.js

@@ -8,6 +8,8 @@
  * feature-detects on it sees locally exactly what it sees on an install
  * without the feature. `version` is `'dev'` (not semver) so a floor check
  * treats the dev mirror as "unknown" rather than as any particular release.
+ * `originMode` is on: the dev server behaves like an app served from its own
+ * origin, where live channels work.
  *
  * Override any of it per project with `informer({ mock: { platform: {…} } })`.
  */
@@ -35,6 +37,7 @@ export function devPlatform(overrides = {}) {
     const { capabilities = {}, ...rest } = overrides || {};
     return {
         version: 'dev',
+        originMode: true,
         ...rest,
         capabilities: { ...DEV_CAPABILITIES, ...capabilities }
     };

package/src/env.js

@@ -1,5 +1,5 @@
 import dotenv from 'dotenv';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, parse as parsePath } from 'node:path';
 
 /**
@@ -71,6 +71,22 @@ export function envWritePath({ mode, cwd } = {}) {
     return resolve(dir, useMode ? `.env.${mode}` : '.env');
 }
 
+/**
+ * A variable as defined in the app's OWN env file (the one envWritePath
+ * names), ignoring the shell and any parent .env loadEnv walked up to. Null
+ * when the file is missing or leaves the variable unset or empty.
+ *
+ * @param {string} name
+ * @param {{ mode?: string, cwd?: string }} options
+ * @returns {string|null}
+ */
+export function localEnvValue(name, { mode, cwd } = {}) {
+    const path = envWritePath({ mode, cwd });
+    if (!existsSync(path)) return null;
+    const value = dotenv.parse(readFileSync(path, 'utf8'))[name];
+    return value ? value : null;
+}
+
 /**
  * Parse --mode <name> from a process.argv array.
  *