@volter/world-runtime 3.0.30 → 3.0.32

package/dist/src/branch.js

@@ -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.js";
 import { downWorld, saveWorldInstance, statusWorld, upWorld } from "./runtime.js";
 import { parseInfraDefinition, pgliteDown, pgliteUp } from "./pglite-backing.js";
 import { redisTwinCli, redisTwinDown, redisTwinUp } from "./redis-backing.js";
@@ -99,6 +100,8 @@ export async function branchWorld(base, name, options = {}) {
             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) {

package/dist/src/browsers.d.ts

@@ -0,0 +1,29 @@
+import { type BrowserState } from '@volter/world-core';
+export type WorldBrowser = {
+    name: string;
+    state: BrowserState;
+    version: string;
+};
+/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
+export declare const browsersDir: (data: string) => string;
+export declare function worldBrowser(data: string, name: string): WorldBrowser | null;
+export declare function worldBrowsers(data: string): WorldBrowser[];
+export declare function putWorldBrowser(data: string, name: string, state: BrowserState): WorldBrowser;
+export declare function deleteWorldBrowser(data: string, name: string): void;
+export declare function inheritWorldBrowsers(fromData: string, toData: string): void;
+/** Derived files under the World state directory, written only by its current branch. */
+export declare function materializeBrowserFiles(data: string, root: string, name: string, main?: string): void;
+export declare function clearBrowserFiles(data: string, root: string): void;
+/** 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 declare const browserLoadId: (version: string, site: string) => string;
+export declare function browserLoad(data: string, id: string | undefined): BrowserLoad | null;
+export declare function putBrowserLoad(data: string, id: string, load: BrowserLoad): void;

package/dist/src/browsers.js

@@ -0,0 +1,180 @@
+import { assertBrowserName, validateBrowserState } from '@volter/world-core';
+import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
+export const browsersDir = (data) => join(dirname(data), 'browser-records');
+const path = (data, name) => { assertBrowserName(name); return join(browsersDir(data), `${name}.json`); };
+const records = new WeakMap();
+export function worldBrowser(data, name) {
+    const store = getActiveWorldStore();
+    const file = path(data, name);
+    const cache = records.get(store) ?? new Map();
+    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);
+    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) => {
+        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) {
+    return getActiveWorldStore().list(browsersDir(data)).filter(f => f.endsWith('.json')).sort().map(f => worldBrowser(data, f.slice(0, -5)));
+}
+export function putWorldBrowser(data, name, state) {
+    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, name) {
+    const store = getActiveWorldStore();
+    store.remove(path(data, name));
+    records.get(store)?.delete(path(data, name));
+    retireBrowserLoads(data, name);
+}
+export function inheritWorldBrowsers(fromData, toData) {
+    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, root, name, main = name) {
+    const store = getActiveWorldStore();
+    const stateDir = join(root, stateDirName());
+    const config = store.read(join(stateDir, 'world.json'));
+    if (config)
+        main = JSON.parse(config).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 = null;
+        const text = store.read(index);
+        if (text)
+            previous = JSON.parse(text);
+        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, root) {
+    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);
+        if (held.data !== data)
+            return;
+        for (const name of held.names) {
+            assertBrowserName(name);
+            store.remove(join(dir, `${name}.json`));
+        }
+        store.remove(index);
+    });
+}
+export const browserLoadId = (version, site) => createHash('sha256').update(`${version}\0${site}`).digest('hex');
+const loadPath = (data, id) => join(dirname(data), 'browser-loads', `${id}.json`);
+export function browserLoad(data, id) {
+    if (!id || !/^[a-f0-9]{64}$/.test(id))
+        return null;
+    const text = getActiveWorldStore().read(loadPath(data, id));
+    return text === null ? null : JSON.parse(text);
+}
+export function putBrowserLoad(data, id, load) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        throw new Error('invalid browser load marker');
+    const held = browserLoad(data, id);
+    const cookies = new Map();
+    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, name, current) {
+    const store = getActiveWorldStore();
+    const dir = join(dirname(data), 'browser-loads');
+    const retiredFile = join(dir, `retired-${name}.json`);
+    const prior = new Map();
+    const keep = (load) => {
+        const cookies = new Map();
+        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))
+            keep(load);
+    const removed = [];
+    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/dist/src/index.d.ts

@@ -53,3 +53,4 @@ export type { ServedWorld } from './served-world.js';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.js';
 export { assertWorldStateRemovable } from './ancestry.js';
 export { withoutVaultSignIn } from './runtime.js';
+export { materializeBrowserFiles, browsersDir, worldBrowser, worldBrowsers, putWorldBrowser, deleteWorldBrowser, inheritWorldBrowsers, type WorldBrowser } from './browsers.js';

package/dist/src/index.js

@@ -37,3 +37,4 @@ export { LOCAL_ORIGIN_BASE, localWorldOrigin, pagesOfHost, pagesOriginOf, pathOf
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";
 export { withoutVaultSignIn } from "./runtime.js";
+export { materializeBrowserFiles, browsersDir, worldBrowser, worldBrowsers, putWorldBrowser, deleteWorldBrowser, inheritWorldBrowsers } from "./browsers.js";

package/dist/src/init.d.ts

@@ -227,7 +227,7 @@ export declare function renderEnvFile(plan: InitPlan): string;
 /** Write the plan's two artifacts. Byte-identical for the same repo + catalog: sorted keys, no
  * timestamps, no absolute paths inside the files. */
 /** What `.volter/.gitignore` says: the story is committed, the running state never is. */
-export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\ntoken.read\nsessions.json\npages-sessions.json\nkeys.json\n";
+export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\ntoken.read\nsessions.json\npages-sessions.json\nbrowsers/\nkeys.json\n";
 export declare function writeWorldInit(plan: InitPlan, options?: {
     force?: boolean;
 }): void;

package/dist/src/init.js

@@ -1088,6 +1088,7 @@ token
 token.read
 sessions.json
 pages-sessions.json
+browsers/
 keys.json
 `;
 export function writeWorldInit(plan, options = {}) {
@@ -1138,17 +1139,48 @@ export function seedCallsRunner(vendor) {
     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/dist/src/local-branches.js

@@ -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.js";
+import { inheritWorldBrowsers, materializeBrowserFiles } from "./browsers.js";
+import { clockFile, statusWorld } from "./runtime.js";
 import { loadWorldConfig } from "./configs.js";
 import { TOKEN_HEADER } from "./served-world.js";
 const RECORD = 'branch.json';
@@ -167,6 +168,9 @@ export class LocalBranches {
                 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/dist/src/pack-facts.d.ts

@@ -1,3 +1,4 @@
+import { type HostPredicate } from '@volter/world-core/host-routing';
 export type PackAdoption = {
     sdks?: string[];
     pypi?: string[];
@@ -108,3 +109,6 @@ export declare function overlayEndpointEnv(table: Record<string, {
     injectEnvTemplates?: Record<string, string>;
     note: string;
 }>): void;
+/** Facts supplied by resolved packs, compiled after the built-in facts in a routing table. */
+export declare function overlaidPackVendors(): string[];
+export declare function packHostRules(): Record<string, HostPredicate>;

package/dist/src/pack-facts.js

@@ -7,6 +7,7 @@
 // The overlay MUTATES the central tables at module init — every use-site keeps reading the
 // 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 } from '@volter/world-core/host-routing';
 import factsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 // world-runtime and core are sibling workspace packages; the artifact is committed,
 // so a missing file is a broken checkout (or an unbuilt generator change), never a soft state.
@@ -106,3 +107,16 @@ export function overlayEndpointEnv(table) {
         };
     }
 }
+/** Facts supplied by resolved packs, compiled after the built-in facts in a routing table. */
+export function overlaidPackVendors() { return Object.keys(overlaid); }
+/** One routing table per immutable merged-facts version, built only for browser routing. */
+const hostTables = new WeakMap();
+export function packHostRules() {
+    const facts = packFacts();
+    let rules = hostTables.get(facts);
+    if (!rules) {
+        rules = createHostTable(facts, overlaidPackVendors()).hosts;
+        hostTables.set(facts, rules);
+    }
+    return rules;
+}

package/dist/src/placeholder.js

@@ -7,9 +7,11 @@
 // keep is a fork, taken before.
 import { materializeRoots } from "./root.js";
 import { loadWorldConfig } from "./configs.js";
+import { WorldDoors, servedName } from "./served-world.js";
+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.js";
 /** The seed entry `init` emits beside the world config, unless the caller names one. */
 export function seedEntryFor(instance, entry) {
@@ -54,7 +56,18 @@ export async function seedWorld(name, options = {}) {
     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;
     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,9 +77,10 @@ export async function seedWorld(name, options = {}) {
                 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));
     }

package/dist/src/redirect-proxy.js

@@ -1,4 +1,4 @@
-import { BROWSER_SESSION_HEADER, serveHttp } from '@volter/world-core/runtime';
+import { serveHttp } from '@volter/world-core/runtime';
 import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress } from '@volter/world-core/network-policy';
 import { websocketRelay } from "./websocket-relay.js";
 // The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
@@ -350,7 +350,7 @@ export async function startRedirectProxy(options) {
                 }
                 const origin = new URL(twin.origin);
                 const headers = new Headers(req.headers);
-                for (const h of [BROWSER_SESSION_HEADER, 'proxy-connection', 'accept-encoding', 'connection'])
+                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') {
@@ -479,9 +479,9 @@ export async function startRedirectProxy(options) {
                 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`);

package/dist/src/reflect.js

@@ -1,4 +1,3 @@
-import { BROWSER_SESSION_HEADER } from '@volter/world-core/runtime';
 import { serveHttp } from '@volter/world-core/runtime';
 import { websocketRelay } from "./websocket-relay.js";
 import { sessionTrustEnv } from "./ca-trust.js";
@@ -140,7 +139,7 @@ export async function startReflectFront(options) {
                     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/dist/src/runtime.js

@@ -1,3 +1,4 @@
+import { materializeBrowserFiles, clearBrowserFiles } from "./browsers.js";
 import { claimEnvOutput, publishEnvOutput } from "./env-output.js";
 import { offSignal } from "./signals.js";
 import { parallelStartup } from "./startup.js";
@@ -1792,7 +1793,7 @@ export async function upWorld(configId, options = {}, abort) {
             }
             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 });
@@ -2011,6 +2012,7 @@ export async function upWorld(configId, options = {}, abort) {
             // 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))];
@@ -2389,7 +2391,12 @@ async function downWorldClaimed(name, root, options) {
             })}\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 };
     }));
 }
 export function statusWorld(name, root = process.cwd(), options = {}) {

package/dist/src/served-world.d.ts

@@ -67,6 +67,10 @@ export type MountedWorld = {
     boot: (url: string) => Promise<void>;
     stop: () => Promise<void>;
 };
+/** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
+/** What a content-plane pass, and the session it opens, carry: its scope; the control session that asked (the content
+ *  session ends with it; none when the World's token asked); the person; the console that frames it; and whether it
+ *  is this machine's own page (attributed to the machine). */
 type PagesGrant = {
     scope: 'read' | 'write';
     session?: string;
@@ -74,7 +78,8 @@ type PagesGrant = {
     framer?: string;
     local?: true; /** the hosted site it
      *  opens (a hostname this World's twins answer), not the content plane */
-    site?: string; /** a parent World's session that asked
+    site?: string;
+    browser?: string; /** a parent World's session that asked
     *  for a branch's page, as an opaque mark: the branch keeps one content session per asker and caps passes by it, but
     *  cannot tell when it ends, so such a session lasts an hour */
     asker?: string;
@@ -110,6 +115,7 @@ export type WorldLayout = {
     dirs: {
         data: string;
     };
+    envFile?: string;
     services: Record<string, {
         url?: string;
         protocol?: unknown;
@@ -262,13 +268,6 @@ export declare class WorldDoors {
     private keepCookiesHere;
     /** What the content plane answers: its opening page and session, and the twins' pages; no door of the World. */
     private pagesPlane;
-    /** A landing resolved as a browser resolves it, within this vendor's place only. */
-    private vendorLanding;
-    /** The pack's declared browser session, never inferred from its vendor or a sign-in page. */
-    private browserSessionOf;
-    private vendorPeople;
-    /** The twin receives its own cookie and changes the session in its own process, over a host-only permit. */
-    private vendorSession;
     /** BROWSER SESSIONS: the session cookie carries an opaque id, never a token, so a leaked cookie is one session and
      *  not the World's write token; rotating the tokens ends every session. Kept in the World's store, so a restart
      *  keeps them; each lasts 30 days from its opening. */
@@ -381,6 +380,10 @@ export declare class WorldDoors {
         vendor: string;
         hosts: string[];
     }>>;
+    /** Browser sites include the pack's exact declared hosts, beside the dynamically claimed sites. */
+    private browserSites;
+    private browserRoutes;
+    private loadBrowser;
     /** What a twin asks an application (`ctx.ask`) that this World can answer truthfully, where no process routes it (a
      *  hosted World's isolate): a GET or HEAD of a URL whose hostname one of this World's twins answers (its hostsClaimed
      *  door: a Cloudflare twin's Worker route or custom domain) is that twin's answer, read as a browser reads the site
@@ -395,7 +398,7 @@ export declare class WorldDoors {
     /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
      *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
      *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */
-    site(request: Request, host: string): Promise<Response>;
+    site(request: Request, host: string, browser?: string, grant?: PagesGrant): Promise<Response>;
     handle(request: Request): Promise<Response>;
     /** A twin's workspaces as its discovery door lists them (`GET /twin`'s `screens`: each built workspace screen's id and
      *  path), which a person is shown at `/<served>/<vendor><path>`. Asked again after a minute, as `enforcesRead` is. */