browxai 0.7.0

package/dist/page/layout-thrash.d.ts

@@ -0,0 +1,34 @@
+import type { CDPSession } from "playwright-core";
+import type { TraceEvent } from "./perf.js";
+/** Default categories for the focused trace — same set DevTools uses when
+ *  it highlights "Forced Reflow" + "Layout Shift" lanes. */
+export declare const LAYOUT_THRASH_CATEGORIES: string[];
+/** Per-origin aggregate: how many events fired from this call-stack + total
+ *  cumulative time, plus a top-N representative origin string. */
+export interface LayoutThrashOrigin {
+    /** Topmost frame: `${functionName}@${url}:${lineNumber}:${columnNumber}` —
+     *  or `"<anonymous>"` if no stack was attached. */
+    originatingStack: string;
+    count: number;
+    totalDurationMs: number;
+}
+export interface LayoutThrashResult {
+    forcedLayoutsCount: number;
+    layoutShiftsCount: number;
+    /** Sorted by count desc. Capped at 50. */
+    eventsByOrigin: LayoutThrashOrigin[];
+    /** Workspace-rooted path the trace was written to. */
+    tracePath: string;
+    durationMs: number;
+}
+export interface LayoutThrashOptions {
+    durationMs?: number;
+}
+/** Default trace filename under `<workspace>/perf/<sessionId>-layout-thrash-<ts>.json`. */
+export declare function defaultLayoutThrashPath(workspaceRoot: string, sessionId: string): string;
+export declare function runLayoutThrashTrace(cdp: CDPSession, workspaceRoot: string, sessionId: string, opts?: LayoutThrashOptions): Promise<LayoutThrashResult>;
+export declare function aggregateLayoutThrash(events: TraceEvent[]): {
+    forcedLayoutsCount: number;
+    layoutShiftsCount: number;
+    eventsByOrigin: LayoutThrashOrigin[];
+};

package/dist/page/layout-thrash.js

@@ -0,0 +1,232 @@
+// Layout-thrash trace — capability `read`. Focused CDP trace just for
+// forced-synchronous-layout + layout-shift events, with origin-of-event
+// stacks aggregated so the agent sees "this rAF loop is causing 200 forced
+// layouts" at a glance instead of paging through a 100MB chromium trace.
+//
+// Pattern mirrors `src/page/perf.ts` (same `Tracing.dataCollected` →
+// `Tracing.tracingComplete` flush flow) but the lifecycle is one-shot —
+// caller doesn't manage state, this function arms + waits + parses + writes
+// in one go.
+//
+// CDP `stackTrace` is populated on relevant trace events when DevTools is
+// attached. We pick the topmost frame as `originatingStack` for the
+// aggregation — that's the function name + url:line:col the agent acts on.
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+/** Default categories for the focused trace — same set DevTools uses when
+ *  it highlights "Forced Reflow" + "Layout Shift" lanes. */
+export const LAYOUT_THRASH_CATEGORIES = [
+    "devtools.timeline",
+    "disabled-by-default-devtools.timeline",
+    "blink.user_timing",
+];
+const DEFAULT_DURATION_MS = 5_000;
+const MAX_DURATION_MS = 30_000;
+const MAX_ORIGINS = 50;
+/** Workspace-rooted path helper — same shape as `resolvePerfTracePath`. */
+function resolveLayoutThrashPath(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 trace filename under `<workspace>/perf/<sessionId>-layout-thrash-<ts>.json`. */
+export function defaultLayoutThrashPath(workspaceRoot, sessionId) {
+    const safe = (sessionId || "default").replace(/[^A-Za-z0-9._-]/g, "_");
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(workspaceRoot, "perf", `${safe}-layout-thrash-${ts}.json`);
+}
+/** Run a focused layout-thrash trace. Records for `durationMs`, parses the
+ *  result, writes the raw events to `<workspace>/perf/...`, returns the
+ *  aggregated finding. */
+/** Start a layout-thrash CDP trace, record for `durationMs`, then stop and drain
+ *  the buffered events (bounded by a 30s completion race). Detaches both
+ *  listeners in `finally` regardless of outcome. */
+async function collectTraceEvents(cdp, durationMs) {
+    const events = [];
+    let complete = null;
+    const onData = (e) => {
+        if (Array.isArray(e?.value)) {
+            for (const ev of e.value)
+                events.push(ev);
+        }
+    };
+    const onComplete = () => {
+        if (complete)
+            complete();
+    };
+    cdp.on("Tracing.dataCollected", onData);
+    cdp.on("Tracing.tracingComplete", onComplete);
+    try {
+        await cdp.send("Tracing.start", {
+            transferMode: "ReportEvents",
+            traceConfig: {
+                recordMode: "recordContinuously",
+                includedCategories: LAYOUT_THRASH_CATEGORIES,
+            },
+        });
+        await new Promise((res) => setTimeout(res, durationMs));
+        const completionPromise = new Promise((res) => {
+            complete = res;
+        });
+        await cdp.send("Tracing.end").catch(() => undefined);
+        await Promise.race([completionPromise, new Promise((res) => setTimeout(res, 30_000))]);
+    }
+    finally {
+        try {
+            cdp.off("Tracing.dataCollected", onData);
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            cdp.off("Tracing.tracingComplete", onComplete);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return events;
+}
+export async function runLayoutThrashTrace(cdp, workspaceRoot, sessionId, opts = {}) {
+    const durationMs = clampDuration(opts.durationMs);
+    const events = await collectTraceEvents(cdp, durationMs);
+    // Write the raw trace events file (workspace-rooted) so the agent can
+    // re-open it in the DevTools Performance panel if desired.
+    const tracePath = defaultLayoutThrashPath(workspaceRoot, sessionId);
+    const resolved = resolveLayoutThrashPath(workspaceRoot, tracePath, "layout_thrash_trace");
+    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 resolveLayoutThrashPath above for the guard.
+    writeFileSync(resolved, JSON.stringify({
+        traceEvents: events,
+        metadata: {
+            source: "browxai",
+            sessionId,
+            categories: LAYOUT_THRASH_CATEGORIES,
+            durationMs,
+            eventCount: events.length,
+            capturedAt: new Date().toISOString(),
+            kind: "layout-thrash",
+        },
+    }), "utf8");
+    const agg = aggregateLayoutThrash(events);
+    return {
+        forcedLayoutsCount: agg.forcedLayoutsCount,
+        layoutShiftsCount: agg.layoutShiftsCount,
+        eventsByOrigin: agg.eventsByOrigin,
+        tracePath: resolved,
+        durationMs,
+    };
+}
+function clampDuration(d) {
+    if (typeof d !== "number" || !Number.isFinite(d) || d <= 0)
+        return DEFAULT_DURATION_MS;
+    if (d > MAX_DURATION_MS)
+        return MAX_DURATION_MS;
+    return Math.floor(d);
+}
+/** Aggregate trace events into the result shape. Pure — exported for unit
+ *  tests against synthetic fixture event blobs. */
+const RECALC_NAMES = new Set(["UpdateLayoutTree", "Recalc Style", "RecalculateStyles"]);
+/** Classify a trace event for the thrash aggregation: a forced/sync layout, a
+ *  layout shift, or a recalc — `relevant` is true when it should be bucketed by
+ *  origin. Returns null for non-object / unnamed events. */
+function classifyLayoutEvent(e) {
+    if (!e || typeof e !== "object")
+        return null;
+    const name = typeof e.name === "string" ? e.name : "";
+    if (!name)
+        return null;
+    const forced = (name === "Layout" && hasForcedFlag(e)) || name === "ForcedSyncLayout";
+    const shift = name === "LayoutShift";
+    const recalc = RECALC_NAMES.has(name);
+    return { forced, shift, relevant: forced || shift || recalc };
+}
+export function aggregateLayoutThrash(events) {
+    let forcedLayoutsCount = 0;
+    let layoutShiftsCount = 0;
+    const byOrigin = new Map();
+    for (const e of events) {
+        const k = classifyLayoutEvent(e);
+        if (!k)
+            continue;
+        if (k.shift)
+            layoutShiftsCount++;
+        if (k.forced)
+            forcedLayoutsCount++;
+        if (!k.relevant)
+            continue;
+        const dur = typeof e.dur === "number" ? e.dur / 1000 : 0;
+        const stack = extractOriginStack(e);
+        const slot = byOrigin.get(stack);
+        if (slot) {
+            slot.count++;
+            slot.totalDurationMs += dur;
+        }
+        else {
+            byOrigin.set(stack, { count: 1, totalDurationMs: dur });
+        }
+    }
+    const eventsByOrigin = [];
+    for (const [originatingStack, { count, totalDurationMs }] of byOrigin) {
+        eventsByOrigin.push({ originatingStack, count, totalDurationMs });
+    }
+    eventsByOrigin.sort((a, b) => b.count - a.count);
+    return {
+        forcedLayoutsCount,
+        layoutShiftsCount,
+        eventsByOrigin: eventsByOrigin.slice(0, MAX_ORIGINS),
+    };
+}
+/** A `Layout` event is "forced sync" when chromium tags it with
+ *  `args.beginData.frame` indicating a JS-driven layout pass. The reliable
+ *  signal in the headless trace stream is the event itself — chromium emits
+ *  `Layout` events on every forced/synchronous layout flush during the
+ *  recording window. Initial page-load layouts also count; the aggregation
+ *  by originating stack distinguishes one from the other.
+ *
+ *  Optimistic note: when DevTools is attached chromium DOES sometimes
+ *  populate `args.data.stackTrace` on the event — we still prefer the
+ *  flagged path when present, since it lets us split per-callsite. The
+ *  bare-event fallback ensures the count surfaces even without stacks. */
+function hasForcedFlag(e) {
+    // `Layout` with a `beginData.frame` is a real layout flush — chromium
+    // emits these on every synchronous layout it does during the recording
+    // window. Treat any Layout event with begin/end data as a forced layout
+    // for the count. The aggregation by originating stack handles
+    // distinguishing per-origin contribution.
+    const args = e.args;
+    if (!args)
+        return false;
+    if (args.beginData && typeof args.beginData === "object")
+        return true;
+    const data = args.data ?? {};
+    if (Array.isArray(data.stackTrace) && data.stackTrace.length > 0)
+        return true;
+    return false;
+}
+/** Get the topmost stack frame as a stable origin string. Returns
+ *  `"<anonymous>"` when no stack is available. */
+function extractOriginStack(e) {
+    const args = e.args;
+    if (!args)
+        return "<anonymous>";
+    const data = args.data ?? args.beginData ?? {};
+    const stack = data.stackTrace;
+    if (!Array.isArray(stack) || stack.length === 0)
+        return "<anonymous>";
+    const top = stack[0];
+    if (!top)
+        return "<anonymous>";
+    const fn = typeof top.functionName === "string" && top.functionName ? top.functionName : "<anonymous>";
+    const url = typeof top.url === "string" ? top.url : "";
+    const line = typeof top.lineNumber === "number" ? top.lineNumber : 0;
+    const col = typeof top.columnNumber === "number" ? top.columnNumber : 0;
+    if (!url)
+        return fn;
+    return `${fn}@${url}:${line}:${col}`;
+}

package/dist/page/learning.d.ts

@@ -0,0 +1,21 @@
+export interface WinnerIdentity {
+    testId?: string;
+    testIdAttr?: string;
+    role: string;
+    name?: string;
+}
+export declare class FeedbackMemory {
+    private entries;
+    private readonly cap;
+    constructor(cap?: number);
+    record(query: string, winner: WinnerIdentity): void;
+    /**
+     * Compute a bonus score (≥ 0) for a candidate against the given query, based on
+     * prior feedback. The bonus = +5 per matching prior entry whose token-set overlaps
+     * the query and whose winner-identity matches the candidate. Capped at +15 per
+     * candidate so a single repeated mistake can't dominate.
+     */
+    bonusFor(query: string, candidate: WinnerIdentity): number;
+    size(): number;
+    clear(): void;
+}

package/dist/page/learning.js

@@ -0,0 +1,84 @@
+// Learned `find()` ranking —  follow-on.
+//
+// Session-scoped, in-memory feedback signal: when the agent calls
+// `find_feedback({ query, ref })` after a successful find→act, we remember that
+// (queryTokenSet → element-identity) pair. On subsequent finds whose query token
+// set overlaps, we boost candidates that match the prior winner's identity.
+//
+// Identity = testId (most stable) or role+name (medium) — the same features the
+// stable-ref scheme uses. So the boost survives snapshots that re-key refs.
+//
+// Cap: 100 entries per session, LRU-evict. Adding more learning sophistication
+// (frequency, decay over wall-clock) is straightforward but work; this
+// minimum-viable version closes the "ranking should adapt" loop without
+// committing to a model.
+export class FeedbackMemory {
+    entries = [];
+    cap;
+    constructor(cap = 100) {
+        this.cap = cap;
+    }
+    record(query, winner) {
+        const tokens = tokenise(query);
+        if (tokens.size === 0)
+            return;
+        // De-dupe: drop any prior entry with identical token set + winner identity.
+        this.entries = this.entries.filter((e) => !(setsEqual(e.tokens, tokens) && identityEqual(e.winner, winner)));
+        this.entries.push({ tokens, winner, ts: Date.now() });
+        if (this.entries.length > this.cap)
+            this.entries.shift();
+    }
+    /**
+     * Compute a bonus score (≥ 0) for a candidate against the given query, based on
+     * prior feedback. The bonus = +5 per matching prior entry whose token-set overlaps
+     * the query and whose winner-identity matches the candidate. Capped at +15 per
+     * candidate so a single repeated mistake can't dominate.
+     */
+    bonusFor(query, candidate) {
+        const qTokens = tokenise(query);
+        if (qTokens.size === 0)
+            return 0;
+        let bonus = 0;
+        for (const e of this.entries) {
+            if (!hasIntersection(qTokens, e.tokens))
+                continue;
+            if (identityEqual(e.winner, candidate))
+                bonus += 5;
+            if (bonus >= 15)
+                break;
+        }
+        return bonus;
+    }
+    size() {
+        return this.entries.length;
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+function tokenise(query) {
+    return new Set(query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 2));
+}
+function hasIntersection(a, b) {
+    for (const t of a)
+        if (b.has(t))
+            return true;
+    return false;
+}
+function setsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const t of a)
+        if (!b.has(t))
+            return false;
+    return true;
+}
+function identityEqual(a, b) {
+    // testId is the strongest disambiguator; if both sides have one, only that matters.
+    if (a.testId && b.testId)
+        return (a.testId === b.testId && (a.testIdAttr ?? "data-testid") === (b.testIdAttr ?? "data-testid"));
+    return a.role === b.role && (a.name ?? "") === (b.name ?? "");
+}

package/dist/page/locator.d.ts

@@ -0,0 +1,54 @@
+import type { Locator, Page } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+/**
+ * Action target shape. Exactly one of `ref` / `selector` / `coords` is
+ * required. `contextRef` optionally scopes a `selector` to the subtree of a
+ * prior ref — lets callers say "the [data-testid=...] *inside this row*"
+ * without baking positional `:nth` chains into the selector. `coords` is the
+ * escape hatch for visually-located targets (canvas, custom-painted UIs,
+ * dismiss-empty-space) that ref/selector resolution genuinely can't address.
+ */
+export type ActionTarget = {
+    ref: string;
+    selector?: undefined;
+    contextRef?: undefined;
+    coords?: undefined;
+} | {
+    selector: string;
+    ref?: undefined;
+    contextRef?: string;
+    coords?: undefined;
+} | {
+    coords: {
+        x: number;
+        y: number;
+    };
+    ref?: undefined;
+    selector?: undefined;
+    contextRef?: undefined;
+};
+export type ResolvedTarget = {
+    kind: "locator";
+    loc: Locator;
+} | {
+    kind: "coords";
+    x: number;
+    y: number;
+};
+export declare function resolveTarget(page: Page, refs: RefRegistry, target: ActionTarget): ResolvedTarget;
+/**
+ * Ambiguity-aware target resolution for the *acting* path. A ref built from a
+ * signal that is shared across repeated / hover-revealed items (e.g. a
+ * `data-testid` reused on every row's edit button) resolves via `.first()` to
+ * whatever instance is first in the DOM — which can be a *different* visible
+ * element than the one the agent found, so the action silently lands at the
+ * wrong visual location. When the primary locator matches more than one node
+ * and the ref carries the concrete structural path it was discovered as,
+ * re-resolve to that concrete element and surface a warning. Verify-before-
+ * dispatch: a loud "I re-resolved" beats a silent wrong-place click.
+ */
+export declare function resolveTargetChecked(page: Page, refs: RefRegistry, target: ActionTarget): Promise<{
+    resolved: ResolvedTarget;
+    warning?: string;
+}>;
+export declare function locatorFor(page: Page, refs: RefRegistry, target: ActionTarget): Locator;

package/dist/page/locator.js

@@ -0,0 +1,142 @@
+// Resolve a `ref` (from snapshot()/find()) or a `selector` (raw CSS / Playwright
+// locator string) into a Playwright Locator we can act on. Refs are the preferred
+// path: they're stable across snapshots and built from role+name(+testId), which
+// gives Playwright auto-waiting + strict-match for free.
+export function resolveTarget(page, refs, target) {
+    if (target.coords) {
+        return { kind: "coords", x: target.coords.x, y: target.coords.y };
+    }
+    return { kind: "locator", loc: locatorFor(page, refs, target) };
+}
+/**
+ * Ambiguity-aware target resolution for the *acting* path. A ref built from a
+ * signal that is shared across repeated / hover-revealed items (e.g. a
+ * `data-testid` reused on every row's edit button) resolves via `.first()` to
+ * whatever instance is first in the DOM — which can be a *different* visible
+ * element than the one the agent found, so the action silently lands at the
+ * wrong visual location. When the primary locator matches more than one node
+ * and the ref carries the concrete structural path it was discovered as,
+ * re-resolve to that concrete element and surface a warning. Verify-before-
+ * dispatch: a loud "I re-resolved" beats a silent wrong-place click.
+ */
+export async function resolveTargetChecked(page, refs, target) {
+    if (target.coords || !target.ref) {
+        return { resolved: resolveTarget(page, refs, target) };
+    }
+    const primary = locatorFor(page, refs, target);
+    const inputs = refs.locatorOf(target.ref);
+    if (!inputs?.cssPath)
+        return { resolved: { kind: "locator", loc: primary } };
+    let count;
+    try {
+        count = await primary.count();
+    }
+    catch {
+        count = 1; // can't tell → don't second-guess the primary path
+    }
+    if (count <= 1)
+        return { resolved: { kind: "locator", loc: primary } };
+    const concrete = page.locator(inputs.cssPath).first();
+    let concreteCount;
+    try {
+        concreteCount = await concrete.count();
+    }
+    catch {
+        concreteCount = 0;
+    }
+    if (concreteCount >= 1) {
+        return {
+            resolved: { kind: "locator", loc: concrete },
+            warning: `ref "${target.ref}": the primary locator matched ${count} nodes ` +
+                `(ambiguous — likely a shared test-id across repeated/overlay items). ` +
+                `Re-resolved to the concrete element captured when the ref was found, ` +
+                `to avoid acting at the wrong visual location.`,
+        };
+    }
+    return {
+        resolved: { kind: "locator", loc: primary },
+        warning: `ref "${target.ref}": the primary locator is ambiguous (${count} matches) ` +
+            `and the concrete path captured at discovery no longer resolves; acting ` +
+            `on .first() — verify the result, the element may have moved or re-rendered.`,
+    };
+}
+export function locatorFor(page, refs, target) {
+    if (target.coords) {
+        throw new Error("locatorFor: coords target has no Locator — use resolveTarget() and switch on kind");
+    }
+    if (target.ref) {
+        const inputs = refs.locatorOf(target.ref);
+        if (!inputs) {
+            throw new Error(`unknown ref "${target.ref}"; call snapshot() or find() first to populate refs, or pass a selector instead`);
+        }
+        // Frame-aware resolution: refs minted inside a child frame
+        // carry a bound Frame handle; route through it so `frame.locator(...)`
+        // crosses the OOPIF / same-origin iframe boundary transparently. Main-
+        // frame refs (no binding) resolve against the page — byte-identical to
+        // pre-v0.5.0 behaviour.
+        const frame = refs.frameOf(target.ref);
+        return locatorFromInputs(frame ?? page, inputs);
+    }
+    if (target.selector) {
+        if (target.contextRef) {
+            const ctxInputs = refs.locatorOf(target.contextRef);
+            if (!ctxInputs) {
+                throw new Error(`unknown contextRef "${target.contextRef}"; call snapshot() or find() first to populate refs`);
+            }
+            const ctxFrame = refs.frameOf(target.contextRef);
+            const ctxLoc = locatorFromInputs(ctxFrame ?? page, ctxInputs);
+            return parseSelectorHint(ctxLoc, target.selector);
+        }
+        return parseSelectorHint(page, target.selector);
+    }
+    throw new Error("locatorFor: requires { ref } or { selector } (with optional { contextRef } for scoped selectors) or { coords }");
+}
+function locatorFromInputs(root, inputs) {
+    // Tier 1: testId — strongest signal, works for any provenance. CSS attribute
+    // form rather than Playwright's `getByTestId` so non-standard test attributes
+    // (`data-type`, `data-cy`, etc.) work without per-context plumbing.
+    if (inputs.testId) {
+        const attr = inputs.testIdAttr ?? "data-testid";
+        return root.locator(`[${attr}=${JSON.stringify(inputs.testId)}]`).first();
+    }
+    // Provenance-aware routing: refs discovered exclusively via the DOM walk
+    // typically carry bare-tag roles (`td`, `div`, `generic`) whose role-locators
+    // are ambiguous or don't actually resolve. Prefer the structural CSS path
+    // captured at walk time.
+    if (inputs.source === "dom" && inputs.cssPath) {
+        return root.locator(inputs.cssPath).first();
+    }
+    // Tier 2: role + name — strong when the a11y pass saw it.
+    if (inputs.name) {
+        return root
+            .getByRole(inputs.role, { name: inputs.name })
+            .first();
+    }
+    // Fallback: structural path (covers `source: "both"` refs where the a11y
+    // pass produced no name, plus the rare migration case of legacy refs that
+    // never got a name).
+    if (inputs.cssPath) {
+        return root.locator(inputs.cssPath).first();
+    }
+    // Last resort: role only. Often ambiguous; the agent saw stability=low.
+    return root.getByRole(inputs.role).first();
+}
+function parseSelectorHint(root, sel) {
+    const s = sel.trim();
+    const attrMatch = s.match(/^\[([a-zA-Z][a-zA-Z0-9-]*)=("([^"]*)"|'([^']*)')\]$/);
+    if (attrMatch) {
+        return root.locator(s).first();
+    }
+    const roleWithNameMatch = s.match(/^role=([a-zA-Z][a-zA-Z0-9-]*)\[name=("((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)')\]$/);
+    if (roleWithNameMatch) {
+        const role = roleWithNameMatch[1];
+        const raw = roleWithNameMatch[3] ?? roleWithNameMatch[4] ?? "";
+        const name = raw.replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\\\/g, "\\");
+        return root.getByRole(role, { name }).first();
+    }
+    const roleOnlyMatch = s.match(/^role=([a-zA-Z][a-zA-Z0-9-]*)$/);
+    if (roleOnlyMatch) {
+        return root.getByRole(roleOnlyMatch[1]).first();
+    }
+    return root.locator(s).first();
+}

package/dist/page/memory-diff.d.ts

@@ -0,0 +1,48 @@
+import { parseHeapSnapshot } from "./heap.js";
+/** One row in the retainer-growth report. */
+export interface RetainerGrowthRow {
+    /** Display name of the grouped nodes: `${type}:${name}` or just `name`. */
+    node: string;
+    /** V8 node-type (closure, object, hidden, …). */
+    type: string;
+    sizeBefore: number;
+    sizeAfter: number;
+    deltaBytes: number;
+    /** Percent change. `sizeBefore:0` reports `deltaPercent: Infinity` →
+     *  surfaced as the string `"+inf"` for JSON serialisability. */
+    deltaPercent: number | "+inf";
+}
+export interface MemoryDiffSummary {
+    totalGrowth: number;
+    top3Growers: Array<{
+        node: string;
+        deltaBytes: number;
+        deltaPercent: number | "+inf";
+    }>;
+}
+export interface MemoryDiffResult {
+    retainerGrowth: RetainerGrowthRow[];
+    summary: MemoryDiffSummary;
+}
+/** Workspace-rooted path helper — same shape as `resolvePerfTracePath`. */
+export declare function resolveHeapPath(workspaceRoot: string, p: string, tool: string): string;
+/** Pure aggregator — group nodes by `${type}:${name}` and sum self_size.
+ *  Exported for unit tests against tiny in-memory snapshot JSON values. */
+export declare function aggregateNodeSizes(parsed: ReturnType<typeof parseHeapSnapshot>): Map<string, {
+    type: string;
+    name: string;
+    size: number;
+}>;
+/** Pure diff helper — given two aggregator maps, return the growth report.
+ *  Exported for unit tests. */
+export declare function diffSizeMaps(before: Map<string, {
+    type: string;
+    name: string;
+    size: number;
+}>, after: Map<string, {
+    type: string;
+    name: string;
+    size: number;
+}>): MemoryDiffResult;
+/** Diff two heap snapshots at the given workspace-rooted paths. */
+export declare function diffHeapSnapshots(workspaceRoot: string, beforePath: string, afterPath: string, tool?: string): MemoryDiffResult;