@volter/world-core 3.0.30 → 3.0.32

package/dist/src/runtime.d.ts

@@ -84,4 +84,4 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.js';
 export { foldHistory } from './log.js';
 export { volterHome } from './volter-home.js';
-export { BROWSER_SESSION_HEADER, BROWSER_SESSION_PATH, stripBrowserSessionPermit, withBrowserSessionPermit } from './browser-session-permit.js';
+export { boardFrameKey } from './board-keys.js';

package/dist/src/runtime.js

@@ -103,4 +103,4 @@ export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, w
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
 export { foldHistory } from "./log.js";
 export { volterHome } from "./volter-home.js";
-export { BROWSER_SESSION_HEADER, BROWSER_SESSION_PATH, stripBrowserSessionPermit, withBrowserSessionPermit } from "./browser-session-permit.js";
+export { boardFrameKey } from "./board-keys.js";

package/dist/src/twin-fetch.d.ts

@@ -17,7 +17,7 @@ export declare const TWIN_SITES_HEADER = "x-volter-world-sites";
 export declare const siteLabel: (hostname: string) => string;
 /** The address a sites template gives `hostname`, or null where the template is not one or the name makes no address
  *  (a label over 63 characters). */
-export declare function siteUrlOf(template: string, hostname: string): string | null;
+export declare function siteUrlOf(template: string, hostname: string, browser?: string): string | null;
 /** Where a page links a hostname the twin answers: the World's address for it when the World shows sites, else the
  *  hostname itself (reached through the World's proxy, or the vendor). A pack's screen links a site from this, as it
  *  mints its own URLs from twinPublicBase. */

package/dist/src/twin-fetch.js

@@ -1,3 +1,4 @@
+import { assertBrowserName } from "./browser-state.js";
 // THE ONE HTTP ADAPTATION (runtime contract R12b): most packs' serve path is the same
 // ~20 lines of glue — the keyless GET /twin manifest door, the body read, a header map,
 // the dispatch into `handle<Vendor>TwinRequest` with the WORLD instant, and a JSON
@@ -50,13 +51,22 @@ export const TWIN_SITES_HEADER = 'x-volter-world-sites';
 export const siteLabel = (hostname) => hostname.toLowerCase().replace(/\./g, '-');
 /** The address a sites template gives `hostname`, or null where the template is not one or the name makes no address
  *  (a label over 63 characters). */
-export function siteUrlOf(template, hostname) {
+export function siteUrlOf(template, hostname, browser) {
     const host = hostname.toLowerCase();
+    if (browser) {
+        try {
+            assertBrowserName(browser);
+        }
+        catch {
+            return null;
+        }
+    }
+    const label = `${browser ? `${browser}--` : ''}${siteLabel(host)}`;
     if (!/^[a-z0-9.-]+$/.test(host))
         return null;
     // a one-label site is never an IDN's (`xn--…` would be read as punycode, and is no address)
-    const filled = /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(template) ? template.replace('{host}', host)
-        : /^https?:\/\/\{site\}--[A-Za-z0-9.-]+(:\d+)?$/.test(template) && !host.startsWith('xn--') ? template.replace('{site}', siteLabel(host)) : null;
+    const filled = /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(template) ? template.replace('{host}', browser ? label : host)
+        : /^https?:\/\/\{site\}--[A-Za-z0-9.-]+(:\d+)?$/.test(template) && !host.startsWith('xn--') ? template.replace('{site}', label) : null;
     try {
         return filled && new URL(filled).hostname.split('.').every((l) => l.length > 0 && l.length <= 63) ? filled : null;
     }
@@ -69,7 +79,16 @@ export function siteUrlOf(template, hostname) {
  *  mints its own URLs from twinPublicBase. */
 export function twinSiteUrl(request, hostname) {
     const at = request.headers.get(TWIN_SITES_HEADER);
-    return (at ? siteUrlOf(at, hostname) : null) ?? `https://${hostname.toLowerCase()}`;
+    let browser = request.headers.get('x-volter-world-browser') ?? undefined;
+    if (browser) {
+        try {
+            assertBrowserName(browser);
+        }
+        catch {
+            browser = undefined;
+        }
+    }
+    return (at ? siteUrlOf(at, hostname, browser) : null) ?? `https://${hostname.toLowerCase()}`;
 }
 /** The request scopes a pack wrapped in `withRequestScopes` enforces, advertised on its `GET /twin` as
  *  `requestScopes`: `read` — a request carrying `x-volter-read-only: 1` (request-scope.ts) has every

package/dist/vendor-hosts.cjs

@@ -1,8 +1,8 @@
 'use strict';
 // THE VENDOR HOST TABLE — which vendor's twin serves a hostname (and, where two vendors share a host, which path), the
-// one home of that fact in a process, dependency-free and side-effect free. The injector (inject.cjs) routes by it; the
+// Node process's loaded facts. The pure compiler and resolver are host-routing.cjs; this loader reads Node facts.
+// The injector (inject.cjs) routes by the table; the
 // application route (app-route.cjs) never answers a name it gives a vendor, in the injector or in a twin's delivery.
-// Moved out of inject.cjs unchanged (2026-09-27).
 // ── PATH-AWARE DISAMBIGUATION (the shared-host case) ─────────────────────────────────────────
 // A predicate is called as `(hostname, pathname)`. `pathname` is OPTIONAL and is `undefined`
 // wherever the caller genuinely does not have one yet — most importantly the proxy's CONNECT
@@ -25,108 +25,12 @@
 // `browserassets` and `googlefavicon`; kernel packages carry no pack descriptor). Every vendor
 // pack's hosts live on its descriptor as DATA — host | suffix | hostPattern, pathPattern,
 // exclude, key — compiled from pack-facts.json.
-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',
-};
-
-// descriptor-first migration (architecture.md, "The descriptor"): packs now declare their hosts as DATA on their descriptor
-// (`hosts` on TwinPack), compiled into the committed pack-facts artifact — a plain JSON this
-// preloaded, dependency-free module can `require` natively. The hand table above shrinks toward
-// empty as entries move; a vendor present in both homes throws (dual declaration is the drift
-// this migration ends, and a broken checkout should refuse to inject rather than half-route).
-/** The keys each pack's compiled rules answer under, by vendor: a pack's own facts learned later (addPackHosts) replace
- *  that vendor's rules, never another's. */
-const COMPILED = new Map();
-/** The hand table's keys, before any pack's rules: a pack installed later replaces its hand entry in place (keeping its
- *  position, which decides who answers a shared host first), where the built-in facts may not declare one twice. */
-const HAND = new Set(Object.keys(VENDOR_HOSTS));
-/** One host rule as a predicate over (hostname, pathname?): its one selector (host | suffix | hostPattern) and its
- *  pathPattern, a path left out matching any. */
-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))),
-  };
-}
-
-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 facts = require('./pack-facts.cjs').packFacts();
-  const installed = new Set(facts.installed || []);
-  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => !installed.has(vendor))), false);
-  compilePackHosts(Object.fromEntries(Object.entries(facts.packs).filter(([vendor]) => installed.has(vendor))), true);
-}
-/** Rules from packs' facts learned after this module loaded (a runtime told the facts of the World it boots): each
- *  vendor's replace its earlier rules. */
-function addPackHosts(packs) { compilePackHosts(packs || {}, true); }
+const routing = require('./host-routing.cjs');
+const facts = require('./pack-facts.cjs').packFacts();
+const table = routing.createHostTable(facts.packs, facts.installed);
+const VENDOR_HOSTS = table.hosts;
+const hostRules = routing.hostRules;
+function addPackHosts(packs) { table.addPackHosts(packs); }
 
 /** Whether any vendor's host rule names `host` (at the host level, whatever the path), whether or not its twin runs. */
 function isVendorHost(host) {
@@ -166,4 +70,8 @@ function twinOrigins(env) {
   return map;
 }
 
-module.exports = { VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };
+/** Resolve using this Node process's loaded facts. */
+function resolveTwinHost(hostname, map, pathname, claimed) {
+  return routing.resolveTwinHost(VENDOR_HOSTS, hostname, map, pathname, claimed);
+}
+module.exports = { resolveTwinHost, VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };

package/dist/vendor-hosts.d.cts

@@ -9,3 +9,6 @@ export function twinOrigins(env: Readonly<Record<string, string | undefined>>):
 /** A pack's host rules (its descriptor's `hosts`, as data) read as the injector reads them: whether any include names a
  *  host whatever the path, and whether a request to a host and path is the pack's. */
 export function hostRules(rules: ReadonlyArray<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }> | undefined): { names(hostname: string): boolean; takes(hostname: string, pathname: string): boolean };
+
+/** Resolve an active twin exactly as the proxy, first declared host/path rules, then claimed hosts. */
+export function resolveTwinHost(hostname: string, map: Readonly<Record<string, string>>, pathname?: string, claimed?: Readonly<Record<string, ReadonlySet<string> | (() => ReadonlySet<string>)>>): { vendor: string; origin: string } | null;

package/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.30",
+  "version": "3.0.32",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",
@@ -29,6 +29,8 @@
     "network-policy.d.cts",
     "app-route.cjs",
     "vendor-hosts.cjs",
+    "host-routing.cjs",
+    "host-routing.d.cts",
     "pack-facts.cjs",
     "vendor-hosts.d.cts",
     "world-clock.cjs",
@@ -61,6 +63,10 @@
       "types": "./dist/src/runtime.d.ts",
       "default": "./dist/src/runtime.js"
     },
+    "./browser": {
+      "types": "./dist/src/browser.d.ts",
+      "default": "./dist/src/browser.js"
+    },
     "./args": {
       "types": "./dist/src/args.d.ts",
       "default": "./dist/src/args.js"
@@ -86,6 +92,10 @@
       "default": "./app-route.cjs"
     },
     "./vendor-hosts": "./vendor-hosts.cjs",
+    "./host-routing": {
+      "types": "./host-routing.d.cts",
+      "default": "./host-routing.cjs"
+    },
     "./pack-facts": "./pack-facts.cjs",
     "./world-clock": {
       "types": "./world-clock.d.cts",

package/src/board-keys.ts

@@ -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: { vendor: string; id: string; browser?: string }): string {
+  return frame.browser ? `~browser:${encodeURIComponent(frame.browser)}:${frame.vendor}:${frame.id}` : `${frame.vendor}:${frame.id}`;
+}

package/src/browser-cookie-jar.ts

@@ -0,0 +1,77 @@
+import suffixes from './public-suffixes.json' with { type: 'json' };
+import { cookieMatchesHost, type BrowserCookie } from './browser-state.ts';
+
+/** Cookie domain acceptance uses the public suffix list, including its wildcard and exception rules. */
+let rules: Set<string> | undefined;
+function publicSuffix(domain: string): boolean {
+  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: string, domain: string): boolean => host === domain || host.endsWith(`.${domain}`);
+const pathMatches = (path: string, scope: string): boolean => 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 {
+  private cookies: BrowserCookie[];
+  constructor(cookies: BrowserCookie[] = []) { this.cookies = structuredClone(cookies); }
+  snapshot(now: number): BrowserCookie[] {
+    this.cookies = this.cookies.filter(c => c.expires === -1 || c.expires > now / 1000);
+    return structuredClone(this.cookies);
+  }
+  header(url: URL, now: number): string {
+    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: string, url: URL, now: number): void {
+    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<string, string>();
+    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: string;
+      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: BrowserCookie = { 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/src/browser-session.ts

@@ -1,4 +1,4 @@
-// A vendor's browser session: the bookkeeping used by its sign-in page and the World's View as door.
+// A vendor's browser session: the bookkeeping used by its own sign-in and sign-out pages.
 import type { HandlerContext } from './derived-core.ts';
 
 type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;

package/src/browser-state.ts

@@ -0,0 +1,89 @@
+/** 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 function assertBrowserName(name: string): void {
+  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: unknown, keys: string[]): Record<string, unknown> {
+  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 as Record<string, unknown>;
+}
+const host = (value: string): boolean => 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: string): string {
+  let url: 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: unknown): BrowserState {
+  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<string>();
+  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<string>();
+  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: Record<string, unknown>): void => {
+        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<string>();
+    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 as BrowserState;
+}
+
+export function cookieMatchesHost(cookie: BrowserCookie, hostname: string): boolean {
+  const domain = cookie.domain.replace(/^\./, '');
+  return hostname === domain || (cookie.domain.startsWith('.') && hostname.endsWith(`.${domain}`));
+}