@volter/world-core 3.0.30 → 3.0.32

package/dist/host-routing.cjs

@@ -0,0 +1,106 @@
+'use strict';
+// Host routing is data in, answer out. No imports, environment reads or module-load table construction.
+function compileHostRule(rule, where) {
+  const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
+  if (selectors !== 1) throw new Error(`inject: ${where} rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
+  const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
+  const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
+  return (h, p) =>
+    (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
+    && (pathRe === null || p === undefined || pathRe.test(p));
+}
+
+/** A pack's host rules (its descriptor's `hosts`) read as the injector reads them: `names(host)`, whether any include
+ *  rule's selector names the host, whatever the path; `takes(host, path)`, whether the request is the pack's (under
+ *  one of its keys, an include matches and no exclude does). The content route at a World's place holds a
+ *  `<base>/@<host>/<path>` to it (pack-fetch.ts). */
+function hostRules(rules) {
+  const byKey = new Map();
+  for (const rule of rules || []) {
+    const key = rule.key === undefined ? '' : rule.key;
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(rule);
+  }
+  const keys = [...byKey.values()].map((keyRules) => ({
+    includes: keyRules.filter((r) => r.exclude !== true).map((r) => compileHostRule(r, 'a pack')),
+    excludes: keyRules.filter((r) => r.exclude === true).map((r) => compileHostRule(r, 'a pack')),
+  }));
+  return {
+    names: (h) => keys.some((k) => k.includes.some((m) => m(h))),
+    takes: (h, p) => keys.some((k) => k.includes.some((m) => m(h, p)) && !k.excludes.some((m) => m(h, p))),
+  };
+}
+
+/** Build one independent host table, in the proxy's key order, from supplied pack facts and overlays. */
+function createHostTable(packs, installed = []) {
+  const VENDOR_HOSTS = {
+    googlefavicon: (h) => h === 'www.google.com' || h === 'google.com' || h === 't2.gstatic.com',
+    browserassets: (h) =>
+      h === 'cdnjs.cloudflare.com' ||
+      h === 'www.googletagmanager.com' ||
+      h === 'www.google-analytics.com' ||
+      h === 'connect.facebook.net' ||
+      h === 'snap.licdn.com' ||
+      h === 'px.ads.linkedin.com' ||
+      h === 'static.hotjar.com' ||
+      h === 'fonts.googleapis.com' ||
+      h === 'fonts.gstatic.com' ||
+      h === 'api.fontshare.com' ||
+      h === 'images.subscribe.dev' ||
+      h === 'www.youtube.com' ||
+      h === 'www.youtube-nocookie.com' ||
+      h === 'i.ytimg.com',
+  };
+  const COMPILED = new Map();
+  const HAND = new Set(Object.keys(VENDOR_HOSTS));
+  function compilePackHosts(packs, overlay) {
+    for (const vendor of Object.keys(packs)) {
+      const rules = packs[vendor].hosts;
+      if (!rules || rules.length === 0) continue;
+      for (const key of COMPILED.get(vendor) || []) delete VENDOR_HOSTS[key];
+      COMPILED.delete(vendor);
+      if (VENDOR_HOSTS[vendor] && !(overlay && HAND.has(vendor))) {
+        throw new Error(`inject: vendor "${vendor}" declares hosts on its pack descriptor AND in the hand VENDOR_HOSTS table — one home per fact; delete the hand entry.`);
+      }
+      // Rules group by `key` (default: the vendor id) — aws's descriptor declares the s3 and
+      // secretsmanager routing identities its twin answers under. A key matches when ANY include
+      // rule matches AND NO exclude rule matches.
+      const byKey = new Map();
+      for (const rule of rules) {
+        const key = rule.key === undefined ? vendor : rule.key;
+        if (!byKey.has(key)) byKey.set(key, []);
+        byKey.get(key).push(rule);
+      }
+      for (const [key, keyRules] of byKey) {
+        if (VENDOR_HOSTS[key] && !(overlay && HAND.has(key))) {
+          throw new Error(`inject: key "${key}" (pack ${vendor}) is declared twice — on this descriptor and in the hand VENDOR_HOSTS table or another pack's descriptor; a key has one home.`);
+        }
+        const compile = (rule) => compileHostRule(rule, `key "${key}" (pack ${vendor})`);
+        const includes = keyRules.filter((r) => r.exclude !== true).map(compile);
+        const excludes = keyRules.filter((r) => r.exclude === true).map(compile);
+        VENDOR_HOSTS[key] = (h, p) => includes.some((m) => m(h, p)) && !excludes.some((m) => m(h, p));
+        COMPILED.set(vendor, [...(COMPILED.get(vendor) || []), key]);
+      }
+    }
+  }
+  const overlays = new Set(installed);
+  compilePackHosts(Object.fromEntries(Object.entries(packs).filter(([vendor]) => !overlays.has(vendor))), false);
+  compilePackHosts(Object.fromEntries(Object.entries(packs).filter(([vendor]) => overlays.has(vendor))), true);
+  return { hosts: VENDOR_HOSTS, addPackHosts: packs => compilePackHosts(packs || {}, true) };
+}
+
+/** Static host/path rules first, then supplied claimed hosts. */
+function resolveTwinHost(rules, hostname, map, pathname, claimed = {}) {
+  for (const vendor of Object.keys(rules)) {
+    if (map[vendor] && rules[vendor](hostname, pathname)) return { vendor, origin: map[vendor] };
+  }
+  const host = String(hostname || '').toLowerCase();
+  for (const vendor of Object.keys(claimed)) {
+    if (!map[vendor]) continue;
+    const hosts = typeof claimed[vendor] === 'function' ? claimed[vendor]() : claimed[vendor];
+    if (hosts.has(host)) return { vendor, origin: map[vendor] };
+  }
+  return null;
+}
+
+module.exports = { createHostTable, hostRules, resolveTwinHost };

package/dist/host-routing.d.cts

@@ -0,0 +1,7 @@
+/** Pure host rules and resolution: supplied data only, safe in an isolate. */
+export type HostRuleData = { host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true };
+export type HostPredicate = (hostname: string, pathname?: string) => boolean;
+export type HostFacts = Readonly<Record<string, { hosts?: ReadonlyArray<HostRuleData> }>>;
+export function hostRules(rules: ReadonlyArray<HostRuleData> | undefined): { names(hostname: string): boolean; takes(hostname: string, pathname: string): boolean };
+export function createHostTable(packs: HostFacts, installed?: Iterable<string>): { hosts: Record<string, HostPredicate>; addPackHosts(packs: HostFacts): void };
+export function resolveTwinHost(rules: Readonly<Record<string, HostPredicate>>, hostname: string, map: Readonly<Record<string, string>>, pathname?: string, claimed?: Readonly<Record<string, ReadonlySet<string> | (() => ReadonlySet<string>)>>): { vendor: string; origin: string } | null;

package/dist/inject.cjs

@@ -47,6 +47,7 @@ const { createPublicKey, createVerify } = require('crypto');
 
 // the vendor host table (VENDOR_HOSTS: a hostname, and a path where two vendors share a host, to the vendor whose twin
 // serves it) has its own home, shared with the application route
+const { resolveTwinHost } = require('./host-routing.cjs');
 const { VENDOR_HOSTS, twinEnvStem, twinOrigins } = require('./vendor-hosts.cjs');
 const dns = require('dns');
 const http2 = require('http2');
@@ -216,15 +217,11 @@ function readMap(env) {
  * sees only the SNI name) omit it and get host-level candidacy.
  */
 function resolveTwin(hostname, map, pathname) {
-  for (const vendor of Object.keys(VENDOR_HOSTS)) {
-    if (map[vendor] && VENDOR_HOSTS[vendor](hostname, pathname)) return { vendor, origin: map[vendor] };
-  }
-  // then a host a running twin claims (a custom domain a person connected), as DNS would route it; never one a
-  // descriptor's hosts name, which the loop above has already answered
+  const target = resolveTwinHost(VENDOR_HOSTS, hostname, map, pathname, Object.fromEntries(
+    Object.keys(CLAIMERS).map(vendor => [vendor, () => claimsAt(map[vendor], CLAIMERS[vendor]).hosts])
+  ));
+  if (target) return target;
   const host = String(hostname || '').toLowerCase();
-  for (const vendor of Object.keys(CLAIMERS)) {
-    if (map[vendor] && claimsAt(map[vendor], CLAIMERS[vendor]).hosts.has(host)) return { vendor, origin: map[vendor] };
-  }
   // last, the application's own production hostnames, routed to where it listens in the World; never the World's own
   // origin or a twin's, whose requests carry the World key
   const bare = host.replace(/\.$/, '');

package/dist/src/board-keys.d.ts

@@ -0,0 +1,6 @@
+/** A page's key, shared by its World and console. Browser keys cannot equal vendor-prefixed plain keys. */
+export declare function boardFrameKey(frame: {
+    vendor: string;
+    id: string;
+    browser?: string;
+}): string;

package/dist/src/board-keys.js

@@ -0,0 +1,4 @@
+/** A page's key, shared by its World and console. Browser keys cannot equal vendor-prefixed plain keys. */
+export function boardFrameKey(frame) {
+    return frame.browser ? `~browser:${encodeURIComponent(frame.browser)}:${frame.vendor}:${frame.id}` : `${frame.vendor}:${frame.id}`;
+}

package/dist/src/browser-cookie-jar.d.ts

@@ -0,0 +1,9 @@
+import { type BrowserCookie } from './browser-state.js';
+/** A seed's HTTP cookie jar; cookies remain at the real URL even when transport goes to a twin. */
+export declare class BrowserCookieJar {
+    private cookies;
+    constructor(cookies?: BrowserCookie[]);
+    snapshot(now: number): BrowserCookie[];
+    header(url: URL, now: number): string;
+    set(line: string, url: URL, now: number): void;
+}

package/dist/src/browser-cookie-jar.js

@@ -0,0 +1,104 @@
+import suffixes from './public-suffixes.json' with { type: 'json' };
+import { cookieMatchesHost } from "./browser-state.js";
+/** Cookie domain acceptance uses the public suffix list, including its wildcard and exception rules. */
+let rules;
+function publicSuffix(domain) {
+    rules ??= new Set(suffixes.rules.map(rule => {
+        const prefix = rule.startsWith('!') ? '!' : rule.startsWith('*.') ? '*.' : '';
+        return `${prefix}${new URL(`https://${rule.slice(prefix.length)}`).hostname}`;
+    }));
+    const labels = domain.split('.');
+    let size = 1;
+    for (let i = 0; i < labels.length; i++) {
+        const suffix = labels.slice(i).join('.');
+        if (rules.has(`!${suffix}`))
+            return labels.length === labels.length - i - 1;
+        if (rules.has(suffix))
+            size = Math.max(size, labels.length - i);
+        if (i > 0 && rules.has(`*.${suffix}`))
+            size = Math.max(size, labels.length - i + 1);
+    }
+    return labels.length === size;
+}
+const domainMatches = (host, domain) => host === domain || host.endsWith(`.${domain}`);
+const pathMatches = (path, scope) => path === scope || (path.startsWith(scope) && (scope.endsWith('/') || path[scope.length] === '/'));
+/** A seed's HTTP cookie jar; cookies remain at the real URL even when transport goes to a twin. */
+export class BrowserCookieJar {
+    cookies;
+    constructor(cookies = []) { this.cookies = structuredClone(cookies); }
+    snapshot(now) {
+        this.cookies = this.cookies.filter(c => c.expires === -1 || c.expires > now / 1000);
+        return structuredClone(this.cookies);
+    }
+    header(url, now) {
+        return this.snapshot(now).filter(c => (!c.secure || url.protocol === 'https:') &&
+            cookieMatchesHost(c, url.hostname) && pathMatches(url.pathname, c.path))
+            .sort((a, b) => b.path.length - a.path.length).map(c => `${c.name}=${c.value}`).join('; ');
+    }
+    set(line, url, now) {
+        const [pair = '', ...attributes] = line.split(';');
+        const eq = pair.indexOf('=');
+        if (eq < 1)
+            return;
+        const name = pair.slice(0, eq).trim();
+        const value = pair.slice(eq + 1).trim();
+        if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || /[\x00-\x1f\x7f;\u0100-\uffff]/.test(value))
+            return;
+        const attrs = new Map();
+        for (const part of attributes) {
+            const at = part.indexOf('=');
+            attrs.set((at < 0 ? part : part.slice(0, at)).trim().toLowerCase(), at < 0 ? '' : part.slice(at + 1).trim());
+        }
+        let domain = url.hostname;
+        const asked = attrs.get('domain');
+        if (asked) {
+            if (/[\s:/\\?#@%]/.test(asked))
+                return;
+            let normalized;
+            try {
+                normalized = new URL(`https://${asked.replace(/^\./, '')}`).hostname;
+            }
+            catch {
+                return;
+            }
+            if (!domainMatches(url.hostname, normalized) || publicSuffix(normalized))
+                return;
+            domain = `.${normalized}`;
+        }
+        const last = url.pathname.lastIndexOf('/');
+        const fallback = last > 0 ? url.pathname.slice(0, last) : '/';
+        const path = attrs.get('path')?.startsWith('/') ? attrs.get('path') : fallback;
+        if (/[\x00-\x20\x7f;\u0100-\uffff]/.test(path))
+            return;
+        const secure = attrs.has('secure');
+        if (secure && url.protocol !== 'https:')
+            return;
+        const same = attrs.get('samesite')?.toLowerCase();
+        const sameSite = same === 'strict' ? 'Strict' : same === 'none' ? 'None' : 'Lax';
+        if (sameSite === 'None' && !secure)
+            return;
+        if (name.startsWith('__Secure-') && !secure)
+            return;
+        if (name.startsWith('__Host-') && (!secure || asked || attrs.get('path') !== '/'))
+            return;
+        let expires = -1;
+        const date = attrs.get('expires');
+        if (date && Number.isFinite(Date.parse(date)))
+            expires = Date.parse(date) / 1000;
+        const age = attrs.get('max-age');
+        if (age && /^-?\d+$/.test(age)) {
+            const seconds = Number(age);
+            expires = seconds <= 0 ? 0 : Math.min(8640000000000, now / 1000 + seconds);
+        }
+        const existing = this.cookies.findIndex(c => c.name === name && c.domain.replace(/^\./, '') === domain.replace(/^\./, '') && c.path === path);
+        // An insecure response cannot replace a secure cookie with an overlapping scope.
+        if (url.protocol !== 'https:' && this.cookies.some(c => c.name === name && c.secure && domainMatches(domain.replace(/^\./, ''), c.domain.replace(/^\./, '')) && pathMatches(path, c.path)))
+            return;
+        const cookie = { name, value, domain, path, expires, secure, httpOnly: attrs.has('httponly'), sameSite };
+        if (existing < 0)
+            this.cookies.push(cookie);
+        else
+            this.cookies[existing] = cookie;
+        this.snapshot(now);
+    }
+}

package/dist/src/browser-state.d.ts

@@ -0,0 +1,52 @@
+/** The frontend state of a scenario, in Playwright's storageState form. */
+export type BrowserCookie = {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires: number;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: 'Strict' | 'Lax' | 'None';
+    partitionKey?: string;
+    _crHasCrossSiteAncestor?: boolean;
+};
+export type BrowserIndexedDB = {
+    name: string;
+    version: number;
+    stores: {
+        name: string;
+        autoIncrement: boolean;
+        keyPath?: string;
+        keyPathArray?: string[];
+        records: {
+            key?: unknown;
+            keyEncoded?: unknown;
+            value?: unknown;
+            valueEncoded?: unknown;
+        }[];
+        indexes: {
+            name: string;
+            keyPath?: string;
+            keyPathArray?: string[];
+            multiEntry: boolean;
+            unique: boolean;
+        }[];
+    }[];
+};
+export type BrowserState = {
+    cookies: BrowserCookie[];
+    origins: {
+        origin: string;
+        localStorage: {
+            name: string;
+            value: string;
+        }[];
+        indexedDB?: BrowserIndexedDB[];
+    }[];
+};
+export declare function assertBrowserName(name: string): void;
+export declare function browserOrigin(value: string): string;
+/** Refuse unknown keys at every level; the accepted object is never reshaped. */
+export declare function validateBrowserState(value: unknown): BrowserState;
+export declare function cookieMatchesHost(cookie: BrowserCookie, hostname: string): boolean;

package/dist/src/browser-state.js

@@ -0,0 +1,105 @@
+export function assertBrowserName(name) {
+    if (!/^[a-z0-9](?:[a-z0-9]|-(?!-)){0,23}$/.test(name) || name.endsWith('-'))
+        throw new Error('browser name: 1–24 lowercase letters, digits or single hyphens, starting and ending with a letter or digit');
+}
+function object(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(k => !keys.includes(k)))
+        throw new Error(`browser state: an object with only ${keys.join(', ')}`);
+    return value;
+}
+const host = (value) => value !== 'localhost' && !value.endsWith('.localhost') && !/^\d+(?:\.\d+){3}$/.test(value) && /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z][a-z0-9-]*$/.test(value) && value.length <= 253 && value.split('.').every(l => l.length <= 63);
+export function browserOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('browser origin: an absolute http or https vendor origin');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== value || !host(url.hostname))
+        throw new Error('browser origin: a canonical http or https vendor origin, never a local twin URL');
+    return value;
+}
+/** Refuse unknown keys at every level; the accepted object is never reshaped. */
+export function validateBrowserState(value) {
+    const state = object(value, ['cookies', 'origins']);
+    if (!Array.isArray(state.cookies) || !Array.isArray(state.origins))
+        throw new Error('browser state: cookies and origins are arrays');
+    const cookies = new Set();
+    for (const raw of state.cookies) {
+        const c = object(raw, ['name', 'value', 'domain', 'path', 'expires', 'httpOnly', 'secure', 'sameSite', 'partitionKey', '_crHasCrossSiteAncestor']);
+        if (typeof c.name !== 'string' || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(c.name) || typeof c.value !== 'string' || /[\x00-\x1f\x7f;]/.test(c.value))
+            throw new Error('browser cookie: a cookie name and wire-safe string value');
+        if (/[^\u0000-\u00ff]/.test(c.value))
+            throw new Error('browser cookie: value characters must be U+00FF or below for Set-Cookie');
+        if (typeof c.domain !== 'string' || !host(c.domain.replace(/^\./, '')))
+            throw new Error('browser cookie: a real vendor domain, optionally prefixed by a dot');
+        if (typeof c.path !== 'string' || !c.path.startsWith('/') || /[\x00-\x20\x7f;\u0100-\uffff]/.test(c.path))
+            throw new Error('browser cookie: an absolute wire-safe cookie path');
+        if (typeof c.expires !== 'number' || !Number.isFinite(c.expires) || (c.expires < 0 && c.expires !== -1))
+            throw new Error('browser cookie: expires is Unix seconds, or -1 for a session');
+        if (typeof c.httpOnly !== 'boolean' || typeof c.secure !== 'boolean' || (typeof c.sameSite !== 'string' || !['Strict', 'Lax', 'None'].includes(c.sameSite)))
+            throw new Error('browser cookie: httpOnly and secure are booleans; sameSite is Strict, Lax or None');
+        if (c.partitionKey !== undefined && (typeof c.partitionKey !== 'string' || !c.partitionKey || /[\x00-\x20\x7f]/.test(c.partitionKey)))
+            throw new Error('browser cookie: partitionKey is a nonempty string');
+        if (c._crHasCrossSiteAncestor !== undefined && typeof c._crHasCrossSiteAncestor !== 'boolean')
+            throw new Error('browser cookie: _crHasCrossSiteAncestor is a boolean');
+        const key = JSON.stringify([c.name, c.domain, c.path, c.partitionKey]);
+        if (cookies.has(key))
+            throw new Error('browser state: duplicate cookie');
+        cookies.add(key);
+    }
+    const origins = new Set();
+    for (const raw of state.origins) {
+        const o = object(raw, ['origin', 'localStorage', 'indexedDB']);
+        if (typeof o.origin !== 'string')
+            throw new Error('browser state: origin is a string');
+        browserOrigin(o.origin);
+        if (origins.has(o.origin))
+            throw new Error('browser state: duplicate origin');
+        origins.add(o.origin);
+        if (!Array.isArray(o.localStorage))
+            throw new Error('browser state: localStorage is an array');
+        if (o.indexedDB !== undefined) {
+            if (!Array.isArray(o.indexedDB))
+                throw new Error('browser storage: indexedDB is an array');
+            const keyPath = (item) => {
+                if (item.keyPath !== undefined && typeof item.keyPath !== 'string')
+                    throw new Error('browser IndexedDB: keyPath is a string');
+                if (item.keyPathArray !== undefined && (!Array.isArray(item.keyPathArray) || item.keyPathArray.some(k => typeof k !== 'string')))
+                    throw new Error('browser IndexedDB: keyPathArray contains strings');
+            };
+            for (const rawDB of o.indexedDB) {
+                const db = object(rawDB, ['name', 'version', 'stores']);
+                if (typeof db.name !== 'string' || typeof db.version !== 'number' || !Number.isSafeInteger(db.version) || db.version < 1 || !Array.isArray(db.stores))
+                    throw new Error('browser IndexedDB: a name, positive integer version and stores array');
+                for (const rawStore of db.stores) {
+                    const store = object(rawStore, ['name', 'autoIncrement', 'keyPath', 'keyPathArray', 'records', 'indexes']);
+                    if (typeof store.name !== 'string' || typeof store.autoIncrement !== 'boolean' || !Array.isArray(store.records) || !Array.isArray(store.indexes))
+                        throw new Error('browser IndexedDB: a store name, autoIncrement boolean, records and indexes arrays');
+                    keyPath(store);
+                    for (const record of store.records)
+                        object(record, ['key', 'keyEncoded', 'value', 'valueEncoded']);
+                    for (const rawIndex of store.indexes) {
+                        const index = object(rawIndex, ['name', 'keyPath', 'keyPathArray', 'multiEntry', 'unique']);
+                        if (typeof index.name !== 'string' || typeof index.multiEntry !== 'boolean' || typeof index.unique !== 'boolean')
+                            throw new Error('browser IndexedDB: an index name, multiEntry and unique booleans');
+                        keyPath(index);
+                    }
+                }
+            }
+        }
+        const names = new Set();
+        for (const rawEntry of o.localStorage) {
+            const entry = object(rawEntry, ['name', 'value']);
+            if (typeof entry.name !== 'string' || typeof entry.value !== 'string' || names.has(entry.name))
+                throw new Error('browser storage: unique string names and string values');
+            names.add(entry.name);
+        }
+    }
+    return value;
+}
+export function cookieMatchesHost(cookie, hostname) {
+    const domain = cookie.domain.replace(/^\./, '');
+    return hostname === domain || (cookie.domain.startsWith('.') && hostname.endsWith(`.${domain}`));
+}

package/dist/src/browser.d.ts

@@ -0,0 +1,12 @@
+import { type BrowserState } from './browser-state.js';
+export { cookieMatchesHost } from './browser-state.js';
+export type SeedBrowser = {
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+    storage(origin: string): {
+        set(key: string, value: string): Promise<void>;
+        remove(key: string): Promise<void>;
+    };
+    state(): Promise<BrowserState>;
+};
+/** A seed's named browser. Every state write goes through the World's single HTTP loader. */
+export declare function browser(name: string): Promise<SeedBrowser>;

package/dist/src/browser.js

@@ -0,0 +1,197 @@
+import { BrowserCookieJar } from "./browser-cookie-jar.js";
+import { assertBrowserName, browserOrigin, validateBrowserState } from "./browser-state.js";
+import { nodeBuiltin } from "./serve-http.js";
+import { worldNow } from "./world-clock.js";
+export { cookieMatchesHost } from "./browser-state.js";
+/** Undo the request's path mount before its answer reaches a vendor-addressed client. */
+function vendorResponse(response, vendor, twin, mount) {
+    if (!mount)
+        return response;
+    const pathAtVendor = (path) => path === mount ? '/' : path.startsWith(`${mount}/`) ? path.slice(mount.length) : path;
+    const urlAtVendor = (value) => {
+        if (!value.trim())
+            return value;
+        let at;
+        try {
+            at = new URL(value, twin);
+        }
+        catch {
+            return value;
+        }
+        if (at.origin !== twin.origin && at.origin !== vendor.origin)
+            return value;
+        const path = pathAtVendor(at.pathname);
+        if (path === at.pathname)
+            return value;
+        const tail = `${path}${at.search}${at.hash}`;
+        return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(value.trim()) ? `${vendor.origin}${tail}` : tail;
+    };
+    const headers = new Headers(response.headers);
+    let changed = false;
+    const cookies = response.headers.getSetCookie();
+    const mapped = cookies.map(cookie => cookie.replace(/(;\s*path\s*=)([^;]*)/gi, (attribute, lead, path) => {
+        const at = pathAtVendor(path.trim());
+        return at === path.trim() ? attribute : `${lead}${at}`;
+    }));
+    if (mapped.some((cookie, i) => cookie !== cookies[i])) {
+        headers.delete('set-cookie');
+        for (const cookie of mapped)
+            headers.append('set-cookie', cookie);
+        changed = true;
+    }
+    for (const name of ['location', 'content-location']) {
+        const value = headers.get(name);
+        if (value === null)
+            continue;
+        const at = urlAtVendor(value);
+        if (at !== value) {
+            headers.set(name, at);
+            changed = true;
+        }
+    }
+    const refresh = headers.get('refresh');
+    if (refresh !== null) {
+        const parts = /^(\s*\d+(?:\.\d+)?\s*[;,]\s*(?:url\s*=\s*)?)(?:"([^"]*)"|'([^']*)'|([^"']*?))(\s*)$/i.exec(refresh);
+        if (parts) {
+            const value = parts[2] ?? parts[3] ?? parts[4];
+            const at = urlAtVendor(value);
+            if (at !== value) {
+                const quote = parts[2] !== undefined ? '"' : parts[3] !== undefined ? "'" : '';
+                headers.set('refresh', `${parts[1]}${quote}${at}${quote}${parts[5]}`);
+                changed = true;
+            }
+        }
+    }
+    return changed ? new Response(response.body, { status: response.status, statusText: response.statusText, headers }) : response;
+}
+/** A seed's named browser. Every state write goes through the World's single HTTP loader. */
+export async function browser(name) {
+    assertBrowserName(name);
+    const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
+    const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
+    if (!process.env.VOLTER_WORLD || !door || !token)
+        throw new Error('browser(name) runs in a World seed, with its browsers door and credential');
+    const require = nodeBuiltin('module').createRequire(import.meta.url);
+    const routing = require('../vendor-hosts.cjs');
+    const { packs } = require('../pack-facts.cjs').packFacts();
+    const resolve = async (url) => {
+        const map = routing.twinOrigins(process.env);
+        const declared = routing.resolveTwinHost(url.hostname, map, url.pathname);
+        if (declared)
+            return declared;
+        const claimed = {};
+        for (const [vendor, facts] of Object.entries(packs)) {
+            const origin = map[vendor] ?? process.env[`${routing.twinEnvStem(vendor)}_TWIN_URL`];
+            if (!origin || !facts.hostsClaimed)
+                continue;
+            map[vendor] = origin;
+            const headers = new Headers({ 'x-volter-read-only': '1' });
+            if (process.env.VOLTER_TWINS_KEY)
+                headers.set('x-twins-key', process.env.VOLTER_TWINS_KEY);
+            const listed = await fetch(`${origin}${facts.hostsClaimed.door}`, { headers })
+                .then(r => r.ok ? r.json() : null).catch(() => null);
+            claimed[vendor] = new Set(Array.isArray(listed?.hosts) ? listed.hosts.map(h => String(h).toLowerCase()) : []);
+        }
+        return routing.resolveTwinHost(url.hostname, map, url.pathname, claimed);
+    };
+    const initial = await fetch(`${door}/${name}`, { headers: { 'x-volter-token': token } });
+    if (!initial.ok && initial.status !== 404)
+        throw new Error(`browser ${name}: ${initial.status} ${await initial.text()}`);
+    const stored = initial.ok ? validateBrowserState(await initial.json()) : { cookies: [], origins: [] };
+    const jar = new BrowserCookieJar(stored.cookies);
+    const origins = structuredClone(stored.origins);
+    let queue = Promise.resolve();
+    const serial = (fn) => { const next = queue.then(fn); queue = next.then(() => undefined, () => undefined); return next; };
+    const snapshot = () => {
+        const now = new Date(worldNow()).getTime();
+        const cookies = jar.snapshot(now);
+        return validateBrowserState({ cookies, origins: structuredClone(origins) });
+    };
+    const save = async () => {
+        const response = await fetch(`${door}/${name}`, { method: 'PUT', headers: { 'content-type': 'application/json', 'x-volter-token': token }, body: JSON.stringify(snapshot()) });
+        if (!response.ok)
+            throw new Error(`browser ${name}: ${response.status} ${await response.text()}`);
+    };
+    if (initial.status === 404)
+        await save();
+    return {
+        state: () => serial(async () => snapshot()),
+        storage(origin) {
+            browserOrigin(origin);
+            const change = (key, value) => serial(async () => {
+                if (typeof key !== 'string' || (value !== undefined && typeof value !== 'string'))
+                    throw new Error('browser storage: string keys and values');
+                const before = JSON.stringify(origins);
+                let entry = origins.find(o => o.origin === origin);
+                if (!entry && value !== undefined) {
+                    entry = { origin, localStorage: [] };
+                    origins.push(entry);
+                }
+                if (entry) {
+                    entry.localStorage = entry.localStorage.filter(v => v.name !== key);
+                    if (value !== undefined)
+                        entry.localStorage.push({ name: key, value });
+                }
+                if (JSON.stringify(origins) !== before)
+                    await save();
+            });
+            return { set: (key, value) => change(key, value), remove: key => change(key) };
+        },
+        fetch: (input, init) => serial(async () => {
+            const request = new Request(input, init);
+            let url = new URL(request.url);
+            let method = request.method;
+            let body = request.body ? await request.arrayBuffer() : undefined;
+            const headers = new Headers(request.headers);
+            if (headers.has('cookie'))
+                throw new Error('browser.fetch carries its own cookie jar');
+            for (let redirects = 0;; redirects++) {
+                if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+                    throw new Error('browser.fetch takes an http or https vendor URL');
+                const target = await resolve(url);
+                if (!target || target.vendor === 'app')
+                    throw new Error(`browser ${name}: no twin in this World serves ${url.hostname}${url.pathname}`);
+                const at = new URL(target.origin);
+                const mount = at.pathname.replace(/\/+$/, '');
+                at.pathname = `${mount}${url.pathname}`;
+                at.search = url.search;
+                const sent = new Headers(headers);
+                const cookies = jar.header(url, new Date(worldNow()).getTime());
+                if (cookies)
+                    sent.set('cookie', cookies);
+                sent.set('host', mount ? at.host : url.host);
+                sent.set('x-volter-twin-original-host', url.host);
+                sent.set('x-forwarded-host', url.host);
+                sent.set('x-forwarded-proto', url.protocol.slice(0, -1));
+                if (process.env.VOLTER_TWINS_KEY)
+                    sent.set('x-twins-key', process.env.VOLTER_TWINS_KEY);
+                const before = JSON.stringify(snapshot());
+                const response = vendorResponse(await fetch(at, { method, headers: sent, body, redirect: 'manual', signal: request.signal }), url, at, mount);
+                for (const cookie of response.headers.getSetCookie())
+                    jar.set(cookie, url, new Date(worldNow()).getTime());
+                if (JSON.stringify(snapshot()) !== before)
+                    await save();
+                const location = response.headers.get('location');
+                if (!location || ![301, 302, 303, 307, 308].includes(response.status) || request.redirect === 'manual')
+                    return response;
+                if (request.redirect === 'error')
+                    throw new Error('browser.fetch refused a redirect');
+                if (redirects >= 20)
+                    throw new Error('browser.fetch exceeded the fetch redirect limit');
+                await response.body?.cancel();
+                const next = new URL(location, url);
+                if (next.origin !== url.origin) {
+                    headers.delete('authorization');
+                    headers.delete('proxy-authorization');
+                }
+                if ((response.status === 303 && method !== 'HEAD') || ([301, 302].includes(response.status) && method === 'POST')) {
+                    method = 'GET';
+                    body = undefined;
+                    for (const key of ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location'])
+                        headers.delete(key);
+                }
+                url = next;
+            }
+        }),
+    };
+}