view-anchor 0.1.2 → 0.2.1

package/dist/view-anchor.js

@@ -1,12 +1,10 @@
 const ZERO = { x: 0, y: 0, width: 0, height: 0 };
-// Round to integers (setBounds rejects fractionals). Width/height are clamped
-// to ≥0 (negative area is meaningless and `0` is the canonical "hidden"
-// signal). x/y are NOT clamped: a position is a position — an anchored overlay
-// scrolled past the top/left edge has a legitimately NEGATIVE origin, and
-// flooring it to 0 would pin the native view at the edge instead of letting it
-// track its element off-screen. (Each consumer's IPC schema enforces its own
-// origin policy — some allow negatives; a placeholder always stays on-screen,
-// so its NonNegInt schema is unaffected.)
+// Replaces a disposed instance's publish callback so a retained handle does
+// not keep the caller's original callback (and whatever it captured) alive.
+const NOOP_PUBLISH = () => false;
+// Round to integer pixels. Width and height are clamped to >= 0 (0 represents
+// a collapsed rect). Coordinates (x, y) can be negative when an element is
+// scrolled out of view; clamping them to 0 would pin the view to the screen edge.
 const clampRect = (r) => ({
     x: Math.round(r.x),
     y: Math.round(r.y),
@@ -14,67 +12,78 @@ const clampRect = (r) => ({
     height: Math.max(0, Math.round(r.height)),
 });
 /**
- * Create an anchor binding ONE native view's bounds to `target`'s geometry.
+ * Bind a native view or external surface to the geometry of `target`.
  *
- * Imperative core — no React, no Electron. Behaviour:
- *   - `present === true`: publish `target.getBoundingClientRect()` (x/y rounded,
- *     width/height `Math.max(0, Math.round(...))`) immediately, then re-publish
- *     SYNCHRONOUSLY on every `ResizeObserver` tick and window `resize`.
- *   - `present === false`: publish `{0,0,0,0}` immediately; do not observe.
- *   - `update(opts)`: re-apply synchronously.
- *   - `dispose()`: stop observing, never publish again.
+ * - `present === true`: measures `target.getBoundingClientRect()` and publishes
+ *   immediately, then re-measures synchronously on ResizeObserver and window resize.
+ * - `present === false`: publishes a zero rect ({ x: 0, y: 0, width: 0, height: 0 })
+ *   and stops observing.
+ * - `update(opts)`: re-applies options immediately.
+ * - `dispose()`: stops observing and prevents any further publishes.
  *
- * Synchronous, NOT RAF-deferred: the native overlay is a cross-process
- * `WebContentsView` whose `setBounds` already lands ~1 compositor frame behind
- * the renderer's DOM paint (the two processes composite on different frames).
- * Deferring the measure+publish to a RAF stacked a SECOND frame on top — during
- * a height/splitter drag that read as the overlay visibly trailing the region
- * edge (worst when GROWING, where the not-yet-followed edge exposes background).
- * Publishing in the observer tick itself removes that self-inflicted frame and
- * leaves only the unavoidable cross-process frame (masked by matching the
- * placeholder/desk background colour). The anti-flood role the RAF used to play
- * — collapsing a burst of RO+resize ticks in one frame into one publish — is now
- * served by `lastPublished` dedup: a tick whose measured rect is byte-identical
- * to the last published one is dropped, so a continuous drag still emits at most
- * one publish per distinct rect.
- *
- * Teardown safety: there is no queued frame to outrun a state change — every
- * emit reads `disposed`/`present` synchronously, so a tick after
- * `update`/`dispose` can never write a stale rect over the live one.
+ * Synchronous publishing: measurement and publishing occur directly in the
+ * observer tick. Cross-process setBounds calls already have a compositor delay;
+ * adding requestAnimationFrame would add a second frame of visual lag during drag
+ * operations. High-frequency updates are deduplicated against the last accepted rect.
  */
 export function createViewAnchor(target, opts) {
     let present = opts.present;
     let publish = opts.publish;
     let observer = null;
-    // The last rect handed to `publish`, for dedup-coalescing (see header). Reset
-    // to `null` on every `apply()` so a state change (e.g. zoom, which rides in
-    // the `publish` closure, not in `Bounds`) always forces one fresh publish
-    // even when the geometry is unchanged.
+    // Local, clearable alias for the `target` parameter so dispose() can drop
+    // the strong reference without widening the public parameter's type.
+    let targetRef = target;
+    // Last rect sent to publish. Reset on apply() so state changes (such as zoom)
+    // force a re-publish even if the geometry did not change.
     let lastPublished = null;
+    let publicationRevision = 0;
     let disposed = false;
     const measure = () => {
-        const r = target.getBoundingClientRect();
+        const r = targetRef.getBoundingClientRect();
+        // Drop ticks with non-finite values (NaN / Infinity cannot be sent over IPC).
+        if (!Number.isFinite(r.left) ||
+            !Number.isFinite(r.top) ||
+            !Number.isFinite(r.width) ||
+            !Number.isFinite(r.height))
+            return null;
         return clampRect({ x: r.left, y: r.top, width: r.width, height: r.height });
     };
     const sameRect = (a, b) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
-    // Measure + publish SYNCHRONOUSLY on the triggering tick — no RAF defer (see
-    // header for why). Bail if torn down or detached, and dedup a rect
-    // byte-identical to the last published one (collapses a same-frame RO+resize
-    // burst, and a steady drag that re-fires the same final rect, into one).
+    const publishCandidate = (candidate) => {
+        const previous = lastPublished;
+        const attempt = ++publicationRevision;
+        lastPublished = candidate;
+        try {
+            const accepted = publish(candidate) !== false;
+            // A reentrant dispose() during publish() already cleared lastPublished;
+            // do not resurrect the pre-dispose value over that terminal state.
+            if (!accepted && publicationRevision === attempt && !disposed)
+                lastPublished = previous;
+            return accepted;
+        }
+        catch (error) {
+            if (publicationRevision === attempt && !disposed)
+                lastPublished = previous;
+            throw error;
+        }
+    };
+    // Measure and publish synchronously on each observer tick.
+    // Drops duplicate rects to coalesce same-frame resize events.
     const emit = () => {
         if (disposed || !present)
             return;
         const m = measure();
+        if (!m)
+            return;
         if (lastPublished && sameRect(lastPublished, m))
             return;
-        lastPublished = m;
-        publish(m);
+        publishCandidate(m);
     };
     const startObserving = () => {
         if (observer)
             return;
         observer = new ResizeObserver(emit);
-        observer.observe(target);
+        observer.observe(targetRef);
         window.addEventListener('resize', emit);
     };
     const stopObserving = () => {
@@ -84,20 +93,19 @@ export function createViewAnchor(target, opts) {
         }
         window.removeEventListener('resize', emit);
     };
-    // Apply the current (present, publish) synchronously. Reset `lastPublished`
-    // first so the publish below is never dedup-skipped — a state change (zoom,
-    // present flip, new publish target) must always re-emit even if the geometry
-    // is byte-identical to the previous emit.
+    // Apply current options synchronously. Reset lastPublished so state changes
+    // always re-publish even if dimensions have not changed.
     const apply = () => {
         lastPublished = null;
         if (present) {
             startObserving();
-            lastPublished = measure();
-            publish(lastPublished);
+            const measured = measure();
+            if (measured)
+                publishCandidate(measured);
         }
         else {
             stopObserving();
-            publish(ZERO);
+            publishCandidate(ZERO);
         }
     };
     apply();
@@ -114,16 +122,15 @@ export function createViewAnchor(target, opts) {
                 return;
             disposed = true;
             stopObserving();
+            targetRef = null;
+            publish = NOOP_PUBLISH;
+            lastPublished = null;
         },
     };
 }
 /**
- * Pure measure: read `target`'s rect and wrap it as an explicit visible
- * Placement. Always `{ visible:true }` — hiddenness is a caller decision
- * (see `createPlacementAnchor`), so this never returns `{ visible:false }`
- * and never infers visibility from a 0 size. A collapsed (0×0) but present
- * element therefore yields `{ visible:true, bounds:{...,width:0,height:0} }`,
- * distinct from any hidden Placement.
+ * Read target's current rect and return { visible: true, bounds }.
+ * Does not infer visibility from dimensions.
  */
 export function measurePlacement(target) {
     const r = target.getBoundingClientRect();
@@ -133,8 +140,6 @@ export function measurePlacement(target) {
     };
 }
 const samePlacement = (a, b) => {
-    // Discriminant-aware dedup: a visibility flip is always a change, even when
-    // the geometry would otherwise look identical.
     if (a.visible !== b.visible)
         return false;
     if (a.visible && b.visible) {
@@ -146,131 +151,136 @@ const samePlacement = (a, b) => {
     return true;
 };
 /**
- * The explicit-Placement mirror of `createViewAnchor`. Same observer/dedup/
- * teardown machinery, but the sink receives a `Placement`:
- *   - `visible === true`  → publish `measurePlacement(target)` and re-publish
- *     SYNCHRONOUSLY on every `ResizeObserver`/`resize` tick.
- *   - `visible === false` → publish `{ visible:false }` (NOT a ZERO bounds);
- *     do not observe.
- *
- * Dedup carries the discriminant (`samePlacement`), so a visibility flip is
- * never coalesced away.
- *
- * Opt-in `guardDisplayNone` (default false): when on, a measured zero-area
- * target (display:none / unmounted / unstable first layout) publishes
- * `{ visible:false }` instead of `{ visible:true, bounds:0×0 }`, and an
- * IntersectionObserver is attached so a display:none transition (which
- * ResizeObserver does not report) re-publishes.
+ * Explicit-visibility variant of createViewAnchor.
  */
 export function createPlacementAnchor(target, opts) {
     let visible = opts.visible;
     let publish = opts.publish;
-    const guardDisplayNone = opts.guardDisplayNone ?? false;
-    // Captured at creation; the follow options are never re-set via update().
-    const followScroll = opts.followScroll ?? false;
-    const followGeometry = opts.followGeometry ?? false;
+    let guardDisplayNone = opts.guardDisplayNone ?? false;
+    let followScroll = opts.followScroll ?? false;
+    let followGeometry = opts.followGeometry ?? false;
+    // Local, clearable alias for the `target` parameter so dispose() can drop
+    // the strong reference without widening the public parameter's type.
+    let targetRef = target;
     let observer = null;
     let io = null;
+    let scrollListening = false;
+    let geometryListening = false;
+    const capture = { capture: true };
+    const passiveCapture = { capture: true, passive: true };
     let lastPublished = null;
+    let publicationRevision = 0;
     let disposed = false;
-    // ── Windowed RAF geometry sentinel state ──────────────────
-    // The sentinel is a windowed poll, opened on demand and auto-closing once
-    // the geometry goes steady. It publishes IN-FRAME (no nested defer): each
-    // frame measures, and either publishes a changed rect synchronously or
-    // counts toward the steady-close threshold. While closed `rafId` is null
-    // and no frame is scheduled — zero static cost when idle.
+    // --- Windowed RAF geometry sentinel state ---
+    // The sentinel polls per frame during active movement and auto-closes once
+    // geometry settles. While closed, no frame is scheduled (zero idle overhead).
     let rafId = null;
     let steadyFrames = 0;
     const STEADY_CLOSE_FRAMES = 2;
-    // Bounds hidden polls the sentinel FOLLOWS so a no-deadline window can't spin.
     const MAX_HIDDEN_FOLLOW_FRAMES = 30;
-    // True while a [role="separator"] splitter drag is in progress: set on the
-    // capture-phase pointerdown that opened the window, cleared on pointerup.
-    // A held pointer means the drag may still resume after a static pause, so a
-    // steady run while held must NOT close the sentinel — it only closes once the
-    // pointer is released. Without this gate a press that pauses a couple of
-    // frames before the drag actually moves would close mid-press and drop the
-    // entire subsequent drag.
+    const MAX_INVALID_FOLLOW_FRAMES = 30;
+    let invalidFrames = 0;
+    // True while a [role="separator"] splitter drag is held.
     let pointerHeld = false;
-    // Absolute time (performance.now()) past which a `pulse(durationMs)` window
-    // force-closes even if the geometry is still changing — the upper bound that
-    // prevents a perpetually-animating target from keeping the sentinel resident.
-    // null = no time bound (scroll/splitter opens rely on steady-close instead).
+    let activePointerId = null;
     let sentinelDeadline = null;
-    // Measure the target, applying the opt-in first-frame / display:none guard:
-    // a zero-area box (no geometry to anchor) becomes a detach instead of a
-    // 0×0-visible Placement. Default off → byte-for-byte the plain measure.
     const computePlacement = () => {
-        const p = measurePlacement(target);
-        if (guardDisplayNone &&
-            p.visible &&
-            (p.bounds.width === 0 || p.bounds.height === 0)) {
+        const p = measurePlacement(targetRef);
+        if (p.visible &&
+            (!Number.isFinite(p.bounds.x) ||
+                !Number.isFinite(p.bounds.y) ||
+                !Number.isFinite(p.bounds.width) ||
+                !Number.isFinite(p.bounds.height)))
+            return null;
+        if (guardDisplayNone && p.visible && (p.bounds.width === 0 || p.bounds.height === 0)) {
             return { visible: false };
         }
         return p;
     };
+    const publishCandidate = (candidate) => {
+        const previous = lastPublished;
+        const attempt = ++publicationRevision;
+        lastPublished = candidate;
+        try {
+            const accepted = publish(candidate) !== false;
+            // A reentrant dispose() during publish() already cleared lastPublished;
+            // do not resurrect the pre-dispose value over that terminal state.
+            if (!accepted && publicationRevision === attempt && !disposed)
+                lastPublished = previous;
+            return accepted;
+        }
+        catch (error) {
+            if (publicationRevision === attempt && !disposed)
+                lastPublished = previous;
+            throw error;
+        }
+    };
     const emit = () => {
         if (disposed || !visible)
             return;
         const p = computePlacement();
+        if (!p)
+            return;
         if (lastPublished && samePlacement(lastPublished, p))
             return;
-        lastPublished = p;
-        publish(p);
+        publishCandidate(p);
     };
-    // Hidden sentinel poll → close (true) once RO/IO recorded the real hide or the
-    // bounded follow run elapsed, else keep following (false); never publishes.
     const shouldCloseOnHiddenPoll = () => {
         if (lastPublished?.visible === false)
             return true;
         return steadyFrames++ >= MAX_HIDDEN_FOLLOW_FRAMES;
     };
-    // One sentinel frame: measure, publish-in-frame if changed, else count toward
-    // the steady-close threshold. Reads `disposed`/`visible` live so a frame
-    // outliving teardown is inert.
     const sentinelFrame = () => {
         rafId = null;
         if (disposed || !visible) {
             sentinelDeadline = null;
             return;
         }
-        // Upper bound: a pulse window past its deadline closes regardless of
-        // motion, so a target that changes every frame can't keep the sentinel alive.
         if (sentinelDeadline !== null && performance.now() >= sentinelDeadline) {
             sentinelDeadline = null;
-            return; // duration elapsed → close (no re-arm)
+            return;
         }
         const p = computePlacement();
-        // The sentinel FOLLOWS visible geometry and NEVER publishes a detach — a
-        // hidden poll is a relayout transient to follow until restore (the fix).
+        if (!p) {
+            if (invalidFrames++ >= MAX_INVALID_FOLLOW_FRAMES) {
+                sentinelDeadline = null;
+                return;
+            }
+            if (!disposed && visible && followGeometry) {
+                rafId = requestAnimationFrame(sentinelFrame);
+            }
+            else {
+                sentinelDeadline = null;
+            }
+            return;
+        }
+        invalidFrames = 0;
         if (!p.visible) {
             if (shouldCloseOnHiddenPoll()) {
                 sentinelDeadline = null;
                 return;
             }
-            rafId = requestAnimationFrame(sentinelFrame);
+            if (!disposed && visible && followGeometry) {
+                rafId = requestAnimationFrame(sentinelFrame);
+            }
+            else {
+                sentinelDeadline = null;
+            }
             return;
         }
         if (lastPublished && samePlacement(lastPublished, p)) {
             steadyFrames++;
-            // Steady-close only fires once the pointer is RELEASED: while a
-            // splitter drag is held, a static pause is a hesitation, not the end of
-            // the drag, so we keep polling (re-arm below) and let `steadyFrames`
-            // accrue — it converges to a close within N frames after pointerup.
             if (steadyFrames >= STEADY_CLOSE_FRAMES && !pointerHeld) {
                 sentinelDeadline = null;
-                return; // steady (and released) → close
+                return;
             }
         }
         else {
-            lastPublished = p;
-            publish(p); // publish synchronously in THIS frame
+            publishCandidate(p);
             steadyFrames = 0;
         }
-        // `publish` may have synchronously disposed (or hidden) the anchor; re-read
-        // live state so a re-entrant teardown leaves ZERO scheduled frames.
-        if (!disposed && visible) {
-            rafId = requestAnimationFrame(sentinelFrame); // keep polling
+        if (!disposed && visible && followGeometry) {
+            rafId = requestAnimationFrame(sentinelFrame);
         }
         else {
             sentinelDeadline = null;
@@ -280,8 +290,10 @@ export function createPlacementAnchor(target, opts) {
         if (!followGeometry || disposed)
             return;
         steadyFrames = 0;
-        if (rafId === null)
+        if (rafId === null) {
+            invalidFrames = 0;
             rafId = requestAnimationFrame(sentinelFrame);
+        }
     };
     const closeSentinel = () => {
         if (rafId !== null) {
@@ -289,94 +301,125 @@ export function createPlacementAnchor(target, opts) {
             rafId = null;
         }
         steadyFrames = 0;
+        invalidFrames = 0;
         sentinelDeadline = null;
         pointerHeld = false;
+        activePointerId = null;
     };
-    // An ancestor scroll moved the target's screen rect. With the sentinel on,
-    // open the window so the whole scroll burst is followed frame-by-frame;
-    // without it, a single synchronous emit() follows the new rect.
     const onScroll = () => {
         if (followGeometry)
             openSentinel();
         else
             emit();
     };
-    // A capture-phase pointerdown on a [role="separator"] splitter handle marks
-    // the start of a drag that moves the target via ancestor reflow (no RO tick)
-    // → open the sentinel.
     const onPointerDown = (e) => {
         const t = e.target;
         if (t && t.closest && t.closest('[role="separator"]')) {
+            if (!pointerHeld)
+                activePointerId = e.pointerId;
             pointerHeld = true;
             openSentinel();
         }
     };
-    // Pointer released: the drag is over, so a steady run may now close the
-    // sentinel. Re-open it (a no-op if already polling) so the steady-close
-    // threshold is reached even if the geometry was already static at release.
-    const onPointerUp = () => {
+    const releasePointer = (e) => {
         if (!pointerHeld)
             return;
+        if (e && activePointerId !== e.pointerId)
+            return;
         pointerHeld = false;
+        activePointerId = null;
         openSentinel();
     };
+    const onPointerUp = (e) => {
+        releasePointer(e);
+    };
+    const onPointerCancel = (e) => {
+        releasePointer(e);
+    };
+    const onWindowBlur = () => {
+        releasePointer();
+    };
+    const startOptionalObserving = () => {
+        if (guardDisplayNone && !io && typeof IntersectionObserver !== 'undefined') {
+            io = new IntersectionObserver(emit);
+            io.observe(targetRef);
+        }
+        if (followScroll && !scrollListening) {
+            window.addEventListener('scroll', onScroll, passiveCapture);
+            scrollListening = true;
+        }
+        if (followGeometry && !geometryListening) {
+            window.addEventListener('pointerdown', onPointerDown, capture);
+            window.addEventListener('pointerup', onPointerUp, capture);
+            window.addEventListener('pointercancel', onPointerCancel, capture);
+            window.addEventListener('blur', onWindowBlur);
+            geometryListening = true;
+        }
+    };
+    const stopOptionalObserving = () => {
+        if (io && !guardDisplayNone) {
+            io.disconnect();
+            io = null;
+        }
+        if (scrollListening && !followScroll) {
+            window.removeEventListener('scroll', onScroll, passiveCapture);
+            scrollListening = false;
+        }
+        if (geometryListening && !followGeometry) {
+            window.removeEventListener('pointerdown', onPointerDown, capture);
+            window.removeEventListener('pointerup', onPointerUp, capture);
+            window.removeEventListener('pointercancel', onPointerCancel, capture);
+            window.removeEventListener('blur', onWindowBlur);
+            geometryListening = false;
+            closeSentinel();
+        }
+    };
+    const stopAllOptionalObserving = () => {
+        if (io) {
+            io.disconnect();
+            io = null;
+        }
+        if (scrollListening) {
+            window.removeEventListener('scroll', onScroll, passiveCapture);
+            scrollListening = false;
+        }
+        if (geometryListening) {
+            window.removeEventListener('pointerdown', onPointerDown, capture);
+            window.removeEventListener('pointerup', onPointerUp, capture);
+            window.removeEventListener('pointercancel', onPointerCancel, capture);
+            window.removeEventListener('blur', onWindowBlur);
+            geometryListening = false;
+        }
+        closeSentinel();
+    };
     const startObserving = () => {
         if (observer)
             return;
         observer = new ResizeObserver(emit);
-        observer.observe(target);
+        observer.observe(targetRef);
         window.addEventListener('resize', emit);
-        // A display:none transition is invisible to ResizeObserver; an
-        // IntersectionObserver re-fires `emit`, which re-measures via
-        // `computePlacement` (now-zero box → detach, restored box → visible).
-        if (guardDisplayNone && typeof IntersectionObserver !== 'undefined') {
-            io = new IntersectionObserver(emit);
-            io.observe(target);
-        }
-        if (followScroll) {
-            window.addEventListener('scroll', onScroll, {
-                capture: true,
-                passive: true,
-            });
-        }
-        if (followGeometry) {
-            window.addEventListener('pointerdown', onPointerDown, { capture: true });
-            window.addEventListener('pointerup', onPointerUp, { capture: true });
-        }
+        startOptionalObserving();
     };
     const stopObserving = () => {
         if (observer) {
             observer.disconnect();
             observer = null;
         }
-        if (io) {
-            io.disconnect();
-            io = null;
-        }
         window.removeEventListener('resize', emit);
-        window.removeEventListener('scroll', onScroll, {
-            capture: true,
-        });
-        window.removeEventListener('pointerdown', onPointerDown, {
-            capture: true,
-        });
-        window.removeEventListener('pointerup', onPointerUp, {
-            capture: true,
-        });
-        closeSentinel();
+        stopAllOptionalObserving();
     };
     const apply = () => {
         lastPublished = null;
         if (visible) {
             startObserving();
-            lastPublished = computePlacement();
-            publish(lastPublished);
+            const placement = computePlacement();
+            if (placement)
+                publishCandidate(placement);
         }
         else {
             stopObserving();
             const hidden = { visible: false };
-            lastPublished = hidden;
-            publish(hidden);
+            publishCandidate(hidden);
         }
     };
     apply();
@@ -386,6 +429,15 @@ export function createPlacementAnchor(target, opts) {
                 return;
             publish = next.publish;
             visible = next.visible;
+            // Omitting a flag preserves its current value so callers that only
+            // pass { visible, publish } don't inadvertently disable enabled flags.
+            guardDisplayNone = next.guardDisplayNone ?? guardDisplayNone;
+            followScroll = next.followScroll ?? followScroll;
+            followGeometry = next.followGeometry ?? followGeometry;
+            if (visible && observer) {
+                stopOptionalObserving();
+                startOptionalObserving();
+            }
             apply();
         },
         dispose() {
@@ -393,18 +445,15 @@ export function createPlacementAnchor(target, opts) {
                 return;
             disposed = true;
             stopObserving();
+            targetRef = null;
+            publish = NOOP_PUBLISH;
+            lastPublished = null;
         },
         pulse(durationMs) {
-            // Imperative window open: start the animation-follow window. It
-            // closes on steady (N=2 unchanged frames) OR, when `durationMs` is given,
-            // at that deadline — whichever comes first. The deadline is the upper bound
-            // that guarantees a still-animating target cannot keep the sentinel
-            // resident; without it, only steady-close applies.
             if (disposed || !followGeometry)
                 return;
             if (durationMs !== undefined && durationMs > 0) {
                 const next = performance.now() + durationMs;
-                // Extend (never shorten) an existing window's deadline.
                 sentinelDeadline = sentinelDeadline === null ? next : Math.max(sentinelDeadline, next);
             }
             openSentinel();