@dimina-kit/view-anchor 0.1.0-dev.20260616102751 → 0.1.0-dev.20260624040247

package/README.md

@@ -66,22 +66,26 @@ handle.update(publish) // 换 publish（IPC 通道），并立即把当前尺寸
 handle.dispose()       // 停止观察；此后不再上报
 ```
 
-它从 `ResizeObserver` 的 border-box 取主导轴尺寸（不调 `getBoundingClientRect`、不强制 reflow），`Math.round` + 钳零，复用与正向同一套 RAF 合并 + 去重。宿主收到尺寸后调整占位、再由正向把视图贴上去——两个单向原语经占位 div 串成一座双向桥。**注意 footgun**：`target` 必须在主导轴上 shrink-to-fit（其尺寸不能被宿主灌入的视图尺寸反向决定），否则跨进程环不收敛。详见 [`docs/bidirectional-design.md`](./docs/bidirectional-design.md)。
+它从 `ResizeObserver` 的 border-box 取主导轴尺寸（不调 `getBoundingClientRect`、不强制 reflow），`Math.round` + 钳零，经反向专用的 RAF 合并 + 去重发出（正向同步、反向 RAF，刻意不对称）。宿主收到尺寸后调整占位、再由正向把视图贴上去——两个单向原语经占位 div 串成一座双向桥。**注意 footgun**：`target` 必须在主导轴上 shrink-to-fit（其尺寸不能被宿主灌入的视图尺寸反向决定），否则跨进程环不收敛。详见 [`docs/bidirectional-design.md`](./docs/bidirectional-design.md)。
 
 ## 文档
 
-- [`docs/mechanism.mdx`](./docs/mechanism.mdx) —— 正向完整机制：RAF 与陈旧帧安全性、`present` / 零矩形 / 卸载契约、React 18 StrictMode 生命周期。内嵌可交互 3D 演示 [`docs/anchor-3d.html`](./docs/anchor-3d.html)。
-- [`docs/bidirectional-design.md`](./docs/bidirectional-design.md) —— 双向化设计：共享 `createMeasureLoop` 核心、单轴所有权与收敛性、信任边界、以及两个原语如何「锚」到一起。
+- [`docs/mechanism.mdx`](./docs/mechanism.mdx) —— 正向完整机制：同步发布与陈旧帧安全性、`present` / 零矩形 / 卸载契约、React 18 StrictMode 生命周期。内嵌可交互 3D 演示 [`docs/anchor-3d.html`](./docs/anchor-3d.html)。
+- [`docs/bidirectional-design.md`](./docs/bidirectional-design.md) —— 双向几何桥：正向同步 / 反向 RAF 的刻意不对称、单轴所有权与收敛性、信任边界、以及两个原语如何「锚」到一起。
 
 ## API
 
 | 导出 | 类型 | 作用 |
 |---|---|---|
-| `createViewAnchor(target, opts)` | 函数 | 正向命令式核心，返回 `{ update, dispose }`。不依赖 React、不依赖 Electron。 |
-| `useViewAnchor(opts)` | Hook | 正向 React 适配层，返回一个挂到占位元素上的 ref 回调。 |
+| `createViewAnchor(target, opts)` | 函数 | 正向命令式核心，返回 `{ update, dispose }`。`present:false` 用零矩形 `{0,0,0,0}` 表示收起。不依赖 React、不依赖 Electron。 |
+| `createPlacementAnchor(target, opts)` | 函数 | 正向核心的显式 `Placement` 变体：可见性是判别式 `{ visible:true, bounds }` / `{ visible:false }`，绝不从零尺寸推断——真正 0×0 但在屏的视图与隐藏视图就此可区分。另支持 opt-in 的 `guardDisplayNone` / `followScroll` / `followGeometry`（按需开窗的 RAF 几何哨兵）+ `pulse()`。 |
+| `measurePlacement(target)` | 函数 | 纯测量：读 `target` 矩形，包成 `{ visible:true, bounds }`。 |
+| `useViewAnchor(opts)` | Hook | 正向 React 适配层（基于 `createViewAnchor`），返回一个挂到占位元素上的 ref 回调。 |
 | `createSizeAdvertiser(target, opts)` | 函数 | 反向命令式核心，返回 `{ update, dispose }`。下游量内容尺寸回流给宿主。 |
 | `Bounds` | 类型 | `{ x, y, width, height }`，单位为 CSS 像素。 |
-| `ViewAnchorOptions` / `ViewAnchorHandle` | 类型 | 正向核心的选项与句柄形状。 |
+| `Placement` | 类型 | `{ visible:true; bounds:Bounds } \| { visible:false }`，显式可见性判别式。 |
+| `ViewAnchorOptions` / `ViewAnchorHandle` | 类型 | 正向零矩形核心的选项与句柄形状。 |
+| `PlacementAnchorOptions` / `PlacementAnchorHandle` | 类型 | 正向 `Placement` 核心的选项与句柄形状。 |
 | `UseViewAnchorOptions` / `ViewAnchorRef` | 类型 | 正向适配层的选项与 ref 回调形状。 |
 | `AdvertisedAxis` / `AdvertisedSize` | 类型 | 反向的轴（`'block'\|'inline'`）与帧载荷 `{ axis, extent }`。 |
 | `SizeAdvertiserOptions` / `SizeAdvertiserHandle` | 类型 | 反向核心的选项与句柄形状。 |

package/dist/react.d.ts

@@ -23,7 +23,7 @@ export type ViewAnchorRef = (el: HTMLElement | null) => void;
  * detach (`null`) → publish ZERO then `dispose()`; on `opts`/`deps` change →
  * `update`; on unmount → publish ZERO then `dispose`.
  *
- * Why ZERO on disappearance (P1 fix): the anchor's follower is a *main-process*
+ * Why ZERO on disappearance: the anchor's follower is a *main-process*
  * `WebContentsView`, not a DOM node. When the anchored element vanishes, core
  * `dispose()` only stops observing — it deliberately never publishes again
  * (its Contract 6/7). But the host only collapses the native view when it

package/dist/react.js

@@ -6,7 +6,7 @@ import { createViewAnchor } from './view-anchor.js';
  * detach (`null`) → publish ZERO then `dispose()`; on `opts`/`deps` change →
  * `update`; on unmount → publish ZERO then `dispose`.
  *
- * Why ZERO on disappearance (P1 fix): the anchor's follower is a *main-process*
+ * Why ZERO on disappearance: the anchor's follower is a *main-process*
  * `WebContentsView`, not a DOM node. When the anchored element vanishes, core
  * `dispose()` only stops observing — it deliberately never publishes again
  * (its Contract 6/7). But the host only collapses the native view when it

package/dist/view-anchor.d.ts

@@ -50,7 +50,7 @@ export interface PlacementAnchorOptions {
      */
     guardDisplayNone?: boolean;
     /**
-     * Opt-in capture-phase ancestor-scroll follow (§2.C). When true, the anchor
+     * Opt-in capture-phase ancestor-scroll follow. When true, the anchor
      * listens for `scroll` on `window` in the CAPTURE phase (scroll events don't
      * bubble, but reach `window` while capturing), so an ancestor scroll
      * container scrolling the target re-measures and re-publishes. With
@@ -60,7 +60,7 @@ export interface PlacementAnchorOptions {
      */
     followScroll?: boolean;
     /**
-     * Opt-in windowed RAF geometry sentinel (§2.D/§6). Catches ancestor
+     * Opt-in windowed RAF geometry sentinel. Catches ancestor
      * transform / reflow moves that no DOM event reports. The sentinel is
      * NON-resident: it is OPENED on demand (a scroll burst, a `[role="separator"]`
      * splitter pointerdown, or an explicit `pulse()`), polls geometry once per

package/dist/view-anchor.js

@@ -173,7 +173,7 @@ export function createPlacementAnchor(target, opts) {
     let io = null;
     let lastPublished = null;
     let disposed = false;
-    // ── Windowed RAF geometry sentinel state (§2.D/§6) ──────────────────
+    // ── Windowed RAF geometry sentinel state ──────────────────
     // The sentinel is a windowed poll, opened on demand and auto-closing once
     // the geometry goes steady. It publishes IN-FRAME (no nested defer): each
     // frame measures, and either publishes a changed rect synchronously or
@@ -183,12 +183,12 @@ export function createPlacementAnchor(target, opts) {
     let steadyFrames = 0;
     const STEADY_CLOSE_FRAMES = 2;
     // True while a [role="separator"] splitter drag is in progress: set on the
-    // capture-phase pointerdown that opened the window, cleared on pointerup
-    // (§2.D). A held pointer means the drag may still resume after a static
-    // pause, so a steady run while held must NOT close the sentinel — it only
-    // closes once the pointer is released (松手后 2~3 帧内判静止→关窗). Without
-    // this gate a press that pauses a couple of frames before the drag actually
-    // moves would close mid-press and drop the entire subsequent drag.
+    // capture-phase pointerdown that opened the window, cleared on pointerup.
+    // A held pointer means the drag may still resume after a static pause, so a
+    // steady run while held must NOT close the sentinel — it only closes once the
+    // pointer is released. Without this gate a press that pauses a couple of
+    // frames before the drag actually moves would close mid-press and drop the
+    // entire subsequent drag.
     let pointerHeld = false;
     // Absolute time (performance.now()) past which a `pulse(durationMs)` window
     // force-closes even if the geometry is still changing — the upper bound that
@@ -227,7 +227,7 @@ export function createPlacementAnchor(target, opts) {
             sentinelDeadline = null;
             return;
         }
-        // §2.F upper bound: a pulse window past its deadline closes regardless of
+        // Upper bound: a pulse window past its deadline closes regardless of
         // motion, so a target that changes every frame can't keep the sentinel alive.
         if (sentinelDeadline !== null && performance.now() >= sentinelDeadline) {
             sentinelDeadline = null;
@@ -236,7 +236,7 @@ export function createPlacementAnchor(target, opts) {
         const p = computePlacement();
         if (lastPublished && samePlacement(lastPublished, p)) {
             steadyFrames++;
-            // Steady-close only fires once the pointer is RELEASED (§2.D): while a
+            // Steady-close only fires once the pointer is RELEASED: while a
             // splitter drag is held, a static pause is a hesitation, not the end of
             // the drag, so we keep polling (re-arm below) and let `steadyFrames`
             // accrue — it converges to a close within N frames after pointerup.
@@ -251,7 +251,7 @@ export function createPlacementAnchor(target, opts) {
             steadyFrames = 0;
         }
         // `publish` may have synchronously disposed (or hidden) the anchor; re-read
-        // live state so a re-entrant teardown leaves ZERO scheduled frames (B2).
+        // live state so a re-entrant teardown leaves ZERO scheduled frames.
         if (!disposed && visible) {
             rafId = requestAnimationFrame(sentinelFrame); // keep polling
         }
@@ -275,18 +275,18 @@ export function createPlacementAnchor(target, opts) {
         sentinelDeadline = null;
         pointerHeld = false;
     };
-    // §2.C — an ancestor scroll moved the target's screen rect. With the sentinel
-    // on, open the window so the whole scroll burst is followed frame-by-frame;
-    // without it, a single synchronous emit() follows the new rect (A1).
+    // An ancestor scroll moved the target's screen rect. With the sentinel on,
+    // open the window so the whole scroll burst is followed frame-by-frame;
+    // without it, a single synchronous emit() follows the new rect.
     const onScroll = () => {
         if (followGeometry)
             openSentinel();
         else
             emit();
     };
-    // §2.D — a capture-phase pointerdown on a [role="separator"] splitter handle
-    // marks the start of a drag that moves the target via ancestor reflow (no RO
-    // tick) → open the sentinel.
+    // A capture-phase pointerdown on a [role="separator"] splitter handle marks
+    // the start of a drag that moves the target via ancestor reflow (no RO tick)
+    // → open the sentinel.
     const onPointerDown = (e) => {
         const t = e.target;
         if (t && t.closest && t.closest('[role="separator"]')) {
@@ -294,7 +294,7 @@ export function createPlacementAnchor(target, opts) {
             openSentinel();
         }
     };
-    // §2.D — pointer released: the drag is over, so a steady run may now close the
+    // Pointer released: the drag is over, so a steady run may now close the
     // sentinel. Re-open it (a no-op if already polling) so the steady-close
     // threshold is reached even if the geometry was already static at release.
     const onPointerUp = () => {
@@ -378,7 +378,7 @@ export function createPlacementAnchor(target, opts) {
             stopObserving();
         },
         pulse(durationMs) {
-            // Imperative window open (§2.F): start the animation-follow window. It
+            // Imperative window open: start the animation-follow window. It
             // closes on steady (N=2 unchanged frames) OR, when `durationMs` is given,
             // at that deadline — whichever comes first. The deadline is the upper bound
             // that guarantees a still-animating target cannot keep the sentinel

package/docs/bidirectional-design.md

@@ -1,27 +1,21 @@
-# view-anchor 双向化重构设计（提案）
+# view-anchor 双向几何桥
 
-> 状态：契约草案，经四轮对抗评审收敛。本页只定契约，不含实现。
+view-anchor 是一座**双向几何桥**，引擎无关、传输注入：
 
-## 1. 目标
+- **正向** `createViewAnchor(target, { present, publish })` —— 宿主渲染进程量 DOM 占位矩形 → `publish(bounds)` → IPC → 主进程 `WebContentsView.setBounds`。
+- **反向** `createSizeAdvertiser(target, { axis, publish })` —— 下游 WebContentsView 自己的渲染进程量自身内容尺寸 → `publish(size)` → IPC → 宿主，宿主据此调整占位尺寸，再经正向把视图贴上去。
 
-把 view-anchor 从「单向锚定」重构成「**双向几何桥**」，且保持引擎无关、传输注入：
+适用场景：toolbar 这类「**交给下游控制**」的 WebContentsView，尺寸的事实来源在下游一侧（典型：宽由宿主主导、高由下游内容主导），占位映射是动态的。
 
-- **正向（已有）** `createViewAnchor(target, { present, publish })` —— 宿主渲染进程量 DOM 占位矩形 → `publish(bounds)` → IPC → 主进程 `WebContentsView.setBounds`。
-- **反向（新增）** `createSizeAdvertiser(target, { axis, publish })` —— 下游 WebContentsView 自己的渲染进程量自身内容尺寸 → `publish(size)` → IPC → 宿主，宿主据此调整占位尺寸，再经正向把视图贴上去。
+范围之外：不是同层渲染（合成器层面、另一套机制）；包里不提供 React 反向适配、不提供宿主决策 `decide`（见 §4/§7）。
 
-动机：workbench 的 toolbar 改成「**交给下游控制**」的 WebContentsView，尺寸的事实来源从宿主翻到了下游一侧（典型：宽宿主主导、高下游内容主导），占位映射变成动态的。
+## 2. 正反向不共享发射核心——两个方向最优时机不同
 
-非目标：不是同层渲染（合成器层面、另一套机制）；不在包里提供 React 反向适配、不在包里提供宿主决策 `decide`（见 §4/§7）。
+正反向的最优发射时机本就不同，所以它们**不共享发射核心**，采取**正向同步、反向 RAF** 的刻意不对称。
 
-## 2. 正反向**不共享发射核心**——两个方向最优时机不同
+**正向 `createViewAnchor` = 同步发布，不走 RAF。** 原生 overlay 的 `setBounds` 是跨进程、本就晚约 1 合成帧；RAF 再叠一帧 → 拖拽可见拖尾。所以正向在每个 `ResizeObserver` / window `resize` 触发里**同步**测量+发布，抗洪由 `lastPublished` 同值去重承担。撤销安全靠「每次发布开头同步读 `disposed`/`present`」——没有排队帧可跑赢状态变化。正向的 sink 是 IPC→主进程 `setBounds`，**不碰本渲染进程 DOM**，所以同步发布不会形成 RO 重入循环。
 
-> 设计初稿曾想抽一个共享 `createMeasureLoop` 给两个方向。落地时与 refactor-simulator
-> 的生产正向合并，发现这是**错的**：正反向的最优发射时机本就不同，强行共享会让核心
-> 长出 by-direction flag。最终采取**正向同步、反向 RAF** 的刻意不对称。
-
-**正向 `createViewAnchor` = 同步发布，不走 RAF。** 原生 overlay 的 `setBounds` 是跨进程、本就晚约 1 合成帧；RAF 再叠一帧 → 拖拽可见拖尾（refactor-simulator 生产验证过的修复）。所以正向在每个 `ResizeObserver` / window `resize` 触发里**同步**测量+发布，抗洪由 `lastPublished` 同值去重承担。撤销安全靠「每次发布开头同步读 `disposed`/`present`」——没有排队帧可跑赢状态变化。正向的 sink 是 IPC→主进程 `setBounds`，**不碰本渲染进程 DOM**，所以同步发布不会形成 RO 重入循环。
-
-**反向 `createSizeAdvertiser` = RAF 合并（内部 `createMeasureLoop`，反向专用）。** 反向是一条**跨进程反馈环**：advertise → 宿主 resize 这块视图 → 下游内容 remeasure → 再 advertise。RAF 的「每帧≤1 次发布」对这条环是合理的阻尼。`createMeasureLoop<T>` 只服务反向，通过注入 `produce`/`same`/`sink` 三元组把方向细节关在外层，核心零 flag：
+**反向 `createSizeAdvertiser` = RAF 合并（内部 `createMeasureLoop`，反向专用）。** 反向是一条**跨进程反馈环**：advertise → 宿主 resize 这块视图 → 下游内容 remeasure → 再 advertise。RAF 的「每帧≤1 次发布」对这条环是合理的阻尼。`createMeasureLoop<T>` 只服务反向（正向不用它），通过注入 `produce`/`same`/`sink` 三元组把方向细节关在外层，核心零 flag：
 
 ```ts
 function createMeasureLoop<T>(cfg: {
@@ -31,7 +25,7 @@ function createMeasureLoop<T>(cfg: {
 }): { schedule, emitNow, setActive, cancel, dispose }
 ```
 
-**为什么不对称是对的**：正向是单向跟随者，少一帧直接消除可见拖尾；反向是反馈环，多一帧阻尼更稳。把两者塞进一个核心要么逼出 `if(direction)` flag，要么把正向重新拖回 RAF（复活拖尾）。所以**正向内联同步、反向用 RAF 引擎**，各取所需。
+**为什么不对称是对的**：正向是单向跟随者，少一帧直接消除可见拖尾；反向是反馈环，多一帧阻尼更稳。把两者塞进一个核心要么逼出 `if(direction)` flag，要么把正向也拖进 RAF（带回拖尾）。所以**正向内联同步、反向用 RAF 引擎**，各取所需。
 
 ## 3. 反向原语契约
 
@@ -50,7 +44,7 @@ export interface SizeAdvertiserOptions {
 }
 
 export interface SizeAdvertiserHandle {
-  update(opts: SizeAdvertiserOptions): void  // 只能换 publish（换 IPC 通道）；axis 不可变
+  update(publish: (size: AdvertisedSize) => void): void  // 只能换 publish（换 IPC 通道）；axis 不可变
   dispose(): void                            // 停 observe、取消 RAF，此后永不再 publish
 }
 
@@ -84,7 +78,7 @@ export function createSizeAdvertiser(target: HTMLElement, opts: SizeAdvertiserOp
 | 白名单轴 | 宿主 | 用 payload 的 `axis` 常量比对，`axis !== expected` 则丢弃 |
 | 位置 / 另一轴 / z-order 锁定 | 宿主 | 下游无任何途径改变 → 杜绝全窗覆盖类点击劫持 |
 
-**target 选错（反馈环）的防护——克制为主，不过度防御。** 关键事实：违反单轴所有权时，RAF 合并把「死循环」**封顶为每帧一次**——它退化成可见的抖动 / 每帧一次冗余 IPC，而**不是冻死 UI**。既然不是灾难性故障，就不值得为它在每帧路径上堆检测器。最终只保留：
+**target 选错（反馈环）的防护——克制为主，不过度防御。** 关键事实：违反单轴所有权时，RAF 合并把「死循环」**封顶为每帧一次**——它退化成可见的抖动 / 每帧一次冗余 IPC，而**不是冻死 UI**。既然不是灾难性故障，就不在每帧路径上堆检测器。只保留：
 
 - **一条构造期廉价守卫**：`target` 是 `<body>`/`<html>` 时 `console.warn`——这是「stable-but-wrong」（占位永远撑成视图高、不缩到内容）最常见的成因，一次性、零每帧成本。
 - **其余靠文档**：JSDoc 与本节把「target 必须主导轴 shrink-to-fit、不被宿主灌入的尺寸反向决定」讲清。
@@ -137,15 +131,10 @@ export function createSizeAdvertiser(target: HTMLElement, opts: SizeAdvertiserOp
 
 ## 7. 与 Electron preferred-size 的关系（宿主侧可选数据源，非替代）
 
-宿主若在 Electron 且能接受零下游代码，可用 `enablePreferredSizeMode` + `preferred-size-changed` 作为反向「**源**」喂给同一个 `decide`，省掉下游注入。但它是 Electron 私有、且有两点待 spike 坐实：① 在 `WebContentsView` 上触发且上报值吸收 zoom；② `setBounds.height` 不回灌 layout（否则正反馈震荡）。
-
-view-anchor 的反向原语是**引擎无关/可移植**那条路（非 Electron / iframe 宿主、需选子 target 的场景）。两者并存：preferred-size 是 Electron 捷径，advertiser 是可移植机制，`decide` + §5 安全红线是二者共用的公共底座。这也是反向逻辑该留在 view-anchor、而非写死成 Electron 事件的理由。spike 结果只决定宿主选哪个**源**，不改变 view-anchor 要不要建反向原语。
-
-## 8. 包定位守恒（仍是一个原语，不是框架）
+宿主若在 Electron 且能接受零下游代码，可用 `enablePreferredSizeMode` + `preferred-size-changed` 作为反向「**源**」喂给同一个 `decide`，省掉下游注入。但它是 Electron 私有，且依赖两个前提：① 在 `WebContentsView` 上触发且上报值吸收 zoom；② `setBounds.height` 不回灌 layout（否则正反馈震荡）。
 
-双向化后 view-anchor 仍是「DOM 几何 ↔ 跨进程视图」的**单一职责双向桥**。守住四条即不滑向框架：① 导出面只多 `createSizeAdvertiser` + 其类型；② `createMeasureLoop` 不导出；③ 现在不做 React 反向适配（下游不保证是 React）；④ `decide` 留宿主、不进包。
+view-anchor 的反向原语是**引擎无关/可移植**那条路（非 Electron / iframe 宿主、需选子 target 的场景）。两者并存：preferred-size 是 Electron 捷径，advertiser 是可移植机制，`decide` + §5 安全红线是二者共用的公共底座。这也是反向逻辑留在 view-anchor、而非写死成 Electron 事件的理由——宿主选哪个**源**不改变反向原语本身。
 
-## 9. 已收敛 / 仍待拍板
+## 8. 包定位守恒（一个原语，不是框架）
 
-已由对抗评审定：payload 单标量 `{axis, extent}`（关闭「单标量 vs 可空双轴」）；命名 `createSizeAdvertiser`/`AdvertisedSize`/`publish`（关闭命名问题）；`present` 砍掉。
-仍待定：React 反向适配 `useSizeAdvertiser` 是否要做（默认否，等出现真实 React 下游）。
+view-anchor 是「DOM 几何 ↔ 跨进程视图」的**单一职责双向桥**。守住四条即不滑向框架：① 导出面只含 `createViewAnchor` / `createPlacementAnchor` / `createSizeAdvertiser` + 其类型；② `createMeasureLoop` 不导出；③ 不提供 React 反向适配（下游不保证是 React）；④ `decide` 留宿主、不进包。

package/docs/mechanism.mdx

@@ -61,6 +61,27 @@ const handle = createViewAnchor(target, {
 - **`{0,0,0,0}`（ZERO）** —— 收起信号。宿主把零面积读作「摘除子视图，但保留其 `WebContents` 存活」，即收起而非销毁，重新挂载瞬时且状态完整。
 - **dispose 后保持静默** —— 不补发零矩形。元素真正消失时，应由调用方先发 ZERO 再 dispose（适配层已替你处理）。
 
+## createPlacementAnchor(target, opts) — 显式可见性变体
+
+`createViewAnchor` 用零矩形 `{0,0,0,0}` 兼任「收起」信号，可见性是从几何推断的。`createPlacementAnchor` 把可见性提升为显式判别式，发的是 `Placement` 而非 `Bounds`：
+
+```ts
+const handle = createPlacementAnchor(target, {
+  visible: true,                 // 调用方意图：视图是否该在屏
+  publish: (placement) => { ... },
+})
+```
+
+| 状态 / 选项 | 行为 |
+|---|---|
+| `visible: true` | 发 `measurePlacement(target)`（`{ visible:true, bounds }`），并在每次 `ResizeObserver` / `resize` 触发**同步**重发。 |
+| `visible: false` | 发 `{ visible:false }`（**不是**零矩形），停止观察。 |
+| `guardDisplayNone`（默认 false） | 开启后，测出零面积的 target（display:none / 卸载 / 首帧未稳）发 `{ visible:false }` 而非 `{ visible:true, bounds:0×0 }`，并挂 `IntersectionObserver` 捕捉 `ResizeObserver` 不上报的 display:none 切换。 |
+| `followScroll`（默认 false） | 捕获阶段监听 `window` 的 `scroll`，祖先滚动容器滚动 target 时重测重发。 |
+| `followGeometry`（默认 false） | 按需开窗的 RAF 几何哨兵，捕捉无 DOM 事件上报的祖先 transform / reflow 位移；几何静止几帧后自动关窗，空闲时零成本。可由 `pulse(durationMs?)` 显式开窗。 |
+
+去重携带判别式（`samePlacement`），所以可见性翻转绝不会被同值合并掉——即使几何看上去一样。真正 0×0 但在屏的视图（`{ visible:true, bounds:{...,width:0} }`）与隐藏视图（`{ visible:false }`）由此可区分，而零矩形约定下二者会塌缩成同一个值。
+
 ## useViewAnchor(opts)
 
 React 适配层，返回一个挂到占位元素上的 ref 回调。
@@ -88,9 +109,11 @@ return <div ref={ref} />
 
 | 文件 | 作用 |
 |---|---|
-| `src/view-anchor.ts` | 命令式核心 `createViewAnchor`。无 React、无 Electron。 |
-| `src/react.ts` | React 适配层 `useViewAnchor`。 |
-| `src/types.ts` | `Bounds`、`ViewAnchorOptions`、`ViewAnchorHandle`。 |
+| `src/view-anchor.ts` | 正向命令式核心 `createViewAnchor` / `createPlacementAnchor` / `measurePlacement`。无 React、无 Electron。 |
+| `src/react.ts` | React 适配层 `useViewAnchor`（基于 `createViewAnchor`）。 |
+| `src/size-advertiser.ts` | 反向命令式核心 `createSizeAdvertiser`。 |
+| `src/measure-loop.ts` | 反向专用的 RAF 合并 / 去重 / dispose 引擎 `createMeasureLoop`（不导出）。 |
+| `src/types.ts` | `Bounds`、`Placement`、各核心的选项与句柄类型、反向的 `AdvertisedAxis` / `AdvertisedSize`。 |
 | `src/index.ts` | 对外公开面。 |
 
-正向运行时依赖只有 `react`（仅适配层）和浏览器 API（`ResizeObserver`、`getBoundingClientRect`、`window` 的 `resize` 监听）——**不含 `requestAnimationFrame`**（正向同步发布；RAF 只在反向 `createSizeAdvertiser` 用）。
+正向运行时依赖只有 `react`（仅适配层）和浏览器 API（`ResizeObserver`、`getBoundingClientRect`、`window` 的 `resize` 监听）。`requestAnimationFrame` 只在反向 `createSizeAdvertiser`（经 `createMeasureLoop`）和 `createPlacementAnchor` 的 opt-in `followGeometry` 哨兵里用；正向的 `createViewAnchor` 同步发布、不走 RAF。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/view-anchor",
-  "version": "0.1.0-dev.20260616102751",
+  "version": "0.1.0-dev.20260624040247",
   "description": "Engine-agnostic primitive that keeps a main-process native view (Electron WebContentsView) aligned to a DOM element's geometry.",
   "keywords": [
     "dimina",
@@ -52,6 +52,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^18.3.12",
     "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.4",
     "esbuild": "^0.28.0",
     "eslint": "^10.2.1",
     "jsdom": "^29.0.2",
@@ -71,6 +72,7 @@
     "check-types": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0",
     "test": "vitest run",
-    "test:dev": "vitest"
+    "test:dev": "vitest",
+    "test:coverage": "vitest run --coverage"
   }
 }

package/src/follow-geometry-press-drag.fix.test.ts

@@ -5,23 +5,20 @@ import type { Placement } from './types.js'
 // ── press-pause-drag: the windowed RAF geometry sentinel must NOT close
 //    while the pointer is still held down ───────────────────────────────
 //
-// TDD — FAILING-FIRST. Locks the press-pause-drag behaviour of the
-// `followGeometry` sentinel (view-anchor-following.md §2.D / §6).
+// Locks the press-pause-drag behaviour of the `followGeometry` sentinel.
 //
-// The contract (§2.D, line "一次 splitter 拖动 = 开窗→拖动中每帧跟随→
-// 松手后 2~3 帧内判静止→关窗") is explicit that the windowed sentinel only
-// closes on *steady* frames AFTER release (松手 = pointerup). The current
-// implementation instead closes after N consecutive identical frames
-// UNCONDITIONALLY — so a press that pauses before the drag actually starts
-// (very common: user clicks the splitter, hesitates a frame or two, THEN
-// drags) closes the window mid-press, and the entire subsequent drag is
-// dropped (the native view freezes at its pre-drag position).
+// The windowed sentinel only closes on *steady* frames AFTER release
+// (pointerup), NOT after N consecutive identical frames unconditionally — a
+// press that pauses before the drag actually starts (very common: user clicks
+// the splitter, hesitates a frame or two, THEN drags) must not close the
+// window mid-press and drop the entire subsequent drag (freezing the native
+// view at its pre-drag position).
 //
 // This file pins:
 //   1. press-pause-drag: pointerdown → ≥2 static frames (current close
 //      threshold) → rect starts moving → the movement is STILL followed.
-//      RED today because the sentinel closes after the static pause and the
-//      drag frames find no scheduled rAF.
+//      The pointerHeld gate keeps the sentinel open through the static pause
+//      so the later drag frames still find a scheduled rAF.
 //   2. no-regression: pointerup → static frames → the sentinel still
 //      eventually closes (we must not "fix" #1 by keeping the window open
 //      forever / spinning a rAF while idle).
@@ -124,7 +121,7 @@ function buildElement(rect: { x: number; y: number; w: number; h: number }): {
 }
 
 /** A `[role="separator"]` splitter (the drag handle): a capture-phase
- *  pointerdown matching it opens the sentinel window (§2.D). */
+ *  pointerdown matching it opens the sentinel window. */
 function buildSplitter(): HTMLElement {
   const sep = document.createElement('div')
   sep.setAttribute('role', 'separator')

package/src/placement.test.ts

@@ -1,37 +1,35 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 
 // ─────────────────────────────────────────────────────────────────────
-// TDD — FAILING tests for the *not-yet-implemented* explicit `Placement`
-// API. The current package encodes "hidden" as the magic geometric value
-// `{x:0,y:0,width:0,height:0}` (the `present:false → ZERO bounds`
-// convention in types.ts/view-anchor.ts). That leaks a compositor/host
-// concept ("detach the view") into the geometry layer, and is ambiguous:
-// a view that is genuinely 0-wide is indistinguishable from a hidden one.
+// Tests for the explicit `Placement` API, the alternative to encoding
+// "hidden" as the magic geometric value `{x:0,y:0,width:0,height:0}` (the
+// `present:false → ZERO bounds` convention in types.ts/view-anchor.ts). That
+// ZERO convention leaks a compositor/host concept ("detach the view") into the
+// geometry layer, and is ambiguous: a view that is genuinely 0-wide is
+// indistinguishable from a hidden one.
 //
-// This file pins the REPLACEMENT contract:
+// The replacement contract:
 //
 //   type Placement =
 //     | { visible: true; bounds: Bounds }
 //     | { visible: false }
 //
 // measure produces a `Placement`; the sink consumes a `Placement`.
-// Visibility is EXPLICIT (a discriminant), never inferred from a 0.
+// Visibility is EXPLICIT (a discriminant), never inferred from a 0. The
+// explicit API NEVER reintroduces a ZERO-bounds path for "hidden".
 //
-// These tests must be RED today: the symbols they import/exercise
-// (`measurePlacement`, `createPlacementAnchor`, the `Placement` type) do
-// not exist yet. We import them dynamically so the failure surfaces as a
-// runtime/assertion failure (a missing export is `undefined`, and calling
-// it throws) rather than a whole-file compile error that vitest would skip.
-// The implementer makes them GREEN by adding the explicit API — WITHOUT
-// reintroducing any ZERO-bounds path for "hidden".
+// The symbols (`measurePlacement`, `createPlacementAnchor`, `Placement`) are
+// imported dynamically so a missing export surfaces as a runtime/assertion
+// failure (an `undefined` that throws when called) rather than a whole-file
+// compile error that vitest would skip.
 // ─────────────────────────────────────────────────────────────────────
 
 import type { Bounds } from './types.js'
 
-// The explicit API is imported through this indirection so that a not-yet-
-// existing export is observable as `undefined` at runtime (→ a failing
-// assertion / TypeError), not a static "module has no exported member"
-// compile error that would prevent the whole suite from running.
+// The explicit API is imported through this indirection so that a missing
+// export is observable as `undefined` at runtime (→ a failing assertion /
+// TypeError), not a static "module has no exported member" compile error that
+// would prevent the whole suite from running.
 import * as viewAnchorModule from './view-anchor.js'
 
 // The shape the explicit API must produce/consume. Mirrored locally (not
@@ -128,11 +126,10 @@ function buildElement(rect: {
   }
 }
 
-// ── Resolve the (not-yet-existing) explicit API at call time ─────────
+// ── Resolve the explicit API at call time ─────────
 //
-// Each returns `undefined` until the implementer adds the export. The
-// tests below call them, so an absent export throws ("not a function") —
-// a RED behavioural failure, which is what TDD wants here.
+// Each helper asserts the export is a function before calling it, so an absent
+// export surfaces as a clear assertion failure rather than a TypeError.
 
 interface MaybeModule {
   // measurePlacement(target): Placement — pure measure, no IPC.
@@ -154,7 +151,7 @@ function measurePlacement(target: HTMLElement): ExpectedPlacement {
   const fn = mod.measurePlacement
   expect(
     typeof fn,
-    'explicit API `measurePlacement` is not implemented yet (expected a function export from view-anchor)',
+    'explicit API `measurePlacement` must be a function export from view-anchor',
   ).toBe('function')
   return fn!(target)
 }
@@ -169,7 +166,7 @@ function createPlacementAnchor(
   const fn = mod.createPlacementAnchor
   expect(
     typeof fn,
-    'explicit API `createPlacementAnchor` is not implemented yet (expected a function export from view-anchor)',
+    'explicit API `createPlacementAnchor` must be a function export from view-anchor',
   ).toBe('function')
   return fn!(target, opts)
 }

package/src/react.test.tsx

@@ -160,10 +160,10 @@ describe('useViewAnchor — ref attach', () => {
 // the leaf div conditionally rendered), failing to dispose leaks the RO
 // and keeps publishing against a detached element.
 //
-// P1 fix: this contract ALSO requires emitting one ZERO on detach. The
-// anchor's follower is a main-process WebContentsView; the host only
-// collapses it on `{0,0,0,0}`. Without a ZERO the native view stays frozen
-// at its last bounds and occludes content. See `react.ts`.
+// This contract ALSO requires emitting one ZERO on detach. The anchor's
+// follower is a main-process WebContentsView; the host only collapses it on
+// `{0,0,0,0}`. Without a ZERO the native view stays frozen at its last bounds
+// and occludes content. See `react.ts`.
 
 describe('useViewAnchor — ref null disposes', () => {
   it('detaching the DOM node publishes ZERO once, disconnects the observer, and stops publishing', () => {
@@ -195,11 +195,9 @@ describe('useViewAnchor — ref null disposes', () => {
     })
     expect(ro.disconnected).toBe(true)
 
-    // NOTE: this assertion previously encoded the P1 bug — it asserted
-    // `expect(publish).not.toHaveBeenCalled()`, i.e. detach published nothing,
-    // which left the native WebContentsView stranded at its old bounds. The
-    // correct behaviour is: a vanished anchor MUST publish exactly one ZERO so
-    // the host collapses the native view.
+    // A vanished anchor MUST publish exactly one ZERO so the host collapses the
+    // native view — detach publishing nothing would strand the native
+    // WebContentsView at its old bounds.
     expect(publish).toHaveBeenCalledTimes(1)
     expect(publish).toHaveBeenCalledWith({ x: 0, y: 0, width: 0, height: 0 })
     publish.mockClear()
@@ -296,9 +294,9 @@ describe('useViewAnchor — opts/deps change re-publishes', () => {
 // Bug it catches: a hook that does not dispose on unmount leaks the RO and
 // can throw when a queued RAF fires against a torn-down IPC channel.
 //
-// P1 fix: unmount must ALSO collapse the native view with one ZERO (same
-// reasoning as Contract 9 — the follower is a main-process WebContentsView
-// the host only collapses on `{0,0,0,0}`).
+// Unmount must ALSO collapse the native view with one ZERO (same reasoning as
+// Contract 9 — the follower is a main-process WebContentsView the host only
+// collapses on `{0,0,0,0}`).
 
 describe('useViewAnchor — unmount disposes', () => {
   it('unmounting the component publishes ZERO once, disconnects the observer, and never publishes after', () => {
@@ -318,10 +316,8 @@ describe('useViewAnchor — unmount disposes', () => {
 
     expect(ro.disconnected).toBe(true)
 
-    // NOTE: this assertion previously encoded the P1 bug — it asserted
-    // `expect(publish).not.toHaveBeenCalled()` after unmount, leaving the
-    // native view stranded. Correct behaviour: unmount publishes exactly one
-    // ZERO to collapse the native view.
+    // Unmount publishes exactly one ZERO to collapse the native view —
+    // publishing nothing would leave the native view stranded.
     expect(publish).toHaveBeenCalledTimes(1)
     expect(publish).toHaveBeenCalledWith({ x: 0, y: 0, width: 0, height: 0 })
     publish.mockClear()
@@ -380,7 +376,7 @@ describe('useViewAnchor — independent instances', () => {
   })
 })
 
-// ── Remount with present transition (codex regression) ──────────────
+// ── Remount with present transition ──────────────
 // Production coupling: the debug cell is *unmounted* when hidden and *remounted*
 // when shown, so the element's mount/unmount and `options.present` flip together
 // (present=false ⟺ unmounted, present=true ⟺ mounted). On "show", React commits

package/src/react.ts

@@ -28,7 +28,7 @@ export type ViewAnchorRef = (el: HTMLElement | null) => void
  * detach (`null`) → publish ZERO then `dispose()`; on `opts`/`deps` change →
  * `update`; on unmount → publish ZERO then `dispose`.
  *
- * Why ZERO on disappearance (P1 fix): the anchor's follower is a *main-process*
+ * Why ZERO on disappearance: the anchor's follower is a *main-process*
  * `WebContentsView`, not a DOM node. When the anchored element vanishes, core
  * `dispose()` only stops observing — it deliberately never publishes again
  * (its Contract 6/7). But the host only collapses the native view when it

package/src/view-anchor.test.ts

@@ -499,12 +499,12 @@ void _boundsShape
 
 // ── display:none / first-frame guard (opt-in) ───────────────────────
 //
-// TDD — FAILING-FIRST tests for an ADDITIVE, OPT-IN hardening of
-// `createPlacementAnchor`, gated behind a new `guardDisplayNone?: boolean`
-// option (default false = today's behaviour, unchanged).
+// An ADDITIVE, OPT-IN hardening of `createPlacementAnchor`, gated behind the
+// `guardDisplayNone?: boolean` option (default false = the unguarded
+// behaviour).
 //
-// Two new behaviours, ONLY when `guardDisplayNone: true`:
-//   §4 First-frame guard — `visible:true` but the measured rect has
+// Two behaviours, ONLY when `guardDisplayNone: true`:
+//   First-frame guard — `visible:true` but the measured rect has
 //      `width === 0 || height === 0` (no geometry box: unmounted /
 //      display:none / unstable first layout) → publish `{ visible:false }`
 //      (a detach, NO bounds) instead of `{ visible:true, bounds:{...,0,0} }`.
@@ -512,27 +512,22 @@ void _boundsShape
 //      the native view flashing at (0,0). NOTE: only ZERO WIDTH OR HEIGHT
 //      triggers this — a NON-zero box at position (0,0) is still a normal
 //      `{ visible:true }`.
-//   §3/§2.E display:none guard — the anchor attaches an
-//      `IntersectionObserver` on the target. When the target goes
-//      display:none (IO reports `isIntersecting:false` with a zero-area
-//      `boundingClientRect`) → publish `{ visible:false }`. When it comes
-//      back with a non-zero box (IO intersecting again / a subsequent
-//      measure yields non-zero width&height) → re-measure → publish
-//      `{ visible:true, bounds }`.
+//   display:none guard — the anchor attaches an `IntersectionObserver` on the
+//      target. When the target goes display:none (IO reports
+//      `isIntersecting:false` with a zero-area `boundingClientRect`) → publish
+//      `{ visible:false }`. When it comes back with a non-zero box (IO
+//      intersecting again / a subsequent measure yields non-zero
+//      width&height) → re-measure → publish `{ visible:true, bounds }`.
 //
-// Caller intent still wins (§3.1): a caller-`visible:false` anchor is
-// detached regardless — the guard NEVER flips a caller's `visible:false`
-// to true, and NEVER detaches purely because a NON-zero box scrolled
-// off-screen (a non-zero box at a negative/off-screen origin stays
-// `visible:true` with its real, possibly negative-origin, bounds).
+// Caller intent still wins: a caller-`visible:false` anchor is detached
+// regardless — the guard NEVER flips a caller's `visible:false` to true, and
+// NEVER detaches purely because a NON-zero box scrolled off-screen (a non-zero
+// box at a negative/off-screen origin stays `visible:true` with its real,
+// possibly negative-origin, bounds).
 //
-// This increment adds an IntersectionObserver, NOT a RAF — so the existing
-// "never schedules a requestAnimationFrame" guard must stay valid. We assert
-// it here too (`rafSpy`/`cancelSpy` from the shared harness).
-//
-// These tests must be RED today: `guardDisplayNone` is not implemented, so
-// no IntersectionObserver is wired and a 0×0 visible measure still publishes
-// `{ visible:true, bounds:0×0 }`.
+// This guard adds an IntersectionObserver, NOT a RAF — so the existing
+// "never schedules a requestAnimationFrame" guard stays valid. We assert it
+// here too (`rafSpy`/`cancelSpy` from the shared harness).
 
 // A controllable fake IntersectionObserver (jsdom has none). Mirrors the
 // FakeResizeObserver style: records observed elements + disconnect, captures
@@ -762,33 +757,26 @@ describe('createPlacementAnchor — display:none / first-frame guard (opt-in)',
   })
 })
 
-// ── scroll + windowed RAF geometry sentinel (opt-in, increment 2) ────
+// ── scroll + windowed RAF geometry sentinel (opt-in) ────
 //
-// TDD — FAILING-FIRST tests for ADDITIVE, OPT-IN follow options on
-// `createPlacementAnchor`, derived from view-anchor-following.md
-// §2.C / §2.D / §2.F / §6 / §7. Both default OFF (= today's behaviour).
+// ADDITIVE, OPT-IN follow options on `createPlacementAnchor`. Both default
+// OFF (= the unfollowed behaviour).
 //
-//   followScroll?: boolean   — §2.C ancestor-scroll capture listener.
-//   followGeometry?: boolean — §2.D windowed RAF geometry sentinel.
-//   pulse(durationMs?)       — §2.F imperative "open the sentinel window".
+//   followScroll?: boolean   — ancestor-scroll capture listener.
+//   followGeometry?: boolean — windowed RAF geometry sentinel.
+//   pulse(durationMs?)       — imperative "open the sentinel window".
 //
 // ────────────────────────────────────────────────────────────────────
-// GOALPOST NOTE (§7): the package-wide "never RAF" invariant is
-// INTENTIONALLY NARROWED by `followGeometry` (opt-in) to "EVENT-driven
-// publishes (ResizeObserver / window resize / scroll) are never
-// RAF-deferred". The sentinel rAF is a POLLING mechanism that publishes
-// SYNCHRONOUSLY within its own frame — it is NOT a deferral of an
-// event-driven publish (see view-anchor-following.md §7). The existing
-// `createViewAnchor` "never schedules a requestAnimationFrame" test
-// (above) REMAINS VALID and is left UNCHANGED, because `followGeometry`
-// defaults off and the forward `createViewAnchor` core never opts in. The
-// tests below re-pin that the DEFAULT / event-driven paths still schedule
-// NO rAF, so the original guarantee holds wherever the sentinel is off.
+// The package-wide "never RAF" invariant is INTENTIONALLY NARROWED by
+// `followGeometry` (opt-in) to "EVENT-driven publishes (ResizeObserver /
+// window resize / scroll) are never RAF-deferred". The sentinel rAF is a
+// POLLING mechanism that publishes SYNCHRONOUSLY within its own frame — it is
+// NOT a deferral of an event-driven publish. The `createViewAnchor` "never
+// schedules a requestAnimationFrame" test (above) stays valid, because
+// `followGeometry` defaults off and the forward `createViewAnchor` core never
+// opts in. The tests below re-pin that the DEFAULT / event-driven paths still
+// schedule NO rAF, so the guarantee holds wherever the sentinel is off.
 // ────────────────────────────────────────────────────────────────────
-//
-// These tests must be RED today: `followScroll` / `followGeometry` /
-// `pulse` are unimplemented, so no capture scroll listener / pointerdown
-// listener / RAF sentinel exists.
 
 // A CONTROLLABLE fake requestAnimationFrame. The shared `rafSpy` only
 // returns 0 and stores nothing (it's a regression guard, not a driver), so
@@ -842,7 +830,7 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
 
   /** Build a `[role="separator"]` splitter element (the drag handle). A
    *  capture-phase pointerdown whose target matches `[role="separator"]`
-   *  opens the sentinel window (§2.D). */
+   *  opens the sentinel window. */
   function buildSplitter(): HTMLElement {
     const sep = document.createElement('div')
     sep.setAttribute('role', 'separator')
@@ -851,7 +839,7 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
   }
 
   /** Dispatch a capture-phase scroll on window (an ancestor scroll container
-   *  scrolling — §2.C: scroll doesn't bubble, but reaches window in capture). */
+   *  scrolling — scroll doesn't bubble, but reaches window in capture). */
   function dispatchCaptureScroll(): void {
     window.dispatchEvent(new Event('scroll'))
   }
@@ -864,8 +852,8 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
   }
 
   /** Pointer release — ends a splitter drag so the sentinel may steady-close
-   *  (§2.D: 关窗只发生在松手之后). Dispatched bubbling from the target and on
-   *  window directly so a capture/bubble window listener sees it. */
+   *  (close only happens after release). Dispatched bubbling from the target
+   *  and on window directly so a capture/bubble window listener sees it. */
   function dispatchPointerup(target: HTMLElement): void {
     target.dispatchEvent(new Event('pointerup', { bubbles: true }))
     window.dispatchEvent(new Event('pointerup'))
@@ -888,12 +876,11 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
   ): PulseHandle =>
     createPlacementAnchor(el, o as FollowOpts) as PulseHandle
 
-  // ── A. followScroll — capture-phase ancestor scroll (§2.C) ──────────
+  // ── A. followScroll — capture-phase ancestor scroll ──────────
 
   // A1: capture scroll re-publishes the freshly-measured rect (basic scroll
-  //     follow works WITHOUT the geometry sentinel — §2.C: "if followGeometry
-  //     is false, the scroll callback should still at least do a synchronous
-  //     emit()").
+  //     follow works WITHOUT the geometry sentinel — with followGeometry off,
+  //     the scroll callback still does a single synchronous emit()).
   it('A1) followScroll (followGeometry off): a capture-phase scroll re-publishes the new measured rect synchronously', () => {
     const publish = vi.fn<(p: Placement) => void>()
     const { el, setRect } = buildElement({ x: 0, y: 0, w: 100, h: 100 })
@@ -960,8 +947,8 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
     removeSpy.mockRestore()
   })
 
-  // A3: §2.C — a followScroll capture-scroll OPENS the RAF sentinel window
-  //     when followGeometry is ALSO on (so it follows every frame of a scroll
+  // A3: a followScroll capture-scroll OPENS the RAF sentinel window when
+  //     followGeometry is ALSO on (so it follows every frame of a scroll
   //     burst, not just the one synchronous emit).
   it('A3) followScroll + followGeometry: a capture scroll opens the RAF sentinel (a frame becomes scheduled)', () => {
     const publish = vi.fn<(p: Placement) => void>()
@@ -982,9 +969,9 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
     expect(raf.pending).toBeGreaterThanOrEqual(1)
   })
 
-  // ── B. followGeometry — windowed RAF geometry sentinel (§2.D/§6) ─────
+  // ── B. followGeometry — windowed RAF geometry sentinel ─────
 
-  // B-idle: §6 — IDLE (no scroll / pointerdown / pulse) schedules NO rAF.
+  // B-idle: IDLE (no scroll / pointerdown / pulse) schedules NO rAF.
   //   The sentinel is windowed: static cost is exactly zero.
   it('B-idle) followGeometry on but idle: NO rAF is ever scheduled (windowed = zero static cost)', () => {
     const publish = vi.fn<(p: Placement) => void>()
@@ -1064,10 +1051,10 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
   })
 
   // B-close: after the pointer is RELEASED, N=2 consecutive UNCHANGED frames
-  //   cancel the rAF (steady = stop) — no further frame scheduled. (§2.D: a
-  //   steady run while the pointer is still HELD is a mid-drag pause and must
-  //   NOT close — see follow-geometry-press-drag.fix.test.ts; close is gated on
-  //   pointerup, so this test now releases before going steady.)
+  //   cancel the rAF (steady = stop) — no further frame scheduled. A steady run
+  //   while the pointer is still HELD is a mid-drag pause and must NOT close
+  //   (see follow-geometry-press-drag.fix.test.ts); close is gated on pointerup,
+  //   so this test releases before going steady.
   it('B-close) pointerup then N=2 consecutive unchanged frames → sentinel stops (cancelAnimationFrame / no further frame scheduled)', () => {
     const publish = vi.fn<(p: Placement) => void>()
     const { el, setRect } = buildElement({ x: 0, y: 0, w: 100, h: 100 })
@@ -1095,7 +1082,7 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
     expect(raf.request.mock.calls.length).toBe(requestsBefore)
   })
 
-  // ── F. pulse() — explicit window open (§2.F) ────────────────────────
+  // ── F. pulse() — explicit window open ────────────────────────
 
   // F-open: pulse() opens the sentinel and it follows subsequent rect changes.
   it('F-open) pulse() opens the sentinel; it follows rect changes on subsequent frames', () => {
@@ -1137,13 +1124,13 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
     expect(raf.request.mock.calls.length).toBe(requestsBefore)
   })
 
-  // ── §7 goalpost: event-driven publishes stay SYNCHRONOUS even with the
-  //    sentinel enabled; the sentinel rAF publishes in-frame, not deferred. ──
+  // ── Event-driven publishes stay SYNCHRONOUS even with the sentinel enabled;
+  //    the sentinel rAF publishes in-frame, not deferred. ──
 
   // B-sync: a ResizeObserver tick still publishes SYNCHRONOUSLY (in the event
   //   stack) WITHOUT scheduling a rAF, even with followGeometry enabled. This
-  //   is the §7 narrowing made concrete: event-driven ≠ RAF-deferred.
-  it('§7) with followGeometry ENABLED, a ResizeObserver tick publishes synchronously and schedules NO rAF', () => {
+  //   is the narrowing made concrete: event-driven ≠ RAF-deferred.
+  it('with followGeometry ENABLED, a ResizeObserver tick publishes synchronously and schedules NO rAF', () => {
     const publish = vi.fn<(p: Placement) => void>()
     const { el, setRect } = buildElement({ x: 0, y: 0, w: 100, h: 100 })
     mk(el, { visible: true, followGeometry: true, publish })
@@ -1158,7 +1145,7 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
       visible: true,
       bounds: { x: 3, y: 4, width: 100, height: 100 },
     })
-    // …and the event-driven path did NOT route through a rAF (the §7 invariant
+    // …and the event-driven path did NOT route through a rAF (the invariant
     // survives, narrowed: event-driven publishes are never RAF-deferred).
     expect(raf.request).not.toHaveBeenCalled()
   })
@@ -1166,7 +1153,7 @@ describe('createPlacementAnchor — scroll + windowed RAF geometry sentinel (opt
   // Default-path "still no rAF": with followGeometry OFF / unset, NOTHING in
   //   the increment-2 surface schedules a rAF — the original package-wide
   //   "never RAF" guarantee holds for the default + event-driven paths.
-  it('§7-default) followGeometry OFF (default): RO + resize + scroll-less lifecycle schedules NO rAF', () => {
+  it('followGeometry OFF (default): RO + resize + scroll-less lifecycle schedules NO rAF', () => {
     const publish = vi.fn<(p: Placement) => void>()
     const { el, setRect } = buildElement({ x: 0, y: 0, w: 100, h: 100 })
     const handle = mk(el, { visible: true, publish }) // followGeometry unset

package/src/view-anchor.ts

@@ -166,7 +166,7 @@ export interface PlacementAnchorOptions {
    */
   guardDisplayNone?: boolean
   /**
-   * Opt-in capture-phase ancestor-scroll follow (§2.C). When true, the anchor
+   * Opt-in capture-phase ancestor-scroll follow. When true, the anchor
    * listens for `scroll` on `window` in the CAPTURE phase (scroll events don't
    * bubble, but reach `window` while capturing), so an ancestor scroll
    * container scrolling the target re-measures and re-publishes. With
@@ -176,7 +176,7 @@ export interface PlacementAnchorOptions {
    */
   followScroll?: boolean
   /**
-   * Opt-in windowed RAF geometry sentinel (§2.D/§6). Catches ancestor
+   * Opt-in windowed RAF geometry sentinel. Catches ancestor
    * transform / reflow moves that no DOM event reports. The sentinel is
    * NON-resident: it is OPENED on demand (a scroll burst, a `[role="separator"]`
    * splitter pointerdown, or an explicit `pulse()`), polls geometry once per
@@ -262,7 +262,7 @@ export function createPlacementAnchor(
   let lastPublished: Placement | null = null
   let disposed = false
 
-  // ── Windowed RAF geometry sentinel state (§2.D/§6) ──────────────────
+  // ── Windowed RAF geometry sentinel state ──────────────────
   // The sentinel is a windowed poll, opened on demand and auto-closing once
   // the geometry goes steady. It publishes IN-FRAME (no nested defer): each
   // frame measures, and either publishes a changed rect synchronously or
@@ -272,12 +272,12 @@ export function createPlacementAnchor(
   let steadyFrames = 0
   const STEADY_CLOSE_FRAMES = 2
   // True while a [role="separator"] splitter drag is in progress: set on the
-  // capture-phase pointerdown that opened the window, cleared on pointerup
-  // (§2.D). A held pointer means the drag may still resume after a static
-  // pause, so a steady run while held must NOT close the sentinel — it only
-  // closes once the pointer is released (松手后 2~3 帧内判静止→关窗). Without
-  // this gate a press that pauses a couple of frames before the drag actually
-  // moves would close mid-press and drop the entire subsequent drag.
+  // capture-phase pointerdown that opened the window, cleared on pointerup.
+  // A held pointer means the drag may still resume after a static pause, so a
+  // steady run while held must NOT close the sentinel — it only closes once the
+  // pointer is released. Without this gate a press that pauses a couple of
+  // frames before the drag actually moves would close mid-press and drop the
+  // entire subsequent drag.
   let pointerHeld = false
   // Absolute time (performance.now()) past which a `pulse(durationMs)` window
   // force-closes even if the geometry is still changing — the upper bound that
@@ -319,7 +319,7 @@ export function createPlacementAnchor(
       sentinelDeadline = null
       return
     }
-    // §2.F upper bound: a pulse window past its deadline closes regardless of
+    // Upper bound: a pulse window past its deadline closes regardless of
     // motion, so a target that changes every frame can't keep the sentinel alive.
     if (sentinelDeadline !== null && performance.now() >= sentinelDeadline) {
       sentinelDeadline = null
@@ -328,7 +328,7 @@ export function createPlacementAnchor(
     const p = computePlacement()
     if (lastPublished && samePlacement(lastPublished, p)) {
       steadyFrames++
-      // Steady-close only fires once the pointer is RELEASED (§2.D): while a
+      // Steady-close only fires once the pointer is RELEASED: while a
       // splitter drag is held, a static pause is a hesitation, not the end of
       // the drag, so we keep polling (re-arm below) and let `steadyFrames`
       // accrue — it converges to a close within N frames after pointerup.
@@ -342,7 +342,7 @@ export function createPlacementAnchor(
       steadyFrames = 0
     }
     // `publish` may have synchronously disposed (or hidden) the anchor; re-read
-    // live state so a re-entrant teardown leaves ZERO scheduled frames (B2).
+    // live state so a re-entrant teardown leaves ZERO scheduled frames.
     if (!disposed && visible) {
       rafId = requestAnimationFrame(sentinelFrame) // keep polling
     } else {
@@ -366,17 +366,17 @@ export function createPlacementAnchor(
     pointerHeld = false
   }
 
-  // §2.C — an ancestor scroll moved the target's screen rect. With the sentinel
-  // on, open the window so the whole scroll burst is followed frame-by-frame;
-  // without it, a single synchronous emit() follows the new rect (A1).
+  // An ancestor scroll moved the target's screen rect. With the sentinel on,
+  // open the window so the whole scroll burst is followed frame-by-frame;
+  // without it, a single synchronous emit() follows the new rect.
   const onScroll = (): void => {
     if (followGeometry) openSentinel()
     else emit()
   }
 
-  // §2.D — a capture-phase pointerdown on a [role="separator"] splitter handle
-  // marks the start of a drag that moves the target via ancestor reflow (no RO
-  // tick) → open the sentinel.
+  // A capture-phase pointerdown on a [role="separator"] splitter handle marks
+  // the start of a drag that moves the target via ancestor reflow (no RO tick)
+  // → open the sentinel.
   const onPointerDown = (e: Event): void => {
     const t = e.target as Element | null
     if (t && t.closest && t.closest('[role="separator"]')) {
@@ -385,7 +385,7 @@ export function createPlacementAnchor(
     }
   }
 
-  // §2.D — pointer released: the drag is over, so a steady run may now close the
+  // Pointer released: the drag is over, so a steady run may now close the
   // sentinel. Re-open it (a no-op if already polling) so the steady-close
   // threshold is reached even if the geometry was already static at release.
   const onPointerUp = (): void => {
@@ -469,7 +469,7 @@ export function createPlacementAnchor(
       stopObserving()
     },
     pulse(durationMs?: number): void {
-      // Imperative window open (§2.F): start the animation-follow window. It
+      // Imperative window open: start the animation-follow window. It
       // closes on steady (N=2 unchanged frames) OR, when `durationMs` is given,
       // at that deadline — whichever comes first. The deadline is the upper bound
       // that guarantees a still-animating target cannot keep the sentinel