@entrinsik/vite-plugin-informer 2.7.0 → 2.11.0

package/src/dev-channel-shim.js

@@ -0,0 +1,361 @@
+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, opts)` mock: the App Channels client
+ * surface (App API v2 §1.9) as the origin-mode shim in html-utils.js
+ * generateChannelShim implements it —
+ *
+ *   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 and a fake fetch, the same way the server spec drives the
+ * production shim.
+ */
+export function generateDevChannelShim() {
+    return `
+    // --- App Channels (dev): frames arrive on Vite's dev websocket ---
+    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 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, 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 (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._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, 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._dispatch = function (event, payload, frame) {
+            var list = this._handlers[event];
+            if (!list) return;
+            list.slice().forEach(function (fn) {
+                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;
+            if (!list || !list.length) {
+                console.warn('[Informer] channel "' + this.name + '" ' + err.code + ': ' + err.message);
+                return;
+            }
+            list.slice().forEach(function (fn) {
+                try { fn(err); }
+                catch (e) { console.error('[Informer] channel error handler failed:', e); }
+            });
+        };
+
+        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');
+            if (typeof fn !== 'function') throw new TypeError('channel.on: handler must be a function');
+            var list = this._handlers[event] || (this._handlers[event] = []);
+            list.push(fn);
+            if (open.indexOf(this) === -1) open.push(this);
+            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);
+                if (i !== -1) list.splice(i, 1);
+            };
+        };
+
+        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 () {
+            if (this._closed) return;
+            this._closed = true;
+            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, 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, opts);
+        };
+    }`;
+}
+
+/**
+ * The `<script type="module">` tag that installs the mock on the dev page.
+ * Vite turns an inline module script into an `?html-proxy` module, which is
+ * what gives it a live `import.meta.hot`. Module scripts run in document
+ * order after parsing, so placed at the top of <head> this installs
+ * `channel()` before the app's own module executes.
+ */
+export function renderDevChannelScript({ hub = true } = {}) {
+    // Without INFORMER_URL, configureServer returns before building the channel
+    // hub, so nothing can ever push a frame — but import.meta.hot is still live,
+    // which would leave the shim silent and the author staring at a channel that
+    // simply never delivers. Passing no `hot` routes it through the same
+    // report-once diagnostic, with the reason that actually applies.
+    const install = hub
+        ? 'installDevChannels(import.meta.hot, window.__INFORMER__);'
+        : `installDevChannels(null, window.__INFORMER__, 'Dev channels need INFORMER_URL set for the dev server to relay frames');`;
+    return `<script type="module">
+${generateDevChannelShim()}
+${install}
+</script>`;
+}

package/src/dev-channels.js

@@ -0,0 +1,283 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * App Channels in dev: the `broadcast(channel, event, payload)` verb for
+ * 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
+ * publishes one frame on a plugin-local emitter. The plugin forwards every
+ * frame to the page over Vite's own dev websocket (see index.js); nothing
+ * here touches the network. Rate limiting and the `enabled` switch are
+ * server-cluster concerns and have no dev counterpart.
+ */
+
+// 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';
+
+/** A short, single-line preview of a payload for the dev console (frames may be 64 KiB). */
+export function previewPayload(value, max = 200) {
+    let text;
+    try { text = JSON.stringify(value); } catch { text = String(value); }
+    if (text === undefined) text = 'undefined';
+    return text.length > max ? `${text.slice(0, max)}… (${text.length} chars)` : text;
+}
+
+/** The emitter event a published frame is raised on. */
+export const BROADCAST_EVENT = 'broadcast';
+
+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.
+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: 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
+ */
+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 → { on, description? }'];
+    }
+    for (const [name, def] of Object.entries(block)) {
+        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) {
+            errors.push(onRequired(name));
+            continue;
+        }
+        if (typeof def !== 'object' || Array.isArray(def)) {
+            errors.push(`channels.${name}: must be a map with "on" and an optional "description"`);
+            continue;
+        }
+        for (const key of Object.keys(def)) {
+            if (key !== 'description' && key !== 'on') errors.push(`channels.${name}: unknown key "${key}"`);
+        }
+        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`);
+        }
+        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)`);
+            }
+        }
+    }
+    return errors;
+}
+
+/**
+ * Create the dev channels hub shared by every dev handler bag.
+ *
+ * @param {Object} [opts]
+ * @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, 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.
+    // `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;
+        try {
+            serialized = JSON.stringify(message);
+        } catch {
+            throw channelError('app_channel_invalid_payload', 400);
+        }
+        // A function/symbol serializes to nothing at all; the sandbox membrane
+        // would have refused it before the server ever saw it.
+        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 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; 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, seq: frame.seq };
+    }
+
+    /**
+     * The `channels:` relay (mirror of emitAppEvent): an emit() of an event
+     * listed in a channel's `on` is also broadcast to that channel, same event
+     * name and payload. A dropped relay warns and never fails the emit.
+     *
+     * @param {Object} manifestChannels - the parsed `channels:` block
+     * @param {string} event
+     * @param {*} payload
+     */
+    function relay(manifestChannels, event, payload) {
+        if (!manifestChannels || typeof manifestChannels !== 'object') return;
+        for (const [channel, def] of Object.entries(manifestChannels)) {
+            if (![].concat((def && def.on) || []).includes(event)) continue;
+            try {
+                publish(channel, event, payload);
+                console.log(`${logPrefix} relayed emit("${event}") → channel "${channel}"`);
+            } catch (err) {
+                console.warn(`${logPrefix} relay dropped: channel "${channel}" event "${event}": ${err.message}`);
+            }
+        }
+    }
+
+    /**
+     * 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 };
+}
+
+/**
+ * Build the dev `emit(event, payload)` bag member: a console-logged no-op
+ * (no app_event row in dev) that still runs the manifest relay, so a page
+ * subscribed to a relayed channel sees the frame locally.
+ *
+ * @param {Object} opts
+ * @param {ReturnType<typeof createDevChannels>} opts.channels
+ * @param {Object} opts.manifestChannels - the parsed `channels:` block
+ * @param {string} [opts.logPrefix]
+ * @returns {(event: string, payload?: *) => { ok: true }}
+ */
+export function createDevEmit({ channels, manifestChannels, logPrefix = '[app-event]' }) {
+    return (event, payload) => {
+        // The sandbox bootstrap sends `payload || {}` across the membrane.
+        const body = payload || {};
+        console.log(`${logPrefix} emit("${event}", ${previewPayload(body)})`);
+        channels.relay(manifestChannels, event, body);
+        return { ok: true };
+    };
+}