@entrinsik/vite-plugin-informer 2.11.0 → 2.12.0

package/README.md

@@ -13,6 +13,8 @@ npm run dev                                # local dev against the Informer in .
 npm run deploy                             # assemble + upload + deploy
 ```
 
+`informer-init` leaves an existing `@entrinsik/vite-plugin-informer` entry alone, and writes one only when the dependency is missing — in which case it uses its own version (2.12.0 and later; before that it wrote `^1.0.0`). A project scaffolded earlier still carries `^1.0.0`, which resolves to 1.0.5 and predates everything below: bump it by hand.
+
 ## What a deploy ships
 
 The assembler uploads your built frontend plus these source trees, matching how an App's library is structured in Informer:
@@ -44,7 +46,7 @@ Against an older server the CLI:
 
 A server whose version isn't comparable (a `dev` build, or an `/about` behind a proxy) is treated as current and warned about — gating it would break deploys to builds made from source.
 
-App Channels phase 2 (plugin 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless.
+App Channels phase 2 (plugin ≥ 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless; plugin 2.12.0 aligns its channel semantics with the server's (wildcard gating, replay expiry, and the per-user send budget), so on 2.11.0 the dev mirror has the phase 2 surface but not all of its behavior.
 
 Feature-detect at runtime with optional chaining, since `platform` is absent entirely before 2026.1.3:
 
@@ -118,11 +120,11 @@ const hits = await query(
 
 ### Dev loop
 
-`npm run deploy` uploads `embeddings/` like any other source tree — there is no manifest block to add (plugin ≥ 2.10.0; earlier versions never upload the folder, so the use case silently does not exist on the server). `npm run dev` never runs the pump, and its `embed()` throws an explanation rather than embedding (the dev mirror reports `platform.capabilities.embeddings: false`), so a search route is exercised against a deployed App. Feature-detect with `platform?.capabilities?.embeddings` — `typeof embed === 'function'` is true on both, since the binding exists either way. Then, in the App admin panel, the **Embeddings** tab lists each use case with its pump status (queued, running, up to date, last run, last error, skipped docs) and a **Run now** action; the same surface exists as API routes (`GET /apps/{id}/embeddings`, `POST /apps/{id}/embeddings/{name}/_run`). Deploy, run, read the error, fix, repeat.
+`npm run deploy` uploads `embeddings/` like any other source tree — there is no manifest block to add (plugin ≥ 2.10.0; earlier versions never upload the folder, so the use case silently does not exist on the server). `npm run dev` never runs the pump, and its `embed()` throws an explanation rather than embedding (the dev mirror reports `platform.capabilities.embeddings: false`), so a search route is exercised against a deployed App. Plugin ≥ 2.12.0 can opt in: `informer({ mock: { platform: { capabilities: { embeddings: true } } } })` binds the dev `embed()` to the deployed App's `_embed` route on the configured server (addressed by package.json `informer.id`; the dev credentials need write access to that App, and each call is billed to it), so the query vector under `npm run dev` is the deployed one — same model, same `revision`. The corpus is not: `query()` still reads the dev workspace datasource, which the pump never writes to, so a search route compares a deployed vector against local rows. Feature-detect with `platform?.capabilities?.embeddings` — `typeof embed === 'function'` is true on both, since the binding exists either way. Then, in the App admin panel, the **Embeddings** tab lists each use case with its pump status (queued, running, up to date, last run, last error, skipped docs) and a **Run now** action; the same surface exists as API routes (`GET /apps/{id}/embeddings`, `POST /apps/{id}/embeddings/{name}/_run`). Deploy, run, read the error, fix, repeat.
 
 ### Upgrading an App that already has an `embeddings/` folder
 
-`embeddings/` is a server-side folder from this release on, like `server/`: its files are uploaded with the library, never served to browsers, and scanned as pump handlers. An App that kept anything else there (assets, data files) loses those files in the browser after redeploying with plugin 2.10.0 or later. A `.js` file there that exports `GET` or `POST` but not both fails the deploy; one that exports neither is never scanned as a use case at all and lands as a warning on an otherwise successful deploy. Move such content elsewhere before upgrading; the deploy names every stray entry as a warning.
+`embeddings/` is a server-side folder from Informer 2026.1.3 on, like `server/`: its files are uploaded with the library, never served to browsers, and scanned as pump handlers. An App that kept anything else there (assets, data files) loses those files in the browser after redeploying with plugin 2.10.0 or later. A `.js` file there that exports `GET` or `POST` but not both fails the deploy; one that exports neither is never scanned as a use case at all and lands as a warning on an otherwise successful deploy. Move such content elsewhere before upgrading; the deploy names every stray entry as a warning.
 
 ### Older Informer releases
 

package/bin/init.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { readFile, writeFile, access } from 'node:fs/promises';
 import { resolve, basename } from 'node:path';
 import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
@@ -118,6 +118,16 @@ function prompt(question, defaultValue) {
     });
 }
 
+/**
+ * The devDependency range a fresh scaffold gets. Read inside init() rather than
+ * at module scope so a failure reaches init()'s error handler.
+ */
+async function pluginVersionRange() {
+    const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    if (!version) throw new Error('could not read the version of @entrinsik/vite-plugin-informer; reinstall the plugin');
+    return `^${version}`;
+}
+
 /**
  * Convert package name to friendly display name.
  * "magic-quickbooks-report" -> "Magic Quickbooks Report"
@@ -174,7 +184,8 @@ async function init() {
     // 5. Add plugin to dependencies if not present
     if (!pkg.devDependencies) pkg.devDependencies = {};
     if (!pkg.devDependencies['@entrinsik/vite-plugin-informer']) {
-        pkg.devDependencies['@entrinsik/vite-plugin-informer'] = '^1.0.0';
+        // Float the scaffold on the version that scaffolded it, not a fixed range.
+        pkg.devDependencies['@entrinsik/vite-plugin-informer'] = await pluginVersionRange();
         console.log('Added @entrinsik/vite-plugin-informer to devDependencies');
     }
 

package/index.d.ts

@@ -15,11 +15,25 @@ export interface AppDevBinding {
     app?: string;
 }
 
+/**
+ * What the platform offers the app, as the server injects it
+ * (`window.__INFORMER__.platform`). A mock override merges into the dev
+ * defaults, so naming one capability leaves the rest alone.
+ */
+export interface MockPlatform {
+    version?: string;
+    originMode?: boolean;
+    capabilities?: Record<string, boolean>;
+}
+
 export interface InformerPluginOptions {
     mock?: {
         report?: { id?: string; name?: string };
         theme?: 'light' | 'dark';
         roles?: string[];
+        /** The viewer identity, for testing `@user/<username>` channels as someone else. */
+        user?: { username?: string; displayName?: string };
+        platform?: MockPlatform;
     };
     devBindings?: Record<string, string | AppDevBinding>;
     proxy?: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.11.0",
+    "version": "2.12.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "scripts": {
         "test": "node --test"

package/src/agent-dev.js

@@ -4,15 +4,7 @@ import { parse as parseUrl } from 'node:url';
 import yaml from 'yaml';
 import { manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 import { createDevChannels, createDevEmit } from './dev-channels.js';
-import { devPlatform } from './dev-platform.js';
-
-// embed() is present on a real install even without the embeddings
-// capability, where it throws a written explanation. Mirroring that here
-// keeps the dev failure the same lesson as the deployed one, instead of a
-// bare "embed is not a function" that reads like a missing binding.
-const embed = async () => {
-    throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
-};
+import { devPlatform, createDevEmbed } from './dev-platform.js';
 
 const parseYaml = yaml.parse;
 
@@ -164,7 +156,7 @@ async function readSSE(response) {
  *   behind `broadcast()` and the `channels:` relay (a private one when omitted)
  * @returns {Function} Connect middleware
  */
-export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels = createDevChannels() }) {
+export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels = createDevChannels(), platform = devPlatform(), appId = null }) {
 
     // query() — proxies to the workspace _sql endpoint (same as server-routes.js)
     async function query(sql, params) {
@@ -223,6 +215,11 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
         return { status, body, contentType };
     }
 
+    // Throws the written explanation unless the mock platform opts into
+    // embeddings; then posts to the deployed app's _embed route through
+    // apiFetch (hoisted below). See createDevEmbed.
+    const embed = createDevEmbed({ platform, apiFetch, appId });
+
     async function apiFetch(path, opts = {}) {
         return await fetchAs(authHeader, path, opts);
     }
@@ -455,7 +452,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
 
                         if (tool) {
                             try {
-                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, log, env, platform: devPlatform() });
+                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, log, env, platform });
                             } catch (err) {
                                 console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
                                 result = { error: err.message };

package/src/dev-bag.js

@@ -1,6 +1,7 @@
 import { loadManifest, manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 import { createDevChannels, createDevEmit } from './dev-channels.js';
-import { devPlatform } from './dev-platform.js';
+import { LIMITS } from './dev-streams.js';
+import { devPlatform, createDevEmbed } from './dev-platform.js';
 
 /**
  * The part of the dev handler bag every surface shares — `server/` routes and
@@ -11,18 +12,33 @@ import { devPlatform } from './dev-platform.js';
  * for channels), the same split the prod sandbox's buildInvokeScript makes.
  */
 
-// embed() is present on a real install even without the embeddings
-// capability, where it throws a written explanation. Mirroring that here
-// keeps the dev failure the same lesson as the deployed one, instead of a
-// bare "embed is not a function" that reads like a missing binding.
-export const embed = async () => {
-    throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
-};
-
 // Cap dev proxy calls at 30s so a hung upstream fails loudly instead of
 // hanging the handler.
 const FETCH_TIMEOUT_MS = 30000;
 
+/**
+ * Read a response body into memory, refusing once it passes `max` and cancelling
+ * the reader so the rest never arrives. `arrayBuffer()` would buffer whatever the
+ * upstream sends before anything could measure it.
+ */
+async function readCapped(resp, max) {
+    if (!resp.body) return Buffer.from(await resp.arrayBuffer());
+    const reader = resp.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel();
+            throw new RangeError(`The upstream body exceeds the ${max} bytes the dev server holds in memory`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+
 /** log(message, data) + log.debug/info/warn/error — the sandbox log surface, to the terminal. */
 export function buildDevLog(prefix = '[app-log]') {
     const logCall = (level, message, data) => {
@@ -65,9 +81,15 @@ export function buildDevUser(user) {
  * @param {string|null} [opts.appToken] - INFORMER_APP_TOKEN for cross-app request()
  * @param {ReturnType<typeof createDevChannels>} [opts.channels] - the dev channels hub
  * @param {string} [opts.logPrefix] - prefix for notify/email/emit console lines
- * @returns {{ query: Function, apiFetch: Function, build: () => Promise<{ manifest: Object, bag: Object }> }}
+ * @param {Object} [opts.platform] - the MERGED platform descriptor (dev defaults
+ *   + mock.platform). The bag must see the same one the browser does, or an app
+ *   that opts into `embeddings` reads the flag as true and still finds embed()
+ *   throwing. Defaults to the bare dev descriptor.
+ * @param {string|null} [opts.appId] - the deployed app's id, for the opt-in
+ *   dev embed()'s call to its `_embed` route
+ * @returns {{ query: Function, apiFetch: Function, build: (opts?: { forwarding?: Object|null }) => Promise<{ manifest: Object, bag: Object }> }}
  */
-export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), logPrefix = '[app]' }) {
+export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), logPrefix = '[app]', platform = devPlatform(), appId = null }) {
     // query() implementation — proxies to the workspace _sql endpoint
     async function query(sql, params) {
         if (!devWorkspaceId) {
@@ -97,7 +119,12 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
         // reject non-canonical shapes here instead of silently accepting them.
         const apiPath = normalizeFetchPath(path);
         if (!apiPath) {
-            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` }, contentType: 'application/json' };
+            // `message` is where every other failure from here puts its
+            // sentence (the synthetic 502 below, and boom's own answers), so
+            // one field read by a caller finds all of them. `error` stays
+            // beside it for anything already reading that.
+            const reason = `Invalid fetch path: ${String(path).slice(0, 80)}`;
+            return { status: 400, body: { message: reason, error: reason }, contentType: 'application/json' };
         }
         const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
@@ -112,13 +139,31 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
         // Read the stream exactly once — `.json()` consumes/locks the body, so a
         // `.text()` fallback would throw "Body is unusable" on any non-JSON
         // response (auth-bounce HTML, proxy error page). Parse in memory
-        // instead — same as prod's unwrapInject.
-        let status, contentType, text;
+        // instead — same as prod's unwrapInject. `raw: true` (I5-13030, a
+        // stream being filled from an integration) keeps the bytes as bytes and
+        // hands the headers back too; the body is still parsed for an error.
+        let status, contentType, text, bytes, headers;
         try {
             const resp = await globalThis.fetch(url, { ...fetchOpts, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
             status = resp.status;
             contentType = resp.headers.get('content-type') || '';
-            text = await resp.text();
+            if (opts.raw) {
+                // Bounded before it is buffered. Prod meters the body mid-stream
+                // and tears the socket down at the first byte past the cap; here
+                // the whole thing lands in memory, so an unbounded read turns a
+                // clean 413 into an OOM'd dev server with nothing naming the
+                // cause. The declared length is the cheap check; the running one
+                // covers a chunked response that declares nothing.
+                const declared = Number(resp.headers.get('content-length'));
+                if (Number.isFinite(declared) && declared > LIMITS.maxUploadBytes) {
+                    throw new RangeError(`The upstream body is ${declared} bytes; the dev server holds at most ${LIMITS.maxUploadBytes} in memory`);
+                }
+                bytes = await readCapped(resp, LIMITS.maxUploadBytes);
+                headers = Object.fromEntries(resp.headers.entries());
+                text = status >= 400 ? bytes.toString('utf8') : '';
+            } else {
+                text = await resp.text();
+            }
         } catch (err) {
             // Transport failure or timeout — fetch throws (TypeError 'fetch failed'
             // with the real reason on err.cause, or a TimeoutError). Return a
@@ -129,7 +174,7 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
         }
         let body;
         try { body = JSON.parse(text); } catch { body = text; }
-        return { status, body, contentType };
+        return opts.raw ? { status, body, contentType, bytes, headers } : { status, body, contentType };
     }
 
     async function apiFetch(path, opts = {}) {
@@ -155,6 +200,11 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
     // won't 500 in production.
     const { notify, email } = buildDevMessaging(logPrefix);
     const log = buildDevLog();
+    // Throws the written explanation a real install gives an app type without
+    // the capability, unless the mock platform opts into embeddings; then it
+    // posts to the deployed app's _embed route through apiFetch. See
+    // createDevEmbed.
+    const embed = createDevEmbed({ platform, apiFetch, appId });
     // markdown helper — passthrough in dev (production uses `marked`)
     const markdown = (text) => text;
 
@@ -162,11 +212,17 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
      * The shared bag for one invocation. The manifest is parsed per call
      * (deps, env and channels all come from that one read) so edits to
      * informer.yaml take effect without a dev-server restart.
+     *
+     * @param {Object} [opts]
+     * @param {Object|null} [opts.forwarding] - the request's stream forwarding
+     *   services (dev-streams.js createStreamServices), so an integration
+     *   request() can send a staged upload or fill a download; only `server/`
+     *   routes have streams, so channel handlers leave it null
      */
-    async function build() {
+    async function build({ forwarding = null } = {}) {
         const manifest = await loadManifest(projectRoot);
         const deps = manifestBlock(manifest, 'dependencies');
-        const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
+        const context = buildDevContext({ deps, apiFetch, devBindings, appFetch, forwarding });
         const env = manifestBlock(manifest, 'env');
 
         // emit() writes no app_event row in dev, but still relays a listed
@@ -177,7 +233,7 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
 
         return {
             manifest,
-            bag: { context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: buildDevCrypto(), markdown, log, env, platform: devPlatform() }
+            bag: { context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: buildDevCrypto(), markdown, log, env, platform }
         };
     }
 

package/src/dev-channel-handlers.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { join } 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';
 
@@ -20,7 +21,7 @@ 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 });
 // 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 +102,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,9 +150,12 @@ 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]' });
+    // 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 }
     const subscriptions = new Map();
     // username → { tokens, ts }
@@ -179,9 +185,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,12 +197,14 @@ 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
@@ -290,6 +298,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();

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';
         }
 
@@ -132,14 +136,17 @@ export function generateDevChannelShim() {
 
         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 +160,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 +239,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 +331,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 +343,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;