browxai 0.7.0

package/dist/page/storage-substrate.d.ts

@@ -0,0 +1,215 @@
+import type { BrowserContext, Page } from "playwright-core";
+import type { SafariSessionHandle } from "../engine/index.js";
+import type { CookieInput, WebStorageKind } from "../session/storage.js";
+import type { ListedCookie, CookiesListRequest, WebStorageEntry, IdbDatabasesResult, IdbStoresResult, IdbGetResult, IdbWriteResult, IdbClearResult, CachesListStoragesResult, CachesListResult, CachesGetResult, CachesPutResult, CachesDeleteResult, CachesClearResult, CachesDeleteStorageResult, StorageSubstrate } from "./storage-substrate-types.js";
+export type { ListedCookie, SafariListedCookie, CookiesListRequest, WebStorageEntry, IdbDatabasesResult, IdbStoresResult, IdbGetResult, IdbWriteResult, IdbClearResult, CachesListStoragesResult, CachesListResult, CachesGetResult, CachesPutResult, CachesDeleteResult, CachesClearResult, CachesDeleteStorageResult, StorageSubstrate, } from "./storage-substrate-types.js";
+/** Playwright engines — delegates cookie ops to the existing `cookiesList` /
+ *  `cookiesSet` over the session's BrowserContext (the `context` thunk captures the
+ *  session entry, the same per-call access the handlers did before this seam), and
+ *  the web-storage ops to the existing `webStorage*` helpers over the session's Page
+ *  (the `page` thunk, likewise). No behaviour change. */
+export declare class PlaywrightStorageSubstrate implements StorageSubstrate {
+    private readonly context;
+    private readonly page;
+    readonly engine: string;
+    constructor(context: () => BrowserContext, page: () => Page, engine?: string);
+    cookiesList(req: CookiesListRequest): Promise<ListedCookie[]>;
+    cookiesSet(req: CookieInput): Promise<{
+        ok: boolean;
+        name: string;
+    }>;
+    webStorageGet(kind: WebStorageKind, args: {
+        key: string;
+    }, tool: string): Promise<{
+        value: string | null;
+        origin: string;
+    }>;
+    webStorageList(kind: WebStorageKind, tool: string): Promise<{
+        entries: WebStorageEntry[];
+        origin: string;
+    }>;
+    webStorageSet(kind: WebStorageKind, args: {
+        key: string;
+        value: string;
+    }, tool: string): Promise<{
+        ok: true;
+        origin: string;
+    }>;
+    webStorageDelete(kind: WebStorageKind, args: {
+        key: string;
+    }, tool: string): Promise<{
+        ok: true;
+        origin: string;
+    }>;
+    webStorageClear(kind: WebStorageKind, tool: string): Promise<{
+        ok: true;
+        origin: string;
+    }>;
+    idbListDatabases(tool: string): Promise<IdbDatabasesResult>;
+    idbListStores(args: {
+        dbName: string;
+    }, tool: string): Promise<IdbStoresResult>;
+    idbGet(args: {
+        dbName: string;
+        storeName: string;
+        key: unknown;
+    }, tool: string): Promise<IdbGetResult>;
+    idbPut(args: {
+        dbName: string;
+        storeName: string;
+        key: unknown;
+        value: unknown;
+    }, tool: string): Promise<IdbWriteResult>;
+    idbDelete(args: {
+        dbName: string;
+        storeName: string;
+        key: unknown;
+    }, tool: string): Promise<IdbWriteResult>;
+    idbClear(args: {
+        dbName: string;
+        storeName: string;
+    }, tool: string): Promise<IdbClearResult>;
+    cachesListStorages(tool: string): Promise<CachesListStoragesResult>;
+    cachesList(args: {
+        cacheName: string;
+        urlPattern?: string;
+    }, tool: string): Promise<CachesListResult>;
+    cachesGet(args: {
+        cacheName: string;
+        url: string;
+    }, tool: string): Promise<CachesGetResult>;
+    cachesPut(args: {
+        cacheName: string;
+        url: string;
+        response: {
+            status?: number;
+            headers?: Record<string, string>;
+            body?: string;
+            contentBase64?: string;
+        };
+    }, tool: string): Promise<CachesPutResult>;
+    cachesDelete(args: {
+        cacheName: string;
+        url: string;
+    }, tool: string): Promise<CachesDeleteResult>;
+    cachesClear(args: {
+        cacheName: string;
+    }, tool: string): Promise<CachesClearResult>;
+    cachesDeleteStorage(args: {
+        cacheName: string;
+    }, tool: string): Promise<CachesDeleteStorageResult>;
+}
+/** Safari — the WebDriver-Classic storage path. Cookies ride the Classic cookie
+ *  endpoints; web-storage rides `execute/sync`, which runs page-context JS just like
+ *  Playwright's `page.evaluate` (the ScriptSubstrate proves the seam). safaridriver
+ *  returns the cookie jar for the current document; the Playwright `urls`
+ *  cross-domain filter is not available over WebDriver, so it is inert here.
+ *  `cookiesSet` scopes to the current document's domain — derived from `url` when
+ *  given (else the explicit `domain`); the session must already be navigated to that
+ *  domain. The web-storage methods run the SAME page-side IIFE the Playwright helper
+ *  evaluates, wrapped in `return (…)` (an expression, not a statement body) the way
+ *  `execute/sync` expects — the validation + origin guard mirror the helper so the
+ *  error envelopes match. Web-storage is page-side JS, so safaridriver runs it the
+ *  same way: on the no-Playwright-Page Safari engine this is a NEW working
+ *  capability (the handler previously had no Safari path and threw), surfaced
+ *  through the same port so the handler stays engine-blind. IndexedDB and the
+ *  Cache API are the exception: both APIs are promise-based, so the page-side script
+ *  is an ASYNC IIFE that must be awaited — but safaridriver's `execute/sync` returns
+ *  the moment the body returns and never observes the settled promise, and there is
+ *  no async-script client on this handle. So every idb and caches method REFUSES
+ *  cleanly in the adapter — rejecting with a structured Error the handler's
+ *  `errText` renders (the pre-seam handlers threw at `page()`, so a reject keeps
+ *  that contract) — rather than running a script whose result would always be a
+ *  pending promise. */
+export declare class SafariStorageSubstrate implements StorageSubstrate {
+    private readonly handle;
+    readonly engine = "safari";
+    constructor(handle: SafariSessionHandle);
+    cookiesList(_req: CookiesListRequest): Promise<ListedCookie[]>;
+    cookiesSet(req: CookieInput): Promise<{
+        ok: boolean;
+        name: string;
+    }>;
+    webStorageGet(kind: WebStorageKind, args: {
+        key: string;
+    }, tool: string): Promise<{
+        value: string | null;
+        origin: string;
+    }>;
+    webStorageList(kind: WebStorageKind, tool: string): Promise<{
+        entries: WebStorageEntry[];
+        origin: string;
+    }>;
+    webStorageSet(kind: WebStorageKind, args: {
+        key: string;
+        value: string;
+    }, tool: string): Promise<{
+        ok: true;
+        origin: string;
+    }>;
+    webStorageDelete(kind: WebStorageKind, args: {
+        key: string;
+    }, tool: string): Promise<{
+        ok: true;
+        origin: string;
+    }>;
+    webStorageClear(kind: WebStorageKind, tool: string): Promise<{
+        ok: true;
+        origin: string;
+    }>;
+    idbListDatabases(tool: string): Promise<IdbDatabasesResult>;
+    idbListStores(_args: {
+        dbName: string;
+    }, tool: string): Promise<IdbStoresResult>;
+    idbGet(_args: {
+        dbName: string;
+        storeName: string;
+        key: unknown;
+    }, tool: string): Promise<IdbGetResult>;
+    idbPut(_args: {
+        dbName: string;
+        storeName: string;
+        key: unknown;
+        value: unknown;
+    }, tool: string): Promise<IdbWriteResult>;
+    idbDelete(_args: {
+        dbName: string;
+        storeName: string;
+        key: unknown;
+    }, tool: string): Promise<IdbWriteResult>;
+    idbClear(_args: {
+        dbName: string;
+        storeName: string;
+    }, tool: string): Promise<IdbClearResult>;
+    cachesListStorages(tool: string): Promise<CachesListStoragesResult>;
+    cachesList(_args: {
+        cacheName: string;
+        urlPattern?: string;
+    }, tool: string): Promise<CachesListResult>;
+    cachesGet(_args: {
+        cacheName: string;
+        url: string;
+    }, tool: string): Promise<CachesGetResult>;
+    cachesPut(_args: {
+        cacheName: string;
+        url: string;
+        response: {
+            status?: number;
+            headers?: Record<string, string>;
+            body?: string;
+            contentBase64?: string;
+        };
+    }, tool: string): Promise<CachesPutResult>;
+    cachesDelete(_args: {
+        cacheName: string;
+        url: string;
+    }, tool: string): Promise<CachesDeleteResult>;
+    cachesClear(_args: {
+        cacheName: string;
+    }, tool: string): Promise<CachesClearResult>;
+    cachesDeleteStorage(_args: {
+        cacheName: string;
+    }, tool: string): Promise<CachesDeleteStorageResult>;
+    private idbRefuse;
+    private cachesRefuse;
+}

package/dist/page/storage-substrate.js

@@ -0,0 +1,280 @@
+// The StorageSubstrate interface — the engine-agnostic seam beneath the storage
+// tools (cookies + localStorage/sessionStorage + IndexedDB + Cache API CRUD). It is
+// the storage side of the engine-agnostic port layer: a tool handler asks a substrate
+// to read or write the cookie jar, web-storage, an IndexedDB store, or the Cache API and gets back a
+// universal result; an engine-specific implementation does the work. The handler
+// never names Playwright, safaridriver, or an engine — it calls
+// `storageFor(e).cookiesList(req)` / `storageFor(e).webStorageGet(kind, req)` /
+// `storageFor(e).idbGet(args, tool)` / `storageFor(e).cachesList(args, tool)`, the
+// same shape as `actionsFor(e).click(args)` / `captureFor(e).screenshot(req)`.
+//
+// Dependency direction (architecture doctrine §1): tool handler → StorageSubstrate
+// (this interface) → implementation → Playwright BrowserContext/Page | safaridriver.
+// Two impls today:
+//   - PlaywrightStorageSubstrate (chromium / firefox / webkit / android): wraps the
+//     existing `cookiesList` / `cookiesSet` over a Playwright BrowserContext and the
+//     existing `webStorage*` / `idb*` helpers over a Playwright Page — byte-identical
+//     to the pre-seam path, so the four engines' keystones stay green unchanged. The
+//     native `urls` cross-domain filter is honoured.
+//   - SafariStorageSubstrate (safari): wraps the WebDriver Classic cookie endpoints
+//     (`getCookies` / `addCookie`; no Playwright BrowserContext) and the WebDriver
+//     `execute/sync` endpoint for web-storage (page-side JS, which safaridriver CAN
+//     run — the same `return (…)` expression wrapping the ScriptSubstrate uses). For
+//     cookies, safaridriver scopes the jar to the current document, so the `urls`
+//     filter is inert (the WebDriver protocol has no cross-domain cookie filter) and
+//     `cookies_set` derives the domain from `url` exactly as the pre-seam Safari
+//     branch did. For web-storage the origin guard reads `currentUrl()` — the Classic
+//     substitute for the Playwright `page.url()` the helper guards on. The gating
+//     lives here, not as an `if (e.session.safari?.())` branch in the handler.
+import { cookiesList, cookiesSet, webStorageGet, webStorageSet, webStorageList, webStorageDelete, webStorageClear, } from "../session/storage.js";
+import { idbListDatabases, idbListStores, idbGet, idbPut, idbDelete, idbClear, } from "../session/idb-storage.js";
+import { cachesListStorages, cachesList, cachesGet, cachesPut, cachesDelete, cachesClear, cachesDeleteStorage, } from "../session/cache-storage.js";
+/** Playwright engines — delegates cookie ops to the existing `cookiesList` /
+ *  `cookiesSet` over the session's BrowserContext (the `context` thunk captures the
+ *  session entry, the same per-call access the handlers did before this seam), and
+ *  the web-storage ops to the existing `webStorage*` helpers over the session's Page
+ *  (the `page` thunk, likewise). No behaviour change. */
+export class PlaywrightStorageSubstrate {
+    context;
+    page;
+    engine;
+    constructor(context, page, engine = "chromium") {
+        this.context = context;
+        this.page = page;
+        this.engine = engine;
+    }
+    async cookiesList(req) {
+        return cookiesList(this.context(), { urls: req.urls });
+    }
+    async cookiesSet(req) {
+        const r = await cookiesSet(this.context(), req);
+        return { ok: r.ok, name: req.name };
+    }
+    webStorageGet(kind, args, tool) {
+        return webStorageGet(this.page(), kind, args, tool);
+    }
+    webStorageList(kind, tool) {
+        return webStorageList(this.page(), kind, tool);
+    }
+    webStorageSet(kind, args, tool) {
+        return webStorageSet(this.page(), kind, args, tool);
+    }
+    webStorageDelete(kind, args, tool) {
+        return webStorageDelete(this.page(), kind, args, tool);
+    }
+    webStorageClear(kind, tool) {
+        return webStorageClear(this.page(), kind, tool);
+    }
+    idbListDatabases(tool) {
+        return idbListDatabases(this.page(), tool);
+    }
+    idbListStores(args, tool) {
+        return idbListStores(this.page(), args, tool);
+    }
+    idbGet(args, tool) {
+        return idbGet(this.page(), args, tool);
+    }
+    idbPut(args, tool) {
+        return idbPut(this.page(), args, tool);
+    }
+    idbDelete(args, tool) {
+        return idbDelete(this.page(), args, tool);
+    }
+    idbClear(args, tool) {
+        return idbClear(this.page(), args, tool);
+    }
+    cachesListStorages(tool) {
+        return cachesListStorages(this.page(), tool);
+    }
+    cachesList(args, tool) {
+        return cachesList(this.page(), args, tool);
+    }
+    cachesGet(args, tool) {
+        return cachesGet(this.page(), args, tool);
+    }
+    cachesPut(args, tool) {
+        return cachesPut(this.page(), args, tool);
+    }
+    cachesDelete(args, tool) {
+        return cachesDelete(this.page(), args, tool);
+    }
+    cachesClear(args, tool) {
+        return cachesClear(this.page(), args, tool);
+    }
+    cachesDeleteStorage(args, tool) {
+        return cachesDeleteStorage(this.page(), args, tool);
+    }
+}
+/** Web-storage is origin-scoped and page-bound — the page MUST be at the target
+ *  origin first. On Safari the Classic substitute for `page.url()` is
+ *  `currentUrl()`; this guard reframes about:blank / unreachable into the same
+ *  navigation hint the Playwright helper throws, so the refusal reads identically
+ *  on every engine. */
+async function safariWebStorageGuard(handle, kind, tool) {
+    let url;
+    try {
+        url = await handle.webDriver.currentUrl(handle.sessionId);
+    }
+    catch {
+        url = "";
+    }
+    if (!url || url === "about:blank") {
+        throw new Error(`${tool}: ${kind} is origin-scoped and the page is at "${url || "(unknown)"}". ` +
+            `Navigate the session to the target origin first.`);
+    }
+}
+/** Safari — the WebDriver-Classic storage path. Cookies ride the Classic cookie
+ *  endpoints; web-storage rides `execute/sync`, which runs page-context JS just like
+ *  Playwright's `page.evaluate` (the ScriptSubstrate proves the seam). safaridriver
+ *  returns the cookie jar for the current document; the Playwright `urls`
+ *  cross-domain filter is not available over WebDriver, so it is inert here.
+ *  `cookiesSet` scopes to the current document's domain — derived from `url` when
+ *  given (else the explicit `domain`); the session must already be navigated to that
+ *  domain. The web-storage methods run the SAME page-side IIFE the Playwright helper
+ *  evaluates, wrapped in `return (…)` (an expression, not a statement body) the way
+ *  `execute/sync` expects — the validation + origin guard mirror the helper so the
+ *  error envelopes match. Web-storage is page-side JS, so safaridriver runs it the
+ *  same way: on the no-Playwright-Page Safari engine this is a NEW working
+ *  capability (the handler previously had no Safari path and threw), surfaced
+ *  through the same port so the handler stays engine-blind. IndexedDB and the
+ *  Cache API are the exception: both APIs are promise-based, so the page-side script
+ *  is an ASYNC IIFE that must be awaited — but safaridriver's `execute/sync` returns
+ *  the moment the body returns and never observes the settled promise, and there is
+ *  no async-script client on this handle. So every idb and caches method REFUSES
+ *  cleanly in the adapter — rejecting with a structured Error the handler's
+ *  `errText` renders (the pre-seam handlers threw at `page()`, so a reject keeps
+ *  that contract) — rather than running a script whose result would always be a
+ *  pending promise. */
+export class SafariStorageSubstrate {
+    handle;
+    engine = "safari";
+    constructor(handle) {
+        this.handle = handle;
+    }
+    async cookiesList(_req) {
+        return this.handle.webDriver.getCookies(this.handle.sessionId);
+    }
+    async cookiesSet(req) {
+        let derivedDomain = req.domain;
+        if (!derivedDomain && req.url) {
+            try {
+                derivedDomain = new URL(req.url).hostname;
+            }
+            catch {
+                derivedDomain = undefined;
+            }
+        }
+        await this.handle.webDriver.addCookie(this.handle.sessionId, {
+            name: req.name,
+            value: req.value,
+            path: req.path ?? "/",
+            ...(derivedDomain ? { domain: derivedDomain } : {}),
+            ...(typeof req.expires === "number" ? { expiry: Math.floor(req.expires) } : {}),
+            ...(req.httpOnly !== undefined ? { httpOnly: req.httpOnly } : {}),
+            ...(req.secure !== undefined ? { secure: req.secure } : {}),
+            ...(req.sameSite ? { sameSite: req.sameSite } : {}),
+        });
+        return { ok: true, name: req.name };
+    }
+    async webStorageGet(kind, args, tool) {
+        if (!args.key)
+            throw new Error(`${tool}: \`key\` is required`);
+        await safariWebStorageGuard(this.handle, kind, tool);
+        const expr = `(() => { var s = window.${kind}; ` +
+            `return { value: s.getItem(${JSON.stringify(args.key)}), origin: window.location.origin }; })()`;
+        return (await this.handle.webDriver.executeScript(this.handle.sessionId, `return (${expr});`));
+    }
+    async webStorageList(kind, tool) {
+        await safariWebStorageGuard(this.handle, kind, tool);
+        const expr = `(() => { var s = window.${kind}; var out = []; ` +
+            `for (var i = 0; i < s.length; i++) { var k = s.key(i); if (k === null) continue; ` +
+            `out.push({ key: k, value: s.getItem(k) || "" }); } ` +
+            `return { entries: out, origin: window.location.origin }; })()`;
+        return (await this.handle.webDriver.executeScript(this.handle.sessionId, `return (${expr});`));
+    }
+    async webStorageSet(kind, args, tool) {
+        if (!args.key)
+            throw new Error(`${tool}: \`key\` is required`);
+        if (typeof args.value !== "string")
+            throw new Error(`${tool}: \`value\` (string) is required`);
+        await safariWebStorageGuard(this.handle, kind, tool);
+        const expr = `(() => { var s = window.${kind}; ` +
+            `s.setItem(${JSON.stringify(args.key)}, ${JSON.stringify(args.value)}); ` +
+            `return { ok: true, origin: window.location.origin }; })()`;
+        return (await this.handle.webDriver.executeScript(this.handle.sessionId, `return (${expr});`));
+    }
+    async webStorageDelete(kind, args, tool) {
+        if (!args.key)
+            throw new Error(`${tool}: \`key\` is required`);
+        await safariWebStorageGuard(this.handle, kind, tool);
+        const expr = `(() => { var s = window.${kind}; s.removeItem(${JSON.stringify(args.key)}); ` +
+            `return { ok: true, origin: window.location.origin }; })()`;
+        return (await this.handle.webDriver.executeScript(this.handle.sessionId, `return (${expr});`));
+    }
+    async webStorageClear(kind, tool) {
+        await safariWebStorageGuard(this.handle, kind, tool);
+        const expr = `(() => { var s = window.${kind}; s.clear(); ` +
+            `return { ok: true, origin: window.location.origin }; })()`;
+        return (await this.handle.webDriver.executeScript(this.handle.sessionId, `return (${expr});`));
+    }
+    idbListDatabases(tool) {
+        return Promise.reject(this.idbRefuse(tool));
+    }
+    idbListStores(_args, tool) {
+        return Promise.reject(this.idbRefuse(tool));
+    }
+    idbGet(_args, tool) {
+        return Promise.reject(this.idbRefuse(tool));
+    }
+    idbPut(_args, tool) {
+        return Promise.reject(this.idbRefuse(tool));
+    }
+    idbDelete(_args, tool) {
+        return Promise.reject(this.idbRefuse(tool));
+    }
+    idbClear(_args, tool) {
+        return Promise.reject(this.idbRefuse(tool));
+    }
+    cachesListStorages(tool) {
+        return Promise.reject(this.cachesRefuse(tool));
+    }
+    cachesList(_args, tool) {
+        return Promise.reject(this.cachesRefuse(tool));
+    }
+    cachesGet(_args, tool) {
+        return Promise.reject(this.cachesRefuse(tool));
+    }
+    cachesPut(_args, tool) {
+        return Promise.reject(this.cachesRefuse(tool));
+    }
+    cachesDelete(_args, tool) {
+        return Promise.reject(this.cachesRefuse(tool));
+    }
+    cachesClear(_args, tool) {
+        return Promise.reject(this.cachesRefuse(tool));
+    }
+    cachesDeleteStorage(_args, tool) {
+        return Promise.reject(this.cachesRefuse(tool));
+    }
+    // IndexedDB's API is promise-based, so its page-side script is an async IIFE that
+    // must be awaited — but safaridriver's `execute/sync` returns the moment the body
+    // returns, never observing the settled promise, and this handle has no
+    // async-script client. Rather than run a script whose result is always a pending
+    // promise, every idb method refuses cleanly here by rejecting with this Error
+    // (the handler's `errText` renders it — the pre-seam handlers threw at `page()`,
+    // so a reject preserves that contract), keeping the engine check out of the handler.
+    idbRefuse(tool) {
+        return new Error(`\`${tool}\`: IndexedDB is not available on the Safari engine — its promise-based API ` +
+            `needs an async page-script path that safaridriver's synchronous execute/sync cannot provide. ` +
+            `Use a chromium, firefox, or webkit session for IndexedDB.`);
+    }
+    // The Cache API is promise-based exactly like IndexedDB — its page-side script is
+    // an async IIFE that safaridriver's synchronous execute/sync cannot await, and this
+    // handle has no async-script client. Same clean in-adapter refusal, keeping the
+    // engine check out of the handler.
+    cachesRefuse(tool) {
+        return new Error(`\`${tool}\`: the Cache API is not available on the Safari engine — its promise-based API ` +
+            `needs an async page-script path that safaridriver's synchronous execute/sync cannot provide. ` +
+            `Use a chromium, firefox, or webkit session for the Cache API.`);
+    }
+}

package/dist/page/structural.d.ts

@@ -0,0 +1,9 @@
+import { type A11yNode } from "./a11y.js";
+/**
+ * Walk the tree once and tag each descendant of a recognised repeated
+ * container with its structural context. Mutates nodes in place.
+ *
+ * Idempotent — re-running on the same tree produces the same annotations
+ * (each node's `context` is overwritten with the freshly computed value).
+ */
+export declare function annotateStructuralContext(tree: A11yNode): void;

package/dist/page/structural.js

@@ -0,0 +1,152 @@
+// Structural-context detector.
+//
+// Annotates A11yNode entries with `context: { collection, rowKey, column,
+// rowText }` when they live inside a recognised repeated layout (semantic
+// table/grid, list, feed). Detection is driven by ARIA roles — generic across
+// any web app, no per-target heuristics.
+//
+// Detection precedence (per node):
+//   1. ancestor chain contains `role=row`           → row context, column from header alignment
+//   2. ancestor chain contains `role=listitem`      → list context
+//   3. ancestor chain contains `role=article` whose siblings are also `role=article`
+//                                                    → feed/card context
+// Otherwise: no annotation (the field stays undefined).
+import { walk } from "./a11y.js";
+const COLLECTION_ROLES = new Set(["table", "grid", "treegrid", "rowgroup", "list", "feed"]);
+const ROW_ROLE = "row";
+const CELL_ROLES = new Set(["cell", "gridcell", "rowheader"]);
+/**
+ * Walk the tree once and tag each descendant of a recognised repeated
+ * container with its structural context. Mutates nodes in place.
+ *
+ * Idempotent — re-running on the same tree produces the same annotations
+ * (each node's `context` is overwritten with the freshly computed value).
+ */
+export function annotateStructuralContext(tree) {
+    const parents = new Map();
+    const ancestors = new Map();
+    ancestors.set(tree, []);
+    for (const { node } of walk(tree)) {
+        const chain = ancestors.get(node) ?? [];
+        for (const c of node.children) {
+            parents.set(c, node);
+            ancestors.set(c, [node, ...chain]);
+        }
+    }
+    // Pre-compute column headers per collection root. Look for the first child
+    // row whose cells are all `role=columnheader` — that's the header row.
+    const columnHeadersByRoot = new Map();
+    for (const { node: root } of walk(tree)) {
+        if (!COLLECTION_ROLES.has(root.role))
+            continue;
+        const headerRow = findHeaderRow(root);
+        if (!headerRow)
+            continue;
+        columnHeadersByRoot.set(root, headerRow.children.filter((c) => c.role === "columnheader").map((c) => (c.name ?? "").trim()));
+    }
+    for (const { node } of walk(tree)) {
+        const chain = ancestors.get(node);
+        if (!chain)
+            continue;
+        const row = findRowContainer(node, chain);
+        if (!row)
+            continue;
+        node.context = buildStructuralContext(node, chain, row, parents, columnHeadersByRoot);
+    }
+}
+/** Resolve the column header for `node` within `row` — index the node's cell
+ *  ancestor (or the node itself) against the collection root's header list. */
+function resolveColumn(node, chain, row, collectionRoot, columnHeadersByRoot) {
+    if (!collectionRoot || !columnHeadersByRoot.has(collectionRoot))
+        return undefined;
+    const headers = columnHeadersByRoot.get(collectionRoot);
+    const cellAncestor = chain.find((a) => CELL_ROLES.has(a.role)) ?? (CELL_ROLES.has(node.role) ? node : undefined);
+    if (!cellAncestor)
+        return undefined;
+    const idx = row.children.indexOf(cellAncestor);
+    return idx >= 0 && idx < headers.length ? headers[idx] || undefined : undefined;
+}
+/** Build the `StructuralContext` for a node inside a resolved row container. */
+function buildStructuralContext(node, chain, row, parents, columnHeadersByRoot) {
+    const collectionRoot = nearestCollectionRoot(row, parents);
+    const ctx = {
+        collection: collectionRoot ? collectionRoot.role : `${row.role}-list`,
+    };
+    const rowKey = firstNonEmptyName(row);
+    const column = resolveColumn(node, chain, row, collectionRoot, columnHeadersByRoot);
+    const rowText = collectVisibleText(row, 200);
+    if (rowKey)
+        ctx.rowKey = rowKey;
+    if (column)
+        ctx.column = column;
+    if (rowText)
+        ctx.rowText = rowText;
+    return ctx;
+}
+function findRowContainer(node, ancestorChain) {
+    // `node` itself qualifies if it's a row/listitem — agents often act on the row.
+    if (node.role === ROW_ROLE || node.role === "listitem" || isArticleInFeed(node, ancestorChain)) {
+        return node;
+    }
+    for (const a of ancestorChain) {
+        if (a.role === ROW_ROLE)
+            return a;
+        if (a.role === "listitem")
+            return a;
+        if (isArticleInFeed(a, ancestorChain))
+            return a;
+    }
+    return undefined;
+}
+function isArticleInFeed(node, chain) {
+    if (node.role !== "article")
+        return false;
+    // Only treat `article` as a row when the chain shows a `feed` ancestor —
+    // otherwise a standalone article isn't a repeated container.
+    return chain.some((a) => a.role === "feed");
+}
+function nearestCollectionRoot(row, parents) {
+    let cur = parents.get(row);
+    while (cur) {
+        if (COLLECTION_ROLES.has(cur.role))
+            return cur;
+        cur = parents.get(cur);
+    }
+    return undefined;
+}
+function findHeaderRow(root) {
+    // Search at most two levels deep for a row whose children are all
+    // `columnheader`s (skip nested rowgroups gracefully).
+    const queue = [{ node: root, depth: 0 }];
+    while (queue.length) {
+        const { node, depth } = queue.shift();
+        if (node.role === ROW_ROLE && node.children.some((c) => c.role === "columnheader")) {
+            return node;
+        }
+        if (depth < 2) {
+            for (const c of node.children)
+                queue.push({ node: c, depth: depth + 1 });
+        }
+    }
+    return undefined;
+}
+function firstNonEmptyName(row) {
+    for (const { node } of walk(row)) {
+        const n = (node.name ?? "").trim();
+        if (n)
+            return n.length > 80 ? n.slice(0, 79) + "…" : n;
+    }
+    return undefined;
+}
+function collectVisibleText(node, max) {
+    const parts = [];
+    for (const { node: n } of walk(node)) {
+        const name = (n.name ?? "").trim();
+        if (name)
+            parts.push(name);
+    }
+    const joined = parts.join(" ").replace(/\s+/g, " ").trim();
+    if (!joined)
+        return "";
+    return joined.length > max ? joined.slice(0, max - 1) + "…" : joined;
+}

package/dist/page/substrate-bundle-safari.d.ts

@@ -0,0 +1,8 @@
+import type { SubstrateBundle, SubstrateDeps } from "../engine/registry.js";
+/** The Safari `SubstrateBundle` — the safari engine registers this. `safari!()` is
+ *  the Safari-native WebDriver-Classic + BiDi handle, present on every safari
+ *  session by construction (the safari `BrowserSession` always supplies it). Takes
+ *  the per-server `SubstrateDeps` to honour the standardized `makeSubstrates(deps)`
+ *  contract, but ignores them: every Safari selector reads the Safari-native handle,
+ *  not the Playwright `ctxFor`/`describeTarget`/`save` deps. */
+export declare function safariSubstrateBundle(_deps: SubstrateDeps): SubstrateBundle;