Skip to content

Write HTML. Render video. Built for agents.

31.0 KB
Raw Blame
import { launchManagedBrowser, resolveManagedGpuMode } from "../browser/launch.js";
// Onion-skin motion screenshot: seek the LIVE timeline at N equal-time steps and
// project the REAL element at each step, so an agent can SELF-VERIFY motion (the
// rendered result — every channel: position, rotation, scale, opacity, colour),
// not just the authored x/y numbers. Reuses the headless-Chrome + static-server
// pattern from layout.ts.
//
// 3D is captured for free: zero-size marker children at the element's corners are
// projected by the browser, so a tilted/edge-on element renders as a real quad.
// Framing controls (samples / time window / fit / filmstrip) let the agent frame
// exactly what it's editing. All geometry + SVG live in ./motionShotLayout.ts
// (pure, tested); this file only drives the browser and SAMPLES.

import { mkdirSync, statSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { pageNavigationTimeoutMs } from "../utils/renderArgs.js";
import { gotoWhenSent } from "../capture/navigateForCapture.js";
import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
import { waitForRuntimeReady } from "../capture/captureCompositionFrame.js";
import {
  assertWebGpuAdapterAvailable,
  compositionRequiresWebGpu,
  resolveLocalBrowserGpuMode,
  resolveLocalWebGpu,
} from "../browser/gpuPolicy.js";
import {
  buildOnionSvg,
  buildRenderedStripSvg,
  ghostAlphas,
  parseAngle,
  resolveShotSelectors,
  sampleTimes,
  stripCaptureTimeCandidates,
  type OnionElement,
  type RenderedStripFrame,
} from "./motionShotLayout.js";

export interface ShotRequest {
  /** CSS selector of the moving element to sample (e.g. "#dot"). */
  selector: string;
}

function pathsReferToSameFile(firstPath: string, secondPath: string): boolean {
  const first = resolve(firstPath);
  const second = resolve(secondPath);
  if (first === second) return true;
  try {
    const firstStat = statSync(first, { bigint: true });
    const secondStat = statSync(second, { bigint: true });
    return firstStat.dev === secondStat.dev && firstStat.ino === secondStat.ino;
  } catch {
    return false;
  }
}

export function ensureShotOutputDir(outPath: string, sourcePath?: string): void {
  if (sourcePath && pathsReferToSameFile(outPath, sourcePath)) {
    throw new Error(
      `--shot output must not overwrite the composition source: ${sourcePath}. Choose a separate .png path.`,
    );
  }
  mkdirSync(dirname(outPath), { recursive: true });
}

/** Returned by the in-browser selector resolver: which animated selectors a
 *  `--selector SCOPE` actually resolves to (scope itself, or its descendants),
 *  plus diagnostic context when nothing under the scope animates. */
interface ScopeResolution {
  /** Animated selectors to sample (subset of `requests`). */
  selectors: string[];
  /** True when the scope selector matched a real element in the DOM. */
  scopeExists: boolean;
}

export interface ShotOptions {
  /** Project-relative HTML entry to render. Defaults to `index.html`. */
  entryFile?: string;
  /** Equal-time samples across the (windowed) timeline. Default 9. */
  samples?: number;
  /** "path" = ghosts at real positions + path. "strip" = real per-time pixel
   * filmstrip, but only when the selector targets an SVG element (see
   * `stripTargetsSvg` below); for any other selector — including every
   * nested sub-composition host, which is always a `<div data-composition-src>`
   * — it falls back to one live frame plus vector position markers. */
  layout?: "path" | "strip";
  /** Zoom the motion to fill the frame. Default true. */
  fit?: boolean;
  /** Sample only this time window (seconds) — dense inspection of one phase. */
  from?: number | null;
  to?: number | null;
  /** Orbit camera: a preset (front|iso|top|side) or "yaw,pitch" degrees. */
  angle?: string;
  /** `--selector` scope: when the user focused one element, narrow `requests`
   *  to that element if it animates, else to its animated descendants (so a
   *  static `.clip` wrapper resolves to the animated children under it). */
  scopeSelector?: string | null;
  /** Rendered ("ghost") onion-skin: capture the canvas pixels at each sample and
   *  composite them as translucent ghosts (older fainter → newest solid) — the
   *  canvas/WebGL motion the bbox-marker onion can't see. Requires a <canvas>. */
  ghost?: boolean;
}

interface PageSample {
  t: number;
  q: Array<{ x: number; y: number }>;
  c: { x: number; y: number };
  color: string;
  opacity: number;
}

type OrbitCamera = { yaw: number; pitch: number };
type FrameSize = { width: number; height: number };

/** Runs in the browser: sample HTML targets through inherited marker geometry,
 * and SVG graphics through their native local bbox + screen transform. */
export async function sampleMarkerOnionElements(
  selectors: string[],
  ts: number[],
): Promise<OnionElement[]> {
  const seek = (window as unknown as { __hfSeekAllAdapters?: (t: number) => Promise<void> })
    .__hfSeekAllAdapters;
  const rigs = selectors.map((selector) => {
    const el = document.querySelector(selector) as HTMLElement | null;
    if (!el) return null;
    const svg = el as Element & {
      getBBox?: () => { x: number; y: number; width: number; height: number };
      getScreenCTM?: () => {
        a: number;
        b: number;
        c: number;
        d: number;
        e: number;
        f: number;
      } | null;
    };
    if (typeof svg.getBBox === "function" && typeof svg.getScreenCTM === "function") {
      return { el, svg, markers: null };
    }
    const w = el.offsetWidth;
    const h = el.offsetHeight;
    const local: Array<[number, number]> = [
      [0, 0],
      [w, 0],
      [w, h],
      [0, h],
      [w / 2, h / 2],
    ];
    const markers = local.map(([lx, ly]) => {
      const marker = document.createElement("div");
      marker.style.cssText = `position:absolute;left:${lx}px;top:${ly}px;width:0;height:0;pointer-events:none`;
      el.appendChild(marker);
      return marker;
    });
    return { el, svg: null, markers };
  });
  const out = selectors.map((selector) => ({ selector, samples: [] as PageSample[] }));
  for (const t of ts) {
    await seek?.(t);
    rigs.forEach((rig, index) => {
      if (!rig) return;
      let points: Array<{ x: number; y: number }>;
      if (rig.svg) {
        const box = rig.svg.getBBox?.();
        const matrix = rig.svg.getScreenCTM?.();
        if (!box || !matrix) return;
        const local = [
          { x: box.x, y: box.y },
          { x: box.x + box.width, y: box.y },
          { x: box.x + box.width, y: box.y + box.height },
          { x: box.x, y: box.y + box.height },
          { x: box.x + box.width / 2, y: box.y + box.height / 2 },
        ];
        points = local.map((point) => ({
          x: matrix.a * point.x + matrix.c * point.y + matrix.e,
          y: matrix.b * point.x + matrix.d * point.y + matrix.f,
        }));
      } else {
        const w = rig.el.offsetWidth;
        const h = rig.el.offsetHeight;
        const local = [
          [0, 0],
          [w, 0],
          [w, h],
          [0, h],
          [w / 2, h / 2],
        ];
        rig.markers!.forEach((marker, i) => {
          marker.style.left = `${local[i]![0]! - rig.el.clientLeft + rig.el.scrollLeft}px`;
          marker.style.top = `${local[i]![1]! - rig.el.clientTop + rig.el.scrollTop}px`;
        });
        points = rig.markers!.map((marker) => {
          const rect = marker.getBoundingClientRect();
          return { x: rect.left, y: rect.top };
        });
      }
      const style = getComputedStyle(rig.el);
      out[index]!.samples.push({
        t: Math.round(t * 1000) / 1000,
        q: points.slice(0, 4),
        c: points[4]!,
        color: style.backgroundColor,
        opacity: parseFloat(style.opacity) || 0,
      });
    });
  }
  rigs.forEach((rig) => {
    if (rig) rig.el.style.visibility = "hidden";
  });
  return out.filter((element) => element.samples.length > 0);
}

// Runs IN THE BROWSER (serialized by page.evaluate). Make the element's ancestor
// chain preserve-3d, strip intermediate perspective, put one perspective on the
// composition root's parent (the lens) and rotate the root — so the element's own
// 3D is viewed from the requested angle on any composition shape (no #stage assumption).
function applyOrbitCamera(selectors: string[], cam: OrbitCamera): void {
  const first = document.querySelector(selectors[0] ?? "");
  const root =
    (first?.closest("[data-composition-id]") as HTMLElement | null) ??
    (document.querySelector("#stage") as HTMLElement | null) ??
    (document.body.firstElementChild as HTMLElement | null) ??
    document.body;
  for (const sel of selectors) {
    let n = document.querySelector(sel) as HTMLElement | null;
    while (n && n !== root) {
      n.style.transformStyle = "preserve-3d";
      n.style.perspective = "none";
      n = n.parentElement;
    }
  }
  root.style.transformStyle = "preserve-3d";
  root.style.perspective = "none";
  root.style.transformOrigin = "50% 50%";
  root.style.transform = `rotateX(${cam.pitch}deg) rotateY(${cam.yaw}deg)`;
  const lens = root.parentElement ?? document.body;
  lens.style.perspective = "1600px";
  lens.style.perspectiveOrigin = "50% 50%";
}

// Runs IN THE BROWSER. Composite N real painted frames (data URLs) onto a black
// canvas with per-frame opacity (older fainter → newest solid) so canvas/WebGL
// motion reads as a rendered onion-skin trail. Returns the composite as a PNG
// data URL. Used by the `--ghost` mode.
function compositeGhostFrames(
  frames: string[],
  alphas: number[],
  W: number,
  H: number,
  label: string,
): Promise<string> {
  return new Promise((resolve) => {
    const cv = document.createElement("canvas");
    cv.width = W;
    cv.height = H;
    const ctx = cv.getContext("2d");
    if (!ctx) {
      resolve("");
      return;
    }
    ctx.fillStyle = "#000";
    ctx.fillRect(0, 0, W, H);
    let i = 0;
    const step = () => {
      if (i >= frames.length) {
        ctx.globalAlpha = 1;
        ctx.font = "600 22px ui-monospace, SFMono-Regular, Menlo, monospace";
        ctx.fillStyle = "#86c2ff";
        ctx.fillText(label, 24, 38);
        resolve(cv.toDataURL("image/png"));
        return;
      }
      const img = new Image();
      img.onload = () => {
        ctx.globalAlpha = alphas[i] ?? 1;
        ctx.drawImage(img, 0, 0, W, H);
        i += 1;
        step();
      };
      img.onerror = () => {
        i += 1;
        step();
      };
      img.src = frames[i] ?? "";
    };
    step();
  });
}

// Runs IN THE BROWSER. Self-contained (only `tt` + window/document — never a
// Node-side closure variable), pauses/seeks every adapter to time `tt`: GSAP
// `__timelines`, the Web Animations API, `__hfAnime` instances, then dispatches
// `hf-seek` and nudges the three/GSAP render hooks. GPU work registered through
// `waitUntil()` is awaited before returning. This one routine backs BOTH
// the ghost-frame capture and the marker sampler below — see installSeekHelper
// for why it's installed as a page global instead of being duplicated inline
// (Puppeteer's page.evaluate only serializes the single function passed to it,
// so a Node-side function can't be *called* from inside another evaluate
// callback; it can only be reused by installing its source as a real page
// global once, up front).
export async function seekAllAdaptersInBrowser(tt: number): Promise<void> {
  const tryCall = (fn: () => void): boolean => {
    try {
      fn();
      return true;
    } catch {
      return false;
    }
  };
  const w = window as unknown as {
    __player?: { renderSeek?: (t: number) => void; seek?: (t: number) => void };
    __hfReseekGpu?: (t: number) => void;
    __hfWaitForSeekCompletion?: () => Promise<void>;
    __hfThreeTime?: number;
    __hfThreeRender?: () => void;
    __hfAnime?: Array<{ pause?: () => void; seek?: (timeMs: number) => void }>;
    gsap?: { ticker?: { tick?: () => void } };
    __timelines?: Record<
      string,
      {
        pause?: () => void;
        seek?: (t: number) => void;
        totalTime?: (t: number, s: boolean) => void;
      }
    >;
  };
  const timeMs = Math.max(0, tt * 1000);
  let runtimeSeeked = false;
  const pendingGpuWork: PromiseLike<unknown>[] = [];

  if (typeof w.__player?.renderSeek === "function") {
    runtimeSeeked = tryCall(() => w.__player?.renderSeek?.(tt));
  } else if (typeof w.__player?.seek === "function") {
    runtimeSeeked = tryCall(() => w.__player?.seek?.(tt));
  } else if (typeof w.__hfReseekGpu === "function") {
    runtimeSeeked = tryCall(() => w.__hfReseekGpu?.(tt));
  }

  Object.values(w.__timelines ?? {}).forEach((tl) => {
    tryCall(() => {
      tl.pause?.();
      if (typeof tl.totalTime === "function") {
        tl.totalTime(tt + 0.001, true);
        tl.totalTime(tt, false);
      } else {
        tl.seek?.(tt);
      }
    });
  });

  tryCall(() => {
    if (typeof document.getAnimations === "function") {
      for (const animation of document.getAnimations()) {
        tryCall(() => {
          animation.currentTime = timeMs;
        });
        tryCall(() => animation.pause());
      }
    }
  });

  for (const instance of w.__hfAnime ?? []) {
    tryCall(() => {
      instance.pause?.();
      instance.seek?.(timeMs);
    });
  }

  w.__hfThreeTime = tt;
  if (!runtimeSeeked) {
    let acceptingGpuWork = true;
    try {
      window.dispatchEvent(
        new CustomEvent("hf-seek", {
          detail: {
            time: tt,
            waitUntil(promise: PromiseLike<unknown>) {
              if (!acceptingGpuWork) {
                throw new Error("hf-seek waitUntil() must be called synchronously");
              }
              pendingGpuWork.push(promise);
            },
          },
        }),
      );
    } finally {
      acceptingGpuWork = false;
    }
  }
  tryCall(() => w.__hfThreeRender?.());
  tryCall(() => w.gsap?.ticker?.tick?.());

  await Promise.all([Promise.all(pendingGpuWork), w.__hfWaitForSeekCompletion?.()]);
}

// Installs seekAllAdaptersInBrowser as a real `window` global, once per page
// load. Both the ghost-frame capture and the marker sampler then call it via a
// plain property access instead of re-declaring its body — see the function's
// own doc comment for why a page global (rather than a Node-side reference) is
// required here.
async function installSeekHelper(page: import("puppeteer-core").Page): Promise<void> {
  await page.evaluate(`window.__hfSeekAllAdapters = ${seekAllAdaptersInBrowser.toString()};`);
}

// Launch headless Chrome, load the composition sized to its canvas, wait for the
// timelines + fonts to be ready. Returns the browser (caller closes it), page, size.
async function openCompositionPage(
  html: string,
  url: string,
  executablePath: string,
): Promise<{
  browser: import("puppeteer-core").Browser;
  page: import("puppeteer-core").Page;
  size: FrameSize;
}> {
  const puppeteer = await import("puppeteer-core");
  const { buildChromeArgs } = await import("@hyperframes/engine");
  const size = resolveCompositionViewportFromHtml(html);
  const requestedGpuMode = resolveLocalBrowserGpuMode();
  const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath);
  const requiresWebGpu = compositionRequiresWebGpu(html);
  const { gpuConfig, softwareWebGpu } = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);
  const browser = await launchManagedBrowser(puppeteer.default, {
    headless: true,
    executablePath,
    args: buildChromeArgs({ ...size, captureMode: "screenshot", requiresWebGpu }, gpuConfig),
  });
  try {
    const page = await browser.newPage();
    await page.setViewport(size);
    await gotoWhenSent(page, url, pageNavigationTimeoutMs());
    await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
    await waitForRuntimeReady(page, 10000);
    await page
      .evaluate(async () => {
        const d = document as unknown as { fonts?: { ready?: Promise<unknown> } };
        if (d.fonts?.ready) await d.fonts.ready;
      })
      .catch(() => {});
    await installSeekHelper(page);
    return { browser, page, size };
  } catch (err) {
    await browser.close().catch(() => {});
    throw err;
  }
}

// Longest seekable duration (seconds) across registered timelines, player/root
// duration, CSS/WAAPI animations, and Anime.js instances.
function timelineDuration(page: import("puppeteer-core").Page): Promise<number> {
  return page.evaluate(() => {
    const finiteSeconds = (value: unknown): number => {
      const n = typeof value === "number" ? value : Number(value);
      return Number.isFinite(n) && n > 0 ? n : 0;
    };
    const finiteMsToSeconds = (value: unknown): number => {
      const n = typeof value === "number" ? value : Number(value);
      return Number.isFinite(n) && n > 0 ? n / 1000 : 0;
    };
    const w = window as unknown as {
      __player?: { getDuration?: () => number };
      __timelines?: Record<string, { duration?: () => number; totalDuration?: () => number }>;
      __hfAnime?: Array<{ duration?: number | string; totalDuration?: number | string }>;
    };

    const timelinesDuration = (): number => {
      let d = 0;
      for (const tl of Object.values(w.__timelines ?? {})) {
        try {
          d = Math.max(d, (tl.totalDuration?.() ?? tl.duration?.() ?? 0) as number);
        } catch {
          // skip
        }
      }
      return d;
    };

    const animationDurationSeconds = (animation: Animation): number => {
      const timing = animation.effect?.getTiming?.();
      if (!timing) return 0;
      const durationMs = Number(timing.duration);
      const iterations = Number(timing.iterations ?? 1);
      if (!Number.isFinite(durationMs) || !Number.isFinite(iterations)) return 0;
      const delayMs = Number(timing.delay ?? 0);
      const endDelayMs = Number(timing.endDelay ?? 0);
      return finiteMsToSeconds(Math.max(0, delayMs) + durationMs * iterations + endDelayMs);
    };

    const waapiDuration = (): number => {
      if (typeof document.getAnimations !== "function") return 0;
      let d = 0;
      try {
        for (const animation of document.getAnimations()) {
          d = Math.max(d, animationDurationSeconds(animation));
        }
      } catch {
        // skip
      }
      return d;
    };

    const animeDuration = (): number => {
      let d = 0;
      for (const instance of w.__hfAnime ?? []) {
        d = Math.max(d, finiteMsToSeconds(instance.totalDuration ?? instance.duration));
      }
      return d;
    };

    let d = finiteSeconds(w.__player?.getDuration?.());
    const root = document.querySelector("[data-composition-id][data-duration]");
    if (root) d = Math.max(d, finiteSeconds(root.getAttribute("data-duration")));
    return Math.max(d, timelinesDuration(), waapiDuration(), animeDuration());
  });
}

// In the live DOM, decide which animated selectors fall under `scope`: read
// whether the scope exists and, for each candidate, whether it is the scope or a
// descendant of it. The pure decision (motionShotLayout.resolveShotSelectors)
// runs Node-side on the booleans this returns, so it stays unit-testable.
async function resolveScopeInBrowser(
  page: import("puppeteer-core").Page,
  scope: string,
  candidates: string[],
): Promise<ScopeResolution> {
  const probe = await page.evaluate(
    (scopeSel: string, cands: string[]) => {
      let root: Element | null = null;
      try {
        root = document.querySelector(scopeSel);
      } catch {
        root = null;
      }
      const descendant = cands.map((sel) => {
        if (!root) return false;
        let el: Element | null = null;
        try {
          el = document.querySelector(sel);
        } catch {
          return false;
        }
        return !!el && (el === root || root.contains(el));
      });
      return { scopeExists: !!root, descendant };
    },
    scope,
    candidates,
  );
  const selectors = resolveShotSelectors(
    scope,
    candidates,
    (_s, target) => probe.descendant[candidates.indexOf(target)] === true,
  );
  return { selectors, scopeExists: probe.scopeExists };
}

// --selector scope: the focused element is often a STATIC wrapper (`.clip`)
// whose animated children carry the tweens. Resolve, in the live DOM, to the
// scope itself if it animates, else its animated descendants — so the shot
// works on the standard composition shape instead of erroring.
async function resolveScopedRequests(
  page: import("puppeteer-core").Page,
  requests: ShotRequest[],
  scopeSelector: string,
): Promise<ShotRequest[]> {
  const resolved = await resolveScopeInBrowser(
    page,
    scopeSelector,
    requests.map((r) => r.selector),
  );
  if (!resolved.scopeExists) {
    throw new Error(`--shot: --selector '${scopeSelector}' matched no element.`);
  }
  if (resolved.selectors.length === 0) {
    const nearest = requests
      .slice(0, 5)
      .map((r) => r.selector)
      .join(", ");
    throw new Error(
      `--shot: nothing animates under '${scopeSelector}'. Nearest animated elements: ${nearest || "(none)"}.`,
    );
  }
  return resolved.selectors.map((selector) => ({ selector }));
}

// In-tick capture: seek the timeline (fires the composition's onUpdate render
// synchronously via the shared window.__hfSeekAllAdapters) + nudge the
// three-adapter, then drawImage every <canvas> onto an offscreen canvas in the
// SAME tick — before the browser clears the GL drawing buffer (works without
// preserveDrawingBuffer; page.screenshot can't see the GL buffer here).
function captureGhostFrame(page: import("puppeteer-core").Page, t: number): Promise<string> {
  return page.evaluate(async (tt: number) => {
    await (
      window as unknown as { __hfSeekAllAdapters?: (time: number) => Promise<void> }
    ).__hfSeekAllAdapters?.(tt);
    const root = (document.querySelector("[data-composition-id]") ?? document.body) as HTMLElement;
    const rb = root.getBoundingClientRect();
    const off = document.createElement("canvas");
    off.width = Math.max(1, Math.round(rb.width));
    off.height = Math.max(1, Math.round(rb.height));
    const octx = off.getContext("2d");
    for (const cv of Array.from(document.querySelectorAll("canvas"))) {
      const r = cv.getBoundingClientRect();
      try {
        octx?.drawImage(cv, r.left - rb.left, r.top - rb.top, r.width, r.height);
      } catch {
        /* tainted / not ready — skip */
      }
    }
    return off.toDataURL("image/png");
  }, t);
}

// Shared by both onion-skin modes: rotate the composition to the requested
// orbit angle (a no-op at the front angle), and format that angle for the
// frame's caption label.
async function applyOrbitCameraIfAngled(
  page: import("puppeteer-core").Page,
  requests: ShotRequest[],
  camera: OrbitCamera,
): Promise<void> {
  if (camera.yaw === 0 && camera.pitch === 0) return;
  await page.evaluate(
    applyOrbitCamera,
    requests.map((r) => r.selector),
    camera,
  );
}

function cameraLabel(camera: OrbitCamera): string {
  return camera.yaw === 0 && camera.pitch === 0
    ? "front"
    : `yaw ${camera.yaw}° pitch ${camera.pitch}°`;
}

// Rendered ("ghost") onion-skin: screenshot the REAL painted stage at each
// sample and composite them as translucent ghosts. This is the onion-skin for
// canvas/WebGL motion the marker sampler is blind to (the markers project a
// bbox; the pixels are the motion). Works for any visual composition, but
// requires a <canvas> (DOM/SVG transform motion already shows up in the
// default marker onion).
async function captureGhostOnionSkin(
  page: import("puppeteer-core").Page,
  requests: ShotRequest[],
  times: number[],
  size: FrameSize,
  camera: OrbitCamera,
  outPath: string,
): Promise<string> {
  await applyOrbitCameraIfAngled(page, requests, camera);
  const hasCanvas = await page.evaluate(() => document.querySelectorAll("canvas").length > 0);
  if (!hasCanvas) {
    throw new Error(
      "--ghost renders a canvas/WebGL motion trail, but this composition has no <canvas>. Use the default --shot onion for DOM/SVG transform motion.",
    );
  }
  const frames: string[] = [];
  for (const t of times) {
    frames.push(await captureGhostFrame(page, t));
  }
  const label = `${cameraLabel(camera)}  ·  rendered onion  ·  ${times.length} frames  ·  t ${times[0]}–${times[times.length - 1]}s`;
  const dataUrl = (await page.evaluate(
    compositeGhostFrames,
    frames,
    ghostAlphas(frames.length),
    size.width,
    size.height,
    label,
  )) as string;
  const b64 = String(dataUrl).replace(/^data:image\/png;base64,/, "");
  if (!b64) throw new Error("ghost composite returned no data");
  writeFileSync(outPath, Buffer.from(b64, "base64"));
  return outPath;
}

async function captureRenderedSvgStrip(
  page: import("puppeteer-core").Page,
  selector: string,
  times: number[],
  size: FrameSize,
  camera: OrbitCamera,
  hasWindow: boolean,
  outPath: string,
): Promise<string> {
  await applyOrbitCameraIfAngled(page, [{ selector }], camera);
  const frames: RenderedStripFrame[] = [];
  for (const t of times) {
    let clip: { x: number; y: number; width: number; height: number } | null = null;
    for (const captureTime of stripCaptureTimeCandidates(t)) {
      await page.evaluate(
        async (time: number) =>
          await (
            window as unknown as { __hfSeekAllAdapters?: (value: number) => Promise<void> }
          ).__hfSeekAllAdapters?.(time),
        captureTime,
      );
      clip = await page.evaluate((value: string) => {
        const element = document.querySelector(value);
        const rect = element?.getBoundingClientRect();
        if (!rect || rect.width <= 0 || rect.height <= 0) return null;
        const padding = 8;
        const x = Math.max(0, Math.floor(rect.left - padding));
        const y = Math.max(0, Math.floor(rect.top - padding));
        const right = Math.min(window.innerWidth, Math.ceil(rect.right + padding));
        const bottom = Math.min(window.innerHeight, Math.ceil(rect.bottom + padding));
        return { x, y, width: Math.max(1, right - x), height: Math.max(1, bottom - y) };
      }, selector);
      if (clip) break;
    }
    if (!clip) throw new Error(`--shot: '${selector}' has no visible SVG bounds at ${t}s.`);
    const shot = await page.screenshot({ type: "png", clip });
    const png = Buffer.isBuffer(shot) ? shot : Buffer.from(shot);
    frames.push({
      t,
      dataUrl: `data:image/png;base64,${png.toString("base64")}`,
      width: clip.width,
      height: clip.height,
    });
  }
  const windowStr = hasWindow ? `  ·  t ${times[0]}–${times[times.length - 1]}s` : "";
  const markup = buildRenderedStripSvg(frames, {
    width: size.width,
    height: size.height,
    label: `${cameraLabel(camera)}  ·  filmstrip  ·  ${times.length} frames${windowStr}`,
  });
  await page.evaluate((svg: string) => document.body.insertAdjacentHTML("beforeend", svg), markup);
  await new Promise((resolveWait) => setTimeout(resolveWait, 60));
  const output = await page.screenshot({ type: "png" });
  if (!output) throw new Error("screenshot returned no data");
  writeFileSync(outPath, output as Uint8Array);
  return outPath;
}

// Default (marker) onion-skin: seek to each sample time, read every element's
// projected corners. Marker children (zero-size) inherit the element's full
// transform chain, so their screen positions ARE the 3D projection of each
// corner — this is how 3D comes "for free" without an #stage assumption.
async function captureMarkerOnionSkin(
  page: import("puppeteer-core").Page,
  requests: ShotRequest[],
  times: number[],
  size: FrameSize,
  camera: OrbitCamera,
  frame: { layout: "path" | "strip"; fit: boolean; hasWindow: boolean },
  outPath: string,
): Promise<string> {
  // Orbit camera as its own step (keeps the sampler simple), only when angled.
  await applyOrbitCameraIfAngled(page, requests, camera);

  const elements = (await page.evaluate(
    sampleMarkerOnionElements,
    requests.map((r) => r.selector),
    times,
  )) as OnionElement[];

  const windowStr = frame.hasWindow ? `  ·  t ${times[0]}–${times[times.length - 1]}s` : "";
  const label = `${cameraLabel(camera)}  ·  ${frame.layout === "strip" ? "filmstrip" : frame.fit ? "zoom-fit" : "1:1"}  ·  ${times.length} frames${windowStr}`;
  const svg = buildOnionSvg(elements, {
    layout: frame.layout,
    fit: frame.fit,
    width: size.width,
    height: size.height,
    label,
  });

  await page.evaluate((markup: string) => {
    document.body.insertAdjacentHTML("beforeend", markup);
  }, svg);
  await new Promise((r) => setTimeout(r, 60));

  const buf = await page.screenshot({ type: "png" });
  if (!buf) throw new Error("screenshot returned no data");
  writeFileSync(outPath, buf as Uint8Array);
  return outPath;
}

/** Render `projectDir`'s index headless, sample each element's motion as a 3D
 *  onion-skin, screenshot to `outPath` (PNG). Returns the saved path. */
export async function captureMotionPathShot(
  projectDir: string,
  requestsIn: ShotRequest[],
  outPath: string,
  opts: ShotOptions = {},
): Promise<string> {
  ensureShotOutputDir(outPath, resolve(projectDir, opts.entryFile ?? "index.html"));
  let requests = requestsIn;
  const samples = Math.max(1, Math.min(60, opts.samples ?? 9));
  const layout = opts.layout ?? "path";
  const fit = opts.fit ?? true;
  const camera = parseAngle(opts.angle);

  const { ensureBrowser } = await import("../browser/manager.js");
  const { serveStaticProjectHtml } = await import("../utils/staticProjectServer.js");
  const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");

  const html = await bundleToSingleHtml(projectDir, { entryFile: opts.entryFile });
  const server = await serveStaticProjectHtml(
    projectDir,
    html,
    "Failed to bind motion shot server",
  );
  let browserInstance: import("puppeteer-core").Browser | undefined;
  try {
    const browser = await ensureBrowser();
    const opened = await openCompositionPage(html, server.url, browser.executablePath);
    browserInstance = opened.browser;
    const { page, size } = opened;

    if (opts.scopeSelector && !opts.ghost) {
      requests = await resolveScopedRequests(page, requests, opts.scopeSelector);
    }

    const times = sampleTimes(
      await timelineDuration(page),
      samples,
      opts.from ?? null,
      opts.to ?? null,
    );

    if (opts.ghost) {
      return await captureGhostOnionSkin(page, requests, times, size, camera, outPath);
    }

    const stripSelector = layout === "strip" ? requests[0]?.selector : undefined;
    const stripTargetsSvg = stripSelector
      ? await page.evaluate((selector: string) => {
          const element = document.querySelector(selector) as Element & {
            getBBox?: () => unknown;
            getScreenCTM?: () => unknown;
          };
          return (
            typeof element?.getBBox === "function" && typeof element.getScreenCTM === "function"
          );
        }, stripSelector)
      : false;
    if (stripSelector && stripTargetsSvg) {
      return await captureRenderedSvgStrip(
        page,
        stripSelector,
        times,
        size,
        camera,
        opts.from != null || opts.to != null,
        outPath,
      );
    }

    return await captureMarkerOnionSkin(
      page,
      requests,
      times,
      size,
      camera,
      { layout, fit, hasWindow: opts.from != null || opts.to != null },
      outPath,
    );
  } finally {
    await browserInstance?.close().catch(() => {});
    await server.close().catch(() => {});
  }
}