@volter/world-core 3.0.29 → 3.0.31

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/actions.d.ts

@@ -167,7 +167,9 @@ export type AtomicActionDecision<T> = {
  * supplied snapshot. Durable state changes only through the returned action, which this helper
  * appends before releasing the lock.
  */
-export declare function decideAndAppendAction<T>(service: string, decide: (resources: TwinResource[]) => AtomicActionDecision<T>, root?: string): {
+export declare function decideAndAppendAction<T>(service: string, decide: (resources: TwinResource[]) => AtomicActionDecision<T>, root?: string, 
+/** A narrower indexed snapshot, read under the same lock; it must cover every decision and precondition. */
+read?: () => TwinResource[]): {
     value: T;
     action?: TwinAction;
     appended: boolean;

package/dist/src/actions.js

@@ -252,9 +252,11 @@ export function occurrenceId(base, ordinal) {
  * supplied snapshot. Durable state changes only through the returned action, which this helper
  * appends before releasing the lock.
  */
-export function decideAndAppendAction(service, decide, root) {
+export function decideAndAppendAction(service, decide, root, 
+/** A narrower indexed snapshot, read under the same lock; it must cover every decision and precondition. */
+read = () => projectResources(service, root)) {
     return withProjection(service, root, () => withFileLock(actionsLock(service, root), () => {
-        const resources = projectResources(service, root);
+        const resources = read();
         const decision = decide(resources);
         if (decision.kind === 'skip')
             return { value: decision.value, appended: false };

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-session.d.ts

@@ -0,0 +1,9 @@
+import type { HandlerContext } from './derived-core.js';
+type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
+/** The named cookie, without interpreting any other vendor's cookie. */
+export declare function browserSessionToken(request: Request, name: string): string | undefined;
+/** A new, independent sign-in, returning the cookie the vendor places on its response. */
+export declare function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string>;
+/** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */
+export declare function endBrowserSession(ctx: Pick<HandlerContext, 'call' | 'record' | 'rowsRaw' | 'occurredAt'>, cookie: string): Promise<string>;
+export {};

package/dist/src/browser-session.js

@@ -0,0 +1,30 @@
+/** The named cookie, without interpreting any other vendor's cookie. */
+export function browserSessionToken(request, name) {
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const at = part.indexOf('=');
+        if (at > 0 && part.slice(0, at).trim() === name) {
+            try {
+                return decodeURIComponent(part.slice(at + 1).trim());
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+/** A new, independent sign-in, returning the cookie the vendor places on its response. */
+export async function startBrowserSession(ctx, email, cookie, scope) {
+    const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });
+    const token = await ctx.secret(`web-session:${issued}`);
+    await ctx.record('_web_session', { token, email, ...(scope !== undefined ? { scope } : {}), created_at: ctx.occurredAt }, `websession:${token}`);
+    return `${cookie}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`;
+}
+/** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */
+export async function endBrowserSession(ctx, cookie) {
+    const token = browserSessionToken(ctx.call.request, cookie);
+    const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token) : undefined;
+    if (session)
+        await ctx.record('_web_session', { token: null, ended_at: ctx.occurredAt }, String(session.id));
+    return `${cookie}=; path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+}

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>;