@volter/world-core 3.0.36 → 3.0.38

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

@@ -1,4 +1,4 @@
-/** The frontend state of a scenario, in Playwright's storageState form. */
+/** A scenario's browser profile, using Playwright's storageState and context option shapes. */
 export type BrowserCookie = {
     name: string;
     value: string;
@@ -34,7 +34,7 @@ export type BrowserIndexedDB = {
         }[];
     }[];
 };
-export type BrowserState = {
+export type BrowserStorageState = {
     cookies: BrowserCookie[];
     origins: {
         origin: string;
@@ -45,8 +45,40 @@ export type BrowserState = {
         indexedDB?: BrowserIndexedDB[];
     }[];
 };
+/** Profile subset of Playwright 1.61.1 BrowserContextOptions; no execution options. */
+export type BrowserContext = {
+    permissions?: string[];
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    locale?: string;
+    timezoneId?: string;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    } | null;
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+    colorScheme?: 'light' | 'dark' | 'no-preference' | null;
+    reducedMotion?: 'reduce' | 'no-preference' | null;
+    extraHTTPHeaders?: Record<string, string>;
+    offline?: boolean;
+};
+export type BrowserState = {
+    storageState: BrowserStorageState;
+    context: BrowserContext;
+};
 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 validateBrowserStorageState(value: unknown): BrowserStorageState;
+export declare function validateBrowserContext(value: unknown): BrowserContext;
+/** Normalize legacy storage-only records and profiles without context on read. */
 export declare function validateBrowserState(value: unknown): BrowserState;
+/** The profile's language header, with Playwright's locale supplying its default. */
+export declare function browserAcceptLanguage(context: BrowserContext): string | undefined;
 export declare function cookieMatchesHost(cookie: BrowserCookie, hostname: string): boolean;

package/dist/src/browser-state.js

@@ -21,7 +21,7 @@ export function browserOrigin(value) {
     return value;
 }
 /** Refuse unknown keys at every level; the accepted object is never reshaped. */
-export function validateBrowserState(value) {
+export function validateBrowserStorageState(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');
@@ -99,6 +99,68 @@ export function validateBrowserState(value) {
     }
     return value;
 }
+export function validateBrowserContext(value) {
+    const context = object(value, ['permissions', 'geolocation', 'locale', 'timezoneId', 'userAgent', 'viewport',
+        'deviceScaleFactor', 'isMobile', 'hasTouch', 'colorScheme', 'reducedMotion', 'extraHTTPHeaders', 'offline']);
+    const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+    if (context.permissions !== undefined && (!Array.isArray(context.permissions) || context.permissions.some(p => typeof p !== 'string')))
+        throw new Error('browser context: permissions is an array of strings');
+    for (const key of ['locale', 'timezoneId', 'userAgent']) {
+        if (context[key] !== undefined && typeof context[key] !== 'string')
+            throw new Error(`browser context: ${key} is a string`);
+    }
+    if (context.locale !== undefined)
+        new Headers({ 'accept-language': context.locale });
+    if (context.userAgent !== undefined)
+        new Headers({ 'user-agent': context.userAgent });
+    for (const key of ['isMobile', 'hasTouch', 'offline']) {
+        if (context[key] !== undefined && typeof context[key] !== 'boolean')
+            throw new Error(`browser context: ${key} is a boolean`);
+    }
+    if (context.deviceScaleFactor !== undefined && !finite(context.deviceScaleFactor))
+        throw new Error('browser context: deviceScaleFactor is a finite number');
+    if (context.geolocation !== undefined) {
+        const geo = object(context.geolocation, ['latitude', 'longitude', 'accuracy']);
+        if (!finite(geo.latitude) || geo.latitude < -90 || geo.latitude > 90 || !finite(geo.longitude) || geo.longitude < -180 || geo.longitude > 180
+            || (geo.accuracy !== undefined && (!finite(geo.accuracy) || geo.accuracy < 0)))
+            throw new Error('browser context: geolocation has latitude [-90, 90], longitude [-180, 180] and optional nonnegative accuracy');
+    }
+    if (context.viewport !== undefined && context.viewport !== null) {
+        const viewport = object(context.viewport, ['width', 'height']);
+        if (!finite(viewport.width) || !Number.isInteger(viewport.width) || !finite(viewport.height) || !Number.isInteger(viewport.height))
+            throw new Error('browser context: viewport has integer width and height, or is null');
+    }
+    if (context.viewport === null && (context.deviceScaleFactor !== undefined || context.isMobile === true))
+        throw new Error('browser context: null viewport does not support deviceScaleFactor or isMobile');
+    for (const [key, values] of [['colorScheme', ['light', 'dark', 'no-preference']], ['reducedMotion', ['reduce', 'no-preference']]]) {
+        if (context[key] !== undefined && context[key] !== null && (typeof context[key] !== 'string' || !values.includes(context[key])))
+            throw new Error(`browser context: ${key} is ${values.join(', ')} or null`);
+    }
+    if (context.extraHTTPHeaders !== undefined) {
+        const headers = context.extraHTTPHeaders;
+        if (!headers || typeof headers !== 'object' || Array.isArray(headers) || Object.values(headers).some(v => typeof v !== 'string'))
+            throw new Error('browser context: extraHTTPHeaders maps header names to strings');
+        // Validate wire values without normalizing the profile's names or values.
+        new Headers(headers);
+    }
+    return value;
+}
+/** Normalize legacy storage-only records and profiles without context on read. */
+export function validateBrowserState(value) {
+    if (value && typeof value === 'object' && ('cookies' in value || 'origins' in value)) {
+        return { storageState: validateBrowserStorageState(value), context: {} };
+    }
+    const profile = object(value, ['storageState', 'context']);
+    return { storageState: validateBrowserStorageState(profile.storageState), context: validateBrowserContext(profile.context === undefined ? {} : profile.context) };
+}
+/** The profile's language header, with Playwright's locale supplying its default. */
+export function browserAcceptLanguage(context) {
+    for (const [name, value] of Object.entries(context.extraHTTPHeaders ?? {})) {
+        if (name.toLowerCase() === 'accept-language')
+            return value;
+    }
+    return context.locale;
+}
 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

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

package/dist/src/browser.js

@@ -1,5 +1,5 @@
 import { BrowserCookieJar } from "./browser-cookie-jar.js";
-import { assertBrowserName, browserOrigin, validateBrowserState } from "./browser-state.js";
+import { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserContext, browserAcceptLanguage } from "./browser-state.js";
 import { nodeBuiltin } from "./serve-http.js";
 import { worldNow } from "./world-clock.js";
 export { cookieMatchesHost } from "./browser-state.js";
@@ -97,15 +97,16 @@ export async function browser(name) {
     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);
+    const stored = validateBrowserState(initial.ok ? await initial.json() : { cookies: [], origins: [] });
+    const jar = new BrowserCookieJar(stored.storageState.cookies);
+    const origins = structuredClone(stored.storageState.origins);
+    let context = structuredClone(stored.context);
     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) });
+        return validateBrowserState({ storageState: { cookies, origins: structuredClone(origins) }, context: structuredClone(context) });
     };
     const save = async () => {
         const response = await fetch(`${door}/${name}`, { method: 'PUT', headers: { 'content-type': 'application/json', 'x-volter-token': token }, body: JSON.stringify(snapshot()) });
@@ -116,6 +117,20 @@ export async function browser(name) {
         await save();
     return {
         state: () => serial(async () => snapshot()),
+        context: options => serial(async () => {
+            const next = structuredClone(validateBrowserContext(options));
+            if (JSON.stringify(next) === JSON.stringify(context))
+                return;
+            const previous = context;
+            context = next;
+            try {
+                await save();
+            }
+            catch (error) {
+                context = previous;
+                throw error;
+            }
+        }),
         storage(origin) {
             browserOrigin(origin);
             const change = (key, value) => serial(async () => {
@@ -156,6 +171,9 @@ export async function browser(name) {
                 at.pathname = `${mount}${url.pathname}`;
                 at.search = url.search;
                 const sent = new Headers(headers);
+                const language = browserAcceptLanguage(context);
+                if (language !== undefined)
+                    sent.set('accept-language', language);
                 const cookies = jar.header(url, new Date(worldNow()).getTime());
                 if (cookies)
                     sent.set('cookie', cookies);

package/dist/src/index.d.ts

@@ -65,4 +65,4 @@ export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
 export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
-export { assertBrowserName, browserOrigin, validateBrowserState, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserIndexedDB } from './browser-state.js';
+export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.js';

package/dist/src/index.js

@@ -60,4 +60,4 @@ export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
 export { browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
-export { assertBrowserName, browserOrigin, validateBrowserState, cookieMatchesHost } from "./browser-state.js";
+export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost } from "./browser-state.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.36",
+  "version": "3.0.38",
   "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",

package/src/browser-state.ts

@@ -1,11 +1,28 @@
-/** The frontend state of a scenario, in Playwright's storageState form. */
+/** A scenario's browser profile, using Playwright's storageState and context option shapes. */
 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 type BrowserStorageState = { cookies: BrowserCookie[]; origins: { origin: string; localStorage: { name: string; value: string }[]; indexedDB?: BrowserIndexedDB[] }[] };
+/** Profile subset of Playwright 1.61.1 BrowserContextOptions; no execution options. */
+export type BrowserContext = {
+  permissions?: string[];
+  geolocation?: { latitude: number; longitude: number; accuracy?: number };
+  locale?: string;
+  timezoneId?: string;
+  userAgent?: string;
+  viewport?: { width: number; height: number } | null;
+  deviceScaleFactor?: number;
+  isMobile?: boolean;
+  hasTouch?: boolean;
+  colorScheme?: 'light' | 'dark' | 'no-preference' | null;
+  reducedMotion?: 'reduce' | 'no-preference' | null;
+  extraHTTPHeaders?: Record<string, string>;
+  offline?: boolean;
+};
+export type BrowserState = { storageState: BrowserStorageState; context: BrowserContext };
 
 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');
@@ -25,7 +42,7 @@ export function browserOrigin(value: string): string {
 }
 
 /** Refuse unknown keys at every level; the accepted object is never reshaped. */
-export function validateBrowserState(value: unknown): BrowserState {
+export function validateBrowserStorageState(value: unknown): BrowserStorageState {
   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>();
@@ -80,7 +97,60 @@ export function validateBrowserState(value: unknown): BrowserState {
       names.add(entry.name);
     }
   }
-  return value as BrowserState;
+  return value as BrowserStorageState;
+}
+
+export function validateBrowserContext(value: unknown): BrowserContext {
+  const context = object(value, ['permissions', 'geolocation', 'locale', 'timezoneId', 'userAgent', 'viewport',
+    'deviceScaleFactor', 'isMobile', 'hasTouch', 'colorScheme', 'reducedMotion', 'extraHTTPHeaders', 'offline']);
+  const finite = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n);
+  if (context.permissions !== undefined && (!Array.isArray(context.permissions) || context.permissions.some(p => typeof p !== 'string'))) throw new Error('browser context: permissions is an array of strings');
+  for (const key of ['locale', 'timezoneId', 'userAgent']) {
+    if (context[key] !== undefined && typeof context[key] !== 'string') throw new Error(`browser context: ${key} is a string`);
+  }
+  if (context.locale !== undefined) new Headers({ 'accept-language': context.locale as string });
+  if (context.userAgent !== undefined) new Headers({ 'user-agent': context.userAgent as string });
+  for (const key of ['isMobile', 'hasTouch', 'offline']) {
+    if (context[key] !== undefined && typeof context[key] !== 'boolean') throw new Error(`browser context: ${key} is a boolean`);
+  }
+  if (context.deviceScaleFactor !== undefined && !finite(context.deviceScaleFactor)) throw new Error('browser context: deviceScaleFactor is a finite number');
+  if (context.geolocation !== undefined) {
+    const geo = object(context.geolocation, ['latitude', 'longitude', 'accuracy']);
+    if (!finite(geo.latitude) || geo.latitude < -90 || geo.latitude > 90 || !finite(geo.longitude) || geo.longitude < -180 || geo.longitude > 180
+      || (geo.accuracy !== undefined && (!finite(geo.accuracy) || geo.accuracy < 0))) throw new Error('browser context: geolocation has latitude [-90, 90], longitude [-180, 180] and optional nonnegative accuracy');
+  }
+  if (context.viewport !== undefined && context.viewport !== null) {
+    const viewport = object(context.viewport, ['width', 'height']);
+    if (!finite(viewport.width) || !Number.isInteger(viewport.width) || !finite(viewport.height) || !Number.isInteger(viewport.height)) throw new Error('browser context: viewport has integer width and height, or is null');
+  }
+  if (context.viewport === null && (context.deviceScaleFactor !== undefined || context.isMobile === true)) throw new Error('browser context: null viewport does not support deviceScaleFactor or isMobile');
+  for (const [key, values] of [['colorScheme', ['light', 'dark', 'no-preference']], ['reducedMotion', ['reduce', 'no-preference']]] as const) {
+    if (context[key] !== undefined && context[key] !== null && (typeof context[key] !== 'string' || !(values as readonly string[]).includes(context[key]))) throw new Error(`browser context: ${key} is ${values.join(', ')} or null`);
+  }
+  if (context.extraHTTPHeaders !== undefined) {
+    const headers = context.extraHTTPHeaders;
+    if (!headers || typeof headers !== 'object' || Array.isArray(headers) || Object.values(headers).some(v => typeof v !== 'string')) throw new Error('browser context: extraHTTPHeaders maps header names to strings');
+    // Validate wire values without normalizing the profile's names or values.
+    new Headers(headers as Record<string, string>);
+  }
+  return value as BrowserContext;
+}
+
+/** Normalize legacy storage-only records and profiles without context on read. */
+export function validateBrowserState(value: unknown): BrowserState {
+  if (value && typeof value === 'object' && ('cookies' in value || 'origins' in value)) {
+    return { storageState: validateBrowserStorageState(value), context: {} };
+  }
+  const profile = object(value, ['storageState', 'context']);
+  return { storageState: validateBrowserStorageState(profile.storageState), context: validateBrowserContext(profile.context === undefined ? {} : profile.context) };
+}
+
+/** The profile's language header, with Playwright's locale supplying its default. */
+export function browserAcceptLanguage(context: BrowserContext): string | undefined {
+  for (const [name, value] of Object.entries(context.extraHTTPHeaders ?? {})) {
+    if (name.toLowerCase() === 'accept-language') return value;
+  }
+  return context.locale;
 }
 
 export function cookieMatchesHost(cookie: BrowserCookie, hostname: string): boolean {

package/src/browser.ts

@@ -1,5 +1,5 @@
 import { BrowserCookieJar } from './browser-cookie-jar.ts';
-import { assertBrowserName, browserOrigin, validateBrowserState, type BrowserState } from './browser-state.ts';
+import { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserContext, browserAcceptLanguage, type BrowserState, type BrowserContext } from './browser-state.ts';
 import { nodeBuiltin } from './serve-http.ts';
 import { worldNow } from './world-clock.ts';
 
@@ -8,6 +8,7 @@ export { cookieMatchesHost } from './browser-state.ts';
 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> };
+  context(options: BrowserContext): Promise<void>;
   state(): Promise<BrowserState>;
 };
 
@@ -87,15 +88,16 @@ export async function browser(name: string): Promise<SeedBrowser> {
   };
   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);
+  const stored = validateBrowserState(initial.ok ? await initial.json() : { cookies: [], origins: [] });
+  const jar = new BrowserCookieJar(stored.storageState.cookies);
+  const origins = structuredClone(stored.storageState.origins);
+  let context = structuredClone(stored.context);
   let queue: Promise<unknown> = Promise.resolve();
   const serial = <T>(fn: () => Promise<T>): Promise<T> => { const next = queue.then(fn); queue = next.then(() => undefined, () => undefined); return next; };
   const snapshot = (): BrowserState => {
     const now = new Date(worldNow()).getTime();
     const cookies = jar.snapshot(now);
-    return validateBrowserState({ cookies, origins: structuredClone(origins) });
+    return validateBrowserState({ storageState: { cookies, origins: structuredClone(origins) }, context: structuredClone(context) });
   };
   const save = async (): Promise<void> => {
     const response = await fetch(`${door}/${name}`, { method: 'PUT', headers: { 'content-type': 'application/json', 'x-volter-token': token }, body: JSON.stringify(snapshot()) });
@@ -104,6 +106,13 @@ export async function browser(name: string): Promise<SeedBrowser> {
   if (initial.status === 404) await save();
   return {
     state: () => serial(async () => snapshot()),
+    context: options => serial(async () => {
+      const next = structuredClone(validateBrowserContext(options));
+      if (JSON.stringify(next) === JSON.stringify(context)) return;
+      const previous = context;
+      context = next;
+      try { await save(); } catch (error) { context = previous; throw error; }
+    }),
     storage(origin) {
       browserOrigin(origin);
       const change = (key: string, value?: string): Promise<void> => serial(async () => {
@@ -135,6 +144,8 @@ export async function browser(name: string): Promise<SeedBrowser> {
         at.pathname = `${mount}${url.pathname}`;
         at.search = url.search;
         const sent = new Headers(headers);
+        const language = browserAcceptLanguage(context);
+        if (language !== undefined) sent.set('accept-language', language);
         const cookies = jar.header(url, new Date(worldNow()).getTime());
         if (cookies) sent.set('cookie', cookies);
         sent.set('host', mount ? at.host : url.host);

package/src/index.ts

@@ -92,4 +92,4 @@ export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioE
 
 export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';
 
-export { assertBrowserName, browserOrigin, validateBrowserState, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserIndexedDB } from './browser-state.ts';
+export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.ts';