domotion-svg 0.28.0 → 0.28.2

package/dist/scroll/composer.d.ts

@@ -21,6 +21,8 @@
  * shrinking output size on mostly-static-content pages.
  */
 import type { ScrollSegmentCapture } from "./executor.js";
+import type { CapturedElement } from "../capture/types.js";
+import { type ChildOverflowClipGeometry } from "../render/element-tree-to-svg.js";
 import { type RenderTextMode } from "../render/text-to-path.js";
 export interface ScrollComposerOptions {
     /** Visible viewport width (output SVG width). */
@@ -75,6 +77,20 @@ export interface ScrollComposerOptions {
      */
     renderText?: RenderTextMode;
 }
+export interface ElementScrollStaticLayers {
+    underlay: CapturedElement[];
+    foregroundLayers: Array<{
+        elements: CapturedElement[];
+        clips: ChildOverflowClipGeometry[];
+    }>;
+}
+/**
+ * Split the static context around an element scroll owner's paint slot at each
+ * ancestor level. Siblings which paint after the owner branch must remain
+ * stationary but render above its moving captures; leaving them in one
+ * wholesale underlay reverses CSS z-order wherever the two overlap.
+ */
+export declare function splitElementScrollStaticLayers(tree: CapturedElement[], ownerId: string): ElementScrollStaticLayers | null;
 /**
  * Fail closed before composition when frame/allowlist/offset authority is
  * omitted, stale, or assigned to a sibling Chromium frame.

package/dist/scroll/composer.js

@@ -31,6 +31,7 @@ import { hoistDuplicateImagePayloads } from "../post-processing/hoist-image-payl
 import { extractFixedSubtrees, dedupeFixedAcrossSegments } from "./hoist-fixed.js";
 import { extractStickyWindows } from "./hoist-sticky.js";
 import { mapTreePruning } from "../tree-ops/prune-tree.js";
+import { sortChildrenByPaintOrder } from "../render/stacking.js";
 /**
  * Map a parsed scroll-action easing (DM-1076) to a CSS `<timing-function>`, or
  * `null` when it's absent or `linear` — the composite's animation-level default
@@ -94,6 +95,41 @@ function findCapturedScrollOwnerPath(tree, ownerId, ancestors = []) {
     }
     return undefined;
 }
+/**
+ * Split the static context around an element scroll owner's paint slot at each
+ * ancestor level. Siblings which paint after the owner branch must remain
+ * stationary but render above its moving captures; leaving them in one
+ * wholesale underlay reverses CSS z-order wherever the two overlap.
+ */
+export function splitElementScrollStaticLayers(tree, ownerId) {
+    const ownerPath = findCapturedScrollOwnerPath(tree, ownerId);
+    const owner = ownerPath?.at(-1);
+    if (ownerPath == null || owner == null || ownerPath.length < 2)
+        return null;
+    const foregroundLayers = [];
+    const foregroundSet = new Set();
+    for (let branchIndex = ownerPath.length - 1; branchIndex >= 1; branchIndex--) {
+        const parent = ownerPath[branchIndex - 1];
+        const branch = ownerPath[branchIndex];
+        const paintOrderedSiblings = sortChildrenByPaintOrder(parent.children, parent.styles.display, parent.styles.flexDirection);
+        const branchPaintIndex = paintOrderedSiblings.indexOf(branch);
+        if (branchPaintIndex < 0)
+            return null;
+        const elements = paintOrderedSiblings.slice(branchPaintIndex + 1);
+        if (elements.length === 0)
+            continue;
+        for (const element of elements)
+            foregroundSet.add(element);
+        foregroundLayers.push({
+            elements,
+            // A sibling shares the branch's clip ancestors but is not a descendant
+            // of the branch's own overflow clip.
+            clips: ownerPath.slice(0, branchIndex).map((element) => childOverflowClipGeometry(element)).filter((clip) => clip != null),
+        });
+    }
+    const underlay = mapTreePruning(tree, (element) => element === owner || foregroundSet.has(element));
+    return { underlay, foregroundLayers };
+}
 /**
  * An element scroll owner moves its own clipped contents, not the page around
  * it. Keep the first capture's surrounding page as a static underlay and feed
@@ -114,7 +150,9 @@ function isolateElementScrollOwner(segments) {
     // the established list-strip contract; there is no surrounding page to pin.
     if (firstOwnerPath == null || firstOwner == null || first.tree.includes(firstOwner))
         return null;
-    const staticUnderlay = mapTreePruning(first.tree, (element) => element.scrollbars?.owner?.ownerId === first.scrollOwnerId);
+    const staticLayers = splitElementScrollStaticLayers(first.tree, first.scrollOwnerId);
+    if (staticLayers == null)
+        return null;
     const isolated = segments.map((segment, index) => {
         if (segment.frameScrollState == null || segment.scrollOwnerId == null) {
             throw new Error(`composeScrollSvg: inner-scroll segment ${index} omitted its owner authority`);
@@ -136,7 +174,8 @@ function isolateElementScrollOwner(segments) {
     });
     return {
         segments: isolated,
-        staticUnderlay,
+        staticUnderlay: staticLayers.underlay,
+        staticForegroundLayers: staticLayers.foregroundLayers,
         ownerClips: firstOwnerPath.map((element) => childOverflowClipGeometry(element)).filter((clip) => clip != null),
     };
 }
@@ -329,6 +368,7 @@ export function composeScrollSvg(segments, opts) {
         return withRenderTextMode(renderTextMode, () => composeScrollSvgBody(composedSegments, opts, {
             axis, W, VH, bg, paintBg, hiDPIFactor, chunkSize,
             staticUnderlay: elementScroll?.staticUnderlay,
+            staticForegroundLayers: elementScroll?.staticForegroundLayers,
             elementOwnerClips: elementScroll?.ownerClips,
         }));
     }
@@ -385,7 +425,7 @@ function buildScrollVisibility(segments, segOffsets, totalMs) {
  * reads (axis / viewport / background / hiDPI / chunk size).
  */
 function composeScrollSvgBody(segments, opts, ctx) {
-    const { axis, W, VH, bg, paintBg, hiDPIFactor, chunkSize, staticUnderlay, elementOwnerClips, } = ctx;
+    const { axis, W, VH, bg, paintBg, hiDPIFactor, chunkSize, staticUnderlay, staticForegroundLayers, elementOwnerClips, } = ctx;
     // ── Total scene duration ──
     // The last segment's endMs is the cycle length. For a single-segment input,
     // the scene is effectively static — emit a 1 s loop so the SVG renders
@@ -568,6 +608,14 @@ function composeScrollSvgBody(segments, opts, ctx) {
         : `\n    <g data-scroll-static-context="true"><svg x="0" y="0" width="${W}" height="${VH}" viewBox="0 0 ${W} ${VH}">` +
             elementTreeToSvgInner(staticUnderlay, W, VH, "static-", false, hiDPIFactor, false) +
             `</svg></g>`;
+    const staticForegroundMarkup = (staticForegroundLayers ?? []).map((layer, layerIndex) => {
+        const clipOpen = layer.clips.map((_clip, clipIndex) => `    <g clip-path="url(#${animClass}-foreground-${layerIndex}-clip-${clipIndex})">`).join("\n");
+        const clipClose = layer.clips.map(() => "    </g>").join("\n");
+        const markup = `<g data-scroll-static-foreground="true"><svg x="0" y="0" width="${W}" height="${VH}" viewBox="0 0 ${W} ${VH}">` +
+            elementTreeToSvgInner(layer.elements, W, VH, `static-foreground-${layerIndex}-`, false, hiDPIFactor, false) +
+            `</svg></g>`;
+        return `${clipOpen === "" ? "" : clipOpen + "\n"}    ${markup}\n${clipClose}`;
+    }).join("\n");
     // 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
@@ -585,6 +633,7 @@ function composeScrollSvgBody(segments, opts, ctx) {
     const ownerClipDefs = (elementOwnerClips ?? []).map((clip, index) => `    <clipPath id="${animClass}-owner-clip-${index}">${roundedRectSvg(clip.x, clip.y, clip.width, clip.height, clip.corners, "")}</clipPath>`).join("\n");
     const ownerClipOpen = (elementOwnerClips ?? []).map((_clip, index) => `    <g clip-path="url(#${animClass}-owner-clip-${index})">`).join("\n");
     const ownerClipClose = (elementOwnerClips ?? []).map(() => "    </g>").join("\n");
+    const foregroundClipDefs = (staticForegroundLayers ?? []).flatMap((layer, layerIndex) => layer.clips.map((clip, clipIndex) => `    <clipPath id="${animClass}-foreground-${layerIndex}-clip-${clipIndex}">${roundedRectSvg(clip.x, clip.y, clip.width, clip.height, clip.corners, "")}</clipPath>`)).join("\n");
     // ── Compose final SVG ──
     // Share each raster payload across the segments that show it (the `<image>`
     // emit is per-element, and a scroll composite repeats a sticky header /
@@ -594,7 +643,7 @@ function composeScrollSvgBody(segments, opts, ctx) {
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${VH}" width="${W}" height="${VH}"${a11y.roleAttr}>${a11y.markup}
   <defs>
     <clipPath id="${animClass}-clip"><rect width="${W}" height="${VH}"/></clipPath>
-${ownerClipDefs === "" ? "" : ownerClipDefs + "\n"}${glyphDefs !== "" ? `    ${glyphDefs}\n` : ""}    <style>
+${ownerClipDefs === "" ? "" : ownerClipDefs + "\n"}${foregroundClipDefs === "" ? "" : foregroundClipDefs + "\n"}${glyphDefs !== "" ? `    ${glyphDefs}\n` : ""}    <style>
 ${fontFaceCss !== "" ? fontFaceCss + "\n" : ""}      .${animClass} { animation: ${animClass} ${totalSec.toFixed(3)}s linear infinite; will-change: transform; }
       @keyframes ${animClass} {
 ${keyframes}
@@ -615,6 +664,7 @@ ${paintBg ? `        <rect width="${compositeW}" height="${compositeH}" fill="${
       </svg>
     </g>
 ${ownerClipClose === "" ? "" : ownerClipClose + "\n"}
+${staticForegroundMarkup === "" ? "" : staticForegroundMarkup + "\n"}
   </g>${overlayMarkup}
 </svg>`);
 }

package/dist/scroll/executor.d.ts

@@ -117,6 +117,10 @@ export interface PageStateSnapshot {
     maxScrollY: number;
     /** Maximum scrollable x. */
     maxScrollX: number;
+    /** Width of the live scroll owner's content viewport, when available. */
+    clientWidth?: number;
+    /** Height of the live scroll owner's content viewport, when available. */
+    clientHeight?: number;
     /** Current scroll position. */
     scrollX: number;
     scrollY: number;
@@ -133,6 +137,15 @@ export interface PageQuery {
     /** Bbox of an element matching the CSS selector, in document coordinates. */
     selectorBbox(css: string): Promise<SelectorBbox | null>;
 }
+/**
+ * Size of one contiguous captured slice along the active scroll axis.
+ *
+ * Window-owned captures fill the configured output viewport. Element-owned
+ * captures only fill the element's client box, even when a larger ancestor or
+ * the whole body is captured around them. Stepping an element by the outer
+ * frame size would therefore leave uncaptured bands in the moving stack.
+ */
+export declare function scrollCaptureChunkSize(axis: ScrollAxis, viewport: Pick<ScrollExecutorOptions, "viewportW" | "viewportH">, snapshot: PageStateSnapshot, elementOwned: boolean): number;
 /**
  * Resolve an `AbsoluteTarget` AST node to an absolute scroll position along
  * the given axis. Returns the position in scroll-coordinate space (i.e. the

package/dist/scroll/executor.js

@@ -76,6 +76,23 @@ function directionSign(action) {
         return 1;
     return -1;
 }
+/**
+ * Size of one contiguous captured slice along the active scroll axis.
+ *
+ * Window-owned captures fill the configured output viewport. Element-owned
+ * captures only fill the element's client box, even when a larger ancestor or
+ * the whole body is captured around them. Stepping an element by the outer
+ * frame size would therefore leave uncaptured bands in the moving stack.
+ */
+export function scrollCaptureChunkSize(axis, viewport, snapshot, elementOwned) {
+    const outputSize = axis === "x" ? viewport.viewportW : viewport.viewportH;
+    if (!elementOwned)
+        return outputSize;
+    const ownerSize = axis === "x" ? snapshot.clientWidth : snapshot.clientHeight;
+    return typeof ownerSize === "number" && Number.isFinite(ownerSize) && ownerSize > 0
+        ? ownerSize
+        : outputSize;
+}
 /**
  * Resolve an `AbsoluteTarget` AST node to an absolute scroll position along
  * the given axis. Returns the position in scroll-coordinate space (i.e. the
@@ -286,27 +303,26 @@ export async function executeScrollPattern(page, pattern, opts) {
         }
         // op.kind === "scroll"
         // DM-604 §4(a): for smooth-mode scrolls (single long action covering
-        // multiple viewport-heights), subdivide into viewport-height chunks so
-        // the composer has enough anchor points to stack contiguously. Without
-        // this, a `down:bottom/30s` action on a 10000-tall page produces only
-        // two captures (initial + post-scroll), and the composite ends up with
-        // 9400 px of empty space between them. ScrollPattern-mode scrolls with
-        // explicit per-token magnitudes ≤ viewport height naturally produce
-        // one chunk per token — no over-subdivision there.
+        // multiple visible slices), subdivide by the selected owner's captured
+        // scrollport so the composer has enough anchor points to stack
+        // contiguously. For the page owner that slice is the configured output
+        // viewport; for an element owner it is the element's client box, which can
+        // be much smaller than a surrounding body capture. Without this, a long
+        // action produces only its endpoints and the composite has an uncaptured
+        // band between them. ScrollPattern-mode scrolls with explicit per-token
+        // magnitudes ≤ one slice naturally produce one chunk per token.
         //
-        // DM-633: chunks MUST land at exact viewport-height multiples (not
-        // evenly-distributed fractions of totalDelta). Each segment's captured
-        // tree fills the entire viewport at its scrollY, so the composer stacks
-        // each VH-tall slice at composite y = scrollY. If consecutive scrollYs
-        // are closer than VH (e.g. 784 px increments when VH = 844), segments
-        // overlap by `VH - delta` and the upper segment's `position: fixed`
-        // header bleeds into the lower segment's tail — visible as a duplicate
-        // nav bar at the bottom of the viewport at t=0.
+        // DM-633: chunks MUST land at exact captured-slice multiples (not
+        // evenly-distributed fractions of totalDelta). Each segment contributes
+        // one visible owner slice at its scroll offset, so the composer stacks it
+        // at that coordinate. For window owners, closer-than-viewport anchors
+        // overlap and can duplicate fixed paint. For element owners, farther-than-
+        // client-box anchors leave a blank band between captured slices.
         const snap0 = await pageQuery.snapshot();
         const dx = op.destX - snap0.scrollX;
         const dy = op.destY - snap0.scrollY;
         const totalDelta = op.axis === "x" ? dx : dy;
-        const viewportSize = op.axis === "x" ? opts.viewportW : opts.viewportH;
+        const viewportSize = scrollCaptureChunkSize(op.axis, opts, snap0, selector != null);
         const numChunks = Math.max(1, Math.ceil(Math.abs(totalDelta) / viewportSize));
         const dir = totalDelta >= 0 ? 1 : -1;
         for (let ci = 1; ci <= numChunks; ci++) {
@@ -314,7 +330,7 @@ export async function executeScrollPattern(page, pattern, opts) {
             // tile contiguously (no overlap, no gap) in the composer. The final
             // chunk clamps to op.destX/op.destY so the scroll completes at the
             // intended target — that single clamped step may overlap the prior
-            // chunk by < VH, but it only affects the last animation frame and
+            // chunk by less than one slice, but it only affects the last frame and
             // never the much-more-common mid-scroll frames.
             const isLast = ci === numChunks;
             const chunkDestX = op.axis === "x"
@@ -517,17 +533,22 @@ function realPageQuery(page, selector) {
                 return page.evaluate(() => ({
                     maxScrollX: Math.max(0, document.documentElement.scrollWidth - document.documentElement.clientWidth),
                     maxScrollY: Math.max(0, document.documentElement.scrollHeight - document.documentElement.clientHeight),
+                    clientWidth: document.documentElement.clientWidth,
+                    clientHeight: document.documentElement.clientHeight,
                     scrollX: window.scrollX,
                     scrollY: window.scrollY,
                 }));
             }
             return page.evaluate((sel) => {
                 const el = document.querySelector(sel);
-                if (!(el instanceof HTMLElement))
-                    return { maxScrollX: 0, maxScrollY: 0, scrollX: 0, scrollY: 0 };
+                if (!(el instanceof HTMLElement)) {
+                    return { maxScrollX: 0, maxScrollY: 0, clientWidth: 0, clientHeight: 0, scrollX: 0, scrollY: 0 };
+                }
                 return {
                     maxScrollX: Math.max(0, el.scrollWidth - el.clientWidth),
                     maxScrollY: Math.max(0, el.scrollHeight - el.clientHeight),
+                    clientWidth: el.clientWidth,
+                    clientHeight: el.clientHeight,
                     scrollX: el.scrollLeft,
                     scrollY: el.scrollTop,
                 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domotion-svg",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "description": "DOM-to-animated-SVG renderer. Captures HTML/CSS via Playwright Chromium and converts it to self-contained SVG with CSS animations — pixel-faithful demos that scale crisply and load lazily.",
   "license": "MIT",
   "author": "Brian Westphal",