@entrinsik/vite-plugin-informer 2.10.0 → 2.12.0

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,36 @@ 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 a valid name for a user called `*`, refused
+// on subscribe as someone else's channel rather than read as a wildcard.
+export const USER_CHANNEL_PREFIX = '@user/';
+export const CHANNEL_NAME = /^(@user\/\S+|[\w.-]+(\/[\w.-]+)*(\/\*)?)$/;
 export const CHANNEL_NAME_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)`, and for how long after
+// the channel's last write (config-factory.js app.channels.replay defaults).
+export const REPLAY_FRAMES = 50;
+export const REPLAY_TTL_MS = 60000;
 // deploy.js CHANNELS_SCHEMA description cap
 const DESCRIPTION_MAX_LENGTH = 500;
 
 // 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 +62,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 under `rooms/`. Any trailing `/*` counts, as on the server (`@user/*` too, so nothing can broadcast to it). */
+export function isWildcardName(name) {
+    return typeof name === 'string' && 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 +117,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 +138,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 +159,40 @@ 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 }}
+ * @param {Function} [opts.now] - clock in ms (tests)
+ * @returns {{ emitter: EventEmitter, broadcast: Function, relay: Function, replay: Function, tenant: string, appId: string }}
  */
-export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', logPrefix = '[app-channel]' } = {}) {
+export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', logPrefix = '[app-channel]', now = Date.now } = {}) {
     const emitter = new EventEmitter();
+    // channel name → { seq, frames, writtenAt }: the monotonic counter and the
+    // last REPLAY_FRAMES frames, oldest first, with the time of the last write.
+    const buffers = new Map();
+
+    function bufferFor(channel) {
+        let buffer = buffers.get(channel);
+        if (!buffer) {
+            buffer = { seq: 0, frames: [], writtenAt: 0 };
+            buffers.set(channel, buffer);
+        }
+        return buffer;
+    }
+
+    // The server's PEXPIRE on the buffer key: the whole buffer goes
+    // REPLAY_TTL_MS after its last write, while the seq counter stays (it has
+    // its own, far longer life).
+    function liveFrames(buffer) {
+        if (buffer.frames.length && now() - buffer.writtenAt >= REPLAY_TTL_MS) buffer.frames = [];
+        return buffer.frames;
+    }
 
     // Validate and publish one §1.1 frame. Synchronous so the manifest relay
     // can run inside a synchronous emit(); throws the server's error codes.
-    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 +206,27 @@ 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 at = now();
+        const frame = { tenant, appId, channel, event, payload: message, seq: buffer.seq, at };
+        if (replay !== false) {
+            const frames = liveFrames(buffer);
+            frames.push(frame);
+            if (frames.length > REPLAY_FRAMES) frames.shift();
+            buffer.writtenAt = at;
+        }
         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 +251,32 @@ 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. An expired buffer
+     * answers no frames and no oldest with the counter intact, which a page
+     * that saw an earlier seq reads as a gap.
+     *
+     * @param {string} channel
+     * @param {number} [since] - the last seq the page has seen
+     * @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 frames = liveFrames(buffer);
+        const from = Number(since) || 0;
+        return {
+            frames: frames.filter(f => f.seq > from),
+            oldest: frames.length ? frames[0].seq : null,
+            current: buffer.seq
+        };
+    }
+
+    return { emitter, broadcast, relay, replay, tenant, appId };
 }
 
 /**

package/src/dev-dependencies.js

@@ -1,3 +1,4 @@
+import { isStreamRef } from './dev-streams.js';
 import { readFile, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import crypto from 'node:crypto';
@@ -387,7 +388,14 @@ export function resolveAppBinding(binding) {
  * @returns {Object} An object keyed by dependency name, values are typed
  *   proxies with methods matching the target's production method surface.
  */
-export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null }) {
+// The integration request route carries a base64 body of at most 50 MB
+// (integration/routes/request.js REQUEST_MAX_BYTES), so a staged stream the dev
+// proxy forwards through it can be at most this many raw bytes — a little less
+// in practice, since the envelope also carries url, headers and params. Pinned
+// to the server constant by test/streams-parity.test.js.
+export const DEV_FORWARD_MAX_BYTES = Math.floor(52428800 * 3 / 4);
+
+export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null, forwarding = null }) {
     const context = {};
     for (const [name, decl] of Object.entries(deps || {})) {
         if (!decl || typeof decl !== 'object') continue;
@@ -417,7 +425,7 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
             : null;
 
         context[name] = targetId
-            ? makeDevProxy({ name, target, targetId, apiFetch })
+            ? makeDevProxy({ name, target, targetId, apiFetch, forwarding })
             : makeUnboundDevProxy({ name, target });
     }
     return context;
@@ -518,7 +526,7 @@ function makeAppDevProxy({ name, binding, appFetch, kind = 'app' }) {
     };
 }
 
-function makeDevProxy({ name, target, targetId, apiFetch }) {
+function makeDevProxy({ name, target, targetId, apiFetch, forwarding = null }) {
     switch (target) {
         case 'dataset':
             return {
@@ -544,7 +552,75 @@ function makeDevProxy({ name, target, targetId, apiFetch }) {
         case 'integration':
             return {
                 async request(payload) {
-                    return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, payload || {}, name, 'integration');
+                    const { data, form, into, ...rest } = payload || {};
+                    const wantsBody = isStreamRef(data, 'upload');
+                    const wantsForm = Boolean(form) && typeof form === 'object' && !Array.isArray(form);
+                    const wantsInto = into !== undefined && into !== null;
+                    // Ahead of the plain-call shortcut below: on its own a
+                    // download handle leaves every flag false, and falling
+                    // through would JSON-POST the handle to the third party as
+                    // the request body. Prod refuses it (app-stream-forwarding.js).
+                    if (isStreamRef(data, 'download')) {
+                        throw dependencyError('request(): only an upload handle can be sent as the body; a download is what a route produces, not what it forwards', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (!wantsBody && !wantsForm && !wantsInto) {
+                        return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, payload || {}, name, 'integration');
+                    }
+                    // Staged streams as bodies (I5-13030). Prod streams them
+                    // through the proxy; dev rides the route's base64 envelope
+                    // with the same request shape, so anything an author sees
+                    // here, deployed code sees too — except the envelope's cap.
+                    if (!forwarding) {
+                        throw dependencyError(`Dependency "${name}" (integration): staged streams are unavailable in this context`, 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (wantsBody && wantsForm) {
+                        throw dependencyError('request(): use either `data` or `form` for the body, not both', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    // A `data` that is not a stream handle is the caller's own
+                    // body: keep it. Mirrors app-stream-forwarding.js — without
+                    // it, request({ data: { q }, into: dl }) sends nothing.
+                    let body = (!wantsBody && !wantsForm && data !== undefined) ? { ...rest, data } : rest;
+                    if (wantsForm && data !== undefined) {
+                        throw dependencyError('request(): use either `data` or `form` for the body, not both', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (wantsBody) {
+                        const upload = forwarding.body(data);
+                        assertForwardable(name, upload.size);
+                        // content-length describes bytes only this side counted;
+                        // content-type stays the caller's to relabel, as in prod.
+                        assertStreamOwnedHeaders(rest.headers, { 'content-length': upload.size }, name);
+                        body = { ...rest, data: upload.bytes.toString('base64'), encoding: 'base64', headers: withDefaultHeader(rest.headers, 'content-type', upload.contentType) };
+                    } else if (wantsForm) {
+                        const { bytes, contentType } = multipart(form, forwarding, name);
+                        assertForwardable(name, bytes.length);
+                        // The boundary is generated in multipart() and nowhere
+                        // else, so content-type is the stream's here; a caller's
+                        // `multipart/form-data` would drop it.
+                        assertStreamOwnedHeaders(rest.headers, { 'content-type': contentType, 'content-length': bytes.length }, name);
+                        body = { ...rest, data: bytes.toString('base64'), encoding: 'base64', headers: withDefaultHeader(rest.headers, 'content-type', contentType) };
+                    }
+                    if (!wantsInto) {
+                        return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, body, name, 'integration');
+                    }
+                    // `into` is claimed before the call, as prod does, so a bad
+                    // target fails without an upstream round trip — and is given
+                    // back on every path that does not deliver a body.
+                    const receiver = forwarding.receiver(into, rest.url);
+                    let answer;
+                    try {
+                        answer = await apiFetch(`integrations/${targetId}/request`, { method: 'POST', body, raw: true });
+                    } catch (err) {
+                        receiver.release();
+                        throw err;
+                    }
+                    const { status, bytes, headers, body: parsed } = answer;
+                    // Prod gates the fill on < 300 (request.js); a 3xx that axios
+                    // did not follow must not be sealed as the file here either.
+                    if (status >= 300) {
+                        receiver.release();
+                        throw dependencyCallError(name, 'integration', status, parsed);
+                    }
+                    return receiver.fill(bytes, headers);
                 }
             };
         default:
@@ -634,6 +710,66 @@ function isBinaryContentType(contentType) {
     return Boolean(ct) && !ct.startsWith('text/') && !ct.includes('json') && !ct.includes('event-stream');
 }
 
+function assertForwardable(name, size) {
+    if (size > DEV_FORWARD_MAX_BYTES) {
+        throw new Error(
+            `Dependency "${name}" (integration): the dev proxy forwards a staged stream through the request route's base64 envelope, which holds at most ${DEV_FORWARD_MAX_BYTES} bytes (this one is ${size}). A deployed app streams it without the cap — test files this size against a deployment.`
+        );
+    }
+}
+
+/**
+ * Refuse a caller-declared header that describes the staged stream, the way
+ * prod's applyStreamHeaders does (modules/integration/routes/request.js).
+ *
+ * Dev sends the body as a base64 envelope and never ships these names, so
+ * without the refusal an author learns a contract that 400s on deploy — or
+ * worse, ships a boundary-less multipart body no upstream can parse.
+ */
+function assertStreamOwnedHeaders(headers, owned, name) {
+    for (const [ownedName, value] of Object.entries(owned)) {
+        const declared = Object.keys(headers || {}).find(k => k.toLowerCase() === ownedName);
+        if (declared && String(headers[declared]) !== String(value)) {
+            throw dependencyError(
+                `request(): \`${declared}\` describes the staged stream and cannot be set by the caller (you sent "${headers[declared]}", the stream is "${value}")`,
+                400, { dependencyName: name, resourceType: 'integration' }
+            );
+        }
+    }
+}
+
+function withDefaultHeader(headers, name, value) {
+    const out = { ...(headers || {}) };
+    if (!Object.keys(out).some(k => k.toLowerCase() === name)) out[name] = value;
+    return out;
+}
+
+/** A multipart/form-data body built here — the plugin ships without form-data. */
+function multipart(form, forwarding, name) {
+    const boundary = `----InformerDevForm${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+    const parts = [];
+    for (const [field, value] of Object.entries(form)) {
+        if (value === undefined || value === null) continue;
+        if (isStreamRef(value, 'download')) {
+            throw dependencyError(`request(): form field "${field}" is a download handle; only uploads can be sent`, 400, { dependencyName: name, resourceType: 'integration' });
+        }
+        if (isStreamRef(value, 'upload')) {
+            const upload = forwarding.body(value);
+            // filenameSchema permits a double quote, which would close the
+            // disposition early and let a filename inject its own part headers.
+            // form-data escapes this for us in prod; here it is hand-rolled.
+            const filename = String(upload.filename || 'upload').replace(/["\r\n]/g, '_');
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"; filename="${filename}"\r\nContent-Type: ${upload.contentType}\r\n\r\n`), upload.bytes, Buffer.from('\r\n'));
+        } else if (typeof value === 'object') {
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"\r\nContent-Type: application/json\r\n\r\n${JSON.stringify(value)}\r\n`));
+        } else {
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"\r\n\r\n${String(value)}\r\n`));
+        }
+    }
+    parts.push(Buffer.from(`--${boundary}--\r\n`));
+    return { bytes: Buffer.concat(parts), contentType: `multipart/form-data; boundary=${boundary}` };
+}
+
 async function devCall(apiFetch, method, path, body, depName, resourceType) {
     const opts = { method };
     if (body !== null && body !== undefined) opts.body = body;

package/src/dev-platform.js

@@ -3,11 +3,14 @@
  * the server injects on `window.__INFORMER__.platform` and on the server
  * handler / tool bag: the Informer build version and the capability flags.
  *
- * Every capability the dev server mirrors is on. `embeddings` is off: the
- * pump and query-time `embed()` need a real Informer, so an app that
- * 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.
+ * Every capability the dev server mirrors is on. `embeddings` is off by
+ * default: the pump needs a real Informer, so an app that feature-detects on
+ * it sees locally exactly what it sees on an install without the feature.
+ * Turning it on binds query-time `embed()` to a deployed app's `_embed` route
+ * (see createDevEmbed); the pump itself is still not mirrored. `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,7 +38,80 @@ export function devPlatform(overrides = {}) {
     const { capabilities = {}, ...rest } = overrides || {};
     return {
         version: 'dev',
+        originMode: true,
         ...rest,
         capabilities: { ...DEV_CAPABILITIES, ...capabilities }
     };
 }
+
+/**
+ * Whatever the response carries by way of an explanation.
+ *
+ * fetchAs returns a parsed JSON body when it can and the raw text when it
+ * cannot (an auth-bounce HTML page, a proxy error page). Boom answers put the
+ * sentence on `message`; fetchAs's own invalid-path synthetic uses `error`.
+ * Reading only `message` drops both of the others and leaves the tautology
+ * `failed (502): HTTP 502` with the text that explained the failure thrown
+ * away.
+ */
+function failureReason(body, status) {
+    if (typeof body === 'string') return body.trim().slice(0, 200) || `HTTP ${status}`;
+    return (body && (body.message || body.error)) || `HTTP ${status}`;
+}
+
+/**
+ * The dev bag's `embed(name, text)`, shared by the server-routes and agent
+ * mirrors so the two cannot drift.
+ *
+ * Off by default: the same written explanation a real install gives an app
+ * type without the capability, so the dev failure reads as the deployed
+ * lesson instead of a bare "embed is not a function".
+ *
+ * Opted in — `informer({ mock: { platform: { capabilities: { embeddings: true } } } })`
+ * — it posts to the deployed app's `_embed` route on the configured server.
+ * That route runs the same host function a deployed handler's `embed()`
+ * runs, so the vector, the revision and the billing are the deployed ones.
+ * The corpus is not: `query()` still goes to the dev workspace datasource,
+ * which the pump never writes to, so a search route compares a deployed
+ * vector against local rows.
+ *
+ * It addresses the app by package.json `informer.id`. `informer-init`
+ * generates that id locally and the first deploy creates the app under it, so
+ * for a scaffolded project it is always set and the question is whether THIS
+ * server has ever had a deploy of it — a 404, answered below with what to do
+ * about it.
+ */
+export function createDevEmbed({ platform, apiFetch, appId }) {
+    if (!(platform && platform.capabilities && platform.capabilities.embeddings)) {
+        return async () => {
+            throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
+        };
+    }
+    return async (name, text) => {
+        if (!appId) {
+            throw new Error('embed() in dev needs an app id to address: set informer.id in package.json (informer-init writes it) and deploy once');
+        }
+        const { status, body } = await apiFetch(`apps/${appId}/embeddings/${encodeURIComponent(String(name))}/_embed`, {
+            method: 'POST',
+            body: { text }
+        });
+
+        if (status === 404) {
+            throw new Error(`embed('${name}') failed (404): the configured server has no app ${appId} with an embeddings use case "${name}". Deploy this project there (npm run deploy) and declare the use case in embeddings/${name}.js.`);
+        }
+        if (status < 200 || status >= 300) {
+            throw new Error(`embed('${name}') failed (${status}): ${failureReason(body, status)}`);
+        }
+        // A 2xx is not yet an answer. globalThis.fetch FOLLOWS redirects, so
+        // an expired INFORMER_API_KEY or an SSO proxy in front of the server
+        // answers 200 with a sign-in page, and a 204 answers nothing at all.
+        // Returned as-is, `result.embedding` is undefined and the failure
+        // surfaces much later as a Postgres parameter-type error inside the
+        // app's own SQL — sending the developer to debug their query for what
+        // is an auth failure.
+        if (!body || !Array.isArray(body.embedding)) {
+            throw new Error(`embed('${name}') got ${status} but no embedding vector — the response did not come from the _embed route. An expired INFORMER_API_KEY or a sign-in proxy in front of the server both answer 200 with a page. Response: ${failureReason(body, status)}`);
+        }
+        return body;
+    };
+}