@entrinsik/vite-plugin-informer 2.7.0-beta.0 → 2.10.0

package/src/compat.js

@@ -0,0 +1,252 @@
+/**
+ * What the CLI needs to know about the Informer it is deploying to.
+ *
+ * The server exposes no route that reports its capability flags —
+ * describePlatform() rides on the app page and on the handler bag, never on the
+ * API — so compatibility is decided from the build version that GET /api/about
+ * reports. That route is `open: true` and has been unchanged across every
+ * release this plugin supports, which makes it the one probe that cannot itself
+ * be a compatibility problem.
+ *
+ * Floors, not probes: each feature names the release that introduced it
+ * server-side. Comparison mirrors the server's own versionSatisfies()
+ * (app/lib/platform-descriptor.js) — hotfix and RC builds carry a prerelease tag
+ * (`2026.1.3-hot2026…`) that plain semver ranks BELOW its base, which would
+ * refuse a feature on the very release that ships it, so only the numeric base
+ * is ever compared.
+ */
+
+/** The release that introduced each app feature server-side. */
+export const FEATURE_FLOORS = Object.freeze({
+    // App Channels: the `channels:` relay block, channels/ handlers, broadcast().
+    channels: '2026.1.3',
+    // The embedding pump: embeddings/ use cases and embed() on the handler bag.
+    embeddings: '2026.1.3',
+    // Staged uploads/downloads: the uploads/downloads services, /view/_uploads
+    // and /view/_downloads, and __INFORMER__.upload() in the page.
+    streams: '2026.1.3',
+    // The platform descriptor itself (window.__INFORMER__.platform and the
+    // handler bag's `platform`). Absent entirely below this floor, which is why
+    // feature detection has to be optional-chained.
+    platform: '2026.1.3',
+    // Server-side enforcement of the manifest's `requires:` block. Below this
+    // floor the CLI is the only thing in the loop that can honour a declared
+    // Informer floor, so it enforces it itself.
+    requiresGate: '2026.1.3'
+});
+
+/**
+ * Source trees whose contents must never reach a browser, paired with the
+ * release whose FOLDER_GATES list first covered them (app/routes/deploy.js).
+ *
+ * A server below the floor does not recognise the directory as server-side, so
+ * isServerSidePath() returns false for it and view-assets.js serves the file to
+ * anyone who can open the app. Uploading these to such a server would publish
+ * the App's workspace SQL and channel authorization logic, so the deploy leaves
+ * them behind instead.
+ *
+ * server/, webhooks/, tools/, mcp/ and migrations/ were gated long before any
+ * release this plugin supports and so need no floor here.
+ */
+export const GATED_SOURCE_DIRS = Object.freeze([
+    Object.freeze({ dir: 'channels', feature: 'channels', holds: 'channel join/leave handlers' }),
+    Object.freeze({ dir: 'embeddings', feature: 'embeddings', holds: 'embedding pump handlers (and the workspace SQL in them)' })
+]);
+
+/**
+ * The leading numeric triple of a build version, as semver.coerce() would read
+ * it: `2026.1.3-hot20260904` -> `2026.1.3`. Returns null when the string is not
+ * a version at all (`dev`), which callers treat as "unknown".
+ *
+ * @param {string} version
+ * @returns {{ major: number, minor: number, patch: number, version: string }|null}
+ */
+export function baseVersion(version) {
+    const match = /^\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(version == null ? '' : version));
+    if (!match) return null;
+    const [major, minor, patch] = [match[1], match[2], match[3]].map(part => Number(part || 0));
+    return { major, minor, patch, version: `${major}.${minor}.${patch}` };
+}
+
+/** -1, 0 or 1, comparing two parsed bases field by field. */
+function compareBase(a, b) {
+    for (const field of ['major', 'minor', 'patch']) {
+        if (a[field] !== b[field]) return a[field] < b[field] ? -1 : 1;
+    }
+    return 0;
+}
+
+/**
+ * Is `version` at or above `floor`? Unknown versions answer `true` — a build
+ * whose version is not semver is a developer build, and gating those would
+ * break the very people who build Informer from source.
+ *
+ * @param {string} version - a build version, as /about reports it
+ * @param {string} floor - a plain `X.Y.Z`
+ * @returns {boolean}
+ */
+export function atLeast(version, floor) {
+    const actual = baseVersion(version);
+    if (!actual) return true;
+    return compareBase(actual, baseVersion(floor)) >= 0;
+}
+
+// The comparator subset a manifest floor realistically uses. Full semver range
+// syntax would mean taking on the `semver` dependency, which this package
+// deliberately does without; anything outside this subset is reported as
+// unevaluated rather than guessed at.
+const RANGE = /^\s*(>=|<=|>|<|\^|~|=)?\s*v?(\d+(?:\.\d+){0,2})\s*$/;
+
+/**
+ * Evaluate a manifest `requires.informer` range against a build version, with
+ * the same coerced-base semantics the server uses.
+ *
+ * @param {string} version - the running build version
+ * @param {string} range - a range from informer.yaml
+ * @returns {{ ok: boolean, unknown: boolean, reason?: string }} `unknown` marks
+ *   a verdict the caller must not act on: an unparseable range, or a build
+ *   version that is not semver.
+ */
+export function satisfiesRange(version, range) {
+    const actual = baseVersion(version);
+    if (!actual) return { ok: true, unknown: true, reason: 'the server did not report a comparable version' };
+
+    const match = RANGE.exec(String(range == null ? '' : range));
+    if (!match) return { ok: true, unknown: true, reason: `"${range}" is not a range this CLI can evaluate` };
+
+    const [, operator = '=', literal] = match;
+    const wanted = baseVersion(literal);
+    const cmp = compareBase(actual, wanted);
+
+    switch (operator) {
+        case '>=': return { ok: cmp >= 0, unknown: false };
+        case '>': return { ok: cmp > 0, unknown: false };
+        case '<=': return { ok: cmp <= 0, unknown: false };
+        case '<': return { ok: cmp < 0, unknown: false };
+        // ^ allows the rest of the major, ~ the rest of the minor. Both still
+        // need the floor met, so a too-old server fails either way.
+        case '^': return { ok: cmp >= 0 && actual.major === wanted.major, unknown: false };
+        case '~': return { ok: cmp >= 0 && actual.major === wanted.major && actual.minor === wanted.minor, unknown: false };
+        default: return { ok: cmp === 0, unknown: false };
+    }
+}
+
+/**
+ * Ask a server what it is. Never throws: a probe that fails leaves the version
+ * unknown, and every gate built on it fails open with a warning rather than
+ * turning an unreachable /about into a failed deploy.
+ *
+ * @param {{ get: (path: string) => Promise<unknown> }} api
+ * @returns {Promise<{ version: string|null, base: string|null, unknown: boolean, supports: (feature: string) => boolean }>}
+ */
+export async function describeServer(api) {
+    let about = null;
+    try {
+        about = await api.get('about');
+    } catch {
+        // A proxy, a WAF, or an auth strategy in front of /about — none of which
+        // say anything about the server's age.
+    }
+
+    const version = (about && typeof about === 'object' && about.version) || null;
+    const base = baseVersion(version);
+
+    return {
+        version,
+        base: base ? base.version : null,
+        unknown: !base,
+        supports: (feature) => atLeast(version, FEATURE_FLOORS[feature] || '0.0.0')
+    };
+}
+
+/** The top-level library directory a collected file belongs to. */
+function topSegment(rel) {
+    return String(rel || '').replace(/^\/+/, '').split('/')[0].toLowerCase();
+}
+
+/**
+ * Decide what a deploy to this server may upload and what the developer has to
+ * be told. Pure, so the whole compatibility matrix is testable without a server.
+ *
+ * @param {Object} opts
+ * @param {{ version: string|null, base: string|null, unknown: boolean, supports: Function }} opts.server
+ * @param {Array<{ abs: string, rel: string }>} opts.files - from collectAppFiles()
+ * @param {Object} opts.manifest - the parsed informer.yaml, or {}
+ * @returns {{ files: Array, warnings: string[], refusal: string|null }}
+ */
+export function planDeploy({ server, files, manifest }) {
+    const warnings = [];
+    const where = server.version ? `Informer ${server.version}` : 'this Informer';
+
+    if (server.unknown) {
+        warnings.push(
+            `Could not read a comparable version from ${server.version ? `"${server.version}"` : 'GET /api/about'}. `
+            + 'Deploying everything on the assumption the server is current — if it is older than 2026.1.3, '
+            + `${GATED_SOURCE_DIRS.map(d => `${d.dir}/`).join(' and ')} will be readable from the App's view URL.`
+        );
+    }
+
+    // 1. Leave behind source trees this server would serve to browsers.
+    let kept = files;
+    for (const { dir, feature, holds } of GATED_SOURCE_DIRS) {
+        if (server.supports(feature)) continue;
+        const dropped = kept.filter(file => topSegment(file.rel) === dir);
+        if (dropped.length === 0) continue;
+        kept = kept.filter(file => topSegment(file.rel) !== dir);
+        warnings.push(
+            `Skipped ${dropped.length} file(s) in ${dir}/ — ${where} predates ${FEATURE_FLOORS[feature]} and does not treat `
+            + `${dir}/ as server-side, so uploading your ${holds} would leave them readable from the App's view URL. `
+            + `The App deploys without them; upgrade the server to ${FEATURE_FLOORS[feature]} to use this feature.`
+        );
+    }
+
+    // 2. Name every feature the App uses that is simply inert here, so a
+    //    successful deploy can't be mistaken for a working one.
+    const uploaded = new Set(kept.map(file => topSegment(file.rel)));
+    if (!server.supports('channels') && isMap(manifest.channels)) {
+        warnings.push(
+            `informer.yaml declares a channels: block, which ${where} ignores (App Channels needs ${FEATURE_FLOORS.channels}). `
+            + 'Nothing is relayed and broadcast() does not reach the page.'
+        );
+    }
+    if (!server.supports('streams') && uploaded.has('server')) {
+        warnings.push(
+            `${where} predates ${FEATURE_FLOORS.streams}: if a handler destructures uploads/downloads from its bag, or the page `
+            + 'calls __INFORMER__.upload() / downloadUrl(), those are undefined here and the staged stream routes answer 404.'
+        );
+    }
+    if (!server.supports('platform')) {
+        warnings.push(
+            `${where} injects no platform descriptor. Feature-detect with optional chaining `
+            + '(`platform?.capabilities?.x`, `window.__INFORMER__.platform?.capabilities?.x`) — a bare '
+            + '`platform.capabilities.x` throws here rather than reporting false.'
+        );
+    }
+
+    return { files: kept, warnings, refusal: refuseOnRequires({ server, manifest, where }) };
+}
+
+/** True for a YAML mapping (not a list, not a scalar). */
+function isMap(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * The manifest's `requires.informer` floor, enforced by the CLI on servers that
+ * do not enforce it themselves. Below FEATURE_FLOORS.requiresGate the server
+ * ignores the block entirely, so without this an App that declared a floor
+ * deploys clean onto a server that cannot run it and fails at runtime instead.
+ *
+ * @returns {string|null} the refusal message, or null to proceed
+ */
+function refuseOnRequires({ server, manifest, where }) {
+    const range = isMap(manifest.requires) && manifest.requires.informer;
+    if (!range || server.supports('requiresGate')) return null;
+
+    const verdict = satisfiesRange(server.version, range);
+    if (verdict.unknown || verdict.ok) return null;
+
+    // No "Deploy refused:" lead-in — bin/deploy.js already prints "Deploy failed:".
+    return `this app requires Informer ${range}, but this server is ${server.version}. `
+        + `Update Informer, or remove the requires.informer floor from informer.yaml if the app can run on ${where}.`;
+}

package/src/deploy.js

@@ -1,5 +1,7 @@
 import { createClient } from './client.js';
 import { collectAppFiles } from './assemble.js';
+import { describeServer, planDeploy } from './compat.js';
+import { loadManifest } from './dev-dependencies.js';
 import { readFile } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
 
@@ -22,6 +24,20 @@ const CHUNK_THRESHOLD = 512 * 1024; // 512KB
  */
 export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, description, icon, id }) {
     const api = createClient({ baseUrl, apiKey, user, pass });
+    const projectRoot = dirname(distDir);
+
+    // 0. Assemble and version-check before touching the app. Both steps below
+    //    are destructive — the snapshot rotates and _clear empties the library —
+    //    so a missing dist/ or a refused version floor has to surface here,
+    //    while the deployed app is still whole.
+    const collected = await collectAppFiles({ distDir, projectRoot });
+    const server = await describeServer(api);
+    const plan = planDeploy({ server, files: collected, manifest: await loadManifest(projectRoot) });
+
+    for (const warning of plan.warnings) {
+        console.warn(`  ! ${warning}`);
+    }
+    if (plan.refusal) throw new Error(plan.refusal);
 
     let entity = null;
     let naturalId = null;
@@ -104,12 +120,14 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     console.log('Clearing existing files...');
     await api.post(`${entityPath}/files/_clear`);
 
-    // 6. Upload the app-library file set: dist output at the library root, plus
-    //    informer.yaml / data-access.yaml and the server/tools/mcp/migrations/webhooks
-    //    source trees. Sourced from the shared collectAppFiles() so a deploy and a
-    //    marketplace publish package byte-identical contents.
+    // 6. Upload the app-library file set assembled in step 0: dist output at the
+    //    library root, plus informer.yaml / data-access.yaml and the
+    //    server/tools/mcp/migrations/webhooks/embeddings source trees, less any
+    //    tree this server is too old to keep out of browsers (see compat.js).
+    //    Sourced from the shared collectAppFiles() so a deploy and a marketplace
+    //    publish package byte-identical contents.
     console.log('Uploading files...');
-    const files = await collectAppFiles({ distDir, projectRoot: dirname(distDir) });
+    const files = plan.files;
 
     for (const { abs, rel } of files) {
         const content = await readFile(abs);
@@ -136,45 +154,9 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         }
     }
 
-    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + tools + agents
+    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + embeddings + tools + agents
     if (apiPrefix === 'apps') {
-        try {
-            console.log('Deploying...');
-            const result = await api.post(`${entityPath}/_deploy`);
-            if (result) {
-                if (result.migrated && result.migrated.length > 0) {
-                    console.log(`  Ran ${result.migrated.length} migration(s): ${result.migrated.join(', ')}`);
-                }
-                if (result.routes && result.routes.length > 0) {
-                    console.log(`  Registered ${result.routes.length} server route(s):`);
-                    for (const r of result.routes) {
-                        console.log(`    ${r}`);
-                    }
-                }
-                if (result.webhooks && result.webhooks.length > 0) {
-                    console.log(`  Registered ${result.webhooks.length} webhook(s):`);
-                    for (const r of result.webhooks) {
-                        console.log(`    ${r}`);
-                    }
-                }
-                if (result.tools && result.tools.length > 0) {
-                    console.log(`  Registered ${result.tools.length} tool(s): ${result.tools.join(', ')}`);
-                }
-                if (result.mcpTools && result.mcpTools.length > 0) {
-                    console.log(`  Registered ${result.mcpTools.length} MCP tool(s): ${result.mcpTools.join(', ')}`);
-                }
-                if (result.agents && result.agents.length > 0) {
-                    console.log(`  Deployed ${result.agents.length} agent(s): ${result.agents.join(', ')}`);
-                }
-            }
-        } catch (err) {
-            if (err.status === 404) {
-                // Server may not support _deploy yet — ignore
-            } else {
-                const detail = err.body || err.message;
-                console.error(`  Deploy failed: ${detail}`);
-            }
-        }
+        await runServerDeploy(api, entityPath);
     }
 
     // 13. Print URL and return UUID for saving
@@ -188,6 +170,97 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     return { id: entity.id, url: entityUrl };
 }
 
+/**
+ * POST `_deploy`: run migrations, scan/bundle server routes, webhooks, tools and
+ * agents, and claim the app as platform-managed.
+ *
+ * Exported for its own tests. This is the step whose failure modes are silent —
+ * everything it does is invisible in the CLI output when it doesn't happen.
+ *
+ * @param {{post: (path: string, body?: unknown) => Promise<unknown>}} api
+ * @param {string} entityPath e.g. `apps/my-app`
+ */
+export async function runServerDeploy(api, entityPath) {
+    try {
+        console.log('Deploying...');
+        // `managed: true` claims the app as platform-managed (origin
+        // 'deployed'), which locks builder editing so a UI edit can't drift
+        // from this project. Opt-in: the server leaves an app editable when the
+        // flag is absent, so the GO admin panel's Redeploy and the builder's
+        // Save can share this route without converting user-built apps. See
+        // app/routes/deploy.js.
+        const result = await api.post(`${entityPath}/_deploy`, { managed: true });
+        if (result === null) {
+            // api.post turns a 404 into null instead of throwing, so this is the
+            // only place it can be caught. Files uploaded, but migrations, server
+            // routes, webhooks and the managed claim did NOT run — and a missing
+            // route is far more often a wrong app id or a proxy path rewrite than
+            // a server too old to have _deploy. Falling through here prints
+            // "Published ..." and exits 0 on a half-finished deploy.
+            throw new Error(
+                `Deploy endpoint not found at ${entityPath}/_deploy. The app may not exist on this server, `
+                + `the path may be rewritten by a proxy, or the server may predate _deploy. `
+                + `Files were uploaded, but migrations, server routes and the managed claim did not run.`
+            );
+        }
+        if (result.migrated && result.migrated.length > 0) {
+            console.log(`  Ran ${result.migrated.length} migration(s): ${result.migrated.join(', ')}`);
+        }
+        if (result.routes && result.routes.length > 0) {
+            console.log(`  Registered ${result.routes.length} server route(s):`);
+            for (const r of result.routes) {
+                console.log(`    ${r}`);
+            }
+        }
+        if (result.webhooks && result.webhooks.length > 0) {
+            console.log(`  Registered ${result.webhooks.length} webhook(s):`);
+            for (const r of result.webhooks) {
+                console.log(`    ${r}`);
+            }
+        }
+        if (result.channelHandlers && result.channelHandlers.length > 0) {
+            console.log(`  Registered ${result.channelHandlers.length} channel handler(s):`);
+            for (const c of result.channelHandlers) {
+                console.log(`    ${c}`);
+            }
+        }
+        if (result.channels && result.channels.length > 0) {
+            console.log(`  Relaying events to ${result.channels.length} channel(s): ${result.channels.join(', ')}`);
+        }
+        if (result.tools && result.tools.length > 0) {
+            console.log(`  Registered ${result.tools.length} tool(s): ${result.tools.join(', ')}`);
+        }
+        if (result.mcpTools && result.mcpTools.length > 0) {
+            console.log(`  Registered ${result.mcpTools.length} MCP tool(s): ${result.mcpTools.join(', ')}`);
+        }
+        if (result.agents && result.agents.length > 0) {
+            console.log(`  Deployed ${result.agents.length} agent(s): ${result.agents.join(', ')}`);
+        }
+        // Advisory findings the server accumulated. The deploy still
+        // succeeded — but silently dropping these leaves authors debugging
+        // mystery responses the server already diagnosed for them.
+        if (result.routeShadowWarnings && result.routeShadowWarnings.length > 0) {
+            console.warn(`  ⚠ ${result.routeShadowWarnings.length} route shadow warning(s):`);
+            for (const w of result.routeShadowWarnings) {
+                console.warn(`    ${w}`);
+            }
+        }
+        if (result.partialFailures && result.partialFailures.length > 0) {
+            console.warn(`  ⚠ ${result.partialFailures.length} non-fatal deploy phase failure(s):`);
+            for (const f of result.partialFailures) {
+                console.warn(`    [${f.phase}] ${f.error}`);
+            }
+        }
+        return result;
+    } catch (err) {
+        // Rethrow: a failed deploy is a failed publish. Logging and falling
+        // through prints "Published ... files" and exits 0, so CI goes green on
+        // an app whose migrations never ran. bin/deploy.js turns this into exit 1.
+        const detail = err.body || err.message;
+        throw new Error(`Deploy failed: ${detail}`);
+    }
+}
+
 function formatSize(bytes) {
     if (bytes < 1024) return `${bytes} B`;
     if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;

package/src/dev-channel-shim.js

@@ -0,0 +1,150 @@
+import { CHANNEL_NAME, CHANNEL_NAME_MAX_LENGTH, DEV_CHANNEL_EVENT } from './dev-channels.js';
+
+/**
+ * The dev `__INFORMER__.channel(name)` mock: the App Channels client surface
+ * (App API v2 §1.9) with the same synchronous name check, `on(event, fn)` →
+ * `fn(payload, frame)` dispatch by `frame.event`, unsubscribe fn, `error`
+ * codes (`join_refused` | `disconnected` | `not_supported`; `rate_limited`
+ * never happens locally), phase-1 `send()` rejection and idempotent
+ * `close()` as the origin-mode shim in html-utils.js generateChannelShim.
+ *
+ * Transport: production subscribes each channel over a nes socket minted
+ * from `/_socket`. Dev has no such socket, and opening one would mean a
+ * second websocket, a `ws: true` proxy and a credential the dev server
+ * cannot mint. Frames instead ride Vite's own dev websocket as the custom
+ * event DEV_CHANNEL_EVENT (`server.ws.send({ type: 'custom', ... })` on the
+ * node side, `import.meta.hot.on(...)` here) and are filtered by channel
+ * name on the page. Vite owns reconnection; a drop surfaces to every open
+ * channel as `disconnected`, the way a lost nes socket does.
+ *
+ * Returned as source (an `installDevChannels(hot, informer)` function
+ * declaration) so it can be evaluated in a test `vm` against a fake hot
+ * context, the same way the server spec drives the production shim.
+ */
+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 FRAME_EVENT = '${DEV_CHANNEL_EVENT}';
+        var open = [];          // channels holding at least one handler
+
+        function channelError(code, message) {
+            var e = new Error(message);
+            e.code = code;
+            return e;
+        }
+
+        function deliver(frame) {
+            if (!frame || typeof frame.channel !== 'string') return;
+            open.slice().forEach(function (ch) {
+                if (ch.name === frame.channel) ch._deliver(frame);
+            });
+        }
+
+        function dropAll() {
+            open.slice().forEach(function (ch) {
+                ch._emitError(channelError('disconnected', 'The dev server connection was lost'));
+            });
+        }
+
+        if (hot) {
+            hot.on(FRAME_EVENT, deliver);
+            hot.on('vite:ws:disconnect', dropAll);
+        }
+
+        function Channel(name) {
+            this.name = name;
+            this._handlers = {};
+            this._closed = false;
+            this._unavailable = false;
+        }
+
+        Channel.prototype._deliver = function (frame) {
+            if (this._closed) return;
+            var list = this._handlers[frame.event];
+            if (!list) return;
+            list.slice().forEach(function (fn) {
+                try { fn(frame.payload, frame); }
+                catch (e) { console.error('[Informer] channel handler failed:', e); }
+            });
+        };
+
+        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.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);
+            if (!hot && !this._unavailable) {
+                // Not served by the Vite dev server: no frames can ever arrive.
+                // Reported once, asynchronously, like a failed connection.
+                this._unavailable = true;
+                var self = this;
+                Promise.resolve().then(function () {
+                    self._emitError(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available'));
+                });
+            }
+            return function () {
+                var i = list.indexOf(fn);
+                if (i !== -1) list.splice(i, 1);
+            };
+        };
+
+        Channel.prototype.send = function () {
+            return Promise.reject(channelError('not_supported', 'Sending on a channel is not supported yet'));
+        };
+
+        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 = {};
+        };
+
+        informer.channel = function (name) {
+            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);
+        };
+    }`;
+}
+
+/**
+ * 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>`;
+}