view-anchor 0.2.2 → 1.0.0-beta.0

package/dist/protocol-types.d.ts

@@ -1,11 +1,8 @@
-import type { AdvertisedSize, Placement } from './types.js';
+import type { SizeMeasurement, Placement } from './types.js';
 /**
- * Leaf module for the wire-format shapes shared by `protocol.ts` (decode/guard)
- * and `protocol-publisher.ts` (encode/batch). Keeping them here — rather than
- * in either of those two — avoids a value import cycle: `protocol.ts`
- * re-exports `protocol-publisher.ts`'s functions, and those functions need
- * `GEOMETRY_PROTOCOL_VERSION`, so neither of those two files can be the
- * source of it without the other importing back from it.
+ * Wire-format shapes shared by `protocol.ts` (decode/guard) and
+ * `protocol-publisher.ts` (encode/batch). Kept here to break a value
+ * import cycle between those two files.
  */
 /** Current wire format version for geometry messages. */
 export declare const GEOMETRY_PROTOCOL_VERSION: 1;
@@ -24,7 +21,7 @@ export interface SizeMessage extends GeometryAddress {
     v: typeof GEOMETRY_PROTOCOL_VERSION;
     kind: 'size';
     seq: number;
-    size: AdvertisedSize;
+    size: SizeMeasurement;
 }
 export type GeometryMessage = PlacementMessage | SizeMessage;
 export interface GeometryBatch {

package/dist/protocol-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-types.d.ts","sourceRoot":"","sources":["../src/protocol-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3D;;;;;;;GAOG;AAEH,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,EAAG,CAAU,CAAA;AAEnD,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,WAAW,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,cAAc,CAAA;CACrB;AAED,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,WAAW,CAAA;AAE5D,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CACrC;AAED,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,aAAa,CAAA"}
+{"version":3,"file":"protocol-types.d.ts","sourceRoot":"","sources":["../src/protocol-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE5D;;;;GAIG;AAEH,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,EAAG,CAAU,CAAA;AAEnD,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,WAAW,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,eAAe,CAAA;CACtB;AAED,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,WAAW,CAAA;AAE5D,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,OAAO,yBAAyB,CAAA;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CACrC;AAED,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,aAAa,CAAA"}

package/dist/protocol-types.js

@@ -1,10 +1,7 @@
 /**
- * Leaf module for the wire-format shapes shared by `protocol.ts` (decode/guard)
- * and `protocol-publisher.ts` (encode/batch). Keeping them here — rather than
- * in either of those two — avoids a value import cycle: `protocol.ts`
- * re-exports `protocol-publisher.ts`'s functions, and those functions need
- * `GEOMETRY_PROTOCOL_VERSION`, so neither of those two files can be the
- * source of it without the other importing back from it.
+ * Wire-format shapes shared by `protocol.ts` (decode/guard) and
+ * `protocol-publisher.ts` (encode/batch). Kept here to break a value
+ * import cycle between those two files.
  */
 /** Current wire format version for geometry messages. */
 export const GEOMETRY_PROTOCOL_VERSION = 1;

package/dist/protocol.d.ts

@@ -14,7 +14,7 @@ export interface GeometryDecodeOptions {
 }
 /**
  * Decodes untrusted transport data without throwing. `maxMessages` is required
- * so each receiver, rather than this library, chooses its own batch limit.
+ * so each receiver chooses its own batch limit.
  */
 export declare function decodeGeometryWireValue(value: unknown, options: GeometryDecodeOptions): GeometryDecodeResult;
 export interface GeometrySequenceGuard {
@@ -31,5 +31,5 @@ export interface GeometrySequenceGuard {
  */
 export declare function createGeometrySequenceGuard(): GeometrySequenceGuard;
 export { createGeometryBatcher, createPlacementMessagePublisher, createSizeMessagePublisher, } from './protocol-publisher.js';
-export type { GeometryBatcher, GeometryBatcherOptions, GeometryBatchSend, GeometrySend, } from './protocol-publisher.js';
+export type { GeometryBatcher, GeometryBatcherOptions, GeometryBatchSender, GeometryMessageSender, } from './protocol-publisher.js';
 //# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,yBAAyB,EAAE,CAAA;AACpC,YAAY,EACV,eAAe,EACf,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,GACZ,CAAA;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhC,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;CACpB;AA6DD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CA0BtB;AAED,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IACzC,kEAAkE;IAClE,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAKD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,qBAAqB,CA4BnE;AAED,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,GAC3B,MAAM,yBAAyB,CAAA;AAChC,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,YAAY,GACb,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,yBAAyB,EAAE,CAAA;AACpC,YAAY,EACV,eAAe,EACf,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,GACZ,CAAA;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhC,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;CACpB;AAmED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CA0BtB;AAED,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IACzC,kEAAkE;IAClE,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAKD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,qBAAqB,CA4BnE;AAED,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,GAC3B,MAAM,yBAAyB,CAAA;AAChC,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,yBAAyB,CAAA"}

package/dist/protocol.js

@@ -1,6 +1,14 @@
 import { GEOMETRY_PROTOCOL_VERSION, } from './protocol-types.js';
 export { GEOMETRY_PROTOCOL_VERSION };
-const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// Only plain objects count, as produced by JSON.parse or structured clone. A
+// custom prototype cannot supply missing fields; checking the prototype once
+// per object is much cheaper than an own-property check per field.
+const isRecord = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
 const isSafeInteger = (value) => typeof value === 'number' && Number.isSafeInteger(value);
 const isNonNegativeSafeInteger = (value) => isSafeInteger(value) && value >= 0;
 function error(message) {
@@ -57,7 +65,7 @@ function decodeMessage(value) {
 }
 /**
  * Decodes untrusted transport data without throwing. `maxMessages` is required
- * so each receiver, rather than this library, chooses its own batch limit.
+ * so each receiver chooses its own batch limit.
  */
 export function decodeGeometryWireValue(value, options) {
     try {

package/dist/react.d.ts

@@ -1,5 +1,4 @@
-import { type PlacementAnchorOptions } from './view-anchor.js';
-import type { Bounds, ViewAnchorOptions } from './types.js';
+import type { ViewAnchorOptions } from './view-anchor.js';
 export interface UseViewAnchorOptions extends ViewAnchorOptions {
     /**
      * Values that re-apply the anchor when changed. Keep this array's length
@@ -9,18 +8,6 @@ export interface UseViewAnchorOptions extends ViewAnchorOptions {
 }
 /** Compatible with React 18's null callback and React 19's ref cleanup. */
 export type ViewAnchorRef = (el: HTMLElement | null) => void | (() => void);
-export interface UsePlacementAnchorOptions extends PlacementAnchorOptions {
-    /**
-     * Values that re-apply the anchor when changed. Keep this array's length
-     * stable across renders.
-     */
-    deps?: ReadonlyArray<unknown>;
-}
-/** Callback ref for the explicit-visibility Placement API. */
-export type PlacementAnchorRef = ViewAnchorRef;
-/** Bind zero-bounds visibility to a DOM element callback ref. */
-export declare function useViewAnchor(options: UseViewAnchorOptions): ViewAnchorRef;
 /** Bind the explicit Placement API to a DOM element callback ref. */
-export declare function usePlacementAnchor(options: UsePlacementAnchorOptions): PlacementAnchorRef;
-export type { Bounds };
+export declare function useViewAnchor(options: UseViewAnchorOptions): ViewAnchorRef;
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,MAAM,EAAoB,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE7E,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAA;AAE3E,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,8DAA8D;AAC9D,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAA;AA+H9C,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAM1E;AAsBD,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAazF;AAED,YAAY,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzD,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAA;AA+J3E,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAe1E"}

package/dist/react.js

@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useRef } from 'react';
-import { createPlacementAnchor, createViewAnchor, } from './view-anchor.js';
+import { useCallback, useEffect, useInsertionEffect, useRef, version } from 'react';
+import { createViewAnchor } from './view-anchor.js';
 // Callback refs own the imperative anchor because React invokes them during commit.
 // React 19 may call the cleanup returned from a ref and immediately reattach the
 // same element in development mode. Collapse is deferred by one microtask so that
@@ -8,12 +8,16 @@ function useAnchorRef(options, applied, adapter) {
     const handleRef = useRef(null);
     const elementRef = useRef(null);
     const optionsRef = useRef(options);
-    optionsRef.current = options;
     const adapterRef = useRef(adapter);
-    adapterRef.current = adapter;
     const appliedRef = useRef(applied);
     const currentAppliedRef = useRef(applied);
-    currentAppliedRef.current = applied;
+    // Renders discarded before commit (e.g. suspended transitions) must not
+    // update optionsRef. Insertion effects run before callback refs in the same commit.
+    useInsertionEffect(() => {
+        optionsRef.current = options;
+        adapterRef.current = adapter;
+        currentAppliedRef.current = applied;
+    });
     // Options handed to the adapter on the last create/update call.
     // Tracks applied state across renders where the deps array reference changes.
     const lastAppliedOptionsRef = useRef(options);
@@ -26,7 +30,7 @@ function useAnchorRef(options, applied, adapter) {
         if (!handle)
             return;
         const adapter = adapterRef.current;
-        const alreadyCollapsed = adapter.isCollapsed(lastAppliedOptionsRef.current);
+        const alreadyCollapsed = adapter.isCollapsed(handle, lastAppliedOptionsRef.current);
         try {
             if (!alreadyCollapsed)
                 adapter.collapse(handle, optionsRef.current);
@@ -45,10 +49,13 @@ function useAnchorRef(options, applied, adapter) {
             collapseAndDispose();
         });
     };
+    // React 19 invokes the cleanup returned from a callback ref instead of calling
+    // ref(null). React 18 warns about the returned function and still calls ref(null).
+    const detachCleanup = (element) => Number.parseInt(version, 10) >= 19 ? () => deferDetach(element) : undefined;
     const ref = useCallback((element) => {
         if (element === elementRef.current) {
             cancelPendingDetach();
-            return element ? () => deferDetach(element) : undefined;
+            return element ? detachCleanup(element) : undefined;
         }
         cancelPendingDetach();
         const previous = elementRef.current;
@@ -67,7 +74,7 @@ function useAnchorRef(options, applied, adapter) {
             handleRef.current = adapterRef.current.create(element, optionsRef.current);
             appliedRef.current = currentAppliedRef.current;
             lastAppliedOptionsRef.current = optionsRef.current;
-            return () => deferDetach(element);
+            return detachCleanup(element);
         }
         return undefined;
     }, []);
@@ -95,49 +102,47 @@ function useAnchorRef(options, applied, adapter) {
     }, []);
     return ref;
 }
-const viewAdapter = {
-    create: createViewAnchor,
-    update(handle, options) {
-        handle.update(options);
+const hideStates = new WeakMap();
+const trackHide = (options, state) => ({
+    ...options,
+    publish(placement) {
+        if (placement.visible)
+            return options.publish(placement);
+        state.accepted = false;
+        const result = options.publish(placement);
+        state.accepted = result !== false;
+        return result;
     },
-    collapse(handle, options) {
-        handle.update({ present: false, publish: options.publish });
-    },
-    isCollapsed(options) {
-        return !options.present;
+});
+const viewAdapter = {
+    create(target, options) {
+        const state = { accepted: false };
+        const handle = createViewAnchor(target, trackHide(options, state));
+        hideStates.set(handle, state);
+        return handle;
     },
-};
-/** Bind zero-bounds visibility to a DOM element callback ref. */
-export function useViewAnchor(options) {
-    return useAnchorRef(options, [options.present, options.publish, ...(options.deps ?? [])], viewAdapter);
-}
-const placementAdapter = {
-    create: createPlacementAnchor,
     update(handle, options) {
-        // In React, an omitted option represents "off" for that render,
-        // rather than keeping the previous value.
-        handle.update({
-            ...options,
-            guardDisplayNone: options.guardDisplayNone ?? false,
-            followScroll: options.followScroll ?? false,
-            followGeometry: options.followGeometry ?? false,
-        });
+        // Options are forwarded as-is; the hook applies the same "omitted resets
+        // to default" rule as the core's update().
+        handle.update(trackHide(options, hideStates.get(handle)));
     },
     collapse(handle, options) {
-        handle.update({ ...options, visible: false });
+        handle.update(trackHide({ ...options, visible: false }, hideStates.get(handle)));
     },
-    isCollapsed(options) {
-        return !options.visible;
+    isCollapsed(handle, options) {
+        return !options.visible && hideStates.get(handle).accepted;
     },
 };
 /** Bind the explicit Placement API to a DOM element callback ref. */
-export function usePlacementAnchor(options) {
+export function useViewAnchor(options) {
     return useAnchorRef(options, [
         options.visible,
         options.publish,
-        options.guardDisplayNone,
+        options.treatZeroAreaAsHidden,
         options.followScroll,
         options.followGeometry,
+        options.holdSelector,
+        options.dedupe,
         ...(options.deps ?? []),
-    ], placementAdapter);
+    ], viewAdapter);
 }

package/dist/{size-advertiser.d.ts → size-anchor.d.ts}

@@ -1,16 +1,17 @@
-import type { SizeAdvertiserOptions, SizeAdvertiserHandle } from './types.js';
+import type { SizeAnchorOptions, SizeAnchorHandle } from './types.js';
 /**
  * Report content size for a single axis back to the host.
  *
  * Runs in a downstream document, reads the content size from
  * `ResizeObserverEntry.borderBoxSize` without triggering reflow, and
- * publishes updates through an animation frame loop (`createMeasureLoop`).
+ * publishes at most once per animation frame, skipping unchanged extents by
+ * default (see the `dedupe` option).
  *
  * Measurements are rounded to integer pixels and clamped to >= 0.
  *
- * Note: `target` should be a shrink-to-fit wrapper on the owned axis.
+ * `target` must be a shrink-to-fit wrapper on the owned axis.
  * If its size is driven by the host view itself (such as `<body>` or `<html>`),
  * updates will not shrink back to content size.
  */
-export declare function createSizeAdvertiser(target: HTMLElement, opts: SizeAdvertiserOptions): SizeAdvertiserHandle;
-//# sourceMappingURL=size-advertiser.d.ts.map
+export declare function createSizeAnchor(target: HTMLElement, opts: SizeAnchorOptions): SizeAnchorHandle;
+//# sourceMappingURL=size-anchor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"size-anchor.d.ts","sourceRoot":"","sources":["../src/size-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAOrE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CA6G/F"}

package/dist/size-anchor.js

@@ -0,0 +1,131 @@
+import { watchAbort } from './abort.js';
+// 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;
+/**
+ * Report content size for a single axis back to the host.
+ *
+ * Runs in a downstream document, reads the content size from
+ * `ResizeObserverEntry.borderBoxSize` without triggering reflow, and
+ * publishes at most once per animation frame, skipping unchanged extents by
+ * default (see the `dedupe` option).
+ *
+ * Measurements are rounded to integer pixels and clamped to >= 0.
+ *
+ * `target` must be a shrink-to-fit wrapper on the owned axis.
+ * If its size is driven by the host view itself (such as `<body>` or `<html>`),
+ * updates will not shrink back to content size.
+ */
+export function createSizeAnchor(target, opts) {
+    const axis = opts.axis;
+    let dedupe = opts.dedupe ?? true;
+    let publish = opts.publish;
+    let observer = null;
+    let rafId = null;
+    let disposed = false;
+    // Latest border-box recorded by the ResizeObserver callback.
+    let latestBoxSize = null;
+    // Last extent passed to publish; null until one is accepted.
+    let lastPublished = null;
+    let publicationRevision = 0;
+    const measure = () => {
+        if (!latestBoxSize)
+            return null;
+        const raw = axis === 'block' ? latestBoxSize.blockSize : latestBoxSize.inlineSize;
+        if (!Number.isFinite(raw))
+            return null;
+        return Math.max(0, Math.round(raw));
+    };
+    const publishExtent = (extent) => {
+        const previous = lastPublished;
+        const attempt = ++publicationRevision;
+        lastPublished = extent;
+        try {
+            const accepted = publish({ axis, extent }) !== false;
+            // A reentrant update() or dispose() during publish() already moved the
+            // baseline; do not roll back over that newer state.
+            if (!accepted && publicationRevision === attempt && !disposed)
+                lastPublished = previous;
+        }
+        catch (error) {
+            if (publicationRevision === attempt && !disposed)
+                lastPublished = previous;
+            throw error;
+        }
+    };
+    const publishFrame = () => {
+        rafId = null;
+        if (disposed)
+            return;
+        const extent = measure();
+        if (extent === null)
+            return;
+        if (dedupe && extent === lastPublished)
+            return;
+        publishExtent(extent);
+    };
+    const onResize = (entries) => {
+        // A callback queued before disconnect() can still fire once more; do not
+        // let it write `latestBoxSize` after dispose() has already cleared it.
+        if (disposed)
+            return;
+        const entry = entries[entries.length - 1];
+        if (entry) {
+            latestBoxSize = entry.borderBoxSize?.[0] ?? entry.contentBoxSize?.[0] ?? latestBoxSize;
+        }
+        if (rafId === null)
+            rafId = requestAnimationFrame(publishFrame);
+    };
+    // Warn if measuring body or documentElement, whose size matches the view.
+    const doc = target.ownerDocument;
+    if (target === doc.body || target === doc.documentElement) {
+        console.warn(`[view-anchor] size-anchor: <${target === doc.body ? 'body' : 'html'}>'s ` +
+            `${axis} size is the view size, not content size. The size anchor will ` +
+            `never shrink to content; measure a shrink-to-fit wrapper instead.`);
+    }
+    let removeAbortListener = () => { };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        removeAbortListener();
+        removeAbortListener = () => { };
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+        if (observer) {
+            observer.disconnect();
+            observer = null;
+        }
+        publish = NOOP_PUBLISH;
+        latestBoxSize = null;
+        lastPublished = null;
+    };
+    if (opts.signal?.aborted)
+        dispose();
+    else {
+        removeAbortListener = watchAbort(opts.signal, dispose);
+        observer = new ResizeObserver(onResize);
+        observer.observe(target);
+    }
+    return {
+        update(next) {
+            if (disposed)
+                return;
+            publish = next.publish;
+            dedupe = next.dedupe ?? true;
+            // The new callback has not accepted anything yet, so an extent the old
+            // callback rejected (or never saw) must not stay latched as the dedupe
+            // baseline — otherwise a later identical tick would be silently
+            // deduped against a value this callback was never actually given.
+            lastPublished = null;
+            // Re-publish the current size to the new sink immediately so it is not
+            // empty until the next ResizeObserver tick.
+            const extent = measure();
+            if (extent !== null)
+                publishExtent(extent);
+        },
+        dispose,
+    };
+}

package/dist/types.d.ts

@@ -27,44 +27,38 @@ export type Placement = {
 } | {
     visible: false;
 };
-export interface ViewAnchorOptions {
+/** Which axis this size anchor reports: 'block' (height) or 'inline' (width). */
+export type SizeAxis = 'block' | 'inline';
+/** One measured size on the owned axis. */
+export interface SizeMeasurement {
+    /** The axis this size anchor reports ('block' or 'inline'). */
+    readonly axis: SizeAxis;
     /**
-     * Whether the native view should be attached. When false, publishes
-     * zero bounds ({ x: 0, y: 0, width: 0, height: 0 }) so the host can detach
-     * the view while keeping its instance alive.
+     * The target's border-box size on this axis in CSS pixels, rounded and
+     * non-negative. Falls back to the content box where no border box is reported.
      */
-    present: boolean;
-    /** Receives the live rect, or zero bounds when detached. */
-    publish: Publisher<Bounds>;
-    /** Stops this anchor when aborted. An already-aborted signal starts no work. */
-    signal?: AbortSignal;
-}
-export interface ViewAnchorHandle {
-    /** Apply new options and re-publish immediately. */
-    update(opts: ViewAnchorOptions): void;
-    /** Stop observing and clean up listeners. After disposal no further values are published. */
-    dispose(): void;
-}
-/** Which axis this advertiser reports: 'block' (height) or 'inline' (width). */
-export type AdvertisedAxis = 'block' | 'inline';
-/** One frame of advertised size on the owned axis. */
-export interface AdvertisedSize {
-    /** The axis this advertiser reports ('block' or 'inline'). */
-    readonly axis: AdvertisedAxis;
-    /** The content extent in CSS pixels, rounded and non-negative. */
     readonly extent: number;
 }
-export interface SizeAdvertiserOptions {
-    /** The single axis this advertiser owns. Fixed for the advertiser's lifetime. */
-    axis: AdvertisedAxis;
-    /** Receives each advertised size. */
-    publish: Publisher<AdvertisedSize>;
-    /** Stops this advertiser when aborted. An already-aborted signal starts no work. */
+export interface SizeAnchorOptions {
+    /** The single axis this size anchor owns. Fixed for its lifetime. */
+    axis: SizeAxis;
+    /** Receives each measured size. */
+    publish: Publisher<SizeMeasurement>;
+    /** Stops this size anchor when aborted. An already-aborted signal starts no work. */
     signal?: AbortSignal;
+    /**
+     * When true (the default), a measurement identical to the last published
+     * extent is not published again. When false, every measurement publishes,
+     * even an unchanged extent. Omitting it in update() resets to true.
+     */
+    dedupe?: boolean;
 }
-export interface SizeAdvertiserHandle {
-    /** Swap the publish callback and re-advertise the current size immediately. */
-    update(publish: Publisher<AdvertisedSize>): void;
+export interface SizeAnchorHandle {
+    /**
+     * Apply a full set of options and re-publish the current size
+     * immediately. Like creation, an omitted dedupe resets to true.
+     */
+    update(opts: Omit<SizeAnchorOptions, 'signal' | 'axis'>): void;
     /** Stop observing and cancel any pending animation frame. */
     dispose(): void;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,CAAA;AAE1C;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,aAAa,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAE9E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,4DAA4D;IAC5D,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;IAC1B,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACrC,6FAA6F;IAC7F,OAAO,IAAI,IAAI,CAAA;CAChB;AAOD,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE/C,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,IAAI,EAAE,cAAc,CAAA;IACpB,qCAAqC;IACrC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,CAAA;IAClC,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,IAAI,CAAA;IAChD,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAA;CAChB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,CAAA;AAE1C;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,aAAa,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAO9E,iFAAiF;AACjF,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEzC,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,IAAI,EAAE,QAAQ,CAAA;IACd,mCAAmC;IACnC,OAAO,EAAE,SAAS,CAAC,eAAe,CAAC,CAAA;IACnC,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,IAAI,CAAA;IAC9D,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAA;CAChB"}

package/dist/view-anchor.d.ts

@@ -1,62 +1,75 @@
-import type { Placement, Publisher, ViewAnchorOptions, ViewAnchorHandle } from './types.js';
-/**
- * Bind a native view or external surface to the geometry of `target`.
- *
- * - `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 publishing: measurement and publishing occur directly in the
- * observer tick. Applying geometry outside the DOM may already be delayed;
- * adding requestAnimationFrame would add another 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 {
+import type { Placement, Publisher } from './types.js';
+export declare const DEFAULT_HOLD_SELECTOR = "[role=\"separator\"]";
+export interface ViewAnchorOptions {
     /**
      * Whether the native view should be visible. When true, publishes
-     * { visible: true, bounds }; when false, publishes { visible: false }.
+     * { visible: true, bounds }; when false, publishes { visible: false } and
+     * stops observing, so a rejected hidden placement is only sent again by the
+     * next update().
      */
     visible: boolean;
     /** Receives each explicit Placement. */
     publish: Publisher<Placement>;
-    /** Stops this anchor when aborted. An already-aborted signal starts no work. */
+    /**
+     * Stops this anchor when aborted. An already-aborted signal starts no work.
+     * Read once at creation only — update()'s type does not accept this field.
+     */
     signal?: AbortSignal;
     /**
      * 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.
+     * update() applies the same default: omitting it resets to false.
      */
-    guardDisplayNone?: boolean;
+    treatZeroAreaAsHidden?: boolean;
     /**
      * 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.
+     * update() applies the same default: omitting it resets to false.
      */
     followScroll?: boolean;
     /**
      * 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.
+     * splitter dragging, or pulse()) and auto-closes when steady.
+     * update() applies the same default: omitting it resets to false.
      */
     followGeometry?: boolean;
+    /**
+     * CSS selector for the press-and-hold target that keeps followGeometry open
+     * for the duration of a pointer press. Only meaningful when followGeometry
+     * is true; the pointer listeners are mounted only while both are set. A capture-phase pointerdown whose
+     * target matches `closest(holdSelector)` opens frame following until release.
+     * Default is `[role="separator"]`. Pass null to disable. update() applies
+     * the same default when omitted. An invalid selector throws synchronously
+     * (SyntaxError) before any option is applied.
+     */
+    holdSelector?: string | null;
+    /**
+     * When true (the default), a measurement identical to the last accepted
+     * Placement is not published again. When false, every usable frame publishes
+     * even if the Placement is unchanged; the steady-frame close and the
+     * invalid/hidden frame caps still compare values either way. Hidden frames
+     * are never published by frame following regardless of this option. Omitting
+     * it in update() resets to true.
+     */
+    dedupe?: boolean;
 }
-export interface PlacementAnchorHandle {
+export interface ViewAnchorHandle {
     /**
-     * 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.
+     * Apply a full set of options and re-publish immediately. Omitted options
+     * reset to defaults: treatZeroAreaAsHidden/followScroll/followGeometry → false,
+     * holdSelector → `[role="separator"]` (pass null to disable), dedupe → true.
+     * `signal` is not accepted here — it cannot be changed after creation.
      */
-    update(opts: PlacementAnchorOptions): void;
+    update(opts: Omit<ViewAnchorOptions, 'signal'>): void;
     /** Stop observing; never publish again. */
     dispose(): void;
     /**
-     * Open the animation frame sentinel window. Auto-closes once stable
+     * Open a frame-following window. Auto-closes once stable
      * or after durationMs. No-op if followGeometry is false.
+     * durationMs is an upper bound, not a minimum: the window closes as soon as
+     * two frames measure the same rect, so a transition that starts slowly
+     * (sub-pixel movement in its first frames) may not be followed to the end.
      */
     pulse(durationMs?: number): void;
 }
@@ -66,7 +79,13 @@ export interface PlacementAnchorHandle {
  */
 export declare function measurePlacement(target: HTMLElement): Placement;
 /**
- * Explicit-visibility variant of createViewAnchor.
+ * Bind a native view or external surface to the geometry of `target`.
+ *
+ * When `visible === true`, publishes { visible: true, bounds } immediately,
+ * then re-measures synchronously on ResizeObserver and window resize.
+ * When `visible === false`, publishes { visible: false } and stops observing.
+ * Publishes are deduplicated against the last accepted Placement by default
+ * (see the `dedupe` option).
  */
-export declare function createPlacementAnchor(target: HTMLElement, opts: PlacementAnchorOptions): PlacementAnchorHandle;
+export declare function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions): ViewAnchorHandle;
 //# 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,EAAU,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAmBnG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAgH/F;AAID,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;IAC7B,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;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,CA6TvB"}
+{"version":3,"file":"view-anchor.d.ts","sourceRoot":"","sources":["../src/view-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAQ9D,eAAO,MAAM,qBAAqB,yBAAuB,CAAA;AAWzD,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAA;IACrD,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf;;;;;;OAMG;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;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CA+V/F"}