dsh-browser-playwright-codex 0.5.1

package/lib/runtime-state.d.ts

@@ -0,0 +1,45 @@
+/** How a page is read into a snapshot tree. */
+export type SnapshotEngine = 'legacy' | 'aria';
+/** Current enable state (loads from disk on first call). */
+export declare function getEnabled(): boolean;
+/** Set the enable state. Returns true if the value actually changed. */
+export declare function setEnabled(next: boolean): boolean;
+/** Subscribe to enable-state transitions. Returns an unsubscribe function. */
+export declare function subscribe(fn: (enabled: boolean) => void): () => void;
+/**
+ * The page-reading mode the user picked, or undefined when they never picked
+ * one — the configured default then applies.
+ */
+export declare function getSnapshotEngine(): SnapshotEngine | undefined;
+/** Pick the page-reading mode. Returns true if the value actually changed. */
+export declare function setSnapshotEngine(next: SnapshotEngine): boolean;
+/**
+ * Report the mode this deployment was configured with, so the settings page can
+ * display what is actually in effect instead of guessing. Called by the provider
+ * when it is constructed; not persisted (it comes from config).
+ * @param engine - the configured default mode.
+ */
+export declare function publishConfiguredEngine(engine: SnapshotEngine): void;
+/**
+ * What a capture will use right now: the user's pick, else the configured
+ * default, else 'legacy'. This is what the settings page shows.
+ */
+export declare function getEffectiveEngine(): SnapshotEngine;
+/** Whether the current mode is the user's own pick rather than the default. */
+export declare function isEngineUserChosen(): boolean;
+/**
+ * The tool family's effective gates, published at registration. The Settings page
+ * needs to show what is actually in effect — including whatever a profile patch
+ * or a home-level patch decided — instead of guessing at the package default.
+ * Not persisted: it is derived from config every time the plugin is applied.
+ * @param gates - whether browser_evaluate / browser_cdp are registered.
+ */
+export declare function publishGates(gates: {
+    allowEvaluate: boolean;
+    allowCdp: boolean;
+}): void;
+/** The published gates, or undefined while the tool family has not been applied. */
+export declare function getGates(): {
+    allowEvaluate: boolean;
+    allowCdp: boolean;
+} | undefined;

package/lib/runtime-state.js

@@ -0,0 +1,181 @@
+/**
+ * Shared user settings for dsh-browser-playwright-codex, used by the three host
+ * entries (browser / browser-playwright / browser-tool) and by the settings-page
+ * switches in dsh-browser-toggle.
+ *
+ * Two settings, both user-facing:
+ *   - `enabled` (default true)  — are the browser tools available at all.
+ *   - `engine`  (default: unset) — how a page is read into the snapshot tree.
+ *       'legacy' = the plugin's own DOM walk (most tested).
+ *       'aria'   = the browser's official accessibility tree (what a screen
+ *                  reader sees), usually more faithful on complex pages.
+ *     Unset means "follow the configured default", which is 'legacy'.
+ *
+ * State persists to ~/.dsh/dsh-browser-playwright.state.json so both settings
+ * survive a DSH restart. The FILE name deliberately keeps the pre-rename
+ * spelling: it is persisted user state, and renaming it would silently reset the
+ * user's switches.
+ *
+ * The file is re-read on every call (no read-once caching), so a change made on
+ * one side (web or desktop) is visible to the other immediately, and flipping a
+ * switch needs no restart and no config edit.
+ *
+ * `DSH_BROWSER_STATE_FILE` redirects the file; tests use it so they never touch
+ * real user state.
+ * @module dsh-browser-playwright-codex/runtime-state
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// Shared layer: the web and desktop sides read the same switch file, so one
+// agent can never see two different states depending on which side is open.
+const STATE_DIR = path.join(os.homedir(), '.dsh');
+const DEFAULT_STATE_FILE = path.join(STATE_DIR, 'dsh-browser-playwright.state.json');
+/** The state file in use, resolved per call so tests can redirect it. */
+function stateFile() {
+    const override = process.env.DSH_BROWSER_STATE_FILE;
+    return override !== undefined && override !== '' ? override : DEFAULT_STATE_FILE;
+}
+let _enabled = true;
+let _engine = undefined;
+/** Default pushed in by the provider that is actually loaded (display only). */
+let _configuredEngine = undefined;
+/** Effective tool gates, pushed in by the tool family when it is applied (display only). */
+let _gates = undefined;
+const _subscribers = new Set();
+function load() {
+    // Re-read the file on every call: whichever side flips the switch, the
+    // other side follows immediately (no read-once caching).
+    const previous = _enabled;
+    try {
+        const txt = fs.readFileSync(stateFile(), 'utf8');
+        const obj = JSON.parse(txt);
+        if (obj !== null && typeof obj === 'object') {
+            if (typeof obj.enabled === 'boolean')
+                _enabled = obj.enabled;
+            // The file is authoritative for the page-reading mode: an absent or
+            // unknown value means "follow the configured default" (undefined here).
+            // Files written before this setting existed therefore stay valid.
+            _engine = obj.engine === 'legacy' || obj.engine === 'aria' ? obj.engine : undefined;
+        }
+    }
+    catch {
+        // Missing file / parse error / unreadable: keep the current values.
+    }
+    if (_enabled !== previous) {
+        for (const fn of [..._subscribers]) {
+            try {
+                fn(_enabled);
+            }
+            catch {
+                // One subscriber failing must not affect the others.
+            }
+        }
+    }
+}
+function persist() {
+    try {
+        const target = stateFile();
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        // Atomic write: rename(2) is atomic on the same filesystem, so a crash
+        // mid-write leaves either the old file or the new file, never half of
+        // both.
+        const tmp = target + '.tmp';
+        // Keep the historical shape until the user actually picks a page-reading
+        // mode: an absent `engine` means "use the configured default".
+        const payload = _engine === undefined ? { enabled: _enabled } : { enabled: _enabled, engine: _engine };
+        fs.writeFileSync(tmp, JSON.stringify(payload, null, 2));
+        fs.renameSync(tmp, target);
+    }
+    catch {
+        // Persist failure must not break the in-memory switches; the next set
+        // will retry.
+    }
+}
+/** Current enable state (loads from disk on first call). */
+export function getEnabled() {
+    load();
+    return _enabled;
+}
+/** Set the enable state. Returns true if the value actually changed. */
+export function setEnabled(next) {
+    load();
+    if (typeof next !== 'boolean')
+        return false;
+    if (_enabled === next)
+        return false;
+    _enabled = next;
+    persist();
+    for (const fn of [..._subscribers]) {
+        try {
+            fn(next);
+        }
+        catch {
+            // One subscriber failing must not prevent others from reacting.
+        }
+    }
+    return true;
+}
+/** Subscribe to enable-state transitions. Returns an unsubscribe function. */
+export function subscribe(fn) {
+    _subscribers.add(fn);
+    return () => {
+        _subscribers.delete(fn);
+    };
+}
+/**
+ * The page-reading mode the user picked, or undefined when they never picked
+ * one — the configured default then applies.
+ */
+export function getSnapshotEngine() {
+    load();
+    return _engine;
+}
+/** Pick the page-reading mode. Returns true if the value actually changed. */
+export function setSnapshotEngine(next) {
+    load();
+    if (next !== 'legacy' && next !== 'aria')
+        return false;
+    if (_engine === next)
+        return false;
+    _engine = next;
+    persist();
+    return true;
+}
+/**
+ * Report the mode this deployment was configured with, so the settings page can
+ * display what is actually in effect instead of guessing. Called by the provider
+ * when it is constructed; not persisted (it comes from config).
+ * @param engine - the configured default mode.
+ */
+export function publishConfiguredEngine(engine) {
+    if (engine === 'legacy' || engine === 'aria')
+        _configuredEngine = engine;
+}
+/**
+ * What a capture will use right now: the user's pick, else the configured
+ * default, else 'legacy'. This is what the settings page shows.
+ */
+export function getEffectiveEngine() {
+    load();
+    return _engine ?? _configuredEngine ?? 'legacy';
+}
+/** Whether the current mode is the user's own pick rather than the default. */
+export function isEngineUserChosen() {
+    load();
+    return _engine !== undefined;
+}
+/**
+ * The tool family's effective gates, published at registration. The Settings page
+ * needs to show what is actually in effect — including whatever a profile patch
+ * or a home-level patch decided — instead of guessing at the package default.
+ * Not persisted: it is derived from config every time the plugin is applied.
+ * @param gates - whether browser_evaluate / browser_cdp are registered.
+ */
+export function publishGates(gates) {
+    _gates = { allowEvaluate: gates.allowEvaluate === true, allowCdp: gates.allowCdp === true };
+}
+/** The published gates, or undefined while the tool family has not been applied. */
+export function getGates() {
+    return _gates === undefined ? undefined : { ..._gates };
+}

package/lib/service.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Browser capability seam: the provider registry and selection service.
+ * Providers implement browser backends; consumers acquire sessions through
+ * ctx.browser without importing a concrete implementation.
+ * @module dsh-browser-playwright-codex/service
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { BrowserProvider, BrowserSession } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        browser: BrowserRuntime;
+    }
+}
+/** Selection config for the browser seam. */
+export interface BrowserRuntimeConfig {
+    /** Explicit provider id. Omitted = auto-select when exactly one is registered. */
+    readonly provider?: string;
+}
+/** Schemastery validation for {@link BrowserRuntimeConfig}. */
+export declare const Config: z<BrowserRuntimeConfig>;
+/**
+ * The browser service, registered as ctx.browser (one instance per context).
+ * Selection semantics (resolved at acquire time, never order-dependent):
+ * - A configured id that is registered → that provider.
+ * - A configured id not registered → CONFIGURED_PROVIDER_MISSING.
+ * - No id configured, exactly one registered provider → that provider.
+ * - No id configured, multiple registered providers → AMBIGUOUS_PROVIDER.
+ * - No registered provider → NO_PROVIDER.
+ */
+export default class BrowserRuntime extends Service {
+    static Config: z<BrowserRuntimeConfig>;
+    private readonly providers;
+    private readonly configuredId;
+    constructor(ctx: Context, config?: BrowserRuntimeConfig);
+    /**
+     * Register a browser provider. Duplicate ids fail the registering plugin.
+     * @param provider - the provider; its id is the registry key.
+     * @returns the disposer that unregisters and disposes the provider.
+     */
+    registerProvider(provider: BrowserProvider): () => void;
+    /**
+     * Acquire the session owned by the owner key through the selected provider.
+     * @param owner - opaque caller-owned session key (a harness session id).
+     * @param signal - optional cancellation forwarded to the provider.
+     * @returns the live browser session.
+     */
+    acquire(owner: string, signal?: AbortSignal): Promise<BrowserSession>;
+    /**
+     * Release the session owned by the owner key on every registered provider;
+     * providers ignore unknown owners.
+     * @param owner - the owner key whose session should be released.
+     */
+    disposeOwner(owner: string): Promise<void>;
+    private resolveProvider;
+}

package/lib/service.js

@@ -0,0 +1,96 @@
+/**
+ * Browser capability seam: the provider registry and selection service.
+ * Providers implement browser backends; consumers acquire sessions through
+ * ctx.browser without importing a concrete implementation.
+ * @module dsh-browser-playwright-codex/service
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { BrowserError } from "./errors.js";
+/** Schemastery validation for {@link BrowserRuntimeConfig}. */
+export const Config = z.object({
+    provider: z.string(),
+});
+/**
+ * The browser service, registered as ctx.browser (one instance per context).
+ * Selection semantics (resolved at acquire time, never order-dependent):
+ * - A configured id that is registered → that provider.
+ * - A configured id not registered → CONFIGURED_PROVIDER_MISSING.
+ * - No id configured, exactly one registered provider → that provider.
+ * - No id configured, multiple registered providers → AMBIGUOUS_PROVIDER.
+ * - No registered provider → NO_PROVIDER.
+ */
+export default class BrowserRuntime extends Service {
+    static Config = Config;
+    providers = new Map();
+    configuredId;
+    constructor(ctx, config = {}) {
+        super(ctx, 'browser');
+        this.configuredId = config.provider;
+        // Unloading this plugin disposes every registered provider's resources.
+        this.ctx.effect(() => () => {
+            for (const provider of this.providers.values())
+                void provider.dispose();
+            this.providers.clear();
+        });
+    }
+    /**
+     * Register a browser provider. Duplicate ids fail the registering plugin.
+     * @param provider - the provider; its id is the registry key.
+     * @returns the disposer that unregisters and disposes the provider.
+     */
+    registerProvider(provider) {
+        if (this.providers.has(provider.id)) {
+            throw new BrowserError('AMBIGUOUS_PROVIDER', 'a browser provider with id "' + provider.id + '" is already registered');
+        }
+        const runtime = this;
+        const dispose = this.ctx.effect(function* () {
+            runtime.providers.set(provider.id, provider);
+            yield () => {
+                runtime.providers.delete(provider.id);
+                void provider.dispose();
+            };
+        }, 'browser.registerProvider()');
+        return () => void dispose();
+    }
+    /**
+     * Acquire the session owned by the owner key through the selected provider.
+     * @param owner - opaque caller-owned session key (a harness session id).
+     * @param signal - optional cancellation forwarded to the provider.
+     * @returns the live browser session.
+     */
+    async acquire(owner, signal) {
+        return this.resolveProvider().acquire(owner, signal);
+    }
+    /**
+     * Release the session owned by the owner key on every registered provider;
+     * providers ignore unknown owners.
+     * @param owner - the owner key whose session should be released.
+     */
+    async disposeOwner(owner) {
+        for (const provider of this.providers.values()) {
+            await provider.disposeOwner(owner);
+        }
+    }
+    resolveProvider() {
+        const { configuredId, providers } = this;
+        if (configuredId !== undefined) {
+            const provider = providers.get(configuredId);
+            if (provider === undefined) {
+                throw new BrowserError('CONFIGURED_PROVIDER_MISSING', 'configured browser provider "' + configuredId + '" is not registered');
+            }
+            return provider;
+        }
+        const registered = [...providers.values()];
+        const [single] = registered;
+        if (single === undefined) {
+            throw new BrowserError('NO_PROVIDER', 'no browser provider is registered; mount the playwright entry of this package');
+        }
+        if (registered.length > 1) {
+            throw new BrowserError('AMBIGUOUS_PROVIDER', 'multiple browser providers are registered (' +
+                registered.map((p) => p.id).join(', ') +
+                '); configure one explicitly');
+        }
+        return single;
+    }
+}

package/lib/snapshot-aria.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Aria semantic snapshot engine: uses Playwright's official
+ * locator.ariaSnapshot({ mode: 'ai' }) as the semantic tree source, then
+ * re-aligns refs onto the project's stable data-dsh-ref scheme.
+ *
+ * Why a ref-alignment layer: ariaSnapshot's `[ref=eN]` are Playwright-internal
+ * per-invocation handles — they are NOT locator-addressable and their numbering
+ * does not survive the project's cross-snapshot stability contract. This module
+ * therefore (1) walks the DOM to mint/keep the same e<docNonce><seq> refs the
+ * legacy engine uses, (2) parses the official YAML into a semantic tree, and
+ * (3) assigns the DOM-minted refs to actionable nodes in document order, so
+ * refLocator('[data-dsh-ref=...]') and REF_PATTERN keep working unchanged.
+ *
+ * The actionable set is intentionally role-based (the same role set the
+ * injected engine uses) so DOM-side ref assignment and tree-side ref alignment
+ * agree on ordering; elements that only tabindex/contenteditable would make
+ * actionable in the legacy engine are out of scope for this engine.
+ * @module dsh-browser-playwright-codex/snapshot-aria
+ */
+import type { Page } from 'playwright-core';
+import type { BrowserNode } from './types.ts';
+/**
+ * Page-context script: walks the DOM in document order and mints/keeps
+ * data-dsh-ref on every actionable element (same rule as the legacy engine,
+ * minus the tabindex/contenteditable escape hatches). Returns the refs in
+ * document order plus the per-document nonce, so the alignment layer can pair
+ * them with the aria tree's actionable nodes depth-first.
+ */
+export declare const ARIA_REF_SCRIPT: string;
+/** One semantic node parsed from the official ariaSnapshot YAML. */
+export interface AriaNode {
+    readonly role: string;
+    readonly name: string;
+    /** Playwright-internal ref from the YAML ([ref=eN]); used for alignment only. */
+    readonly ariaRef?: string;
+    readonly level?: number;
+    readonly checked?: boolean;
+    readonly selected?: boolean;
+    readonly disabled?: boolean;
+    readonly href?: string;
+    /** `/placeholder:` attribute line: names an input the same way the legacy walker does. */
+    readonly placeholder?: string;
+    readonly children: readonly AriaNode[];
+}
+/** Parsed tree plus the lines the parser could not read (format drift). */
+export interface AriaParseResult {
+    readonly roots: AriaNode[];
+    /** Content lines that could not be parsed — non-empty means format drift. */
+    readonly unparsed: string[];
+}
+/**
+ * Parse Playwright's official ariaSnapshot YAML into a semantic node tree.
+ *
+ * The real format (verified against playwright-core 1.62, 2026-09-30) is:
+ *
+ *   - generic [active] [ref=e1]:          ← trailing ':' = the node has children
+ *     - link "One" [ref=e6] [cursor=pointer]:
+ *       - /url: /one                       ← href rides a deeper child line
+ *     - text: Name                         ← text content uses 'text: <value>'
+ *
+ * The first version of this parser assumed a hand-rolled dialect
+ * (`- role "name" [flags] -> href`, nothing after the flags) that real output
+ * never produces. Every container line ends in ':', so that regex matched none
+ * of them: the whole hierarchy was dropped, links and their hrefs vanished, and
+ * `captureAriaSnapshot` still reported success. Unreadable lines are now
+ * collected in `unparsed` so the capture layer can refuse the tree and let the
+ * provider fall back to the legacy engine.
+ * @param yaml - the ariaSnapshot text.
+ * @returns parsed roots plus any unreadable content lines.
+ */
+export declare function parseAriaSnapshotWithStats(yaml: string): AriaParseResult;
+/**
+ * Parse Playwright's ariaSnapshot YAML into a semantic node tree.
+ * @param yaml - the ariaSnapshot text.
+ * @returns the parsed root nodes (see {@link parseAriaSnapshotWithStats} for
+ * the unreadable-line report this is a thin wrapper over).
+ */
+export declare function parseAriaSnapshot(yaml: string): AriaNode[];
+/** Whether an aria role carries a ref (must match the DOM-side assignment). */
+export declare function isActionableRole(role: string): boolean;
+/**
+ * Build BrowserNode[] from the parsed aria tree, aligning DOM-minted refs onto
+ * actionable nodes in depth-first order, with node/name caps and truncation.
+ * @param nodes - parsed aria tree roots.
+ * @param opts - bounding options.
+ * @param refs - data-dsh-refs minted by the page-side walk, in document order.
+ * @returns the converted tree plus the truncation flag.
+ */
+export declare function ariaTreeToBrowserNodes(nodes: readonly AriaNode[], opts: {
+    maxNodes: number;
+    maxNameLength: number;
+    maxTextLength: number;
+    interactiveOnly?: boolean;
+}, refs: readonly string[], roles?: readonly string[]): {
+    nodes: BrowserNode[];
+    truncated: boolean;
+    totalRefs: number;
+    misaligned: boolean;
+};
+/**
+ * Capture one aria snapshot from a live page: official ariaSnapshot(mode:'ai')
+ * for the semantic tree, DOM-side ref minting for stable refs, then alignment.
+ * Returns the same shape the legacy capture produces, so playwright.ts can
+ * dispatch transparently.
+ *
+ * `missing: true` is the honest-failure contract: the official call threw, the
+ * YAML was empty, or the text carried lines this parser cannot read. The caller
+ * must treat it as "engine unavailable" (the provider falls back to the legacy
+ * DOM walker) and must never forward the empty node list to the model.
+ */
+export declare function captureAriaSnapshot(page: Page, opts: {
+    interactiveOnly?: boolean;
+    maxNodes: number;
+    maxNameLength: number;
+    maxTextLength: number;
+} | undefined): Promise<{
+    nodes: BrowserNode[];
+    truncated: boolean;
+    totalRefs: number;
+    missing?: boolean;
+}>;