domotion-svg 0.2.2 → 0.3.2

package/src/scroll/composer.ts

@@ -23,6 +23,14 @@
 
 import type { ScrollSegmentCapture } from "./executor.js";
 import { elementTreeToSvg } from "../render/element-tree-to-svg.js";
+import {
+  clearEmbeddedFonts,
+  getEmbeddedFontFaceCss,
+  setRenderTextMode,
+  type RenderTextMode,
+} from "../render/text-to-path.js";
+import { extractFixedSubtrees, dedupeFixedAcrossSegments } from "./hoist-fixed.js";
+import { extractStickyWindows, type StickyOverlay } from "./hoist-sticky.js";
 
 export interface ScrollComposerOptions {
   /** Visible viewport width (output SVG width). */
@@ -40,6 +48,31 @@ export interface ScrollComposerOptions {
    * to source-resolution data URIs. Default 2 (matches `elementTreeToSvg`).
    */
   hiDPIFactor?: number;
+  /**
+   * DM-648: number of consecutive segments to group inside one
+   * `<g style="will-change: transform">` chunk wrapper. Each chunk gets its
+   * own GPU backing store so tall composites don't blow Chromium's
+   * per-layer raster budget (the 1280 × 6015 px apple-desktop-scroll capture
+   * at hi-DPI 2 was ~30 MB of raster on a single layer). Default `2` —
+   * meaning every two segments share one layer; a 16-segment scroll yields
+   * 8 layers. `1` puts each segment on its own layer (more layers, smaller
+   * each); higher values trade layer count for layer size. Must be ≥ 1.
+   * See `docs/36-scroll-composite-layer-chunking.md`.
+   */
+  chunkSize?: number;
+  /**
+   * DM-652: text rendering mode. Default `"embedded-font"` emits `<text>`
+   * elements with a single `@font-face` per used webfont — much faster
+   * in WebKit (≈1.84× perf gain + 4.5× smaller file on text-heavy
+   * fixtures per DM-651) and visually equivalent in Chromium. `"paths"`
+   * is the legacy Chromium-faithful mode that emits `<use href="#gN">`
+   * references to glyph path defs, useful when the consumer needs
+   * per-pixel parity with the Chromium capture (e.g. visual-regression
+   * diffing against the live page). System-font runs and bidi /
+   * fallback-chain runs always stay in `"paths"` mode regardless of
+   * this flag (MVP scope).
+   */
+  renderText?: RenderTextMode;
 }
 
 const DEFAULT_BG = "#0d1117";
@@ -62,6 +95,23 @@ export function composeScrollSvg(
   const VH = opts.viewportH;
   const bg = opts.bgColor ?? DEFAULT_BG;
   const hiDPIFactor = opts.hiDPIFactor ?? 2;
+  const chunkSize = opts.chunkSize ?? 2;
+  if (chunkSize < 1 || !Number.isInteger(chunkSize)) {
+    throw new Error(`composeScrollSvg: chunkSize must be a positive integer, got ${chunkSize}`);
+  }
+
+  // DM-652: arm the text-render lifecycle. Default is "embedded-font" —
+  // the per-segment text renderer emits `<text>` runs against a single
+  // @font-face per used webfont, ~2× faster in WebKit and ~5× smaller
+  // SVG payload than the legacy glyph-path output, visually equivalent
+  // in Chromium. Callers that need per-pixel Chromium parity (e.g.
+  // visual-regression diffing) opt back into "paths" explicitly. State
+  // is module-global so every segment's `elementTreeToSvg` call shares
+  // the same `@font-face` registry; we collect everything into one
+  // top-level <style> block at the bottom of this function.
+  const renderTextMode: RenderTextMode = opts.renderText ?? "embedded-font";
+  clearEmbeddedFonts();
+  setRenderTextMode(renderTextMode);
 
   // ── Total scene duration ──
   // The last segment's endMs is the cycle length. For a single-segment input,
@@ -80,22 +130,175 @@ export function composeScrollSvg(
   const compositeH = axis === "y" ? (maxPos - minPos) + VH : VH;
   const compositeW = axis === "x" ? (maxPos - minPos) + W  : W;
 
+  const animClass = `scrl-${Math.random().toString(36).slice(2, 8)}`;
+
+  // ── Split each capture into "scrolling" + "fixed" subtrees ──
+  // DM-643: `position: fixed` elements (site headers, cookie banners, etc.)
+  // appear at the same viewport coordinates in every capture. If we leave
+  // them inside the per-segment subtrees, the composer offsets each copy by
+  // that segment's scrollY and the scrolling composite carries them past the
+  // viewport — so the consumer sees the header "scroll" once per segment.
+  // Strip the fixed subtrees from every segment and hoist them onto a single
+  // viewport-level overlay below.
+  const fixedStripped: typeof segments[number]["tree"][] = [];
+  const perSegFixed: typeof segments[number]["tree"][] = [];
+  for (const seg of segments) {
+    const { stripped, fixed } = extractFixedSubtrees(seg.tree);
+    fixedStripped.push(stripped);
+    perSegFixed.push(fixed);
+  }
+  const fixedOverlay = dedupeFixedAcrossSegments(perSegFixed);
+
+  // ── Sticky overlays (DM-647) ──
+  // For each `position: sticky` element, find the runs of consecutive
+  // segments where it stays at the same viewport-y (stuck windows) and
+  // hoist each run onto the same overlay layer as the fixed overlay. The
+  // element stays inline in segments where it's still scrolling.
+  const { stripped: strippedTrees, overlays: stickyOverlays } = extractStickyWindows(fixedStripped);
+
+  // ── Per-segment visibility windows (DM-642) ──
+  // Each segment K is anchored at scroll-y = offsetK. Reading the keyframe
+  // schedule, find the % of cycle at which the composite's scroll-y reaches
+  // (offsetK - VH) [segment K enters viewport from below] and (offsetK + VH)
+  // [segment K leaves viewport off the top]. Outside that window the segment
+  // is `visibility: hidden` so the browser skips painting it. With ~8 segments
+  // for an apple.com-style page only ~2 segments are visible at any moment;
+  // hiding the other ~6 cuts per-frame paint cost dramatically.
+  //
+  // DM-641: we use `visibility` (not `display`) for the same reason the
+  // animator does — an element whose 0% keyframe is `display: none`
+  // never enters Chromium's render tree, so the animation engine never
+  // ticks the keyframe that would bring it back in.
+  // The full-cycle anchors come from `dedupedStops` below; build a temporary
+  // helper here that mirrors the same data shape.
+  const segOffsets: number[] = segments.map((s) =>
+    (axis === "y" ? s.scrollY : s.scrollX) - minPos,
+  );
+  const cycleStops: Array<{ pct: number; offset: number }> = [];
+  cycleStops.push({ pct: 0, offset: segOffsets[0] });
+  for (let i = 0; i < segments.length; i++) {
+    const endPct = (segments[i].segmentEndMs / totalMs) * 100;
+    cycleStops.push({ pct: endPct, offset: segOffsets[i] });
+  }
+  function pctAtScrollY(targetY: number, mode: "first" | "last"): number {
+    // Linear interpolation across cycleStops to find when scroll-y crosses
+    // targetY. With monotonic ascending scroll-y, "first" returns the first
+    // crossing (entering); "last" returns the last crossing (leaving).
+    // Out-of-range clamps to 0 / 100.
+    let hit = mode === "first" ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+    for (let s = 0; s + 1 < cycleStops.length; s++) {
+      const a = cycleStops[s], b = cycleStops[s + 1];
+      const lo = Math.min(a.offset, b.offset);
+      const hi = Math.max(a.offset, b.offset);
+      if (targetY < lo - 0.001 || targetY > hi + 0.001) continue;
+      const span = b.offset - a.offset;
+      const t = span === 0 ? 0 : (targetY - a.offset) / span;
+      const pct = a.pct + (b.pct - a.pct) * t;
+      if (mode === "first" && pct < hit) hit = pct;
+      if (mode === "last" && pct > hit) hit = pct;
+    }
+    if (!isFinite(hit)) return mode === "first" ? 0 : 100;
+    return Math.max(0, Math.min(100, hit));
+  }
+
   // ── Render each capture's content at its position offset ──
   const captureGroups: string[] = [];
+  const segmentCullCss: string[] = [];
   for (let i = 0; i < segments.length; i++) {
     const seg = segments[i];
-    const offset = (axis === "y" ? seg.scrollY : seg.scrollX) - minPos;
-    const inner = elementTreeToSvg(seg.tree, W, VH, `seg${i}-`, true, hiDPIFactor);
+    const offset = segOffsets[i];
+    const inner = elementTreeToSvg(strippedTrees[i], W, VH, `seg${i}-`, true, hiDPIFactor);
     const tx = axis === "x" ? offset : 0;
     const ty = axis === "y" ? offset : 0;
-    captureGroups.push(
-      `  <g transform="translate(${tx} ${ty})">` +
+    // Visibility window: visible while scroll-y is in the rasterisation
+    // window for this segment. The strict mathematical bound is
+    // `offset ± VH` (segment content can intersect viewport), but using
+    // exactly that triggers a Chromium compositor pop: the segment is
+    // `visibility: hidden` until the moment its content first enters the
+    // viewport, then `visible` snaps it on — but the GPU has zero time to
+    // rasterise the segment before its first frame of "should be visible"
+    // content is displayed, so for one or two frames the segment paints
+    // empty while raster catches up. Users see "content pops in at the
+    // viewport bottom" (DM-668 — reproducible on the NYT-desktop-scroll
+    // fixture at the s5→s6 boundary, ~26.3% of cycle).
+    //
+    // Fix: make each segment visible one extra `dim` (viewport-height /
+    // -width) earlier on enter and later on leave. Browsers get a full
+    // viewport-height of scroll time to rasterise before the segment's
+    // content actually needs to paint, and the segment stays rasterised
+    // a viewport longer after it leaves so a rapid scroll reversal also
+    // hits a warm GPU layer. Peak segments-visible-at-once roughly
+    // doubles (2 → ~4 worst case), which doesn't materially affect file
+    // size (the wrappers are hidden, not omitted) but does increase
+    // resident raster memory by ~one extra viewport per layer chunk —
+    // acceptable on every device we've profiled.
+    const dim = axis === "y" ? VH : W;
+    const rasterBuffer = dim;
+    const enterPct = pctAtScrollY(offset - dim - rasterBuffer, "first");
+    const leavePct = pctAtScrollY(offset + dim + rasterBuffer, "last");
+    const fullyVisible = enterPct <= 0 && leavePct >= 100;
+    if (fullyVisible) {
+      captureGroups.push(
+        `  <g transform="translate(${tx} ${ty})">` +
+          `<svg x="0" y="0" width="${W}" height="${VH}" viewBox="0 0 ${W} ${VH}">` +
+            inner +
+          `</svg>` +
+        `</g>`,
+      );
+    } else {
+      const cls = `${animClass}-s${i}`;
+      // step-end so the segment snaps in/out at the boundary, no fractional
+      // opacity that would force the browser to keep compositing it.
+      segmentCullCss.push(
+        `      @keyframes ${cls} { 0% { visibility: hidden } ${Math.max(0, enterPct - 0.001).toFixed(3)}% { visibility: hidden } ${enterPct.toFixed(3)}% { visibility: visible } ${leavePct.toFixed(3)}% { visibility: visible } ${Math.min(100, leavePct + 0.001).toFixed(3)}% { visibility: hidden } 100% { visibility: hidden } }
+      .${cls} { animation: ${cls} ${totalSec.toFixed(3)}s infinite; animation-timing-function: step-end; }`,
+      );
+      captureGroups.push(
+        `  <g class="${cls}" transform="translate(${tx} ${ty})">` +
+          `<svg x="0" y="0" width="${W}" height="${VH}" viewBox="0 0 ${W} ${VH}">` +
+            inner +
+          `</svg>` +
+        `</g>`,
+      );
+    }
+  }
+  // ── Sticky overlay markup + visibility keyframes ──
+  // Each overlay is one stuck window for one sticky element. Wrap the
+  // rendered subtree in a <g class="…"> whose visibility keyframe shows it
+  // only during [firstSegmentStart, lastSegmentEnd] of the cycle and hides
+  // it otherwise. DM-641 convention: visibility, never display.
+  const stickyMarkup: string[] = [];
+  const stickyCullCss: string[] = [];
+  for (let i = 0; i < stickyOverlays.length; i++) {
+    const o: StickyOverlay = stickyOverlays[i];
+    const visStartPct = (segments[o.firstSegmentIdx].segmentStartMs / totalMs) * 100;
+    const visEndPct = (segments[o.lastSegmentIdx].segmentEndMs / totalMs) * 100;
+    const alwaysVisible = visStartPct <= 0 && visEndPct >= 100;
+    const inner = elementTreeToSvg([o.subtree], W, VH, `stk${i}-`, true, hiDPIFactor);
+    if (alwaysVisible) {
+      stickyMarkup.push(
+        `\n  <g><svg x="0" y="0" width="${W}" height="${VH}" viewBox="0 0 ${W} ${VH}">${inner}</svg></g>`,
+      );
+    } else {
+      const cls = `${animClass}-k${i}`;
+      stickyCullCss.push(
+        `      @keyframes ${cls} { 0% { visibility: hidden } ${Math.max(0, visStartPct - 0.001).toFixed(3)}% { visibility: hidden } ${visStartPct.toFixed(3)}% { visibility: visible } ${visEndPct.toFixed(3)}% { visibility: visible } ${Math.min(100, visEndPct + 0.001).toFixed(3)}% { visibility: hidden } 100% { visibility: hidden } }
+      .${cls} { animation: ${cls} ${totalSec.toFixed(3)}s infinite; animation-timing-function: step-end; }`,
+      );
+      stickyMarkup.push(
+        `\n  <g class="${cls}"><svg x="0" y="0" width="${W}" height="${VH}" viewBox="0 0 ${W} ${VH}">${inner}</svg></g>`,
+      );
+    }
+  }
+
+  const fixedMarkup = fixedOverlay.length === 0
+    ? ""
+    : `\n  <g>` +
         `<svg x="0" y="0" width="${W}" height="${VH}" viewBox="0 0 ${W} ${VH}">` +
-          inner +
+          elementTreeToSvg(fixedOverlay, W, VH, "fix-", true, hiDPIFactor) +
         `</svg>` +
-      `</g>`,
-    );
-  }
+      `</g>`;
+  const overlayMarkup = fixedMarkup + stickyMarkup.join("");
 
   // ── Keyframes — one stop per segment ──
   // Each segment anchors a (time-percent, position-offset) pair. Linear
@@ -110,21 +313,51 @@ export function composeScrollSvg(
   }
   // Dedupe trivially equal stops to keep CSS small.
   const dedupedStops = stops.filter((s, i, arr) => i === 0 || !(s.pct === arr[i - 1].pct && s.offset === arr[i - 1].offset));
-  const animClass = `scrl-${Math.random().toString(36).slice(2, 8)}`;
+  const translateFn = axis === "x" ? "X" : "Y";
   const keyframes = dedupedStops
-    .map((s) => `      ${s.pct.toFixed(3)}% { transform: translate${axis === "x" ? "X" : "Y"}(-${s.offset.toFixed(3)}px); }`)
+    .map((s) =>
+      // DM-642: use translate3d to coax the browser into promoting the
+      // animated <g> onto its own compositing layer so per-frame motion is
+      // a GPU paint rather than a CPU re-rasterisation of every embedded
+      // image/path under the composite.
+      `      ${s.pct.toFixed(3)}% { transform: translate3d(${translateFn === "X" ? `-${s.offset.toFixed(3)}px, 0` : `0, -${s.offset.toFixed(3)}px`}, 0); }`,
+    )
     .join("\n");
 
+  // ── DM-648: chunked compositing layers ──
+  // Group consecutive segment wrappers into chunks of `chunkSize`. Each
+  // chunk wrapper carries `style="will-change: transform"` so Chromium gives
+  // it its own GPU backing store, letting tall composites stay under the
+  // per-layer raster cap. The chunk wrapper itself has NO `transform` (would
+  // double-translate); the inner per-segment `translate(0 Y)` still places
+  // content. The DM-642 cull classes on each inner segment are untouched.
+  const chunks: string[] = [];
+  for (let i = 0; i < captureGroups.length; i += chunkSize) {
+    const slice = captureGroups.slice(i, i + chunkSize);
+    chunks.push(`<g style="will-change: transform">\n${slice.join("\n")}\n      </g>`);
+  }
+
+  // DM-652: collect every `@font-face` rule the embedded-font path
+  // registered during segment + overlay rendering above, into a single
+  // top-level <style> block. Each font appears once (registry is keyed
+  // per (family, weight, italic)) — segments referencing the same font
+  // collapse onto one rule. Restore the default render mode now that
+  // all per-segment rendering has finished.
+  const fontFaceCss = getEmbeddedFontFaceCss();
+  setRenderTextMode("paths");
+
   // ── Compose final SVG ──
   return `<?xml version="1.0" encoding="UTF-8"?>
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${VH}" width="${W}" height="${VH}">
   <defs>
     <clipPath id="${animClass}-clip"><rect width="${W}" height="${VH}"/></clipPath>
     <style>
-      .${animClass} { animation: ${animClass} ${totalSec.toFixed(3)}s linear infinite; }
+${fontFaceCss !== "" ? fontFaceCss + "\n" : ""}      .${animClass} { animation: ${animClass} ${totalSec.toFixed(3)}s linear infinite; will-change: transform; }
       @keyframes ${animClass} {
 ${keyframes}
       }
+${segmentCullCss.join("\n")}
+${stickyCullCss.join("\n")}
     </style>
   </defs>
   <rect width="${W}" height="${VH}" fill="${bg}"/>
@@ -132,9 +365,9 @@ ${keyframes}
     <g class="${animClass}">
       <svg x="0" y="0" width="${compositeW}" height="${compositeH}" viewBox="0 0 ${compositeW} ${compositeH}">
         <rect width="${compositeW}" height="${compositeH}" fill="${bg}"/>
-${captureGroups.join("\n")}
+      ${chunks.join("\n      ")}
       </svg>
     </g>
-  </g>
+  </g>${overlayMarkup}
 </svg>`;
 }

package/src/scroll/executor.test.ts

@@ -174,6 +174,33 @@ describe("resolveScrollAction", () => {
     expect(r.scrollDurationMs).toBe(3000);
   });
 
+  it("explicit @<speed> overrides the executor's default speed", async () => {
+    const { query, snap } = fakePageQuery({ maxScrollY: 4000 });
+    const action: ScrollAction = {
+      kind: "scroll",
+      target: { kind: "delta", signedLength: { sign: 1, value: 720, unit: "px" } },
+      speedPxPerSec: 600,
+    };
+    // 720 / 600 * 1000 = 1200. Default speed of 1500 is ignored.
+    const r = await resolveScrollAction(action, query, snap, 1500);
+    expect(r.scrollDurationMs).toBe(1200);
+  });
+
+  it("@<speed> applies to the actual scroll magnitude, not the requested delta", async () => {
+    // Scroll request of 5000 px but page maxScrollY=4000 — actual magnitude
+    // is 4000 px after clamping. Speed math uses the clamped magnitude so
+    // the action lands at the boundary in the right amount of time.
+    const { query, snap } = fakePageQuery({ maxScrollY: 4000, scrollY: 0 });
+    const action: ScrollAction = {
+      kind: "scroll",
+      target: { kind: "delta", signedLength: { sign: 1, value: 5000, unit: "px" } },
+      speedPxPerSec: 1000,
+    };
+    const r = await resolveScrollAction(action, query, snap, 1500);
+    expect(r.destY).toBe(4000);
+    expect(r.scrollDurationMs).toBe(4000);
+  });
+
   it("`down:-100px` reverses direction (same as up:100px)", async () => {
     const { query, snap } = fakePageQuery({ maxScrollY: 4000, scrollY: 500 });
     const action: ScrollAction = {

package/src/scroll/executor.ts

@@ -14,7 +14,9 @@
  * a single `PageQuery` interface lets a test inject a fake page-state
  * provider in lieu of the real `Page`.
  *
- * Grammar reference: `dm604-scroll-grammar.txt` (signed-off draft on DM-604).
+ * Canonical grammar reference: `docs/37-scroll-pattern-grammar.md`. Keep
+ * this executor's axis/direction resolution, speed-derived duration math,
+ * and `until`-clause semantics in sync with what doc 37 describes.
  */
 
 import type { Page } from "@playwright/test";
@@ -215,7 +217,14 @@ export async function resolveScrollAction(
   const destX = axis === "x" ? clamp(snapshot.scrollX + delta, 0, snapshot.maxScrollX) : snapshot.scrollX;
   const destY = axis === "y" ? clamp(snapshot.scrollY + delta, 0, snapshot.maxScrollY) : snapshot.scrollY;
   const magnitude = Math.abs(axis === "x" ? destX - snapshot.scrollX : destY - snapshot.scrollY);
-  const scrollDurationMs = action.durationMs ?? Math.round((magnitude / defaultSpeed) * 1000);
+  // Duration resolution priority:
+  //   1. Explicit `/<duration>` on the action wins (the user pinned the time).
+  //   2. Else, action's `@<speed>` suffix (the user pinned constant speed for
+  //      this action only — magnitude / actionSpeed yields the duration).
+  //   3. Else, executor's inherited `defaultSpeed` (whole-pattern fallback).
+  // Cases 2 and 3 are mutually exclusive at parse time; safe to read both.
+  const effectiveSpeed = action.speedPxPerSec ?? defaultSpeed;
+  const scrollDurationMs = action.durationMs ?? Math.round((magnitude / effectiveSpeed) * 1000);
   return { axis, destX, destY, scrollDurationMs };
 }
 
@@ -527,8 +536,8 @@ function realPageQuery(page: Page, selector: string | null): PageQuery {
         }));
       }
       return page.evaluate((sel) => {
-        const el = document.querySelector(sel) as HTMLElement | null;
-        if (el == null) return { maxScrollX: 0, maxScrollY: 0, scrollX: 0, scrollY: 0 };
+        const el = document.querySelector(sel);
+        if (!(el instanceof HTMLElement)) return { maxScrollX: 0, maxScrollY: 0, scrollX: 0, scrollY: 0 };
         return {
           maxScrollX: Math.max(0, el.scrollWidth  - el.clientWidth),
           maxScrollY: Math.max(0, el.scrollHeight - el.clientHeight),
@@ -553,8 +562,8 @@ async function scrollTo(page: Page, selector: string | null, destX: number, dest
     await page.evaluate(({ x, y }) => window.scrollTo(x, y), { x: destX, y: destY });
   } else {
     await page.evaluate(({ sel, x, y }) => {
-      const el = document.querySelector(sel) as HTMLElement | null;
-      if (el != null) { el.scrollLeft = x; el.scrollTop = y; }
+      const el = document.querySelector(sel);
+      if (el instanceof HTMLElement) { el.scrollLeft = x; el.scrollTop = y; }
     }, { sel: selector, x: destX, y: destY });
   }
   // Wait the action's nominal duration plus a small settle for layout.
@@ -570,13 +579,13 @@ async function runPrescroll(page: Page, selector: string | null): Promise<void>
     await page.waitForTimeout(PRESCROLL_TOP_WAIT_MS);
   } else {
     await page.evaluate((sel) => {
-      const el = document.querySelector(sel) as HTMLElement | null;
-      if (el != null) el.scrollTop = el.scrollHeight;
+      const el = document.querySelector(sel);
+      if (el instanceof HTMLElement) el.scrollTop = el.scrollHeight;
     }, selector);
     await page.waitForTimeout(PRESCROLL_BOTTOM_WAIT_MS);
     await page.evaluate((sel) => {
-      const el = document.querySelector(sel) as HTMLElement | null;
-      if (el != null) el.scrollTop = 0;
+      const el = document.querySelector(sel);
+      if (el instanceof HTMLElement) el.scrollTop = 0;
     }, selector);
     await page.waitForTimeout(PRESCROLL_TOP_WAIT_MS);
   }

package/src/scroll/hoist-fixed.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+
+import type { CapturedElement } from "../capture/types.js";
+import { extractFixedSubtrees, dedupeFixedAcrossSegments } from "./hoist-fixed.js";
+
+function el(
+  partial: Partial<CapturedElement> & { tag: string; x: number; y: number },
+  position: string = "static",
+): CapturedElement {
+  return {
+    text: "",
+    width: partial.width ?? 100,
+    height: partial.height ?? 20,
+    children: partial.children ?? [],
+    ...partial,
+    styles: {
+      position,
+      ...(partial.styles ?? {}),
+    } as CapturedElement["styles"],
+  };
+}
+
+describe("extractFixedSubtrees", () => {
+  it("returns input unchanged when no fixed elements exist", () => {
+    const tree: CapturedElement[] = [
+      el({ tag: "div", x: 0, y: 0 }, "static"),
+      el({ tag: "p", x: 0, y: 30 }, "relative"),
+    ];
+    const r = extractFixedSubtrees(tree);
+    expect(r.fixed).toEqual([]);
+    expect(r.stripped).toBe(tree);
+  });
+
+  it("hoists a top-level position:fixed subtree", () => {
+    const header = el({ tag: "header", x: 0, y: 0, width: 800, height: 60 }, "fixed");
+    const main = el({ tag: "main", x: 0, y: 60 }, "static");
+    const r = extractFixedSubtrees([header, main]);
+    expect(r.fixed).toEqual([header]);
+    expect(r.stripped).toHaveLength(1);
+    expect(r.stripped[0].tag).toBe("main");
+  });
+
+  it("hoists a fixed subtree nested inside a normal-positioned ancestor", () => {
+    const fixedNav = el({ tag: "nav", x: 0, y: 0, width: 800, height: 50 }, "fixed");
+    const root = el({
+      tag: "body",
+      x: 0, y: 0, width: 800, height: 600,
+      children: [fixedNav, el({ tag: "section", x: 0, y: 100 }, "static")],
+    }, "static");
+    const r = extractFixedSubtrees([root]);
+    expect(r.fixed).toEqual([fixedNav]);
+    // body shallow-copied with the nav stripped out
+    expect(r.stripped).toHaveLength(1);
+    expect(r.stripped[0]).not.toBe(root);
+    expect(r.stripped[0].children).toHaveLength(1);
+    expect(r.stripped[0].children![0].tag).toBe("section");
+  });
+
+  it("treats a fixed subtree atomically — inner fixed descendants ride along", () => {
+    // Real-world: a fixed header with a fixed dropdown inside it. The
+    // dropdown is part of the header's stacking context; we shouldn't try
+    // to extract it separately.
+    const innerFixed = el({ tag: "div", x: 10, y: 10 }, "fixed");
+    const outerFixed = el({
+      tag: "header",
+      x: 0, y: 0, width: 800, height: 60,
+      children: [innerFixed],
+    }, "fixed");
+    const r = extractFixedSubtrees([outerFixed]);
+    expect(r.fixed).toEqual([outerFixed]);
+    expect(r.fixed[0].children).toContain(innerFixed);
+  });
+
+  it("does not mutate the input tree when stripping", () => {
+    const fixedChild = el({ tag: "div", x: 0, y: 0 }, "fixed");
+    const original = el({
+      tag: "body",
+      x: 0, y: 0,
+      children: [fixedChild, el({ tag: "p", x: 0, y: 20 }, "static")],
+    }, "static");
+    const originalChildren = original.children;
+    extractFixedSubtrees([original]);
+    // The original wasn't mutated — its children array reference and contents are intact.
+    expect(original.children).toBe(originalChildren);
+    expect(original.children).toHaveLength(2);
+  });
+});
+
+describe("dedupeFixedAcrossSegments", () => {
+  it("returns first occurrence per (tag, position, size) key", () => {
+    const segA: CapturedElement[] = [
+      el({ tag: "header", x: 0, y: 0, width: 800, height: 60, text: "v1" }, "fixed"),
+    ];
+    const segB: CapturedElement[] = [
+      el({ tag: "header", x: 0, y: 0, width: 800, height: 60, text: "v2" }, "fixed"),
+    ];
+    const r = dedupeFixedAcrossSegments([segA, segB]);
+    expect(r).toHaveLength(1);
+    expect(r[0].text).toBe("v1");
+  });
+
+  it("keeps distinct fixed elements that differ in size or position", () => {
+    const segA: CapturedElement[] = [
+      el({ tag: "header", x: 0, y: 0, width: 800, height: 60 }, "fixed"),
+    ];
+    const segB: CapturedElement[] = [
+      el({ tag: "header", x: 0, y: 0, width: 800, height: 60 }, "fixed"),
+      el({ tag: "div",    x: 0, y: 540, width: 800, height: 60 }, "fixed"),
+    ];
+    const r = dedupeFixedAcrossSegments([segA, segB]);
+    expect(r).toHaveLength(2);
+  });
+
+  it("returns empty when no segment contributed fixed elements", () => {
+    expect(dedupeFixedAcrossSegments([[], [], []])).toEqual([]);
+  });
+});

package/src/scroll/hoist-fixed.ts

@@ -0,0 +1,95 @@
+/**
+ * Hoist `position: fixed` elements out of scroll-segment trees so the scroll
+ * composer doesn't render them once per segment.
+ *
+ * DM-643: each segment's capture sees the live page at a different scrollY but
+ * a `position: fixed` element (e.g. a sticky-feeling site header) always
+ * occupies the same viewport coordinates. The scroll composer stacks segments
+ * vertically inside a translating composite, so the header from segment 0
+ * ends up at composite-y = 0+headerY, the header from segment 1 at composite-y
+ * = segment1.scrollY + headerY, and so on — producing the "fixed header
+ * repeats every viewport-height" artifact described in the ticket.
+ *
+ * The fix is to recognise `position: fixed` during composition: strip those
+ * subtrees from every per-segment capture and emit them once as a static
+ * overlay above the scrolling composite (where they belong visually). They
+ * stay in their captured viewport coordinates and never animate.
+ */
+
+import type { CapturedElement } from "../capture/types.js";
+
+/**
+ * Walk the tree, remove every subtree rooted at a `position: fixed` element
+ * (matching what Chromium reports in `getComputedStyle`), and return the list
+ * of removed subtrees. The input tree is shallow-copied at every level
+ * touched by the strip so the caller's references aren't mutated.
+ *
+ * A subtree rooted at a fixed element is hoisted whole: descendants follow
+ * their fixed ancestor. Inner fixed descendants of an already-hoisted subtree
+ * are NOT separately extracted — they live inside their ancestor's hoisted
+ * copy, which is the correct paint result (Chromium would paint them in the
+ * same stacking context anyway).
+ */
+export function extractFixedSubtrees(tree: CapturedElement[]): {
+  stripped: CapturedElement[];
+  fixed: CapturedElement[];
+} {
+  const fixed: CapturedElement[] = [];
+  const stripped = stripFromList(tree, fixed);
+  return { stripped, fixed };
+}
+
+function stripFromList(
+  list: CapturedElement[],
+  fixedOut: CapturedElement[],
+): CapturedElement[] {
+  const kept: CapturedElement[] = [];
+  for (const node of list) {
+    if (node.styles?.position === "fixed") {
+      fixedOut.push(node);
+      continue;
+    }
+    if (node.children != null && node.children.length > 0) {
+      const newChildren = stripFromList(node.children, fixedOut);
+      if (newChildren !== node.children) {
+        // At least one descendant was stripped — emit a shallow copy with the
+        // pruned child list so the caller's tree isn't mutated.
+        kept.push({ ...node, children: newChildren });
+        continue;
+      }
+    }
+    kept.push(node);
+  }
+  // If nothing was removed at this level, return the original list (lets
+  // ancestor levels avoid copying too).
+  if (kept.length === list.length && fixedOut.length === 0) return list;
+  return kept;
+}
+
+/**
+ * Cross-segment dedupe: capture 0's fixed elements are typically present in
+ * every segment too (the live page kept them fixed throughout the scroll).
+ * Returns the union of fixed elements seen across all segments, keyed by a
+ * coarse identity (tag + viewport position + size) so the same logical
+ * element captured at slightly different times (e.g. with a small text-style
+ * tweak) doesn't get emitted twice.
+ *
+ * v1 keeps the FIRST occurrence's subtree. Future work could pick the
+ * occurrence whose neighbours match the largest fraction of segments, or
+ * crossfade subtle variants — but for fixed site chrome the first occurrence
+ * is already what consumers see at scrollY=0.
+ */
+export function dedupeFixedAcrossSegments(perSegment: CapturedElement[][]): CapturedElement[] {
+  const seen = new Map<string, CapturedElement>();
+  for (const seg of perSegment) {
+    for (const el of seg) {
+      const key = fixedKey(el);
+      if (!seen.has(key)) seen.set(key, el);
+    }
+  }
+  return [...seen.values()];
+}
+
+function fixedKey(el: CapturedElement): string {
+  return `${el.tag}|${Math.round(el.x)},${Math.round(el.y)}|${Math.round(el.width)}x${Math.round(el.height)}`;
+}