browxai 0.7.0

package/dist/page/har.js

@@ -0,0 +1,174 @@
+// HAR (HTTP Archive) record/replay primitives. Full-session reproducibility:
+// capture every request the page made into a HAR file, then later replay a
+// session with `open_session({hars:[file]})` so navigation/XHR/fetch are served
+// from the archive instead of hitting the network.
+//
+// Recording strategy. Playwright's HAR is finalized on `context.close()` — there
+// is no public mid-session flush. We honour that:
+//
+//   - `start_har({path?})` calls `context.routeFromHAR(harPath, {update:true,
+//     updateMode:"full", updateContent:"embed"})`. From that point every request
+//     in the context is logged into the in-memory HAR.
+//   - `stop_har()` calls `context.unrouteAll({behavior:"wait"})` to remove the
+//     recording route. The HAR FILE on disk is written when the context closes
+//     (`close_session` is the standard finalize point). Until then the path is
+//     reserved + tracked; the caller's flow is "start_har → drive → stop_har →
+//     close_session → read the .har". This Playwright constraint is documented
+//     on every return shape.
+//   - For up-front recording across the whole session, prefer the additive
+//     `open_session({har: {...}})` schema — that routes through Playwright's
+//     `recordHar` context option, which is also finalized on close but is the
+//     blessed native primitive.
+//
+// Replay strategy. `open_session({hars: ["file.har", ...]})` calls
+// `context.routeFromHAR(file, {notFound:"fallback"})` on each path immediately
+// after context creation. Files that escape the workspace are rejected (the
+// `resolveWorkspacePath` helper); a missing file is a hard error (no silent
+// fallback to network on a typo).
+//
+// Per-session state lives in `SessionEntry.har`; the registry's HAR field is
+// initialised at session creation and consulted by `start_har`/`stop_har`.
+import { existsSync, mkdirSync, statSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { resolveWorkspacePath } from "../session/storage.js";
+/** Maximum size (in bytes) at which a finalized HAR is returned inline rather
+ *  than only by path. Mirrors the same cap used by `network_body` / storage
+ *  dumps — agents that hit it should rely on the path field instead. */
+export const HAR_INLINE_CAP_BYTES = 256 * 1024;
+export function newHarRecorderState() {
+    return { active: false };
+}
+/** Default HAR filename for an auto-named recording. ISO timestamp with
+ *  `:` / `.` mapped to `-` so the name is filesystem-safe on every platform. */
+export function defaultHarFilename(sessionId, now = new Date()) {
+    const iso = now.toISOString().replace(/[:.]/g, "-");
+    const safeId = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+    return `${safeId}-${iso}.har`;
+}
+/** Resolve an explicit user-supplied path (workspace-escape rejected) OR
+ *  build the default `<workspace>/har/<auto>.har` path. Creates the parent
+ *  dir on demand — still under the workspace root by construction. */
+export function resolveHarPath(workspaceRoot, sessionId, userPath, tool) {
+    const resolved = userPath
+        ? resolveWorkspacePath(workspaceRoot, userPath, tool)
+        : resolveWorkspacePath(workspaceRoot, `har/${defaultHarFilename(sessionId)}`, tool);
+    // `resolved` is workspace-rooted by construction (resolveWorkspacePath rejects
+    // any escape from `workspaceRoot`); so `dirname(resolved)` is workspace-rooted
+    // too — the mkdirSync below never touches cwd. BROWX_WORKSPACE-derived.
+    const parent = dirname(resolved);
+    if (parent && parent !== resolved && !existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+    }
+    return resolved;
+}
+/** Validate replay HAR file paths supplied to `open_session({hars})`. Each
+ *  must resolve under `$BROWX_WORKSPACE` and the file must exist (a typo
+ *  silently falling back to live network would defeat the point). */
+export function resolveHarReplayPaths(workspaceRoot, hars, tool) {
+    const out = [];
+    for (const h of hars) {
+        if (typeof h !== "string" || !h) {
+            throw new Error(`${tool}: \`hars\` entries must be non-empty workspace-rooted strings`);
+        }
+        const resolved = resolveWorkspacePath(workspaceRoot, h, tool);
+        if (!existsSync(resolved)) {
+            throw new Error(`${tool}: HAR replay file not found at "${resolved}"`);
+        }
+        out.push(resolved);
+    }
+    return out;
+}
+/** Begin HAR recording on a live context via `routeFromHAR(update:true)`. The
+ *  HAR file on disk is finalized when the context closes — this returns the
+ *  reserved path and the caller is responsible for `close_session` (or the
+ *  natural session teardown) to flush. Re-calling `start_har` on an already-
+ *  active recorder replaces the in-flight target after a transparent stop. */
+export async function startHar(context, state, workspaceRoot, sessionId, cfg = {}) {
+    if (state.nativeRecord) {
+        throw new Error("start_har: HAR recording was already wired at session creation via " +
+            "`open_session({har})`. Close the session and re-open without the `har` " +
+            "field if you need start/stop granularity.");
+    }
+    const replacedPrior = state.active;
+    if (replacedPrior) {
+        // Best-effort stop of the prior recorder before swapping targets. Without
+        // this a second `routeFromHAR(update:true)` chains rather than replacing.
+        await context.unrouteAll({ behavior: "wait" }).catch(() => undefined);
+    }
+    const path = resolveHarPath(workspaceRoot, sessionId, cfg.path, "start_har");
+    const mode = cfg.mode ?? "full";
+    const content = cfg.content ?? "embed";
+    const options = {
+        update: true,
+        updateMode: mode,
+        updateContent: content === "omit" ? undefined : content,
+    };
+    if (cfg.urlFilter !== undefined)
+        options.url = cfg.urlFilter;
+    await context.routeFromHAR(path, options);
+    state.active = true;
+    state.path = path;
+    state.startedAt = Date.now();
+    state.mode = mode;
+    state.content = content;
+    state.nativeRecord = false;
+    return { path, mode, content, replacedPrior };
+}
+/** Stop HAR recording on a live context. Removes the recording route; the HAR
+ *  file is written to disk when the context closes (Playwright constraint).
+ *  No-op + `{wasActive:false}` when no recorder is active. */
+export async function stopHar(context, state) {
+    if (!state.active) {
+        return { wasActive: false, finalized: false, nativeRecord: !!state.nativeRecord };
+    }
+    if (state.nativeRecord) {
+        // Recording was wired at context creation — Playwright doesn't expose a
+        // mid-session disable for that path. Surface the constraint instead of
+        // silently lying about having stopped.
+        return { wasActive: true, path: state.path, finalized: false, nativeRecord: true };
+    }
+    await context.unrouteAll({ behavior: "wait" }).catch(() => undefined);
+    const path = state.path;
+    state.active = false;
+    // Keep `path` discoverable on the state until session close so callers can
+    // still find the file after teardown.
+    return { wasActive: true, path, finalized: false, nativeRecord: false };
+}
+/** Best-effort read of a finalized HAR. Used by callers that want the file
+ *  inlined when small. Returns `undefined` when the file doesn't yet exist
+ *  (HAR not finalized) or is over the inline cap. */
+export function readHarIfSmall(path, capBytes = HAR_INLINE_CAP_BYTES) {
+    if (!existsSync(path))
+        return undefined;
+    const st = statSync(path);
+    if (st.size > capBytes)
+        return undefined;
+    return readFileSync(path, "utf8");
+}
+/** Apply replay HAR(s) to a live context. Each file is wired with
+ *  `notFound:"fallback"` so a request that isn't in the archive falls through
+ *  to the live network (the safer default; agents who want a hermetic replay
+ *  can route the rest themselves). */
+export async function applyHarReplay(context, files) {
+    for (const f of files) {
+        await context.routeFromHAR(f, { notFound: "fallback" });
+    }
+}
+/** Build the Playwright `recordHar` option for `open_session({har})`. The
+ *  caller passes this into `browser.newContext({recordHar})` / equivalent
+ *  on `chromium.launchPersistentContext`. */
+export function buildRecordHarOption(workspaceRoot, sessionId, cfg) {
+    const path = resolveHarPath(workspaceRoot, sessionId, cfg.path, "open_session");
+    const mode = cfg.mode ?? "full";
+    const content = cfg.content ?? "embed";
+    const recordHar = {
+        path,
+        mode,
+        content,
+    };
+    if (cfg.urlFilter !== undefined)
+        recordHar.urlFilter = cfg.urlFilter;
+    // Parent dir is ensured by `resolveHarPath`. The path is workspace-rooted by
+    // construction — `resolveWorkspacePath` rejects escape.
+    return { path, mode, content, recordHar };
+}

package/dist/page/heap.d.ts

@@ -0,0 +1,97 @@
+import type { CDPSession } from "playwright-core";
+/** Take a V8 heap snapshot on `cdp`. Returns the full snapshot JSON as a
+ *  string (the format chrome://inspect's Memory tool consumes). Buffers
+ *  `HeapProfiler.addHeapSnapshotChunk` events fired during
+ *  `HeapProfiler.takeHeapSnapshot`. Detaches its listeners on return —
+ *  no leak across calls. */
+export declare function takeHeapSnapshot(cdp: CDPSession): Promise<string>;
+export declare function resolveHeapSnapshotPath(workspaceRoot: string, p: string, tool: string): string;
+/** Default snapshot filename under
+ *  `<workspace>/heap-snapshots/<sessionId>-<ts>.heapsnapshot`. The
+ *  `.heapsnapshot` extension is the one DevTools' Memory panel and
+ *  `chrome://inspect` recognise on drag-and-drop. */
+export declare function defaultHeapSnapshotPath(workspaceRoot: string, sessionId: string): string;
+/** Write a snapshot JSON string to a workspace-rooted file. Creates the
+ *  parent dir if missing. Returns the resolved path + byte count. */
+export declare function writeHeapSnapshotFile(workspaceRoot: string, filePath: string, snapshotJson: string, tool: string): {
+    resolved: string;
+    bytes: number;
+};
+/** Parsed snapshot summary surfaced on `heap_retainers` results. */
+export interface HeapSnapshotSummary {
+    nodeCount: number;
+    edgeCount: number;
+    stringCount: number;
+    /** Sum of `self_size` across every node — total heap occupied. */
+    totalSelfSize: number;
+}
+/** One retainer row in a `heap_retainers` result. */
+export interface HeapRetainerRow {
+    /** Display name of the retainer node: `${type}:${name}` or just `name`. */
+    retainerName: string;
+    retainerType: string;
+    retainerSelfSize: number;
+    /** How many distinct edges from this retainer point to a matching node. */
+    edgesToMatches: number;
+    /** Display names of up to 5 matching nodes this retainer holds. */
+    sampleHeldNodes: string[];
+}
+/** Result body of a `heap_retainers` call. */
+export interface HeapRetainersResult {
+    summary: HeapSnapshotSummary;
+    /** How many nodes the query matched. */
+    matchCount: number;
+    /** Cap-applied retainer rows, sorted by retainer self_size desc. */
+    retainers: HeapRetainerRow[];
+    /** Sample of matched node display names (first 10). Lets the caller
+     *  sanity-check the query without parsing the full retainer set. */
+    sampleMatches: string[];
+    /** Non-fatal extraction warnings (unknown field layout, etc.). */
+    warnings?: string[];
+}
+/** Internal parsed snapshot. */
+interface ParsedSnapshot {
+    nodeFields: string[];
+    nodeTypes: string[];
+    edgeFields: string[];
+    edgeTypes: string[];
+    nodes: number[];
+    edges: number[];
+    strings: string[];
+    nodeFieldCount: number;
+    edgeFieldCount: number;
+    /** Index into nodeFields for fast access. */
+    fieldIdx: {
+        nodeType: number;
+        nodeName: number;
+        nodeSelfSize: number;
+        nodeEdgeCount: number;
+        edgeType: number;
+        edgeName: number;
+        edgeToNode: number;
+    };
+}
+export declare function parseHeapSnapshot(snapshotJson: string): ParsedSnapshot;
+/** Read a snapshot file from disk + parse. */
+export declare function readHeapSnapshotFile(workspaceRoot: string, filePath: string, tool: string): {
+    parsed: ParsedSnapshot;
+    resolved: string;
+};
+/** Query input for `heap_retainers`. Either `name` (string match against
+ *  node display name) or `type` (string match against node type). Both
+ *  may be set — the row matches when both match. */
+export interface HeapRetainersQuery {
+    /** Substring or exact string to match against the node's display name
+     *  (the V8 string-table entry). Case-sensitive. */
+    name?: string;
+    /** Exact node-type to match (`"closure"`, `"object"`, `"hidden"`, …).
+     *  See V8's `node_types[0]` for the catalogue in the snapshot. */
+    type?: string;
+    /** When `name` is set: match style. `"exact"` (default) requires
+     *  string equality; `"substring"` allows substring containment. */
+    nameMatch?: "exact" | "substring";
+}
+/** Run a retainer query over a parsed snapshot. Pure — exported for unit
+ *  tests; the public-facing tool composes parse → query. */
+export declare function queryRetainers(p: ParsedSnapshot, q: HeapRetainersQuery): HeapRetainersResult;
+export {};

package/dist/page/heap.js

@@ -0,0 +1,285 @@
+// V8 heap snapshots — capability `action` (writes a file).
+//
+// "This page slowly leaks memory — what's holding the old DOM tree alive?"
+// has no diagnostic surface in browxai's read-only tools: a screenshot /
+// snapshot / network slice shows what's on the page now, not what's still
+// retained from a previous state. CDP `HeapProfiler.takeHeapSnapshot`
+// produces a V8 heap snapshot blob — the same `.heapsnapshot` format
+// chrome://inspect's Memory tab consumes — that lets the agent ask
+// "who points to objects named X / typed Y" against the live VM.
+//
+// Two tools, one lifecycle (no start/stop — a snapshot is a single
+// point-in-time capture, not a recording window):
+//   - heap_snapshot({path?})         → write a snapshot file under
+//                                       `<workspace>/heap-snapshots/<id>-<ts>.heapsnapshot`.
+//                                       Default path is in the workspace,
+//                                       explicit `path` is enforced inside
+//                                       the workspace.
+//   - heap_retainers({snapshotPath,  → parse a written snapshot and return
+//                     query, …})       top retainers of nodes matching the
+//                                       query (against node name OR class
+//                                       constructor name). Pure file read +
+//                                       in-process parse — no CDP touch.
+//
+// CDP delivers the snapshot as a stream of `HeapProfiler.addHeapSnapshotChunk`
+// events fired during `HeapProfiler.takeHeapSnapshot`. The chunks are JSON
+// fragments that, concatenated in order, form the complete `.heapsnapshot`
+// JSON document. We buffer them and write at end — same pattern as
+// `src/page/perf.ts`'s `Tracing.dataCollected` → `tracingComplete` flow,
+// but without a long-running state-machine (a snapshot is one-shot).
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+/** Take a V8 heap snapshot on `cdp`. Returns the full snapshot JSON as a
+ *  string (the format chrome://inspect's Memory tool consumes). Buffers
+ *  `HeapProfiler.addHeapSnapshotChunk` events fired during
+ *  `HeapProfiler.takeHeapSnapshot`. Detaches its listeners on return —
+ *  no leak across calls. */
+export async function takeHeapSnapshot(cdp) {
+    const chunks = [];
+    const onChunk = (e) => {
+        if (typeof e?.chunk === "string")
+            chunks.push(e.chunk);
+    };
+    cdp.on("HeapProfiler.addHeapSnapshotChunk", onChunk);
+    try {
+        // `reportProgress:false` — we don't need the progress events, just the
+        // chunks. `captureNumericValue` is omitted; the default snapshot covers
+        // what a retainer query needs (we don't read primitive values).
+        await cdp.send("HeapProfiler.takeHeapSnapshot", { reportProgress: false });
+    }
+    finally {
+        cdp.off("HeapProfiler.addHeapSnapshotChunk", onChunk);
+    }
+    return chunks.join("");
+}
+// ---------------------------------------------------------------------------
+// Workspace path helper — mirrors `resolvePerfTracePath` in src/page/perf.ts.
+export function resolveHeapSnapshotPath(workspaceRoot, p, tool) {
+    const resolved = resolve(workspaceRoot, p);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`${tool}: \`path\` must resolve inside $BROWX_WORKSPACE — got "${p}".`);
+    }
+    return resolved;
+}
+/** Default snapshot filename under
+ *  `<workspace>/heap-snapshots/<sessionId>-<ts>.heapsnapshot`. The
+ *  `.heapsnapshot` extension is the one DevTools' Memory panel and
+ *  `chrome://inspect` recognise on drag-and-drop. */
+export function defaultHeapSnapshotPath(workspaceRoot, sessionId) {
+    const safe = (sessionId || "default").replace(/[^A-Za-z0-9._-]/g, "_");
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(workspaceRoot, "heap-snapshots", `${safe}-${ts}.heapsnapshot`);
+}
+/** Write a snapshot JSON string to a workspace-rooted file. Creates the
+ *  parent dir if missing. Returns the resolved path + byte count. */
+export function writeHeapSnapshotFile(workspaceRoot, filePath, snapshotJson, tool) {
+    // Path is workspace-rooted by construction via `resolveHeapSnapshotPath`.
+    const resolved = resolveHeapSnapshotPath(workspaceRoot, filePath, tool);
+    const parent = dirname(resolved);
+    // ws.sub-style: ensure parent exists under workspace.root.
+    if (parent && !existsSync(parent))
+        mkdirSync(parent, { recursive: true });
+    // ws.root-rooted path — see resolveHeapSnapshotPath above for the guard.
+    writeFileSync(resolved, snapshotJson, "utf8");
+    return { resolved, bytes: Buffer.byteLength(snapshotJson, "utf8") };
+}
+const MAX_RETAINER_RESULTS = 50;
+const MAX_SAMPLE_HELD = 5;
+const MAX_SAMPLE_MATCHES = 10;
+/** Parse + validate the heap snapshot JSON into a plain record, throwing a
+ *  descriptive error on malformed input. */
+function parseSnapshotRoot(snapshotJson) {
+    let raw;
+    try {
+        raw = JSON.parse(snapshotJson);
+    }
+    catch (err) {
+        throw new Error(`heap snapshot is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (!raw || typeof raw !== "object") {
+        throw new Error("heap snapshot: top-level value is not an object");
+    }
+    return raw;
+}
+/** Extract the field/type name arrays from `snapshot.meta`. */
+function extractSnapshotMeta(r) {
+    const snapshot = r.snapshot;
+    const meta = snapshot?.meta;
+    if (!meta || !Array.isArray(meta.node_fields) || !Array.isArray(meta.edge_fields)) {
+        throw new Error("heap snapshot: missing snapshot.meta.node_fields / edge_fields");
+    }
+    // node_types[0] / edge_types[0] is the array of distinct type names (the others
+    // are scalar tags like "string" / "number"). V8 quirks.
+    const firstTypeArray = (v) => {
+        const arr = Array.isArray(v) ? v : [];
+        return Array.isArray(arr[0]) ? arr[0].map(String) : [];
+    };
+    return {
+        nodeFields: meta.node_fields.map(String),
+        edgeFields: meta.edge_fields.map(String),
+        nodeTypes: firstTypeArray(meta.node_types),
+        edgeTypes: firstTypeArray(meta.edge_types),
+    };
+}
+export function parseHeapSnapshot(snapshotJson) {
+    const r = parseSnapshotRoot(snapshotJson);
+    const { nodeFields, edgeFields, nodeTypes, edgeTypes } = extractSnapshotMeta(r);
+    const nodes = Array.isArray(r.nodes) ? r.nodes : null;
+    const edges = Array.isArray(r.edges) ? r.edges : null;
+    const strings = Array.isArray(r.strings) ? r.strings.map(String) : null;
+    if (!nodes || !edges || !strings) {
+        throw new Error("heap snapshot: missing nodes / edges / strings arrays");
+    }
+    const fieldIdx = {
+        nodeType: nodeFields.indexOf("type"),
+        nodeName: nodeFields.indexOf("name"),
+        nodeSelfSize: nodeFields.indexOf("self_size"),
+        nodeEdgeCount: nodeFields.indexOf("edge_count"),
+        edgeType: edgeFields.indexOf("type"),
+        edgeName: edgeFields.indexOf("name_or_index"),
+        edgeToNode: edgeFields.indexOf("to_node"),
+    };
+    // Required fields for retainer walking — bail if any are missing.
+    for (const [k, v] of Object.entries(fieldIdx)) {
+        if (v < 0) {
+            throw new Error(`heap snapshot: required field "${k}" missing from meta`);
+        }
+    }
+    return {
+        nodeFields,
+        nodeTypes,
+        edgeFields,
+        edgeTypes,
+        nodes,
+        edges,
+        strings,
+        nodeFieldCount: nodeFields.length,
+        edgeFieldCount: edgeFields.length,
+        fieldIdx,
+    };
+}
+/** Read a snapshot file from disk + parse. */
+export function readHeapSnapshotFile(workspaceRoot, filePath, tool) {
+    const resolved = resolveHeapSnapshotPath(workspaceRoot, filePath, tool);
+    if (!existsSync(resolved)) {
+        throw new Error(`${tool}: snapshot file not found at "${resolved}" — call heap_snapshot first`);
+    }
+    const raw = readFileSync(resolved, "utf8");
+    const parsed = parseHeapSnapshot(raw);
+    return { parsed, resolved };
+}
+/** Display name for a node — `${type}:${name}` if both useful, else
+ *  whichever is non-empty. Falls back to `node#${index}`. */
+function nodeDisplayName(p, nodeIdx) {
+    const base = nodeIdx * p.nodeFieldCount;
+    const typeIdx = p.nodes[base + p.fieldIdx.nodeType] ?? 0;
+    const nameIdx = p.nodes[base + p.fieldIdx.nodeName] ?? 0;
+    const type = p.nodeTypes[typeIdx] ?? "";
+    const name = p.strings[nameIdx] ?? "";
+    if (type && name)
+        return `${type}:${name}`;
+    if (name)
+        return name;
+    if (type)
+        return type;
+    return `node#${nodeIdx}`;
+}
+/** Self size of a node. */
+function nodeSelfSize(p, nodeIdx) {
+    return p.nodes[nodeIdx * p.nodeFieldCount + p.fieldIdx.nodeSelfSize] ?? 0;
+}
+/** First pass: identify nodes matching the query + accumulate total self-size. */
+function findMatchingNodes(p, q, nodeCount) {
+    const nameMatch = q.nameMatch ?? "exact";
+    const matchSet = new Set();
+    let totalSelfSize = 0;
+    for (let i = 0; i < nodeCount; i++) {
+        const base = i * p.nodeFieldCount;
+        totalSelfSize += p.nodes[base + p.fieldIdx.nodeSelfSize] ?? 0;
+        const type = p.nodeTypes[p.nodes[base + p.fieldIdx.nodeType] ?? 0] ?? "";
+        if (q.type && type !== q.type)
+            continue; // type filter first (cheap)
+        if (q.name) {
+            const name = p.strings[p.nodes[base + p.fieldIdx.nodeName] ?? 0] ?? "";
+            if (nameMatch === "exact" ? name !== q.name : !name.includes(q.name))
+                continue;
+        }
+        matchSet.add(i);
+    }
+    return { matchSet, totalSelfSize };
+}
+/** Second pass: walk every node's edge slice and record retainers of matched
+ *  nodes. `to_node` is a FIRST-FIELD index into the flat `nodes` array, so divide
+ *  by `nodeFieldCount` for the logical node index. */
+function walkRetainers(p, matchSet, nodeCount) {
+    const retainerMap = new Map();
+    let edgeCursor = 0;
+    for (let nodeIdx = 0; nodeIdx < nodeCount; nodeIdx++) {
+        const edgesOnThisNode = p.nodes[nodeIdx * p.nodeFieldCount + p.fieldIdx.nodeEdgeCount] ?? 0;
+        for (let e = 0; e < edgesOnThisNode; e++) {
+            const edgeBase = (edgeCursor + e) * p.edgeFieldCount;
+            const toNodeIdx = ((p.edges[edgeBase + p.fieldIdx.edgeToNode] ?? 0) / p.nodeFieldCount) | 0;
+            if (!matchSet.has(toNodeIdx) || nodeIdx === toNodeIdx)
+                continue; // skip non-matches + self
+            let agg = retainerMap.get(nodeIdx);
+            if (!agg) {
+                agg = { edgesToMatches: 0, sampleHeldNodes: [] };
+                retainerMap.set(nodeIdx, agg);
+            }
+            agg.edgesToMatches++;
+            if (agg.sampleHeldNodes.length < MAX_SAMPLE_HELD) {
+                agg.sampleHeldNodes.push(nodeDisplayName(p, toNodeIdx));
+            }
+        }
+        edgeCursor += edgesOnThisNode;
+    }
+    return retainerMap;
+}
+/** Materialise the retainer rows, sorted by self-size desc then edge count desc,
+ *  capped at MAX_RETAINER_RESULTS. */
+function materialiseRetainerRows(p, retainerMap) {
+    const rows = [];
+    for (const [retainerIdx, agg] of retainerMap.entries()) {
+        const typeIdx = p.nodes[retainerIdx * p.nodeFieldCount + p.fieldIdx.nodeType] ?? 0;
+        rows.push({
+            retainerName: nodeDisplayName(p, retainerIdx),
+            retainerType: p.nodeTypes[typeIdx] ?? "",
+            retainerSelfSize: nodeSelfSize(p, retainerIdx),
+            edgesToMatches: agg.edgesToMatches,
+            sampleHeldNodes: agg.sampleHeldNodes,
+        });
+    }
+    rows.sort((a, b) => b.retainerSelfSize !== a.retainerSelfSize
+        ? b.retainerSelfSize - a.retainerSelfSize
+        : b.edgesToMatches - a.edgesToMatches);
+    return rows.length > MAX_RETAINER_RESULTS ? rows.slice(0, MAX_RETAINER_RESULTS) : rows;
+}
+/** Run a retainer query over a parsed snapshot. Pure — exported for unit
+ *  tests; the public-facing tool composes parse → query. */
+export function queryRetainers(p, q) {
+    if (!q.name && !q.type) {
+        // Caller must specify SOMETHING — running against every node would dump
+        // millions of edges and is never the right answer.
+        throw new Error("heap_retainers: query must specify at least one of `name` or `type`");
+    }
+    const nodeCount = (p.nodes.length / p.nodeFieldCount) | 0;
+    const { matchSet, totalSelfSize } = findMatchingNodes(p, q, nodeCount);
+    const summary = {
+        nodeCount,
+        edgeCount: (p.edges.length / p.edgeFieldCount) | 0,
+        stringCount: p.strings.length,
+        totalSelfSize,
+    };
+    if (matchSet.size === 0) {
+        return { summary, matchCount: 0, retainers: [], sampleMatches: [] };
+    }
+    // Sample matches for the caller's sanity check (cap at MAX_SAMPLE_MATCHES).
+    const sampleMatches = [];
+    for (const idx of matchSet) {
+        if (sampleMatches.length >= MAX_SAMPLE_MATCHES)
+            break;
+        sampleMatches.push(nodeDisplayName(p, idx));
+    }
+    const retainers = materialiseRetainerRows(p, walkRetainers(p, matchSet, nodeCount));
+    return { summary, matchCount: matchSet.size, retainers, sampleMatches };
+}

package/dist/page/inspect.d.ts

@@ -0,0 +1,34 @@
+import type { Locator } from "playwright-core";
+/** Always-returned style keys — the ones layout/control-state bugs hinge on.
+ *  Callers can request extra properties via `extra`. */
+export declare const DEFAULT_STYLE_KEYS: readonly ["display", "visibility", "opacity", "position", "cursor", "pointerEvents", "overflow", "overflowX", "overflowY", "zIndex", "flexDirection", "justifyContent", "alignItems"];
+export interface InspectResult {
+    found: boolean;
+    /** Bounding box in CSS px (raw getBoundingClientRect — not viewport-clipped;
+     *  use `find()`'s visible-rect bbox when you need the clipped version). */
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    styles?: Record<string, string>;
+    /** True when the element overflows its own padding box on either axis
+     *  (scrollWidth/Height > clientWidth/Height) — the "label clips / content
+     *  overflows" signal. */
+    overflowing?: {
+        x: boolean;
+        y: boolean;
+    };
+    /** Cheap visibility read: non-zero box + not display:none/visibility:hidden
+     *  + opacity > 0. Not the full visible-rect intersection (that's `find`). */
+    visible?: boolean;
+    childCount?: number;
+}
+/**
+ * Read the whitelisted computed styles + box for a resolved element. Pure
+ * read (no action window). `extra` appends caller-requested style properties
+ * to the default set. Returns `{ found:false }` when the locator matches
+ * nothing.
+ */
+export declare function inspectElement(loc: Locator, extra?: string[]): Promise<InspectResult>;

package/dist/page/inspect.js

@@ -0,0 +1,75 @@
+/// <reference lib="dom" />
+// computed-style + box probe.
+//
+// Layout-break and control-state bugs (a flex row losing a child →
+// misalignment; `cursor-wait` vs `cursor-not-allowed`; a label that clips /
+// overflows) need computed style + box geometry, which the curated surface
+// doesn't otherwise expose. `inspect` is a read primitive returning a
+// *whitelisted* style set + box + overflow/clip state — generalizes the
+// visible-rect work to "is this visually broken".
+/** Always-returned style keys — the ones layout/control-state bugs hinge on.
+ *  Callers can request extra properties via `extra`. */
+export const DEFAULT_STYLE_KEYS = [
+    "display",
+    "visibility",
+    "opacity",
+    "position",
+    "cursor",
+    "pointerEvents",
+    "overflow",
+    "overflowX",
+    "overflowY",
+    "zIndex",
+    "flexDirection",
+    "justifyContent",
+    "alignItems",
+];
+/**
+ * Read the whitelisted computed styles + box for a resolved element. Pure
+ * read (no action window). `extra` appends caller-requested style properties
+ * to the default set. Returns `{ found:false }` when the locator matches
+ * nothing.
+ */
+export async function inspectElement(loc, extra = []) {
+    try {
+        if ((await loc.count()) === 0)
+            return { found: false };
+        const keys = [...DEFAULT_STYLE_KEYS, ...extra];
+        return await loc
+            .evaluate((e, styleKeys) => {
+            const cs = getComputedStyle(e);
+            const styles = {};
+            for (const k of styleKeys) {
+                try {
+                    styles[k] = String(cs[k]);
+                }
+                catch {
+                    /* unknown prop — skip */
+                }
+            }
+            const r = e.getBoundingClientRect();
+            const box = { x: r.x, y: r.y, width: r.width, height: r.height };
+            const overflowing = {
+                x: e.scrollWidth > e.clientWidth + 1,
+                y: e.scrollHeight > e.clientHeight + 1,
+            };
+            const visible = box.width > 0 &&
+                box.height > 0 &&
+                styles.display !== "none" &&
+                styles.visibility !== "hidden" &&
+                Number(styles.opacity || "1") > 0;
+            return {
+                found: true,
+                box,
+                styles,
+                overflowing,
+                visible,
+                childCount: e.childElementCount,
+            };
+        }, keys)
+            .catch(() => ({ found: false }));
+    }
+    catch {
+        return { found: false };
+    }
+}