view-anchor 0.2.2 → 1.0.0-beta.1

package/README.md

@@ -7,43 +7,41 @@
 [![npm version](https://img.shields.io/npm/v/view-anchor)](https://www.npmjs.com/package/view-anchor)
 [![npm downloads](https://img.shields.io/npm/dm/view-anchor)](https://www.npmjs.com/package/view-anchor)
 [![License](https://img.shields.io/npm/l/view-anchor)](./LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
 
 [English](./README.md) · [简体中文](./README.zh-CN.md)
 
-> 🎮 **Live demo**: the [3D interactive demo](https://lbb00.github.io/view-anchor/) runs the real core in your browser. Drag the splitter, toggle the panel, and watch the native view follow.
+> 🎮 **Live demo**: [3D interactive demo](https://lbb00.github.io/view-anchor/) runs the real core in your browser. Drag the splitters, scroll the page, and click its buttons directly in the tilted scene: surface A follows its placeholder, and surface B reports its content height back so the page resizes its placeholder.
 
 ## The problem
 
-Some surfaces are positioned by application code rather than by CSS. They may be a canvas, a video overlay, an embedded document, or any other thing you can position from a rectangle. Your layout moves DOM elements, but it cannot move that external surface by itself.
+Some surfaces are positioned by application code rather than by CSS — a canvas, a video overlay, an embedded document, or anything you can position from a rectangle. DOM layout moves placeholder elements, but cannot move those external surfaces.
 
-Point `view-anchor` at a placeholder element. It measures the element on creation, on `ResizeObserver` notifications, and on window `resize`, then calls your `publish` function. Your function applies, stores, or sends that value using the mechanism your application already has.
+Point `view-anchor` at a placeholder element. It measures it on creation, on `ResizeObserver` notifications, and on window `resize`, then calls your `publish` function. Your function applies, stores, or sends that value however your application already does.
 
-The core has no dependency on a host runtime, React, or a layout library. It only uses `ResizeObserver`, `requestAnimationFrame`, and `getBoundingClientRect`. React support lives in a separate `view-anchor/react` entry.
+The core has no dependency on a host runtime, React, or a layout library, and uses only `ResizeObserver`, `requestAnimationFrame`, and `getBoundingClientRect`. React support lives in a separate `view-anchor/react` entry.
 
 ## What `publish` receives
 
-`publish` is not a built-in transport. It is a synchronous function that the library calls with one of these plain values:
+`publish` is a synchronous function that the library calls with one of these plain values:
 
-- `createViewAnchor` calls `publish(bounds)`, where `bounds` is `{ x, y, width, height }` in CSS pixels from `getBoundingClientRect()`. When `present` becomes `false`, it calls `publish({ x: 0, y: 0, width: 0, height: 0 })` once and stops observing.
-- `createPlacementAnchor` calls `publish({ visible: true, bounds })` while shown, or `publish({ visible: false })` while hidden. Use it when a visible zero-sized element differs from a hidden one.
-- `createSizeAdvertiser` calls `publish({ axis, extent })`, where `axis` is `block` (height) or `inline` (width), and `extent` is the rounded non-negative content size in CSS pixels.
+- `createViewAnchor` calls `publish({ visible: true, bounds })` while shown, where `bounds` is `{ x, y, width, height }` in CSS pixels from `getBoundingClientRect()`, or `publish({ visible: false })` while hidden. The explicit `visible` flag distinguishes a visible-but-zero-sized element from one that is hidden or unmounted.
+- `createSizeAnchor` calls `publish({ axis, extent })`, where `axis` is `block` (height) or `inline` (width), and `extent` is the target's rounded, non-negative border-box size on that axis in CSS pixels (padding and border included; content-box only where the browser does not report a border box).
 
-Return `false` only when the value was not accepted; a later measurement may retry it. Return `true` or nothing after accepting or queueing it.
+Return `false` only when the value was not accepted; a later measurement may retry it. Return `true` or nothing after accepting or queueing it. A hidden anchor measures nothing, so a rejected `{ visible: false }` is not retried on its own: call `update()` again to resend it. `useViewAnchor` does this for you on unmount.
 
-## Built for the hot path
+## Performance
 
-Geometry updates fire on every resize and, when following a drag, on every animation frame. The library keeps that work predictable:
+Geometry updates fire on every resize and, when following a drag, on every animation frame.
 
 - **Synchronous delivery.** Measurement and publish happen inside the same `ResizeObserver` callback. No timers, no extra frame of lag.
-- **Dedupe outgoing updates.** A rectangle identical to the last accepted one is not passed to `publish` again.
-- **Frame following only when needed.** `followGeometry` polls `requestAnimationFrame` during a scroll burst, a splitter drag, or an explicit `pulse()`, then closes itself once the rectangle settles. Idle cost is zero, and hidden or invalid targets are capped at 30 frames.
+- **Dedupe by default.** A `Placement` identical to the last accepted one is not passed to `publish` again; set `dedupe: false` to receive every measurement.
+- **Frame following on demand.** `followGeometry` polls `requestAnimationFrame` during a scroll burst, a splitter drag, or an explicit `pulse()`, then stops once the rectangle settles. Idle cost is zero; hidden or invalid targets are capped at 30 frames.
 - **O(1) generation changes.** In the protocol layer, moving an anchor to a new generation or clearing it does not touch other anchors.
-- **Latest-wins batching.** Messages queued in the same task are merged in a microtask. The newest placement and size for each anchor are sent separately.
+- **Latest-wins batching.** Messages queued in the same task are merged in a microtask; the newest placement and size for each anchor are sent separately.
 - **Release on disposal.** Disposed handles stop observing and release their target and callback references, even when the caller keeps the handle.
-- **Compact, tree-shakeable core.** Functions are separate exports with `sideEffects: false`; the complete core export is under 3 KB gzipped.
+- **Tree-shakeable core.** Functions are separate exports with `sideEffects: false`; the complete core export is under 3 KB gzipped.
 
-The [performance report](./docs/performance-report.md) contains the reproducible measurements and their environment. They are useful for comparing changes on the same machine, not for predicting browser layout, serialization, delivery, or your app's workload.
+See the [performance report](./docs/performance-report.md) for a comparison with 0.2.2 and export sizes.
 
 ## Installation
 
@@ -53,7 +51,7 @@ pnpm add view-anchor
 npm install view-anchor
 ```
 
-React is an optional peer dependency. Import the hooks from `view-anchor/react`. The root entry also re-exports `useViewAnchor` for compatibility with `v0.1.2`, so any app that imports `view-anchor` needs React installed. `view-anchor/protocol` does not.
+React is an optional peer dependency, needed only if you import from `view-anchor/react`. The root entry (`view-anchor`) and `view-anchor/protocol` have no React dependency and load without it installed.
 
 ## Usage
 
@@ -62,28 +60,33 @@ React is an optional peer dependency. Import the hooks from `view-anchor/react`.
 ```ts
 import { createViewAnchor } from 'view-anchor'
 
-const publish = (bounds) => {
-  applyBounds(bounds)
+const publish = (placement) => {
+  if (placement.visible) applyBounds(placement.bounds)
+  else hideSurface()
 }
 
 const handle = createViewAnchor(target, {
-  present: true,
+  visible: true,
   publish,
+  followScroll: true, // re-measure when any ancestor scrolls
+  followGeometry: true, // poll animation frames during scrolls / drags, stop when steady
+  treatZeroAreaAsHidden: true, // zero-area or display:none target → { visible: false }
+  holdSelector: '[role="separator"]', // default; pointerdown on a match keeps followGeometry open while held, null disables
+  dedupe: true, // default; set false to receive every measurement, even unchanged ones
 })
 
-handle.update({ present: true, publish }) // apply new options and publish right away
+handle.update({ visible: true, publish }) // apply new options and publish right away
+handle.pulse() // re-measure after a move no observer sees (e.g. a class toggle moved the target without resizing it); closes once steady
 handle.dispose() // stop observing; never publishes again
 ```
 
-Set `present: false` to collapse the surface. The core publishes a zero rectangle and stops observing. Your `publish` function decides whether that removes, hides, or retains the external surface.
+Set `visible: false` to collapse the surface. The core publishes `{ visible: false }` and stops observing. Your `publish` function decides whether that removes, hides, or retains the external surface.
 
-For ancestor scroll, transforms, or other position-only changes, use `createPlacementAnchor` with `followScroll` or `followGeometry` as needed.
-
-`createViewAnchor`, `createPlacementAnchor`, `createSizeAdvertiser`, and `createGeometryBatcher` accept `signal`. Aborting it is equivalent to `dispose()`; an already-aborted signal does not measure, publish, or install listeners.
+`createViewAnchor`, `createSizeAnchor`, and `createGeometryBatcher` accept `signal`. Aborting it is equivalent to `dispose()`; an already-aborted signal does not measure, publish, or install listeners.
 
 ```ts
 const controller = new AbortController()
-const handle = createViewAnchor(target, { present: true, publish, signal: controller.signal })
+const handle = createViewAnchor(target, { visible: true, publish, signal: controller.signal })
 
 controller.abort() // same cleanup as handle.dispose()
 ```
@@ -95,62 +98,44 @@ import { useViewAnchor } from 'view-anchor/react'
 
 function DebugPanel({ visible }: { visible: boolean }) {
   const ref = useViewAnchor({
-    present: visible,
-    publish: publishPanelBounds,
+    visible,
+    publish: publishPanelPlacement,
+    followScroll: true,
+    followGeometry: true,
   })
   // The external surface follows this placeholder. Hiding or unmounting it
-  // sends the collapsed value, without deciding how the surface is stored.
+  // sends { visible: false }, without deciding how the surface is stored.
   return <div ref={ref} className="h-full w-full" />
 }
 ```
 
-The hook survives React 18 and 19 StrictMode double-mounting without publishing stale frames.
-
-### Explicit visibility
-
-A zero rectangle cannot tell a hidden view from one that is visible but currently 0×0. When that distinction matters, use the `Placement` API. It publishes `{ visible: true, bounds }` or `{ visible: false }` and adds opt-in scroll and geometry following:
-
-```ts
-import { createPlacementAnchor } from 'view-anchor'
-
-const handle = createPlacementAnchor(target, {
-  visible: true,
-  publish(placement) {
-    applyPlacement(placement)
-  },
-  followScroll: true, // re-measure when any ancestor scrolls
-  followGeometry: true, // poll animation frames during scrolls / drags, stop when steady
-  guardDisplayNone: true, // zero-area or display:none target → { visible: false }
-})
-
-handle.pulse() // open a short frame-following window, e.g. during a CSS transition
-```
-
-The React version is `usePlacementAnchor` from `view-anchor/react`.
+The hook survives React 18 and 19 StrictMode double-mounting without publishing stale frames. It re-applies options on every update with the same reset semantics as `createViewAnchor` and `update()`: an omitted option resets to its default, not the previous value. An omitted `treatZeroAreaAsHidden`, `followScroll`, or `followGeometry` counts as `false`; an omitted `holdSelector` resets to `[role="separator"]`; an omitted `dedupe` resets to `true`. Pass `null` / `false` to turn `holdSelector` / `dedupe` off.
 
 ### Let content drive the size
 
-Sometimes the hosted surface's size should come from its own content, for example a toolbar rendered by downstream code. Run `createSizeAdvertiser` inside the hosted document. It reports the content size back so a DOM placeholder in the host can grow to match:
+Sometimes the hosted surface's size should come from its own content, for example a toolbar rendered by downstream code. Run `createSizeAnchor` inside the hosted document. It reports the content size back so a DOM placeholder in the host can grow to match:
 
 ```ts
-import { createSizeAdvertiser } from 'view-anchor'
+import { createSizeAnchor } from 'view-anchor'
+
+const publish = (size) => {
+  updatePlaceholderSize(size)
+}
 
-const handle = createSizeAdvertiser(contentWrapper, {
-  axis: 'block', // one axis per advertiser: block = height, inline = width
-  publish(size) {
-    updatePlaceholderSize(size)
-  },
+const handle = createSizeAnchor(contentWrapper, {
+  axis: 'block', // one axis per size anchor: block = height, inline = width
+  publish,
 })
 
-handle.update(publish) // swap the publish channel and report the current size again
+handle.update({ publish }) // apply new options and report the current size again; an omitted dedupe resets to true
 handle.dispose() // stop observing; never reports again
 ```
 
-> **Warning:** the target must shrink to fit its content on the owned axis. If the host sets that size instead, the two sides keep reacting to each other and never settle. See [docs/bidirectional-design.md](./docs/bidirectional-design.md).
+> The target must shrink to fit its content on the owned axis. If the host sets that size instead, the two sides keep reacting to each other and never settle. See [docs/bidirectional-design.md](./docs/bidirectional-design.md).
 
 ### Versioned transport across a boundary
 
-The core hands you plain `Bounds`, `Placement`, and `AdvertisedSize` values. If an application passes them through an asynchronous or untrusted channel, it usually needs validation and ordering. The optional `view-anchor/protocol` entry adds versioned message envelopes, bounded decoding, a per-anchor sequence guard that drops stale messages, and a microtask batcher:
+The core hands you plain `Bounds`, `Placement`, and `SizeMeasurement` values. If an application passes them through an asynchronous or untrusted channel, it usually needs validation and ordering. The optional `view-anchor/protocol` entry adds versioned message envelopes, bounded decoding, a per-anchor sequence guard that drops stale messages, and a microtask batcher:
 
 ```ts
 import {
@@ -173,45 +158,44 @@ if (decoded.ok) {
 }
 ```
 
-Two rules keep the ordering correct:
-
 - **Keep one publisher per `{ anchorId, generation }`.** The batcher and `createGeometrySequenceGuard` remember the highest sequence number for each message kind per anchor. A publisher rebuilt for the same address restarts at sequence 1 and its messages are dropped as stale. In React, hold it in `useMemo` or `useRef`. Bump `generation` when you really want a fresh start.
-- **A synchronous publisher returns `false` to say "not accepted".** The core then retries the same geometry on the next trigger. A batching publisher returns `true` once queued and owns any later retries.
+- **A synchronous publisher returns `false` to say "not accepted".** The core then retries the same geometry on the next trigger (a rejected `{ visible: false }` waits for the next `update()`). A batching publisher returns `true` once queued and owns any later retries.
 
 The full contract is in [docs/protocol.md](./docs/protocol.md).
 
 ## API
 
-| Export                                                                      | Kind              | Purpose                                                                                                                       |
-| --------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `createViewAnchor(target, opts)`                                            | function          | Measure a DOM element and call `publish({ x, y, width, height })`. A zero rect means collapsed.                               |
-| `createPlacementAnchor(target, opts)`                                       | function          | Same core with explicit `Placement` visibility, opt-in `followScroll` / `followGeometry` / `guardDisplayNone`, and `pulse()`. |
-| `measurePlacement(target)`                                                  | function          | Pure measurement: wraps the target rect as `{ visible: true, bounds }`.                                                       |
-| `createSizeAdvertiser(target, opts)`                                        | function          | Call `publish({ axis, extent })` with one content-size axis.                                                                  |
-| `useViewAnchor(opts)` from `view-anchor/react`                              | hook              | Returns a ref callback for a placeholder element.                                                                             |
-| `usePlacementAnchor(opts)` from `view-anchor/react`                         | hook              | React adapter for the `Placement` API, including `followScroll` and `followGeometry`.                                         |
-| `Bounds`                                                                    | type              | `{ x, y, width, height }` in CSS pixels.                                                                                      |
-| `Placement`                                                                 | type              | `{ visible: true; bounds } \| { visible: false }`.                                                                            |
-| `ViewAnchorOptions` / `ViewAnchorHandle`                                    | type              | Options and handle for `createViewAnchor`.                                                                                    |
-| `PlacementAnchorOptions` / `PlacementAnchorHandle`                          | type              | Options and handle for `createPlacementAnchor`.                                                                               |
-| `UseViewAnchorOptions` / `ViewAnchorRef` from `view-anchor/react`           | type              | Options and ref shape for `useViewAnchor`.                                                                                    |
-| `UsePlacementAnchorOptions` / `PlacementAnchorRef` from `view-anchor/react` | type              | Options and ref shape for `usePlacementAnchor`.                                                                               |
-| `AdvertisedAxis` / `AdvertisedSize`                                         | type              | Axis and payload types for the reverse direction.                                                                             |
-| `SizeAdvertiserOptions` / `SizeAdvertiserHandle`                            | type              | Options and handle for `createSizeAdvertiser`.                                                                                |
-| `view-anchor/protocol`                                                      | functions + types | Versioned messages, strict decoding, sequence guards, message publishers, and microtask batching.                             |
+| Export                                                            | Kind              | Purpose                                                                                                                                    |
+| ----------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createViewAnchor(target, opts)`                                  | function          | Publish a `Placement`, with opt-in `followScroll` / `followGeometry` / `treatZeroAreaAsHidden` / `holdSelector` / `dedupe`, and `pulse()`. |
+| `measurePlacement(target)`                                        | function          | Pure measurement: wraps the target rect as `{ visible: true, bounds }`.                                                                    |
+| `createSizeAnchor(target, opts)`                                  | function          | Call `publish({ axis, extent })` with one content-size axis.                                                                               |
+| `useViewAnchor(opts)` from `view-anchor/react`                    | hook              | React adapter for `createViewAnchor`, returning a ref callback for a placeholder element.                                                  |
+| `Bounds`                                                          | type              | `{ x, y, width, height }` in CSS pixels.                                                                                                   |
+| `Placement`                                                       | type              | `{ visible: true; bounds } \| { visible: false }`.                                                                                         |
+| `Publisher<T>` / `PublishResult`                                  | type              | Signature of the `publish` callback and its return value (`void \| boolean`).                                                              |
+| `ViewAnchorOptions` / `ViewAnchorHandle`                          | type              | Options and handle for `createViewAnchor`.                                                                                                 |
+| `UseViewAnchorOptions` / `ViewAnchorRef` from `view-anchor/react` | type              | Options and ref shape for `useViewAnchor`.                                                                                                 |
+| `SizeAxis` / `SizeMeasurement`                                    | type              | Axis and payload types for the reverse direction.                                                                                          |
+| `SizeAnchorOptions` / `SizeAnchorHandle`                          | type              | Options and handle for `createSizeAnchor`.                                                                                                 |
+| `view-anchor/protocol`                                            | functions + types | Versioned messages, strict decoding, sequence guards, message publishers, and microtask batching.                                          |
+
+## Versioning
+
+Within 1.x, `view-anchor` does not remove or rename any public export from `.`, `view-anchor/react`, or `view-anchor/protocol`, and does not change the default behavior for input that is already valid. Minor releases add functionality; patch releases fix bugs. An interface slated for removal is deprecated first and only removed in 2.0.
 
 ## Documentation
 
-- [docs/mechanism.md](./docs/mechanism.md): how the forward direction works. Synchronous publishing, stale-frame safety, the `present` / zero-rect / unmount contract, StrictMode behaviour. Includes the interactive 3D demo at [docs/index.html](./docs/index.html).
+- [docs/mechanism.md](./docs/mechanism.md): how the forward direction works. Synchronous publishing, default dedup and `dedupe: false`, the `Placement` / visibility / unmount contract, StrictMode behaviour. Includes the interactive 3D demo at [docs/index.html](./docs/index.html).
 - [docs/bidirectional-design.md](./docs/bidirectional-design.md): running both directions at once. Why the forward path is synchronous while the reverse path uses animation frames, single-axis ownership, and where the trust boundary sits.
 - [docs/protocol.md](./docs/protocol.md): message envelopes, validation, ordering, batching, and what happens on failure.
-- [docs/performance-report.md](./docs/performance-report.md): reproducible CPU, heap, RSS, extreme-case, V8, and export-size measurements.
+- [docs/performance-report.md](./docs/performance-report.md): performance summary and export sizes.
 
 ## Contributing
 
-Issues and pull requests are welcome. Before submitting, run `pnpm lint`, `pnpm format:check`, `pnpm check-types`, `pnpm test`, and `pnpm build`. `pnpm benchmark` prints the data used to update the performance report.
+Before submitting, run `pnpm lint`, `pnpm format:check`, `pnpm check-types`, `pnpm test`, and `pnpm build`. `pnpm benchmark` prints the data used to update the performance report.
 
-Changes that affect a published version must include a Changeset. Run `pnpm changeset`, select the version bump, and describe the user-visible change. Merging it into `main` opens a version PR; merging that PR publishes the package.
+Changes that affect a published version must include a Changeset. Run `pnpm changeset`, select the version bump, and describe the user-visible change. Merging into `main` opens a version PR; merging that PR publishes the package.
 
 ## License
 

package/README.zh-CN.md

@@ -7,27 +7,25 @@
 [![npm version](https://img.shields.io/npm/v/view-anchor)](https://www.npmjs.com/package/view-anchor)
 [![npm downloads](https://img.shields.io/npm/dm/view-anchor)](https://www.npmjs.com/package/view-anchor)
 [![License](https://img.shields.io/npm/l/view-anchor)](./LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
 
 [English](./README.md) · [简体中文](./README.zh-CN.md)
 
-> [在线演示](https://lbb00.github.io/view-anchor/)：拖动分栏、切换面板或 3D 视角，查看外部画面如何跟随占位元素。
+> [在线演示](https://lbb00.github.io/view-anchor/)：直接在倾斜的 3D 场景里拖动分隔条、滚动页面、点击按钮。画面 A 跟随占位元素；画面 B 把自己的内容高度报回页面，页面据此调整它的占位。
 
 ## 它解决什么问题
 
-有些画面的位置不是由 CSS 直接控制：例如应用自己摆放的叠层、嵌入式文档，或能根据矩形定位的渲染表面。DOM 布局会移动占位元素，却不会自动更新这些画面的位置。
+有些画面的位置由应用自己摆放（叠层、嵌入式文档或能根据矩形定位的渲染表面）。DOM 布局会移动占位元素，但不会自动更新这些画面的位置。
 
-`view-anchor` 负责测量占位元素。元素尺寸变化或窗口大小变化时，它同步调用你提供的 `publish` 函数。函数怎么使用这个值由应用决定。
+`view-anchor` 负责测量占位元素，在尺寸变化或窗口大小变化时同步调用你提供的 `publish` 函数。函数如何使用这个值由应用决定。
 
 ## `publish` 收到什么
 
-`publish` 不是内置传输通道，而是一个同步回调。不同接口会传入不同的普通对象：
+`publish` 是一个同步回调，不同接口会传入不同的普通对象：
 
-- `createViewAnchor` 调用 `publish(bounds)`。`bounds` 是相对视口、取整后的 CSS 像素矩形：`{ x, y, width, height }`。`present` 变为 `false` 时，会发布一次全零矩形，然后停止观察。
-- `createPlacementAnchor` 在显示时调用 `publish({ visible: true, bounds })`，隐藏时调用 `publish({ visible: false })`。
-- `createSizeAdvertiser` 调用 `publish({ axis, extent })`。`axis` 为 `block`（高度）或 `inline`（宽度），`extent` 是取整后且不小于零的内容尺寸。
+- `createViewAnchor` 在显示时调用 `publish({ visible: true, bounds })`（`bounds` 是相对视口、取整后的 CSS 像素矩形 `{ x, y, width, height }`），隐藏时调用 `publish({ visible: false })`。显式的 `visible` 用于区分“可见但恰好是 0×0”和“已隐藏或未挂载”。
+- `createSizeAnchor` 调用 `publish({ axis, extent })`。`axis` 为 `block`（高度）或 `inline`（宽度），`extent` 是目标元素在该轴上的 border-box 尺寸（包含 padding 和 border；浏览器不提供 border-box 时退回 content-box），单位 CSS 像素，取整且不小于零。
 
-数据已接收或已经入队时，返回 `true` 或不返回值；当前不能接收时才返回 `false`。下一次测量会重试被拒绝的值。
+数据已接收或已经入队时，返回 `true` 或不返回值；当前不能接收时才返回 `false`，下一次测量会重试被拒绝的值。隐藏状态下不再测量，所以被拒绝的 `{ visible: false }` 不会自动重发，需要再调用一次 `update()`；`useViewAnchor` 会在卸载时替你补发。
 
 ## 安装
 
@@ -37,7 +35,7 @@ pnpm add view-anchor
 npm install view-anchor
 ```
 
-React 是可选 peer dependency。Hook 从 `view-anchor/react` 导入；根入口为了兼容 `v0.1.2` 也会导出 `useViewAnchor`，因此导入根入口时需要安装 React。`view-anchor/protocol` 不需要 React。
+React 是可选 peer dependency，只有从 `view-anchor/react` 导入时才需要。根入口（`view-anchor`）和 `view-anchor/protocol` 不依赖 React，未安装 React 也能加载。
 
 ## 使用
 
@@ -46,29 +44,34 @@ React 是可选 peer dependency。Hook 从 `view-anchor/react` 导入；根入
 ```ts
 import { createViewAnchor } from 'view-anchor'
 
-const publish = (bounds) => {
-  applyBoundsToExternalSurface(bounds)
+const publish = (placement) => {
+  if (placement.visible) applyBoundsToExternalSurface(placement.bounds)
+  else hideExternalSurface()
 }
 
 const handle = createViewAnchor(placeholderEl, {
-  present: true,
+  visible: true,
   publish,
+  followScroll: true, // 祖先容器滚动时重新测量
+  followGeometry: true, // 拖拽或滚动期间逐帧测量；稳定后停止
+  treatZeroAreaAsHidden: true, // 零面积或 display:none 时发布 { visible: false }
+  holdSelector: '[role="separator"]', // 默认值；命中该选择器的 pointerdown 按住期间保持 followGeometry 开启，传 null 关闭
+  dedupe: true, // 默认值；传 false 让每次测量都发布，即使值没变
 })
 
-handle.update({ present: true, publish }) // 更新选项并立即重新发布
+handle.update({ visible: true, publish }) // 更新选项并立即重新发布
+handle.pulse() // 位置变了但没有任何观察器能感知时（如一次类名切换让目标移动了但尺寸没变）主动重测；稳定后自动停止
 handle.dispose() // 停止观察；之后不会再发布
 ```
 
-默认的 `createViewAnchor` 监听 `ResizeObserver` 和窗口 `resize`。如果祖先滚动、transform 或拖拽会移动元素而不改变它自身尺寸，请使用下面的 `createPlacementAnchor`，按需开启 `followScroll` 或 `followGeometry`。
+把 `visible` 设为 `false` 会发布 `{ visible: false }` 并停止观察。你的 `publish` 函数可以把它解释为隐藏、移除，或保留外部画面。
 
-把 `present` 设为 `false` 会发布全零矩形并停止观察。你的 `publish` 函数可以把它解释为隐藏、移除，或保留外部画面。
-
-`createViewAnchor`、`createPlacementAnchor`、`createSizeAdvertiser` 和 `createGeometryBatcher` 都支持 `signal`。调用 `AbortController.abort()` 的清理效果等同于 `dispose()`；创建前已经 abort 的 signal 不会开始测量或安装监听。
+`createViewAnchor`、`createSizeAnchor` 和 `createGeometryBatcher` 都支持 `signal`。调用 `AbortController.abort()` 的清理效果等同于 `dispose()`；创建前已经 abort 的 signal 不会开始测量或安装监听。
 
 ```ts
 const controller = new AbortController()
 const handle = createViewAnchor(placeholderEl, {
-  present: true,
+  visible: true,
   publish,
   signal: controller.signal,
 })
@@ -83,49 +86,35 @@ import { useViewAnchor } from 'view-anchor/react'
 
 function ExternalSurfaceContainer({ visible }: { visible: boolean }) {
   const ref = useViewAnchor({
-    present: visible,
-    publish: applyBoundsToExternalSurface,
+    visible,
+    publish: applyPlacementToExternalSurface,
+    followScroll: true,
+    followGeometry: true,
   })
 
   return <div ref={ref} className="h-full w-full" />
 }
 ```
 
-元素卸载时，Hook 会先发布收起值，再释放监听。它兼容 React 18 和 19 的 StrictMode 重挂载。
-
-### 显式可见性
-
-全零矩形无法区分“已隐藏”和“可见但恰好是 0×0”。需要这个区分时使用 `Placement` API：
-
-```ts
-import { createPlacementAnchor } from 'view-anchor'
-
-const handle = createPlacementAnchor(target, {
-  visible: true,
-  publish: applyPlacement,
-  followScroll: true, // 祖先容器滚动时重新测量
-  followGeometry: true, // 拖拽或滚动期间逐帧测量；稳定后停止
-  guardDisplayNone: true, // 零面积或 display:none 时发布 { visible: false }
-})
+元素卸载时，Hook 会先发布 `{ visible: false }`，再释放监听。它兼容 React 18 和 19 的 StrictMode 重挂载，不会因此发布过期帧。
 
-handle.pulse() // 例如在 CSS 过渡期间主动打开一段逐帧测量
-```
-
-React 版本为 `view-anchor/react` 导出的 `usePlacementAnchor`。
+它每次调用都会重新应用选项，规则与 `createViewAnchor` 和 `update()` 一致：省略任何一项都会重置为默认值，而不是沿用上次的值。省略 `treatZeroAreaAsHidden`、`followScroll` 或 `followGeometry` 会重置为 `false`；省略 `holdSelector` 会重置为 `[role="separator"]`；省略 `dedupe` 会重置为 `true`。要关闭 `holdSelector` / `dedupe`，传 `null` / `false`。
 
 ### 由内容决定占位尺寸
 
-当外部画面的内容尺寸需要反过来调整占位元素时，在内容所在的文档中使用 `createSizeAdvertiser`：
+当外部画面的内容尺寸需要反过来调整占位元素时，在内容所在的文档中使用 `createSizeAnchor`：
 
 ```ts
-import { createSizeAdvertiser } from 'view-anchor'
+import { createSizeAnchor } from 'view-anchor'
 
-const handle = createSizeAdvertiser(contentWrapper, {
-  axis: 'block', // 一个 advertiser 只负责一个轴：block = 高度，inline = 宽度
-  publish: updatePlaceholderSize,
+const publish = updatePlaceholderSize
+
+const handle = createSizeAnchor(contentWrapper, {
+  axis: 'block', // 一个 size anchor 只负责一个轴：block = 高度，inline = 宽度
+  publish,
 })
 
-handle.update(updatePlaceholderSize) // 有当前尺寸时会立即重新报告
+handle.update({ publish }) // 应用新选项并立即重新报告当前尺寸；省略 dedupe 会重置为 true
 handle.dispose()
 ```
 
@@ -133,7 +122,7 @@ handle.dispose()
 
 ### 需要传递、校验和排序时
 
-核心只交付 `Bounds`、`Placement` 和 `AdvertisedSize`。如果应用需要把这些值交给别的页面、环境或异步通道，可选的 `view-anchor/protocol` 提供消息版本、输入校验、乱序过滤和微任务合并。
+核心只交付 `Bounds`、`Placement` 和 `SizeMeasurement`。如果应用需要把这些值交给别的页面、环境或异步通道，可选的 `view-anchor/protocol` 提供消息版本、输入校验、乱序过滤和微任务合并。
 
 ```ts
 import {
@@ -161,34 +150,40 @@ if (decoded.ok) {
 
 ## 性能边界
 
-- 相同的已发布矩形不会再次调用 `publish`。
+- 默认去重：与上一次已发布的 `Placement`/尺寸完全相同不会再次调用 `publish`；传 `dedupe: false` 可以让每次测量都发布。
 - `followGeometry` 只在需要时启动动画帧轮询，稳定后停止。
 - `createGeometryBatcher` 会合并同一微任务内的更新；每个锚点的位置和尺寸各保留最新值。
 - `dispose()` 或 abort 会停止监听并释放长期持有的元素和回调引用。
 
-性能数据和测量方式见 [性能报告](./docs/performance-report.md)。这些数据只用于比较同一台机器上的改动，不能代表浏览器布局、传递或应用业务的耗时。
+与 0.2.2 的对比和导出体积见 [性能报告](./docs/performance-report.md)。
 
 ## API
 
-| 导出                                  | 类型        | 用途                                                                       |
-| ------------------------------------- | ----------- | -------------------------------------------------------------------------- |
-| `createViewAnchor(target, opts)`      | 函数        | 测量 DOM 元素并调用 `publish({ x, y, width, height })`。全零矩形表示收起。 |
-| `createPlacementAnchor(target, opts)` | 函数        | 发布带可见性的 `Placement`，可选滚动和几何跟随。                           |
-| `measurePlacement(target)`            | 函数        | 读取当前矩形，返回 `{ visible: true, bounds }`。                           |
-| `createSizeAdvertiser(target, opts)`  | 函数        | 用 `publish({ axis, extent })` 上报一个内容尺寸轴。                        |
-| `useViewAnchor(opts)`                 | Hook        | 返回占位元素的 ref 回调。                                                  |
-| `usePlacementAnchor(opts)`            | Hook        | `Placement` API 的 React 适配。                                            |
-| `Bounds`                              | 类型        | `{ x, y, width, height }`，单位为 CSS 像素。                               |
-| `Placement`                           | 类型        | `{ visible: true; bounds } \| { visible: false }`。                        |
-| `AdvertisedAxis` / `AdvertisedSize`   | 类型        | 内容尺寸上报的轴和数据。                                                   |
-| `view-anchor/protocol`                | 函数 + 类型 | 消息封装、校验、排序和批处理。                                             |
+| 导出                                     | 类型        | 用途                                                                                                                                 |
+| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `createViewAnchor(target, opts)`         | 函数        | 发布带可见性的 `Placement`，可选 `followScroll`、`followGeometry`、`treatZeroAreaAsHidden`、`holdSelector`、`dedupe`，含 `pulse()`。 |
+| `measurePlacement(target)`               | 函数        | 读取当前矩形，返回 `{ visible: true, bounds }`。                                                                                     |
+| `createSizeAnchor(target, opts)`         | 函数        | 用 `publish({ axis, extent })` 上报一个内容尺寸轴。                                                                                  |
+| `useViewAnchor(opts)`                    | Hook        | `createViewAnchor` 的 React 适配，返回占位元素的 ref 回调。                                                                          |
+| `Bounds`                                 | 类型        | `{ x, y, width, height }`，单位为 CSS 像素。                                                                                         |
+| `Placement`                              | 类型        | `{ visible: true; bounds } \| { visible: false }`。                                                                                  |
+| `Publisher<T>` / `PublishResult`         | 类型        | `publish` 回调的签名及其返回值（`void \| boolean`）。                                                                                |
+| `ViewAnchorOptions` / `ViewAnchorHandle` | 类型        | `createViewAnchor` 的选项与句柄。                                                                                                    |
+| `UseViewAnchorOptions` / `ViewAnchorRef` | 类型        | `useViewAnchor` 的选项与 ref 类型。                                                                                                  |
+| `SizeAxis` / `SizeMeasurement`           | 类型        | 内容尺寸上报的轴和数据。                                                                                                             |
+| `SizeAnchorOptions` / `SizeAnchorHandle` | 类型        | `createSizeAnchor` 的选项与句柄。                                                                                                    |
+| `view-anchor/protocol`                   | 函数 + 类型 | 消息封装、校验、排序和批处理。                                                                                                       |
+
+## 版本承诺
+
+1.x 版本内，`view-anchor` 不会删除或重命名 `.`、`view-anchor/react`、`view-anchor/protocol` 的任何公开导出，也不会改变已有合法输入的默认行为。minor 版本只新增功能，patch 版本只修 bug。要移除的接口会先标记为废弃，等到 2.0 才真正删除。
 
 ## 文档
 
-- [机制说明](./docs/mechanism.md)：正向测量的触发条件、收起和 React 生命周期。
+- [机制说明](./docs/mechanism.md)：正向测量的触发条件、默认去重与 `dedupe: false`、可见性与 React 生命周期。
 - [双向几何设计](./docs/bidirectional-design.md)：内容尺寸反向调整占位元素时的单轴约束。
 - [通信协议](./docs/protocol.md)：消息格式、校验、排序和批处理。
-- [性能报告](./docs/performance-report.md)：可复现的性能数据和测量环境。
+- [性能报告](./docs/performance-report.md)：性能结论和导出体积。
 
 ## 参与贡献
 

package/dist/index.d.ts

@@ -1,11 +1,9 @@
 /**
  * view-anchor: keeps an external surface aligned with a DOM element's geometry.
  */
-export { createViewAnchor, measurePlacement, createPlacementAnchor } from './view-anchor.js';
-export type { PlacementAnchorOptions, PlacementAnchorHandle } from './view-anchor.js';
-export type { Bounds, Placement, Publisher, PublishResult, ViewAnchorOptions, ViewAnchorHandle, } from './types.js';
-export { createSizeAdvertiser } from './size-advertiser.js';
-export { useViewAnchor } from './react.js';
-export type { AdvertisedAxis, AdvertisedSize, SizeAdvertiserOptions, SizeAdvertiserHandle, } from './types.js';
-export type { UseViewAnchorOptions, ViewAnchorRef } from './react.js';
+export { createViewAnchor, measurePlacement } from './view-anchor.js';
+export type { ViewAnchorOptions, ViewAnchorHandle } from './view-anchor.js';
+export type { Bounds, Placement, Publisher, PublishResult } from './types.js';
+export { createSizeAnchor } from './size-anchor.js';
+export type { SizeAxis, SizeMeasurement, SizeAnchorOptions, SizeAnchorHandle } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC5F,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACrF,YAAY,EACV,MAAM,EACN,SAAS,EACT,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,YAAY,EACV,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACrE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC3E,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,6 +1,5 @@
 /**
  * view-anchor: keeps an external surface aligned with a DOM element's geometry.
  */
-export { createViewAnchor, measurePlacement, createPlacementAnchor } from './view-anchor.js';
-export { createSizeAdvertiser } from './size-advertiser.js';
-export { useViewAnchor } from './react.js';
+export { createViewAnchor, measurePlacement } from './view-anchor.js';
+export { createSizeAnchor } from './size-anchor.js';

package/dist/protocol-publisher.d.ts

@@ -1,7 +1,7 @@
-import type { AdvertisedSize, Placement, Publisher } from './types.js';
+import type { SizeMeasurement, Placement, Publisher } from './types.js';
 import { type GeometryAddress, type GeometryBatch, type GeometryMessage } from './protocol-types.js';
-export type GeometrySend = Publisher<GeometryMessage>;
-export type GeometryBatchSend = Publisher<GeometryBatch>;
+export type GeometryMessageSender = Publisher<GeometryMessage>;
+export type GeometryBatchSender = Publisher<GeometryBatch>;
 export interface GeometryBatcherOptions {
     /** Observes every batch-delivery error, including explicit flushes; it must not throw. */
     onError?: (error: unknown) => void;
@@ -27,17 +27,15 @@ export interface GeometryBatcher {
  * recreating a publisher for the same address causes its messages to be dropped.
  * Increment `generation` when intentionally resetting the publisher.
  */
-export declare function createPlacementMessagePublisher(address: GeometryAddress, send: GeometrySend): (placement: Placement) => boolean;
+export declare function createPlacementMessagePublisher(address: GeometryAddress, send: GeometryMessageSender): (placement: Placement) => boolean;
 /**
  * Wraps size updates in a versioned protocol message.
  * Follows the same stability rule: keep one publisher per `{ anchorId, generation }`,
  * and increment `generation` when resetting.
  */
-export declare function createSizeMessagePublisher(address: GeometryAddress, send: GeometrySend): (size: AdvertisedSize) => boolean;
+export declare function createSizeMessagePublisher(address: GeometryAddress, send: GeometryMessageSender): (size: SizeMeasurement) => boolean;
 /**
- * Coalesces same-task messages without adding a rendering-frame delay. It owns
- * no authorization policy: callers must associate addresses with trusted
- * sources before accepting a delivered batch.
+ * Coalesces same-task messages without adding a rendering-frame delay.
  */
-export declare function createGeometryBatcher(send: GeometryBatchSend, options?: GeometryBatcherOptions): GeometryBatcher;
+export declare function createGeometryBatcher(send: GeometryBatchSender, options?: GeometryBatcherOptions): GeometryBatcher;
 //# sourceMappingURL=protocol-publisher.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"protocol-publisher.d.ts","sourceRoot":"","sources":["../src/protocol-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEtE,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EAGrB,MAAM,qBAAqB,CAAA;AAE5B,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,eAAe,CAAC,CAAA;AACrD,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC,aAAa,CAAC,CAAA;AAExD,MAAM,WAAW,sBAAsB;IACrC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IAC1C,4FAA4F;IAC5F,KAAK,IAAI,OAAO,CAAA;IAChB,gEAAgE;IAChE,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,uEAAuE;IACvE,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,YAAY,GACjB,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAcnC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,YAAY,GACjB,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAcnC;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAyKjB"}
+{"version":3,"file":"protocol-publisher.d.ts","sourceRoot":"","sources":["../src/protocol-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEvE,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EAGrB,MAAM,qBAAqB,CAAA;AAE5B,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,eAAe,CAAC,CAAA;AAC9D,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,aAAa,CAAC,CAAA;AAE1D,MAAM,WAAW,sBAAsB;IACrC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAA;IAC1C,4FAA4F;IAC5F,KAAK,IAAI,OAAO,CAAA;IAChB,gEAAgE;IAChE,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,uEAAuE;IACvE,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,qBAAqB,GAC1B,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAcnC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,qBAAqB,GAC1B,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAcpC;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,mBAAmB,EACzB,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAqKjB"}

package/dist/protocol-publisher.js

@@ -46,9 +46,7 @@ export function createSizeMessagePublisher(address, send) {
 // keep the caller's transport closure (and whatever it captured) alive.
 const NOOP_SEND = () => false;
 /**
- * Coalesces same-task messages without adding a rendering-frame delay. It owns
- * no authorization policy: callers must associate addresses with trusted
- * sources before accepting a delivered batch.
+ * Coalesces same-task messages without adding a rendering-frame delay.
  */
 export function createGeometryBatcher(send, options = {}) {
     const anchors = new Map();
@@ -154,11 +152,7 @@ export function createGeometryBatcher(send, options = {}) {
         removeAbortListener = () => { };
         anchors.clear();
         pendingAnchors.clear();
-        // Callers may still mutate the original options object after
-        // construction (e.g. reassigning onError); flush() captures its own
-        // reference before send() runs, so an in-flight error report keeps
-        // reading that object even though dispose() drops the instance's
-        // long-lived reference here.
+        // Drop the long-lived reference; flush() captures its own before send() runs.
         options = {};
         send = NOOP_SEND;
     };