@entrinsik/vite-plugin-informer 2.12.0 → 2.13.0

package/README.md

@@ -25,7 +25,7 @@ The assembler uploads your built frontend plus these source trees, matching how
 | `webhooks/` | Publicly callable webhook routes |
 | `tools/` | AI tools, private to the App's agents |
 | `mcp/` | Tools exposed over the App's MCP endpoint |
-| `channels/` | Live channel handlers: `join` / `joined` / `leave` and event-named handlers for `channel.send()`; `npm run dev` runs them locally, and the `channels:` block in `informer.yaml` declares relays only (each entry needs `on`) |
+| `channels/` | Live channel handlers: `join` / `joined` / `leave` and event-named handlers for `channel.send()`, or a channel actor (`config.actor`: one live instance per channel, with `start` / `tick` / `stop` / `snapshot`); `npm run dev` runs both locally, and the `channels:` block in `informer.yaml` declares relays only (each entry needs `on`) |
 | `migrations/` | Workspace database migrations, run in order on deploy |
 | `embeddings/` | Declarative embedding use cases (see below) |
 | `lib/`, `shared/` | Modules importable by the trees above |
@@ -48,6 +48,8 @@ A server whose version isn't comparable (a `dev` build, or an `/about` behind a
 
 App Channels phase 2 (plugin ≥ 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless; plugin 2.12.0 aligns its channel semantics with the server's (wildcard gating, replay expiry, and the per-user send budget), so on 2.11.0 the dev mirror has the phase 2 surface but not all of its behavior.
 
+Channel actors (plugin ≥ 2.13.0: `config.actor` files, `request.member`, `__INFORMER__.serverNow()`) need a server that reports `platform.capabilities.channelActors`; on one that does not, the same file runs as an ordinary channel handler, one fresh module per message. Under `npm run dev` each concrete channel gets its own module instance, calls run one at a time, `tick()` runs on a timer, and the actor stops `idleMs` after its last page leaves. `snapshot()` is kept in memory, so editing a file under `channels/`, `shared/`, `lib/` or `server/` restarts the running actors on the new code from their snapshots with the same pages subscribed: a game in progress survives the edit. The server's cluster, leases, billing and broadcast limits have no dev counterpart.
+
 Feature-detect at runtime with optional chaining, since `platform` is absent entirely before 2026.1.3:
 
 ```javascript

package/bin/deploy.js

@@ -82,5 +82,8 @@ try {
     }
 } catch (err) {
     console.error('Deploy failed:', err.message);
+    // The server's own message carries the recovery instruction; err.message is
+    // only the status line.
+    if (err.detail) console.error(err.detail);
     process.exit(1);
 }

package/index.d.ts

@@ -2,12 +2,14 @@ import type { Plugin } from 'vite';
 
 /**
  * Dev-only binding for a `target: app` or `target: pack` dependency slot.
- * Points `request()` at the target app in dev. For app slots it overrides the
- * manifest `defaultBinding` when both are present; for pack slots it is the
- * only way to bind — the marketplace pin has no install to resolve against in
- * dev, so point it at your locally-installed copy of the pack's app.
+ * Points `request()` and `url()` at the target app in dev. For app slots it
+ * overrides the manifest `defaultBinding` when both are present; for pack
+ * slots it is the only way to bind — the marketplace pin has no install to
+ * resolve against in dev, so point it at your locally-installed copy of the
+ * pack's app.
  *
- * - `app` — the target app (`owner:slug` or UUID). Powers `request()`.
+ * - `app` — the target app (`owner:slug` or UUID). Powers `request()`, and
+ *   names the app `url()` links into (on `INFORMER_URL`).
  *
  * A bare string is shorthand for `{ app }`.
  */

package/package.json

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

package/src/agent-dev.js

@@ -325,7 +325,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
                 // `context.<slot>.<method>(...)` and `env` work locally and match
                 // the prod sandbox bag. The manifest is already in hand.
                 const deps = manifestBlock(yaml, 'dependencies');
-                const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
+                const context = buildDevContext({ deps, apiFetch, devBindings, appFetch, serverOrigin });
                 const env = manifestBlock(yaml, 'env');
 
                 // emit() writes no app_event row in dev, but still relays a

package/src/client.js

@@ -2,6 +2,26 @@
  * Informer API client using native fetch with Basic auth.
  */
 
+/**
+ * The server's own explanation, dug out of an error body.
+ *
+ * Boom replies carry the useful sentence in `message`, and for a refused deploy
+ * that sentence is the whole value of the response — it names the call that
+ * unblocks the app. A bare status line leaves the author with nothing to act on.
+ *
+ * @param {string} body - raw response body
+ * @returns {string} the server's message, or '' when the body says nothing
+ */
+function errorDetail(body) {
+    if (!body) return '';
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.message || parsed.error || '';
+    } catch {
+        return String(body).trim().slice(0, 500);
+    }
+}
+
 class InformerApiError extends Error {
     constructor(status, statusText, body, url) {
         super(`Informer API ${status} ${statusText}${url ? ` (${url})` : ''}`);
@@ -9,6 +29,7 @@ class InformerApiError extends Error {
         this.status = status;
         this.statusText = statusText;
         this.body = body;
+        this.detail = errorDetail(body);
         this.url = url;
     }
 }
@@ -63,7 +84,7 @@ export function createClient({ baseUrl, apiKey, user, pass }) {
      * Upload a file using chunked Flow.js protocol, then assemble into an entity's library.
      * @param {{ entityPath?: string, reportId?: string, path: string, buffer: Buffer, filename: string }} opts
      */
-    async function uploadChunked({ entityPath, reportId, path, buffer, filename }) {
+    async function uploadChunked({ entityPath, reportId, path, buffer, filename, stagingLibraryId }) {
         const basePath = entityPath || `reports/${reportId}`;
         const totalChunks = Math.ceil(buffer.length / CHUNK_SIZE);
         const uploadId = `publish-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
@@ -98,14 +119,19 @@ export function createClient({ baseUrl, apiKey, user, pass }) {
             }
         }
 
-        // Assemble chunks into a file in the entity's library at the specified path
+        // Assemble chunks into a file in the entity's library at the specified
+        // path. `stagingLibraryId` claims the in-flight deploy — without it the
+        // server refuses the write rather than folding it into someone else's
+        // build (see deploy-target.js).
         await request('POST', `${basePath}/_upload`, {
             uploadId,
-            path
+            path,
+            ...(stagingLibraryId ? { stagingLibraryId } : {})
         });
     }
 
     return {
+        baseUrl: origin,
         get: (path) => request('GET', path),
         post: (path, body) => request('POST', path, body),
         put: (path, body) => request('PUT', path, body),

package/src/deploy.js

@@ -71,19 +71,18 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         };
         if (id) payload.id = id;
 
-        try {
-            console.log(`Creating new app "${name}"...`);
-            entity = await api.post('apps', { ...payload, type: 'app' });
-            apiPrefix = 'apps';
-        } catch (e) {
-            // If apps endpoint doesn't exist (404), fall back to legacy reports
-            if (e.status === 404) {
-                console.log('Apps API not available, using legacy reports API...');
-                entity = await api.post('reports', { ...payload, type: 'magicReport' });
-                apiPrefix = 'reports';
-            } else {
-                throw e;
-            }
+        console.log(`Creating new app "${name}"...`);
+        entity = await api.post('apps', { ...payload, type: 'app' });
+        apiPrefix = 'apps';
+
+        // Null, not a throw: client.js turns a 404 into a null reply, so the
+        // legacy-reports fallback has to branch on the value. As a catch on
+        // `e.status === 404` it could never fire, and a genuine missing-apps-API
+        // surfaced as "Failed to create" instead of falling back.
+        if (entity === null) {
+            console.log('Apps API not available, using legacy reports API...');
+            entity = await api.post('reports', { ...payload, type: 'magicReport' });
+            apiPrefix = 'reports';
         }
 
         if (!entity || !entity.id) {
@@ -116,9 +115,10 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         limit: 10
     });
 
-    // 5. Clear existing files in one server-side transaction
-    console.log('Clearing existing files...');
-    await api.post(`${entityPath}/files/_clear`);
+    // 5. Open a staging library so the upload pass below doesn't touch what the
+    //    app is currently serving.
+    console.log('Staging deploy...');
+    const stagingLibraryId = await openStagingDeploy(api, entityPath);
 
     // 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
@@ -126,37 +126,59 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     //    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...');
+    //
+    //    Everything from here until the deploy completes runs inside the try, so
+    //    nothing can leave the app staged: a live staging pointer redirects later
+    //    content writes into a library nothing serves while reads keep returning
+    //    the old build, and the routes that cannot redirect refuse with 409
+    //    (I5-12961). `files` is declared outside the try so step 13 can still
+    //    report on it once the staging lock has released.
     const files = plan.files;
+    let deployed = false;
+    const releaseStaging = installStagingSignalHandlers(api, entityPath, stagingLibraryId);
+    try {
+        console.log('Uploading files...');
 
-    for (const { abs, rel } of files) {
-        const content = await readFile(abs);
-
-        if (content.length > CHUNK_THRESHOLD) {
-            // Large file: chunked upload via Flow.js protocol
-            await api.uploadChunked({
-                entityPath,
-                path: rel,
-                buffer: content,
-                filename: basename(abs)
-            });
-            console.log(`  ${rel} (${formatSize(content.length)}, chunked)`);
-        } else {
-            // Small file: direct JSON upload
-            const ext = '.' + rel.split('.').pop();
-            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
-            const payload = isText
-                ? { content: content.toString('utf8'), encoding: 'utf8' }
-                : { content: content.toString('base64'), encoding: 'base64' };
-
-            await api.put(`${entityPath}/contents/${rel}`, payload);
-            console.log(`  ${rel}`);
+        // Presented on every write so the server folds it into THIS deploy. A
+        // write that doesn't claim the staging library is refused rather than
+        // quietly joining it (see deploy-target.js). Empty on the _clear
+        // fallback, where there is no staging library to claim.
+        const claim = stagingLibraryId ? { stagingLibraryId } : {};
+
+        for (const { abs, rel } of files) {
+            const content = await readFile(abs);
+
+            if (content.length > CHUNK_THRESHOLD) {
+                // Large file: chunked upload via Flow.js protocol
+                await api.uploadChunked({
+                    entityPath,
+                    path: rel,
+                    buffer: content,
+                    filename: basename(abs),
+                    stagingLibraryId
+                });
+                console.log(`  ${rel} (${formatSize(content.length)}, chunked)`);
+            } else {
+                // Small file: direct JSON upload
+                const ext = '.' + rel.split('.').pop();
+                const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
+                const payload = isText
+                    ? { content: content.toString('utf8'), encoding: 'utf8', ...claim }
+                    : { content: content.toString('base64'), encoding: 'base64', ...claim };
+
+                await api.put(`${entityPath}/contents/${rel}`, payload);
+                console.log(`  ${rel}`);
+            }
         }
-    }
 
-    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + embeddings + tools + agents
-    if (apiPrefix === 'apps') {
-        await runServerDeploy(api, entityPath);
+        // 12. Deploy: run migrations + scan/bundle server routes + webhooks + embeddings + tools + agents
+        if (apiPrefix === 'apps') {
+            await runServerDeploy(api, entityPath, stagingLibraryId);
+        }
+        deployed = true;
+    } finally {
+        releaseStaging();
+        if (stagingLibraryId && !deployed) await discardStaging(api, entityPath, stagingLibraryId);
     }
 
     // 13. Print URL and return UUID for saving
@@ -170,6 +192,129 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     return { id: entity.id, url: entityUrl };
 }
 
+/**
+ * Discard this deploy's staged upload so a failure doesn't leave the app locked.
+ *
+ * Presents the id so a cleanup can never destroy a DIFFERENT deploy's in-flight
+ * upload, and is best-effort: the original failure is what the user needs to
+ * see, so a cleanup problem is reported but never replaces it.
+ *
+ * @param {Object} api - Informer API client
+ * @param {string} entityPath
+ * @param {string} stagingLibraryId
+ */
+export async function discardStaging(api, entityPath, stagingLibraryId) {
+    try {
+        await api.del(`${entityPath}/files/_stage?stagingLibraryId=${encodeURIComponent(stagingLibraryId)}`);
+        console.log('Discarded the staged upload; the app is unchanged and editable.');
+    } catch (cleanupErr) {
+        console.log(`Could not discard the staged upload (${cleanupErr.message}).`);
+        console.log(`The app will keep redirecting content edits until it is cleared.`);
+        console.log(`Run: DELETE ${entityPath}/files/_stage`);
+    }
+}
+
+/**
+ * Discard the staged upload if the process is interrupted.
+ *
+ * Ctrl-C during a long upload is an ordinary way to end a deploy, and without a
+ * handler it leaves the app staged with no cleanup at all. Returns a function
+ * that removes the handlers so a completed deploy doesn't keep them installed.
+ *
+ * @returns {Function} release
+ */
+function installStagingSignalHandlers(api, entityPath, stagingLibraryId) {
+    if (!stagingLibraryId) return () => {};
+
+    // A second Ctrl-C during the cleanup await would re-enter and start a
+    // competing discard, so the first one wins and later signals exit at once.
+    let discarding = false;
+
+    const handlers = ['SIGINT', 'SIGTERM'].map((signal) => {
+        const handler = async () => {
+            if (discarding) {
+                console.log(`\nInterrupted again; exiting without waiting for the discard.`);
+                process.exit(130);
+            }
+            discarding = true;
+            console.log(`\nInterrupted (${signal}); discarding the staged upload...`);
+            await discardStaging(api, entityPath, stagingLibraryId);
+            process.exit(130);
+        };
+        process.on(signal, handler);
+        return { signal, handler };
+    });
+
+    return () => handlers.forEach(({ signal, handler }) => process.off(signal, handler));
+}
+
+/**
+ * POST `files/_stage`: open a staging library for this deploy.
+ *
+ * Everything uploaded afterwards lands in the staging library while the app
+ * goes on serving its current one; POST `_deploy`, given this library's id,
+ * then replaces the live library's files with the staged ones inside a single
+ * transaction. That is what keeps an app usable, and complete, for the
+ * whole length of its own deploy (I5-12961).
+ *
+ * Falls back to the old wipe-then-upload flow against a server with no _stage
+ * route. That flow is precisely what staging exists to avoid, so it announces
+ * itself rather than degrading silently.
+ *
+ * Note the null check rather than a try/catch: client.js turns a 404 into a
+ * `null` reply instead of throwing, so an unsupported route arrives here as a
+ * value, not an exception.
+ *
+ * @param {Object} api - Informer API client
+ * @param {string} entityPath - e.g. `apps/team:my-app`
+ * @returns {Promise<string|null>} staging library id to present at deploy time, or
+ *   null when it fell back to _clear and there is nothing to promote
+ */
+export async function openStagingDeploy(api, entityPath) {
+    let staged;
+    try {
+        staged = await api.post(`${entityPath}/files/_stage`);
+    } catch (err) {
+        // 409 means a previous deploy died and left its upload staged. The
+        // server refuses to stage over it (destroying it silently is how two
+        // deploys interleave), so the app stays locked until someone discards
+        // it — and this message is the only place that instruction appears.
+        if (err.status === 409) {
+            const base = api.baseUrl ? `${api.baseUrl}/api` : '<informer-url>/api';
+            throw new Error(
+                `${err.detail || 'This app already has a staged upload from an earlier deploy.'}\n\n`
+                + `A previous deploy did not finish and left its upload staged. Discard it, then re-run this deploy:\n`
+                + `  curl -u <user>:<pass> -X DELETE '${base}/${entityPath}/files/_stage'`
+            );
+        }
+        throw err;
+    }
+
+    // `null` means 404 and ONLY 404 — client.js returns it for a missing route
+    // and throws for every other non-ok status. Any other falsy-id reply is a
+    // server that DID stage, so it must not take the destructive branch.
+    if (staged === null) {
+        console.log('  Server does not support staged deploys; clearing files instead.');
+        console.log('  The app will be unavailable to its users until this deploy finishes.');
+        await api.post(`${entityPath}/files/_clear`);
+        return null;
+    }
+
+    if (!staged.id) {
+        // _stage SUCCEEDED, so the server has already pointed the app at a
+        // staging library this deploy cannot name. Clearing here would empty the
+        // live library while every upload silently redirected into that staging
+        // library, and the unclaimed deploy would then publish the empty one.
+        throw new Error(
+            `POST ${entityPath}/files/_stage succeeded but returned no library id `
+            + `(got: ${JSON.stringify(staged).slice(0, 200)}). The app now has a staging library `
+            + `this deploy cannot claim. Nothing was uploaded or cleared.`
+        );
+    }
+
+    return staged.id;
+}
+
 /**
  * POST `_deploy`: run migrations, scan/bundle server routes, webhooks, tools and
  * agents, and claim the app as platform-managed.
@@ -179,8 +324,10 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
  *
  * @param {{post: (path: string, body?: unknown) => Promise<unknown>}} api
  * @param {string} entityPath e.g. `apps/my-app`
+ * @param {string} [stagingLibraryId] id returned by openStagingDeploy; presenting
+ *     it is what authorises the server to promote that staged upload
  */
-export async function runServerDeploy(api, entityPath) {
+export async function runServerDeploy(api, entityPath, stagingLibraryId) {
     try {
         console.log('Deploying...');
         // `managed: true` claims the app as platform-managed (origin
@@ -189,7 +336,13 @@ export async function runServerDeploy(api, entityPath) {
         // 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 });
+        // Presenting the staged id is what authorises the server to promote that
+        // upload. Omitting it (the _clear fallback path) leaves the server
+        // deploying the live library, which is the pre-staging behaviour.
+        const result = await api.post(`${entityPath}/_deploy`, {
+            managed: true,
+            ...(stagingLibraryId ? { stagingLibraryId } : {})
+        });
         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

package/src/dev-bag.js

@@ -222,7 +222,7 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
     async function build({ forwarding = null } = {}) {
         const manifest = await loadManifest(projectRoot);
         const deps = manifestBlock(manifest, 'dependencies');
-        const context = buildDevContext({ deps, apiFetch, devBindings, appFetch, forwarding });
+        const context = buildDevContext({ deps, apiFetch, devBindings, appFetch, forwarding, serverOrigin });
         const env = manifestBlock(manifest, 'env');
 
         // emit() writes no app_event row in dev, but still relays a listed

package/src/dev-channel-actors.js

@@ -0,0 +1,352 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Channel actors in the dev mirror, the counterpart of the server's
+ * app-channel-actors.js. A `channels/` file whose `config.actor` is an object
+ * gets one live module instance per concrete channel (`match/42`), kept while
+ * pages are subscribed:
+ *
+ *   - start({ channel, restored }) runs first, then join / joined / leave and
+ *     every event export run inside that instance, one call at a time
+ *   - tick({ dt, frame }) runs `config.actor.tick` times a second; a tick that
+ *     comes due while a call is still running is skipped, not queued
+ *   - the actor stops `idleMs` after its last page leaves, with its
+ *     stop({ reason }), and the next join or send starts a fresh one
+ *   - snapshot() is called every `snapshotMs` and kept in memory; when a file
+ *     the actors load changes, each actor keeps a snapshot, stops with reason
+ *     'redeploy', and restarts at once on the new code from it, with the same
+ *     pages: a game survives an edit, as it survives a deploy on the server
+ *
+ * A page is one member here (a dev page is one client, with no reconnects),
+ * so leave runs when it unsubscribes. The server's cluster, leases, billing
+ * and rate limits have no dev counterpart.
+ */
+
+export const ACTOR_LIFECYCLE = Object.freeze(['start', 'stop', 'tick', 'snapshot']);
+// The server's actors.callTimeoutMs: a call that runs longer stops the actor.
+export const ACTOR_CALL_TIMEOUT_MS = 1000;
+export const ACTOR_STOP_TIMEOUT_MS = 5000;
+const DEFAULTS = Object.freeze({ tick: 0, idleMs: 30000, snapshotMs: 5000 });
+const MAX_TICK_HZ = 60;
+
+export function isActorModule(mod) {
+    const actor = mod && mod.config && mod.config.actor;
+    return Boolean(actor && typeof actor === 'object' && !Array.isArray(actor));
+}
+
+/** `request.member` for a dev page: a hash of its client id, shaped like the server's. */
+export function memberIdFor(clientId) {
+    return `m_${createHash('sha256').update(`dev:${clientId}`).digest('base64url').slice(0, 16)}`;
+}
+
+function optionsOf(mod) {
+    const asked = mod.config.actor;
+    return {
+        tickHz: Math.min(Math.max(Number(asked.tick) || 0, 0), MAX_TICK_HZ),
+        idleMs: asked.idleMs === undefined ? DEFAULTS.idleMs : Math.max(0, Number(asked.idleMs) || 0),
+        snapshotMs: Math.min(Math.max(Number(asked.snapshotMs) || DEFAULTS.snapshotMs, 1000), 60000)
+    };
+}
+
+// What `config.actor` may say, and the wording the deploy uses to refuse it
+// (channel-scanner.js assertActorConfig on the server). Without this, a file
+// that sets `actor: { tickRate: 30 }` or exports tick() with no rate runs
+// quietly tick-less in dev and 400s at deploy time.
+const ACTOR_KEYS = ['tick', 'idleMs', 'memoryMb', 'snapshotMs'];
+
+function assertActorConfig(mod, filePath) {
+    const actor = mod.config.actor;
+    const exports = Object.keys(mod);
+    const fail = message => {
+        throw new Error(`channel handler "${filePath}" ${message} Fix config.actor.`);
+    };
+    const unknown = Object.keys(actor).filter(key => !ACTOR_KEYS.includes(key));
+    if (unknown.length) fail(`sets config.actor.${unknown.join(', config.actor.')}, which is not an actor setting (${ACTOR_KEYS.join(', ')} are).`);
+    const number = (key, min) => {
+        if (actor[key] === undefined) return;
+        if (typeof actor[key] !== 'number' || !Number.isFinite(actor[key]) || actor[key] < min) {
+            fail(`sets config.actor.${key} to ${JSON.stringify(actor[key])}; it must be a number of at least ${min}.`);
+        }
+    };
+    number('tick', 0);
+    number('idleMs', 0);
+    number('memoryMb', 8);
+    number('snapshotMs', 1000);
+    if (actor.tick > 0 && !exports.includes('tick')) fail(`sets config.actor.tick to ${actor.tick} but exports no tick() to call.`);
+    if (exports.includes('tick') && !(actor.tick > 0)) fail('exports tick() but config.actor.tick does not say how often to call it.');
+    if (actor.snapshotMs !== undefined && !exports.includes('snapshot')) fail(`sets config.actor.snapshotMs to ${actor.snapshotMs} but exports no snapshot() to call.`);
+}
+
+const unavailable = name => () => {
+    throw new Error(`${name}() is not available in a channel actor: it would run with one subscriber's credentials on behalf of all of them. Call a server/ route from the page instead.`);
+};
+
+/**
+ * @param {Object} opts
+ * @param {Object} opts.viteServer - loads a fresh module instance per actor run (ssrLoadModule with a query)
+ * @param {Function} opts.bagFor - async (channel, params) => the handler bag (broadcast, query, log, …)
+ * @param {string} [opts.logPrefix]
+ * @param {number} [opts.callTimeoutMs]
+ */
+export function createDevActors({ viteServer, bagFor, logPrefix = '[app-channel]', callTimeoutMs = ACTOR_CALL_TIMEOUT_MS }) {
+    const actors = new Map();       // channel name → actor
+    const starting = new Map();     // channel name → its start in flight
+    const snapshots = new Map();    // channel name → the last snapshot() kept
+    let runs = 0;
+
+    async function load(filePath, channel) {
+        // a query per run: a separate instance per channel, and a fresh one per start
+        return await viteServer.ssrLoadModule(`${filePath}?actor=${encodeURIComponent(channel)}&run=${++runs}`);
+    }
+
+    function queue(actor, exportName, extras, timeoutMs = callTimeoutMs) {
+        const run = async () => {
+            if (actor.state === 'stopped') throw Object.assign(new Error('app_channel_actor_stopped'), { statusCode: 503, code: 'app_channel_actor_stopped' });
+            actor.busy = true;
+            let timer;
+            try {
+                const call = Promise.resolve().then(() => actor.mod[exportName]({ ...actor.bag, ...extras }));
+                const overrun = new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(Object.assign(new Error(`${exportName} ran past ${timeoutMs} ms`), { overrun: true })), timeoutMs);
+                });
+                return await Promise.race([call, overrun]);
+            } catch (err) {
+                if (err && err.overrun) {
+                    console.error(`${logPrefix} actor "${actor.channel}" stopped: ${err.message}; the next join or send starts a new one`);
+                    stop(actor, 'timeout');
+                    throw Object.assign(new Error('app_channel_actor_timeout'), { statusCode: 504, code: 'app_channel_actor_timeout' });
+                }
+                if (err && typeof err.statusCode === 'number') throw err;
+                console.error(`${logPrefix} ${exportName}("${actor.channel}") failed:`, err);
+                throw Object.assign(new Error(`app_channel_${exportName}_failed`), { statusCode: 500, code: 'app_channel_send_failed' });
+            } finally {
+                clearTimeout(timer);
+                actor.busy = false;
+            }
+        };
+        const result = actor.queue.then(run, run);
+        actor.queue = result.catch(() => {});
+        return result;
+    }
+
+    const has = (actor, name) => typeof actor.mod[name] === 'function';
+
+    // Another actor took this channel while this one was stopping: the
+    // channel's shared state (its kept snapshot, its registry slot) is that
+    // one's now, and this one must not write over it.
+    const isReplaced = actor => actors.has(actor.channel) && actors.get(actor.channel) !== actor;
+
+    function scheduleTick(actor) {
+        const period = 1000 / actor.options.tickHz;
+        const next = actor.tickOrigin + (actor.frame + 1) * period;
+        actor.timers.tick = setTimeout(() => {
+            if (actor.state !== 'running') return;
+            actor.frame++;
+            if (!actor.busy) {
+                const now = Date.now();
+                const dt = (now - actor.lastTickAt) / 1000;
+                actor.lastTickAt = now;
+                queue(actor, 'tick', { dt, frame: actor.frame, request: null }).catch(() => {});
+            }
+            scheduleTick(actor);
+        }, Math.max(0, next - Date.now()));
+    }
+
+    function armIdle(actor) {
+        clearTimeout(actor.timers.idle);
+        if (actor.members.size > 0 || actor.state !== 'running') return;
+        actor.timers.idle = setTimeout(() => stop(actor, 'idle'), actor.options.idleMs);
+    }
+
+    async function saveSnapshot(actor) {
+        if (!has(actor, 'snapshot')) return;
+        try {
+            const state = await queue(actor, 'snapshot', { request: null });
+            // taken between messages, so a replacement may have started meanwhile
+            if (state !== undefined && state !== null && !isReplaced(actor)) snapshots.set(actor.channel, JSON.parse(JSON.stringify(state)));
+        } catch {
+            // reported by queue()
+        }
+    }
+
+    async function start(channel, params, filePath) {
+        const mod = await load(filePath, channel);
+        assertActorConfig(mod, filePath);
+        const bag = await bagFor(channel, params);
+        // An actor's broadcast to its own channel answers the production shape:
+        // there it is queued on the actor's ordered chain and has no seq yet,
+        // and `const { seq } = await channel.broadcast(...)` must not read as a
+        // usable number locally and null once deployed. Any other channel goes
+        // the way every handler's broadcast does.
+        const broadcastOwn = async (event, body, options) => {
+            await bag.broadcast(channel, event, body, options);
+            return { ok: true, queued: true, seq: null };
+        };
+        const actor = {
+            channel, params, filePath, mod,
+            options: optionsOf(mod),
+            bag: {
+                ...bag,
+                broadcast: (name, event, body, options) => (name === channel
+                    ? broadcastOwn(event, body, options)
+                    : bag.broadcast(name, event, body, options)),
+                fetch: unavailable('fetch'),
+                context: undefined,
+                channel: { name: channel, params, broadcast: broadcastOwn }
+            },
+            members: new Map(),     // clientId → the request it joined with
+            queue: Promise.resolve(),
+            busy: false,
+            timers: {},
+            frame: 0,
+            state: 'running'
+        };
+        actors.set(channel, actor);
+        const restored = has(actor, 'snapshot') ? snapshots.get(channel) : undefined;
+        if (has(actor, 'start')) {
+            try {
+                await queue(actor, 'start', { restored, request: null });
+            } catch (err) {
+                // a state the new start cannot take would fail every start after it too
+                snapshots.delete(channel);
+                actors.delete(channel);
+                actor.state = 'stopped';
+                throw err;
+            }
+        }
+        if (actor.options.tickHz > 0 && has(actor, 'tick')) {
+            actor.tickOrigin = Date.now();
+            actor.lastTickAt = actor.tickOrigin;
+            scheduleTick(actor);
+        }
+        if (has(actor, 'snapshot')) actor.timers.snapshot = setInterval(() => saveSnapshot(actor), actor.options.snapshotMs);
+        armIdle(actor);
+        console.log(`${logPrefix} actor "${channel}" started${restored !== undefined ? ' from its snapshot' : ''}`);
+        return actor;
+    }
+
+    /**
+     * Stop an actor: for a redeploy (an edited file) keep a snapshot first;
+     * after idle or a timeout drop it; stop() runs unless the actor hung.
+     */
+    function stop(actor, reason) {
+        if (actor.stopping) return actor.stopping;
+        // Synchronously, as the server does: a stop that only marks the actor
+        // dead after its awaits hands it out of ensure() for the whole
+        // graceful stop, and the page joins an actor that is on its way out.
+        actor.state = 'stopping';
+        actor.stopping = (async () => {
+            clearTimeout(actor.timers.tick);
+            clearTimeout(actor.timers.idle);
+            clearInterval(actor.timers.snapshot);
+            if (reason === 'redeploy' || reason === 'shutdown') await saveSnapshot(actor);
+            if (reason !== 'timeout' && has(actor, 'stop')) {
+                await queue(actor, 'stop', { reason, request: null }, ACTOR_STOP_TIMEOUT_MS).catch(() => {});
+            }
+            actor.state = 'stopped';
+            const replaced = isReplaced(actor);
+            // a replacement started while this one was stopping owns the
+            // channel's snapshot now
+            if ((reason === 'idle' || reason === 'timeout') && !replaced) snapshots.delete(actor.channel);
+            if (!replaced) actors.delete(actor.channel);
+            console.log(`${logPrefix} actor "${actor.channel}" stopped (${reason})`);
+        })();
+        return actor.stopping;
+    }
+
+    /**
+     * Admit a page: the actor's join decides (exactly true admits), and an
+     * actor never holds a member its join did not admit. Every admission goes
+     * through here, as on the server, so a join that seeds per-member state or
+     * caps seats is exercised in dev too -- not just on the subscribe path.
+     */
+    async function admit(actor, clientId, request) {
+        if (has(actor, 'join') && await queue(actor, 'join', { payload: null, request }) !== true) {
+            armIdle(actor);
+            throw Object.assign(new Error('app_channel_join_refused'), { statusCode: 403, code: 'app_channel_join_refused' });
+        }
+        actor.members.set(clientId, request);
+        clearTimeout(actor.timers.idle);
+    }
+
+    // The running actor for a channel, starting one if there is none; two
+    // callers at once share one start.
+    async function ensure(channel, params, filePath) {
+        const running = actors.get(channel);
+        if (running && running.state === 'running' && !starting.has(channel)) return running;
+        if (!starting.has(channel)) {
+            starting.set(channel, start(channel, params, filePath).finally(() => starting.delete(channel)));
+        }
+        return await starting.get(channel);
+    }
+
+    return {
+        /** A page subscribes: the actor's join decides (exactly true admits). */
+        async join({ channel, params, filePath, clientId, request }) {
+            const actor = await ensure(channel, params, filePath);
+            await admit(actor, clientId, request);
+        },
+        async joined({ channel, clientId, request }) {
+            const actor = actors.get(channel);
+            if (!actor || !actor.members.has(clientId) || !has(actor, 'joined')) return;
+            await queue(actor, 'joined', { payload: null, request });
+        },
+        async leave({ channel, clientId }) {
+            const actor = actors.get(channel);
+            if (!actor || !actor.members.has(clientId)) return;
+            const request = actor.members.get(clientId);
+            actor.members.delete(clientId);
+            armIdle(actor);
+            if (has(actor, 'leave')) await queue(actor, 'leave', { payload: null, request });
+        },
+        /** A page's send(): a call into the running actor, started afresh if it stopped. */
+        async send({ channel, params, filePath, clientId, request, event, payload }) {
+            const actor = await ensure(channel, params, filePath);
+            if (ACTOR_LIFECYCLE.includes(event) || typeof actor.mod[event] !== 'function') {
+                throw Object.assign(new Error('app_channel_no_handler'), { statusCode: 404, code: 'app_channel_no_handler' });
+            }
+            // a sender this actor has not admitted (it restarted, or its code
+            // changed since the page joined) goes through join like anyone else
+            if (!actor.members.has(clientId)) await admit(actor, clientId, request);
+            return await queue(actor, event, { payload: payload === undefined ? null : payload, request });
+        },
+        /**
+         * A file an actor loads changed: an actor that keeps snapshots and has
+         * pages stops with one and restarts at once on the new code, carrying
+         * its pages in through the new code's own join. Any other actor just
+         * stops, and the next join or send starts it fresh -- the same two
+         * rules the server follows across a deploy, so a join that refuses the
+         * carried page (or a file that keeps no snapshot) behaves here as it
+         * will there.
+         */
+        async restartAll() {
+            const running = [...actors.values()].filter(a => a.state === 'running');
+            await Promise.all(running.map(async actor => {
+                const carry = has(actor, 'snapshot') && actor.members.size > 0;
+                const members = new Map(actor.members);
+                await stop(actor, 'redeploy');
+                if (!carry) return;
+                try {
+                    const next = await ensure(actor.channel, actor.params, actor.filePath);
+                    for (const [clientId, request] of members) {
+                        try {
+                            await admit(next, clientId, request);
+                        } catch (err) {
+                            console.log(`${logPrefix} a page was not carried into actor "${actor.channel}" on the edited code: ${err.message}`);
+                        }
+                    }
+                } catch (err) {
+                    console.error(`${logPrefix} actor "${actor.channel}" did not restart on the edited code:`, err);
+                }
+            }));
+        },
+        async stopAll(reason = 'shutdown') {
+            await Promise.all([...actors.values()].map(actor => stop(actor, reason)));
+        },
+        /** What is running, for the terminal and tests. */
+        list() {
+            return [...actors.values()].map(a => ({ channel: a.channel, members: a.members.size, frame: a.frame, state: a.state }));
+        },
+        snapshots
+    };
+}

package/src/dev-channel-handlers.js

@@ -1,10 +1,11 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 import { parse as parseUrl } from 'node:url';
 import { createDevBagBuilder, buildDevUser } from './dev-bag.js';
 import { devPlatform } from './dev-platform.js';
 import { filePathToRoute, matchRoute, walkJsFiles } from './server-routes.js';
 import { createDevChannels, isChannelName, isWildcardName, isEventName, isReservedEvent, channelError, USER_CHANNEL_PREFIX } from './dev-channels.js';
+import { createDevActors, isActorModule, memberIdFor, ACTOR_LIFECYCLE } from './dev-channel-actors.js';
 
 /**
  * The dev counterpart of app-channel-handlers.js: a page's `channel()` mock
@@ -12,8 +13,9 @@ import { createDevChannels, isChannelName, isWildcardName, isEventName, isReserv
  * the matching `channels/` file runs in-process the way a deployed handler
  * runs in the sandbox — `join` decides admission, `joined` runs after it,
  * `leave` runs on unsubscribe, and an event-named export answers `send()`.
- * Frames still ride Vite's websocket to every page; admission is what tells
- * the page which frames it may dispatch.
+ * A file with `config.actor` runs as a channel actor instead (see
+ * dev-channel-actors.js). Frames still ride Vite's websocket to every page;
+ * admission is what tells the page which frames it may dispatch.
  */
 
 export const CHANNELS_DIR = 'channels';
@@ -23,6 +25,10 @@ export const CHANNEL_METHOD = 'CHANNEL';
 export const HANDLER_TIMEOUT_MS = 5000;
 // Per-user inbound budget (token bucket): send() and the replay reads a reconnect makes.
 export const SEND_RATE = Object.freeze({ perSecond: 10, burst: 30 });
+// The server's separate, larger send() budget for actor channels (a game's inputs).
+export const ACTOR_SEND_RATE = Object.freeze({ perSecond: 30, burst: 60 });
+// Edits under these directories can change what an actor runs: its file, or what it imports.
+const ACTOR_SOURCE_DIRS = ['channels', 'shared', 'lib', 'server'];
 // Exports with a fixed meaning; every other export must be an event name.
 export const LIFECYCLE_EXPORTS = Object.freeze(['config', 'join', 'joined', 'leave']);
 
@@ -156,10 +162,39 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
     // handler reading platform.capabilities.embeddings must not disagree with
     // the route beside it, and its embed() must be bound when they agree.
     const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]', platform, appId });
-    // clientId → channel name → { clientId, channel, params, file }
+    // clientId → channel name → { clientId, channel, params, file, actor }
     const subscriptions = new Map();
-    // username → { tokens, ts }
+    // username (or `actor:` + username) → { tokens, ts }
     const buckets = new Map();
+    const actors = createDevActors({
+        viteServer,
+        bagFor: async () => (await bagBuilder.build()).bag,
+        logPrefix,
+        callTimeoutMs: Math.min(timeoutMs, 1000)
+    });
+    // A Vite restart (a config edit) closes this server and builds another:
+    // without this the old server's actors keep their tick loops and module
+    // instances running forever, so two config edits leave three copies of the
+    // same game ticking.
+    if (viteServer.httpServer && typeof viteServer.httpServer.once === 'function') {
+        viteServer.httpServer.once('close', () => {
+            actors.stopAll().catch(err => console.error(`${logPrefix} stopping actors on shutdown failed:`, err));
+        });
+    }
+    // An edit to a file actors load restarts them on the new code, from their snapshots.
+    if (viteServer.watcher && typeof viteServer.watcher.on === 'function') {
+        viteServer.watcher.on('change', file => {
+            const rel = relative(projectRoot, file);
+            if (rel.startsWith('..') || !ACTOR_SOURCE_DIRS.includes(rel.split(sep)[0])) return;
+            for (const mod of (viteServer.moduleGraph && viteServer.moduleGraph.getModulesByFile(file)) || []) {
+                viteServer.moduleGraph.invalidateModule(mod);
+            }
+            actors.restartAll().catch(err => console.error(`${logPrefix} restarting actors after an edit failed:`, err));
+        });
+    }
+
+    // The `request` a handler sees: the page's member id, and the mocked viewer.
+    const requestFor = clientId => ({ member: memberIdFor(clientId), user: { ...devUser }, roles });
 
     function recordsFor(clientId) {
         let records = subscriptions.get(clientId);
@@ -170,14 +205,15 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         return records;
     }
 
-    function takeSendToken(username) {
+    function takeSendToken(username, budget = rate) {
         const at = now();
-        let bucket = buckets.get(username);
+        const key = budget === rate ? username : `actor:${username}`;
+        let bucket = buckets.get(key);
         if (!bucket) {
-            bucket = { tokens: rate.burst, ts: at };
-            buckets.set(username, bucket);
+            bucket = { tokens: budget.burst, ts: at };
+            buckets.set(key, bucket);
         }
-        bucket.tokens = Math.min(rate.burst, bucket.tokens + (Math.max(0, at - bucket.ts) / 1000) * rate.perSecond);
+        bucket.tokens = Math.min(budget.burst, bucket.tokens + (Math.max(0, at - bucket.ts) / 1000) * budget.perSecond);
         bucket.ts = at;
         if (bucket.tokens < 1) return false;
         bucket.tokens -= 1;
@@ -209,13 +245,13 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
 
     // Run one export with the channel bag under the handler's timeout. A thrown
     // channel error keeps its status; anything else is 500 app_channel_<export>_failed.
-    async function runExport(mod, exportName, { channel, params, payload }) {
+    async function runExport(mod, exportName, { channel, params, payload, clientId }) {
         const { bag } = await bagBuilder.build();
         const invocation = {
             ...bag,
             channel: { name: channel, params, broadcast: async (event, body, options) => await bag.broadcast(channel, event, body, options) },
             payload: payload === undefined ? null : payload,
-            request: { user: { ...devUser }, roles }
+            request: requestFor(clientId)
         };
         const cap = Math.min(Number(mod.config && mod.config.timeout) || timeoutMs, timeoutMs);
         let timer;
@@ -252,12 +288,17 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         if (Array.isArray(required) && required.length > 0 && !required.some(r => roles.includes(r))) {
             throw channelError('app_channel_role_required', 403);
         }
-        if (typeof mod.join === 'function') {
+        if (isActorModule(mod)) {
+            // the channel's actor runs join itself (and starts on the first one)
+            if (isWildcardName(channel)) throw channelError('app_channel_actor_wildcard', 403);
+            await actors.join({ channel, params: record.params, filePath: resolved.file.filePath, clientId, request: requestFor(clientId) });
+            record.actor = true;
+        } else if (typeof mod.join === 'function') {
             // admitted only when the handler returned exactly true
             if (await runExport(mod, 'join', record) !== true) throw channelError('app_channel_join_refused', 403);
         }
         recordsFor(clientId).set(channel, record);
-        console.log(`${logPrefix} join("${channel}") admitted${typeof mod.join === 'function' ? '' : ' (no join export)'}`);
+        console.log(`${logPrefix} join("${channel}") admitted${record.actor ? ' (actor)' : typeof mod.join === 'function' ? '' : ' (no join export)'}`);
         return mod;
     }
 
@@ -267,6 +308,10 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         if (!record) return;
         records.delete(channel);
         if (!record.file) return;
+        if (record.actor) {
+            await actors.leave({ channel, clientId }).catch(err => console.warn(`${logPrefix} leave("${channel}") failed: ${err.message}`));
+            return;
+        }
         try {
             const mod = await viteServer.ssrLoadModule(record.file.filePath);
             if (typeof mod.leave === 'function') await runExport(mod, 'leave', record);
@@ -282,6 +327,12 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         if (!isEventName(event)) throw channelError('app_channel_invalid_event', 400);
         if (isReservedEvent(event)) throw channelError('app_channel_reserved_event', 400);
         if (!record.file) throw channelError('app_channel_no_handler', 404);
+        if (record.actor) {
+            if (LIFECYCLE_EXPORTS.includes(event) || ACTOR_LIFECYCLE.includes(event)) throw channelError('app_channel_no_handler', 404);
+            if (!takeSendToken(devUser.username, ACTOR_SEND_RATE)) throw channelError('app_channel_rate_limited', 429);
+            const result = await actors.send({ channel, params: record.params, filePath: record.file.filePath, clientId, request: requestFor(clientId), event, payload });
+            return result === undefined ? null : result;
+        }
         const mod = await viteServer.ssrLoadModule(record.file.filePath);
         if (LIFECYCLE_EXPORTS.includes(event) || typeof mod[event] !== 'function') throw channelError('app_channel_no_handler', 404);
         if (!takeSendToken(devUser.username)) throw channelError('app_channel_rate_limited', 429);
@@ -290,7 +341,7 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
         return result === undefined ? null : result;
     }
 
-    return async function devChannelHandlersMiddleware(req, res, next) {
+    async function devChannelHandlersMiddleware(req, res, next) {
         const parsed = parseUrl(req.url, true);
         const route = `${req.method} ${parsed.pathname}`;
         let body = {};
@@ -315,7 +366,10 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
                 if (mod && typeof mod.joined === 'function') {
                     const record = recordsFor(body.clientId).get(body.channel);
                     setImmediate(() => {
-                        runExport(mod, 'joined', record).catch(err => console.warn(`${logPrefix} joined("${body.channel}") failed: ${err.message}`));
+                        const run = record.actor
+                            ? actors.joined({ channel: body.channel, clientId: body.clientId, request: requestFor(body.clientId) })
+                            : runExport(mod, 'joined', record);
+                        run.catch(err => console.warn(`${logPrefix} joined("${body.channel}") failed: ${err.message}`));
                     });
                 }
                 return;
@@ -324,12 +378,16 @@ export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader,
                 await unsubscribe(body);
                 return sendJson(res, 200, { ok: true });
             }
-            return sendJson(res, 200, { result: await send(body) });
+            // `now`, as the server stamps it: the page's serverNow() reads it
+            return sendJson(res, 200, { result: await send(body), now: Date.now() });
         } catch (err) {
             const status = typeof err.statusCode === 'number' ? err.statusCode : 500;
             if (status === 500) console.error(logPrefix, err);
             else if (route === 'POST /subscribe') console.log(`${logPrefix} join("${body.channel}") refused (${err.code || err.message})`);
             sendJson(res, status, { error: err.code || err.message });
         }
-    };
+    }
+    // the running actors, for tests and the terminal
+    devChannelHandlersMiddleware.actors = actors;
+    return devChannelHandlersMiddleware;
 }

package/src/dev-channel-shim.js

@@ -134,6 +134,30 @@ export function generateDevChannelShim() {
             hot.on('vite:ws:connect', subscribeAll);
         }
 
+        // A page that goes away (closed, reloaded, navigated off) leaves its
+        // channels, as its socket closing does on the server, or an actor
+        // would keep it as a member and never go idle. One the browser keeps
+        // and brings back (the back/forward cache) joins them again.
+        if (hot && typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+            window.addEventListener('pagehide', function () {
+                open.forEach(function (ch) {
+                    if (!ch._admitted) return;
+                    ch._admitted = false;
+                    ch._resume = true;
+                    try {
+                        fetch(API + '/unsubscribe', {
+                            method: 'POST', keepalive: true, credentials: 'same-origin',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ clientId: clientId, channel: ch.name })
+                        }).catch(function () {});
+                    } catch (e) { /* the page is going regardless */ }
+                });
+            });
+            window.addEventListener('pageshow', function (e) {
+                if (e.persisted) subscribeAll();
+            });
+        }
+
         function Channel(name, opts) {
             this.name = name;
             // null-prototype: an event name admits 'constructor' and 'toString',
@@ -355,6 +379,10 @@ export function generateDevChannelShim() {
             }).catch(function () {});
         };
 
+        // the page and the dev server share this machine's clock
+        informer.serverNow = function () { return Date.now(); };
+        Channel.prototype.serverNow = function () { return Date.now(); };
+
         informer.channel = function (name, opts) {
             if (typeof name !== 'string' || name.length > CHANNEL_NAME_MAX_LENGTH || !CHANNEL_NAME.test(name)) {
                 throw channelError('join_refused', 'Invalid channel name: ' + name);

package/src/dev-dependencies.js

@@ -165,8 +165,8 @@ const METHOD_SURFACE = {
     query: ['execute'],
     datasource: ['query'],
     integration: ['request'],
-    app: ['request'],
-    pack: ['request']
+    app: ['request', 'url'],
+    pack: ['request', 'url']
 };
 
 // Cross-app request() method allow-list — mirrors REQUEST_METHODS in
@@ -395,7 +395,7 @@ export function resolveAppBinding(binding) {
 // 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 }) {
+export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null, forwarding = null, serverOrigin = null }) {
     const context = {};
     for (const [name, decl] of Object.entries(deps || {})) {
         if (!decl || typeof decl !== 'object') continue;
@@ -403,11 +403,10 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
         if (!VALID_TARGETS.has(target)) continue;
 
         // App and pack slots bind from the plugin's `devBindings` (a human
-        // `owner:slug` pointing request() at the target app). App slots fall
-        // back to the manifest `defaultBinding` UUID; pack slots have no
-        // fallback — the pin resolves via marketplace installs, which dev
-        // doesn't have, so the devBinding names the locally-installed app.
-        // request() is the only surface either way.
+        // `owner:slug` pointing request() and url() at the target app). App
+        // slots fall back to the manifest `defaultBinding` UUID; pack slots
+        // have no fallback — the pin resolves via marketplace installs, which
+        // dev doesn't have, so the devBinding names the locally-installed app.
         if (target === 'app' || target === 'pack') {
             const fallback = (target === 'app'
                 && typeof decl.defaultBinding === 'string' && UUID_PATTERN.test(decl.defaultBinding))
@@ -415,7 +414,7 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
                 : null;
             const binding = devBindings[name] != null ? devBindings[name] : fallback;
             context[name] = binding
-                ? makeAppDevProxy({ name, binding, appFetch, kind: target })
+                ? makeAppDevProxy({ name, binding, appFetch, serverOrigin, kind: target })
                 : makeUnboundDevProxy({ name, target });
             continue;
         }
@@ -432,12 +431,31 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
 }
 
 /**
- * Dev proxy for a `target: app` or `target: pack` slot. `request()` is the
- * only surface. Pack slots reuse this wholesale — in production the pack
- * driver resolves its marketplace pin and then delegates the runtime to the
- * app driver, and the devBinding IS that resolution done by hand. The prod
- * version gate (pack_dependency_out_of_range) is not emulated: dev has no
- * pack_install to read a version from.
+ * Append an app-relative path, query string, or fragment to a view URL, or
+ * null when the result would leave the view. Mirrors joinViewPath in
+ * informer-server's modules/app/lib/app-launch.js so dev refuses the same
+ * paths prod 400s; exported so test/streams-parity.test.js can hold the two
+ * copies to the same input table.
+ *
+ * Unguarded, as the server copy is: no `path` makes the parse throw, so the
+ * one thing that can is a malformed INFORMER_URL, and that deserves to read
+ * as the config error it is rather than as a claim about '..' segments.
+ */
+export function joinViewPath(viewUrl, path) {
+    if (!path) return viewUrl;
+    const joined = /^[?#]/.test(path) ? `${viewUrl}${path}` : `${viewUrl}/${path.replace(/^\/+/, '')}`;
+    const base = new URL(viewUrl, 'http://localhost').pathname;
+    const resolved = new URL(joined, 'http://localhost').pathname;
+    return resolved === base || resolved.startsWith(`${base}/`) ? joined : null;
+}
+
+/**
+ * Dev proxy for a `target: app` or `target: pack` slot, with prod's
+ * `request()` and `url()` surface. Pack slots reuse this wholesale — in
+ * production the pack driver resolves its marketplace pin and then delegates
+ * the runtime to the app driver, and the devBinding IS that resolution done
+ * by hand. The prod version gate (pack_dependency_out_of_range) is not
+ * emulated: dev has no pack_install to read a version from.
  *
  * Production runs `request()` through the target's own /view/_/ dispatch, and
  * dev injects into the same route:
@@ -452,16 +470,21 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
  *       Non-JSON success responses follow the prod envelope contract: text/HTML
  *       returns a text envelope; binary is rejected (dev can't emulate it yet).
  *
+ *   url(path) -> <INFORMER_URL>/api/apps/<app>/view[/path | ?query | #fragment]
+ *       The target's view URL on the configured server, for a page to open.
+ *
  * @param {Object} args
  * @param {string} args.name - dependency slot name
  * @param {string|{app?: string}} args.binding - devBindings entry (or the
  *   manifest defaultBinding UUID). A bare string is shorthand for `{ app }`.
  * @param {Function|null} args.appFetch - token-authed fetch, or null when
  *   INFORMER_APP_TOKEN is unset.
+ * @param {string|null} [args.serverOrigin] - INFORMER_URL, the server url()
+ *   links point at.
  * @param {'app'|'pack'} [args.kind] - slot flavor, for error labels and the
  *   structured resourceType guest code branches on.
  */
-function makeAppDevProxy({ name, binding, appFetch, kind = 'app' }) {
+function makeAppDevProxy({ name, binding, appFetch, serverOrigin = null, kind = 'app' }) {
     const { app } = resolveAppBinding(binding);
 
     return {
@@ -522,6 +545,25 @@ function makeAppDevProxy({ name, binding, appFetch, kind = 'app' }) {
                 return { status, body, contentType: contentType || '', headers: { 'content-type': contentType || '' } };
             }
             return body;
+        },
+
+        async url(path) {
+            if (!app) {
+                throw new Error(
+                    `Dependency "${name}" (${kind}): dev url() needs the target app — set devBindings.${name}.app (e.g. 'admin:kanban')`
+                );
+            }
+            if (!serverOrigin) {
+                throw new Error(`Dependency "${name}" (${kind}): dev url() needs INFORMER_URL, the server its links point at`);
+            }
+            if (path !== undefined && path !== null && typeof path !== 'string') {
+                throw new Error(`Dependency "${name}" (${kind}): url(path) takes a string`);
+            }
+            const href = joinViewPath(`${serverOrigin}/api/apps/${encodeURIComponent(app)}/view`, path);
+            if (!href) {
+                throw new Error(`Dependency "${name}" (${kind}): url(path) must not escape the target app with ".." path segments`);
+            }
+            return href;
         }
     };
 }

package/src/dev-platform.js

@@ -31,6 +31,8 @@ export const DEV_CAPABILITIES = Object.freeze({
     // live channels: broadcast() in the sandbox, the `channels:` relay block,
     // and channels/ join/leave handlers — the dev server mirrors all three.
     channels: true,
+    // channels/ files with config.actor: one live instance per channel (dev-channel-actors.js)
+    channelActors: true,
     embeddings: false
 });
 

package/src/openapi-to-dts.js

@@ -109,6 +109,10 @@ function slotInterface (iface, spec) {
     return [
         `export interface ${iface} {`,
         overloads.join('\n'),
+        `    /** Link into the target app's UI: its view root, or a path, query or`,
+        `     *  fragment under it. Absolute wherever the deployment names an`,
+        `     *  external address — always, when apps serve from their own origins. */`,
+        '    url(path?: string): Promise<string>;',
         '}'
     ].join('\n');
 }

package/src/server-routes.js

@@ -164,8 +164,8 @@ async function walkJsFiles(dir, basePath) {
  * 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.
+ * there's no isolate to attribute the throw to). The header rule is shared
+ * with prod's modules/app/lib/handler-headers.js — change both.
  */
 function sendDescriptor(res, result) {
     const encoding = typeof result.encoding === 'string' ? result.encoding : null;
@@ -177,28 +177,38 @@ function sendDescriptor(res, result) {
     }
     const responseBody = result.body !== undefined ? result.body : null;
 
+    // Validate before writing anything: prod rejects a malformed body while
+    // building the response, so nothing of the handler's reaches the client. Left
+    // below the header loop, a 500 here still carried the handler's
+    // Content-Disposition and the browser saved a .pdf full of JSON.
+    if (encoding === 'base64' && !isBase64(responseBody)) {
+        throw new Error('Handler returned malformed base64 body');
+    }
+
     res.statusCode = result.status || 200;
+    // Lowercased for wire parity with Hapi. Node's header lookup is
+    // case-insensitive either way, which is why dev never reproduced I5-12972.
     for (const [key, value] of Object.entries(result.headers || {})) {
-        res.setHeader(key, value);
+        res.setHeader(key.toLowerCase(), value);
+    }
+
+    // Same rule as prod's applyHandlerHeaders, and applied before the body is
+    // branched on so it covers base64 too. Dev used to leave a binary response
+    // unlabelled, which the browser sniffed happily while prod shipped it as
+    // application/json — the I5-12972 failure, arrived at from the other side.
+    const declaredType = res.getHeader('content-type');
+    if (typeof declaredType !== 'string' || !declaredType.trim()) {
+        res.setHeader('content-type', 'application/json');
     }
 
     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));
     }
 }