deio-scroll 1.0.0

package/dist/editor/frameVideo.js

@@ -0,0 +1,181 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { probeVideoDurationMs, probeVideoFps, probeVideoSize } from "../transcode/probe.js";
+const PRESET_FILES = {
+    gray_noise_gradient: "gray_noise_gradient.png",
+    paper_blue: "paper_blue.png",
+    red_blocks_gradient: "red_blocks_gradient.png",
+};
+const CONTENT_SCALE = 0.84;
+export async function frameVideoOnBackground(options) {
+    const { inputPath, outputPath, preset, addShadow, roundedCorners = false, encode } = options;
+    const size = await probeVideoSize(inputPath);
+    if (!size)
+        throw new Error("Could not read video dimensions for background export");
+    const fps = (await probeVideoFps(inputPath)) ?? 30;
+    const durationMs = await probeVideoDurationMs(inputPath);
+    const width = even(size.width);
+    const height = even(size.height);
+    const contentWidth = even(Math.round(width * CONTENT_SCALE));
+    const contentHeight = even(Math.round(height * CONTENT_SCALE));
+    const x = Math.floor((width - contentWidth) / 2);
+    const y = Math.floor((height - contentHeight) / 2);
+    const cornerRadius = roundedCorners
+        ? Math.max(6, Math.round(Math.min(contentWidth, contentHeight) * 0.014))
+        : 0;
+    const backgroundPath = await resolvePresetPath(PRESET_FILES[preset]);
+    // Corners and shadows do not change from frame to frame. Building them once
+    // avoids running geq/gblur thousands of times on long recordings.
+    const staticLayers = await createStaticLayers({
+        outputPath,
+        width,
+        height,
+        contentWidth,
+        contentHeight,
+        x,
+        y,
+        cornerRadius,
+        addShadow,
+    });
+    try {
+        const filters = [
+            `[1:v]scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height},setsar=1[bg]`,
+            `[0:v]scale=${contentWidth}:${contentHeight}:flags=lanczos,setsar=1,format=rgba[card-base]`,
+        ];
+        const inputs = ["-y", "-i", inputPath, "-loop", "1", "-framerate", String(fps), "-i", backgroundPath];
+        let inputIndex = 2;
+        if (staticLayers.maskPath) {
+            inputs.push("-loop", "1", "-framerate", String(fps), "-i", staticLayers.maskPath);
+            filters.push(`[${inputIndex}:v]format=gray[mask]`, `[card-base][mask]alphamerge[card]`);
+            inputIndex += 1;
+        }
+        else {
+            filters.push("[card-base]copy[card]");
+        }
+        if (staticLayers.shadowPath) {
+            inputs.push("-loop", "1", "-framerate", String(fps), "-i", staticLayers.shadowPath);
+            filters.push(`[${inputIndex}:v]format=rgba[shadow]`, "[bg][shadow]overlay=0:0[canvas]", `[canvas][card]overlay=${x}:${y}:shortest=1,fps=${fps},format=yuv420p[output]`);
+        }
+        else {
+            filters.push(`[bg][card]overlay=${x}:${y}:shortest=1,fps=${fps},format=yuv420p[output]`);
+        }
+        await runFfmpeg([
+            ...inputs,
+            "-filter_complex",
+            filters.join(";"),
+            "-map",
+            "[output]",
+            "-an",
+            "-c:v",
+            "libx264",
+            "-preset",
+            encode.preset,
+            "-crf",
+            String(encode.crf),
+            "-pix_fmt",
+            "yuv420p",
+            ...(durationMs ? ["-t", (durationMs / 1000).toFixed(3)] : []),
+            "-shortest",
+            "-movflags",
+            "+faststart",
+            outputPath,
+        ]);
+    }
+    finally {
+        await Promise.all(staticLayers.files.map((file) => fs.unlink(file).catch(() => undefined)));
+    }
+}
+async function createStaticLayers(options) {
+    const { outputPath, width, height, contentWidth, contentHeight, x, y, cornerRadius, addShadow } = options;
+    if (!cornerRadius && !addShadow)
+        return { files: [], maskPath: undefined, shadowPath: undefined };
+    const id = randomUUID();
+    const dir = path.dirname(outputPath);
+    const maskPath = path.join(dir, `.style-mask-${id}.png`);
+    const shadowPath = addShadow ? path.join(dir, `.style-shadow-${id}.png`) : undefined;
+    const maskFilter = cornerRadius ? roundedMaskFilter(cornerRadius) : "format=gray";
+    await runFfmpeg([
+        "-y", "-f", "lavfi", "-i", `color=c=white:s=${contentWidth}x${contentHeight}:r=1`,
+        "-vf", maskFilter,
+        "-frames:v", "1", "-c:v", "png", maskPath,
+    ]);
+    if (shadowPath) {
+        // Soft bottom drop-shadow: mainly below the card so it reads on light and busy
+        // backgrounds. Slight X inset + wider blur keeps it natural without a hard halo.
+        const shadowOffsetY = Math.max(22, Math.round(height * 0.032));
+        const shadowY = y + shadowOffsetY;
+        const shadowBlur = Math.max(28, Math.round(Math.min(width, height) * 0.034));
+        const shadowAlpha = 0.38;
+        // Grow the shadow plate a touch so blur doesn't thin out at the sides.
+        const shadowPadX = Math.max(8, Math.round(contentWidth * 0.012));
+        const shadowW = even(contentWidth + shadowPadX * 2);
+        const shadowH = even(contentHeight + Math.round(shadowOffsetY * 0.35));
+        const shadowX = Math.max(0, x - shadowPadX);
+        await runFfmpeg([
+            "-y", "-i", maskPath,
+            "-f", "lavfi", "-i", `color=c=black:s=${contentWidth}x${contentHeight}:r=1`,
+            "-filter_complex",
+            // Soft plate → pad into full frame (offset down) → opacity → blur
+            `[0:v]format=gray,scale=${shadowW}:${shadowH}:flags=bilinear[mask];` +
+                `[1:v]format=rgba,scale=${shadowW}:${shadowH}:flags=bilinear[black];` +
+                `[black][mask]alphamerge,` +
+                `pad=${width}:${height}:${shadowX}:${shadowY}:color=black@0,` +
+                `format=rgba,colorchannelmixer=aa=${shadowAlpha},` +
+                `gblur=sigma=${shadowBlur}:steps=3[output]`,
+            "-map", "[output]", "-frames:v", "1", "-c:v", "png", shadowPath,
+        ]);
+    }
+    return {
+        files: shadowPath ? [maskPath, shadowPath] : [maskPath],
+        maskPath: cornerRadius ? maskPath : undefined,
+        shadowPath,
+    };
+}
+function roundedMaskFilter(radius) {
+    const right = `W-${radius}`;
+    const bottom = `H-${radius}`;
+    const outsideCorner = [
+        `lt(X,${radius})*lt(Y,${radius})*gt(hypot(X-${radius},Y-${radius}),${radius})`,
+        `gt(X,${right})*lt(Y,${radius})*gt(hypot(X-(${right}),Y-${radius}),${radius})`,
+        `lt(X,${radius})*gt(Y,${bottom})*gt(hypot(X-${radius},Y-(${bottom})),${radius})`,
+        `gt(X,${right})*gt(Y,${bottom})*gt(hypot(X-(${right}),Y-(${bottom})),${radius})`,
+    ].join("+");
+    return `format=gray,geq=lum='if(gt(${outsideCorner},0),0,255)'`;
+}
+async function resolvePresetPath(filename) {
+    const apiPublicDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../public/background_presets");
+    const builtPath = path.join(apiPublicDir, filename);
+    if (await exists(builtPath))
+        return builtPath;
+    // During Vite development, its public directory is the authoritative source.
+    const webPublicPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../web/public/background_presets", filename);
+    if (await exists(webPublicPath))
+        return webPublicPath;
+    throw new Error(`Background preset is unavailable: ${filename}`);
+}
+function even(value) {
+    return value % 2 === 0 ? value : value - 1;
+}
+async function exists(filePath) {
+    return fs.access(filePath).then(() => true).catch(() => false);
+}
+function runFfmpeg(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`Background render failed with code ${code}: ${stderr.slice(-2000)}`));
+        });
+    });
+}
+//# sourceMappingURL=frameVideo.js.map

package/dist/editor/frameVideo.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { recordWebsite } from './pipeline/recordWebsite.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,mBAAmB,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { recordWebsite } from './pipeline/recordWebsite.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA"}

package/dist/inspection/inspectWebsite.d.ts

@@ -0,0 +1,21 @@
+import type { WebsiteInspection, WebsiteSection } from "../types.js";
+export interface RawWebsiteSection {
+    label: string;
+    selector: string;
+    kind: "heading" | "landmark";
+    y: number;
+    height: number;
+    stable: number;
+}
+export declare function inspectWebsite(options: {
+    targetUrl: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}): Promise<WebsiteInspection>;
+export declare function normalizeInspectionSections(raw: RawWebsiteSection[], safeViewport: {
+    topInsetPx: number;
+    bottomInsetPx: number;
+}, viewportHeight: number, maxScroll: number): WebsiteSection[];
+//# sourceMappingURL=inspectWebsite.d.ts.map

package/dist/inspection/inspectWebsite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspectWebsite.d.ts","sourceRoot":"","sources":["../../src/inspection/inspectWebsite.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,iBAAiB,EAEjB,cAAc,EACf,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2E7B;AAwED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,iBAAiB,EAAE,EACxB,YAAY,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAC3D,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,GAChB,cAAc,EAAE,CAoFlB"}

package/dist/inspection/inspectWebsite.js

@@ -0,0 +1,412 @@
+import { chromium } from "playwright";
+import { gotoReachablePage } from "../browser/goto.js";
+export async function inspectWebsite(options) {
+    const target = assertHttpUrl(options.targetUrl);
+    const viewport = options.viewport ?? { width: 1280, height: 720 };
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage({ viewport });
+        await gotoReachablePage(page, target.href);
+        await page
+            .waitForLoadState("networkidle", { timeout: 10_000 })
+            .catch(() => undefined);
+        const pageHeight = await page.evaluate(() => Math.max(document.body.scrollHeight, document.documentElement.scrollHeight));
+        const scrollMode = await detectInspectionScrollMode(page, pageHeight, viewport.height);
+        const safeViewport = await detectInspectionSafeViewport(page, viewport);
+        const sections = normalizeInspectionSections(await collectSections(page), safeViewport, viewport.height, Math.max(0, pageHeight - viewport.height));
+        const interactions = scrollMode === "document"
+            ? await collectInteractionCandidates(page)
+            : [];
+        const { screenshots, storyboard } = scrollMode === "virtual"
+            ? await takeVirtualStoryboardScreenshots(page, viewport)
+            : await takeDocumentStoryboardScreenshots(page, pageHeight, viewport.height);
+        if (scrollMode === "document") {
+            await attachSectionPreviewScreenshots(page, sections, screenshots, viewport.height);
+        }
+        const warnings = [];
+        if (page.url() !== target.href)
+            warnings.push(`Redirected to ${page.url()}`);
+        if (pageHeight <= viewport.height + 48 && scrollMode === "document") {
+            warnings.push("This page has little or no scrollable content.");
+        }
+        if (scrollMode === "virtual") {
+            warnings.push("Virtual scrolling detected; direction uses storyboard progress points.");
+        }
+        if (safeViewport.topInsetPx > 0) {
+            warnings.push(`A ${safeViewport.topInsetPx}px fixed header will be kept clear.`);
+        }
+        if (scrollMode === "document" && sections.length === 0) {
+            warnings.push("No semantic sections were detected; storyboard waypoints will be used.");
+        }
+        return {
+            url: page.url(),
+            title: await page.title(),
+            pageHeight,
+            viewport,
+            scrollMode,
+            safeViewport,
+            sections,
+            interactions,
+            storyboard,
+            screenshots,
+            warnings,
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}
+async function collectInteractionCandidates(page) {
+    return page.evaluate(`(() => {
+    const blocked = /\\b(delete|remove|unsubscribe|sign out|log out|purchase|buy|pay|checkout|submit|send|publish|confirm|destroy|upload|download)\\b/i;
+    const pathFor = (element) => {
+      if (element.id) return "#" + CSS.escape(element.id);
+      for (const name of ["data-testid", "data-test", "data-qa"]) {
+        const value = element.getAttribute(name);
+        if (value) return "[" + name + "=\\"" + CSS.escape(value) + "\\"]";
+      }
+      const segments = [];
+      let current = element;
+      while (current && current !== document.body && segments.length < 5) {
+        const parent = current.parentElement;
+        const tag = current.tagName.toLowerCase();
+        const siblings = parent ? Array.from(parent.children).filter((child) => child.tagName === current.tagName) : [];
+        const suffix = siblings.length > 1 ? ":nth-of-type(" + (siblings.indexOf(current) + 1) + ")" : "";
+        segments.unshift(tag + suffix);
+        current = parent;
+      }
+      return "body > " + segments.join(" > ");
+    };
+    return Array.from(document.querySelectorAll("button,a[href],[role='button'],[role='tab'],[role='switch'],[role='menuitem'],[aria-expanded],summary,input:not([type='hidden'])"))
+      .flatMap((element, index) => {
+        const rect = element.getBoundingClientRect();
+        const style = getComputedStyle(element);
+        const label = (element.getAttribute("aria-label") || element.getAttribute("title") || element.textContent || element.value || "").replace(/\\s+/g, " ").trim().slice(0, 120);
+        if (!label || blocked.test(label) || rect.width < 28 || rect.height < 20 || style.display === "none" || style.visibility === "hidden" || Number(style.opacity) < 0.05 || element.hasAttribute("disabled") || element.getAttribute("aria-disabled") === "true") return [];
+        const tag = element.tagName.toLowerCase();
+        const role = element.getAttribute("role") || (tag === "a" ? "link" : tag);
+        const type = (element.getAttribute("type") || "").toLowerCase();
+        const semanticClick = ["tab", "switch", "menuitem", "option"].includes(role) || element.hasAttribute("aria-expanded") || tag === "summary" || (tag === "button" && type === "button") || (tag === "button" && !element.closest("form") && !type);
+        const focusable = element.tabIndex >= 0 || ["button", "a", "input", "summary"].includes(tag);
+        const actions = ["hover", ...(focusable ? ["focus"] : []), ...(semanticClick && tag !== "a" ? ["click"] : [])];
+        const selector = pathFor(element);
+        const id = "interaction_" + String(index + 1).padStart(2, "0");
+        const maxScroll = Math.max(0, document.documentElement.scrollHeight - innerHeight);
+        const progress = maxScroll === 0 ? 0 : Math.max(0, Math.min(1, (rect.top + scrollY - innerHeight / 2) / maxScroll));
+        const recommendedZoomScale = rect.width > innerWidth * 0.4 ? 1.12 : 1.28;
+        return [{
+          id,
+          selector,
+          label,
+          tag,
+          role,
+          actions,
+          rect: {
+            x: Math.round(rect.left + window.scrollX),
+            y: Math.round(rect.top + window.scrollY),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+          },
+          recommendedTarget: { type: "selector", selector, align: "center", fallbackProgress: progress },
+          recommendedHoldMs: semanticClick ? 1600 : 1300,
+          recommendedZoomScale,
+          recommendedInteraction: {
+            action: "hover",
+            candidateId: id,
+            label,
+            role,
+            zoomScale: recommendedZoomScale,
+            showCursor: true,
+          },
+        }];
+      })
+      .slice(0, 30);
+  })()`);
+}
+export function normalizeInspectionSections(raw, safeViewport, viewportHeight, maxScroll) {
+    const safeTop = safeViewport.topInsetPx + 24;
+    const safeBottom = viewportHeight - safeViewport.bottomInsetPx;
+    const headingLeadPx = Math.round((safeBottom - safeTop) * 0.14);
+    const scored = raw
+        .map((section) => ({
+        ...section,
+        score: (section.kind === "heading" ? 4 : 0) + section.stable * 2,
+        recommendedAlign: "top",
+        recommendedOffsetPx: section.kind === "heading" ? -headingLeadPx : 0,
+        targetY: Math.max(0, Math.min(maxScroll, section.kind === "heading"
+            ? section.y - safeTop - headingLeadPx
+            : section.y - safeTop)),
+    }))
+        .sort((a, b) => a.y - b.y || b.score - a.score);
+    const selected = [];
+    for (const section of scored) {
+        const nearby = selected.findIndex((candidate) => Math.abs(candidate.y - section.y) <= 160);
+        if (nearby < 0)
+            selected.push(section);
+        else {
+            const candidate = selected[nearby];
+            const sameVisualRow = candidate.kind === "heading"
+                && section.kind === "heading"
+                && Math.abs(candidate.y - section.y) <= 48;
+            const candidateLabel = candidate.label.toLowerCase();
+            const sectionLabel = section.label.toLowerCase();
+            const distinctLabels = candidateLabel !== sectionLabel
+                && !candidateLabel.includes(sectionLabel)
+                && !sectionLabel.includes(candidateLabel);
+            if (sameVisualRow && distinctLabels) {
+                candidate.label = `${candidate.label} · ${section.label}`.slice(0, 120);
+            }
+            else if (section.score > candidate.score) {
+                selected[nearby] = section;
+            }
+        }
+    }
+    let previousTarget = 0;
+    return selected
+        .sort((a, b) => a.y - b.y)
+        .slice(0, 30)
+        .map((section) => {
+        const distanceFromPrevious = Math.max(0, section.targetY - previousTarget);
+        previousTarget = section.targetY;
+        const recommendedTransitionMs = Math.max(600, Math.ceil((((distanceFromPrevious * 1.9) /
+            Math.max(1, viewportHeight * 1.5)) *
+            1000) /
+            50) * 50);
+        return {
+            label: section.label,
+            selector: section.selector,
+            kind: section.kind,
+            y: section.y,
+            height: section.height,
+            targetY: section.targetY,
+            progress: maxScroll === 0 ? 0 : section.targetY / maxScroll,
+            distanceFromPrevious,
+            recommendedTransitionMs,
+            recommendedTarget: {
+                type: "selector",
+                selector: section.selector,
+                align: section.recommendedAlign,
+                ...(section.recommendedOffsetPx
+                    ? { offsetPx: section.recommendedOffsetPx }
+                    : {}),
+            },
+        };
+    });
+}
+async function collectSections(page) {
+    return page.evaluate(`(() => {
+    const pathFor = (element) => {
+      if (element.id) return "#" + CSS.escape(element.id);
+      const framerName = element.getAttribute("data-framer-name");
+      if (framerName) {
+        const namedSelector = "[data-framer-name=\\"" + CSS.escape(framerName) + "\\"]";
+        if (document.querySelectorAll(namedSelector).length === 1) return namedSelector;
+      }
+      const segments = [];
+      let current = element;
+      while (current && current !== document.body && segments.length < 12) {
+        const parent = current.parentElement;
+        const tag = current.tagName.toLowerCase();
+        const index = parent ? Array.from(parent.children).filter((child) => child.tagName === current.tagName).indexOf(current) + 1 : 1;
+        segments.unshift(tag + ":nth-of-type(" + index + ")");
+        current = parent;
+      }
+      return current === document.body
+        ? "body > " + segments.join(" > ")
+        : "body " + segments.join(" > ");
+    };
+    const genericFramerNames = new Set([
+      "app", "background", "bg", "border", "bottom", "container", "content",
+      "default", "desktop", "footer", "header", "interface", "layout", "left",
+      "main", "mobile", "new layout", "right", "section", "shade", "tablet",
+      "top", "ui", "visual", "wrapper",
+    ]);
+    const semantic = Array.from(document.querySelectorAll("h1,h2,h3,main,section,article,footer,[role='main'],[role='region']"))
+      // A footer inside main/section/article is commonly part of a UI mockup
+      // or card. Treat only page-level footers as navigation landmarks.
+      .filter((element) => element.tagName.toLowerCase() !== "footer" || !element.closest("main,section,article"))
+      .map((element) => {
+        const tag = element.tagName.toLowerCase();
+        const heading = /^h[1-3]$/.test(tag) ? element : element.querySelector("h1,h2,h3");
+        const focus = heading || element;
+        const rect = focus.getBoundingClientRect();
+        const framerName = element.getAttribute("data-framer-name") || "";
+        const namedLabel = genericFramerNames.has(framerName.toLowerCase()) ? "" : framerName;
+        const text = (
+          element.getAttribute("aria-label")
+          || heading?.innerText
+          || heading?.textContent
+          || namedLabel
+          || (tag === "footer" ? "Footer" : element.innerText || element.textContent)
+          || ""
+        ).replace(/\\s+/g, " ").trim();
+        return { label: text.slice(0, 120) || tag, selector: pathFor(focus), kind: heading ? "heading" : "landmark", y: Math.max(0, Math.round(rect.top + window.scrollY)), height: Math.max(1, Math.round(rect.height)), stable: focus.id ? 1 : 0, visible: rect.width > 0 && rect.height > 0 };
+      })
+      .filter((section) => section.visible && section.label.length > 0 && Number.isFinite(section.y));
+    const namedBands = Array.from(document.querySelectorAll("main [data-framer-name]"))
+      .flatMap((element) => {
+        const name = (element.getAttribute("data-framer-name") || "").replace(/\\s+/g, " ").trim();
+        const normalizedName = name.toLowerCase();
+        if (
+          name.length < 3
+          || name.length > 60
+          || genericFramerNames.has(normalizedName)
+          || element.querySelector("h1,h2,h3")
+        ) return [];
+        const main = element.closest("main");
+        let depth = 0;
+        let current = element;
+        while (current && current !== main) {
+          depth += 1;
+          current = current.parentElement;
+        }
+        const rect = element.getBoundingClientRect();
+        const style = getComputedStyle(element);
+        const visible =
+          rect.width >= innerWidth * 0.65
+          && rect.height >= Math.max(280, innerHeight * 0.34)
+          && style.display !== "none"
+          && style.visibility !== "hidden"
+          && Number(style.opacity || 1) > 0
+          && style.position !== "fixed"
+          && style.position !== "sticky";
+        if (!main || depth > 2 || !visible) return [];
+        return [{
+          label: name,
+          selector: pathFor(element),
+          kind: "landmark",
+          y: Math.max(0, Math.round(rect.top + window.scrollY)),
+          height: Math.max(1, Math.round(rect.height)),
+          stable: element.id || document.querySelectorAll("[data-framer-name=\\"" + CSS.escape(name) + "\\"]").length === 1 ? 1 : 0,
+          visible: true,
+        }];
+      });
+    return [...semantic, ...namedBands];
+  })()`);
+}
+async function detectInspectionSafeViewport(page, viewport) {
+    const topInsetPx = await page.evaluate(`(() => Array.from(document.querySelectorAll("body *")).reduce((inset, element) => {
+    const style = getComputedStyle(element); const rect = element.getBoundingClientRect();
+    const pinned = style.position === "fixed" || style.position === "sticky";
+    const visible = style.display !== "none" && style.visibility !== "hidden" && Number(style.opacity || 1) > 0;
+    const topBar = rect.top <= 8 && rect.bottom > 0 && rect.width >= ${viewport.width} * 0.5 && rect.height >= 24 && rect.height <= ${viewport.height} * 0.3;
+    return pinned && visible && topBar ? Math.max(inset, Math.round(rect.bottom)) : inset;
+  }, 0))()`);
+    return { topInsetPx, bottomInsetPx: 24 };
+}
+async function takeDocumentStoryboardScreenshots(page, pageHeight, viewportHeight) {
+    const maxScroll = Math.max(0, pageHeight - viewportHeight);
+    const positions = [
+        ...new Set([
+            0,
+            Math.round(maxScroll / 3),
+            Math.round((maxScroll * 2) / 3),
+            maxScroll,
+        ]),
+    ];
+    const screenshots = [];
+    const storyboard = [];
+    for (const position of positions) {
+        await page.evaluate(`window.scrollTo(0, ${position})`);
+        await page.waitForTimeout(250);
+        screenshots.push((await page.screenshot({ type: "jpeg", quality: 60 })).toString("base64"));
+        storyboard.push({
+            imageIndex: screenshots.length - 1,
+            target: { type: "progress", value: maxScroll === 0 ? 0 : position / maxScroll },
+            y: position,
+        });
+    }
+    return { screenshots, storyboard };
+}
+async function attachSectionPreviewScreenshots(page, sections, screenshots, viewportHeight) {
+    if (sections.length === 0)
+        return;
+    const allPreviewPositions = [];
+    const minimumSpacing = Math.max(180, viewportHeight * 0.28);
+    for (const section of sections) {
+        const nearby = allPreviewPositions.findIndex((position) => Math.abs(position - section.targetY) < minimumSpacing);
+        if (nearby < 0) {
+            allPreviewPositions.push(section.targetY);
+        }
+    }
+    allPreviewPositions.sort((a, b) => a - b);
+    const maximumPreviewCount = 16;
+    const previewPositions = allPreviewPositions.length <= maximumPreviewCount
+        ? allPreviewPositions
+        : [...new Set(Array.from({ length: maximumPreviewCount }, (_, index) => allPreviewPositions[Math.round((index * (allPreviewPositions.length - 1)) / (maximumPreviewCount - 1))]))];
+    const indexes = new Map();
+    for (const position of previewPositions) {
+        await page.evaluate(`window.scrollTo({ top: ${Math.round(position)}, left: 0, behavior: "instant" })`);
+        await page.waitForTimeout(120);
+        screenshots.push((await page.screenshot({ type: "jpeg", quality: 68 })).toString("base64"));
+        indexes.set(position, screenshots.length - 1);
+    }
+    for (const section of sections) {
+        const closest = previewPositions.reduce((best, position) => {
+            if (best === undefined)
+                return position;
+            return Math.abs(position - section.targetY) < Math.abs(best - section.targetY)
+                ? position
+                : best;
+        }, undefined);
+        if (closest !== undefined)
+            section.imageIndex = indexes.get(closest);
+    }
+}
+async function takeVirtualStoryboardScreenshots(page, viewport) {
+    const progressPoints = [0, 0.25, 0.5, 0.75, 1];
+    const wheelBudget = viewport.height * 8;
+    const centerX = Math.floor(viewport.width / 2);
+    const centerY = Math.floor(viewport.height / 2);
+    const cdp = await page.context().newCDPSession(page);
+    const screenshots = [];
+    const storyboard = [];
+    let dispatched = 0;
+    try {
+        await page.mouse.move(centerX, centerY);
+        await page.mouse.click(centerX, centerY);
+        for (const value of progressPoints) {
+            const target = value * wheelBudget;
+            if (target > dispatched) {
+                const delta = (target - dispatched) / 20;
+                for (let tick = 0; tick < 20; tick += 1) {
+                    await cdp.send("Input.dispatchMouseEvent", {
+                        type: "mouseWheel",
+                        x: centerX,
+                        y: centerY,
+                        deltaX: 0,
+                        deltaY: delta,
+                    });
+                    await page.waitForTimeout(16);
+                }
+                dispatched = target;
+                await page.waitForTimeout(250);
+            }
+            screenshots.push((await page.screenshot({ type: "jpeg", quality: 60 })).toString("base64"));
+            storyboard.push({ imageIndex: screenshots.length - 1, target: { type: "progress", value } });
+        }
+    }
+    finally {
+        await cdp.detach().catch(() => undefined);
+    }
+    return { screenshots, storyboard };
+}
+async function detectInspectionScrollMode(page, pageHeight, viewportHeight) {
+    if (pageHeight - viewportHeight > 48)
+        return "document";
+    const virtual = await page.evaluate(`(() => {
+    const body = getComputedStyle(document.body); const html = getComputedStyle(document.documentElement);
+    const locked = body.overflow === "hidden" || body.overflowY === "hidden" || html.overflow === "hidden" || html.overflowY === "hidden";
+    const fixedShell = Array.from(document.querySelectorAll("body *")).some((element) => { const style = getComputedStyle(element); const rect = element.getBoundingClientRect(); return (style.position === "fixed" || style.position === "sticky") && rect.height >= innerHeight * 0.85 && rect.width >= innerWidth * 0.85; });
+    return locked || fixedShell || document.querySelectorAll("canvas").length >= 3;
+  })()`);
+    return virtual ? "virtual" : "document";
+}
+function assertHttpUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("Only HTTP(S) URLs are supported");
+    }
+    return url;
+}
+//# sourceMappingURL=inspectWebsite.js.map