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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/view-anchor",
-  "version": "0.1.0-dev.20260618090552",
+  "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