@juxtapose/core 0.4.0 → 0.6.0

package/dist/capture/snap.js

@@ -0,0 +1,103 @@
+// Capture one URL through the full settle pipeline, outside any run.
+//
+// The public entry point for `jux snap` and for anything else that needs a
+// single deterministic capture. It exists so captureStory and the settle
+// pipeline can stay unexported (see index.ts): callers get the result of the
+// load-bearing ordering without being able to reorder it.
+import { createUrlPlatform } from '../platforms/urls.js';
+import { captureStory } from './capture.js';
+import { captureEnv } from './env.js';
+const DEFAULT_SNAP_VIEWPORT = { width: 1280, height: 800 };
+/**
+ * Capture several URLs with one context and one page, in order.
+ * A page that fails records its error and the rest still capture: the agent
+ * asked for all of them and wants to know which ones it got.
+ *
+ * One page, navigated, is the cold path captureStory already takes: a
+ * navigation discards injected styles and captureStory re-applies them.
+ * Origin state is cleared between pages by resetBetweenPages.
+ */
+export async function snapPages(opts) {
+    const viewport = opts.viewport ?? DEFAULT_SNAP_VIEWPORT;
+    const context = await opts.browser.newContext({ viewport, blockServiceWorkers: true });
+    try {
+        const page = await context.newPage();
+        let status = null;
+        const off = page.onMainResponse((s) => (status = s));
+        const pages = [];
+        for (const [k, url] of opts.urls.entries()) {
+            status = null;
+            const id = `snap-${k}`;
+            const platform = createUrlPlatform([
+                { id, url, ...(opts.params ? { params: opts.params } : {}) },
+            ]);
+            try {
+                const [story] = await platform.enumerate({ projectRoot: process.cwd() });
+                const snapshot = await captureStory(page, story, { platform, baseUrl: url }, viewport);
+                if (!snapshot)
+                    throw new Error('page declared skip');
+                pages.push({ url, snapshot, status });
+            }
+            catch (err) {
+                pages.push({
+                    url,
+                    status,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            await resetBetweenPages(context, page, url);
+        }
+        off();
+        return { env: captureEnv(opts.browser), pages };
+    }
+    finally {
+        await context.close().catch(() => { });
+    }
+}
+/**
+ * A navigation keeps everything origin-scoped: cookies, localStorage,
+ * IndexedDB, Cache Storage and service workers. One context is shared by every
+ * page (a context per page would cost the launch savings back), so the
+ * previous page's origin is wiped through the page's own CDP session
+ * (Storage.clearDataForOrigin, as before) instead; otherwise a page's pixels
+ * could depend on which page was captured before it. Service workers
+ * are blocked at context creation, since clearing cannot stop one that has
+ * already intercepted the next navigation.
+ *
+ * The origin comes from the requested URL, not only the page: after a failed
+ * load the page is an error page with an opaque origin. The page's final URL
+ * is cleared too, for redirects. Covers IndexedDB, Cache Storage, service
+ * workers and local storage. Best effort: nothing here
+ * may fail a capture that already succeeded.
+ */
+async function resetBetweenPages(context, page, requestedUrl) {
+    await context.clearCookies().catch(() => { });
+    // A redirect lands on another origin (a login host, a canonical port) that
+    // holds state of its own.
+    const origins = new Set();
+    for (const u of [requestedUrl, page.url()]) {
+        try {
+            const o = new URL(u);
+            if (o.protocol === 'http:' || o.protocol === 'https:')
+                origins.add(o.origin);
+        }
+        catch {
+            // about:blank, chrome-error:// — no origin to clear.
+        }
+    }
+    for (const origin of origins)
+        await page.clearOrigin(origin).catch(() => { });
+}
+export async function snapPage(opts) {
+    const { env, pages } = await snapPages({
+        urls: [opts.url],
+        browser: opts.browser,
+        ...(opts.viewport ? { viewport: opts.viewport } : {}),
+        ...(opts.params ? { params: opts.params } : {}),
+    });
+    const [r] = pages;
+    if (!r.snapshot)
+        throw new Error(r.error ?? 'jux: could not capture');
+    return { snapshot: r.snapshot, env, status: r.status };
+}
+//# sourceMappingURL=snap.js.map

package/dist/capture/snap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snap.js","sourceRoot":"","sources":["../../src/capture/snap.ts"],"names":[],"mappings":"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"}

package/dist/capture/structure.d.ts

@@ -0,0 +1,77 @@
+import type { Page } from '../browser/page.js';
+import type { StructureSnapshot, Viewport } from '../types.js';
+/** Styles recorded per element. `display`/`visibility` are deliberately absent:
+ *  display:none elements have no layout entry at all, and visibility is read
+ *  only to filter (see `visibilityIdx` in normalizeStructure). */
+export declare const STRUCTURE_PROPS: readonly string[];
+/** Inherited properties are stored only where they differ from the parent. */
+export declare const INHERITED_PROPS: ReadonlySet<string>;
+/** Computed-style initial values for non-inherited properties. A value equal
+ *  to its initial value is not stored. Border colors are special-cased: they
+ *  default to currentColor, so they are stored only when that side's width is
+ *  non-zero. */
+export declare const INITIAL_VALUES: Readonly<Record<string, string>>;
+export declare const MASK_ATTR = "data-jux-masked";
+export declare const MAX_ELEMENTS = 5000;
+/** The subset of a CDP DOMSnapshot.captureSnapshot response we read. */
+export interface CdpSnapshot {
+    documents: Array<{
+        contentHeight?: number;
+        nodes: {
+            parentIndex: number[];
+            nodeType: number[];
+            nodeName: number[];
+            nodeValue: number[];
+            attributes: number[][];
+            /** Rare-string data: parallel arrays of node index → string index.
+             *  Verified on Chromium 151: pseudo-elements appear as element nodes
+             *  named `::before`/`::after` with pseudoType set; an <input>'s typed
+             *  value is in inputValue, not in an attribute. */
+            pseudoType?: {
+                index: number[];
+                value: number[];
+            };
+            inputValue?: {
+                index: number[];
+                value: number[];
+            };
+        };
+        layout: {
+            nodeIndex: number[];
+            styles: number[][];
+            bounds: number[][];
+            paintOrders?: number[];
+        };
+    }>;
+    strings: string[];
+}
+export declare const round: (n: number) => number;
+/**
+ * Turn a raw CDP snapshot into a StructureSnapshot.
+ *
+ * Only the top document is read: iframe content is a separate document and is
+ * represented by the <iframe> element's own rect. Open shadow content is part
+ * of the host document's node list and is included.
+ */
+export declare function normalizeStructure(raw: CdpSnapshot, viewport: Viewport): StructureSnapshot;
+/** The full value of `prop` for element `index`, reconstructing what the
+ *  compact storage omitted. */
+export declare function effectiveStyle(s: StructureSnapshot, index: number, prop: string): string;
+export declare function encodeStructure(s: StructureSnapshot): Buffer;
+export declare function decodeStructure(b: Buffer): StructureSnapshot;
+/**
+ * Snapshot the page's structure. Never throws: a missing structure costs the
+ * agent some explanation, a thrown error would cost the story its capture.
+ *
+ * Mask selectors are resolved with the same CSS-over-open-shadow-roots query
+ * the screenshot masks with; Playwright-only syntax is rejected in
+ * captureStory before anything runs. Matches get MASK_ATTR so the normalizer
+ * collapses their subtree. A plain document.querySelectorAll would miss
+ * matches inside shadow roots and leak masked content into the sidecar.
+ *
+ * Fail closed: if marking fails, or any match lost its mark by the time the
+ * snapshot returns (the page mutated in between), return undefined. Setting an
+ * attribute does not affect paint unless a stylesheet targets it, which
+ * nothing ships with.
+ */
+export declare function captureStructure(page: Page, viewport: Viewport, mask: readonly string[]): Promise<StructureSnapshot | undefined>;

package/dist/capture/structure.js

@@ -0,0 +1,498 @@
+// Structure snapshot: the visible DOM and its computed styles, captured in the
+// same frame as the screenshot.
+//
+// Why: pixels say WHERE something changed; this says WHAT — which element,
+// which property, old → new — so an agent can decide without reading an image
+// (spec: docs/specs/2026-10-12-sp0-structural-diff-agent-surface-design.md).
+// It explains a failure; it never decides one. The pixel hash still does.
+//
+// Everything here is a pure function of the CDP response so it can be tested
+// against real Chromium output committed as a fixture.
+import { createHash } from 'node:crypto';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { queryAllExpression } from '../browser/selectors.js';
+/** Styles recorded per element. `display`/`visibility` are deliberately absent:
+ *  display:none elements have no layout entry at all, and visibility is read
+ *  only to filter (see `visibilityIdx` in normalizeStructure). */
+export const STRUCTURE_PROPS = [
+    'color',
+    'background-color',
+    'background-image',
+    'font-family',
+    'font-size',
+    'font-weight',
+    'font-style',
+    'line-height',
+    'letter-spacing',
+    'text-align',
+    'text-decoration-line',
+    'text-transform',
+    'padding-top',
+    'padding-right',
+    'padding-bottom',
+    'padding-left',
+    'margin-top',
+    'margin-right',
+    'margin-bottom',
+    'margin-left',
+    'border-top-width',
+    'border-right-width',
+    'border-bottom-width',
+    'border-left-width',
+    'border-top-color',
+    'border-right-color',
+    'border-bottom-color',
+    'border-left-color',
+    'border-top-left-radius',
+    'border-top-right-radius',
+    'border-bottom-right-radius',
+    'border-bottom-left-radius',
+    'opacity',
+    'transform',
+    'box-shadow',
+    'gap',
+    'z-index',
+    // SVG paint is computed style, not an attribute: without these an icon
+    // recolour is unexplained pixels.
+    'fill',
+    'stroke',
+    'stroke-width',
+    // A pseudo-element's visible text lives here, not in a text node: without it
+    // a CSS icon swap (`content: "★"` → `"☆"`) is unexplained pixels.
+    'content',
+];
+/** Inherited properties are stored only where they differ from the parent. */
+export const INHERITED_PROPS = new Set([
+    'color',
+    'font-family',
+    'font-size',
+    'font-weight',
+    'font-style',
+    'line-height',
+    'letter-spacing',
+    'text-align',
+    'text-transform',
+    'fill',
+    'stroke',
+    'stroke-width',
+]);
+/** Computed-style initial values for non-inherited properties. A value equal
+ *  to its initial value is not stored. Border colors are special-cased: they
+ *  default to currentColor, so they are stored only when that side's width is
+ *  non-zero. */
+export const INITIAL_VALUES = {
+    'background-color': 'rgba(0, 0, 0, 0)',
+    'background-image': 'none',
+    'text-decoration-line': 'none',
+    'padding-top': '0px',
+    'padding-right': '0px',
+    'padding-bottom': '0px',
+    'padding-left': '0px',
+    'margin-top': '0px',
+    'margin-right': '0px',
+    'margin-bottom': '0px',
+    'margin-left': '0px',
+    'border-top-width': '0px',
+    'border-right-width': '0px',
+    'border-bottom-width': '0px',
+    'border-left-width': '0px',
+    'border-top-left-radius': '0px',
+    'border-top-right-radius': '0px',
+    'border-bottom-right-radius': '0px',
+    'border-bottom-left-radius': '0px',
+    opacity: '1',
+    transform: 'none',
+    'box-shadow': 'none',
+    gap: 'normal',
+    'z-index': 'auto',
+    content: 'normal',
+};
+/** Root defaults for inherited props when no kept ancestor exists. */
+const ROOT_INHERITED = {
+    color: 'rgb(0, 0, 0)',
+    'font-style': 'normal',
+    'font-weight': '400',
+    'letter-spacing': 'normal',
+    'text-align': 'start',
+    'text-transform': 'none',
+    // SVG paint defaults (CSS initial values, as Chromium computes them)
+    fill: 'rgb(0, 0, 0)',
+    stroke: 'none',
+    'stroke-width': '1px',
+};
+export const MASK_ATTR = 'data-jux-masked';
+export const MAX_ELEMENTS = 5000;
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const IMPLICIT_ROLES = {
+    button: 'button',
+    h1: 'heading',
+    h2: 'heading',
+    h3: 'heading',
+    h4: 'heading',
+    h5: 'heading',
+    h6: 'heading',
+    img: 'img',
+    select: 'combobox',
+    textarea: 'textbox',
+    nav: 'navigation',
+    main: 'main',
+    header: 'banner',
+    footer: 'contentinfo',
+    ul: 'list',
+    ol: 'list',
+    li: 'listitem',
+    table: 'table',
+    dialog: 'dialog',
+    iframe: 'document',
+};
+export const round = (n) => Math.round(n * 100) / 100;
+/**
+ * Turn a raw CDP snapshot into a StructureSnapshot.
+ *
+ * Only the top document is read: iframe content is a separate document and is
+ * represented by the <iframe> element's own rect. Open shadow content is part
+ * of the host document's node list and is included.
+ */
+export function normalizeStructure(raw, viewport) {
+    const doc = raw.documents[0];
+    const str = (i) => i === undefined || i < 0 ? undefined : raw.strings[i];
+    const { nodes, layout } = doc;
+    const styleIdx = STRUCTURE_PROPS.map((_, i) => i);
+    // `visibility` is requested after STRUCTURE_PROPS and used only to filter.
+    const visibilityIdx = STRUCTURE_PROPS.length;
+    // node index -> layout row. A node can have several rows (a pseudo-element
+    // gets one for its box and one per text fragment); the FIRST is the box.
+    const layoutOf = new Map();
+    layout.nodeIndex.forEach((n, row) => {
+        if (!layoutOf.has(n))
+            layoutOf.set(n, row);
+    });
+    const contentIdx = STRUCTURE_PROPS.indexOf('content');
+    const rare = (r) => {
+        const m = new Map();
+        r?.index.forEach((n, k) => m.set(n, str(r.value[k]) ?? ''));
+        return m;
+    };
+    const inputValue = rare(nodes.inputValue);
+    // children lists and own text, in document order
+    const children = new Map();
+    const ownText = new Map();
+    for (let i = 0; i < nodes.nodeType.length; i++) {
+        const p = nodes.parentIndex[i];
+        if (p < 0)
+            continue;
+        if (nodes.nodeType[i] === TEXT_NODE) {
+            const t = str(nodes.nodeValue[i]) ?? '';
+            ownText.set(p, (ownText.get(p) ?? '') + t);
+        }
+        else if (nodes.nodeType[i] === ELEMENT_NODE) {
+            const list = children.get(p) ?? [];
+            list.push(i);
+            children.set(p, list);
+        }
+    }
+    const attrs = (i) => {
+        const out = {};
+        const a = nodes.attributes[i] ?? [];
+        for (let k = 0; k + 1 < a.length; k += 2)
+            out[str(a[k])] = str(a[k + 1]) ?? '';
+        return out;
+    };
+    const elements = [];
+    let total = 0;
+    // effective inherited values per kept element, for compact storage
+    const effective = [];
+    const visit = (i, parentPath, keptParent) => {
+        const tag = (str(nodes.nodeName[i]) ?? '').toLowerCase();
+        if (tag === 'head' || tag === 'script' || tag === 'style')
+            return;
+        const a = attrs(i);
+        const siblings = children.get(nodes.parentIndex[i]) ?? [];
+        const sameTag = siblings.filter((s) => (str(nodes.nodeName[s]) ?? '').toLowerCase() === tag);
+        const step = a.id !== undefined
+            ? `${tag}#${a.id}`
+            : a['data-testid'] !== undefined
+                ? `${tag}[data-testid="${a['data-testid']}"]`
+                : `${tag}:nth-of-type(${sameTag.indexOf(i) + 1})`;
+        const path = parentPath ? `${parentPath}>${step}` : step;
+        const row = layoutOf.get(i);
+        // Mask first, before any check that can descend: a visibility:hidden mask
+        // target with a visibility:visible child used to take the hidden branch
+        // below and record the child's text, while the screenshot mask covered it.
+        if (a[MASK_ATTR] !== undefined) {
+            if (row === undefined)
+                return; // no box: nothing to stand in for
+            total++;
+            if (elements.length < MAX_ELEMENTS) {
+                const [x, y, w, h] = layout.bounds[row];
+                elements.push({
+                    path,
+                    parent: keptParent,
+                    tag: 'masked',
+                    rect: { x: round(x), y: round(y), w: round(w), h: round(h) },
+                    paintOrder: layout.paintOrders?.[row] ?? 0,
+                    styles: {},
+                });
+                effective.push(keptParent === null ? { ...ROOT_INHERITED } : effective[keptParent]);
+            }
+            return; // never descend into a masked subtree
+        }
+        if (row === undefined)
+            return; // display:none (or no box): drop the subtree
+        const values = layout.styles[row].map((s) => urlsToFileNames(str(s) ?? ''));
+        if (values[visibilityIdx] === 'hidden' || values[visibilityIdx] === 'collapse') {
+            // hidden boxes can still contain visible descendants (visibility: visible)
+            for (const c of children.get(i) ?? [])
+                visit(c, path, keptParent);
+            return;
+        }
+        const [x, y, w, h] = layout.bounds[row];
+        const rect = { x: round(x), y: round(y), w: round(w), h: round(h) };
+        const offscreen = rect.x + rect.w <= 0 ||
+            rect.y + rect.h <= 0 ||
+            rect.x >= viewport.width ||
+            rect.y >= viewport.height;
+        const empty = rect.w <= 0 || rect.h <= 0;
+        const keep = !offscreen && !empty && tag !== 'html' && tag !== 'body';
+        let me = keptParent;
+        if (keep) {
+            total++;
+            if (elements.length < MAX_ELEMENTS) {
+                const inherited = keptParent === null ? ROOT_INHERITED : effective[keptParent];
+                const styles = {};
+                const eff = { ...inherited };
+                for (const k of styleIdx) {
+                    const prop = STRUCTURE_PROPS[k];
+                    const v = values[k];
+                    if (INHERITED_PROPS.has(prop)) {
+                        eff[prop] = v;
+                        if (inherited[prop] !== v)
+                            styles[prop] = v;
+                    }
+                    else if (prop.startsWith('border-') && prop.endsWith('-color')) {
+                        const side = prop.split('-')[1];
+                        const width = values[STRUCTURE_PROPS.indexOf(`border-${side}-width`)];
+                        if (width !== '0px')
+                            styles[prop] = v;
+                    }
+                    else if (INITIAL_VALUES[prop] !== v) {
+                        styles[prop] = v;
+                    }
+                }
+                // `content` is meaningful only on a pseudo-element, where it IS the
+                // text; on a normal element it is always `normal`, so drop it there.
+                const isPseudo = tag.startsWith('::');
+                if (!isPseudo)
+                    delete styles.content;
+                const pseudoText = isPseudo ? parseContent(values[contentIdx]) : '';
+                // Sidecars are committed to git: never record a secret field's value.
+                const secret = tag === 'input' && isSecretInput(a);
+                const typed = secret ? undefined : inputValue.get(i);
+                const text = collapse(pseudoText || typed || ownText.get(i) || '');
+                const role = a.role ?? implicitRole(tag, a);
+                const name = (a['aria-label'] ?? a.alt ?? a.title ?? text) || undefined;
+                const el = {
+                    path,
+                    parent: keptParent,
+                    tag,
+                    rect,
+                    paintOrder: layout.paintOrders?.[row] ?? 0,
+                    styles,
+                };
+                if (a.id !== undefined)
+                    el.id = a.id;
+                if (a['data-testid'] !== undefined)
+                    el.testId = a['data-testid'];
+                const classes = (a.class ?? '').split(/\s+/).filter(Boolean);
+                if (classes.length)
+                    el.classes = classes;
+                if (role)
+                    el.role = role;
+                if (name)
+                    el.name = name.slice(0, 80);
+                if (text)
+                    el.text = text.slice(0, 200);
+                if (a.src !== undefined)
+                    el.src = fileName(a.src);
+                elements.push(el);
+                effective.push(eff);
+                me = elements.length - 1;
+            }
+        }
+        for (const c of children.get(i) ?? [])
+            visit(c, path, me);
+    };
+    // node 0 is #document; start from its element children (<html>)
+    for (const c of children.get(0) ?? [])
+        visit(c, '', null);
+    const snapshot = {
+        schema: 'juxtapose.structure/v1',
+        viewport,
+        structureHash: hashElements(elements),
+        contentHeight: round(doc.contentHeight ?? viewport.height),
+        elements,
+    };
+    if (total > elements.length)
+        snapshot.truncated = { kept: elements.length, total };
+    return snapshot;
+}
+/** Autofill tokens that name a secret: a typed OTP, password or card number
+ *  in a `type=text` field is as sensitive as one in `type=password`. */
+const SECRET_AUTOCOMPLETE = new Set([
+    'one-time-code',
+    'current-password',
+    'new-password',
+]);
+function isSecretInput(a) {
+    if (['password', 'hidden'].includes((a.type ?? '').toLowerCase()))
+        return true;
+    return (a.autocomplete ?? '')
+        .toLowerCase()
+        .split(/\s+/)
+        .some((t) => SECRET_AUTOCOMPLETE.has(t) || t.startsWith('cc-'));
+}
+function implicitRole(tag, a) {
+    if (tag === 'a')
+        return a.href !== undefined ? 'link' : undefined;
+    if (tag === 'input') {
+        const t = (a.type ?? 'text').toLowerCase();
+        return t === 'checkbox' || t === 'radio'
+            ? t
+            : t === 'button' || t === 'submit'
+                ? 'button'
+                : 'textbox';
+    }
+    return IMPLICIT_ROLES[tag];
+}
+/** The filename of a URL: no origin, path, query or hash. The origin changes
+ *  every run (`jux run` serves on port 0) and between machines, so recording
+ *  it would make the same page hash differently each time. */
+function fileName(u) {
+    // A data: URI's "filename" is a slice of its payload: opaque, and as long as
+    // the payload happens to be between slashes.
+    if (/^data:/i.test(u.trim()))
+        return 'data:';
+    return u.split(/[?#]/)[0].split('/').pop() ?? '';
+}
+/** Computed values serialize url() tokens absolute: probe2 recorded
+ *  `url("http://127.0.0.1:41001/bg.png")` vs `...:41002/bg.png` for one page
+ *  on two ports, and two different structureHashes. Keep only the filename. */
+function urlsToFileNames(v) {
+    if (!v.includes('url('))
+        return v;
+    return v.replace(/url\((?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|([^)]*))\)/g, (_m, dq, sq, bare) => `url(${JSON.stringify(fileName((dq ?? sq ?? bare ?? '').trim()))})`);
+}
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+/** Computed `content` is a CSS string like `"★"` (quoted), `none`, `normal`,
+ *  or something like `counter(x)`. Return the visible literal text when there
+ *  is one; otherwise the raw value, so a change is still detected. */
+function parseContent(v) {
+    if (!v || v === 'none' || v === 'normal')
+        return '';
+    const m = /^"(.*)"$/.exec(v);
+    return m ? m[1] : v;
+}
+/** The full value of `prop` for element `index`, reconstructing what the
+ *  compact storage omitted. */
+export function effectiveStyle(s, index, prop) {
+    const el = s.elements[index];
+    if (el.styles[prop] !== undefined)
+        return el.styles[prop];
+    if (INHERITED_PROPS.has(prop)) {
+        return el.parent === null
+            ? (ROOT_INHERITED[prop] ?? '')
+            : effectiveStyle(s, el.parent, prop);
+    }
+    if (prop.startsWith('border-') && prop.endsWith('-color')) {
+        return effectiveStyle(s, index, 'color'); // currentColor
+    }
+    return INITIAL_VALUES[prop] ?? '';
+}
+/** Canonical JSON: object keys sorted at every level, so hashing is stable. */
+function canonical(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(',')}]`;
+    if (v && typeof v === 'object') {
+        const o = v;
+        return `{${Object.keys(o)
+            .sort()
+            .filter((k) => o[k] !== undefined)
+            .map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(v);
+}
+function hashElements(elements) {
+    return createHash('sha256').update(canonical(elements)).digest('hex');
+}
+export function encodeStructure(s) {
+    return gzipSync(Buffer.from(JSON.stringify(s)));
+}
+export function decodeStructure(b) {
+    return JSON.parse(gunzipSync(b).toString('utf8'));
+}
+/**
+ * Snapshot the page's structure. Never throws: a missing structure costs the
+ * agent some explanation, a thrown error would cost the story its capture.
+ *
+ * Mask selectors are resolved with the same CSS-over-open-shadow-roots query
+ * the screenshot masks with; Playwright-only syntax is rejected in
+ * captureStory before anything runs. Matches get MASK_ATTR so the normalizer
+ * collapses their subtree. A plain document.querySelectorAll would miss
+ * matches inside shadow roots and leak masked content into the sidecar.
+ *
+ * Fail closed: if marking fails, or any match lost its mark by the time the
+ * snapshot returns (the page mutated in between), return undefined. Setting an
+ * attribute does not affect paint unless a stylesheet targets it, which
+ * nothing ships with.
+ */
+export async function captureStructure(page, viewport, mask) {
+    const mark = (sel) => page.evaluate(queryAllExpression(sel, "for (const el of els) el.setAttribute(a0, '1'); return els.length;", MASK_ATTR));
+    const verify = (sel) => page.evaluate(queryAllExpression(sel, 'return { total: els.length, marked: els.filter((e) => e.hasAttribute(a0)).length };', MASK_ATTR));
+    const unmark = () => page
+        .evaluate(queryAllExpression(`[${MASK_ATTR}]`, 'for (const el of els) el.removeAttribute(a0);', MASK_ATTR))
+        .catch(() => { });
+    // How many elements each selector marked. Verification re-resolves the
+    // selector, so an element that lost both its mark and its match would drop
+    // out of the re-resolved list and `every` would pass on the survivors
+    // (probe c: SECRET-C recorded). Comparing counts closes that.
+    const markedCounts = [];
+    try {
+        for (const sel of mask) {
+            const n = await mark(sel);
+            markedCounts.push(typeof n === 'number' ? n : 0);
+        }
+    }
+    catch {
+        if (mask.length)
+            await unmark();
+        return undefined;
+    }
+    try {
+        const raw = (await page.send('DOMSnapshot.captureSnapshot', {
+            computedStyles: [...STRUCTURE_PROPS, 'visibility'],
+            includeDOMRects: true,
+            includePaintOrder: true,
+        }));
+        for (const [k, sel] of mask.entries()) {
+            const v = (await verify(sel));
+            // Every current match still marked, and none of the marked ones gone.
+            const intact = typeof v === 'object' &&
+                v !== null &&
+                v.marked === v.total &&
+                v.marked >= markedCounts[k];
+            if (!intact)
+                return undefined;
+        }
+        return normalizeStructure(raw, viewport);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (mask.length)
+            await unmark();
+    }
+}
+//# sourceMappingURL=structure.js.map