view-anchor 0.1.2 → 0.2.0

package/dist/view-anchor.d.ts

@@ -1,111 +1,70 @@
-import type { Placement, ViewAnchorOptions, ViewAnchorHandle } from './types.js';
+import type { Placement, Publisher, ViewAnchorOptions, ViewAnchorHandle } from './types.js';
 /**
- * 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 declare function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions): ViewAnchorHandle;
 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 declare function measurePlacement(target: HTMLElement): Placement;
 /**
- * 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 declare function createPlacementAnchor(target: HTMLElement, opts: PlacementAnchorOptions): PlacementAnchorHandle;
 //# sourceMappingURL=view-anchor.d.ts.map

package/dist/view-anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-anchor.d.ts","sourceRoot":"","sources":["../src/view-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAwBnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,iBAAiB,GACtB,gBAAgB,CA6ElB;AASD,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,OAAO,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAA;IACvC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,MAAM,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAA;IAC1C,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAM/D;AAiBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,sBAAsB,GAC3B,qBAAqB,CAuPvB"}
+{"version":3,"file":"view-anchor.d.ts","sourceRoot":"","sources":["../src/view-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAmBnB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,iBAAiB,GACtB,gBAAgB,CA6FlB;AAID,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAA;IAC1C,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAM/D;AAeD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,sBAAsB,GAC3B,qBAAqB,CA2SvB"}