view-anchor 0.1.1

package/dist/view-anchor.js

@@ -0,0 +1,413 @@
+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.)
+const clampRect = (r) => ({
+    x: Math.round(r.x),
+    y: Math.round(r.y),
+    width: Math.max(0, Math.round(r.width)),
+    height: Math.max(0, Math.round(r.height)),
+});
+/**
+ * Create an anchor binding ONE native view's bounds to `target`'s geometry.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
+    let lastPublished = null;
+    let disposed = false;
+    const measure = () => {
+        const r = target.getBoundingClientRect();
+        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 emit = () => {
+        if (disposed || !present)
+            return;
+        const m = measure();
+        if (lastPublished && sameRect(lastPublished, m))
+            return;
+        lastPublished = m;
+        publish(m);
+    };
+    const startObserving = () => {
+        if (observer)
+            return;
+        observer = new ResizeObserver(emit);
+        observer.observe(target);
+        window.addEventListener('resize', emit);
+    };
+    const stopObserving = () => {
+        if (observer) {
+            observer.disconnect();
+            observer = null;
+        }
+        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.
+    const apply = () => {
+        lastPublished = null;
+        if (present) {
+            startObserving();
+            lastPublished = measure();
+            publish(lastPublished);
+        }
+        else {
+            stopObserving();
+            publish(ZERO);
+        }
+    };
+    apply();
+    return {
+        update(next) {
+            if (disposed)
+                return;
+            publish = next.publish;
+            present = next.present;
+            apply();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stopObserving();
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function measurePlacement(target) {
+    const r = target.getBoundingClientRect();
+    return {
+        visible: true,
+        bounds: clampRect({ x: r.left, y: r.top, width: r.width, height: r.height }),
+    };
+}
+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) {
+        return (a.bounds.x === b.bounds.x &&
+            a.bounds.y === b.bounds.y &&
+            a.bounds.width === b.bounds.width &&
+            a.bounds.height === b.bounds.height);
+    }
+    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.
+ */
+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 observer = null;
+    let io = null;
+    let lastPublished = null;
+    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.
+    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.
+    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 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)) {
+            return { visible: false };
+        }
+        return p;
+    };
+    const emit = () => {
+        if (disposed || !visible)
+            return;
+        const p = computePlacement();
+        if (lastPublished && samePlacement(lastPublished, p))
+            return;
+        lastPublished = p;
+        publish(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)
+        }
+        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.visible) {
+            if (shouldCloseOnHiddenPoll()) {
+                sentinelDeadline = null;
+                return;
+            }
+            rafId = requestAnimationFrame(sentinelFrame);
+            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
+            }
+        }
+        else {
+            lastPublished = p;
+            publish(p); // publish synchronously in THIS frame
+            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
+        }
+        else {
+            sentinelDeadline = null;
+        }
+    };
+    const openSentinel = () => {
+        if (!followGeometry || disposed)
+            return;
+        steadyFrames = 0;
+        if (rafId === null)
+            rafId = requestAnimationFrame(sentinelFrame);
+    };
+    const closeSentinel = () => {
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+        steadyFrames = 0;
+        sentinelDeadline = null;
+        pointerHeld = false;
+    };
+    // 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"]')) {
+            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 = () => {
+        if (!pointerHeld)
+            return;
+        pointerHeld = false;
+        openSentinel();
+    };
+    const startObserving = () => {
+        if (observer)
+            return;
+        observer = new ResizeObserver(emit);
+        observer.observe(target);
+        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 });
+        }
+    };
+    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();
+    };
+    const apply = () => {
+        lastPublished = null;
+        if (visible) {
+            startObserving();
+            lastPublished = computePlacement();
+            publish(lastPublished);
+        }
+        else {
+            stopObserving();
+            const hidden = { visible: false };
+            lastPublished = hidden;
+            publish(hidden);
+        }
+    };
+    apply();
+    return {
+        update(next) {
+            if (disposed)
+                return;
+            publish = next.publish;
+            visible = next.visible;
+            apply();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stopObserving();
+        },
+        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();
+        },
+    };
+}