@livetemplate/client 0.11.5 → 0.11.7

package/dist/dom/directives.js

@@ -14,6 +14,11 @@ exports.handleAnimateDirectives = handleAnimateDirectives;
 exports.handleToastDirectives = handleToastDirectives;
 exports.setupToastClickOutside = setupToastClickOutside;
 exports.handleShadowRootHydration = handleShadowRootHydration;
+exports.handleAreaSelectDirectives = handleAreaSelectDirectives;
+exports.teardownAreaSelectForRoot = teardownAreaSelectForRoot;
+exports.handleURLHashDirective = handleURLHashDirective;
+exports.teardownURLHashForRoot = teardownURLHashForRoot;
+exports.__resetURLHashUnencodedWarnedForTesting = __resetURLHashUnencodedWarnedForTesting;
 const reactive_attributes_1 = require("./reactive-attributes");
 // ─── Trigger parsing for lvt-fx: attributes ─────────────────────────────────
 const FX_LIFECYCLE_SET = new Set(["pending", "success", "error", "done"]);
@@ -858,4 +863,850 @@ function handleShadowRootHydration(rootElement) {
         tpl.remove();
     }
 }
+// areaSelectArmed tracks the cleanup callback for every element that
+// currently has a `lvt-fx:area-select` handler attached. Map (not
+// WeakMap) because the sweep needs to iterate to detect elements whose
+// attribute was removed by a server diff — without iteration those
+// elements would keep their listeners and silently dispatch the old
+// action on subsequent drags. Detached elements are cleaned up via
+// the same sweep (isConnected check).
+const areaSelectArmed = new Map();
+// areaSelectWarnedParents dedupes the "parent not positioned" dev-warn
+// so a user who repeatedly drags on a mis-configured element gets a
+// single console message instead of one per pointerdown. WeakSet so
+// detached parents don't leak.
+//
+// Known limitation: once a parent is in the set, the warn never fires
+// again on that DOM node — even if the developer subsequently adds
+// `position: relative` to fix the issue. The WeakSet is per-object
+// (different DOM node = different entry), so re-mounting the parent
+// resets the dedupe; in-place CSS fixes do not. Fine in practice
+// (the user already saw the warn once, on the broken render).
+const areaSelectWarnedParents = new WeakSet();
+// MIN_AREA_FRACTION filters accidental click-style gestures where the
+// user meant to click, not drag. 2% of the element's rendered size is
+// big enough to be intentional on touch + mouse but small enough that
+// anyone seriously trying to annotate a tiny region can still do it.
+const MIN_AREA_FRACTION = 0.02;
+/**
+ * Apply area-select directives. `lvt-fx:area-select="<actionName>"` on
+ * an element (typically an `<img>` inside a positioned parent) lets
+ * the user drag a rectangle locally — a `<div>` overlay tracks the
+ * gesture in real time without a server round-trip — and on
+ * `pointerup` dispatches a single livetemplate action with the final
+ * `{x, y, w, h}` as 0..1 fractions of the element's rendered bounding
+ * rect. The image's intrinsic dimensions don't matter for the
+ * fractions: any uniform scale (zoom, responsive layout) preserves
+ * the fraction. The consumer scales to pixels using the natural size
+ * if it needs them.
+ *
+ * Contract:
+ *  - Host's `parentElement` must establish a positioning context
+ *    (`position: relative` / `absolute` / `fixed`). The overlay is
+ *    `position: absolute` inside that parent so it follows the host
+ *    on scroll / reflow.
+ *  - Consumers usually pair this with `touch-action: none` on the
+ *    host so iOS Safari doesn't interpret the drag as a pinch/scroll.
+ *  - `<img>` and other natively-draggable hosts work automatically:
+ *    the directive calls `preventDefault()` on `dragstart` so the
+ *    browser's native drag (which would otherwise steal the gesture)
+ *    is suppressed.
+ *  - On pointer-cancel (e.g. system gesture, app switch), the overlay
+ *    is removed and no action is dispatched — same effect as cancelling
+ *    a click on `mouseleave`.
+ *  - Drags smaller than `MIN_AREA_FRACTION` in BOTH dimensions are
+ *    dropped — a click on the host still fires normal `click`
+ *    handlers via the compatibility mouse events.
+ *  - For text-bearing hosts, set `user-select: none` (the directive
+ *    deliberately does NOT call `preventDefault()` on `pointerdown`
+ *    so click handlers still receive the gesture; that means the
+ *    browser's default text-selection-on-drag behaviour also fires
+ *    unless the host opts out via CSS).
+ *  - The overlay uses `z-index: var(--lvt-area-select-z-index, 9999)`.
+ *    9999 is high enough for most use cases but can collide with
+ *    portals / modals / drawers that also sit at a high z-index.
+ *    Set `--lvt-area-select-z-index` on the host (or any ancestor)
+ *    to override. Color + fill follow the same pattern via
+ *    `--lvt-area-select-color` and `--lvt-area-select-fill`.
+ *  - **No keyboard equivalent.** Pointer-only by design (a keyboard-
+ *    selected rectangle requires a different UX — focus + arrow keys
+ *    to position + arrow keys to size). Consumers needing a11y for
+ *    area selection should provide a parallel form-based affordance.
+ *
+ * Idempotent across renders: an element re-armed with the same action
+ * keeps its existing listeners. A different action causes a tear-down
+ * and re-arm. Disconnected elements (and elements whose attribute was
+ * cleared by a server diff) get their listeners cleaned up by the
+ * sweep at the top of every call — we use a regular Map (not WeakMap)
+ * specifically so the sweep can iterate.
+ *
+ * Module-level singleton: `areaSelectArmed` is shared across all
+ * LiveTemplateClient instances in the same window. If two clients
+ * ever arm the same element with different actions, the second wins
+ * and the first client's send() is orphaned. Single-client use is
+ * unaffected.
+ */
+function handleAreaSelectDirectives(rootElement, send) {
+    // Sweep stale entries before processing the current match set:
+    // disconnected elements AND elements where the attribute was
+    // removed by a server diff. Without this, a previously-armed
+    // element whose lvt-fx:area-select was cleared would keep its
+    // listeners and silently dispatch the old action on subsequent
+    // drags. Iterate via Array.from so cleanup()'s delete() doesn't
+    // disturb the iterator.
+    for (const [element, entry] of Array.from(areaSelectArmed)) {
+        if (!element.isConnected || !element.hasAttribute("lvt-fx:area-select")) {
+            entry.cleanup();
+        }
+    }
+    const matches = rootElement.querySelectorAll("[lvt-fx\\:area-select]");
+    if (matches.length === 0)
+        return;
+    for (const el of matches) {
+        const action = el.getAttribute("lvt-fx:area-select");
+        // Empty attribute → consumer almost certainly typoed; warn and
+        // skip rather than dispatching to a blank action name.
+        if (!action) {
+            console.warn(`lvt-fx:area-select requires an action name, got: ${JSON.stringify(action)}`);
+            continue;
+        }
+        const existing = areaSelectArmed.get(el);
+        if (existing && existing.action === action) {
+            // Idempotent re-arm: keep the listeners + WeakMap entry, but
+            // update the captured send so a subsequent drag dispatches
+            // through the latest callback (e.g. after a WebSocket
+            // reconnect rebuilt the transport).
+            existing.updateSend(send);
+            continue;
+        }
+        if (existing)
+            existing.cleanup();
+        areaSelectArmed.set(el, attachAreaSelect(el, action, send));
+    }
+}
+/**
+ * Cancel area-select listeners for every armed element under root.
+ * Mirrors teardownAutoClickTimers: meant for the client's disconnect /
+ * destroy lifecycle so the module-level singleton doesn't outlive a
+ * client that was torn down without a subsequent
+ * handleAreaSelectDirectives call (e.g. network error closed the
+ * socket while an element was armed). Without this, a SPA that mounts
+ * + tears down livetemplate trees would leak listeners across mounts.
+ */
+function teardownAreaSelectForRoot(rootElement) {
+    // `contains` returns true for the node itself, so this also handles
+    // the (today-impossible) case of rootElement being armed directly.
+    for (const [element, entry] of Array.from(areaSelectArmed)) {
+        if (rootElement.contains(element)) {
+            entry.cleanup();
+        }
+    }
+}
+// urlHashArmed tracks `lvt-fx:url-hash` listeners and their last-
+// mirrored hash. Same Map-not-WeakMap reasoning as area-select: the
+// sweep iterates to detect elements whose attribute was removed by a
+// server diff, and detached elements are cleaned up via the same
+// sweep (isConnected check).
+//
+// Module-level singleton: shared across all LiveTemplateClient
+// instances in the window. Two clients arming DIFFERENT elements
+// each get their own entry; the shared window hashchange listener
+// iterates the map and dispatches through every armed entry's own
+// send, so a multi-client page sees each client receive its hash
+// event. Teardown is scoped per root via teardownURLHashForRoot, so
+// clients don't tear down each other's listeners.
+//
+// Same-element multi-arm is "last writer wins": the Map key is the
+// element, so a second client arming the same element runs the
+// existing entry's cleanup() and replaces it. The first client's
+// send is orphaned. This matches area-select's behavior and is fine
+// for the documented single-arm-per-element contract.
+const urlHashArmed = new Map();
+// urlHashWindowListener is the single window-level `hashchange`
+// listener shared across all armed elements. Registered on first arm,
+// removed when the armed map becomes empty. Per-element listeners
+// would multi-fire for the (rare) case of multiple armed elements;
+// one shared listener iterating the armed map keeps the dispatch
+// count deterministic.
+let urlHashWindowListener = null;
+/**
+ * Apply url-hash directives. `lvt-fx:url-hash="<actionName>"` plus a
+ * `data-lvt-url-hash="<hash>"` attribute on an element (typically the
+ * `<body>`) wires a two-way bridge between server state and
+ * `location.hash`:
+ *
+ *  - **State → URL** (every render): if `data-lvt-url-hash` differs
+ *    from `location.hash`, mirror the data-attr into the URL via
+ *    `history.pushState` when the path component changed (everything
+ *    before the first `:`) or `history.replaceState` when only the
+ *    target (line range / anchor) changed. Replace is the right
+ *    default for line scrolls so the back-button cycles between files,
+ *    not between every clicked line.
+ *  - **URL → State** (on `hashchange` AND initial arm): dispatch
+ *    `{action: <actionName>, data: {hash: <hash>}}` so the server can
+ *    parse the hash and update its state (which then renders back as
+ *    a matching data-attr — closing the loop).
+ *
+ * The directive uses `history.pushState`/`replaceState` (not
+ * `location.hash = ...`) for the state→URL direction precisely so
+ * those writes do NOT fire `hashchange` — only true user-initiated
+ * navigation (anchor click, address-bar edit, back-button) reaches
+ * the URL→state listener. This avoids the obvious infinite loop.
+ *
+ * Idempotent across renders: same action → keep listener + update
+ * send. Different action → cleanup + re-arm. Detached / attribute-
+ * removed elements are swept on every call (same pattern as
+ * area-select). The window listener is registered on first arm and
+ * removed when the armed map becomes empty.
+ *
+ * Coexistence with `setupHashLink`: prereview-style hashes
+ * (`README.md:L4`, `foo/bar.html:h-anchor`) never match a
+ * `document.getElementById(...)`, so the existing dialog/popover/
+ * details hash machinery silently no-ops. If a deep-link hash
+ * happens to collide with an element id, both handlers will fire —
+ * the server is expected to no-op on hashes that don't resolve to a
+ * known file.
+ *
+ * **Pre-encoding contract**: `data-lvt-url-hash` must hold the hash
+ * value already in URL-encoded form. The directive writes the
+ * attribute verbatim into `history.pushState`/`replaceState`, so a
+ * value containing spaces, `[`, `]`, `%`, or other reserved
+ * characters needs to be percent-encoded by the server. The hash
+ * sent to the action on `hashchange` is also passed through unmodified
+ * (no decoding) — both directions are byte-exact mirrors of what's
+ * in `location.hash`.
+ *
+ * **URL/state divergence after a non-deep-link initial load**: if
+ * the user lands with a native-anchor hash (`#hero`) AND the server
+ * has a selected file, the directive leaves the URL on `#hero` (case
+ * b) — URL and server state diverge until the user navigates. This
+ * is intentional: popovers/anchors aren't ours to overwrite. The
+ * next user action that triggers a server render will re-sync only
+ * once URL and state share a deep-link hash.
+ *
+ * **Path-only deep links require an extension**: the
+ * `looksLikeDeepLinkHash` heuristic dispatches only hashes
+ * containing `:`, `/`, or `.`. Extension-less root files
+ * (`#Makefile`, `#Dockerfile`, `#LICENSE`) won't dispatch as
+ * path-only deep links — use the line form (`#Makefile:L1`)
+ * instead. The trade-off favours not clobbering native-anchor
+ * machinery for single-token hashes.
+ */
+function handleURLHashDirective(rootElement, send) {
+    // Sweep stale entries first — disconnected hosts AND hosts whose
+    // attribute was removed by a server diff. Iterate via Array.from so
+    // cleanup()'s delete() doesn't disturb the iterator.
+    for (const [element, entry] of Array.from(urlHashArmed)) {
+        if (!element.isConnected ||
+            !element.hasAttribute("lvt-fx:url-hash")) {
+            entry.cleanup();
+        }
+    }
+    // Match the root itself, descendants, AND the document body. The
+    // url-hash directive is typically placed on `<body>`, but livetemplate
+    // auto-injects its `<div data-lvt-id>` INSIDE body, so the rootElement
+    // passed by the client is the wrapper div — a strict descendant of
+    // body. Without the body check, a directive on `<body>` would never
+    // arm. We accept body placement because URL hash is page-global
+    // anyway; the directive's lifecycle is still tied to the wrapper via
+    // teardownURLHashForRoot (called on disconnect of the wrapper).
+    const matches = [];
+    if (rootElement instanceof HTMLElement &&
+        rootElement.hasAttribute("lvt-fx:url-hash")) {
+        matches.push(rootElement);
+    }
+    const body = rootElement.ownerDocument?.body;
+    if (body &&
+        body !== rootElement &&
+        body.hasAttribute("lvt-fx:url-hash") &&
+        !matches.includes(body)) {
+        matches.push(body);
+    }
+    rootElement
+        .querySelectorAll("[lvt-fx\\:url-hash]")
+        .forEach((el) => {
+        if (!matches.includes(el))
+            matches.push(el);
+    });
+    if (matches.length === 0)
+        return;
+    for (const el of matches) {
+        const action = el.getAttribute("lvt-fx:url-hash");
+        if (!action) {
+            console.warn(`lvt-fx:url-hash requires an action name, got: ${JSON.stringify(action)}`);
+            continue;
+        }
+        const dataHash = el.getAttribute("data-lvt-url-hash") || "";
+        const existing = urlHashArmed.get(el);
+        if (existing && existing.action === action) {
+            existing.updateSend(send);
+            mirrorDataAttrToLocation(existing, dataHash);
+            continue;
+        }
+        if (existing)
+            existing.cleanup();
+        const entry = attachURLHash(el, action, send);
+        urlHashArmed.set(el, entry);
+        // First-arm sync: three cases, in priority order.
+        const initialLocation = window.location.hash.replace(/^#/, "");
+        if (initialLocation &&
+            initialLocation !== dataHash &&
+            looksLikeDeepLinkHash(initialLocation)) {
+            // (a) URL has a deep-link hash that differs from server state.
+            // URL "wins" on initial load — dispatch so the server can
+            // reconcile, and seed currentDataHash so the converging render
+            // doesn't try to mirror over the user's URL.
+            entry.currentDataHash = initialLocation;
+            send({ action, data: { hash: initialLocation } });
+        }
+        else if (initialLocation && !looksLikeDeepLinkHash(initialLocation)) {
+            // (b) URL has a non-deep-link hash (e.g. `#hero` opening a
+            // popover, or a native heading anchor). Leave it alone — it
+            // belongs to other machinery (setupHashLink, native scroll).
+            // Seed currentDataHash so a later mirror sees the data-attr
+            // as the baseline to compare against, and only writes when
+            // the user navigates away from the popover/anchor.
+            entry.currentDataHash = dataHash;
+        }
+        else {
+            // (c) URL is empty (or already matches the server). Mirror the
+            // server's hash into the URL if any.
+            mirrorDataAttrToLocation(entry, dataHash);
+        }
+    }
+}
+/**
+ * Cancel url-hash listeners for every armed element under root. Same
+ * lifecycle role as teardownAreaSelectForRoot.
+ */
+function teardownURLHashForRoot(rootElement) {
+    // Includes body when body is an ancestor of rootElement and body is
+    // armed — the directive accepts body placement (see the matcher in
+    // handleURLHashDirective), so teardown must symmetrically clean up
+    // both directions.
+    //
+    // Multi-client caveat: a body-armed entry is shared across all
+    // LiveTemplateClient instances (Map key is the element, so only one
+    // entry per body). Tearing down client A's root will therefore also
+    // tear down a body listener that client B armed last — there's no
+    // "owner" tracked. Acceptable for the single-client case (the
+    // common deployment) and matches the same-element-multi-arm
+    // last-writer-wins behavior in attachURLHash. A "fix" that
+    // restricted the body-cleanup branch to client A would leak
+    // client A's own body listener — don't do that without also
+    // tracking entry ownership.
+    const body = rootElement.ownerDocument?.body;
+    for (const [element, entry] of Array.from(urlHashArmed)) {
+        if (rootElement.contains(element)) {
+            entry.cleanup();
+            continue;
+        }
+        if (body && element === body && body.contains(rootElement)) {
+            entry.cleanup();
+        }
+    }
+}
+// mirrorDataAttrToLocation pushes `dataHash` into `location.hash` if
+// it differs from what's already in the URL. Chooses push vs replace
+// by comparing the path component (everything before the first `:`)
+// against the current location.hash's path: a path change is a "file
+// switch" (user-meaningful back-button entry) and gets pushState;
+// any other change is a target-only update (line scroll / anchor
+// scroll) and gets replaceState. Updates entry.currentDataHash so a
+// subsequent render with the same data-attr no-ops.
+//
+// Initial-mirror special case: if the URL was empty when we're
+// mirroring (no prior hash to compare against), use replaceState even
+// though the path-component comparison would say "changed". An empty
+// URL → first server hash isn't a "navigation" — we're establishing
+// the initial state. Using pushState here would let Back land the
+// user on `url-without-hash`, which re-triggers the same arm and
+// pushes the same hash again. Loop.
+//
+// Empty-dataHash special case: if the server transitions FROM a
+// selected file TO no-selection (state.URLHash() returns ""), we
+// would otherwise wipe location.hash entirely — including hashes the
+// directive doesn't own (a popover #hero the user opened during the
+// session). To stay safe, only clear when the URL currently holds a
+// deep-link-shaped hash; non-deep-link hashes are left alone.
+function mirrorDataAttrToLocation(entry, dataHash) {
+    if (entry.currentDataHash === dataHash)
+        return;
+    const currentLocation = window.location.hash.replace(/^#/, "");
+    if (currentLocation === dataHash) {
+        entry.currentDataHash = dataHash;
+        return;
+    }
+    if (currentLocation !== "" && !looksLikeDeepLinkHash(currentLocation)) {
+        // URL is on something not ours (popover id, native anchor) —
+        // don't clobber it, regardless of what the server's data-attr
+        // says. This covers BOTH the server-clears case (dataHash="")
+        // and the rarer server-changes-selection-while-popover-open
+        // case (dataHash transitions from one file to another while
+        // the URL is parked on a non-deep-link hash).
+        entry.currentDataHash = dataHash;
+        return;
+    }
+    warnIfUnencodedHash(dataHash);
+    const targetURL = dataHash ? `#${dataHash}` : window.location.pathname + window.location.search;
+    const oldPath = currentLocation.split(":")[0];
+    const newPath = dataHash.split(":")[0];
+    // Preserve existing history.state — passing `null` would clobber
+    // anything other SPA-like code on the page stores there (scroll
+    // position, modal flag, etc.). The state object is independent of
+    // the URL we're rewriting, so carrying it forward is the right
+    // default.
+    const currentState = window.history.state;
+    // Empty currentLocation means we're establishing the URL from a
+    // blank slate (initial render with no prior URL hash) — that's NOT
+    // a back-button-meaningful navigation, so always replaceState.
+    // Otherwise: a path change is a file switch (push), a target-only
+    // change is a line/anchor scroll (replace).
+    if (currentLocation !== "" && oldPath !== newPath) {
+        window.history.pushState(currentState, "", targetURL);
+    }
+    else {
+        window.history.replaceState(currentState, "", targetURL);
+    }
+    entry.currentDataHash = dataHash;
+}
+// warnIfUnencodedHash flags `data-lvt-url-hash` values containing
+// characters that should be percent-encoded (raw space, `<`, `>`,
+// `"`, ``` ` ```, `#`, `[`, `]`, `%`). The directive writes the
+// hash verbatim into `pushState`/`replaceState`, so an unencoded
+// value will silently produce a malformed URL — `location.hash`
+// reads back differently from what was set. Cheap dev-time guard
+// against a server-side contract slip; dedupes by value to avoid
+// log spam.
+//
+// `%` is included because a raw `%` not followed by two hex digits
+// is itself a percent-encoding error. The check is a heuristic
+// (won't catch every malformed escape), but covers the common
+// "forgot to encode" cases.
+const urlHashUnencodedWarned = new Set();
+/**
+ * Test-only: reset the per-page dedupe Set that suppresses repeated
+ * `warnIfUnencodedHash` calls for the same hash value. Production
+ * code shouldn't need this — the Set is bounded by the number of
+ * unique malformed hashes — but tests that re-use the same hash
+ * across cases need to clear it or the second test won't see the
+ * warning. Mirrors `__resetAnimatedElementsForTesting`.
+ */
+function __resetURLHashUnencodedWarnedForTesting() {
+    urlHashUnencodedWarned.clear();
+}
+function warnIfUnencodedHash(hash) {
+    if (!hash || urlHashUnencodedWarned.has(hash))
+        return;
+    if (/[ <>"`#\[\]]/.test(hash) || /%(?![0-9A-Fa-f]{2})/.test(hash)) {
+        urlHashUnencodedWarned.add(hash);
+        console.warn(`lvt-fx:url-hash: data-lvt-url-hash="${hash}" contains characters that should be percent-encoded. The directive writes it verbatim into history.pushState/replaceState; malformed URLs result. Server-side FormatHash (or equivalent) should percent-escape path segments and target ids before serialization.`);
+    }
+}
+// looksLikeDeepLinkHash discriminates URL hashes the prereview deep-
+// link grammar can produce (file path with optional :L<n> or :h-id)
+// from hashes that belong to other native machinery (HTML element
+// anchors, dialog/popover/details ids, etc.). Deep-link hashes always
+// contain at least one of: `:` (target separator), `/` (nested path),
+// or `.` (file extension). Empty → false.
+//
+// False positives are possible but cheap. A heading id like
+// `#v1.0.0`, `#menu/item`, or `#key:value` matches this heuristic
+// and will dispatch the action — but the consuming server is
+// expected to no-op on hashes whose path doesn't resolve to a known
+// file (prereview's SetURLHash does, via the loadDiffCached failure
+// path). The cost is one wasted roundtrip per false positive, which
+// is acceptable for the alternative of missing real deep links.
+//
+// False negatives: extension-less filenames at the repo root —
+// `#Makefile`, `#Dockerfile`, `#LICENSE` — don't match this
+// heuristic and won't be dispatched as path-only deep links. The
+// workaround is the line-form (`#Makefile:L1`), which always
+// dispatches. This trade-off is deliberate: a heuristic that
+// matched single-token hashes would also clobber every native
+// anchor / popover id, which is a much worse default. Consumers
+// that need extension-less file deep links can build a richer
+// directive on top.
+function looksLikeDeepLinkHash(hash) {
+    if (!hash)
+        return false;
+    return hash.includes(":") || hash.includes("/") || hash.includes(".");
+}
+function attachURLHash(el, action, initialSend) {
+    const entry = {
+        action,
+        send: initialSend,
+        cleanup: () => {
+            urlHashArmed.delete(el);
+            if (urlHashArmed.size === 0 && urlHashWindowListener) {
+                window.removeEventListener("hashchange", urlHashWindowListener);
+                urlHashWindowListener = null;
+            }
+        },
+        updateSend: (s) => {
+            entry.send = s;
+        },
+        currentDataHash: "",
+    };
+    if (!urlHashWindowListener) {
+        urlHashWindowListener = () => {
+            const hash = window.location.hash.replace(/^#/, "");
+            // Only dispatch hashes that look like deep-link targets — they
+            // contain `:` (target separator), `/` (nested path), or `.`
+            // (file extension). Plain element-id hashes like `#hero` or
+            // `#confirm-delete-xyz` belong to the native anchor / dialog /
+            // popover / details machinery (setupHashLink handles those) and
+            // would otherwise be dispatched here, prompt a server no-op,
+            // then get clobbered by the mirror step when the server's
+            // data-attr (unchanged) doesn't match.
+            //
+            // Empty hash (user cleared the URL bar) is also intentionally
+            // ignored. The directive treats the server as the source of
+            // truth for "what's selected"; an empty URL is "user navigated
+            // away from a hash" but not "deselect everything". If the user
+            // wants to deselect, they use the in-app affordance
+            // (clearSelection / Escape) which makes the server emit an
+            // empty data-attr — at which point the mirror step propagates
+            // the empty hash back to the URL.
+            if (!looksLikeDeepLinkHash(hash))
+                return;
+            // Iterate via Array.from in case a dispatched action triggers a
+            // render that mutates the armed map (e.g. tears down this
+            // element). Each armed entry dispatches through its OWN send +
+            // action so multi-arm is deterministic — typically the body is
+            // the only armed element so this is one iteration.
+            for (const e of Array.from(urlHashArmed.values())) {
+                // Record the user-driven hash as the new baseline so the
+                // next render's mirror step doesn't immediately revert it.
+                e.currentDataHash = hash;
+                e.send({ action: e.action, data: { hash } });
+            }
+        };
+        window.addEventListener("hashchange", urlHashWindowListener);
+    }
+    return entry;
+}
+// attachAreaSelect captures `send` in a mutable local so the
+// idempotent re-arm path (same element, same action) can swap it via
+// the returned `updateSend` callback without tearing down + rebuilding
+// listeners. Listeners reference the closure-captured `send` variable
+// directly, so reassigning it propagates instantly. This guards
+// against the stale-closure trap a caller would hit if their `send`
+// reference changed across renders — e.g. a reconnect rebuilt the
+// transport.
+function attachAreaSelect(el, action, initialSend) {
+    let send = initialSend;
+    let overlay = null;
+    let startClientX = 0;
+    let startClientY = 0;
+    let pointerId = -1;
+    // Capture the parent at pointerdown time so a server diff that moves
+    // the host to a NEW parent mid-drag doesn't split the drag across
+    // two positioning contexts. updateOverlay positions against this
+    // cached parent for the lifetime of the gesture; the overlay itself
+    // stays a child of the parent we appended it to (overlay removal
+    // uses overlay.parentElement, which is independent).
+    let dragParent = null;
+    // Cache the host's rect at pointerdown — startClientX/Y are captured
+    // in the SAME frame, so the start corner is meaningful only against
+    // the rect that existed then. If a server diff repositions the host
+    // mid-drag, finalize would otherwise clamp the (old-coord-system)
+    // startClientX against the new rect and silently produce wrong
+    // fractions. Anchoring to the start-rect keeps the dispatched
+    // rectangle pinned to the visual region the user actually dragged.
+    let startRect = null;
+    const removeOverlay = () => {
+        if (overlay) {
+            // Element.remove() is a no-op if the node isn't in the DOM,
+            // so we don't need the parent-null guard the older two-step
+            // pattern needed.
+            overlay.remove();
+        }
+        overlay = null;
+    };
+    const finalize = (e, dispatch) => {
+        if (pointerId === -1)
+            return;
+        // CRITICAL ORDER: reset pointerId + dragParent + startRect BEFORE
+        // calling releasePointerCapture. Chromium fires lostpointercapture
+        // SYNCHRONOUSLY during releasePointerCapture, which lands in
+        // onLostCapture → finalize(null, false). Without the early reset,
+        // the nested finalize sees pointerId still matching and runs to
+        // completion (clearing startRect), then the outer finalize
+        // resumes with startRect == null and silently drops the
+        // dispatched action. Resetting first makes the nested call
+        // return at the `pointerId === -1` guard, leaving outer state
+        // intact.
+        const capturedPointerId = pointerId;
+        const rect = startRect;
+        pointerId = -1;
+        dragParent = null;
+        startRect = null;
+        try {
+            el.releasePointerCapture(capturedPointerId);
+        }
+        catch {
+            // Capture may already be gone (e.g. pointercancel) — ignore.
+        }
+        // Remove the per-gesture pointerleave fallback so a NEXT drag
+        // doesn't inherit a stale listener from this one. {once: true}
+        // only auto-removes if it fires; a stuck drag never fired it.
+        el.removeEventListener("pointerleave", onPointerLeaveCancel);
+        if (!dispatch || !e || !rect) {
+            removeOverlay();
+            return;
+        }
+        if (rect.width <= 0 || rect.height <= 0) {
+            removeOverlay();
+            return;
+        }
+        // Clamp the two corners to the rect BEFORE computing fractions so
+        // a drag that escapes the element still yields a rectangle inside
+        // it (x ∈ [0,1], w ∈ [0,1-x]). Otherwise a far-off-rect endpoint
+        // would push w past 1 even with x already > 0.
+        const rectRight = rect.left + rect.width;
+        const rectBottom = rect.top + rect.height;
+        const x0 = clampRange(Math.min(startClientX, e.clientX), rect.left, rectRight);
+        const y0 = clampRange(Math.min(startClientY, e.clientY), rect.top, rectBottom);
+        const x1 = clampRange(Math.max(startClientX, e.clientX), rect.left, rectRight);
+        const y1 = clampRange(Math.max(startClientY, e.clientY), rect.top, rectBottom);
+        const x = (x0 - rect.left) / rect.width;
+        const y = (y0 - rect.top) / rect.height;
+        const w = (x1 - x0) / rect.width;
+        const h = (y1 - y0) / rect.height;
+        removeOverlay();
+        // Reject zero-area rectangles outright. The MIN_AREA_FRACTION
+        // check below uses `&&` (drop only when BOTH dims are small) so
+        // a wide-but-thin selection is preserved — but a literal
+        // 60%×0 (or 0×60%) collapses to no region, can't be rendered
+        // sensibly, and would divide by zero in any pixel-space
+        // conversion downstream. Drop independently of the threshold.
+        if (w <= 0 || h <= 0)
+            return;
+        // Drop when BOTH dimensions are below the threshold (intentional
+        // `&&` — NOT `||`). A wide-but-thin drag (e.g. an underline across
+        // an annotated row) or a tall-but-thin drag (e.g. a vertical
+        // highlight) is a real selection in this directive's contract,
+        // not an accidental click. `||` would drop those legitimate
+        // gestures. The click-vs-drag boundary lives in "the rect has
+        // basically no area" — that's both dims below the threshold.
+        if (w < MIN_AREA_FRACTION && h < MIN_AREA_FRACTION) {
+            // Treat as a click, not a drag. Don't dispatch; let normal click
+            // handlers (if any) run via the platform.
+            return;
+        }
+        send({ action, data: { x, y, w, h } });
+    };
+    const onPointerLeaveCancel = (e) => {
+        // Fallback for the rare case where setPointerCapture failed: without
+        // capture, pointermove + pointerup stop arriving once the pointer
+        // leaves the host, freezing the overlay. Treating pointerleave as
+        // a cancel keeps the overlay from getting stuck on screen.
+        // Guard on pointerId — in multi-touch, a SECONDARY pointer's
+        // leave shouldn't cancel the primary drag.
+        if (e.pointerId !== pointerId)
+            return;
+        finalize(null, false);
+    };
+    // Chromium fires `dragstart` on an <img> after the first mousemove
+    // following mousedown, yanking the gesture away from pointer events
+    // before pointerup arrives — the overlay flashes and capture is
+    // lost. preventDefault on dragstart suppresses the native image
+    // drag without breaking pointer events. Cheap to attach on every
+    // element type (non-img hosts simply never fire dragstart).
+    const onDragStart = (e) => e.preventDefault();
+    const onPointerDown = (e) => {
+        // Only primary button (left mouse / single touch / pen tip). Modifier
+        // keys passed through so the server-side handler can decide what to
+        // do with them via subsequent renders.
+        if (!e.isPrimary || e.button !== 0)
+            return;
+        // Re-entrancy guard: if a prior drag never finished (e.g. capture
+        // failed silently, then pointer left the element with no pointerup
+        // ever delivered), the closed-over pointerId variable would still
+        // hold the stale id. Cancel the prior drag — removing its overlay
+        // and listeners — before starting a fresh one.
+        if (pointerId !== -1)
+            finalize(null, false);
+        const parent = el.parentElement;
+        if (!parent)
+            return; // overlay needs a positioned container
+        // Dev-time check: if the parent doesn't establish a positioning
+        // context, the overlay's `position: absolute` will resolve against
+        // the nearest positioned ANCESTOR — a distant element with no
+        // visible relationship to the host. Result: overlay paints in
+        // the wrong place with no error, just a confusing visual.
+        // Check against the positive list of positioned values; the
+        // default "static" and an unset/empty value both fail it (jsdom
+        // returns "" for unset position). Dedupe via WeakSet so a user
+        // dragging repeatedly on the same mis-configured parent gets ONE
+        // console message, not one per pointerdown.
+        if (!areaSelectWarnedParents.has(parent)) {
+            const parentPos = window.getComputedStyle(parent).position;
+            if (parentPos !== "relative" &&
+                parentPos !== "absolute" &&
+                parentPos !== "fixed" &&
+                parentPos !== "sticky") {
+                console.warn("lvt-fx:area-select: parentElement has no positioning context; the drag overlay will be mis-positioned. " +
+                    "Add position:relative (or absolute/fixed/sticky) to the parent.", parent);
+                areaSelectWarnedParents.add(parent);
+            }
+        }
+        startClientX = e.clientX;
+        startClientY = e.clientY;
+        pointerId = e.pointerId;
+        dragParent = parent;
+        startRect = el.getBoundingClientRect();
+        let captureOk = false;
+        try {
+            el.setPointerCapture(pointerId);
+            captureOk = true;
+        }
+        catch {
+            // Capture failure is non-fatal — without it, leaving the element
+            // mid-drag will lose pointermove. Fall back to pointerleave as
+            // the cancel signal so the overlay can't get stuck.
+        }
+        if (!captureOk) {
+            el.addEventListener("pointerleave", onPointerLeaveCancel, { once: true });
+        }
+        overlay = document.createElement("div");
+        overlay.className = "lvt-area-select-overlay";
+        overlay.setAttribute("aria-hidden", "true");
+        // Inline styles so the directive doesn't depend on a CSS class
+        // shipped by the consumer. Consumers can override via the class
+        // selector if they want a different look.
+        overlay.style.cssText =
+            "position:absolute;pointer-events:none;border:2px solid var(--lvt-area-select-color,#4cc2ff);" +
+                "background:var(--lvt-area-select-fill,rgba(76,194,255,0.18));box-sizing:border-box;" +
+                "z-index:var(--lvt-area-select-z-index,9999);";
+        parent.appendChild(overlay);
+        updateOverlay(e);
+        // NOT calling e.preventDefault() here: doing so on pointerdown
+        // suppresses the compatibility mouse events (mousedown → mouseup
+        // → click), so a small-rect drag (which finalize() treats as a
+        // click) would never reach the host's click handlers. The
+        // directive's contract promises clicks still bubble. Text-
+        // selection during drag is the consumer's responsibility — set
+        // `user-select: none` on the host (the contract docs this).
+    };
+    const updateOverlay = (e) => {
+        if (!overlay)
+            return;
+        // Use the parent captured at pointerdown — if a server diff
+        // moved `el` to a new parent mid-drag, re-fetching el.parentElement
+        // here would compute against the new container while the overlay
+        // lives in the old, paint at the wrong place for the rest of the
+        // gesture.
+        const parent = dragParent;
+        if (!parent)
+            return;
+        const elRect = el.getBoundingClientRect();
+        const parentRect = parent.getBoundingClientRect();
+        // Convert viewport coords (clientX/Y) to position:absolute CSS
+        // offsets inside the parent. Three corrections, all subtracted
+        // from / added to the same way for every value we compute:
+        //
+        //   1. parentRect.left/top — getBoundingClientRect is in viewport
+        //      coords; CSS offsets are relative to the parent's box.
+        //   2. parent.clientLeft/Top — position:absolute is measured from
+        //      the padding box; getBoundingClientRect returns the border
+        //      box. A parent with a CSS border would otherwise shift the
+        //      overlay by the border width.
+        //   3. parent.scrollLeft/Top — when the parent is scrolled, an
+        //      element at viewport_x = parentRect.left has CSS_left =
+        //      parent.scrollLeft (not 0). Without adding scroll back in,
+        //      the overlay paints offset by the scroll amount.
+        const borderL = parent.clientLeft;
+        const borderT = parent.clientTop;
+        const scrollL = parent.scrollLeft;
+        const scrollT = parent.scrollTop;
+        const toCSSLeft = (vx) => vx - parentRect.left - borderL + scrollL;
+        const toCSSTop = (vy) => vy - parentRect.top - borderT + scrollT;
+        const left = toCSSLeft(Math.min(startClientX, e.clientX));
+        const top = toCSSTop(Math.min(startClientY, e.clientY));
+        const width = Math.abs(e.clientX - startClientX);
+        const height = Math.abs(e.clientY - startClientY);
+        // Clamp to the host's rendered rect (in the same CSS coord space)
+        // so a drag that runs off the edge doesn't paint outside the host.
+        const minLeft = toCSSLeft(elRect.left);
+        const minTop = toCSSTop(elRect.top);
+        const maxRight = minLeft + elRect.width;
+        const maxBottom = minTop + elRect.height;
+        const clampedLeft = Math.max(minLeft, Math.min(left, maxRight));
+        const clampedTop = Math.max(minTop, Math.min(top, maxBottom));
+        const clampedRight = Math.max(minLeft, Math.min(left + width, maxRight));
+        const clampedBottom = Math.max(minTop, Math.min(top + height, maxBottom));
+        overlay.style.left = `${clampedLeft}px`;
+        overlay.style.top = `${clampedTop}px`;
+        overlay.style.width = `${Math.max(0, clampedRight - clampedLeft)}px`;
+        overlay.style.height = `${Math.max(0, clampedBottom - clampedTop)}px`;
+    };
+    const onPointerMove = (e) => {
+        if (e.pointerId !== pointerId)
+            return;
+        // Host removed from the DOM mid-drag (e.g. server diff replaced it).
+        // Without this, the overlay would be left orphaned under the parent
+        // because the host's cleanup never runs.
+        if (!el.isConnected) {
+            finalize(null, false);
+            return;
+        }
+        updateOverlay(e);
+    };
+    const onPointerUp = (e) => {
+        if (e.pointerId !== pointerId)
+            return;
+        if (!el.isConnected) {
+            finalize(null, false);
+            return;
+        }
+        finalize(e, true);
+    };
+    const onPointerCancel = (e) => {
+        if (e.pointerId !== pointerId)
+            return;
+        finalize(e, false);
+    };
+    // lostpointercapture handles the rare case where the platform yanks
+    // capture (OS gesture, another setPointerCapture call). Guard on
+    // pointerId — another code path could call setPointerCapture for a
+    // DIFFERENT pointer on the same element, and we mustn't cancel
+    // our in-progress drag because of an unrelated release.
+    const onLostCapture = (e) => {
+        if (e.pointerId === pointerId)
+            finalize(null, false);
+    };
+    el.addEventListener("pointerdown", onPointerDown);
+    el.addEventListener("pointermove", onPointerMove);
+    el.addEventListener("pointerup", onPointerUp);
+    el.addEventListener("pointercancel", onPointerCancel);
+    el.addEventListener("lostpointercapture", onLostCapture);
+    el.addEventListener("dragstart", onDragStart);
+    const cleanup = () => {
+        el.removeEventListener("pointerdown", onPointerDown);
+        el.removeEventListener("pointermove", onPointerMove);
+        el.removeEventListener("pointerup", onPointerUp);
+        el.removeEventListener("pointercancel", onPointerCancel);
+        el.removeEventListener("lostpointercapture", onLostCapture);
+        el.removeEventListener("pointerleave", onPointerLeaveCancel);
+        el.removeEventListener("dragstart", onDragStart);
+        finalize(null, false);
+        areaSelectArmed.delete(el);
+    };
+    return {
+        action,
+        cleanup,
+        updateSend: (s) => {
+            send = s;
+        },
+    };
+}
+function clampRange(n, lo, hi) {
+    if (!Number.isFinite(n) || n < lo)
+        return lo;
+    if (n > hi)
+        return hi;
+    return n;
+}
 //# sourceMappingURL=directives.js.map