browxai 0.7.0

package/dist/util/capabilities.js

@@ -0,0 +1,254 @@
+// Capability toggles —  security model. See `docs/threat-model.md` for the
+// full design. The gist:
+//
+//   - Tools group into coarse categories (`read`, `navigation`, `action`, `human`,
+//     `eval`, `byob-attach`, `file-io`). Each is independently enable/disable-able at
+//     server start.
+//   - Default set: read + navigation + action + human. `eval` / `byob-attach` /
+//     `file-io` are off-by-default — opt in via `BROWX_CAPABILITIES`.
+//   - The server's startup log lists the active set; `browxai doctor` warns when
+//     dangerous capabilities are on (`eval`, `byob-attach`).
+//
+// Configuring:
+//   BROWX_CAPABILITIES=read,navigation,action,human            # the default
+//   BROWX_CAPABILITIES=read                                    # read-only server
+//   BROWX_CAPABILITIES=read,navigation,action,human,eval       # opts in to eval_js
+export const ALL_CAPABILITIES = [
+    "read",
+    "navigation",
+    "action",
+    "human",
+    "eval",
+    "byob-attach",
+    "file-io",
+    "network-body",
+    "clipboard",
+    "secrets",
+    "extensions",
+    "stealth",
+    "captcha",
+    "credentials",
+    "device-emulation",
+    "diagnostics",
+    "canvas",
+];
+export const DEFAULT_CAPABILITIES = [
+    "read",
+    "navigation",
+    "action",
+    "human",
+];
+/**
+ * Capabilities that USED to be valid and have since been retired. A retired
+ * capability is still ACCEPTED in `BROWX_CAPABILITIES` (and the `capabilities`
+ * config key) — it is ignored with a deprecation warning, never an error — so
+ * evolving the capability set can't crash an existing adopter's config.
+ * Genuine typos (a name that was never a capability) are still rejected loudly.
+ * A retired entry may be dropped entirely only in a major version bump.
+ * See the "API evolution" rule in CLAUDE.md.
+ *
+ * The value is the agent/operator-facing reason + what to do instead.
+ */
+export const RETIRED_CAPABILITIES = {
+    unstable: "the tools it gated (gestures, route mocking, compound act-and-observe " +
+        "tools, visual regions, profile snapshot/restore) were promoted into the " +
+        "default stable surface — it no longer gates anything; drop it from " +
+        "BROWX_CAPABILITIES",
+};
+/**
+ * The per-tool capability assignment is DERIVED (RFC 0004 P2 / D2): it lives at
+ * each tool's `host.register({ capability })` call (the single source of truth,
+ * src/tools/host.ts), not in a hand-maintained list here. This module owns the
+ * closed *vocabulary* (`Capability` / `ALL_CAPABILITIES` above); the per-tool
+ * rows are populated from the registration metadata via `declareToolCapability`,
+ * collected once by the tools-layer bootstrap (`src/tools/tool-metadata.ts`).
+ *
+ * A tool with no declared capability is treated as `human` (coordination
+ * primitive, always safe) — the same permissive default as before, now reachable
+ * only for the control-plane primitives that legitimately carry no browser
+ * capability (open_session, batch, get_config, …), never by a silent omission
+ * (the completeness fitness test asserts every browser tool declares one).
+ */
+const TOOL_CAPABILITY_MAP = new Map();
+/** Record one tool's capability assignment from its colocated
+ *  `host.register({ capability })` metadata (RFC 0004 P2). Idempotent for an
+ *  identical re-declaration; a *conflicting* one throws (two registrations cannot
+ *  disagree on one tool's gate). The only writer of the derived map. */
+export function declareToolCapability(tool, capability) {
+    const existing = TOOL_CAPABILITY_MAP.get(tool);
+    if (existing !== undefined && existing !== capability) {
+        throw new Error(`declareToolCapability: "${tool}" already declared as "${existing}", got "${capability}"`);
+    }
+    TOOL_CAPABILITY_MAP.set(tool, capability);
+}
+/** Lazy-collection seam (RFC 0004 P2). The tools layer installs a collector that
+ *  runs the registration metadata once and populates the derived maps;
+ *  `capabilities.ts` (a leaf) cannot import the tools layer, so the dependency is
+ *  inverted through this setter. Every real entry point (`createServer`, the SDK
+ *  client, the CLI, the package entry) reaches the tools-layer bootstrap, which
+ *  installs the collector AND eagerly populates the map — so in production a gate
+ *  read always sees the full derived rows. */
+let toolMetadataCollector;
+let toolMetadataLoaded = false;
+/** True while the collector is mid-run. A re-entrant read during collection (the
+ *  collector's own `resolveCapabilities`/`buildHost` path touches the gate) must
+ *  tolerate the partially-populated map WITHOUT tripping the fail-safe — the
+ *  collector is installed and running, so the map is about to be complete. */
+let toolMetadataCollecting = false;
+export function installToolMetadataCollector(collect) {
+    toolMetadataCollector = collect;
+    // A late install (after the first read already ran the empty map) still takes
+    // effect: clear the loaded flag so the next read collects.
+    toolMetadataLoaded = false;
+}
+function ensureToolMetadataLoaded() {
+    if (toolMetadataLoaded || toolMetadataCollector === undefined)
+        return;
+    toolMetadataLoaded = true; // set before running so re-entrant declares don't recurse
+    toolMetadataCollecting = true;
+    try {
+        toolMetadataCollector();
+    }
+    finally {
+        toolMetadataCollecting = false;
+    }
+}
+/**
+ * D1 fail-safe (RFC 0004 P2, SECURITY-CRITICAL): the capability gate must NEVER
+ * fail OPEN. If a reader hits the derived map while it is empty AND no collector
+ * was ever installed, the tools-layer bootstrap did not run — `isToolEnabled`
+ * would otherwise pass EVERYTHING through the permissive `human` default,
+ * silently un-gating `eval_js` / `register_secret` / `network_body` / the engine
+ * gate. Rather than fail open we throw a structured, actionable error so the
+ * misconfiguration is loud and impossible to ship. The guaranteed bootstrap
+ * (`tool-metadata.ts`, imported by every real entry point) is the primary
+ * mechanism that keeps this throw from firing in production; this is the backstop.
+ *
+ * The throw is suppressed only DURING collection (the collector's own gate read
+ * legitimately sees a partial map) — at that point a collector is installed and
+ * running, so the map is about to be complete.
+ */
+function assertGateBootstrapped() {
+    if (TOOL_CAPABILITY_MAP.size > 0 || toolMetadataCollecting)
+        return;
+    throw new Error("browxai capability gate read before the tool-metadata bootstrap ran: the derived " +
+        "TOOL_CAPABILITY map is empty and no collector was installed. Refusing to fail OPEN " +
+        "(which would un-gate eval_js / register_secret / network_body). Import the package " +
+        'entry ("browxai") or call createServer before reading the capability gate. ' +
+        "(RFC 0004 P2 / D1.)");
+}
+/** The derived tool→capability map. Reading drives the lazy collection so the
+ *  rows declared at registration are present for a standalone caller, then
+ *  asserts the gate is bootstrapped (fail-safe — never returns an empty
+ *  un-gated map to a consumer). */
+export function toolCapabilityMap() {
+    ensureToolMetadataLoaded();
+    assertGateBootstrapped();
+    return TOOL_CAPABILITY_MAP;
+}
+/** Back-compat `Record` view of the derived map for the consumers that index it
+ *  by name (`TOOL_CAPABILITY[tool]`). A `Proxy` so a read both triggers the lazy
+ *  collection and reflects any registration that ran after a prior read. Every
+ *  access path that resolves a capability (the by-name `get`, the membership
+ *  `has`, key enumeration, and the D2 `Symbol.iterator` Map-parity iterator)
+ *  runs the D1 fail-safe — the gate never answers from an empty unbootstrapped
+ *  map. */
+export const TOOL_CAPABILITY = new Proxy(Object.create(null), {
+    get(_t, key) {
+        ensureToolMetadataLoaded();
+        // D2: Map-parity iteration — `for (const [tool, cap] of TOOL_CAPABILITY)`
+        // and `[...TOOL_CAPABILITY]` delegate to the backing Map's iterator. Bound
+        // to the Map so the internal-slot read keeps the right receiver.
+        if (key === Symbol.iterator) {
+            assertGateBootstrapped();
+            return TOOL_CAPABILITY_MAP[Symbol.iterator].bind(TOOL_CAPABILITY_MAP);
+        }
+        if (typeof key !== "string")
+            return undefined;
+        assertGateBootstrapped();
+        return TOOL_CAPABILITY_MAP.get(key);
+    },
+    has(_t, key) {
+        ensureToolMetadataLoaded();
+        assertGateBootstrapped();
+        return typeof key === "string" && TOOL_CAPABILITY_MAP.has(key);
+    },
+    ownKeys() {
+        ensureToolMetadataLoaded();
+        assertGateBootstrapped();
+        return [...TOOL_CAPABILITY_MAP.keys()];
+    },
+    getOwnPropertyDescriptor(_t, key) {
+        ensureToolMetadataLoaded();
+        assertGateBootstrapped();
+        if (typeof key === "string" && TOOL_CAPABILITY_MAP.has(key)) {
+            return { enumerable: true, configurable: true, value: TOOL_CAPABILITY_MAP.get(key) };
+        }
+        return undefined;
+    },
+});
+export function resolveCapabilities(env = process.env) {
+    const raw = env.BROWX_CAPABILITIES?.trim();
+    const list = raw
+        ? raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [...DEFAULT_CAPABILITIES];
+    const warnings = [];
+    const live = [];
+    const unknown = [];
+    for (const c of list) {
+        if (ALL_CAPABILITIES.includes(c)) {
+            live.push(c);
+        }
+        else if (Object.prototype.hasOwnProperty.call(RETIRED_CAPABILITIES, c)) {
+            // Retired, not unknown — tolerate it so an old config never crashes.
+            warnings.push(`BROWX_CAPABILITIES: "${c}" is a retired capability — ${RETIRED_CAPABILITIES[c]}. ` +
+                `It is ignored (no effect); the rest of your config is honoured.`);
+        }
+        else {
+            unknown.push(c);
+        }
+    }
+    if (unknown.length) {
+        throw new Error(`BROWX_CAPABILITIES: unknown capability/capabilities ${unknown.map((u) => JSON.stringify(u)).join(", ")}. ` +
+            `Valid: ${ALL_CAPABILITIES.join(", ")}.`);
+    }
+    const enabled = new Set(live);
+    const disabledTools = [];
+    for (const [tool, cap] of toolCapabilityMap()) {
+        if (!enabled.has(cap))
+            disabledTools.push({ tool, capability: cap });
+    }
+    return { enabled, disabledTools, warnings };
+}
+/** Returns true iff the tool is enabled given the active capability set. */
+export function isToolEnabled(tool, caps) {
+    const cap = toolCapabilityMap().get(tool);
+    if (!cap)
+        return true; // unknown tool: pass through (human-coordination default)
+    return caps.enabled.has(cap);
+}
+const ALL_CONFIRM_HOOKS = [
+    "navigate_off_allowlist",
+    "file_download",
+    "file_upload",
+    "byob_action",
+];
+const DEFAULT_CONFIRM_HOOKS = ["navigate_off_allowlist", "byob_action"];
+export function resolveConfirmHooks(env = process.env) {
+    const raw = env.BROWX_CONFIRM_REQUIRED?.trim();
+    if (!raw)
+        return new Set(DEFAULT_CONFIRM_HOOKS);
+    const list = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const unknown = list.filter((h) => !ALL_CONFIRM_HOOKS.includes(h));
+    if (unknown.length) {
+        throw new Error(`BROWX_CONFIRM_REQUIRED: unknown hook(s) ${unknown.map((u) => JSON.stringify(u)).join(", ")}. ` +
+            `Valid: ${ALL_CONFIRM_HOOKS.join(", ")}.`);
+    }
+    return new Set(list);
+}

package/dist/util/config-store.d.ts

@@ -0,0 +1,103 @@
+/** Full resolved view consumed by the server. */
+export interface ResolvedConfig {
+    testAttributes: string[];
+    capabilities: string[];
+    confirmRequired: string[];
+    allowedOrigins: string[];
+    blockedOrigins: string[];
+    headless: boolean;
+    /** hard anti-wedge deadline (ms) applied to every action body /
+     *  `eval_js` / read-CDP path. Default 5000. Per-call `timeoutMs` overrides.
+     *  Clamped to [1, 3_600_000] at use. A real op completes well under this;
+     *  raising it as a blanket masks no-ops/wedges. */
+    actionTimeoutMs?: number;
+    /** when true, `managed` / `incognito` sessions launch with
+     *  `--disable-web-security --disable-site-isolation-trials` (SOP/CORS OFF
+     *  browser-wide). Dangerous opt-in — off by default, loud-warned, and
+     *  deliberately NOT mappable from the legacy env layer (set via MCP
+     *  `set_config` or the managed config file only). No effect on
+     *  `attached`/BYOB (externally launched). */
+    disableWebSecurity?: boolean;
+    /** default device-preset name for new sessions (Playwright device
+     *  registry, e.g. "iPhone 14"). Overridable per `open_session`. */
+    defaultDevice?: string;
+    /** default viewport for new sessions. Overrides a preset's viewport
+     *  when both are set. Overridable per `open_session`. */
+    defaultViewport?: {
+        width: number;
+        height: number;
+    };
+    /** CSS selectors for chrome/overlay elements (dev-build HMR widgets,
+     *  devtools iframes, cookie/consent banners) that should be neutralised
+     *  before the agent interacts with the page. A server-injected init
+     *  script applies `pointer-events:none; display:none` to matches on every
+     *  navigation — non-destructive (no node removal), config-driven, no
+     *  agent JS. Default `[]` (feature off). */
+    hideOverlaySelectors: string[];
+    /** declarative plugin set. Mirrors what `plugins.json`
+     *  declares; persisted alongside other config so `set_config({plugins})`
+     *  and `get_config({scope:"resolved"}).plugins` work without hand-editing
+     *  the plugins.json file. Plugin lifecycle is RESOLVED ONCE AT SERVER
+     *  START — `set_config` persists, but takes effect on next restart
+     *  (mirrors `capabilities`). Empty array = "no plugins declared". */
+    plugins: string[];
+    /** Experimental / feature-flag knobs. Not stable; shallow-merged across layers. */
+    unstable: Record<string, unknown>;
+}
+/** A partial override at one precedence layer. Every key optional. */
+export type ConfigLayer = Partial<Omit<ResolvedConfig, "unstable">> & {
+    unstable?: Record<string, unknown>;
+};
+export type PersistentScope = "user" | "project";
+export type ConfigScope = "defaults" | "env" | PersistentScope | "session";
+export declare const BUILTIN_DEFAULTS: ResolvedConfig;
+/** Legacy `BROWX_*` env vars as a low-precedence layer (above defaults). */
+export declare function envLayer(env?: NodeJS.ProcessEnv): ConfigLayer;
+export declare class ConfigStore {
+    private filePath;
+    private persisted;
+    private env;
+    constructor(workspaceRoot: string, env?: NodeJS.ProcessEnv);
+    private load;
+    private save;
+    /** Merge one layer onto an accumulator. Arrays replace; unstable shallow-merges. */
+    private static apply;
+    /** The precedence chain as DATA (RFC 0004 P4 / D6) — replacing the four
+     *  fixed-order `apply` calls + the `getLayer` switch. The array order IS the
+     *  precedence, applied lowest → highest: env < user < project < session, atop
+     *  the built-in defaults base. CRITICAL: reordering this array silently
+     *  changes which layer wins, so the order is pinned by the config-store unit
+     *  tests for every layer permutation. `read(store, sessionPatch)` returns the
+     *  raw pre-merge layer for that scope (the same value the old `getLayer` arm
+     *  returned). Adding a layer is one entry here, not edits to two methods.
+     *
+     *  `defaults` is NOT in this array: it is the base accumulator, not an
+     *  override layer (`getLayer("defaults")` returns the resolved base directly).
+     *  `session` reads `sessionPatch` during `resolve()` but is not held on the
+     *  store, so its `getLayer` view is `{}` — preserved exactly. */
+    private static readonly PRECEDENCE;
+    /** Resolve the full config. `sessionPatch` is the highest-precedence layer.
+     *  Iterates `PRECEDENCE` low → high atop the defaults base — byte-identical to
+     *  the old fixed `apply(env) → apply(user) → apply(project) → apply(session)`
+     *  sequence, now data-driven. */
+    resolve(sessionPatch?: ConfigLayer): ResolvedConfig;
+    /** Inspect one layer (raw, pre-merge) — for `get_config({ scope })`. Reads the
+     *  same `PRECEDENCE` array `resolve()` iterates, so the inspected layer and the
+     *  applied layer can never diverge. `defaults` returns the base directly (it is
+     *  not an override layer); `session` is never held here, so its raw view is
+     *  `{}` — both preserved exactly. */
+    getLayer(scope: ConfigScope): ConfigLayer | ResolvedConfig;
+    /** Persist a patch into `user` or `project`. The only writer of config.json. */
+    setLayer(scope: PersistentScope, patch: ConfigLayer): void;
+    /** Clear a persistent layer entirely. */
+    resetLayer(scope: PersistentScope): void;
+}
+/**
+ * Adapter: render a `ResolvedConfig` as an env-shaped record so the existing
+ * env-driven resolvers (`resolveCapabilities` / `resolveOriginPolicy` /
+ * `resolveConfirmHooks` / `resolveConfig`) can consume the *fully resolved*
+ * precedence chain without each being rewritten. Precedence is already applied
+ * in `ConfigStore.resolve()`; this just re-expresses the result in the shape
+ * those functions parse.
+ */
+export declare function resolvedToEnv(c: ResolvedConfig): NodeJS.ProcessEnv;

package/dist/util/config-store.js

@@ -0,0 +1,206 @@
+// browxai-managed config store.
+//
+// Precedence (lowest → highest):
+//   built-in defaults < env (legacy BROWX_*) < user < project < session patch
+//
+// Persistent layers live in `<workspace>/config.json` as
+// `{ "user": {...}, "project": {...} }` and are mutated ONLY via
+// set_config / reset_config (the MCP tools). The file is machine-managed —
+// a malformed file degrades to "ignore that layer + warn", never a crash.
+//
+// `workspace` (root path) is intentionally NOT config — it's the *location*
+// the store itself lives at, resolved before the store exists.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "./logging.js";
+import { invariant } from "./invariant.js";
+export const BUILTIN_DEFAULTS = {
+    testAttributes: ["data-testid", "data-test", "data-cy", "data-qa"],
+    capabilities: ["read", "navigation", "action", "human"],
+    confirmRequired: ["navigate_off_allowlist", "byob_action"],
+    allowedOrigins: [],
+    blockedOrigins: [],
+    headless: false,
+    hideOverlaySelectors: [],
+    plugins: [],
+    unstable: {},
+};
+const CONFIG_FILE = "config.json";
+/** Legacy `BROWX_*` env vars as a low-precedence layer (above defaults). */
+export function envLayer(env = process.env) {
+    const layer = {};
+    const list = (v) => v
+        ? v
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : undefined;
+    const ta = list(env.BROWX_TEST_ATTRIBUTES?.trim());
+    if (ta)
+        layer.testAttributes = ta;
+    const caps = list(env.BROWX_CAPABILITIES?.trim());
+    if (caps)
+        layer.capabilities = caps;
+    const cr = list(env.BROWX_CONFIRM_REQUIRED?.trim());
+    if (cr)
+        layer.confirmRequired = cr;
+    const ao = list(env.BROWX_ALLOWED_ORIGINS?.trim());
+    if (ao)
+        layer.allowedOrigins = ao;
+    const bo = list(env.BROWX_BLOCKED_ORIGINS?.trim());
+    if (bo)
+        layer.blockedOrigins = bo;
+    const hl = env.BROWX_HEADLESS?.trim();
+    if (hl)
+        layer.headless = hl === "1" || hl.toLowerCase() === "true";
+    const hos = list(env.BROWX_HIDE_OVERLAY_SELECTORS?.trim());
+    if (hos)
+        layer.hideOverlaySelectors = hos;
+    return layer;
+}
+export class ConfigStore {
+    filePath;
+    persisted = {};
+    env;
+    constructor(workspaceRoot, env = process.env) {
+        this.filePath = join(workspaceRoot, CONFIG_FILE);
+        this.env = envLayer(env);
+        this.load();
+    }
+    load() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const raw = JSON.parse(readFileSync(this.filePath, "utf8"));
+            // Defensive: only accept the two known sections; ignore anything else.
+            this.persisted = {
+                ...(raw.user && typeof raw.user === "object" ? { user: raw.user } : {}),
+                ...(raw.project && typeof raw.project === "object" ? { project: raw.project } : {}),
+            };
+        }
+        catch (e) {
+            log.warn(`config: ${CONFIG_FILE} is malformed — ignoring persistent layers`, {
+                error: e instanceof Error ? e.message : String(e),
+            });
+            this.persisted = {};
+        }
+    }
+    save() {
+        try {
+            writeFileSync(this.filePath, JSON.stringify(this.persisted, null, 2) + "\n", "utf8");
+        }
+        catch (e) {
+            log.warn(`config: failed to write ${CONFIG_FILE}`, {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    /** Merge one layer onto an accumulator. Arrays replace; unstable shallow-merges. */
+    static apply(acc, layer) {
+        if (!layer)
+            return acc;
+        return {
+            testAttributes: layer.testAttributes ?? acc.testAttributes,
+            capabilities: layer.capabilities ?? acc.capabilities,
+            confirmRequired: layer.confirmRequired ?? acc.confirmRequired,
+            allowedOrigins: layer.allowedOrigins ?? acc.allowedOrigins,
+            blockedOrigins: layer.blockedOrigins ?? acc.blockedOrigins,
+            headless: layer.headless ?? acc.headless,
+            actionTimeoutMs: layer.actionTimeoutMs ?? acc.actionTimeoutMs,
+            disableWebSecurity: layer.disableWebSecurity ?? acc.disableWebSecurity,
+            defaultDevice: layer.defaultDevice ?? acc.defaultDevice,
+            defaultViewport: layer.defaultViewport ?? acc.defaultViewport,
+            hideOverlaySelectors: layer.hideOverlaySelectors ?? acc.hideOverlaySelectors,
+            plugins: layer.plugins ?? acc.plugins,
+            unstable: layer.unstable ? { ...acc.unstable, ...layer.unstable } : acc.unstable,
+        };
+    }
+    /** The precedence chain as DATA (RFC 0004 P4 / D6) — replacing the four
+     *  fixed-order `apply` calls + the `getLayer` switch. The array order IS the
+     *  precedence, applied lowest → highest: env < user < project < session, atop
+     *  the built-in defaults base. CRITICAL: reordering this array silently
+     *  changes which layer wins, so the order is pinned by the config-store unit
+     *  tests for every layer permutation. `read(store, sessionPatch)` returns the
+     *  raw pre-merge layer for that scope (the same value the old `getLayer` arm
+     *  returned). Adding a layer is one entry here, not edits to two methods.
+     *
+     *  `defaults` is NOT in this array: it is the base accumulator, not an
+     *  override layer (`getLayer("defaults")` returns the resolved base directly).
+     *  `session` reads `sessionPatch` during `resolve()` but is not held on the
+     *  store, so its `getLayer` view is `{}` — preserved exactly. */
+    static PRECEDENCE = [
+        { scope: "env", read: (s) => s.env },
+        { scope: "user", read: (s) => s.persisted.user },
+        { scope: "project", read: (s) => s.persisted.project },
+        { scope: "session", read: (_s, sessionPatch) => sessionPatch },
+    ];
+    /** Resolve the full config. `sessionPatch` is the highest-precedence layer.
+     *  Iterates `PRECEDENCE` low → high atop the defaults base — byte-identical to
+     *  the old fixed `apply(env) → apply(user) → apply(project) → apply(session)`
+     *  sequence, now data-driven. */
+    resolve(sessionPatch) {
+        // L8: the precedence chain must be non-empty and `session` must be its
+        // highest-precedence (last) layer — the whole contract of `resolve()` is
+        // "apply lowest → highest, session wins". A reordering that demoted `session`
+        // would silently let a persisted layer override an open_session patch. The
+        // PRECEDENCE array is a fixed module constant ending in `session`, so this
+        // holds on every call; the invariant pins the ordering contract at the one
+        // place it is depended on, complementing the per-permutation unit tests.
+        const chain = ConfigStore.PRECEDENCE;
+        invariant(chain.length > 0, "config precedence chain is empty");
+        invariant(chain[chain.length - 1].scope === "session", "config precedence: `session` must be the highest-precedence layer");
+        let acc = { ...BUILTIN_DEFAULTS, unstable: { ...BUILTIN_DEFAULTS.unstable } };
+        for (const layer of chain) {
+            acc = ConfigStore.apply(acc, layer.read(this, sessionPatch));
+        }
+        return acc;
+    }
+    /** Inspect one layer (raw, pre-merge) — for `get_config({ scope })`. Reads the
+     *  same `PRECEDENCE` array `resolve()` iterates, so the inspected layer and the
+     *  applied layer can never diverge. `defaults` returns the base directly (it is
+     *  not an override layer); `session` is never held here, so its raw view is
+     *  `{}` — both preserved exactly. */
+    getLayer(scope) {
+        if (scope === "defaults")
+            return BUILTIN_DEFAULTS;
+        const entry = ConfigStore.PRECEDENCE.find((l) => l.scope === scope);
+        // session config isn't held here (it's per open_session), so its raw layer
+        // is `{}`; every other scope returns its stored layer (or `{}` when unset).
+        return entry?.read(this) ?? {};
+    }
+    /** Persist a patch into `user` or `project`. The only writer of config.json. */
+    setLayer(scope, patch) {
+        const current = this.persisted[scope] ?? {};
+        this.persisted[scope] = {
+            ...current,
+            ...patch,
+            ...(patch.unstable ? { unstable: { ...(current.unstable ?? {}), ...patch.unstable } } : {}),
+        };
+        this.save();
+        log.info(`config: set scope="${scope}"`, { keys: Object.keys(patch) });
+    }
+    /** Clear a persistent layer entirely. */
+    resetLayer(scope) {
+        delete this.persisted[scope];
+        this.save();
+        log.info(`config: reset scope="${scope}"`);
+    }
+}
+/**
+ * Adapter: render a `ResolvedConfig` as an env-shaped record so the existing
+ * env-driven resolvers (`resolveCapabilities` / `resolveOriginPolicy` /
+ * `resolveConfirmHooks` / `resolveConfig`) can consume the *fully resolved*
+ * precedence chain without each being rewritten. Precedence is already applied
+ * in `ConfigStore.resolve()`; this just re-expresses the result in the shape
+ * those functions parse.
+ */
+export function resolvedToEnv(c) {
+    return {
+        BROWX_TEST_ATTRIBUTES: c.testAttributes.join(","),
+        BROWX_CAPABILITIES: c.capabilities.join(","),
+        BROWX_CONFIRM_REQUIRED: c.confirmRequired.join(","),
+        BROWX_ALLOWED_ORIGINS: c.allowedOrigins.join(","),
+        BROWX_BLOCKED_ORIGINS: c.blockedOrigins.join(","),
+        BROWX_HEADLESS: c.headless ? "1" : "",
+    };
+}

package/dist/util/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Threshold below which `snapshot()` emits the "low-content" warning (
+ * ). Tuned conservatively — most non-trivial pages have well more than 5
+ * interactive descendants in the a11y tree; a hydrated page returning fewer is
+ * almost always a sparse-a11y SPA where the DOM-walk fallback wins.
+ */
+export declare const LOW_A11Y_THRESHOLD = 5;
+export interface BrowxConfig {
+    testAttributes: string[];
+}
+export declare function resolveConfig(env?: NodeJS.ProcessEnv): BrowxConfig;

package/dist/util/config.js

@@ -0,0 +1,28 @@
+// Runtime configuration sourced from env. Resolved once at startup so behaviour
+// is predictable per-session. Adopters who need to add a project-conventional
+// data-attribute (e.g. some codebases use `data-type`, `data-cy`, `data-qa`)
+// can do so without code changes:
+//
+//   BROWX_TEST_ATTRIBUTES=data-testid,data-test,data-cy,data-qa,data-type
+//
+// The list is order-sensitive: the **first** match on a node wins as its `testId`
+// and the matched attribute name flows through to selectorHint so the agent
+// transcribes the right selector ("[data-type=\"foo\"]", not "[data-testid=\"foo\"]").
+const DEFAULT_TEST_ATTRIBUTES = ["data-testid", "data-test", "data-cy", "data-qa"];
+/**
+ * Threshold below which `snapshot()` emits the "low-content" warning (
+ * ). Tuned conservatively — most non-trivial pages have well more than 5
+ * interactive descendants in the a11y tree; a hydrated page returning fewer is
+ * almost always a sparse-a11y SPA where the DOM-walk fallback wins.
+ */
+export const LOW_A11Y_THRESHOLD = 5;
+export function resolveConfig(env = process.env) {
+    const raw = env.BROWX_TEST_ATTRIBUTES?.trim();
+    const list = raw
+        ? raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : DEFAULT_TEST_ATTRIBUTES;
+    return { testAttributes: list };
+}