@entrinsik/vite-plugin-informer 2.7.0 → 2.11.0

package/src/index.js

@@ -1,13 +1,71 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from './client.js';
-import { loadDependencies, validateDependencies, validateDevBindings, resolveAppBinding } from './dev-dependencies.js';
+import { loadDependencies, loadChannels, validateDependencies, validateDevBindings, resolveAppBinding } from './dev-dependencies.js';
 import { buildDeclarations } from './openapi-to-dts.js';
 import { loadEnv, envWritePath } from './env.js';
 import { createMiddleware as createServerRoutes } from './server-routes.js';
 import { createAgentMiddleware } from './agent-dev.js';
+import { createDevChannels, validateChannels, BROADCAST_EVENT, DEV_CHANNEL_EVENT, DEV_CHANNEL_API } from './dev-channels.js';
+import { createDevChannelHandlers, validateChannelHandlers } from './dev-channel-handlers.js';
+import { renderDevChannelScript } from './dev-channel-shim.js';
+import { createStreamStore, createUploadsMiddleware, createDownloadsMiddleware } from './dev-streams.js';
+import { streamsClientSource } from './streams-client.js';
 import { init, migrate } from './workspace.js';
+import { devPlatform } from './dev-platform.js';
+
+/**
+ * The dev `window.__INFORMER__` context: defaults overlaid with the plugin's
+ * `mock` option. Shared by the page injection and the dev channels hub (whose
+ * frames carry `report.id` as the app id).
+ */
+function buildMock(options) {
+    return {
+        report: {
+            id: 'dev-local',
+            name: 'Local Development'
+        },
+        theme: 'light',
+        roles: [],
+        // The viewer identity the server injects (window.__INFORMER__.user);
+        // override with mock.user to test @user/<username> channels as someone else.
+        user: { username: 'dev', displayName: 'Local Developer' },
+        ...options.mock,
+        // What the platform offers, as the server injects it; a mock
+        // override merges into the dev defaults (see dev-platform.js).
+        platform: devPlatform(options.mock && options.mock.platform)
+    };
+}
+
+/**
+ * Occupied-spot check for the dev /api mount: does informer.yaml's
+ * access.apis declare this method+path? Mirrors the server's matchWhitelist
+ * semantics — segment-aware, `*` matches exactly one segment.
+ */
+function manifestOccupies (projectRoot, req) {
+    let entries;
+    try {
+        const raw = parseYaml(readFileSync(resolve(projectRoot, 'informer.yaml'), 'utf8')) || {};
+        entries = (raw.access && Array.isArray(raw.access.apis)) ? raw.access.apis : [];
+    } catch {
+        return false; // no/invalid manifest: nothing is occupied
+    }
+    // Connect strips the mount prefix, so re-add it for whole-path matching.
+    const path = `/api${(req.url || '').split('?')[0]}`;
+    const segments = path.split('/').filter(Boolean);
+    const method = (req.method || 'GET').toUpperCase();
+    return entries.some(entry => {
+        const spec = typeof entry === 'string'
+            ? entry
+            : `${(entry && entry.method) || 'GET'} ${(entry && (entry.url || entry.path)) || ''}`;
+        const parsed = /^([A-Za-z]+)\s+(\S+)$/.exec(String(spec).trim());
+        if (!parsed || parsed[1].toUpperCase() !== method) return false;
+        const want = parsed[2].split('/').filter(Boolean);
+        return want.length === segments.length && want.every((s, i) => s === '*' || s === segments[i]);
+    });
+}
 
 /**
  * Write generated app-dependency type declarations under .informer/ and keep the
@@ -39,7 +97,9 @@ async function writeAppDepTypes (projectRoot, dts) {
  *
  * - Proxies /api requests to the Informer server with Basic auth
  * - Runs server/ route handlers locally via ssrLoadModule (if server/ dir exists)
- * - Injects window.__INFORMER__ context mock in dev mode
+ * - Runs channels/ handlers locally (join / joined / leave / send) behind
+ *   the `channel()` mock injected with the window.__INFORMER__ context in
+ *   dev mode, whose frames arrive over Vite's dev websocket
  * - Sets base to './' so built assets use relative paths
  *
  * @param {Object} [options]
@@ -101,7 +161,12 @@ export default function informer(options = {}) {
                                     Authorization: authHeader
                                 },
                                 ...options.proxy
-                            }
+                            },
+                            // NOTE: no /informer-api mount. The server
+                            // retired that spelling — /api is ONE namespace
+                            // with manifest-driven precedence (a whitelisted
+                            // access.apis path OCCUPIES its spot; everything
+                            // else is the app's own routes), mirrored below.
                         }
                     };
                 }
@@ -185,6 +250,50 @@ export default function informer(options = {}) {
             for (const message of validateDevBindings(deps, options.devBindings || {})) {
                 console.error(`[informer] vite.config.js: ${message}`);
             }
+            // Same for the `channels:` relay block — the deploy 400s on a bad
+            // channel or event name; say so now instead of dropping relays.
+            try {
+                for (const message of validateChannels(await loadChannels(projectRoot))) {
+                    console.error(`[informer] informer.yaml: ${message}`);
+                }
+            } catch (err) {
+                console.warn(`[informer] Could not read informer.yaml channels: ${err.message}`);
+            }
+            // And for channels/ files — the deploy 400s on a stray export or a
+            // path no page can subscribe to.
+            try {
+                for (const message of await validateChannelHandlers(projectRoot)) {
+                    console.error(`[informer] ${message}`);
+                }
+            } catch (err) {
+                console.warn(`[informer] Could not read channels/: ${err.message}`);
+            }
+
+            // App Channels in dev. Handlers' broadcast() (and the `channels:`
+            // relay behind emit()) publish frames on this hub; each frame goes
+            // to the page as a custom event on Vite's own dev websocket, which
+            // the injected `__INFORMER__.channel` mock listens to via
+            // import.meta.hot. Riding the HMR socket means no second websocket,
+            // no `ws: true` on the /api proxy and no socket credential to mint
+            // — the dev server already owns a live connection to every page.
+            // Every page receives every frame; the subscribe loop mounted below
+            // (join / joined / leave / send against channels/ files) is what
+            // tells a page which channels it may dispatch.
+            const channels = createDevChannels({ appId: buildMock(options).report.id });
+            channels.emitter.on(BROADCAST_EVENT, (frame) => {
+                server.ws.send({ type: 'custom', event: DEV_CHANNEL_EVENT, data: frame });
+            });
+            server.middlewares.use(DEV_CHANNEL_API, createDevChannelHandlers(server, {
+                serverOrigin,
+                authHeader,
+                devWorkspaceId,
+                projectRoot,
+                devBindings: options.devBindings || {},
+                appToken,
+                channels,
+                user: buildMock(options).user,
+                roles: (options.mock && options.mock.roles) || []
+            }));
 
             // Generate .d.ts types for bound `target: app` / `target: pack`
             // deps from their published OpenAPI docs, so server/ handlers get
@@ -249,6 +358,16 @@ export default function informer(options = {}) {
                 console.warn(`[informer] app-dependency type generation skipped: ${err.message}`);
             }
 
+            // App streams (I5-12979): the dev origin's /_uploads and /_downloads
+            // — the same protocol the deployed app speaks on its own origin —
+            // backed by one in-memory store the server routes' `uploads` /
+            // `downloads` services share. Mounted regardless of server/: the
+            // client helper is always on __INFORMER__, so a page may stage an
+            // upload before any handler exists to consume it.
+            const streamStore = createStreamStore();
+            server.middlewares.use('/_uploads', createUploadsMiddleware(streamStore));
+            server.middlewares.use('/_downloads', createDownloadsMiddleware(streamStore));
+
             // Mount server-side route handlers if a server/ directory exists
             const serverDir = resolve(projectRoot, 'server');
 
@@ -259,14 +378,31 @@ export default function informer(options = {}) {
                     devWorkspaceId,
                     projectRoot,
                     roles: (options.mock && options.mock.roles) || [],
+                    user: buildMock(options).user,
                     // Dev-only bindings for `target: app` / `target: pack`
                     // slots (app: overrides the manifest defaultBinding; pack:
                     // names the locally-installed pack app). Shape:
                     //   devBindings: { kanban: { app: 'admin:kanban' } }
                     devBindings: options.devBindings || {},
-                    appToken
+                    appToken,
+                    channels,
+                    streamStore
                 });
                 server.middlewares.use('/api/_server', serverRoutes);
+                // Occupied-spot precedence (App API v2, matches production
+                // dispatch in view-api.js): a platform API declared in
+                // informer.yaml's access.apis OCCUPIES its /api path — those
+                // requests skip the local handlers (next() falls through to
+                // the /api proxy above); every unclaimed path dispatches the
+                // app's own routes. The manifest is re-read per request so
+                // edits apply without a restart. Dev limitation: only raw
+                // access.apis entries are consulted (dependency-derived
+                // grants proxy through their typed context slots anyway).
+                // /api/_server stays as the legacy exclusive spelling.
+                server.middlewares.use('/api', (req, res, next) => {
+                    if (manifestOccupies(projectRoot, req)) return next();
+                    return serverRoutes(req, res, next);
+                });
             }
 
             // Mount agent dev middleware if tools/, mcp/, or informer.yaml agents exist
@@ -281,7 +417,8 @@ export default function informer(options = {}) {
                     devWorkspaceId,
                     projectRoot,
                     devBindings: options.devBindings || {},
-                    appToken
+                    appToken,
+                    channels
                 });
                 server.middlewares.use('/api/_agent', agentDev);
             }
@@ -293,22 +430,25 @@ export default function informer(options = {}) {
             handler(html) {
                 if (!isDev) return html;
 
-                const mock = {
-                    report: {
-                        id: 'dev-local',
-                        name: 'Local Development'
-                    },
-                    theme: 'light',
-                    roles: [],
-                    ...options.mock
-                };
+                const mock = buildMock(options);
 
+                // The context is a classic script (synchronous, so it exists
+                // before anything else runs). The streams client (upload /
+                // downloadUrl) rides inside it: the one piece of the mock that is
+                // code, not data, the same helper the deployed page gets,
+                // speaking to the /_uploads and /_downloads mounted in
+                // configureServer. The channel mock follows as a module script
+                // because only a Vite-processed module gets import.meta.hot.
                 const script = `<script>
 (function() {
     'use strict';
     window.__INFORMER__ = ${JSON.stringify(mock)};
+    var __streams = ${streamsClientSource()};
+    window.__INFORMER__.upload = __streams.upload;
+    window.__INFORMER__.downloadUrl = __streams.downloadUrl;
 })();
-</script>`;
+</script>
+${renderDevChannelScript({ hub: Boolean(serverOrigin) })}`;
 
                 // Insert after <head> tag, matching server behavior
                 const headIdx = html.indexOf('<head>');

package/src/server-routes.js

@@ -1,14 +1,12 @@
 import { readdir, stat } from 'node:fs/promises';
-import { join, relative, posix } from 'node:path';
+import { join } from 'node:path';
 import { parse as parseUrl } from 'node:url';
-import { loadDependencies, buildDevContext, loadAppEnv, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
+import { createDevBagBuilder, buildDevUser } from './dev-bag.js';
+import { createDevChannels } from './dev-channels.js';
+import { createStreamStore, createStreamServices, isStreamRef, serveDownload as serveDevDownload } from './dev-streams.js';
 
 const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 
-// Cap dev proxy calls at 30s so a hung upstream fails loudly instead of
-// hanging the handler.
-const FETCH_TIMEOUT_MS = 30000;
-
 // Strict base64 — see view-api.js for the rationale. Mirror kept identical to
 // keep dev and prod behavior aligned, down to the scan: the quantified
 // /^[A-Za-z0-9+/]+={0,2}$/ throws "RangeError: Maximum call stack size
@@ -26,17 +24,19 @@ function isBase64(s) {
 }
 
 /**
- * Convert a file path under server/ to a route path.
+ * Convert a file path under a handler directory to a route path (mirrors the
+ * server's route-scanner.js filePathToRoute).
  *
  * Examples:
- *   server/orders/index.js     -> /orders
- *   server/orders/[id].js      -> /orders/:id
+ *   server/orders/index.js        -> /orders
+ *   server/orders/[id].js         -> /orders/:id
  *   server/orders/[id]/approve.js -> /orders/:id/approve
- *   server/index.js            -> /
+ *   server/index.js               -> /
+ *   channels/rooms/[room].js      -> /rooms/:room   (dirPrefix 'channels')
  */
-function filePathToRoute(filePath) {
+function filePathToRoute(filePath, dirPrefix = 'server') {
     let route = filePath
-        .replace(/^server\//, '')
+        .replace(new RegExp(`^${dirPrefix}/`), '')
         .replace(/\.js$/, '');
 
     route = route.replace(/\[([^\]]+)\]/g, ':$1');
@@ -132,7 +132,7 @@ async function scanRoutes(serverDir) {
     }));
 }
 
-export { filePathToRoute, walkJsFiles };
+export { filePathToRoute, matchRoute, walkJsFiles };
 
 async function walkJsFiles(dir, basePath) {
     const results = [];
@@ -158,6 +158,54 @@ async function walkJsFiles(dir, basePath) {
     return results;
 }
 
+/**
+ * Write a handler's `{ status, headers?, body?, encoding? }` response
+ * descriptor (mirrors app-sandbox.js buildInvokeScript / respondCallback).
+ * The encoding allow-list and contract checks are enforced inside the ivm in
+ * production; replicated here so handlers see the same errors in dev (where
+ * there's no isolate to attribute the throw to). If you change this, mirror
+ * it in modules/app/routes/view-api.js.
+ */
+function sendDescriptor(res, result) {
+    const encoding = typeof result.encoding === 'string' ? result.encoding : null;
+    if (encoding !== null && encoding !== 'base64') {
+        throw new Error(`Unknown response encoding: ${JSON.stringify(encoding)} (expected 'base64' or omitted)`);
+    }
+    if (encoding === 'base64' && typeof result.body !== 'string') {
+        throw new Error(`encoding: 'base64' requires body to be a base64-encoded string, got ${typeof result.body}`);
+    }
+    const responseBody = result.body !== undefined ? result.body : null;
+
+    res.statusCode = result.status || 200;
+    for (const [key, value] of Object.entries(result.headers || {})) {
+        res.setHeader(key, value);
+    }
+
+    if (responseBody === null) {
+        res.end();
+    } else if (encoding === 'base64') {
+        if (!isBase64(responseBody)) {
+            throw new Error('Handler returned malformed base64 body');
+        }
+        res.end(Buffer.from(responseBody, 'base64'));
+    } else if (typeof responseBody === 'string') {
+        // Strings go out verbatim, as prod passes them.
+        if (!res.getHeader('content-type')) {
+            res.setHeader('Content-Type', 'application/json');
+        }
+        res.end(responseBody);
+    } else {
+        if (!res.getHeader('content-type')) {
+            res.setHeader('Content-Type', 'application/json');
+        }
+        res.end(JSON.stringify(responseBody));
+    }
+}
+
+function isDescriptor(value) {
+    return value !== null && typeof value === 'object' && typeof value.status === 'number';
+}
+
 /**
  * Create Connect middleware for dev-mode server route execution.
  *
@@ -170,92 +218,20 @@ async function walkJsFiles(dir, basePath) {
  * @param {string[]} [opts.roles] - dev user roles surfaced on request.roles
  * @param {Object} [opts.devBindings] - dev bindings for `target: app` deps
  * @param {string|null} [opts.appToken] - INFORMER_APP_TOKEN for cross-app request()
+ * @param {ReturnType<typeof createDevChannels>} [opts.channels] - the dev channels hub
+ *   behind `broadcast()` and the `channels:` relay (a private one when omitted)
+ * @param {Object} [opts.streamStore] - dev stream store shared with the /_uploads
+ *   and /_downloads middleware (createStreamStore()); a private one when omitted
  * @returns {Function} Connect middleware
  */
-export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles, devBindings, appToken }) {
+export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles, user, devBindings, appToken, channels = createDevChannels(), streamStore }) {
+    // `@user/${request.user.username}` on the server names the channel the
+    // page subscribes to.
+    const devUser = buildDevUser(user);
     const serverDir = join(projectRoot, 'server');
-
-    // query() implementation — proxies to the workspace _sql endpoint
-    async function query(sql, params) {
-        if (!devWorkspaceId) {
-            throw new Error('query() requires INFORMER_DEV_WORKSPACE. Run: npx informer-workspace init');
-        }
-
-        const resp = await globalThis.fetch(`${serverOrigin}/api/datasources/${devWorkspaceId}/_sql`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', Authorization: authHeader },
-            body: JSON.stringify({ sql, params: params || [] })
-        });
-
-        if (!resp.ok) {
-            const err = await resp.json().catch(() => ({}));
-            const detail = err.message || resp.statusText;
-            throw new Error(`query() failed: ${resp.status} ${detail} (${serverOrigin}/api/datasources/${devWorkspaceId}/_sql)`);
-        }
-
-        const data = await resp.json();
-        return data.rows;
-    }
-
-    // fetch() implementation — proxies API calls to the Informer server
-    async function fetchAs(auth, path, opts = {}) {
-        const method = (opts.method || 'GET').toUpperCase();
-        // Same strict canonicalization as prod (app-sandbox.js normalizeFetchPath);
-        // 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' };
-        }
-        const url = `${serverOrigin}${apiPath}`;
-        const fetchOpts = {
-            method,
-            headers: { Authorization: auth, 'Content-Type': 'application/json', ...(opts.headers || {}) }
-        };
-
-        if (opts.body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
-            fetchOpts.body = JSON.stringify(opts.body);
-        }
-
-        // 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;
-        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();
-        } catch (err) {
-            // Transport failure or timeout — fetch throws (TypeError 'fetch failed'
-            // with the real reason on err.cause, or a TimeoutError). Return a
-            // synthetic 502 so the dependency layer names it (dep + url + cause)
-            // rather than a bare unhandled "fetch failed".
-            const reason = (err.cause && err.cause.message) || err.message;
-            return { status: 502, body: { message: `fetch to ${url} failed: ${reason}` }, contentType: 'application/json' };
-        }
-        let body;
-        try { body = JSON.parse(text); } catch { body = text; }
-        return { status, body, contentType };
-    }
-
-    async function apiFetch(path, opts = {}) {
-        return await fetchAs(authHeader, path, opts);
-    }
-
-    // Cross-app request() targets /api/apps/<id>/view/_/<path>, whose auth accepts
-    // only the token/session strategies — NOT basic auth. In API-key mode the
-    // INFORMER_API_KEY Bearer already satisfies that, so reuse it; under basic
-    // auth a separate API token (INFORMER_APP_TOKEN) is required, and without one
-    // the app proxy's request() throws a pointed error instead of a bare 401.
-    // appFetch also stamps x-informer-app-depth:1 so the target runs one hop deep
-    // and enforces the same one-hop guard it does in production.
-    const appAuth = appToken
-        ? `Bearer ${appToken}`
-        : (authHeader && authHeader.startsWith('Bearer ') ? authHeader : null);
-    const appFetch = appAuth
-        ? async (path, opts = {}) => await fetchAs(appAuth, path, { ...opts, headers: { ...(opts.headers || {}), 'x-informer-app-depth': '1' } })
-        : null;
+    const streams = streamStore || createStreamStore();
+    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]' });
+    const { query } = bagBuilder;
 
     return async function serverRoutesMiddleware(req, res, next) {
         try {
@@ -300,40 +276,6 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 try { body = JSON.parse(rawBody); } catch { body = rawBody; }
             }
 
-            // crypto helper — mirrors the prod sandbox crypto surface
-            const cryptoHelper = buildDevCrypto();
-
-            // log helper — mirrors sandbox log(message, data) + log.info/warn/error/debug
-            const logCall = (level, message, data) => {
-                const msg = typeof message === 'string' ? message : JSON.stringify(message);
-                const args = [`[app-log] [${level}] ${msg}`];
-                if (data) args.push(data);
-                console.log(...args);
-            };
-            const log = Object.assign(
-                (message, data) => logCall('info', message, data),
-                {
-                    debug: (message, data) => logCall('debug', message, data),
-                    info: (message, data) => logCall('info', message, data),
-                    warn: (message, data) => logCall('warn', message, data),
-                    error: (message, data) => logCall('error', message, data)
-                }
-            );
-
-            // markdown helper — passthrough in dev (production uses `marked`)
-            const markdown = (text) => text;
-
-            // emit helper — no-op in dev (logs to console)
-            const emit = (event, payload) => {
-                console.log(`[app-event] emit("${event}",`, JSON.stringify(payload), ')');
-                return { ok: true };
-            };
-
-            // notify/email — delivery is a console-logged no-op in dev, but the
-            // required-field validation mirrors prod so an app that passes here
-            // won't 500 in production.
-            const { notify, email } = buildDevMessaging('[app]');
-
             // Build request context
             const request = {
                 method: req.method.toUpperCase(),
@@ -344,92 +286,75 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 rawBody,
                 headers: req.headers,
                 roles: roles || [],
-                user: {
-                    username: 'dev-user',
-                    displayName: 'Dev User',
-                    email: null,
-                    timezone: null
-                }
+                user: { ...devUser }
             };
 
-            // respond() — sends early response, handler continues in background
+            // App streams (I5-12979): per-invocation uploads/downloads services.
+            // An upload handle passed as a query() parameter is swapped for a
+            // \x bytea literal on the way to the _sql proxy (prod passes the
+            // bytes as a Buffer parameter — same column-typed coercion).
+            const streamServices = createStreamServices({ store: streams, query: devWorkspaceId ? query : null });
+            const streamQuery = async (sql, params) => await query(sql, await streamServices.resolveQueryParams(params || []));
+
+            // Serve a download handle as the response, like view-api.js does
+            // when a handler returns one (single-use, prod headers).
+            function serveDownloadHandle(ref) {
+                const item = streams.get('download', ref.id);
+                if (!item) throw new Error(`Unknown download ${ref.id} — was it discarded?`);
+                // Do NOT force complete: production 404s an unsealed download
+                // (app-streams.js#serveDownload), so forcing it here would hide
+                // a half-written download that fails once deployed.
+                if (!item.complete) {
+                    throw new Error(`Download ${ref.id} was never ended — call end() (or return it) before serving it.`);
+                }
+                serveDevDownload(streams, item, res);
+            }
+
+            // respond() — sends the early response, the handler continues in
+            // the background. A `{ status, headers?, body?, encoding? }`
+            // descriptor is honored as such (app-sandbox.js respondCallback);
+            // anything else is wrapped as 200 JSON; a download handle streams
+            // the staged bytes.
             let responded = false;
-            function respond(earlyBody) {
+            async function respond(earlyBody) {
                 if (responded) return;
+                if (isStreamRef(earlyBody, 'download')) {
+                    // Seal it first, as production does (app-sandbox.js
+                    // respondCallback), then claim the response — not before,
+                    // or a failure here would leave the request unanswered.
+                    await streamServices.endDownload(earlyBody.id);
+                    responded = true;
+                    return serveDownloadHandle(earlyBody);
+                }
                 responded = true;
+                if (isDescriptor(earlyBody)) return sendDescriptor(res, earlyBody);
                 res.statusCode = 200;
                 res.setHeader('Content-Type', 'application/json');
                 res.end(JSON.stringify(earlyBody));
             }
 
-            // Build the dependency-injection context the same way the prod
-            // sandbox does, so handlers using `await context.myDep.method(...)`
-            // work locally. Loaded per request so edits to informer.yaml take
-            // effect without a dev-server restart.
-            const deps = await loadDependencies(projectRoot);
-            const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
-            const env = await loadAppEnv(projectRoot);
+            const { bag } = await bagBuilder.build();
 
             // Call handler — bag mirrors the prod sandbox (see app-sandbox.js).
-            const result = await handler({ request, context, query, fetch: apiFetch, respond, emit, notify, email, crypto: cryptoHelper, markdown, log, env });
+            const result = await handler({ ...bag, request, query: streamQuery, respond, uploads: streamServices.uploads, downloads: streamServices.downloads });
+
+            // Seal any download the handler left open (prod finalizes the same way).
+            await streamServices.finalize();
 
             // If respond() was already called, the response is already sent
             if (responded) return;
 
-            // Normalize response (mirrors app-sandbox.js buildInvokeScript logic).
-            // The encoding allow-list and contract checks are enforced inside the
-            // ivm in production; replicate them here so handlers see the same
-            // errors in dev (where there's no isolate to attribute the throw to).
-            // If you change this, mirror it in modules/app/routes/view-api.js.
-            let status, responseBody, responseHeaders, encoding;
+            // A returned download handle streams as the response.
+            if (isStreamRef(result, 'download')) return serveDownloadHandle(result);
 
+            // Normalize the return value (mirrors app-sandbox.js buildInvokeScript).
             if (result === undefined || result === null) {
-                status = 204;
-                responseBody = null;
-                responseHeaders = {};
-            } else if (typeof result === 'object' && typeof result.status === 'number') {
-                encoding = typeof result.encoding === 'string' ? result.encoding : null;
-                if (encoding !== null && encoding !== 'base64') {
-                    throw new Error(`Unknown response encoding: ${JSON.stringify(encoding)} (expected 'base64' or omitted)`);
-                }
-                if (encoding === 'base64' && typeof result.body !== 'string') {
-                    throw new Error(`encoding: 'base64' requires body to be a base64-encoded string, got ${typeof result.body}`);
-                }
-                status = result.status || 200;
-                responseBody = result.body !== undefined ? result.body : null;
-                responseHeaders = result.headers || {};
-            } else {
-                status = 200;
-                responseBody = result;
-                responseHeaders = { 'content-type': 'application/json' };
-            }
-
-            res.statusCode = status;
-            for (const [key, value] of Object.entries(responseHeaders)) {
-                res.setHeader(key, value);
-            }
-
-            if (responseBody === null) {
+                res.statusCode = 204;
                 res.end();
-            } else if (encoding === 'base64' && typeof responseBody === 'string') {
-                if (!isBase64(responseBody)) {
-                    throw new Error('Handler returned malformed base64 body');
-                }
-                res.end(Buffer.from(responseBody, 'base64'));
-            } else if (typeof responseBody === 'string') {
-                // Pre-PR the dev middleware always JSON.stringify'd the body, so
-                // a handler returning { body: 'hello' } emitted "hello" (with
-                // quotes) — diverging from prod which passed strings verbatim.
-                // This branch fixes that parity.
-                if (!res.getHeader('content-type')) {
-                    res.setHeader('Content-Type', 'application/json');
-                }
-                res.end(responseBody);
+            } else if (isDescriptor(result)) {
+                sendDescriptor(res, result);
             } else {
-                if (!res.getHeader('content-type')) {
-                    res.setHeader('Content-Type', 'application/json');
-                }
-                res.end(JSON.stringify(responseBody));
+                sendDescriptor(res, { status: 200, headers: { 'content-type': 'application/json' }, body: result });
             }
         } catch (err) {
             viteServer.ssrFixStacktrace(err);