view-anchor 0.2.2-alpha.0 → 1.0.0-beta.0

package/README.md

@@ -2,38 +2,46 @@
   <img src="https://raw.githubusercontent.com/lbb00/view-anchor/main/assets/banner.svg" alt="view-anchor — keep anything outside the DOM aligned to a DOM element" width="820">
 </p>
 
-> A high-performance geometry bridge that keeps anything living outside the DOM aligned to a DOM element: an Electron `WebContentsView`, a native webview in another desktop shell, a cross-origin iframe, or any surface you position from a rectangle. Every move and resize is published synchronously with no duplicate frames.
+> Keep an external surface aligned to a DOM element. `view-anchor` measures the element and synchronously gives your code the current geometry whenever it changes.
 
 [![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 things you want to place inside your layout are not DOM nodes. An Electron `WebContentsView` is positioned by the main process. A native webview in another desktop shell is positioned by host code. The document inside a cross-origin iframe only knows what you tell it over `postMessage`. Your layout, whether it is flexbox, dockview, or react-resizable-panels, only moves DOM nodes and has no idea that something else is supposed to sit exactly on top of one of them.
+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.
 
-`view-anchor` closes that gap. You point it at a placeholder element. It measures the element and, every time the element moves or resizes, hands the new rectangle to your `publish` callback. What happens next is up to you: `ipcRenderer.send` plus `view.setBounds` in Electron, `postMessage` to an iframe, or a direct call into whatever positions the surface.
+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 Electron, a browser shell, React, or any 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.
 
-## Built for the hot path
+## What `publish` receives
 
-Geometry updates fire on every resize and, when following a drag, on every animation frame. The library keeps that work predictable:
+`publish` is a synchronous function that the library calls with one of these plain values:
+
+- `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. 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.
+
+## Performance
+
+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 before allocate.** A rectangle identical to the last accepted one is rejected by comparing four numbers, before any object is created.
-- **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 DOM layout, Electron IPC, structured clone, or your app's workload.
+See the [performance report](./docs/performance-report.md) for a comparison with 0.2.2 and export sizes.
 
 ## Installation
 
@@ -43,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
 
@@ -52,16 +60,36 @@ React is an optional peer dependency. Import the hooks from `view-anchor/react`.
 ```ts
 import { createViewAnchor } from 'view-anchor'
 
+const publish = (placement) => {
+  if (placement.visible) applyBounds(placement.bounds)
+  else hideSurface()
+}
+
 const handle = createViewAnchor(target, {
-  present: true,                 // mount the native view
-  publish: (bounds) => { ... },  // receive live rectangles; wire IPC → setBounds
+  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, publish }) // apply new options and publish right away
-handle.dispose()                    // stop observing; never publishes again
+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 view. The core publishes a zero rectangle and stops observing. The host can detach the subview while keeping the `WebContents` alive, so re-showing it later is instant.
+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.
+
+`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, { visible: true, publish, signal: controller.signal })
+
+controller.abort() // same cleanup as handle.dispose()
+```
 
 ### React
 
@@ -70,57 +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 native view follows this placeholder div. Hiding the panel
-  // (visible=false or unmount) collapses it without destroying it.
+  // The external surface follows this placeholder. Hiding or unmounting it
+  // 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, {
-  publish: (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 handle = createSizeAdvertiser(contentWrapper, {
-  axis: 'block',                 // one axis per advertiser: block = height, inline = width
-  publish: (size) => { ... },    // receives { axis, extent }; wire IPC → host
+const 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.dispose()       // stop observing; never reports 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. Once those values cross a process or origin boundary, over IPC or `postMessage`, you usually want validation and ordering. The optional `view-anchor/protocol` entry adds versioned message envelopes, bounded decoding of untrusted input, 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 {
@@ -129,59 +144,58 @@ import {
   decodeGeometryWireValue,
 } from 'view-anchor/protocol'
 
-// sending side (renderer, iframe, ...)
-const batcher = createGeometryBatcher((batch) => ipc.send('geometry', batch))
+// `sendGeometryBatch` is supplied by your application.
+const batcher = createGeometryBatcher(sendGeometryBatch)
 const publish = createPlacementMessagePublisher(
   { anchorId: 'editor', generation: 3 },
   batcher.publish,
 )
 
-// receiving side (main process, host page, ...)
+// receiving side
 const decoded = decodeGeometryWireValue(received, { maxMessages: 100 })
 if (decoded.ok) {
   /* check the sender, then apply only newer messages */
 }
 ```
 
-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 publish live bounds. 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          | Reverse direction: report the view's own content size to the host.                                                            |
-| `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

@@ -1,39 +1,31 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/lbb00/view-anchor/main/assets/banner.svg" alt="view-anchor — 让 DOM 之外的画面贴合 DOM 元素" width="820">
+  <img src="https://raw.githubusercontent.com/lbb00/view-anchor/main/assets/banner.svg" alt="view-anchor — 让 DOM 之外的画面实时对齐 DOM 元素" width="820">
 </p>
 
-> 高性能几何桥接库，让任何"不在 DOM 里的东西"始终贴合某个 DOM 元素：Electron 的 `WebContentsView`、其他桌面壳里的原生 webview、跨域 iframe，或者任何你能用一个矩形来定位的画面。每次移动和缩放都同步发布、不会重复发帧。
+> 让 DOM 之外的画面实时对齐 DOM 元素：测量占位元素，逐帧同步最新矩形，拖拽无延迟。
 
 [![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)
 
-> 🎮 **在线 Demo**：[3D 交互演示](https://lbb00.github.io/view-anchor/) 在浏览器里跑的是真实核心代码。拖动分栏、切换面板显示，看原生视图实时跟随。
+> [在线演示](https://lbb00.github.io/view-anchor/)：直接在倾斜的 3D 场景里拖动分隔条、滚动页面、点击按钮。画面 A 跟随占位元素；画面 B 把自己的内容高度报回页面，页面据此调整它的占位。
 
-## 要解决的问题
+## 它解决什么问题
 
-有些你想放进布局里的东西并不是 DOM 节点。Electron 的 `WebContentsView` 由主进程定位；其他桌面壳里的原生 webview 由宿主代码定位；跨域 iframe 里的文档只知道你通过 `postMessage` 告诉它的信息。而你的布局，不管是 flexbox、dockview 还是 react-resizable-panels，只会移动 DOM 节点，并不知道有别的东西需要正好盖在其中某个节点上面。
+有些画面的位置由应用自己摆放（叠层、嵌入式文档或能根据矩形定位的渲染表面）。DOM 布局会移动占位元素，但不会自动更新这些画面的位置。
 
-`view-anchor` 负责补上这一段。你把它指向一个占位元素，它测量这个元素，元素每次移动或缩放时，把新的矩形交给你的 `publish` 回调。接下来怎么用由你决定：在 Electron 里接 `ipcRenderer.send` 和 `view.setBounds`，对 iframe 就 `postMessage`，或者直接调用任何负责定位那个画面的代码。
+`view-anchor` 负责测量占位元素，在尺寸变化或窗口大小变化时同步调用你提供的 `publish` 函数。函数如何使用这个值由应用决定。
 
-核心不依赖 Electron、任何浏览器壳、React 或布局库，只用到 `ResizeObserver`、`requestAnimationFrame` 和 `getBoundingClientRect`。React 支持放在单独的 `view-anchor/react` 入口里。
+## `publish` 收到什么
 
-## 为热路径而写
+`publish` 是一个同步回调，不同接口会传入不同的普通对象：
 
-几何更新在每次缩放时都会触发，跟随拖拽时更是每一帧都触发。这个库让这条路径保持可控：
+- `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 像素，取整且不小于零。
 
-- **同步发布。** 测量和发布在同一个 `ResizeObserver` 回调里完成。没有定时器，不多等一帧。
-- **先去重，再分配。** 和上一次已接受的矩形完全相同的结果，只比较四个数字就会被丢弃，不会创建任何对象。
-- **只在需要时逐帧跟随。** `followGeometry` 只在滚动、拖动分栏或显式调用 `pulse()` 时才开始按 `requestAnimationFrame` 轮询，矩形稳定后自动停止。空闲时开销为零，隐藏或无效目标最多跟 30 帧。
-- **generation 切换是 O(1)。** 协议层里，把某个锚点换到新的 generation 或清除它，不会碰到其他锚点。
-- **合并批量，只发最新。** 同一个任务里排队的消息在一个微任务里合并，每个锚点分别发送最新的位置和尺寸。
-- **销毁后释放引用。** 句柄 `dispose()` 后会停止观察，并释放目标元素和回调；调用方继续持有句柄也不会保留它们。
-- **核心紧凑，可摇树。** 每个函数都是独立导出，并声明了 `sideEffects: false`；完整核心导出 gzip 后小于 3 KB。
-
-[性能报告](./docs/performance-report.md) 保留可复现的测量数据和环境。它适合比较同一台机器上的改动，不用于预测 DOM layout、Electron IPC、structured clone 或你的应用负载。
+数据已接收或已经入队时，返回 `true` 或不返回值；当前不能接收时才返回 `false`，下一次测量会重试被拒绝的值。隐藏状态下不再测量，所以被拒绝的 `{ visible: false }` 不会自动重发，需要再调用一次 `update()`；`useViewAnchor` 会在卸载时替你补发。
 
 ## 安装
 
@@ -43,84 +35,94 @@ pnpm add view-anchor
 npm install view-anchor
 ```
 
-React 是可选的 peer dependency。Hook 从 `view-anchor/react` 导入。为了兼容 `v0.1.2`，根入口也会重新导出 `useViewAnchor`，所以只要导入了 `view-anchor` 就需要装 React。`view-anchor/protocol` 不需要。
+React 是可选 peer dependency，只有从 `view-anchor/react` 导入时才需要。根入口（`view-anchor`）和 `view-anchor/protocol` 不依赖 React，未安装 React 也能加载。
 
-## 用法
+## 使用
 
 ### 跟随一个 DOM 元素
 
 ```ts
 import { createViewAnchor } from 'view-anchor'
 
-const handle = createViewAnchor(target, {
-  present: true,                 // 挂载原生视图
-  publish: (bounds) => { ... },  // 收到实时矩形；接 IPC → setBounds
+const publish = (placement) => {
+  if (placement.visible) applyBoundsToExternalSurface(placement.bounds)
+  else hideExternalSurface()
+}
+
+const handle = createViewAnchor(placeholderEl, {
+  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, publish }) // 应用新选项并立刻发布一次
-handle.dispose()                    // 停止观察；之后不会再发布
+handle.update({ visible: true, publish }) // 更新选项并立即重新发布
+handle.pulse() // 位置变了但没有任何观察器能感知时（如一次类名切换让目标移动了但尺寸没变）主动重测；稳定后自动停止
+handle.dispose() // 停止观察；之后不会再发布
 ```
 
-把 `present` 设为 `false` 可以收起视图。核心会发布一个零矩形并停止观察。宿主可以把子视图摘下来但保留 `WebContents`，这样之后再显示时是即时的。
+把 `visible` 设为 `false` 会发布 `{ visible: false }` 并停止观察。你的 `publish` 函数可以把它解释为隐藏、移除，或保留外部画面。
+
+`createViewAnchor`、`createSizeAnchor` 和 `createGeometryBatcher` 都支持 `signal`。调用 `AbortController.abort()` 的清理效果等同于 `dispose()`；创建前已经 abort 的 signal 不会开始测量或安装监听。
+
+```ts
+const controller = new AbortController()
+const handle = createViewAnchor(placeholderEl, {
+  visible: true,
+  publish,
+  signal: controller.signal,
+})
+
+controller.abort()
+```
 
 ### React
 
 ```tsx
 import { useViewAnchor } from 'view-anchor/react'
 
-function DebugPanel({ visible }: { visible: boolean }) {
+function ExternalSurfaceContainer({ visible }: { visible: boolean }) {
   const ref = useViewAnchor({
-    present: visible,
-    publish: publishPanelBounds,
+    visible,
+    publish: applyPlacementToExternalSurface,
+    followScroll: true,
+    followGeometry: true,
   })
-  // 原生视图跟随这个占位 div。隐藏面板（visible=false 或卸载）
-  // 只会收起视图，不会销毁它。
+
   return <div ref={ref} className="h-full w-full" />
 }
 ```
 
-Hook 在 React 18 和 19 的 StrictMode 双重挂载下不会发出过期的帧。
+元素卸载时，Hook 会先发布 `{ visible: false }`，再释放监听。它兼容 React 18 和 19 的 StrictMode 重挂载，不会因此发布过期帧。
 
-### 显式可见性
+它每次调用都会重新应用选项，规则与 `createViewAnchor` 和 `update()` 一致：省略任何一项都会重置为默认值，而不是沿用上次的值。省略 `treatZeroAreaAsHidden`、`followScroll` 或 `followGeometry` 会重置为 `false`；省略 `holdSelector` 会重置为 `[role="separator"]`；省略 `dedupe` 会重置为 `true`。要关闭 `holdSelector` / `dedupe`，传 `null` / `false`。
 
-零矩形分不清"视图被隐藏了"和"视图可见但此刻正好是 0×0"。需要区分这两种情况时，用 `Placement` API。它发布的是 `{ visible: true, bounds }` 或 `{ visible: false }`，并提供可选的滚动跟随和几何跟随：
+### 由内容决定占位尺寸
 
-```ts
-import { createPlacementAnchor } from 'view-anchor'
-
-const handle = createPlacementAnchor(target, {
-  publish: (placement) => { ... },
-  followScroll: true,     // 任意祖先滚动时重新测量
-  followGeometry: true,   // 滚动 / 拖拽期间逐帧轮询，稳定后停止
-  guardDisplayNone: true, // 零面积或 display:none 的目标 → { visible: false }
-})
-
-handle.pulse() // 打开一小段逐帧跟随窗口，比如 CSS 过渡期间
-```
-
-React 版本是 `view-anchor/react` 里的 `usePlacementAnchor`。
-
-### 由内容决定尺寸
-
-有时被嵌入的那个画面的尺寸应该由它自己的内容决定，比如一条由下游代码渲染的工具栏。这种情况在被嵌入的文档里运行 `createSizeAdvertiser`，它把内容尺寸报告回去，宿主里的 DOM 占位元素就能跟着长到一样大：
+当外部画面的内容尺寸需要反过来调整占位元素时，在内容所在的文档中使用 `createSizeAnchor`：
 
 ```ts
-import { createSizeAdvertiser } from 'view-anchor'
+import { createSizeAnchor } from 'view-anchor'
+
+const publish = updatePlaceholderSize
 
-const handle = createSizeAdvertiser(contentWrapper, {
-  axis: 'block',                 // 一个 advertiser 只管一个轴：block = 高度，inline = 宽度
-  publish: (size) => { ... },    // 收到 { axis, extent }；接 IPC → 宿主
+const handle = createSizeAnchor(contentWrapper, {
+  axis: 'block', // 一个 size anchor 只负责一个轴：block = 高度，inline = 宽度
+  publish,
 })
 
-handle.update(publish) // 换一个发布通道，并立刻再报告一次当前尺寸
-handle.dispose()       // 停止观察；之后不会再报告
+handle.update({ publish }) // 应用新选项并立即重新报告当前尺寸；省略 dedupe 会重置为 true
+handle.dispose()
 ```
 
-> **注意：** 目标元素在它负责的那个轴上必须是随内容收缩的。如果这个尺寸反过来由宿主设置，两边会互相触发、永远停不下来。见 [docs/bidirectional-design.md](./docs/bidirectional-design.md)。
+目标元素在它负责的轴上必须随内容伸缩。若应用也反过来在同一轴上强制设置尺寸，双方会互相触发布局，难以稳定。详见 [双向几何设计](./docs/bidirectional-design.md)。
 
-### 跨边界的带版本传输
+### 需要传递、校验和排序时
 
-核心交给你的是普通的 `Bounds`、`Placement` 和 `AdvertisedSize` 值。这些值一旦通过 IPC 或 `postMessage` 跨过进程或源的边界，通常就需要校验和排序。可选的 `view-anchor/protocol` 入口提供带版本的消息信封、对不可信输入的有界解码、按锚点丢弃过期消息的序列守卫，以及一个微任务批处理器：
+核心只交付 `Bounds`、`Placement` 和 `SizeMeasurement`。如果应用需要把这些值交给别的页面、环境或异步通道，可选的 `view-anchor/protocol` 提供消息版本、输入校验、乱序过滤和微任务合并。
 
 ```ts
 import {
@@ -129,57 +131,63 @@ import {
   decodeGeometryWireValue,
 } from 'view-anchor/protocol'
 
-// 发送方（渲染进程、iframe 等）
-const batcher = createGeometryBatcher((batch) => ipc.send('geometry', batch))
+// sendGeometryBatch 由应用实现：接收一个 batch，并同步返回是否已接收。
+const batcher = createGeometryBatcher(sendGeometryBatch)
 const publish = createPlacementMessagePublisher(
   { anchorId: 'editor', generation: 3 },
   batcher.publish,
 )
 
-// 接收方（主进程、宿主页面等）
 const decoded = decodeGeometryWireValue(received, { maxMessages: 100 })
 if (decoded.ok) {
-  /* 先校验发送方，再只应用更新的消息 */
+  // 先验证来源，再只应用更新的消息。
 }
 ```
 
-两条规则保证顺序正确：
+同一个 `{ anchorId, generation }` 应只保留一个 publisher 实例。针对同一地址重新创建 publisher 会让序号回到 1，接收端会把新消息当作过期消息丢弃。需要重新开始时，把 `generation` 加一。
+
+完整约定见 [通信协议](./docs/protocol.md)。
+
+## 性能边界
 
-- **每个 `{ anchorId, generation }` 只保留一个 publisher。** batcher 和 `createGeometrySequenceGuard` 会分别记住每个锚点的位置与尺寸消息的最大序号。针对同一地址重建 publisher 会让序号从 1 重新开始，它发的消息会被当成过期而丢弃。在 React 里用 `useMemo` 或 `useRef` 持有它。确实需要重新开始时，把 `generation` 加一。
-- **同步 publisher 返回 `false` 表示"未接受"。** 核心会在下一次触发时重试同一份几何数据。批处理 publisher 入队后就返回 `true`，之后的重试由它自己负责。
+- 默认去重：与上一次已发布的 `Placement`/尺寸完全相同不会再次调用 `publish`；传 `dedupe: false` 可以让每次测量都发布。
+- `followGeometry` 只在需要时启动动画帧轮询，稳定后停止。
+- `createGeometryBatcher` 会合并同一微任务内的更新；每个锚点的位置和尺寸各保留最新值。
+- `dispose()` 或 abort 会停止监听并释放长期持有的元素和回调引用。
 
-完整约定见 [docs/protocol.md](./docs/protocol.md)。
+与 0.2.2 的对比和导出体积见 [性能报告](./docs/performance-report.md)。
 
 ## API
 
-| 导出                                                                         | 类型        | 用途                                                                                                                   |
-| ---------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `createViewAnchor(target, opts)`                                             | 函数        | 测量 DOM 元素并发布实时 bounds。零矩形表示已收起。                                                                     |
-| `createPlacementAnchor(target, opts)`                                        | 函数        | 同一个核心，带显式 `Placement` 可见性、可选的 `followScroll` / `followGeometry` / `guardDisplayNone`，以及 `pulse()`。 |
-| `measurePlacement(target)`                                                   | 函数        | 纯测量：把目标矩形包成 `{ visible: true, bounds }`。                                                                   |
-| `createSizeAdvertiser(target, opts)`                                         | 函数        | 反向：把视图自身的内容尺寸报告给宿主。                                                                                 |
-| `useViewAnchor(opts)`，来自 `view-anchor/react`                              | Hook        | 返回用于占位元素的 ref 回调。                                                                                          |
-| `usePlacementAnchor(opts)`，来自 `view-anchor/react`                         | Hook        | `Placement` API 的 React 适配，包含 `followScroll` 和 `followGeometry`。                                               |
-| `Bounds`                                                                     | 类型        | CSS 像素单位的 `{ x, y, width, height }`。                                                                             |
-| `Placement`                                                                  | 类型        | `{ visible: true; bounds } \| { visible: false }`。                                                                    |
-| `ViewAnchorOptions` / `ViewAnchorHandle`                                     | 类型        | `createViewAnchor` 的选项和句柄。                                                                                      |
-| `PlacementAnchorOptions` / `PlacementAnchorHandle`                           | 类型        | `createPlacementAnchor` 的选项和句柄。                                                                                 |
-| `UseViewAnchorOptions` / `ViewAnchorRef`，来自 `view-anchor/react`           | 类型        | `useViewAnchor` 的选项和 ref 形状。                                                                                    |
-| `UsePlacementAnchorOptions` / `PlacementAnchorRef`，来自 `view-anchor/react` | 类型        | `usePlacementAnchor` 的选项和 ref 形状。                                                                               |
-| `AdvertisedAxis` / `AdvertisedSize`                                          | 类型        | 反向方向的轴和负载类型。                                                                                               |
-| `SizeAdvertiserOptions` / `SizeAdvertiserHandle`                             | 类型        | `createSizeAdvertiser` 的选项和句柄。                                                                                  |
-| `view-anchor/protocol`                                                       | 函数 + 类型 | 带版本的消息、严格解码、序列守卫、消息 publisher 和微任务批处理。                                                      |
+| 导出                                     | 类型        | 用途                                                                                                                                 |
+| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `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](./docs/mechanism.md)：正向方向的原理。同步发布、防止过期帧、`present` / 零矩形 / 卸载的约定、StrictMode 下的行为。内含 [docs/index.html](./docs/index.html) 的 3D 交互演示。
-- [docs/bidirectional-design.md](./docs/bidirectional-design.md)：两个方向同时运行时的设计。为什么正向是同步的而反向走动画帧、单轴归属，以及信任边界在哪。
-- [docs/protocol.md](./docs/protocol.md)：消息信封、校验、排序、批处理，以及失败时会发生什么。
-- [docs/performance-report.md](./docs/performance-report.md)：可复现的 CPU、堆、RSS、极端场景、V8 和导出体积测量。
+- [机制说明](./docs/mechanism.md)：正向测量的触发条件、默认去重与 `dedupe: false`、可见性与 React 生命周期。
+- [双向几何设计](./docs/bidirectional-design.md)：内容尺寸反向调整占位元素时的单轴约束。
+- [通信协议](./docs/protocol.md)：消息格式、校验、排序和批处理。
+- [性能报告](./docs/performance-report.md)：性能结论和导出体积。
 
 ## 参与贡献
 
-欢迎提 issue 和 pull request。提交前请运行 `pnpm lint`、`pnpm format:check`、`pnpm check-types`、`pnpm test` 和 `pnpm build`。`pnpm benchmark` 会输出用于更新性能报告的数据。
+提交前运行 `pnpm lint`、`pnpm format:check`、`pnpm check-types`、`pnpm test` 和 `pnpm build`。`pnpm benchmark` 用于更新性能报告。
 
 ## 许可证
 

package/dist/abort.d.ts

@@ -0,0 +1,3 @@
+/** Attach a one-shot abort listener and return a function that detaches it. */
+export declare function watchAbort(signal: AbortSignal | undefined, dispose: () => void): () => void;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAEA,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAK3F"}