view-anchor 0.1.2 → 0.2.1

package/src/view-anchor.ts

@@ -1,26 +1,15 @@
-import type {
-  Bounds,
-  Placement,
-  ViewAnchorOptions,
-  ViewAnchorHandle,
-} from './types.js'
+import type { Bounds, Placement, Publisher, ViewAnchorOptions, ViewAnchorHandle } from './types.js'
 
 const ZERO: Bounds = { 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: number
-  y: number
-  width: number
-  height: number
-}): Bounds => ({
+// 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 => 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: number; y: number; width: number; height: number }): Bounds => ({
   x: Math.round(r.x),
   y: Math.round(r.y),
   width: Math.max(0, Math.round(r.width)),
@@ -28,72 +17,79 @@ const clampRect = (r: {
 })
 
 /**
- * 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.
+ * Bind a native view or external surface to the geometry of `target`.
  *
- * 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.
+ * - `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.
  *
- * 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: HTMLElement,
-  opts: ViewAnchorOptions,
-): ViewAnchorHandle {
+export function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions): ViewAnchorHandle {
   let present = opts.present
   let publish = opts.publish
   let observer: ResizeObserver | null = 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: HTMLElement | null = 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: Bounds | null = null
+  let publicationRevision = 0
   let disposed = false
 
-  const measure = (): Bounds => {
-    const r = target.getBoundingClientRect()
+  const measure = (): Bounds | null => {
+    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: Bounds, b: Bounds): boolean =>
     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: Bounds): boolean => {
+    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 = (): void => {
     if (disposed || !present) return
     const m = measure()
+    if (!m) return
     if (lastPublished && sameRect(lastPublished, m)) return
-    lastPublished = m
-    publish(m)
+    publishCandidate(m)
   }
 
   const startObserving = (): void => {
     if (observer) return
     observer = new ResizeObserver(emit)
-    observer.observe(target)
+    observer.observe(targetRef!)
     window.addEventListener('resize', emit)
   }
 
@@ -105,19 +101,17 @@ export function createViewAnchor(
     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 = (): void => {
     lastPublished = null
     if (present) {
       startObserving()
-      lastPublished = measure()
-      publish(lastPublished)
+      const measured = measure()
+      if (measured) publishCandidate(measured)
     } else {
       stopObserving()
-      publish(ZERO)
+      publishCandidate(ZERO)
     }
   }
 
@@ -134,78 +128,63 @@ export function createViewAnchor(
       if (disposed) return
       disposed = true
       stopObserving()
+      targetRef = null
+      publish = NOOP_PUBLISH
+      lastPublished = null
     },
   }
 }
 
-// ── Explicit Placement API ────────────────────────────────────────────
-//
-// The modern surface that replaces the magic-`{0,0,0,0}` "hidden" value.
-// Visibility is an explicit discriminant, NEVER inferred from geometry — a
-// real 0×0-but-on-screen view is `{ visible:true, bounds:{...,width:0} }`
-// and a hidden one is `{ visible:false }` (no `bounds`). See `Placement`.
+// --- Explicit Placement API ---
 
 export interface PlacementAnchorOptions {
   /**
-   * Caller's INTENT: should the native view be on-screen? `true` →
-   * publish the measured rect as `{ visible:true, bounds }`; `false` →
-   * publish `{ visible:false }`. Crucially, hiddenness comes from this
-   * flag, not from a measured zero size — so a legitimately 0-sized but
-   * visible target still publishes `visible:true`.
+   * Whether the native view should be visible. When true, publishes
+   * { visible: true, bounds }; when false, publishes { visible: false }.
    */
   visible: boolean
-  /** Receives each explicit Placement. Owns IPC → host. */
-  publish: (placement: Placement) => void
+  /** Receives each explicit Placement. */
+  publish: Publisher<Placement>
   /**
-   * Opt-in geometry detach. When true, a measured zero-area target (no
-   * geometry box — display:none / unmounted / unstable first layout) publishes
-   * `{ visible:false }` (detach-but-keep) instead of `{ visible:true,
-   * bounds:0×0 }`, and an IntersectionObserver is attached so a display:none
-   * transition (which ResizeObserver does not report) re-publishes. Default
-   * false keeps the legitimate 0×0-visible semantics.
+   * When true, targets with zero area (such as display: none or unmounted elements)
+   * publish { visible: false } instead of { visible: true, bounds: 0x0 }, and an
+   * IntersectionObserver tracks display: none transitions. Default is false.
+   * Sticky across update(): omitting it preserves the current setting.
    */
   guardDisplayNone?: boolean
   /**
-   * Opt-in capture-phase ancestor-scroll follow. When true, the anchor
-   * listens for `scroll` on `window` in the CAPTURE phase (scroll events don't
-   * bubble, but reach `window` while capturing), so an ancestor scroll
-   * container scrolling the target re-measures and re-publishes. With
-   * `followGeometry` off, the scroll callback does a single synchronous
-   * `emit()`; with it on, the scroll OPENS the RAF sentinel window so the
-   * follow tracks every frame of a scroll burst. Default false.
+   * When true, listens for capture-phase scroll events on window to re-measure
+   * when an ancestor container scrolls. Default is false.
+   * Sticky across update(): omitting it preserves the current setting.
    */
   followScroll?: boolean
   /**
-   * Opt-in windowed RAF geometry sentinel. Catches ancestor
-   * transform / reflow moves that no DOM event reports. The sentinel is
-   * NON-resident: it is OPENED on demand (a scroll burst, a `[role="separator"]`
-   * splitter pointerdown, or an explicit `pulse()`), polls geometry once per
-   * animation frame publishing IN-FRAME, and AUTO-CLOSES once the rect goes
-   * steady (a few unchanged frames). While closed it schedules no frame, so the
-   * static cost when idle is exactly zero. Default false.
+   * When true, polls geometry per animation frame during active motion (scrolls,
+   * splitter dragging, or pulse()) and auto-closes when steady. Zero idle overhead.
+   * Sticky across update(): omitting it preserves the current setting.
    */
   followGeometry?: boolean
 }
 
 export interface PlacementAnchorHandle {
-  /** Apply new options; re-publishes immediately (mirrors `createViewAnchor`). */
+  /**
+   * Apply new options and re-publish immediately.
+   * guardDisplayNone, followScroll, and followGeometry are sticky: omitting a flag
+   * preserves its current value. Pass an explicit false to disable one.
+   */
   update(opts: PlacementAnchorOptions): void
   /** Stop observing; never publish again. */
   dispose(): void
   /**
-   * Open the RAF sentinel window (animation follow); auto-closes after going
-   * steady or after `durationMs`. No-op when `followGeometry` is false.
+   * Open the animation frame sentinel window. Auto-closes once stable
+   * or after durationMs. No-op if followGeometry is false.
    */
   pulse(durationMs?: number): void
 }
 
 /**
- * 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: HTMLElement): Placement {
   const r = target.getBoundingClientRect()
@@ -216,8 +195,6 @@ export function measurePlacement(target: HTMLElement): Placement {
 }
 
 const samePlacement = (a: Placement, b: Placement): boolean => {
-  // 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 (
@@ -231,21 +208,7 @@ const samePlacement = (a: Placement, b: Placement): boolean => {
 }
 
 /**
- * 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: HTMLElement,
@@ -253,112 +216,129 @@ export function createPlacementAnchor(
 ): PlacementAnchorHandle {
   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: HTMLElement | null = target
   let observer: ResizeObserver | null = null
   let io: IntersectionObserver | null = null
+  let scrollListening = false
+  let geometryListening = false
+  const capture = { capture: true }
+  const passiveCapture = { capture: true, passive: true }
   let lastPublished: Placement | null = 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: number | null = 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: number | undefined | null = null
   let sentinelDeadline: number | null = 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 = (): Placement => {
-    const p = measurePlacement(target)
+  const computePlacement = (): Placement | null => {
+    const p = measurePlacement(targetRef!)
     if (
-      guardDisplayNone &&
       p.visible &&
-      (p.bounds.width === 0 || p.bounds.height === 0)
-    ) {
+      (!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: Placement): boolean => {
+    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 = (): void => {
     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 = (): boolean => {
     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 = (): void => {
     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 (shouldCloseOnHiddenPoll()) {
+        sentinelDeadline = null
+        return
+      }
+      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
     }
@@ -367,7 +347,10 @@ export function createPlacementAnchor(
   const openSentinel = (): void => {
     if (!followGeometry || disposed) return
     steadyFrames = 0
-    if (rafId === null) rafId = requestAnimationFrame(sentinelFrame)
+    if (rafId === null) {
+      invalidFrames = 0
+      rafId = requestAnimationFrame(sentinelFrame)
+    }
   }
 
   const closeSentinel = (): void => {
@@ -376,95 +359,129 @@ export function createPlacementAnchor(
       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 = (): void => {
     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: Event): void => {
     const t = e.target as Element | null
     if (t && t.closest && t.closest('[role="separator"]')) {
+      if (!pointerHeld) activePointerId = (e as PointerEvent).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 = (): void => {
+  const releasePointer = (e?: Event): void => {
     if (!pointerHeld) return
+    if (e && activePointerId !== (e as PointerEvent).pointerId) return
     pointerHeld = false
+    activePointerId = null
     openSentinel()
   }
 
-  const startObserving = (): void => {
-    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') {
+  const onPointerUp = (e: Event): void => {
+    releasePointer(e)
+  }
+
+  const onPointerCancel = (e: Event): void => {
+    releasePointer(e)
+  }
+
+  const onWindowBlur = (): void => {
+    releasePointer()
+  }
+
+  const startOptionalObserving = (): void => {
+    if (guardDisplayNone && !io && typeof IntersectionObserver !== 'undefined') {
       io = new IntersectionObserver(emit)
-      io.observe(target)
+      io.observe(targetRef!)
     }
-    if (followScroll) {
-      window.addEventListener('scroll', onScroll, {
-        capture: true,
-        passive: true,
-      })
+    if (followScroll && !scrollListening) {
+      window.addEventListener('scroll', onScroll, passiveCapture)
+      scrollListening = true
     }
-    if (followGeometry) {
-      window.addEventListener('pointerdown', onPointerDown, { capture: true })
-      window.addEventListener('pointerup', onPointerUp, { capture: 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 stopObserving = (): void => {
-    if (observer) {
-      observer.disconnect()
-      observer = null
+  const stopOptionalObserving = (): void => {
+    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 = (): void => {
     if (io) {
       io.disconnect()
       io = null
     }
-    window.removeEventListener('resize', emit)
-    window.removeEventListener('scroll', onScroll, {
-      capture: true,
-    } as EventListenerOptions)
-    window.removeEventListener('pointerdown', onPointerDown, {
-      capture: true,
-    } as EventListenerOptions)
-    window.removeEventListener('pointerup', onPointerUp, {
-      capture: true,
-    } as EventListenerOptions)
+    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 = (): void => {
+    if (observer) return
+    observer = new ResizeObserver(emit)
+    observer.observe(targetRef!)
+    window.addEventListener('resize', emit)
+    startOptionalObserving()
+  }
+
+  const stopObserving = (): void => {
+    if (observer) {
+      observer.disconnect()
+      observer = null
+    }
+    window.removeEventListener('resize', emit)
+    stopAllOptionalObserving()
+  }
+
   const apply = (): void => {
     lastPublished = null
     if (visible) {
       startObserving()
-      lastPublished = computePlacement()
-      publish(lastPublished)
+      const placement = computePlacement()
+      if (placement) publishCandidate(placement)
     } else {
       stopObserving()
       const hidden: Placement = { visible: false }
-      lastPublished = hidden
-      publish(hidden)
+      publishCandidate(hidden)
     }
   }
 
@@ -475,23 +492,29 @@ export function createPlacementAnchor(
       if (disposed) 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(): void {
       if (disposed) return
       disposed = true
       stopObserving()
+      targetRef = null
+      publish = NOOP_PUBLISH
+      lastPublished = null
     },
     pulse(durationMs?: number): void {
-      // 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()