@volter/world-runtime 3.0.30 → 3.0.32

package/dist/src/world-origins.js

@@ -69,7 +69,7 @@ export function siteOfHost(hostname, served, base = LOCAL_ORIGIN_BASE) {
         if (!label || !rest.endsWith(`.${label}`))
             continue;
         const site = rest.slice(0, -(label.length + 1));
-        if (site.includes('.'))
+        if (site.includes('.') || site.includes('--'))
             return { world: name, site };
     }
     return undefined;

package/dist/src/world-view.js

@@ -3,6 +3,8 @@
 // World"). `volter world view` is this; the runtime's `up` gains no step. A host that serves many
 // Worlds (world-host) answers the same doors; this serves one, and the branches made of it.
 import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { materializeBrowserFiles } from "./browsers.js";
+import { statusWorld } from "./runtime.js";
 import { loadWorldConfig } from "./configs.js";
 import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core/runtime';
@@ -90,6 +92,8 @@ export async function serveWorldView(name, opts = {}) {
                 rmSync(current, { force: true });
             else
                 writeFileSync(current, `${branch}\n`);
+            const selected = statusWorld(branch, root);
+            materializeBrowserFiles(selected.dirs.data, root, branch, selected.config);
         }
         finally {
             switching = false;
@@ -118,7 +122,7 @@ export async function serveWorldView(name, opts = {}) {
             // a site the World's twins answer, under the World's local origin (`<hostname>.<world>--<org>.localhost`)
             const site = origins && !proxied ? siteOfHost(at.hostname, worlds.keys()) : undefined;
             if (site)
-                return worlds.get(site.world).site(request, site.site);
+                return !site.site.includes('.') && site.site.includes('--') ? worlds.get(site.world).handle(request) : worlds.get(site.world).site(request, site.site);
             // a World's content plane serves that World's twins' pages and nothing else of this view's (no console)
             const pagesFor = origins && !proxied ? pagesOfHost(at.hostname, worlds.keys()) : undefined;
             if (pagesFor)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.30",
+  "version": "3.0.32",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -68,14 +68,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.30",
-    "@volter/world-console": "3.0.25"
+    "@volter/world-core": "3.0.32",
+    "@volter/world-console": "3.0.27"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.30",
+    "@volter/world-core": "3.0.32",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/branch.ts

@@ -10,6 +10,7 @@ import { cpSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withHistoryLocks, worldPaths, worldStateRoot } from '@volter/world-core/runtime';
+import { inheritWorldBrowsers, materializeBrowserFiles } from './browsers.ts';
 import { downWorld, saveWorldInstance, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 import { parseInfraDefinition, pgliteDown, pgliteUp } from './pglite-backing.ts';
@@ -80,6 +81,8 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
       }
       if (states.length) forked[service] = states.map(s => s.state);
     }
+    inheritWorldBrowsers(from.dirs.data, instance.dirs.data);
+    materializeBrowserFiles(instance.dirs.data, root, name, instance.config);
     await branchManagedDatabases(from, instance, databases);
   } catch (error) {
     await downWorld(name, root, { purge: true, expectedCreatedAt: instance.createdAt });

package/src/browsers.ts

@@ -0,0 +1,146 @@
+import { assertBrowserName, validateBrowserState, type BrowserState } from '@volter/world-core';
+import { getActiveWorldStore, stateDirName, type WorldStore } from '@volter/world-core/runtime';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+
+export type WorldBrowser = { name: string; state: BrowserState; version: string };
+/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
+export const browsersDir = (data: string): string => join(dirname(data), 'browser-records');
+const path = (data: string, name: string): string => { assertBrowserName(name); return join(browsersDir(data), `${name}.json`); };
+const records = new WeakMap<WorldStore, Map<string, { version: string; text: string; record: WorldBrowser }>>();
+export function worldBrowser(data: string, name: string): WorldBrowser | null {
+  const store = getActiveWorldStore();
+  const file = path(data, name);
+  const cache = records.get(store) ?? new Map<string, { version: string; text: string; record: WorldBrowser }>();
+  records.set(store, cache);
+  const text = store.read(file);
+  if (text === null) { cache.delete(file); return null; }
+  const held = cache.get(file);
+  if (held?.text === text) return held.record;
+  const record = JSON.parse(text) as WorldBrowser;
+  if (record.name !== name || typeof record.version !== 'string') throw new Error(`invalid browser record: ${name}`);
+  if (held?.version === record.version) { held.text = text; return held.record; }
+  validateBrowserState(record.state);
+  const freeze = (value: unknown): void => {
+    if (!value || typeof value !== 'object') return;
+    for (const item of Object.values(value)) freeze(item);
+    Object.freeze(value);
+  };
+  freeze(record);
+  cache.set(file, { version: record.version, text, record });
+  return record;
+}
+export function worldBrowsers(data: string): WorldBrowser[] {
+  return getActiveWorldStore().list(browsersDir(data)).filter(f => f.endsWith('.json')).sort().map(f => worldBrowser(data, f.slice(0, -5))!);
+}
+export function putWorldBrowser(data: string, name: string, state: BrowserState): WorldBrowser {
+  const record = { name, state: validateBrowserState(state), version: randomUUID() };
+  getActiveWorldStore().writeAtomic(path(data, name), `${JSON.stringify(record)}\n`, { secret: true });
+  retireBrowserLoads(data, name, record);
+  return record;
+}
+export function deleteWorldBrowser(data: string, name: string): void {
+  const store = getActiveWorldStore();
+  store.remove(path(data, name));
+  records.get(store)?.delete(path(data, name));
+  retireBrowserLoads(data, name);
+}
+export function inheritWorldBrowsers(fromData: string, toData: string): void {
+  const store = getActiveWorldStore();
+  for (const b of worldBrowsers(fromData)) store.writeAtomic(path(toData, b.name), `${JSON.stringify(b)}\n`, { secret: true });
+}
+
+/** Derived files under the World state directory, written only by its current branch. */
+export function materializeBrowserFiles(data: string, root: string, name: string, main = name): void {
+  const store = getActiveWorldStore();
+  const stateDir = join(root, stateDirName());
+  const config = store.read(join(stateDir, 'world.json'));
+  if (config) main = (JSON.parse(config) as { id: string }).id;
+  if ((store.read(join(stateDir, 'current'))?.trim() || main) !== name) return;
+  const rows = worldBrowsers(data);
+  const dir = join(stateDir, 'browsers');
+  const index = join(dir, '.source.json');
+  if (!rows.length && store.read(index) === null) return;
+  if (rows.length) {
+    const ignore = join(stateDir, '.gitignore');
+    const held = store.read(ignore) ?? '';
+    if (!held.split('\n').includes('browsers/')) store.write(ignore, `${held.replace(/\n?$/, '\n')}browsers/\n`);
+  }
+  store.withLock(join(dir, '.lock'), () => {
+    let previous: { data: string; names: string[] } | null = null;
+    const text = store.read(index);
+    if (text) previous = JSON.parse(text) as { data: string; names: string[] };
+    for (const name of previous?.names ?? []) { assertBrowserName(name); if (!rows.some(b => b.name === name)) store.remove(join(dir, `${name}.json`)); }
+    for (const b of rows) store.writeAtomic(join(dir, `${b.name}.json`), `${JSON.stringify(b.state)}\n`, { secret: true });
+    if (rows.length) store.writeAtomic(index, `${JSON.stringify({ data, names: rows.map(b => b.name) })}\n`, { secret: true }); else store.remove(index);
+  });
+}
+export function clearBrowserFiles(data: string, root: string): void {
+  const store = getActiveWorldStore();
+  const dir = join(root, stateDirName(), 'browsers');
+  const index = join(dir, '.source.json');
+  if (store.read(index) === null) return;
+  store.withLock(join(dir, '.lock'), () => {
+    const text = store.read(index);
+    if (!text) return;
+    const held = JSON.parse(text) as { data: string; names: string[] };
+    if (held.data !== data) return;
+    for (const name of held.names) { assertBrowserName(name); store.remove(join(dir, `${name}.json`)); }
+    store.remove(index);
+  });
+}
+
+/** Private load-marker history; the cookie carries only an opaque id, never vendor state. */
+export type BrowserLoad = { name: string; site: string; version: string; cookies: Array<{ name: string; path: string }> };
+export const browserLoadId = (version: string, site: string): string => createHash('sha256').update(`${version}\0${site}`).digest('hex');
+const loadPath = (data: string, id: string): string => join(dirname(data), 'browser-loads', `${id}.json`);
+export function browserLoad(data: string, id: string | undefined): BrowserLoad | null {
+  if (!id || !/^[a-f0-9]{64}$/.test(id)) return null;
+  const text = getActiveWorldStore().read(loadPath(data, id));
+  return text === null ? null : JSON.parse(text) as BrowserLoad;
+}
+export function putBrowserLoad(data: string, id: string, load: BrowserLoad): void {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('invalid browser load marker');
+  const held = browserLoad(data, id);
+  const cookies = new Map<string, { name: string; path: string }>();
+  if (held?.name === load.name && held.site === load.site && held.version === load.version) {
+    for (const cookie of held.cookies) cookies.set(JSON.stringify([cookie.name, cookie.path]), cookie);
+  }
+  for (const cookie of load.cookies) cookies.set(JSON.stringify([cookie.name, cookie.path]), cookie);
+  getActiveWorldStore().writeAtomic(loadPath(data, id), `${JSON.stringify({ ...load, cookies: [...cookies.values()] })}\n`, { secret: true });
+}
+
+/** Retire old ids; cookie paths survive loads and deletion until carried into the name's next version. */
+function retireBrowserLoads(data: string, name: string, current?: WorldBrowser): void {
+  const store = getActiveWorldStore();
+  const dir = join(dirname(data), 'browser-loads');
+  const retiredFile = join(dir, `retired-${name}.json`);
+  const prior = new Map<string, BrowserLoad>();
+  const keep = (load: BrowserLoad): void => {
+    const cookies = new Map<string, { name: string; path: string }>();
+    for (const cookie of [...(prior.get(load.site)?.cookies ?? []), ...load.cookies]) {
+      cookies.set(JSON.stringify([cookie.name, cookie.path]), cookie);
+    }
+    prior.set(load.site, { ...load, cookies: [...cookies.values()] });
+  };
+  const retired = store.read(retiredFile);
+  if (retired !== null) for (const load of JSON.parse(retired) as BrowserLoad[]) keep(load);
+  const removed: string[] = [];
+  for (const file of store.list(dir)) {
+    if (!/^[a-f0-9]{64}\.json$/.test(file)) continue;
+    const load = browserLoad(data, file.slice(0, -5));
+    if (!load || load.name !== name || load.version === current?.version) continue;
+    keep(load);
+    removed.push(file);
+  }
+  // Preserve paths before removing the version records that supplied them.
+  if (current) {
+    for (const load of prior.values()) putBrowserLoad(data, browserLoadId(current.version, load.site), {
+      ...load, version: current.version,
+    });
+    store.remove(retiredFile);
+  } else if (prior.size) {
+    store.writeAtomic(retiredFile, `${JSON.stringify([...prior.values()])}\n`, { secret: true });
+  }
+  for (const file of removed) store.remove(join(dir, file));
+}

package/src/index.ts

@@ -177,3 +177,5 @@ export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type
 export { assertWorldStateRemovable } from './ancestry.ts';
 
 export { withoutVaultSignIn } from './runtime.ts';
+
+export { materializeBrowserFiles, browsersDir, worldBrowser, worldBrowsers, putWorldBrowser, deleteWorldBrowser, inheritWorldBrowsers, type WorldBrowser } from './browsers.ts';

package/src/init.ts

@@ -1273,6 +1273,7 @@ token
 token.read
 sessions.json
 pages-sessions.json
+browsers/
 keys.json
 `;
 
@@ -1325,17 +1326,48 @@ export function seedCallsRunner(vendor: string): string {
   return `// ${vendor}'s default data, as its twin's pack declares it (./${vendor}.data.ts: calls to the vendor's own
 // operations), made against the twin in order. Ownership transferred on copy: both files are yours — edit or delete.
 import { seed as calls } from './${vendor}.data.ts';
+import * as defaults from './${vendor}.data.ts';
+import type { SeedBrowser } from '@volter/world-core/browser';
 
 export async function seed(): Promise<void> {
   // a twin with a root is the vendor's real account: its default data is not written (VOLTER_SEED_SKIP)
   if ((process.env.VOLTER_SEED_SKIP ?? '').split(',').includes('${vendor}')) return;
   const base = process.env.${stem}_TWIN_URL;
   if (!base) throw new Error('${stem}_TWIN_URL is not set — bring the world up and run the seed with its env (volter-world attach/run)');
-  for (const call of calls) {
-    const res = await fetch(\`\${base.replace(/\\/$/, '')}\${call.path}\`, {
+  const clients = new Map<string, SeedBrowser>();
+  const snapshots = new Map<string, Awaited<ReturnType<SeedBrowser['state']>>>();
+  let browserHelper: typeof import('@volter/world-core/browser') | undefined;
+  const browserCalls = ('browserSeed' in defaults ? defaults.browserSeed as typeof calls : undefined) ?? [];
+  for (const call of [...calls, ...browserCalls]) {
+    if (call.browser) {
+      if (!snapshots.has(call.browser)) {
+        const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
+        const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
+        if (!door || !token) throw new Error('browser defaults run in a World seed with its browsers door and credential');
+        const held = await fetch(\`\${door}/\${encodeURIComponent(call.browser)}\`, { headers: { 'x-volter-token': token } });
+        if (!held.ok && held.status !== 404) throw new Error(\`browser \${call.browser}: \${held.status} \${await held.text()}\`);
+        snapshots.set(call.browser, held.ok ? await held.json() as Awaited<ReturnType<SeedBrowser['state']>> : { cookies: [], origins: [] });
+      }
+      browserHelper ??= await import('@volter/world-core/browser').catch(error => {
+        throw new Error('Install @volter/world-core 3.0.31 or later in this project to seed browsers.', { cause: error });
+      });
+      const initial = snapshots.get(call.browser)!;
+      const hostname = new URL(call.path).hostname;
+      if (initial.cookies.some(cookie => browserHelper!.cookieMatchesHost(cookie, hostname))
+        || initial.origins.some(origin => new URL(origin.origin).hostname === hostname)) continue;
+    }
+    const headers = { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) };
+    const form = /^application\\/x-www-form-urlencoded\\b/i.test(new Headers(headers).get('content-type') ?? '');
+    const body = call.body === undefined ? undefined : form
+      ? new URLSearchParams(Object.entries(call.body as Record<string, unknown>).map(([key, value]) => [key, String(value)]))
+      : JSON.stringify(call.body);
+    if (call.browser && !clients.has(call.browser)) {
+      clients.set(call.browser, await browserHelper!.browser(call.browser));
+    }
+    const client = call.browser ? clients.get(call.browser)! : null;
+    const res = await (client ? client.fetch : fetch)(client ? call.path : \`\${base.replace(/\\/$/, '')}\${call.path}\`, {
       method: call.method,
-      headers: { ...(call.body !== undefined ? { 'content-type': 'application/json' } : {}), ...(call.headers ?? {}) },
-      ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+      headers, ...(body === undefined ? {} : { body }),
     });
     if (!res.ok) throw new Error(\`${vendor} seed: \${call.method} \${call.path}: \${res.status} \${await res.text()}\`);
   }

package/src/local-branches.ts

@@ -6,7 +6,8 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { stateDirName, withStateRemoval } from '@volter/world-core/runtime';
-import { clockFile } from './runtime.ts';
+import { inheritWorldBrowsers, materializeBrowserFiles } from './browsers.ts';
+import { clockFile, statusWorld } from './runtime.ts';
 import { loadWorldConfig } from './configs.ts';
 import { TOKEN_HEADER, type BranchDoors, type BranchRow, type MountedWorld } from './served-world.ts';
 
@@ -160,6 +161,9 @@ export class LocalBranches {
       // a live branch (a pull request's preview) keeps the parent's time: real time, or its simulated clock
       const clock = at.instant ?? this.frozenClock(from) ?? (at.live ? null : new Date().toISOString());
       if (clock) { const file = clockFile(root, id); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, `${clock}\n`); }
+      const child = statusWorld(id, root);
+      inheritWorldBrowsers(statusWorld(world, from.root).dirs.data, child.dirs.data);
+      materializeBrowserFiles(child.dirs.data, root, id, child.config);
       const createdAt = new Date().toISOString();
       const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
       // what it was made as (a pull request's preview is labelled and may be live)

package/src/pack-facts.ts

@@ -8,6 +8,7 @@
 // object it always read — and a fact declared in BOTH places throws: dual declaration is the
 // drift this migration exists to end, so it is loud everywhere, not just in a test.
 
+import { createHostTable, type HostPredicate } from '@volter/world-core/host-routing';
 import factsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 
 export type PackAdoption = { sdks?: string[]; pypi?: string[]; scopes?: string[]; envStems?: string[]; worldIds?: string[]; tools?: Array<{ package: string; usage: 'build' | 'deployment' }>; configFiles?: Array<{ file: string; usage: 'application' | 'build' | 'deployment'; when?: string }> };
@@ -146,3 +147,18 @@ export function overlayEndpointEnv(
     };
   }
 }
+
+/** Facts supplied by resolved packs, compiled after the built-in facts in a routing table. */
+export function overlaidPackVendors(): string[] { return Object.keys(overlaid); }
+
+/** One routing table per immutable merged-facts version, built only for browser routing. */
+const hostTables = new WeakMap<Record<string, PackFacts>, Record<string, HostPredicate>>();
+export function packHostRules(): Record<string, HostPredicate> {
+  const facts = packFacts();
+  let rules = hostTables.get(facts);
+  if (!rules) {
+    rules = createHostTable(facts, overlaidPackVendors()).hosts;
+    hostTables.set(facts, rules);
+  }
+  return rules;
+}

package/src/placeholder.ts

@@ -7,9 +7,11 @@
 // keep is a fork, taken before.
 import { materializeRoots } from './root.ts';
 import { loadWorldConfig } from './configs.ts';
+import { WorldDoors, servedName } from './served-world.ts';
+import { randomUUID } from 'node:crypto';
 import { existsSync, readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, worldStateRoot } from '@volter/world-core/runtime';
+import { serveHttp, beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, worldStateRoot } from '@volter/world-core/runtime';
 import { downWorld, runWithWorldEnv, saveWorldInstance, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 
@@ -55,7 +57,18 @@ export async function seedWorld(name: string, options: SeedWorldOptions = {}): P
   const at = new Date().toISOString();
   for (const service of services) beginPlaceholderPull(service, join(instance.dirs.data, service), at);
   let exitCode = 1;
+  const served = servedName(root, instance.configPath);
+  const token = `tok_seed_${randomUUID()}`;
+  const doors = new WorldDoors(name, root, instance.configPath, served, {
+    ready: () => true, layout: () => instance, reload: () => statusWorld(name, root), twinFetch: () => null,
+  }, token, `tok_seed_read_${randomUUID()}`);
+  let doorServer: Awaited<ReturnType<typeof serveHttp>> | undefined;
   try {
+    doorServer = await serveHttp({ twinRequestJournal: false, maxRequestBodySize: 4 * 1024 * 1024, fetch: request => {
+      const path = new URL(request.url).pathname;
+      return path === `/-/${served}/browsers` || path.startsWith(`/-/${served}/browsers/`)
+        ? doors.handle(request) : Response.json({ error: 'the seed loader serves browser state only' }, { status: 404 });
+    } });
     // The runtime that is running runs the seed: Bun, or Node with its TypeScript type stripping
     // (`--experimental-strip-types`, accepted from Node 22.6 and on by default since 23.6). Never
     // `bun` by name: the published runtime supports Node alone, and the tab's engine has no Bun.
@@ -64,8 +77,9 @@ export async function seedWorld(name: string, options: SeedWorldOptions = {}): P
       if (major < 22 || (major === 22 && minor < 6)) throw new Error(`${entry} is TypeScript: seeding it under Node needs Node 22.6 or newer (type stripping), or Bun; this is Node ${process.versions.node}`);
     }
     const runner = typeof Bun !== 'undefined' ? ['bun', entry] : [process.execPath, '--experimental-strip-types', '--no-warnings', entry];
-    exitCode = await runWithWorldEnv(name, runner, root, { cwd: options.cwd ?? dirname(entry), env: { VOLTER_SEED_SKIP: [...rooted].sort().join(',') } });
+    exitCode = await runWithWorldEnv(name, runner, root, { cwd: options.cwd ?? dirname(entry), env: { VOLTER_SEED_SKIP: [...rooted].sort().join(','), VOLTER_WORLD_BROWSER_DOOR: `${doorServer.url.origin}/-/${served}/browsers`, VOLTER_WORLD_BROWSER_TOKEN: token } });
   } finally {
+    await doorServer?.stop();
     for (const service of services) endPlaceholderPull(service, join(instance.dirs.data, service));
   }
   const observed: Record<string, number> = {};

package/src/redirect-proxy.ts

@@ -1,4 +1,4 @@
-import { BROWSER_SESSION_HEADER, serveHttp, type HttpServer } from '@volter/world-core/runtime';
+import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
 import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress } from '@volter/world-core/network-policy';
 import { websocketRelay } from './websocket-relay.ts';
 // The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
@@ -376,7 +376,7 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
         const origin = new URL(twin.origin);
 
         const headers = new Headers(req.headers);
-        for (const h of [BROWSER_SESSION_HEADER, 'proxy-connection', 'accept-encoding', 'connection']) headers.delete(h);
+        for (const h of ['proxy-connection', 'accept-encoding', 'connection', 'x-volter-world-browser']) headers.delete(h);
         // the application is not a twin: it gets no World key, keeps its Host and hears it was reached over TLS
         if (twin.vendor === 'app') {
           headers.delete('x-twins-key');
@@ -509,9 +509,9 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
         outHeaders['x-volter-twin-original-host'] = headers.host ?? origin.host;
         outHeaders.host = origin.host;
       }
-      delete outHeaders[BROWSER_SESSION_HEADER];
       delete outHeaders['proxy-connection'];
       delete outHeaders['accept-encoding'];
+      delete outHeaders['x-volter-world-browser'];
       upstream.write(`${method} ${path} ${version}\r\n`);
       for (const [name, value] of Object.entries(outHeaders)) upstream.write(`${name}: ${value}\r\n`);
       upstream.write('\r\n');

package/src/reflect.ts

@@ -1,4 +1,3 @@
-import { BROWSER_SESSION_HEADER } from '@volter/world-core/runtime';
 import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
 import { websocketRelay } from './websocket-relay.ts';
 import { sessionTrustEnv } from './ca-trust.ts';
@@ -161,7 +160,7 @@ export async function startReflectFront(options: ReflectFrontOptions): Promise<R
         try { origin = new URL(target.origin); } catch { return new Response('bad twin origin', { status: 502 }); }
 
         const headers = new Headers(req.headers);
-        headers.delete(BROWSER_SESSION_HEADER);
+        headers.delete('x-volter-world-browser');
         headers.delete('proxy-connection');
         headers.delete('accept-encoding');
         // the consumer spoke TLS to the front; a twin that answers with an absolute URL (Slack's Socket Mode link)

package/src/runtime.ts

@@ -1,3 +1,4 @@
+import { materializeBrowserFiles, clearBrowserFiles } from './browsers.ts';
 import { claimEnvOutput, publishEnvOutput } from './env-output.ts';
 import { offSignal } from './signals.ts';
 import { parallelStartup } from './startup.ts';
@@ -1741,7 +1742,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       if (existsSync(logs)) { rmSync(join(logs, 'previous'), { recursive: true, force: true }); renameSync(logs, previousLogs); }
       try {
         if (options.keepState) {
-          const KEEP = ['data', 'marks', 'changesets', 'episodes'];
+          const KEEP = ['data', 'marks', 'changesets', 'episodes', 'browser-records', 'browser-loads'];
           for (const entry of existsSync(instance) ? readdirSync(instance) : []) if (!KEEP.includes(entry)) rmSync(join(instance, entry), { recursive: true, force: true });
         } else removeWorldState(root, instance, () => rmSync(instance, { recursive: true, force: true }));
       } catch (error) {
@@ -1930,6 +1931,7 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       // Config env and discovered credentials: a file this writes is owner-only; a file the caller already made keeps
       // the mode the caller chose (a shared env file may be read under another uid).
       publishEnvOutput(envOutputClaim, envFileContents(env));
+      materializeBrowserFiles(data, root, name, loaded.config.id);
       writePidsFromInstance(worldInstance, Object.values(worldInstance.services).map((service) => service.pid).filter((pid) => pid > 0));
       saveWorldInstance(worldInstance);
       const servicePids = [...new Set(Object.values(services).map((service) => service.pid).filter((pid) => pid > 0))];
@@ -2286,7 +2288,10 @@ async function downWorldClaimed(
       })}\n`);
     }
     releaseWorldLifecycle(resolvedRoot, name);
-    return options.purge ? { ...result, purged: purgeInstanceDir(resolvedRoot, name) } : result;
+    if (!options.purge) return result;
+    const purged = purgeInstanceDir(resolvedRoot, name);
+    if (purged && instance) clearBrowserFiles(instance.dirs.data, resolvedRoot);
+    return { ...result, purged };
   }));
 }