view-anchor 0.2.2-alpha.0 → 0.2.2

package/README.md

@@ -2,7 +2,7 @@
   <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)
@@ -15,25 +15,35 @@
 
 ## 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. 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.
 
-`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 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.
 
-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. It only uses `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:
+
+- `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.
+
+Return `false` only when the value was not accepted; a later measurement may retry it. Return `true` or nothing after accepting or queueing it.
 
 ## Built for the hot path
 
 Geometry updates fire on every resize and, when following a drag, on every animation frame. The library keeps that work predictable:
 
 - **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.
+- **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.
 - **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.
 - **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.
 
-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.
+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.
 
 ## Installation
 
@@ -52,16 +62,31 @@ 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 handle = createViewAnchor(target, {
-  present: true,                 // mount the native view
-  publish: (bounds) => { ... },  // receive live rectangles; wire IPC → setBounds
+  present: true,
+  publish,
 })
 
-handle.update({ present, publish }) // apply new options and publish right away
-handle.dispose()                    // stop observing; never publishes again
+handle.update({ present: true, publish }) // apply new options and publish right away
+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 `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.
+
+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.
+
+```ts
+const controller = new AbortController()
+const handle = createViewAnchor(target, { present: true, publish, signal: controller.signal })
+
+controller.abort() // same cleanup as handle.dispose()
+```
 
 ### React
 
@@ -73,8 +98,8 @@ function DebugPanel({ visible }: { visible: boolean }) {
     present: visible,
     publish: publishPanelBounds,
   })
-  // 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 the collapsed value, without deciding how the surface is stored.
   return <div ref={ref} className="h-full w-full" />
 }
 ```
@@ -89,9 +114,12 @@ A zero rectangle cannot tell a hidden view from one that is visible but currentl
 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
+  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 }
 })
 
@@ -108,19 +136,21 @@ Sometimes the hosted surface's size should come from its own content, for exampl
 import { createSizeAdvertiser } 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
+  axis: 'block', // one axis per advertiser: block = height, inline = width
+  publish(size) {
+    updatePlaceholderSize(size)
+  },
 })
 
 handle.update(publish) // swap the publish channel and report the current size again
-handle.dispose()       // stop observing; never reports again
+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).
 
 ### 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 `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:
 
 ```ts
 import {
@@ -129,14 +159,14 @@ 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 */
@@ -154,10 +184,10 @@ The full contract is in [docs/protocol.md](./docs/protocol.md).
 
 | Export                                                                      | Kind              | Purpose                                                                                                                       |
 | --------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `createViewAnchor(target, opts)`                                            | function          | Measure a DOM element and publish live bounds. A zero rect means collapsed.                                                   |
+| `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          | Reverse direction: report the view's own content size to the host.                                                            |
+| `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.                                                                                      |

package/README.zh-CN.md

@@ -1,8 +1,8 @@
 <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)
@@ -11,29 +11,23 @@
 
 [English](./README.md) · [简体中文](./README.zh-CN.md)
 
-> 🎮 **在线 Demo**：[3D 交互演示](https://lbb00.github.io/view-anchor/) 在浏览器里跑的是真实核心代码。拖动分栏、切换面板显示，看原生视图实时跟随。
+> [在线演示](https://lbb00.github.io/view-anchor/)：拖动分栏、切换面板或 3D 视角，查看外部画面如何跟随占位元素。
 
-## 要解决的问题
+## 它解决什么问题
 
-有些你想放进布局里的东西并不是 DOM 节点。Electron 的 `WebContentsView` 由主进程定位；其他桌面壳里的原生 webview 由宿主代码定位；跨域 iframe 里的文档只知道你通过 `postMessage` 告诉它的信息。而你的布局，不管是 flexbox、dockview 还是 react-resizable-panels，只会移动 DOM 节点，并不知道有别的东西需要正好盖在其中某个节点上面。
+有些画面的位置不是由 CSS 直接控制：例如应用自己摆放的叠层、嵌入式文档，或能根据矩形定位的渲染表面。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(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` 是取整后且不小于零的内容尺寸。
 
-- **同步发布。** 测量和发布在同一个 `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`。下一次测量会重试被拒绝的值。
 
 ## 安装
 
@@ -43,84 +37,103 @@ 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。Hook 从 `view-anchor/react` 导入；根入口为了兼容 `v0.1.2` 也会导出 `useViewAnchor`，因此导入根入口时需要安装 React。`view-anchor/protocol` 不需要 React。
 
-## 用法
+## 使用
 
 ### 跟随一个 DOM 元素
 
 ```ts
 import { createViewAnchor } from 'view-anchor'
 
-const handle = createViewAnchor(target, {
-  present: true,                 // 挂载原生视图
-  publish: (bounds) => { ... },  // 收到实时矩形；接 IPC → setBounds
+const publish = (bounds) => {
+  applyBoundsToExternalSurface(bounds)
+}
+
+const handle = createViewAnchor(placeholderEl, {
+  present: true,
+  publish,
 })
 
-handle.update({ present, publish }) // 应用新选项并立刻发布一次
-handle.dispose()                    // 停止观察；之后不会再发布
+handle.update({ present: true, publish }) // 更新选项并立即重新发布
+handle.dispose() // 停止观察；之后不会再发布
 ```
 
-把 `present` 设为 `false` 可以收起视图。核心会发布一个零矩形并停止观察。宿主可以把子视图摘下来但保留 `WebContents`，这样之后再显示时是即时的。
+默认的 `createViewAnchor` 监听 `ResizeObserver` 和窗口 `resize`。如果祖先滚动、transform 或拖拽会移动元素而不改变它自身尺寸，请使用下面的 `createPlacementAnchor`，按需开启 `followScroll` 或 `followGeometry`。
+
+把 `present` 设为 `false` 会发布全零矩形并停止观察。你的 `publish` 函数可以把它解释为隐藏、移除，或保留外部画面。
+
+`createViewAnchor`、`createPlacementAnchor`、`createSizeAdvertiser` 和 `createGeometryBatcher` 都支持 `signal`。调用 `AbortController.abort()` 的清理效果等同于 `dispose()`；创建前已经 abort 的 signal 不会开始测量或安装监听。
+
+```ts
+const controller = new AbortController()
+const handle = createViewAnchor(placeholderEl, {
+  present: 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,
+    publish: applyBoundsToExternalSurface,
   })
-  // 原生视图跟随这个占位 div。隐藏面板（visible=false 或卸载）
-  // 只会收起视图，不会销毁它。
+
   return <div ref={ref} className="h-full w-full" />
 }
 ```
 
-Hook 在 React 18 和 19 的 StrictMode 双重挂载下不会发出过期的帧。
+元素卸载时，Hook 会先发布收起值，再释放监听。它兼容 React 18 和 19 的 StrictMode 重挂载。
 
 ### 显式可见性
 
-零矩形分不清"视图被隐藏了"和"视图可见但此刻正好是 0×0"。需要区分这两种情况时，用 `Placement` API。它发布的是 `{ visible: true, bounds }` 或 `{ visible: false }`，并提供可选的滚动跟随和几何跟随：
+全零矩形无法区分“已隐藏”和“可见但恰好是 0×0”。需要这个区分时使用 `Placement` API：
 
 ```ts
 import { createPlacementAnchor } from 'view-anchor'
 
 const handle = createPlacementAnchor(target, {
-  publish: (placement) => { ... },
-  followScroll: true,     // 任意祖先滚动时重新测量
-  followGeometry: true,   // 滚动 / 拖拽期间逐帧轮询，稳定后停止
-  guardDisplayNone: true, // 零面积或 display:none 的目标 → { visible: false }
+  visible: true,
+  publish: applyPlacement,
+  followScroll: true, // 祖先容器滚动时重新测量
+  followGeometry: true, // 拖拽或滚动期间逐帧测量；稳定后停止
+  guardDisplayNone: true, // 零面积或 display:none 时发布 { visible: false }
 })
 
-handle.pulse() // 打开一小段逐帧跟随窗口，比如 CSS 过渡期间
+handle.pulse() // 例如在 CSS 过渡期间主动打开一段逐帧测量
 ```
 
-React 版本是 `view-anchor/react` 里的 `usePlacementAnchor`。
+React 版本为 `view-anchor/react` 导出的 `usePlacementAnchor`。
 
-### 由内容决定尺寸
+### 由内容决定占位尺寸
 
-有时被嵌入的那个画面的尺寸应该由它自己的内容决定，比如一条由下游代码渲染的工具栏。这种情况在被嵌入的文档里运行 `createSizeAdvertiser`，它把内容尺寸报告回去，宿主里的 DOM 占位元素就能跟着长到一样大：
+当外部画面的内容尺寸需要反过来调整占位元素时，在内容所在的文档中使用 `createSizeAdvertiser`：
 
 ```ts
 import { createSizeAdvertiser } from 'view-anchor'
 
 const handle = createSizeAdvertiser(contentWrapper, {
-  axis: 'block',                 // 一个 advertiser 只管一个轴：block = 高度，inline = 宽度
-  publish: (size) => { ... },    // 收到 { axis, extent }；接 IPC → 宿主
+  axis: 'block', // 一个 advertiser 只负责一个轴：block = 高度，inline = 宽度
+  publish: updatePlaceholderSize,
 })
 
-handle.update(publish) // 换一个发布通道，并立刻再报告一次当前尺寸
-handle.dispose()       // 停止观察；之后不会再报告
+handle.update(updatePlaceholderSize) // 有当前尺寸时会立即重新报告
+handle.dispose()
 ```
 
-> **注意：** 目标元素在它负责的那个轴上必须是随内容收缩的。如果这个尺寸反过来由宿主设置，两边会互相触发、永远停不下来。见 [docs/bidirectional-design.md](./docs/bidirectional-design.md)。
+目标元素在它负责的轴上必须随内容伸缩。若应用也反过来在同一轴上强制设置尺寸，双方会互相触发布局，难以稳定。详见 [双向几何设计](./docs/bidirectional-design.md)。
 
-### 跨边界的带版本传输
+### 需要传递、校验和排序时
 
-核心交给你的是普通的 `Bounds`、`Placement` 和 `AdvertisedSize` 值。这些值一旦通过 IPC 或 `postMessage` 跨过进程或源的边界，通常就需要校验和排序。可选的 `view-anchor/protocol` 入口提供带版本的消息信封、对不可信输入的有界解码、按锚点丢弃过期消息的序列守卫，以及一个微任务批处理器：
+核心只交付 `Bounds`、`Placement` 和 `AdvertisedSize`。如果应用需要把这些值交给别的页面、环境或异步通道，可选的 `view-anchor/protocol` 提供消息版本、输入校验、乱序过滤和微任务合并。
 
 ```ts
 import {
@@ -129,57 +142,57 @@ 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`，之后的重试由它自己负责。
+- 相同的已发布矩形不会再次调用 `publish`。
+- `followGeometry` 只在需要时启动动画帧轮询，稳定后停止。
+- `createGeometryBatcher` 会合并同一微任务内的更新；每个锚点的位置和尺寸各保留最新值。
+- `dispose()` 或 abort 会停止监听并释放长期持有的元素和回调引用。
 
-完整约定见 [docs/protocol.md](./docs/protocol.md)。
+性能数据和测量方式见 [性能报告](./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)`      | 函数        | 测量 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`                | 函数 + 类型 | 消息封装、校验、排序和批处理。                                             |
 
 ## 文档
 
-- [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)：正向测量的触发条件、收起和 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"}

package/dist/abort.js

@@ -0,0 +1,9 @@
+const NOOP = () => { };
+/** Attach a one-shot abort listener and return a function that detaches it. */
+export function watchAbort(signal, dispose) {
+    if (!signal)
+        return NOOP;
+    const onAbort = () => dispose();
+    signal.addEventListener('abort', onAbort, { once: true });
+    return () => signal.removeEventListener('abort', onAbort);
+}

package/dist/protocol-publisher.d.ts

@@ -5,6 +5,8 @@ export type GeometryBatchSend = Publisher<GeometryBatch>;
 export interface GeometryBatcherOptions {
     /** Observes every batch-delivery error, including explicit flushes; it must not throw. */
     onError?: (error: unknown) => void;
+    /** Stops this batcher when aborted. An already-aborted signal starts no work. */
+    signal?: AbortSignal;
 }
 export interface GeometryBatcher {
     /** Queues one message. Returns false after disposal. */
@@ -34,8 +36,8 @@ export declare function createPlacementMessagePublisher(address: GeometryAddress
 export declare function createSizeMessagePublisher(address: GeometryAddress, send: GeometrySend): (size: AdvertisedSize) => boolean;
 /**
  * Coalesces same-task messages without adding a rendering-frame delay. It owns
- * no authorization policy: callers must associate addresses with trusted IPC
- * senders before accepting a delivered batch.
+ * no authorization policy: callers must associate addresses with trusted
+ * sources before accepting a delivered batch.
  */
 export declare function createGeometryBatcher(send: GeometryBatchSend, 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;AACtE,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;CACnC;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,CAgKjB"}
+{"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"}

package/dist/protocol-publisher.js

@@ -1,3 +1,4 @@
+import { watchAbort } from './abort.js';
 import { GEOMETRY_PROTOCOL_VERSION, } from './protocol-types.js';
 /**
  * Wraps placement updates in a versioned protocol message. Sequence numbers
@@ -46,8 +47,8 @@ export function createSizeMessagePublisher(address, send) {
 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 IPC
- * senders before accepting a delivered batch.
+ * no authorization policy: callers must associate addresses with trusted
+ * sources before accepting a delivered batch.
  */
 export function createGeometryBatcher(send, options = {}) {
     const anchors = new Map();
@@ -55,6 +56,7 @@ export function createGeometryBatcher(send, options = {}) {
     let disposed = false;
     let scheduled = false;
     let flushing = false;
+    let removeAbortListener = () => { };
     // `activeOptions` lets a caller keep reporting to the options object that
     // was live when its flush() call started, even if a reentrant dispose()
     // during send() has since cleared the instance-level `options` reference.
@@ -144,6 +146,26 @@ export function createGeometryBatcher(send, options = {}) {
                 flush();
         });
     }
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        removeAbortListener();
+        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.
+        options = {};
+        send = NOOP_SEND;
+    };
+    if (options.signal?.aborted)
+        dispose();
+    else
+        removeAbortListener = watchAbort(options.signal, dispose);
     return {
         publish(message) {
             if (disposed)
@@ -191,17 +213,6 @@ export function createGeometryBatcher(send, options = {}) {
                 pendingAnchors.delete(state);
             anchors.delete(anchorId);
         },
-        dispose() {
-            disposed = true;
-            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.
-            options = {};
-            send = NOOP_SEND;
-        },
+        dispose,
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"size-advertiser.d.ts","sourceRoot":"","sources":["../src/size-advertiser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAOnB;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,qBAAqB,GAC1B,oBAAoB,CAoEtB"}
+{"version":3,"file":"size-advertiser.d.ts","sourceRoot":"","sources":["../src/size-advertiser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAQnB;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,qBAAqB,GAC1B,oBAAoB,CA8EtB"}