domotion-svg 0.1.1

package/dist/stacking-context.test.js

@@ -0,0 +1,927 @@
+import { describe, expect, it } from "vitest";
+import { elementTreeToSvg } from "./dom-to-svg.js";
+/**
+ * DM-473: cross-stacking-context z-index unit tests.
+ *
+ * These exercise `establishesStackingContext` + `gatherStackingContextChildren`
+ * (both internal) by their observable effect on `elementTreeToSvg` output:
+ * the relative DOM order of `fill="rgb(...)"` rect emissions in the SVG
+ * string equals the paint order Chromium would use. The colours are unique
+ * per scenario so the fixture under test only needs to verify each colour
+ * appears in the expected sequence.
+ *
+ * Pairs with the integration fixtures in `tests/features.ts` (see the
+ * `z-index-cross-parent-non-context` / `z-index-stacking-context-boundary` /
+ * `z-index-negative-escapes` / `z-index-transform-stacking-context` blocks).
+ */
+function makeElement(overrides = {}) {
+    return {
+        tag: "div",
+        text: "",
+        x: 0,
+        y: 0,
+        width: 100,
+        height: 100,
+        children: [],
+        ...overrides,
+        styles: {
+            backgroundColor: "rgb(255,255,255)",
+            borderColor: "rgb(0,0,0)",
+            borderWidth: "0",
+            borderRadius: "0",
+            borderTopLeftRadius: "0",
+            borderTopRightRadius: "0",
+            borderBottomRightRadius: "0",
+            borderBottomLeftRadius: "0",
+            borderTopWidth: "0",
+            borderRightWidth: "0",
+            borderBottomWidth: "0",
+            borderLeftWidth: "0",
+            borderTopColor: "rgb(0,0,0)",
+            borderRightColor: "rgb(0,0,0)",
+            borderBottomColor: "rgb(0,0,0)",
+            borderLeftColor: "rgb(0,0,0)",
+            borderTopStyle: "none",
+            borderRightStyle: "none",
+            borderBottomStyle: "none",
+            borderLeftStyle: "none",
+            color: "rgb(0,0,0)",
+            fontSize: "16px",
+            fontFamily: "sans-serif",
+            fontWeight: "400",
+            fontStyle: "normal",
+            lineHeight: "20px",
+            letterSpacing: "normal",
+            textAlign: "left",
+            textTransform: "none",
+            textDecoration: "none",
+            textDecorationLine: "none",
+            textDecorationStyle: "solid",
+            textDecorationColor: "rgb(0,0,0)",
+            textDecorationThickness: "auto",
+            textUnderlineOffset: "auto",
+            whiteSpace: "normal",
+            wordSpacing: "0",
+            verticalAlign: "baseline",
+            direction: "ltr",
+            writingMode: "horizontal-tb",
+            textOverflow: "clip",
+            cursor: "auto",
+            caretColor: "auto",
+            outlineColor: "rgb(0,0,0)",
+            outlineWidth: "0",
+            outlineStyle: "none",
+            outlineOffset: "0",
+            boxShadow: "none",
+            opacity: "1",
+            transform: "none",
+            transformOrigin: "50% 50%",
+            visibility: "visible",
+            borderCollapse: "separate",
+            overflowX: "visible",
+            overflowY: "visible",
+            scrollbarGutter: "auto",
+            scrollWidth: 100,
+            scrollHeight: 100,
+            clientWidth: 100,
+            clientHeight: 100,
+            scrollTop: 0,
+            scrollLeft: 0,
+            objectFit: "fill",
+            objectPosition: "50% 50%",
+            filter: "none",
+            backdropFilter: "none",
+            mixBlendMode: "normal",
+            clipPath: "none",
+            mask: "none",
+            maskImage: "none",
+            maskMode: "match-source",
+            maskSize: "auto",
+            maskPosition: "0% 0%",
+            maskRepeat: "repeat",
+            maskComposite: "add",
+            listStyleType: "disc",
+            listStyleImage: "none",
+            display: "block",
+            listStylePosition: "outside",
+            backgroundImage: "none",
+            backgroundSize: "auto",
+            backgroundPosition: "0% 0%",
+            backgroundRepeat: "repeat",
+            backgroundClip: "border-box",
+            backgroundOrigin: "padding-box",
+            backgroundAttachment: "scroll",
+            paddingTop: "0",
+            paddingRight: "0",
+            paddingBottom: "0",
+            paddingLeft: "0",
+            borderImageSource: "none",
+            borderImageSlice: "100%",
+            borderImageWidth: "1",
+            borderImageOutset: "0",
+            borderImageRepeat: "stretch",
+            zIndex: "auto",
+            position: "static",
+            float: "none",
+            order: "0",
+            flexDirection: "row",
+            ...(overrides.styles ?? {}),
+        },
+    };
+}
+/** Returns the order of `fill="<color>"` occurrences in the SVG. */
+function fillOrder(svg, colors) {
+    const positions = colors
+        .map((c) => ({ c, i: svg.indexOf(`fill="${c}"`) }))
+        .filter((p) => p.i >= 0)
+        .sort((a, b) => a.i - b.i);
+    return positions.map((p) => p.c);
+}
+describe("DM-473 stacking-context paint order — cross-parent z-index", () => {
+    it("hoists positioned grandchild with z-index>0 above ancestor's later sibling when ancestor is non-SC", () => {
+        // Tree:
+        //   root (relative)
+        //   ├── red    (absolute, z:auto, NOT SC)        — bucket: zero/auto
+        //   │   └── blue  (absolute, z:1, SC)           — hoists to root, bucket: positive(1)
+        //   └── green  (absolute, z:auto, NOT SC)       — bucket: zero/auto, after red in DOM
+        //
+        // Paint order: bg → red → green → blue (blue hoists into positive(1) bucket
+        // so it paints AFTER both auto-bucket positioned siblings).
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: { ...makeElement().styles, position: "absolute", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(63,185,80)", "rgb(88,166,255)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // red painted first (z:auto, DOM order)
+            "rgb(63,185,80)", // green next (z:auto, after red)
+            "rgb(88,166,255)", // blue hoisted to positive(1) bucket — paints last
+        ]);
+    });
+    it("respects stacking-context boundary: z-index>5 inside SC doesn't escape to root", () => {
+        // Tree:
+        //   root
+        //   ├── red    (absolute, z:1, IS SC)          — bucket: positive(1)
+        //   │   └── blue  (absolute, z:5, SC)          — STAYS inside red's SC
+        //   └── green  (absolute, z:2, IS SC)          — bucket: positive(2), paints after red
+        //
+        // Paint order: red → blue (inside red) → green
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "5", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "2", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(88,166,255)", "rgb(63,185,80)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // red (z:1)
+            "rgb(88,166,255)", // blue inside red — DFS continues inside SC
+            "rgb(63,185,80)", // green (z:2) paints last
+        ]);
+    });
+    it("transform creates a stacking context — descendants don't escape", () => {
+        // Same shape as the boundary test but the SC root uses `transform`
+        // instead of an explicit z-index.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: {
+                            ...makeElement().styles,
+                            position: "absolute",
+                            transform: "translate(0px, 0px) matrix(1, 0, 0, 1, 0, 0)",
+                            transformOrigin: "60px 60px",
+                            backgroundColor: "rgb(220,38,38)",
+                        },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "5", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(88,166,255)", "rgb(63,185,80)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // red (transformed, SC root) — auto-z bucket at root
+            "rgb(88,166,255)", // blue inside red's SC
+            "rgb(63,185,80)", // green (z:1) paints last over both
+        ]);
+    });
+    it("negative z-index hoists below ancestor's earlier in-flow content", () => {
+        // Tree:
+        //   root (relative)
+        //   ├── gray  (absolute, z:auto)               — bucket: zero/auto
+        //   └── red   (absolute, z:auto, NOT SC)       — bucket: zero/auto (after gray)
+        //       └── blue (absolute, z:-1, SC)          — hoists to root, bucket: NEGATIVE
+        //
+        // Paint order: bg → blue (negative bucket, first) → gray → red.
+        // Visually: blue paints behind both gray and red.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 220, height: 50,
+                        styles: { ...makeElement().styles, position: "absolute", backgroundColor: "rgb(148,163,184)" },
+                    }),
+                    makeElement({
+                        x: 60, y: 40, width: 120, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 30, y: 20, width: 200, height: 120,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "-1", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(88,166,255)", "rgb(148,163,184)", "rgb(220,38,38)"]);
+        expect(order).toEqual([
+            "rgb(88,166,255)", // blue (z:-1) hoisted to negative bucket — paints first
+            "rgb(148,163,184)", // gray (z:auto)
+            "rgb(220,38,38)", // red (z:auto, after gray in DOM)
+        ]);
+    });
+    it("will-change: transform creates a stacking context (DM-498)", () => {
+        // Apple-style hero pattern: artwork wrapper has `will-change: transform`
+        // (no explicit transform value yet — author intends to animate). Per CSS
+        // spec, this MUST create a stacking context. Without DM-498, Domotion
+        // missed this and positioned descendants escaped past the wrapper into
+        // the parent SC's flat list, disrupting paint order.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: { ...makeElement().styles, position: "absolute", willChange: "transform", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "5", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(88,166,255)", "rgb(63,185,80)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // will-change wrapper (auto-z bucket at root, paints first)
+            "rgb(88,166,255)", // blue trapped INSIDE the SC
+            "rgb(63,185,80)", // green (z:1) paints last via positive bucket
+        ]);
+    });
+    it("contain: paint creates a stacking context (DM-498)", () => {
+        // `contain: paint | strict | content` per CSS Containment spec creates
+        // a stacking context. Mirrors the will-change test — descendants stay
+        // inside.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: { ...makeElement().styles, position: "absolute", contain: "paint", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "5", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(88,166,255)", "rgb(63,185,80)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)",
+            "rgb(88,166,255)",
+            "rgb(63,185,80)",
+        ]);
+    });
+    it("isolation: isolate creates a stacking context (DM-498)", () => {
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: { ...makeElement().styles, position: "absolute", isolation: "isolate", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "5", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(88,166,255)", "rgb(63,185,80)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)",
+            "rgb(88,166,255)",
+            "rgb(63,185,80)",
+        ]);
+    });
+    it("will-change: scroll-position does NOT create a stacking context", () => {
+        // CSS-Will-Change-1: only properties that themselves create SCs trigger
+        // SC formation when listed in will-change. `scroll-position` is not such
+        // a property — listing it should leave normal hoist behavior intact.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: { ...makeElement().styles, position: "absolute", willChange: "scroll-position", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                // z-index:5, but parent is NOT an SC → blue hoists to root SC.
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "5", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(88,166,255)", "rgb(63,185,80)"]);
+        // blue (z:5 hoisted to root) paints LAST — over green (z:1).
+        expect(order).toEqual([
+            "rgb(220,38,38)",
+            "rgb(63,185,80)",
+            "rgb(88,166,255)",
+        ]);
+    });
+    it("position:fixed/sticky always create a stacking context (modern CSS)", () => {
+        // A fixed-positioned ancestor with z-index:auto still creates an SC
+        // per the "modern CSS" rule. Its z-indexed descendants stay inside.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 240, height: 160,
+                styles: { ...makeElement().styles, position: "relative", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 10, y: 10, width: 120, height: 120,
+                        styles: { ...makeElement().styles, position: "fixed", backgroundColor: "rgb(220,38,38)" },
+                        children: [
+                            makeElement({
+                                x: 40, y: 40, width: 140, height: 90,
+                                styles: { ...makeElement().styles, position: "absolute", zIndex: "5", backgroundColor: "rgb(88,166,255)" },
+                            }),
+                        ],
+                    }),
+                    makeElement({
+                        x: 80, y: 50, width: 140, height: 80,
+                        styles: { ...makeElement().styles, position: "absolute", zIndex: "1", backgroundColor: "rgb(63,185,80)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 240, 160);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(88,166,255)", "rgb(63,185,80)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // fixed red (auto-z bucket at root)
+            "rgb(88,166,255)", // blue trapped inside red's SC
+            "rgb(63,185,80)", // green (z:1) paints last
+        ]);
+    });
+});
+describe("DM-525 flex/grid item z-index — stacking context without explicit positioning", () => {
+    // CSS Flexbox 1 §5.4 / CSS Grid 1: a flex/grid item with z-index ≠ auto
+    // creates a stacking context even when position:static, behaving as if
+    // position were relative. Without this, a static-positioned flex item
+    // with z-index:10 would NOT z-sort, and DOM order alone would decide
+    // overlapping paint — visible on `15-deep-flex-order-vs-z` (DM-525) where
+    // `<div class="item a" style="z-index: 10">A</div>` should pop above its
+    // overlapping siblings but Domotion painted it underneath.
+    it("paints a flex item with z-index:10 ABOVE its later DOM-order siblings (default position:static)", () => {
+        // Tree: a flex container with three static-positioned children.
+        // The first child has z-index:10 — per spec, it should paint LAST.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, display: "flex", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, zIndex: "10", backgroundColor: "rgb(220,38,38)" }, // red, z:10
+                    }),
+                    makeElement({
+                        x: 100, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, backgroundColor: "rgb(22,163,74)" }, // green, z:auto
+                    }),
+                    makeElement({
+                        x: 200, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, backgroundColor: "rgb(37,99,235)" }, // blue, z:auto
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(22,163,74)", "rgb(37,99,235)"]);
+        expect(order).toEqual([
+            "rgb(22,163,74)", // green (auto)
+            "rgb(37,99,235)", // blue (auto)
+            "rgb(220,38,38)", // red z:10 — paints LAST
+        ]);
+    });
+    it("z-sorts multiple flex items by their z-index, regardless of DOM order", () => {
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, display: "flex", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    // a: z:5 — should paint last
+                    makeElement({
+                        x: 0, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, zIndex: "5", backgroundColor: "rgb(220,38,38)" },
+                    }),
+                    // b: z:1 — paints between auto-bucket and z:5
+                    makeElement({
+                        x: 100, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, zIndex: "1", backgroundColor: "rgb(22,163,74)" },
+                    }),
+                    // c: z:auto — paints first (before any explicit-z item per CSS)
+                    makeElement({
+                        x: 200, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, backgroundColor: "rgb(37,99,235)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(22,163,74)", "rgb(37,99,235)"]);
+        expect(order).toEqual([
+            "rgb(37,99,235)", // c: auto-bucket
+            "rgb(22,163,74)", // b: z:1
+            "rgb(220,38,38)", // a: z:5 — last
+        ]);
+    });
+    it("does NOT z-sort children of a non-flex/grid container with z-index (DOM order preserved)", () => {
+        // Sanity check: a regular block container ignores z-index on static
+        // children — they paint in DOM order.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, display: "block", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, zIndex: "10", backgroundColor: "rgb(220,38,38)" }, // red, z:10 IGNORED
+                    }),
+                    makeElement({
+                        x: 0, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, backgroundColor: "rgb(22,163,74)" }, // green
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(22,163,74)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // DOM order: red first
+            "rgb(22,163,74)", // green second
+        ]);
+    });
+    it("treats grid items the same as flex items (display: grid)", () => {
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, display: "grid", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, zIndex: "10", backgroundColor: "rgb(220,38,38)" },
+                    }),
+                    makeElement({
+                        x: 100, y: 0, width: 100, height: 100,
+                        styles: { ...makeElement().styles, backgroundColor: "rgb(22,163,74)" },
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(22,163,74)"]);
+        expect(order).toEqual([
+            "rgb(22,163,74)", // green (auto)
+            "rgb(220,38,38)", // red z:10 — last
+        ]);
+    });
+});
+describe("DM-558 flex/grid item z-index — buried-inside-non-SC-ancestor hoist", () => {
+    // CSS Flexbox 1 §5.4 / CSS Grid 1 §17 promote a flex/grid item with
+    // explicit z-index to a stacking-context root even at position:static.
+    // When such an item is BURIED inside a non-SC ancestor's sub-tree (the
+    // flex item's parent is itself a non-SC element that's a child of the
+    // real SC root), the item must hoist into the real SC root's paint sort
+    // — otherwise it stays nested at its DOM-order depth and paints BEFORE
+    // a sibling positioned element that should be beneath it.
+    //
+    // Real-world case: apple.com hero `tile-wrapper > tile-content > tile-ctas
+    // > a.button` (button is a grid item of `tile-ctas` with z:4). Without
+    // this hoist, the captured background image (sibling of `tile-content`
+    // under `tile-wrapper`) painted on top of the button.
+    function fillOrder(svg, expectedColors) {
+        const fillRe = /fill="(rgb\([^)]+\))"/g;
+        const found = [];
+        let m;
+        while ((m = fillRe.exec(svg)) !== null) {
+            if (expectedColors.includes(m[1]) && !found.includes(m[1])) {
+                found.push(m[1]);
+            }
+        }
+        return found;
+    }
+    it("hoists a buried flex/grid-item-with-z above its non-SC parent's later sibling", () => {
+        // Mirror apple's structure simplified:
+        //   tile-wrapper (display:flex + overflow:clip → SC root)
+        //     ├─ tile-content (position:relative, z:auto — non-SC) [DOM 0]
+        //     │    └─ tile-ctas (display:grid)
+        //     │         └─ a.button (position:static, z:4) — must paint LAST
+        //     └─ tile-image-wrapper (position:absolute, z:auto — non-SC) [DOM 1]
+        //          └─ image-bg (the bg that wrongly painted on top of button)
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: {
+                    ...makeElement().styles,
+                    display: "flex",
+                    overflowX: "clip",
+                    overflowY: "clip",
+                    backgroundColor: "rgb(13,17,23)",
+                },
+                children: [
+                    // tile-content
+                    makeElement({
+                        x: 0, y: 0, width: 300, height: 100,
+                        styles: { ...makeElement().styles, display: "flex", position: "relative", backgroundColor: "rgb(255,255,255)" },
+                        children: [
+                            // tile-ctas (display:grid)
+                            makeElement({
+                                x: 100, y: 30, width: 100, height: 40,
+                                styles: { ...makeElement().styles, display: "grid", backgroundColor: "rgb(255,255,255)" },
+                                children: [
+                                    // a.button (grid-item with z:4, position:static)
+                                    makeElement({
+                                        x: 100, y: 30, width: 100, height: 40,
+                                        styles: { ...makeElement().styles, zIndex: "4", backgroundColor: "rgb(0,113,227)" }, // blue button
+                                    }),
+                                ],
+                            }),
+                        ],
+                    }),
+                    // tile-image-wrapper (positioned, covers same x range)
+                    makeElement({
+                        x: 0, y: 0, width: 300, height: 100,
+                        styles: { ...makeElement().styles, position: "absolute", backgroundColor: "rgb(220,38,38)" }, // red image bg
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        const order = fillOrder(svg, ["rgb(0,113,227)", "rgb(220,38,38)"]);
+        // tile-image-wrapper (red) must paint BEFORE the button (blue) so that
+        // the button is visible on top — matches Chromium for the real apple
+        // hero.
+        expect(order).toEqual([
+            "rgb(220,38,38)", // tile-image-wrapper
+            "rgb(0,113,227)", // a.button (hoisted past its non-SC ancestor)
+        ]);
+    });
+});
+describe("DM-537 flex/grid `order` property — paint follows order-modified document order", () => {
+    // CSS Flexbox 1 §5.4.1 / CSS Grid 1 §17: flex/grid items paint in
+    // order-modified document order (ascending `order`, ties broken by source
+    // order). The `order` property reorders both the visual layout AND the
+    // paint stack. This is the residual bug in `15-deep-flex-order-vs-z`
+    // section 2 after DM-525 fixed the explicit-z-index portion: items
+    // `order: 5,4,3,2,1` reverse the visual layout so E (order:1) is leftmost
+    // and A (order:5) is rightmost; with default z:auto Chrome paints E first
+    // and A last (visual L-to-R order). Domotion was painting in DOM order
+    // (A first, E last), which matched the source order rather than the
+    // order-modified one — visible as colored stripes at the box-overlap
+    // zones since the wrong sibling covered each overlap.
+    it("paints flex items in ascending `order` value (default z:auto)", () => {
+        // Tree: 5 flex items, A first in DOM with order:5 (visually rightmost)
+        // through E last in DOM with order:1 (visually leftmost). Paint must
+        // be E, D, C, B, A — visual L-to-R / order-modified.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 600, height: 60,
+                styles: { ...makeElement().styles, display: "flex", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({ x: 480, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, order: "5", backgroundColor: "rgb(220,38,38)" } }), // A
+                    makeElement({ x: 360, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, order: "4", backgroundColor: "rgb(22,163,74)" } }), // B
+                    makeElement({ x: 240, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, order: "3", backgroundColor: "rgb(37,99,235)" } }), // C
+                    makeElement({ x: 120, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, order: "2", backgroundColor: "rgb(234,88,12)" } }), // D
+                    makeElement({ x: 0, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, order: "1", backgroundColor: "rgb(124,58,237)" } }), // E
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 600, 60);
+        const order = fillOrder(svg, [
+            "rgb(220,38,38)", "rgb(22,163,74)", "rgb(37,99,235)", "rgb(234,88,12)", "rgb(124,58,237)",
+        ]);
+        expect(order).toEqual([
+            "rgb(124,58,237)", // E (order:1) first
+            "rgb(234,88,12)", // D (order:2)
+            "rgb(37,99,235)", // C (order:3)
+            "rgb(22,163,74)", // B (order:4)
+            "rgb(220,38,38)", // A (order:5) last/top
+        ]);
+    });
+    it("breaks `order` ties with source (DOM) order", () => {
+        // Two items share order:0, two share order:1. Within each bucket the
+        // painted-first is the one earlier in DOM order.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 400, height: 60,
+                styles: { ...makeElement().styles, display: "flex", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({ x: 0, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "1", backgroundColor: "rgb(220,38,38)" } }), // red, order:1, DOM 0
+                    makeElement({ x: 100, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "0", backgroundColor: "rgb(22,163,74)" } }), // green, order:0, DOM 1
+                    makeElement({ x: 200, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "1", backgroundColor: "rgb(37,99,235)" } }), // blue, order:1, DOM 2
+                    makeElement({ x: 300, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "0", backgroundColor: "rgb(234,88,12)" } }), // orange, order:0, DOM 3
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 400, 60);
+        const order = fillOrder(svg, [
+            "rgb(220,38,38)", "rgb(22,163,74)", "rgb(37,99,235)", "rgb(234,88,12)",
+        ]);
+        expect(order).toEqual([
+            "rgb(22,163,74)", // green (order:0, DOM 1) — first
+            "rgb(234,88,12)", // orange (order:0, DOM 3)
+            "rgb(220,38,38)", // red (order:1, DOM 0)
+            "rgb(37,99,235)", // blue (order:1, DOM 2) — last
+        ]);
+    });
+    it("ignores `order` on children of a non-flex/non-grid container (DOM order preserved)", () => {
+        // Plain block container — `order` has no effect.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 200, height: 60,
+                styles: { ...makeElement().styles, display: "block", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({ x: 0, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "5", backgroundColor: "rgb(220,38,38)" } }),
+                    makeElement({ x: 100, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "1", backgroundColor: "rgb(22,163,74)" } }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 200, 60);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(22,163,74)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // DOM order — `order` ignored
+            "rgb(22,163,74)",
+        ]);
+    });
+    it("reverses paint order for flex-direction:row-reverse (visually-rightmost paints last)", () => {
+        // Section 3 of `15-deep-flex-order-vs-z`: 5 items in DOM order A,B,C,D,E
+        // inside `flex-direction: row-reverse` with no `order` on items. Items
+        // pack from main-start (right) so visual L-to-R is E,D,C,B,A. Chrome
+        // empirically paints in REVERSE DOM order — E first, A last — which
+        // ends up matching visual L-to-R. Without this rule Domotion painted
+        // in source order (A first, E last) and the colored stripes at the
+        // box-overlap zones diff'd because the wrong sibling owned each
+        // overlap (DM-537 follow-up to DM-525).
+        const tree = [makeElement({
+                x: 0, y: 0, width: 600, height: 60,
+                styles: { ...makeElement().styles, display: "flex", flexDirection: "row-reverse", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({ x: 480, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, backgroundColor: "rgb(220,38,38)" } }), // A — DOM 0, visually rightmost
+                    makeElement({ x: 360, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, backgroundColor: "rgb(22,163,74)" } }), // B
+                    makeElement({ x: 240, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, backgroundColor: "rgb(37,99,235)" } }), // C
+                    makeElement({ x: 120, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, backgroundColor: "rgb(234,88,12)" } }), // D
+                    makeElement({ x: 0, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, backgroundColor: "rgb(124,58,237)" } }), // E — DOM 4, visually leftmost
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 600, 60);
+        const order = fillOrder(svg, [
+            "rgb(220,38,38)", "rgb(22,163,74)", "rgb(37,99,235)", "rgb(234,88,12)", "rgb(124,58,237)",
+        ]);
+        expect(order).toEqual([
+            "rgb(124,58,237)", // E (DOM-last) paints first under row-reverse
+            "rgb(234,88,12)", // D
+            "rgb(37,99,235)", // C
+            "rgb(22,163,74)", // B
+            "rgb(220,38,38)", // A (DOM-first, visually rightmost) paints last/top
+        ]);
+    });
+    it("does NOT reverse paint order for flex-direction:row (default — DOM order)", () => {
+        // Section 1 sanity: same items but `flex-direction: row` (default) with
+        // no `order` set → paint = source/DOM order, A first, E last.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 600, height: 60,
+                styles: { ...makeElement().styles, display: "flex", flexDirection: "row", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({ x: 0, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, backgroundColor: "rgb(220,38,38)" } }),
+                    makeElement({ x: 120, y: 0, width: 120, height: 60, styles: { ...makeElement().styles, backgroundColor: "rgb(124,58,237)" } }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 600, 60);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(124,58,237)"]);
+        expect(order).toEqual(["rgb(220,38,38)", "rgb(124,58,237)"]);
+    });
+    it("combines `order` reordering with explicit z-index buckets (z-index wins)", () => {
+        // green has order:5 (visually last) but z:1 — should paint AFTER red
+        // (z:auto) regardless of order. Red is order:1 (visually first) z:auto.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 200, height: 60,
+                styles: { ...makeElement().styles, display: "flex", backgroundColor: "rgb(13,17,23)" },
+                children: [
+                    makeElement({ x: 100, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "5", zIndex: "1", backgroundColor: "rgb(22,163,74)" } }), // green
+                    makeElement({ x: 0, y: 0, width: 100, height: 60, styles: { ...makeElement().styles, order: "1", backgroundColor: "rgb(220,38,38)" } }), // red
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 200, 60);
+        const order = fillOrder(svg, ["rgb(220,38,38)", "rgb(22,163,74)"]);
+        expect(order).toEqual([
+            "rgb(220,38,38)", // red (auto bucket — paints before any explicit-z item)
+            "rgb(22,163,74)", // green (z:1 — last)
+        ]);
+    });
+});
+describe("DM-543 position:fixed escapes ancestor overflow clips", () => {
+    // CSS painting order: position:fixed paints in the viewport stacking
+    // context and escapes ALL ancestor overflow clips — UNLESS an ancestor
+    // creates a containing block for fixed (transform / filter / will-change:
+    // <transform|filter|perspective> / contain: <paint|strict|content|layout>),
+    // in which case the descendant is anchored to that ancestor and respects
+    // its clipping.
+    // The renderer wraps an overflow-clipping ancestor's children in
+    // `<g clip-path="url(#ovN)">`. We verify "escaped" vs "trapped" by
+    // checking whether the pin's fill appears AFTER the closing </g> of the
+    // clip group (escaped) or before it (trapped).
+    function clipState(svg, pinFill) {
+        const pinIdx = svg.indexOf(`fill="${pinFill}"`);
+        if (pinIdx < 0)
+            return "missing";
+        // Walk all <g.../</g> tokens up to pinIdx, tracking the open-tag stack.
+        // The pin is "trapped" if any frame on the stack at pinIdx is a
+        // clip-path group; "escaped" otherwise.
+        const tokens = svg.slice(0, pinIdx).matchAll(/<g\b[^>]*>|<\/g>/g);
+        const stack = [];
+        for (const t of tokens) {
+            const s = t[0];
+            if (s === "</g>")
+                stack.pop();
+            else
+                stack.push(s);
+        }
+        return stack.some((s) => s.includes('clip-path="url(#ov')) ? "trapped" : "escaped";
+    }
+    it("hoists position:fixed inside an overflow:auto SC ancestor to the root SC", () => {
+        // Tree:
+        //   section (overflow:auto SC, NOT a fixed CB)
+        //     innerDiv (static, no CB)
+        //       pin (position:fixed)  ← should escape section's clip-path group
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, backgroundColor: "rgb(248,250,252)", overflowX: "auto", overflowY: "auto" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 300, height: 200,
+                        styles: { ...makeElement().styles, backgroundColor: "rgb(241,245,249)" },
+                        children: [
+                            makeElement({
+                                x: 250, y: 80, width: 40, height: 16,
+                                styles: { ...makeElement().styles, position: "fixed", backgroundColor: "rgb(220,38,38)" },
+                            }),
+                        ],
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        expect(clipState(svg, "rgb(220,38,38)")).toBe("escaped");
+    });
+    it("traps position:fixed inside a transform-CB ancestor (does not over-escape)", () => {
+        // Tree:
+        //   section (overflow:auto SC, NOT a fixed CB)
+        //     frame (transform:translate(0) — IS a fixed CB)
+        //       pin (position:fixed)  ← stays trapped under frame inside section's clip
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, backgroundColor: "rgb(248,250,252)", overflowX: "auto", overflowY: "auto" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 300, height: 200,
+                        styles: { ...makeElement().styles, position: "relative", transform: "matrix(1, 0, 0, 1, 0, 0)", backgroundColor: "rgb(254,243,199)" },
+                        children: [
+                            makeElement({
+                                x: 250, y: 180, width: 40, height: 16,
+                                styles: { ...makeElement().styles, position: "fixed", backgroundColor: "rgb(220,38,38)" },
+                            }),
+                        ],
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        expect(clipState(svg, "rgb(220,38,38)")).toBe("trapped");
+    });
+    it("traps position:fixed inside a contain:paint ancestor", () => {
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, backgroundColor: "rgb(248,250,252)", overflowX: "auto", overflowY: "auto" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 300, height: 200,
+                        styles: { ...makeElement().styles, position: "relative", contain: "paint", backgroundColor: "rgb(254,243,199)" },
+                        children: [
+                            makeElement({
+                                x: 250, y: 180, width: 40, height: 16,
+                                styles: { ...makeElement().styles, position: "fixed", backgroundColor: "rgb(220,38,38)" },
+                            }),
+                        ],
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        expect(clipState(svg, "rgb(220,38,38)")).toBe("trapped");
+    });
+    it("traps position:fixed inside a will-change:transform ancestor", () => {
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, backgroundColor: "rgb(248,250,252)", overflowX: "auto", overflowY: "auto" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 300, height: 200,
+                        styles: { ...makeElement().styles, position: "relative", willChange: "transform", backgroundColor: "rgb(254,243,199)" },
+                        children: [
+                            makeElement({
+                                x: 250, y: 180, width: 40, height: 16,
+                                styles: { ...makeElement().styles, position: "fixed", backgroundColor: "rgb(220,38,38)" },
+                            }),
+                        ],
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        expect(clipState(svg, "rgb(220,38,38)")).toBe("trapped");
+    });
+    it("hoists position:fixed past nested non-CB SC ancestors (overflow scroller inside overflow scroller)", () => {
+        // section1 (overflow:auto) > section2 (overflow:auto) > pin (fixed)
+        // Both scrollers are SCs but neither is a fixed-CB; pin escapes to root.
+        const tree = [makeElement({
+                x: 0, y: 0, width: 300, height: 100,
+                styles: { ...makeElement().styles, backgroundColor: "rgb(248,250,252)", overflowX: "auto", overflowY: "auto" },
+                children: [
+                    makeElement({
+                        x: 0, y: 0, width: 300, height: 200,
+                        styles: { ...makeElement().styles, backgroundColor: "rgb(241,245,249)", overflowX: "auto", overflowY: "auto" },
+                        children: [
+                            makeElement({
+                                x: 250, y: 80, width: 40, height: 16,
+                                styles: { ...makeElement().styles, position: "fixed", backgroundColor: "rgb(220,38,38)" },
+                            }),
+                        ],
+                    }),
+                ],
+            })];
+        const svg = elementTreeToSvg(tree, 300, 100);
+        expect(clipState(svg, "rgb(220,38,38)")).toBe("escaped");
+    });
+});