@livetemplate/client 0.11.5 → 0.11.7

package/dist/tests/directives.test.js

@@ -900,4 +900,1095 @@ describe("handleShadowRootHydration", () => {
         });
     });
 });
+describe("handleAreaSelectDirectives", () => {
+    // The module-level areaSelectArmed map is cleared lazily — the sweep
+    // only fires when handleAreaSelectDirectives runs. Without an explicit
+    // afterEach, tests that don't call it would inherit armed elements
+    // from prior tests. teardownAreaSelectForRoot(document.body) wipes
+    // every entry so each test gets a fresh slate.
+    afterEach(() => {
+        (0, directives_1.teardownAreaSelectForRoot)(document.body);
+    });
+    // jsdom-friendly helper: configure the target element so it has a
+    // non-trivial bounding rect (jsdom returns zeros by default) and a
+    // positioned parent so the overlay has somewhere to land. Returns
+    // [target, parent] for the assertions.
+    function mountTarget(targetTag, attrs, rect) {
+        document.body.innerHTML = `
+      <div id="parent" style="position:relative;">
+        <${targetTag} id="target"></${targetTag}>
+      </div>
+    `;
+        const target = document.getElementById("target");
+        const parent = document.getElementById("parent");
+        for (const [k, v] of Object.entries(attrs))
+            target.setAttribute(k, v);
+        target.getBoundingClientRect = jest.fn(() => ({
+            x: rect.left,
+            y: rect.top,
+            left: rect.left,
+            top: rect.top,
+            right: rect.left + rect.width,
+            bottom: rect.top + rect.height,
+            width: rect.width,
+            height: rect.height,
+            toJSON: () => ({}),
+        }));
+        parent.getBoundingClientRect = jest.fn(() => ({
+            x: rect.left,
+            y: rect.top,
+            left: rect.left,
+            top: rect.top,
+            right: rect.left + rect.width,
+            bottom: rect.top + rect.height,
+            width: rect.width,
+            height: rect.height,
+            toJSON: () => ({}),
+        }));
+        // jsdom doesn't implement pointer-capture; stub so the directive's
+        // try/catch around it doesn't matter, but the test still asserts
+        // the contract.
+        target.setPointerCapture = jest.fn();
+        target.releasePointerCapture = jest.fn();
+        return [target, parent];
+    }
+    function dispatchPointer(el, type, clientX, clientY, pointerId = 1) {
+        const e = new MouseEvent(type, { clientX, clientY, button: 0, bubbles: true });
+        // PointerEvent isn't fully supported in jsdom but the directive
+        // only reads pointerId / isPrimary / button / clientX / clientY.
+        Object.defineProperty(e, "pointerId", { value: pointerId });
+        Object.defineProperty(e, "isPrimary", { value: true });
+        el.dispatchEvent(e);
+    }
+    beforeEach(() => {
+        document.body.innerHTML = "";
+        jest.spyOn(console, "warn").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it("dispatches the action with 0..1 fraction coords on pointerup", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 100, top: 50, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Drag from (120, 80) → (220, 150) inside the rect.
+        // x = (120 - 100) / 200 = 0.10
+        // y = (80 - 50)   / 200 = 0.15
+        // w = (220 - 120) / 200 = 0.50
+        // h = (150 - 80)  / 200 = 0.35
+        dispatchPointer(target, "pointerdown", 120, 80);
+        dispatchPointer(target, "pointermove", 220, 150);
+        dispatchPointer(target, "pointerup", 220, 150);
+        expect(send).toHaveBeenCalledTimes(1);
+        const msg = send.mock.calls[0][0];
+        expect(msg.action).toBe("selectImageArea");
+        expect(msg.data.x).toBeCloseTo(0.10, 5);
+        expect(msg.data.y).toBeCloseTo(0.15, 5);
+        expect(msg.data.w).toBeCloseTo(0.50, 5);
+        expect(msg.data.h).toBeCloseTo(0.35, 5);
+    });
+    it("filters drags smaller than the min-fraction threshold", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 1000, height: 1000 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Drag is 10×10 px on a 1000×1000 rect → 1% fraction in both dims.
+        // 1% < MIN_AREA_FRACTION (2%) → must drop.
+        dispatchPointer(target, "pointerdown", 100, 100);
+        dispatchPointer(target, "pointermove", 110, 110);
+        dispatchPointer(target, "pointerup", 110, 110);
+        expect(send).not.toHaveBeenCalled();
+        // Overlay should have been cleaned up after the failed drag.
+        expect(document.querySelectorAll(".lvt-area-select-overlay").length).toBe(0);
+    });
+    it("paints an overlay during the drag and removes it on release", () => {
+        const [, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const target = parent.querySelector("img");
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        expect(parent.querySelector(".lvt-area-select-overlay")).not.toBeNull();
+        dispatchPointer(target, "pointermove", 60, 70);
+        const overlay = parent.querySelector(".lvt-area-select-overlay");
+        expect(overlay.style.width).toBe("50px");
+        expect(overlay.style.height).toBe("60px");
+        dispatchPointer(target, "pointerup", 60, 70);
+        expect(parent.querySelector(".lvt-area-select-overlay")).toBeNull();
+    });
+    it("pointercancel removes the overlay and does NOT dispatch", () => {
+        const [, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const target = parent.querySelector("img");
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 60, 60);
+        dispatchPointer(target, "pointercancel", 60, 60);
+        expect(send).not.toHaveBeenCalled();
+        expect(parent.querySelector(".lvt-area-select-overlay")).toBeNull();
+    });
+    it("is idempotent across renders for the same action", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 100, 100);
+        dispatchPointer(target, "pointerup", 100, 100);
+        // Listeners must NOT have been duplicated by repeated calls.
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+    it("re-arms with new action when the attribute value changes", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "first" }, { left: 0, top: 0, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        target.setAttribute("lvt-fx:area-select", "second");
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 100, 100);
+        dispatchPointer(target, "pointerup", 100, 100);
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(send.mock.calls[0][0].action).toBe("second");
+    });
+    it("warns and skips when the attribute value is empty", () => {
+        const warn = console.warn;
+        mountTarget("img", { "lvt-fx:area-select": "" }, { left: 0, top: 0, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("requires an action name"));
+    });
+    it("clamps coords to 0..1 when the drag escapes the element rect", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 100, top: 100, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Drag starts inside but ends far below-right of the rect.
+        dispatchPointer(target, "pointerdown", 150, 150);
+        dispatchPointer(target, "pointerup", 10000, 10000);
+        expect(send).toHaveBeenCalledTimes(1);
+        const data = send.mock.calls[0][0].data;
+        expect(data.x).toBeGreaterThanOrEqual(0);
+        expect(data.x).toBeLessThanOrEqual(1);
+        expect(data.x + data.w).toBeLessThanOrEqual(1);
+        expect(data.y + data.h).toBeLessThanOrEqual(1);
+    });
+    it("fast-path returns when no matching elements", () => {
+        document.body.innerHTML = `<div><p>nothing here</p></div>`;
+        const send = jest.fn();
+        // Should not throw, should not dispatch.
+        expect(() => (0, directives_1.handleAreaSelectDirectives)(document.body, send)).not.toThrow();
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("removes the overlay when the host is detached mid-drag", () => {
+        const [target, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        expect(parent.querySelector(".lvt-area-select-overlay")).not.toBeNull();
+        // Simulate a server diff replacing the host element.
+        target.remove();
+        // A late pointermove (jsdom dispatches to the detached element)
+        // must clean up the overlay rather than leave it orphaned under
+        // the parent.
+        dispatchPointer(target, "pointermove", 60, 70);
+        expect(parent.querySelector(".lvt-area-select-overlay")).toBeNull();
+    });
+    it("suppresses native <img> drag via dragstart preventDefault", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        (0, directives_1.handleAreaSelectDirectives)(document.body, jest.fn());
+        // Without the dragstart listener, Chromium would call default-
+        // action (start a native image drag) and steal the gesture from
+        // pointer events. The directive must call preventDefault on
+        // dragstart so pointermove + pointerup keep arriving.
+        const drag = new Event("dragstart", { bubbles: true, cancelable: true });
+        target.dispatchEvent(drag);
+        expect(drag.defaultPrevented).toBe(true);
+    });
+    it("positions overlay correctly when target is offset inside its parent", () => {
+        // Parent at (0,0), target at (50, 25) — exercises the
+        // border-box-to-padding-box offset math with a real gap.
+        document.body.innerHTML = `
+      <div id="parent" style="position:relative;">
+        <img id="target" lvt-fx:area-select="selectImageArea">
+      </div>
+    `;
+        const target = document.getElementById("target");
+        const parent = document.getElementById("parent");
+        target.getBoundingClientRect = jest.fn(() => ({
+            x: 50, y: 25, left: 50, top: 25, right: 150, bottom: 125,
+            width: 100, height: 100, toJSON: () => ({}),
+        }));
+        parent.getBoundingClientRect = jest.fn(() => ({
+            x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+            width: 200, height: 200, toJSON: () => ({}),
+        }));
+        target.setPointerCapture = jest.fn();
+        target.releasePointerCapture = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, jest.fn());
+        // Drag from (80, 50) → (120, 90) — inside the target's 100×100 rect.
+        // Relative to the parent (and after subtracting clientLeft/clientTop=0
+        // for a borderless parent), the overlay should sit at left=80, top=50.
+        dispatchPointer(target, "pointerdown", 80, 50);
+        dispatchPointer(target, "pointermove", 120, 90);
+        const overlay = parent.querySelector(".lvt-area-select-overlay");
+        expect(overlay).not.toBeNull();
+        expect(overlay.style.left).toBe("80px");
+        expect(overlay.style.top).toBe("50px");
+        expect(overlay.style.width).toBe("40px");
+        expect(overlay.style.height).toBe("40px");
+    });
+    it("pointerleave for a different pointerId does NOT cancel our capture-fallback drag", () => {
+        // When setPointerCapture fails the directive attaches a
+        // pointerleave fallback so the drag can clean up. In a multi-
+        // touch scenario, a SECONDARY pointer leaving the element fires
+        // pointerleave too — must not be mistaken for our pointer
+        // leaving.
+        const [, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const target = parent.querySelector("img");
+        // Force capture failure so the pointerleave fallback is attached.
+        target.setPointerCapture = jest.fn(() => {
+            throw new DOMException("no capture", "InvalidStateError");
+        });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Primary drag with pointerId=1.
+        dispatchPointer(target, "pointerdown", 10, 10, 1);
+        dispatchPointer(target, "pointermove", 80, 80, 1);
+        // Secondary pointer (id=42) leaves the host. Must NOT cancel
+        // our id=1 drag.
+        dispatchPointer(target, "pointerleave", 80, 80, 42);
+        // Primary drag still alive — pointerup completes it normally.
+        dispatchPointer(target, "pointerup", 100, 100, 1);
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+    it("lostpointercapture for a different pointerId does NOT cancel our drag", () => {
+        // Another code path could call setPointerCapture on the same
+        // element with a different pointerId and later release it,
+        // firing lostpointercapture on the host. Our handler must not
+        // mistake that for OUR drag being canceled.
+        const [, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const target = parent.querySelector("img");
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Our drag starts with pointerId=1.
+        dispatchPointer(target, "pointerdown", 10, 10, 1);
+        dispatchPointer(target, "pointermove", 80, 80, 1);
+        // Unrelated lostpointercapture for pointerId=42 — must be ignored.
+        dispatchPointer(target, "lostpointercapture", 80, 80, 42);
+        // Our drag is still alive — pointerup dispatches normally.
+        dispatchPointer(target, "pointerup", 100, 100, 1);
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+    it("releasePointerCapture firing lostpointercapture synchronously does not drop the dispatch", () => {
+        // Chromium fires lostpointercapture SYNCHRONOUSLY during
+        // releasePointerCapture. Without the early state-reset in
+        // finalize, the nested lostpointercapture handler would see
+        // pointerId still matching, run a nested finalize that clears
+        // startRect, then the outer finalize would resume with rect=null
+        // and silently drop the dispatched action.
+        const [, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const target = parent.querySelector("img");
+        // Make releasePointerCapture fire lostpointercapture synchronously
+        // — the real Chromium behaviour that wasn't covered by jest.fn().
+        target.releasePointerCapture = jest.fn((pid) => {
+            target.dispatchEvent(Object.assign(new MouseEvent("lostpointercapture", { bubbles: false }), {
+                pointerId: pid,
+            }));
+        });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 20, 20);
+        dispatchPointer(target, "pointermove", 80, 80);
+        dispatchPointer(target, "pointerup", 80, 80);
+        // The action must still dispatch — the early state-reset prevents
+        // the nested lostpointercapture from re-entering finalize and
+        // clearing the rect mid-call.
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+    it("uses pointerdown-time rect for fractions even if host moves between mousemoves", () => {
+        // If a server diff repositions the host mid-drag, the rect
+        // captured AT POINTERUP would clamp startClientX (which was
+        // captured against the OLD position) into the wrong place.
+        // The dispatched fractions must reflect the original drag,
+        // measured against the rect that existed at pointerdown.
+        document.body.innerHTML = `
+      <div id="parent" style="position:relative;"><img id="target" lvt-fx:area-select="selectImageArea"></div>
+    `;
+        const parent = document.getElementById("parent");
+        const target = document.getElementById("target");
+        // Rect call counter: first call (pointerdown) returns the OLD
+        // rect, subsequent calls return a NEW rect 500px away.
+        let rectCalls = 0;
+        target.getBoundingClientRect = jest.fn(() => {
+            rectCalls++;
+            if (rectCalls === 1) {
+                return {
+                    x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+                    width: 200, height: 200, toJSON: () => ({}),
+                };
+            }
+            return {
+                x: 500, y: 500, left: 500, top: 500, right: 700, bottom: 700,
+                width: 200, height: 200, toJSON: () => ({}),
+            };
+        });
+        parent.getBoundingClientRect = jest.fn(() => ({
+            x: 0, y: 0, left: 0, top: 0, right: 1000, bottom: 1000,
+            width: 1000, height: 1000, toJSON: () => ({}),
+        }));
+        target.setPointerCapture = jest.fn();
+        target.releasePointerCapture = jest.fn();
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Drag from (40, 60) → (140, 160) inside the OLD rect at (0..200).
+        // OLD-rect fractions: x=40/200=0.2, y=60/200=0.3, w=100/200=0.5,
+        // h=100/200=0.5. With the new (500..700) rect at finalize time,
+        // clamping (40,60) into that rect would silently shift the start.
+        dispatchPointer(target, "pointerdown", 40, 60);
+        dispatchPointer(target, "pointermove", 90, 110);
+        dispatchPointer(target, "pointerup", 140, 160);
+        expect(send).toHaveBeenCalledTimes(1);
+        const data = send.mock.calls[0][0].data;
+        expect(data.x).toBeCloseTo(0.2, 5);
+        expect(data.y).toBeCloseTo(0.3, 5);
+        expect(data.w).toBeCloseTo(0.5, 5);
+        expect(data.h).toBeCloseTo(0.5, 5);
+    });
+    it("uses the pointerdown-time parent even if host moves between mousemoves", () => {
+        // Two positioned parents at known offsets. The host starts under
+        // the first; we begin a drag, then synthetically re-parent the
+        // host into the second container mid-drag. Without the parent-
+        // capture fix, updateOverlay would refetch el.parentElement and
+        // compute against the SECOND parent while the overlay still
+        // lives in the FIRST — visual mis-positioning for the rest of
+        // the drag. With the fix, the overlay tracks the FIRST parent.
+        document.body.innerHTML = `
+      <div id="p1" style="position:relative;"></div>
+      <div id="p2" style="position:relative;"></div>
+    `;
+        const p1 = document.getElementById("p1");
+        const p2 = document.getElementById("p2");
+        const target = document.createElement("img");
+        target.setAttribute("lvt-fx:area-select", "selectImageArea");
+        p1.appendChild(target);
+        target.getBoundingClientRect = jest.fn(() => ({
+            x: 10, y: 10, left: 10, top: 10, right: 110, bottom: 110,
+            width: 100, height: 100, toJSON: () => ({}),
+        }));
+        p1.getBoundingClientRect = jest.fn(() => ({
+            x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+            width: 200, height: 200, toJSON: () => ({}),
+        }));
+        p2.getBoundingClientRect = jest.fn(() => ({
+            x: 500, y: 500, left: 500, top: 500, right: 700, bottom: 700,
+            width: 200, height: 200, toJSON: () => ({}),
+        }));
+        target.setPointerCapture = jest.fn();
+        target.releasePointerCapture = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, jest.fn());
+        dispatchPointer(target, "pointerdown", 30, 30);
+        // Server diff moves the host to p2.
+        p2.appendChild(target);
+        dispatchPointer(target, "pointermove", 80, 60);
+        // Overlay stays in p1 (where pointerdown attached it). Position is
+        // computed against p1's rect (cached at pointerdown), not p2's.
+        const overlayInP1 = p1.querySelector(".lvt-area-select-overlay");
+        const overlayInP2 = p2.querySelector(".lvt-area-select-overlay");
+        expect(overlayInP1).not.toBeNull();
+        expect(overlayInP2).toBeNull();
+        // pointerdown at (30,30), move to (80,60) → 50×30 against p1
+        // at (0,0). If updateOverlay had re-fetched el.parentElement
+        // and used p2 (at 500,500), left would be -470 instead of 30.
+        expect(overlayInP1.style.left).toBe("30px");
+    });
+    it("positions overlay correctly when parent is scrolled", () => {
+        // For a scrolled positioned parent: an element at viewport_x =
+        // parentRect.left actually has CSS_left = parent.scrollLeft (the
+        // browser is scrolled, so what's at viewport-x-0 is parent-x-100
+        // for scrollLeft=100). Without adding scrollLeft/scrollTop back
+        // into the CSS coords, the overlay paints displaced by the scroll
+        // amount.
+        document.body.innerHTML = `
+      <div id="parent" style="position:relative;"><img id="target" lvt-fx:area-select="selectImageArea"></div>
+    `;
+        const parent = document.getElementById("parent");
+        const target = document.getElementById("target");
+        target.getBoundingClientRect = jest.fn(() => ({
+            x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+            width: 200, height: 200, toJSON: () => ({}),
+        }));
+        parent.getBoundingClientRect = jest.fn(() => ({
+            x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+            width: 200, height: 200, toJSON: () => ({}),
+        }));
+        // jsdom: scrollLeft/Top are mutable properties; just assign.
+        Object.defineProperty(parent, "scrollLeft", { value: 100, configurable: true });
+        Object.defineProperty(parent, "scrollTop", { value: 50, configurable: true });
+        target.setPointerCapture = jest.fn();
+        target.releasePointerCapture = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, jest.fn());
+        // Drag from viewport (30, 40) to (90, 100). With the scroll
+        // correction the overlay's CSS left should be
+        // 30 - 0 - 0 + 100 = 130 and CSS top should be
+        // 40 - 0 - 0 + 50 = 90. Without it, left=30 / top=40 (the bug).
+        dispatchPointer(target, "pointerdown", 30, 40);
+        dispatchPointer(target, "pointermove", 90, 100);
+        const overlay = parent.querySelector(".lvt-area-select-overlay");
+        expect(overlay).not.toBeNull();
+        expect(overlay.style.left).toBe("130px");
+        expect(overlay.style.top).toBe("90px");
+        expect(overlay.style.width).toBe("60px");
+        expect(overlay.style.height).toBe("60px");
+    });
+    it("warns when the parent's computed position is `static`", () => {
+        // Forgetting position:relative on the parent silently mis-paints
+        // the overlay against the nearest positioned ancestor. A
+        // dev-time warn gives the author a chance to spot the mistake.
+        const warn = console.warn;
+        document.body.innerHTML = `
+      <div id="static-parent">
+        <img id="target" lvt-fx:area-select="selectImageArea">
+      </div>
+    `;
+        const target = document.getElementById("target");
+        target.getBoundingClientRect = jest.fn(() => ({
+            x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+            width: 200, height: 200, toJSON: () => ({}),
+        }));
+        target.setPointerCapture = jest.fn();
+        target.releasePointerCapture = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, jest.fn());
+        dispatchPointer(target, "pointerdown", 10, 10);
+        const warnings = warn.mock.calls.filter((args) => typeof args[0] === "string" && args[0].includes("parentElement has no positioning context"));
+        expect(warnings.length).toBe(1);
+    });
+    it("dedupes the static-parent warn across repeated drags", () => {
+        // Without the WeakSet dedupe, a user repeatedly dragging on the
+        // same mis-configured element would spam console.warn (and
+        // re-run getComputedStyle, a style-recalc trigger) once per
+        // pointerdown.
+        const warn = console.warn;
+        document.body.innerHTML = `
+      <div id="static-parent">
+        <img id="target" lvt-fx:area-select="selectImageArea">
+      </div>
+    `;
+        const target = document.getElementById("target");
+        target.getBoundingClientRect = jest.fn(() => ({
+            x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+            width: 200, height: 200, toJSON: () => ({}),
+        }));
+        target.setPointerCapture = jest.fn();
+        target.releasePointerCapture = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, jest.fn());
+        // Three drags on the same mis-configured parent — only the FIRST
+        // should warn.
+        for (let i = 0; i < 3; i++) {
+            dispatchPointer(target, "pointerdown", 10, 10);
+            dispatchPointer(target, "pointerup", 60, 60);
+        }
+        const warnings = warn.mock.calls.filter((args) => typeof args[0] === "string" && args[0].includes("parentElement has no positioning context"));
+        expect(warnings.length).toBe(1);
+    });
+    it("pointercancel cancels the drag without dispatching", () => {
+        // pointercancel fires on system gestures (OS-level swipe, app
+        // switch). Like lostpointercapture / pointerleave, it must remove
+        // the overlay and NOT dispatch — same contract from the user's
+        // perspective.
+        const [, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const target = parent.querySelector("img");
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 80, 80);
+        dispatchPointer(target, "pointercancel", 80, 80);
+        expect(send).not.toHaveBeenCalled();
+        expect(parent.querySelector(".lvt-area-select-overlay")).toBeNull();
+    });
+    it("rejects zero-area rectangles even if the threshold check would pass", () => {
+        // The MIN_AREA_FRACTION check uses && so a wide-but-thin drag is
+        // a legit selection — but a literal 60% × 0% drag has no area,
+        // can't render sensibly, and would divide by zero downstream.
+        // Drop it independently of the threshold.
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Drag from (40,100) to (160,100) — w=60% of 200, h=0%.
+        dispatchPointer(target, "pointerdown", 40, 100);
+        dispatchPointer(target, "pointermove", 160, 100);
+        dispatchPointer(target, "pointerup", 160, 100);
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("teardownAreaSelectForRoot cancels armed elements under root", () => {
+        // For the disconnect / destroy lifecycle: if a client tears down
+        // without a subsequent handleAreaSelectDirectives call, the
+        // module-level singleton would otherwise leak listeners.
+        document.body.innerHTML = `
+      <div id="root">
+        <div id="parent" style="position:relative;">
+          <img id="target" lvt-fx:area-select="selectImageArea">
+        </div>
+      </div>
+      <div id="outside-parent" style="position:relative;">
+        <img id="outside-target" lvt-fx:area-select="otherAction">
+      </div>
+    `;
+        const root = document.getElementById("root");
+        const target = document.getElementById("target");
+        const outside = document.getElementById("outside-target");
+        for (const el of [target, outside]) {
+            el.getBoundingClientRect = jest.fn(() => ({
+                x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+                width: 200, height: 200, toJSON: () => ({}),
+            }));
+            el.parentElement.getBoundingClientRect = jest.fn(() => ({
+                x: 0, y: 0, left: 0, top: 0, right: 200, bottom: 200,
+                width: 200, height: 200, toJSON: () => ({}),
+            }));
+            el.setPointerCapture = jest.fn();
+            el.releasePointerCapture = jest.fn();
+        }
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        (0, directives_1.teardownAreaSelectForRoot)(root);
+        // The target inside root must NOT dispatch after teardown.
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 100, 100);
+        dispatchPointer(target, "pointerup", 100, 100);
+        expect(send).not.toHaveBeenCalled();
+        // The target outside root must still work.
+        dispatchPointer(outside, "pointerdown", 10, 10);
+        dispatchPointer(outside, "pointermove", 100, 100);
+        dispatchPointer(outside, "pointerup", 100, 100);
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(send.mock.calls[0][0].action).toBe("otherAction");
+        (0, directives_1.teardownAreaSelectForRoot)(document.body); // clean up for next test
+    });
+    it("does not preventDefault on pointerdown — clicks still bubble", () => {
+        // The contract promises a small-rect drag (treated as a click)
+        // still reaches the host's click handlers. Calling
+        // preventDefault on pointerdown would suppress the compatibility
+        // mouse events that fire click — so the directive must NOT do
+        // that.
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        (0, directives_1.handleAreaSelectDirectives)(document.body, jest.fn());
+        const down = new MouseEvent("pointerdown", {
+            clientX: 50, clientY: 50, button: 0, bubbles: true, cancelable: true,
+        });
+        Object.defineProperty(down, "pointerId", { value: 1 });
+        Object.defineProperty(down, "isPrimary", { value: true });
+        target.dispatchEvent(down);
+        expect(down.defaultPrevented).toBe(false);
+    });
+    it("stale pointerleave listener does not survive into the next gesture", () => {
+        // The bug Claude flagged: when setPointerCapture fails on drag N,
+        // the directive registers a pointerleave fallback. If drag N
+        // gets stuck (pointer never leaves so the fallback never fires
+        // and no pointerup arrives), and the user starts drag N+1, the
+        // re-entrancy guard finalizes drag N but the STALE pointerleave
+        // listener from N would still be attached. If capture SUCCEEDS
+        // on drag N+1 (no new pointerleave registered), the stale one
+        // from N would still fire if the pointer ever leaves — and
+        // incorrectly cancel drag N+1. finalize() must remove the
+        // pointerleave listener so it can't outlive its own gesture.
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        // Capture FAILS only on the first call (drag N), succeeds after.
+        let captureCalls = 0;
+        target.setPointerCapture = jest.fn(() => {
+            captureCalls++;
+            if (captureCalls === 1) {
+                throw new DOMException("no capture", "InvalidStateError");
+            }
+        });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Drag N: pointerdown attaches the pointerleave fallback, but
+        // user starts drag and never releases (simulates a "stuck"
+        // drag). Do NOT pointerup.
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 80, 80);
+        // Drag N+1 starts. Re-entrancy guard finalizes drag N. WITHOUT
+        // the fix, drag N's pointerleave listener stays attached.
+        // Capture succeeds this time so no NEW pointerleave is attached.
+        dispatchPointer(target, "pointerdown", 20, 20);
+        dispatchPointer(target, "pointermove", 100, 100);
+        // Fire pointerleave. With the fix, no pointerleave handler is
+        // attached → no-op, drag N+1 continues. WITHOUT the fix, the
+        // stale listener from N would call finalize and cancel.
+        target.dispatchEvent(new MouseEvent("pointerleave", { bubbles: false }));
+        dispatchPointer(target, "pointerup", 100, 100);
+        // Drag N+1 should have dispatched normally — the stale listener
+        // must NOT have cancelled it.
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+    it("idempotent re-arm picks up the latest send callback (no stale closure)", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const firstSend = jest.fn();
+        const secondSend = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, firstSend);
+        // A subsequent render passes a different send (e.g. after a WS
+        // reconnect rebuilt the transport). The idempotent path keeps
+        // the listeners but MUST swap the captured send so the next
+        // drag dispatches through the latest callback.
+        (0, directives_1.handleAreaSelectDirectives)(document.body, secondSend);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 100, 100);
+        dispatchPointer(target, "pointerup", 100, 100);
+        expect(firstSend).not.toHaveBeenCalled();
+        expect(secondSend).toHaveBeenCalledTimes(1);
+    });
+    it("lostpointercapture cancels the drag without dispatching", () => {
+        const [, parent] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const target = parent.querySelector("img");
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 80, 80);
+        // Platform yanks capture (OS gesture, another setPointerCapture
+        // call elsewhere). lostpointercapture should cancel like
+        // pointercancel — overlay removed, no action dispatched.
+        dispatchPointer(target, "lostpointercapture", 80, 80);
+        expect(send).not.toHaveBeenCalled();
+        expect(parent.querySelector(".lvt-area-select-overlay")).toBeNull();
+    });
+    it("cleans up armed elements whose attribute was removed by a server diff", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // Server diff removes the attribute. The element stays in the DOM
+        // (host alive, but no longer wants area-select). The next
+        // handleAreaSelectDirectives pass MUST cancel the listeners — a
+        // subsequent drag must not dispatch the old action.
+        target.removeAttribute("lvt-fx:area-select");
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 100, 100);
+        dispatchPointer(target, "pointerup", 100, 100);
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("recovers from a stuck drag on the next pointerdown (re-entrancy guard)", () => {
+        const [target] = mountTarget("img", { "lvt-fx:area-select": "selectImageArea" }, { left: 0, top: 0, width: 200, height: 200 });
+        const send = jest.fn();
+        (0, directives_1.handleAreaSelectDirectives)(document.body, send);
+        // First drag: pointerdown but no pointerup (simulates a captured
+        // pointer that never released — what happens when capture silently
+        // fails and pointer leaves the element).
+        dispatchPointer(target, "pointerdown", 10, 10);
+        dispatchPointer(target, "pointermove", 60, 60);
+        // No pointerup. The drag is "stuck".
+        // Second drag starts. Without the re-entrancy guard, the first
+        // overlay would be orphaned. With the guard, the directive cancels
+        // the stuck drag before starting the new one, and the new drag
+        // completes normally.
+        dispatchPointer(target, "pointerdown", 100, 100);
+        dispatchPointer(target, "pointermove", 150, 150);
+        dispatchPointer(target, "pointerup", 150, 150);
+        expect(send).toHaveBeenCalledTimes(1);
+        // The dispatched coords must come from the SECOND drag, not the
+        // first. (Start=100, End=150 → x=0.5, w=0.25 on the 200-wide rect.)
+        const data = send.mock.calls[0][0].data;
+        expect(data.x).toBeCloseTo(0.50, 5);
+        expect(data.w).toBeCloseTo(0.25, 5);
+        // Exactly one overlay at most over the whole sequence (the second
+        // drag's) — never two.
+        expect(document.querySelectorAll(".lvt-area-select-overlay").length).toBe(0);
+    });
+});
+describe("handleURLHashDirective", () => {
+    // The directive is a module-level singleton (a Map of armed elements
+    // plus a single window-level hashchange listener), so every test
+    // must tear down to avoid bleed between cases.
+    afterEach(() => {
+        (0, directives_1.teardownURLHashForRoot)(document.body);
+        document.body.innerHTML = "";
+        // Body persists across tests (innerHTML only resets descendants);
+        // wipe attributes the previous test set on body itself.
+        document.body.removeAttribute("lvt-fx:url-hash");
+        document.body.removeAttribute("data-lvt-url-hash");
+        // Reset URL hash without touching history (the directive uses
+        // pushState/replaceState; jsdom keeps them isolated per test).
+        window.history.replaceState(null, "", window.location.pathname);
+        // The unencoded-hash warning dedupe Set is module-level and
+        // outlives a single test; reset so a hash value reused across
+        // tests still warns.
+        (0, directives_1.__resetURLHashUnencodedWarnedForTesting)();
+        jest.restoreAllMocks();
+    });
+    function mountBody(dataHash, action = "setURLHash") {
+        const body = document.body;
+        body.setAttribute("lvt-fx:url-hash", action);
+        body.setAttribute("data-lvt-url-hash", dataHash);
+        return body;
+    }
+    it("on first arm with empty location.hash and non-empty data-attr, mirrors data-attr into location.hash", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L4");
+        // No dispatch because the URL didn't drive the change — the server
+        // already knew the state (the data-attr came FROM the server).
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("on first arm with empty URL, uses replaceState (not pushState) — Back must not loop", () => {
+        // Bug pinned: when initial URL is empty AND server has a hash,
+        // the mirror step uses pushState by the path-comparison rule
+        // ("" → "README.md" is a path change). That leaves a history
+        // entry where Back lands the user on `url-without-hash`, which
+        // re-arms the directive, which pushes the same hash again. Loop.
+        // Fix: empty currentLocation → always replaceState.
+        const lengthBefore = window.history.length;
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L4");
+        expect(window.history.length).toBe(lengthBefore);
+    });
+    it("on first arm with non-empty location.hash differing from data-attr, dispatches the action with the URL hash", () => {
+        window.history.replaceState(null, "", "#README.md:L4");
+        mountBody(""); // server hasn't seen the hash yet
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(send.mock.calls[0][0]).toEqual({
+            action: "setURLHash",
+            data: { hash: "README.md:L4" },
+        });
+        // The URL is not rewritten — the server's next render will produce
+        // the canonical data-attr, and we'll converge then.
+        expect(window.location.hash).toBe("#README.md:L4");
+    });
+    it("on first arm with empty location.hash and empty data-attr, no-op (no dispatch, no URL write)", () => {
+        mountBody("");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(send).not.toHaveBeenCalled();
+        expect(window.location.hash).toBe("");
+    });
+    it("mirrors data-attr change to location.hash via replaceState when path component is unchanged", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L4");
+        const lengthBefore = window.history.length;
+        // Server re-render: same file, different line.
+        document.body.setAttribute("data-lvt-url-hash", "README.md:L8");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L8");
+        // replaceState keeps history depth flat: jsdom's history.length
+        // increments only on pushState, not replaceState.
+        expect(window.history.length).toBe(lengthBefore);
+    });
+    it("mirrors data-attr change to location.hash via pushState when path component changes", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        const lengthBefore = window.history.length;
+        // Server re-render: different file.
+        document.body.setAttribute("data-lvt-url-hash", "OTHER.md:L1");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#OTHER.md:L1");
+        expect(window.history.length).toBe(lengthBefore + 1);
+    });
+    it("on hashchange (user clicks a permalink), dispatches the action with the new hash", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        send.mockClear();
+        // Simulate a user-driven hash change: set location.hash AND
+        // synchronously fire the hashchange event. (jsdom queues
+        // hashchange asynchronously when you assign location.hash, so we
+        // dispatch manually to keep the test deterministic — same pattern
+        // as area-select's synthetic pointer events.)
+        window.history.replaceState(null, "", "#OTHER.md:L2");
+        window.dispatchEvent(new Event("hashchange"));
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(send.mock.calls[0][0]).toEqual({
+            action: "setURLHash",
+            data: { hash: "OTHER.md:L2" },
+        });
+    });
+    it("idempotent re-arm with the same action does NOT add history entries", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        const lengthAfterArm = window.history.length;
+        // Re-call with no data-attr change.
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.history.length).toBe(lengthAfterArm);
+        expect(window.location.hash).toBe("#README.md:L4");
+    });
+    it("updateSend swaps the captured transport so a reconnect rebuilds dispatching", () => {
+        mountBody("README.md:L4");
+        const firstSend = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, firstSend);
+        firstSend.mockClear();
+        // Re-arm with a NEW send (simulating a reconnect that rebuilt the
+        // transport).
+        const secondSend = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, secondSend);
+        // hashchange now should route through the second send only.
+        window.history.replaceState(null, "", "#OTHER.md:L1");
+        window.dispatchEvent(new Event("hashchange"));
+        expect(firstSend).not.toHaveBeenCalled();
+        expect(secondSend).toHaveBeenCalledTimes(1);
+        expect(secondSend.mock.calls[0][0].data).toEqual({ hash: "OTHER.md:L1" });
+    });
+    it("teardown removes the armed element AND its hashchange listener", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L4");
+        (0, directives_1.teardownURLHashForRoot)(document.body);
+        // After teardown, a hashchange does NOT dispatch — the window
+        // listener was removed when the armed map emptied.
+        window.history.replaceState(null, "", "#OTHER.md:L1");
+        window.dispatchEvent(new Event("hashchange"));
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("teardown via a descendant root cleans up a body-armed entry", () => {
+        // Pin the body-ancestor branch of teardownURLHashForRoot: in
+        // production, livetemplate calls teardown with the wrapper div
+        // (inside body) as the root, but the directive lives on body.
+        // The teardown must clean up the body entry too — otherwise
+        // disconnect/reconnect cycles leak listeners.
+        mountBody("README.md:L4");
+        const wrapper = document.createElement("div");
+        document.body.appendChild(wrapper);
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        (0, directives_1.teardownURLHashForRoot)(wrapper);
+        window.history.replaceState(null, "", "#OTHER.md:L1");
+        window.dispatchEvent(new Event("hashchange"));
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("sweep cleans up entries whose attribute was removed by a server diff", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        // Server diff removed the directive.
+        document.body.removeAttribute("lvt-fx:url-hash");
+        document.body.removeAttribute("data-lvt-url-hash");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        // The window listener should be gone now too — no dispatch.
+        window.history.replaceState(null, "", "#OTHER.md:L1");
+        window.dispatchEvent(new Event("hashchange"));
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("warns and skips when lvt-fx:url-hash is present but empty", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+        document.body.setAttribute("lvt-fx:url-hash", "");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("lvt-fx:url-hash requires an action name"));
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("ignores plain element-id hashes on initial load (no dispatch, no URL clobber)", () => {
+        // Anchors like `#hero` (no `:`, no `/`, no `.`) belong to native
+        // anchor / dialog / popover machinery — the directive must NOT
+        // dispatch for them or it would race against setupHashLink.
+        window.history.replaceState(null, "", "#hero");
+        mountBody("");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(send).not.toHaveBeenCalled();
+        expect(window.location.hash).toBe("#hero");
+    });
+    it("on initial load with non-deep-link hash AND non-empty server data-attr, leaves the URL alone", () => {
+        // The browser navigated to `#hero` (a popover id, say). The
+        // server happens to have selected a default file, so the data-
+        // attr is non-empty. Before the fix, the else-branch mirrored
+        // the server's hash into the URL and silently closed the
+        // popover. After the fix, the URL is left alone — popover
+        // wins.
+        window.history.replaceState(null, "", "#hero");
+        mountBody("README.md");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(send).not.toHaveBeenCalled();
+        expect(window.location.hash).toBe("#hero");
+    });
+    it("server changing selection while a non-deep-link URL hash is open does NOT clobber", () => {
+        // Round-8 bot edge case: case (b) leaves the URL on #hero and
+        // seeds currentDataHash = dataHash. If the server then pushes a
+        // DIFFERENT selection (rare in prereview — server state changes
+        // only on user action — but possible via cross-tab sync or a
+        // server-driven update), the mirror's path-comparison would
+        // have written the new file's hash and clobbered #hero. Fixed
+        // by generalising the non-deep-link-URL guard to cover any
+        // dataHash, not just empty.
+        window.history.replaceState(null, "", "#hero");
+        mountBody("README.md");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#hero");
+        // Server pushes a different selection — URL must NOT change.
+        document.body.setAttribute("data-lvt-url-hash", "OTHER.md");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#hero");
+    });
+    it("server clearing the data-attr DOES clear a deep-link URL hash (deliberate, symmetric)", () => {
+        // Symmetric to "non-deep-link is never clobbered": if the URL
+        // is a deep-link we own AND the server transitions to
+        // no-selection, the URL should clear. Pin this as deliberate
+        // so a future refactor doesn't accidentally make all
+        // empty-dataHash mirrors no-op.
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L4");
+        document.body.setAttribute("data-lvt-url-hash", "");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("");
+    });
+    it("deselection (deep-link → empty) uses pushState — Back returns to the selection (deliberate)", () => {
+        // Pin the path-comparison branch's behavior for the deselect
+        // case: server transitions `data-lvt-url-hash` from a selected
+        // file to "", path comparison says oldPath !== newPath (one is
+        // empty), the mirror uses pushState. That leaves a history
+        // entry so Back returns the user to their prior selection.
+        // Intentional — matches the file-switch UX.
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L4");
+        const lengthBeforeDeselect = window.history.length;
+        document.body.setAttribute("data-lvt-url-hash", "");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("");
+        expect(window.history.length).toBe(lengthBeforeDeselect + 1);
+    });
+    it("server clearing the data-attr does NOT wipe a non-deep-link URL hash", () => {
+        // Server first has README.md selected → URL becomes
+        // `#README.md`. Then the user opens a popover whose id is
+        // `#hero` (URL is now `#hero`). Then the server transitions to
+        // no-selection (e.g. ClearSelection) and renders data-attr="".
+        // The directive must not clobber the popover hash.
+        mountBody("README.md");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md");
+        // User navigates to a popover-shaped hash (simulated).
+        window.history.replaceState(null, "", "#hero");
+        // Server clears state → empty data-attr.
+        document.body.setAttribute("data-lvt-url-hash", "");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#hero");
+    });
+    it("case-(b) + user clears URL: URL stays empty while server keeps its selection (deliberate divergence)", () => {
+        // Load with a popover-shaped hash, server has a file selected.
+        // Case (b) seeds entry.currentDataHash with the server's value.
+        window.history.replaceState(null, "", "#hero");
+        mountBody("README.md");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#hero");
+        // User clears the URL bar.
+        window.history.replaceState(null, "", window.location.pathname);
+        window.dispatchEvent(new Event("hashchange"));
+        expect(send).not.toHaveBeenCalled();
+        // Server re-renders with the SAME selection (data-attr unchanged).
+        // The early-exit guard (currentDataHash === dataHash) means we
+        // never mirror — URL stays empty, server stays on README.md.
+        // This divergence is intentional: case (b) said "the URL isn't
+        // ours, leave it alone", and a user clearing the URL doesn't
+        // change that — they're still navigating outside our turf.
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("");
+        expect(send).not.toHaveBeenCalled();
+        // Convergence only happens when the user takes an in-app action
+        // that changes server state (e.g. SelectFile to OTHER.md): the
+        // data-attr now differs from currentDataHash and the mirror
+        // step writes the new hash.
+        document.body.setAttribute("data-lvt-url-hash", "OTHER.md");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#OTHER.md");
+    });
+    it("user clearing the URL hash (hashchange to empty) does NOT dispatch — server stays source of truth", () => {
+        // The directive treats the server as source of truth for
+        // "what's selected". An empty location.hash is "user navigated
+        // away from the hash" but not "deselect". Deselect happens via
+        // in-app affordances that flow through the server, which then
+        // emits an empty data-attr.
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        send.mockClear();
+        // User clears the URL bar.
+        window.history.replaceState(null, "", window.location.pathname);
+        window.dispatchEvent(new Event("hashchange"));
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("ignores plain element-id hashes on hashchange", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        send.mockClear();
+        // User clicks an HTML anchor link (e.g. inside the TOC overlay).
+        window.history.replaceState(null, "", "#some-section");
+        window.dispatchEvent(new Event("hashchange"));
+        expect(send).not.toHaveBeenCalled();
+    });
+    it("preserves history.state across the mirror write (doesn't clobber co-tenant SPA state)", () => {
+        // Co-tenant code stores something in history.state — e.g. scroll
+        // position or modal flag. Our directive's push/replaceState must
+        // pass that state through, not overwrite with null.
+        window.history.replaceState({ scroll: 42, modal: "open" }, "", window.location.pathname);
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#README.md:L4");
+        expect(window.history.state).toEqual({ scroll: 42, modal: "open" });
+        // Same on a path-change pushState path.
+        document.body.setAttribute("data-lvt-url-hash", "OTHER.md");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.location.hash).toBe("#OTHER.md");
+        expect(window.history.state).toEqual({ scroll: 42, modal: "open" });
+    });
+    it("warns when data-lvt-url-hash contains characters that should be percent-encoded", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+        // Note: jsdom's location.hash setter percent-encodes spaces, so
+        // we mount the directive with a value containing a literal space
+        // and expect a warn before the directive writes the URL.
+        mountBody("path with space.md");
+        (0, directives_1.handleURLHashDirective)(document.body, jest.fn());
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("should be percent-encoded"));
+    });
+    it.each([
+        ["bracket [", "path[v1].md"],
+        ["bracket ]", "list]item.md"],
+        ["raw percent", "50%off.md"],
+        ["raw quote", `name".md`],
+        ["raw less-than", "x<y.md"],
+    ])("warns on %s", (_label, hash) => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+        mountBody(hash);
+        (0, directives_1.handleURLHashDirective)(document.body, jest.fn());
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("should be percent-encoded"));
+    });
+    it("valid percent-encoded sequence does NOT warn", () => {
+        // `%20` is a properly percent-encoded space — no warn.
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+        mountBody("path%20with%20space.md");
+        (0, directives_1.handleURLHashDirective)(document.body, jest.fn());
+        expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("should be percent-encoded"));
+    });
+    it("data-attr update unchanged from last mirror is a no-op (no history pollution)", () => {
+        mountBody("README.md:L4");
+        const send = jest.fn();
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        // User clicks a permalink anchor → location.hash changes to the
+        // same value the data-attr already had. The hashchange dispatch
+        // updates currentDataHash to the same value; subsequent renders
+        // with the same data-attr should still no-op (no extra history
+        // entries when the server echoes back the same hash).
+        window.history.replaceState(null, "", "#OTHER.md:L9");
+        window.dispatchEvent(new Event("hashchange"));
+        const lengthBefore = window.history.length;
+        send.mockClear();
+        document.body.setAttribute("data-lvt-url-hash", "OTHER.md:L9");
+        (0, directives_1.handleURLHashDirective)(document.body, send);
+        expect(window.history.length).toBe(lengthBefore);
+        expect(window.location.hash).toBe("#OTHER.md:L9");
+    });
+});
 //# sourceMappingURL=directives.test.js.map