deio-scroll 1.0.0

package/dist/browser/networkPolicy.js

@@ -0,0 +1,119 @@
+import dns from "node:dns/promises";
+import net from "node:net";
+const guardedPages = new WeakSet();
+const resolutionCache = new Map();
+export function targetNetworkPolicyFromEnv() {
+    return {
+        // Localhost capture is a core local-development feature. Disable this in SaaS.
+        allowLocalhost: process.env.ALLOW_LOCALHOST_TARGETS !== "0",
+        allowPrivateNetworks: process.env.ALLOW_PRIVATE_TARGETS === "1",
+    };
+}
+export async function installNetworkGuard(page, policy = targetNetworkPolicyFromEnv()) {
+    if (guardedPages.has(page))
+        return;
+    guardedPages.add(page);
+    await page.route("**/*", async (route) => {
+        try {
+            await assertSafeTargetUrl(route.request().url(), policy);
+            await route.continue();
+        }
+        catch (error) {
+            await abortBlockedRoute(route, error);
+        }
+    });
+}
+export async function assertSafeTargetUrl(value, policy = targetNetworkPolicyFromEnv()) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("Only HTTP(S) URLs are supported");
+    }
+    if (url.username || url.password) {
+        throw new Error("Target URLs cannot contain credentials");
+    }
+    const hostname = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (isCloudMetadataHostname(hostname)) {
+        throw new Error("Cloud metadata targets are blocked");
+    }
+    const addresses = await resolveAddresses(hostname);
+    if (addresses.length === 0)
+        throw new Error(`Could not resolve target host: ${hostname}`);
+    for (const address of addresses)
+        assertAddressAllowed(address, hostname, policy);
+    return url;
+}
+export function assertAddressAllowed(address, hostname, policy) {
+    const normalized = normalizeMappedIpv4(address);
+    if (isCloudMetadataAddress(normalized)) {
+        throw new Error("Cloud metadata targets are blocked");
+    }
+    const category = addressCategory(normalized);
+    if (category === "public")
+        return;
+    if (category === "loopback" && policy.allowLocalhost && isLocalHostname(hostname, normalized)) {
+        return;
+    }
+    if (category === "private" && policy.allowPrivateNetworks)
+        return;
+    throw new Error(`Target resolves to a blocked ${category} address (${normalized})`);
+}
+export function addressCategory(address) {
+    const version = net.isIP(address);
+    if (version === 4) {
+        const [a, b] = address.split(".").map(Number);
+        if (a === 127)
+            return "loopback";
+        if (a === 0 ||
+            a === 10 ||
+            (a === 100 && b >= 64 && b <= 127) ||
+            (a === 169 && b === 254) ||
+            (a === 172 && b >= 16 && b <= 31) ||
+            (a === 192 && b === 168) ||
+            (a === 198 && (b === 18 || b === 19)) ||
+            a >= 224)
+            return "private";
+        return "public";
+    }
+    if (version === 6) {
+        const lower = address.toLowerCase();
+        if (lower === "::" || lower === "::1")
+            return "loopback";
+        if (/^(fc|fd)/.test(lower) || /^fe[89ab]/.test(lower) || lower.startsWith("ff")) {
+            return "private";
+        }
+        return "public";
+    }
+    throw new Error(`Invalid resolved IP address: ${address}`);
+}
+async function resolveAddresses(hostname) {
+    if (net.isIP(hostname))
+        return [hostname];
+    const cached = resolutionCache.get(hostname);
+    if (cached && cached.expiresAt > Date.now())
+        return cached.addresses;
+    const resolved = await dns.lookup(hostname, { all: true, verbatim: true });
+    const addresses = [...new Set(resolved.map((item) => item.address))];
+    resolutionCache.set(hostname, { expiresAt: Date.now() + 30_000, addresses });
+    return addresses;
+}
+function isLocalHostname(hostname, address) {
+    return (hostname === "localhost" ||
+        hostname.endsWith(".localhost") ||
+        hostname === address ||
+        hostname === `[${address}]`);
+}
+function isCloudMetadataHostname(hostname) {
+    return hostname === "metadata.google.internal" || hostname.endsWith(".metadata.google.internal");
+}
+function isCloudMetadataAddress(address) {
+    return address === "169.254.169.254" || address.toLowerCase() === "fd00:ec2::254";
+}
+function normalizeMappedIpv4(address) {
+    const match = address.toLowerCase().match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    return match?.[1] ?? address;
+}
+async function abortBlockedRoute(route, error) {
+    console.warn(`Blocked browser request to ${route.request().url()}: ${error instanceof Error ? error.message : "network policy violation"}`);
+    await route.abort("blockedbyclient");
+}
+//# sourceMappingURL=networkPolicy.js.map

package/dist/browser/networkPolicy.js.map

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

package/dist/browser/prime.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from 'playwright';
+export declare function primeLazyAssets(page: Page): Promise<void>;
+//# sourceMappingURL=prime.d.ts.map

package/dist/browser/prime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prime.d.ts","sourceRoot":"","sources":["../../src/browser/prime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,iBAgB/C"}

package/dist/browser/prime.js

@@ -0,0 +1,13 @@
+export async function primeLazyAssets(page) {
+    await page.evaluate(async () => {
+        const lazyImages = document.querySelectorAll('img[loading="lazy"], img[data-src], img[data-lazy-src], img[data-original]');
+        for (const img of lazyImages) {
+            img.loading = 'eager';
+            const lazySrc = img.dataset.src ?? img.dataset.lazySrc ?? img.dataset.original;
+            if (lazySrc)
+                img.src = lazySrc;
+        }
+        await Promise.all(Array.from(document.images).map((img) => img.decode().catch(() => undefined)));
+    });
+}
+//# sourceMappingURL=prime.js.map

package/dist/browser/prime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prime.js","sourceRoot":"","sources":["../../src/browser/prime.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAU;IAC9C,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE;QAC7B,MAAM,UAAU,GAAG,QAAQ,CAAC,gBAAgB,CAC1C,4EAA4E,CAC7E,CAAA;QAED,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,GAAG,CAAC,OAAO,GAAG,OAAO,CAAA;YACrB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAA;YAC9E,IAAI,OAAO;gBAAE,GAAG,CAAC,GAAG,GAAG,OAAO,CAAA;QAChC,CAAC;QAED,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAC9E,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/browser/sanitize.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from "playwright";
+export declare function sanitizeDom(page: Page, removeOverlayElements: boolean): Promise<void>;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/browser/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/browser/sanitize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAYvC,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,iBA6B3E"}

package/dist/browser/sanitize.js

@@ -0,0 +1,37 @@
+const OVERLAY_SELECTORS = [
+    '[id*="cookie"]',
+    '[class*="cookie"]',
+    '[id*="consent"]',
+    '[class*="consent"]',
+    ".newsletter-popup",
+    '[class*="popup"]',
+    '[aria-modal="true"]',
+];
+export async function sanitizeDom(page, removeOverlayElements) {
+    await page.evaluate(({ selectors, remove }) => {
+        const style = document.createElement("style");
+        style.innerHTML = `
+      ::-webkit-scrollbar { display: none !important; width: 0 !important; height: 0 !important; }
+      html, body {
+        scroll-behavior: auto !important;
+        scrollbar-width: none !important;
+        overflow: hidden !important;
+        margin: 0 !important;
+        padding: 0 !important;
+        width: 100% !important;
+        min-height: 100% !important;
+      }
+    `;
+        document.head.appendChild(style);
+        if (!remove)
+            return;
+        for (const selector of selectors) {
+            document.querySelectorAll(selector).forEach((el) => {
+                if (el === document.documentElement || el === document.body)
+                    return;
+                el.remove();
+            });
+        }
+    }, { selectors: OVERLAY_SELECTORS, remove: removeOverlayElements });
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/browser/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../src/browser/sanitize.ts"],"names":[],"mappings":"AAEA,MAAM,iBAAiB,GAAG;IACxB,gBAAgB;IAChB,mBAAmB;IACnB,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,kBAAkB;IAClB,qBAAqB;CACtB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAU,EAAE,qBAA8B;IAC1E,MAAM,IAAI,CAAC,QAAQ,CACjB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC9C,KAAK,CAAC,SAAS,GAAG;;;;;;;;;;;KAWnB,CAAC;QACA,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAEjC,IAAI,CAAC,MAAM;YAAE,OAAO;QAEpB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;gBACjD,IAAI,EAAE,KAAK,QAAQ,CAAC,eAAe,IAAI,EAAE,KAAK,QAAQ,CAAC,IAAI;oBAAE,OAAO;gBACpE,EAAE,CAAC,MAAM,EAAE,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,EACD,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAChE,CAAC;AACJ,CAAC"}

package/dist/browser/scroll.d.ts

@@ -0,0 +1,29 @@
+import type { Page } from "playwright";
+import type { FrameRecorder } from "../capture/frameRecorder.js";
+import type { AnimationConfig, PauseTrigger, ResolvedMotionPlan, ScrollMode } from "../types.js";
+import type { BezierControlPoints } from "./curves.js";
+export interface RunScrollOptions {
+    pixelsPerFrame: number;
+    pauseTriggers: PauseTrigger[];
+    bezier: BezierControlPoints;
+    scrollMode?: ScrollMode;
+    animationConfig?: AnimationConfig;
+    viewportWidth: number;
+    viewportHeight: number;
+    fastMode?: boolean;
+    frameRecorder?: FrameRecorder;
+    signal?: AbortSignal;
+    onProgress?: (completedFrames: number, totalFrames: number) => void | Promise<void>;
+}
+export interface RunScrollResult {
+    scrollStrategy: "document" | "virtual";
+    maxScroll: number;
+    frames?: Array<{
+        file: string;
+        y?: number;
+        progress?: number;
+    }>;
+    motionPlan: ResolvedMotionPlan;
+}
+export declare function runScroll(page: Page, options: RunScrollOptions): Promise<RunScrollResult>;
+//# sourceMappingURL=scroll.d.ts.map

package/dist/browser/scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../src/browser/scroll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,KAAK,EACV,eAAe,EAGf,YAAY,EAEZ,kBAAkB,EAElB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAmBvD,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,UAAU,GAAG,SAAS,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAQ1B"}

package/dist/browser/scroll.js

@@ -0,0 +1,420 @@
+import { resolveVirtualScrollSettings } from "../config/virtualScroll.js";
+import { DEFAULT_DIRECTED_START_HOLD_MS } from "../types.js";
+import { resolveScrollCurve } from "./curves.js";
+import { detectScrollMode } from "./detectScrollMode.js";
+import { buildMotionTimeline } from "./motion.js";
+import { runVirtualTimeline } from "./virtualScroll.js";
+import { alignedDocumentPosition, collectSemanticAnchors, detectSafeViewport, nearestSemanticAnchor, resolvePauseFraming, } from "./composition.js";
+import { normalizeResolvedBeats } from "./directionGuardrails.js";
+import { ComponentInteractionAnimator } from "./componentInteraction.js";
+const DEFAULT_BEAT_CURVE = { preset: "ease-in-out-cubic" };
+export async function runScroll(page, options) {
+    const mode = await detectScrollMode(page, options.scrollMode ?? "auto");
+    await settleCaptureAtTop(page);
+    if (mode === "virtual") {
+        return runDirectedVirtualScroll(page, options);
+    }
+    return runDirectedDocumentScroll(page, options);
+}
+async function runDirectedDocumentScroll(page, options) {
+    const maxScroll = await page.evaluate(() => Math.max(0, document.documentElement.scrollHeight - window.innerHeight));
+    const direction = options.animationConfig?.direction;
+    const startHoldMs = direction
+        ? direction.startHoldMs ?? DEFAULT_DIRECTED_START_HOLD_MS
+        : options.animationConfig?.heroHoldMs ?? 0;
+    const safeViewport = await detectSafeViewport(page, options.viewportWidth, options.viewportHeight);
+    const anchors = direction
+        ? await collectSemanticAnchors(page, safeViewport, options.viewportHeight, maxScroll)
+        : [];
+    const resolved = direction
+        ? await resolveDirectedDocumentBeats(page, direction.beats, maxScroll, options.viewportHeight, safeViewport, anchors, startHoldMs)
+        : await resolveLegacyDocumentBeats(page, options, maxScroll, safeViewport);
+    const fps = options.frameRecorder?.getFps() ?? 30;
+    const samples = buildMotionTimeline({
+        fps,
+        startHoldMs,
+        beats: resolved.timeline,
+    });
+    const frames = [];
+    let lastY = -1;
+    const interactionAnimator = new ComponentInteractionAnimator(page);
+    for (const [index, sample] of samples.entries()) {
+        options.signal?.throwIfAborted();
+        const y = Math.max(0, Math.min(maxScroll, Math.round(sample.position)));
+        if (y !== lastY) {
+            await settleScrollPaint(page, y);
+            lastY = y;
+        }
+        const activeBeat = sample.beatIndex >= 0 ? resolved.beats[sample.beatIndex] : undefined;
+        if (sample.phase === "hold"
+            && activeBeat?.interaction
+            && activeBeat.target.type === "selector") {
+            await interactionAnimator.render({
+                beatIndex: sample.beatIndex,
+                selector: activeBeat.target.selector,
+                interaction: activeBeat.interaction,
+                progress: sample.phaseProgress ?? 0,
+            });
+        }
+        else {
+            await interactionAnimator.reset();
+        }
+        if (options.frameRecorder) {
+            const frameNumber = options.frameRecorder.getFrameCount();
+            await options.frameRecorder.writeFrame(page);
+            frames.push({
+                file: `frame-${String(frameNumber).padStart(6, "0")}.jpg`,
+                y,
+            });
+        }
+        else {
+            await page.waitForTimeout(1000 / fps);
+        }
+        await options.onProgress?.(index + 1, samples.length);
+    }
+    const durationMs = Math.round((samples.length / fps) * 1000);
+    await interactionAnimator.reset();
+    return {
+        scrollStrategy: "document",
+        maxScroll,
+        frames: options.frameRecorder ? frames : undefined,
+        motionPlan: {
+            mode: "document",
+            startHoldMs,
+            durationMs,
+            beats: resolved.beats,
+            adjustments: resolved.adjustments,
+        },
+    };
+}
+async function runDirectedVirtualScroll(page, options) {
+    const virtual = resolveVirtualScrollSettings(options.animationConfig ?? {}, options.viewportHeight, options.pixelsPerFrame, options.fastMode ?? false);
+    const direction = options.animationConfig?.direction;
+    if (!direction && (options.pauseTriggers?.length ?? 0) > 0) {
+        throw new Error("Selector pause triggers are not supported on virtual-scroll pages. Inspect the page and use direction beats with progress targets.");
+    }
+    const startHoldMs = direction?.startHoldMs
+        ?? (direction ? DEFAULT_DIRECTED_START_HOLD_MS : options.animationConfig?.heroHoldMs ?? 0);
+    const resolved = direction
+        ? resolveDirectedVirtualBeats(direction.beats, startHoldMs, options.viewportHeight, virtual.wheelBudget)
+        : resolveLegacyVirtualBeats(virtual.durationMs, options.bezier);
+    const fps = options.frameRecorder?.getFps() ?? 30;
+    const samples = buildMotionTimeline({
+        fps,
+        startHoldMs,
+        beats: resolved.timeline,
+    });
+    const frames = await runVirtualTimeline(page, {
+        viewportWidth: options.viewportWidth,
+        viewportHeight: options.viewportHeight,
+        wheelBudget: virtual.wheelBudget,
+        samples,
+        frameRecorder: options.frameRecorder,
+        signal: options.signal,
+        onProgress: options.onProgress,
+    });
+    const durationMs = Math.round((samples.length / fps) * 1000);
+    return {
+        scrollStrategy: "virtual",
+        maxScroll: 0,
+        frames: options.frameRecorder ? frames : undefined,
+        motionPlan: {
+            mode: "virtual",
+            startHoldMs,
+            durationMs,
+            beats: resolved.beats,
+            adjustments: resolved.adjustments,
+        },
+    };
+}
+async function resolveDirectedDocumentBeats(page, beats, maxScroll, viewportHeight, safeViewport, anchors, startHoldMs) {
+    if (beats.length === 0)
+        throw new Error("direction.beats must contain at least one beat");
+    const resolved = [];
+    const adjustments = [];
+    for (const [beatIndex, beat] of beats.entries()) {
+        validateBeat(beat);
+        let target = beat.target;
+        let position = await resolveDocumentTarget(page, target, maxScroll, viewportHeight, safeViewport);
+        if (target.type === "progress" && (beat.holdMs ?? 0) > 0) {
+            const nearest = nearestSemanticAnchor(anchors, position, viewportHeight);
+            if (nearest) {
+                const requested = target;
+                target = { type: "selector", selector: nearest.selector, align: nearest.recommendedAlign };
+                position = nearest.position;
+                adjustments.push({
+                    beatIndex,
+                    code: "promoted-progress-target",
+                    message: `Promoted a held progress target to the nearby “${nearest.label}” section`,
+                    requested,
+                    resolved: target,
+                });
+            }
+        }
+        const curve = beat.curve ?? DEFAULT_BEAT_CURVE;
+        resolved.push({
+            target,
+            position,
+            transitionMs: beat.transitionMs,
+            holdMs: beat.holdMs ?? 0,
+            curve,
+            interaction: beat.interaction,
+        });
+    }
+    await applyHeldBeatFraming(page, resolved, adjustments, safeViewport, viewportHeight, maxScroll);
+    const normalized = normalizeResolvedBeats({
+        beats: resolved,
+        startHoldMs,
+        viewportHeight,
+        adjustments,
+    });
+    normalized.beats.forEach((beat, index) => {
+        if (index > 0 && beat.position + 1 < normalized.beats[index - 1].position) {
+            throw new Error(`Direction target ${describeTarget(beat.target)} resolves behind the previous beat`);
+        }
+    });
+    return {
+        ...normalized,
+        timeline: normalized.beats.map((beat) => ({
+            position: beat.position,
+            transitionMs: beat.transitionMs,
+            holdMs: beat.holdMs,
+            bezier: resolveScrollCurve(beat.curve),
+        })),
+    };
+}
+async function applyHeldBeatFraming(page, beats, adjustments, safeViewport, viewportHeight, maxScroll) {
+    for (const [beatIndex, beat] of beats.entries()) {
+        if (beat.holdMs <= 0 || beat.target.type !== "selector")
+            continue;
+        const metrics = await page.evaluate((selector) => {
+            let element = null;
+            try {
+                element = document.querySelector(selector);
+            }
+            catch {
+                return null;
+            }
+            if (!element)
+                return null;
+            const rect = element.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                return null;
+            return {
+                y: rect.top + window.scrollY,
+                height: rect.height,
+            };
+        }, beat.target.selector);
+        if (!metrics)
+            continue;
+        const align = beat.target.align ?? "center";
+        const framing = resolvePauseFraming({
+            y: metrics.y,
+            height: metrics.height,
+            position: beat.position,
+            align,
+            safeViewport,
+            viewportHeight,
+            maxScroll,
+        });
+        const requestedPosition = beat.position;
+        beat.position = framing.targetY;
+        beat.framing = {
+            selector: beat.target.selector,
+            align: framing.align,
+            targetY: framing.targetY,
+            safeTopPx: framing.safeTopPx,
+            safeBottomPx: framing.safeBottomPx,
+            verified: framing.verified,
+        };
+        if (Math.abs(requestedPosition - beat.position) > 1) {
+            adjustments.push({
+                beatIndex,
+                code: "corrected-pause-framing",
+                message: "Adjusted a held target to keep its focal element inside the safe viewport",
+                requested: requestedPosition,
+                resolved: beat.position,
+            });
+        }
+    }
+}
+function resolveDirectedVirtualBeats(beats, startHoldMs, viewportHeight, wheelBudget) {
+    if (beats.length === 0)
+        throw new Error("direction.beats must contain at least one beat");
+    let previous = 0;
+    const resolved = [];
+    for (const beat of beats) {
+        validateBeat(beat);
+        if (beat.interaction) {
+            throw new Error("Component interactions are only supported on document-scroll pages");
+        }
+        if (beat.target.type === "selector") {
+            if (beat.target.fallbackProgress === undefined) {
+                throw new Error(`Selector target ${beat.target.selector} cannot direct a virtual-scroll page; use a progress target from inspect_website`);
+            }
+        }
+        const position = beat.target.type === "page-end"
+            ? 1
+            : beat.target.type === "selector"
+                ? beat.target.fallbackProgress
+                : beat.target.value;
+        if (position < 0 || position > 1)
+            throw new Error("Virtual progress targets must be between 0 and 1");
+        if (position + 1e-6 < previous)
+            throw new Error("Virtual progress beats must be ordered from 0 to 1");
+        previous = position;
+        const curve = beat.curve ?? DEFAULT_BEAT_CURVE;
+        resolved.push({ target: beat.target, position, transitionMs: beat.transitionMs, holdMs: beat.holdMs ?? 0, curve });
+    }
+    const normalized = normalizeResolvedBeats({
+        beats: resolved,
+        startHoldMs,
+        viewportHeight,
+        positionScale: wheelBudget,
+    });
+    return {
+        ...normalized,
+        timeline: normalized.beats.map((beat) => ({
+            position: beat.position,
+            transitionMs: beat.transitionMs,
+            holdMs: beat.holdMs,
+            bezier: resolveScrollCurve(beat.curve),
+        })),
+    };
+}
+async function resolveLegacyDocumentBeats(page, options, maxScroll, safeViewport) {
+    const pauses = normalizePauseTriggers(options.pauseTriggers ?? []);
+    const pauseTargets = [];
+    for (const pause of pauses) {
+        const target = { type: "selector", selector: pause.selector, align: "center" };
+        const position = await resolveDocumentTarget(page, target, maxScroll, options.viewportHeight, safeViewport);
+        pauseTargets.push({ target, position, holdMs: pause.durationMs });
+    }
+    pauseTargets.sort((a, b) => a.position - b.position);
+    const targets = [
+        ...pauseTargets,
+        { target: { type: "page-end" }, position: maxScroll, holdMs: 0 },
+    ].filter((target, index, all) => index === 0 || target.position > all[index - 1].position + 1 || target.holdMs > 0);
+    const defaultMovementMs = Math.max(1000, (Math.ceil(maxScroll / Math.max(1, options.pixelsPerFrame)) / (options.frameRecorder?.getFps() ?? 30)) * 1000);
+    let movementMs = options.animationConfig?.durationMs ?? defaultMovementMs;
+    const scrollSync = options.animationConfig?.scrollSync;
+    if (scrollSync && scrollSync.refMaxScroll > 0 && scrollSync.refDurationMs > 0) {
+        const refSpeed = scrollSync.refMaxScroll / scrollSync.refDurationMs;
+        if (refSpeed > 0) {
+            const calculatedMs = Math.round(maxScroll / refSpeed);
+            const maxAllowedMs = Math.min(90000, (options.animationConfig?.durationMs ?? 18000) * 5);
+            movementMs = Math.max(1000, Math.min(maxAllowedMs, calculatedMs));
+        }
+    }
+    const curve = options.animationConfig?.scrollCurve ?? { preset: "linear" };
+    const resolved = [];
+    const timeline = [];
+    let previous = 0;
+    for (const target of targets) {
+        const distance = Math.max(0, target.position - previous);
+        const transitionMs = maxScroll > 0 ? Math.max(1, Math.round(movementMs * distance / maxScroll)) : 1;
+        resolved.push({ target: target.target, position: target.position, transitionMs, holdMs: target.holdMs, curve });
+        timeline.push({ position: target.position, transitionMs, holdMs: target.holdMs, bezier: options.bezier });
+        previous = target.position;
+    }
+    return { beats: resolved, timeline, adjustments: [] };
+}
+function resolveLegacyVirtualBeats(durationMs, bezier) {
+    const target = { type: "page-end" };
+    return {
+        beats: [{ target, position: 1, transitionMs: durationMs, holdMs: 0, curve: { preset: "linear" } }],
+        timeline: [{ position: 1, transitionMs: durationMs, holdMs: 0, bezier }],
+        adjustments: [],
+    };
+}
+async function resolveDocumentTarget(page, target, maxScroll, viewportHeight, safeViewport) {
+    if (target.type === "page-end")
+        return maxScroll;
+    if (target.type === "progress") {
+        if (target.value < 0 || target.value > 1)
+            throw new Error("Progress targets must be between 0 and 1");
+        return maxScroll * target.value;
+    }
+    const metrics = await page.evaluate((selector) => {
+        let element = null;
+        try {
+            element = document.querySelector(selector);
+        }
+        catch {
+            return null;
+        }
+        if (!element)
+            return null;
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0)
+            return null;
+        return { top: rect.top + window.scrollY, height: rect.height };
+    }, target.selector);
+    if (!metrics) {
+        if (target.fallbackProgress !== undefined)
+            return maxScroll * target.fallbackProgress;
+        throw new Error(`Direction selector was not found or visible: ${target.selector}`);
+    }
+    return alignedDocumentPosition({
+        y: metrics.top,
+        height: metrics.height,
+        align: target.align ?? "center",
+        offsetPx: target.offsetPx ?? 0,
+        safeViewport,
+        viewportHeight,
+        maxScroll,
+    });
+}
+function validateBeat(beat) {
+    if (!Number.isFinite(beat.transitionMs) || beat.transitionMs < 250 || beat.transitionMs > 60_000) {
+        throw new Error("Each direction transitionMs must be between 250 and 60000");
+    }
+    const holdMs = beat.holdMs ?? 0;
+    if (!Number.isFinite(holdMs) || holdMs < 0 || holdMs > 15_000) {
+        throw new Error("Each direction holdMs must be between 0 and 15000");
+    }
+    if (beat.interaction) {
+        if (beat.target.type !== "selector") {
+            throw new Error("Component interactions require a selector target from inspect_website");
+        }
+        if (holdMs < 900) {
+            throw new Error("Interactive beats require holdMs of at least 900ms");
+        }
+        const zoomScale = beat.interaction.zoomScale ?? 1.25;
+        if (!Number.isFinite(zoomScale) || zoomScale < 1 || zoomScale > 1.8) {
+            throw new Error("Interaction zoomScale must be between 1 and 1.8");
+        }
+    }
+    if (beat.target.type === "selector"
+        && beat.target.fallbackProgress !== undefined
+        && (!Number.isFinite(beat.target.fallbackProgress) || beat.target.fallbackProgress < 0 || beat.target.fallbackProgress > 1)) {
+        throw new Error("Selector fallbackProgress must be between 0 and 1");
+    }
+    resolveScrollCurve(beat.curve ?? DEFAULT_BEAT_CURVE);
+}
+function normalizePauseTriggers(triggers) {
+    return triggers
+        .map((trigger) => ({ selector: trigger.selector.trim(), durationMs: Math.max(0, Math.round(trigger.durationMs)) }))
+        .filter((trigger) => trigger.selector.length > 0 && trigger.durationMs >= 100);
+}
+function describeTarget(target) {
+    if (target.type === "selector")
+        return target.selector;
+    if (target.type === "progress")
+        return `progress ${target.value}`;
+    return "page end";
+}
+async function settleScrollPaint(page, scrollY) {
+    await page.evaluate(async (y) => {
+        window.scrollTo({ top: y, left: 0, behavior: "instant" });
+        await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+    }, scrollY);
+}
+async function settleCaptureAtTop(page) {
+    await page.evaluate(async () => {
+        window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+        await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+    });
+    await page.waitForTimeout(250);
+}
+//# sourceMappingURL=scroll.js.map