domotion-svg 0.28.1 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domotion-svg",
-  "version": "0.28.1",
+  "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",