view-anchor 0.2.1 → 0.2.2

package/dist/react.js

@@ -8,14 +8,11 @@ function useAnchorRef(options, applied, adapter) {
     const handleRef = useRef(null);
     const elementRef = useRef(null);
     const optionsRef = useRef(options);
-    // eslint-disable-next-line react-hooks/refs
     optionsRef.current = options;
     const adapterRef = useRef(adapter);
-    // eslint-disable-next-line react-hooks/refs
     adapterRef.current = adapter;
     const appliedRef = useRef(applied);
     const currentAppliedRef = useRef(applied);
-    // eslint-disable-next-line react-hooks/refs
     currentAppliedRef.current = applied;
     // Options handed to the adapter on the last create/update call.
     // Tracks applied state across renders where the deps array reference changes.
@@ -73,7 +70,6 @@ function useAnchorRef(options, applied, adapter) {
             return () => deferDetach(element);
         }
         return undefined;
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- helpers only read stable refs
     }, []);
     useEffect(() => {
         const previous = appliedRef.current;
@@ -87,7 +83,7 @@ function useAnchorRef(options, applied, adapter) {
             adapterRef.current.update(handle, optionsRef.current);
             lastAppliedOptionsRef.current = optionsRef.current;
         }
-        // eslint-disable-next-line react-hooks/exhaustive-deps
+        // oxlint-disable-next-line react/exhaustive-deps
     }, applied);
     useEffect(() => {
         cancelPendingDetach();
@@ -96,7 +92,6 @@ function useAnchorRef(options, applied, adapter) {
             if (element)
                 deferDetach(element);
         };
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- helpers only read stable refs
     }, []);
     return ref;
 }

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

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

package/dist/size-advertiser.js

@@ -1,3 +1,4 @@
+import { watchAbort } from './abort.js';
 import { createMeasureLoop } from './measure-loop.js';
 // Replaces a disposed instance's publish callback so a retained handle does
 // not keep the caller's original callback (and whatever it captured) alive.
@@ -53,9 +54,30 @@ export function createSizeAdvertiser(target, opts) {
             `${axis} size is the view size, not content size. The advertiser will ` +
             `never shrink to content; measure a shrink-to-fit wrapper instead.`);
     }
-    loop.setActive(true);
-    observer = new ResizeObserver(onResize);
-    observer.observe(target);
+    let removeAbortListener = () => { };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        removeAbortListener();
+        removeAbortListener = () => { };
+        loop.cancel();
+        if (observer) {
+            observer.disconnect();
+            observer = null;
+        }
+        loop.dispose();
+        publish = NOOP_PUBLISH;
+        latest = null;
+    };
+    if (opts.signal?.aborted)
+        dispose();
+    else {
+        removeAbortListener = watchAbort(opts.signal, dispose);
+        loop.setActive(true);
+        observer = new ResizeObserver(onResize);
+        observer.observe(target);
+    }
     return {
         update(nextPublish) {
             if (disposed)
@@ -67,18 +89,6 @@ export function createSizeAdvertiser(target, opts) {
             if (cur !== null)
                 loop.emitNow(cur);
         },
-        dispose() {
-            if (disposed)
-                return;
-            disposed = true;
-            loop.cancel();
-            if (observer) {
-                observer.disconnect();
-                observer = null;
-            }
-            loop.dispose();
-            publish = NOOP_PUBLISH;
-            latest = null;
-        },
+        dispose,
     };
 }

package/dist/types.d.ts

@@ -36,6 +36,8 @@ export interface ViewAnchorOptions {
     present: boolean;
     /** Receives the live rect, or zero bounds when detached. */
     publish: Publisher<Bounds>;
+    /** Stops this anchor when aborted. An already-aborted signal starts no work. */
+    signal?: AbortSignal;
 }
 export interface ViewAnchorHandle {
     /** Apply new options and re-publish immediately. */
@@ -57,6 +59,8 @@ export interface SizeAdvertiserOptions {
     axis: AdvertisedAxis;
     /** Receives each advertised size. */
     publish: Publisher<AdvertisedSize>;
+    /** Stops this advertiser when aborted. An already-aborted signal starts no work. */
+    signal?: AbortSignal;
 }
 export interface SizeAdvertiserHandle {
     /** Swap the publish callback and re-advertise the current size immediately. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,CAAA;AAE1C;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,aAAa,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAE9E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,4DAA4D;IAC5D,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACrC,6FAA6F;IAC7F,OAAO,IAAI,IAAI,CAAA;CAChB;AAOD,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE/C,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,IAAI,EAAE,cAAc,CAAA;IACpB,qCAAqC;IACrC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,IAAI,CAAA;IAChD,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAA;CAChB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,CAAA;AAE1C;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,aAAa,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAE9E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,4DAA4D;IAC5D,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;IAC1B,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACrC,6FAA6F;IAC7F,OAAO,IAAI,IAAI,CAAA;CAChB;AAOD,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE/C,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,IAAI,EAAE,cAAc,CAAA;IACpB,qCAAqC;IACrC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,CAAA;IAClC,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,IAAI,CAAA;IAChD,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAA;CAChB"}

package/dist/view-anchor.d.ts

@@ -10,8 +10,8 @@ import type { Placement, Publisher, ViewAnchorOptions, ViewAnchorHandle } from '
  * - `dispose()`: stops observing and prevents any further publishes.
  *
  * Synchronous publishing: measurement and publishing occur directly in the
- * observer tick. Cross-process setBounds calls already have a compositor delay;
- * adding requestAnimationFrame would add a second frame of visual lag during drag
+ * observer tick. Applying geometry outside the DOM may already be delayed;
+ * adding requestAnimationFrame would add another frame of visual lag during drag
  * operations. High-frequency updates are deduplicated against the last accepted rect.
  */
 export declare function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions): ViewAnchorHandle;
@@ -23,6 +23,8 @@ export interface PlacementAnchorOptions {
     visible: boolean;
     /** Receives each explicit Placement. */
     publish: Publisher<Placement>;
+    /** Stops this anchor when aborted. An already-aborted signal starts no work. */
+    signal?: AbortSignal;
     /**
      * When true, targets with zero area (such as display: none or unmounted elements)
      * publish { visible: false } instead of { visible: true, bounds: 0x0 }, and an

package/dist/view-anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-anchor.d.ts","sourceRoot":"","sources":["../src/view-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAkBnG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAsG/F;AAID,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAA;IAC1C,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAM/D;AAeD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,sBAAsB,GAC3B,qBAAqB,CAmTvB"}
+{"version":3,"file":"view-anchor.d.ts","sourceRoot":"","sources":["../src/view-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAmBnG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAgH/F;AAID,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;IAC7B,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAA;IAC1C,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAM/D;AAeD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,sBAAsB,GAC3B,qBAAqB,CA6TvB"}

package/dist/view-anchor.js

@@ -1,3 +1,4 @@
+import { watchAbort } from './abort.js';
 const ZERO = { x: 0, y: 0, width: 0, height: 0 };
 // Replaces a disposed instance's publish callback so a retained handle does
 // not keep the caller's original callback (and whatever it captured) alive.
@@ -22,8 +23,8 @@ const clampRect = (r) => ({
  * - `dispose()`: stops observing and prevents any further publishes.
  *
  * Synchronous publishing: measurement and publishing occur directly in the
- * observer tick. Cross-process setBounds calls already have a compositor delay;
- * adding requestAnimationFrame would add a second frame of visual lag during drag
+ * observer tick. Applying geometry outside the DOM may already be delayed;
+ * adding requestAnimationFrame would add another frame of visual lag during drag
  * operations. High-frequency updates are deduplicated against the last accepted rect.
  */
 export function createViewAnchor(target, opts) {
@@ -40,7 +41,7 @@ export function createViewAnchor(target, opts) {
     let disposed = false;
     const measure = () => {
         const r = targetRef.getBoundingClientRect();
-        // Drop ticks with non-finite values (NaN / Infinity cannot be sent over IPC).
+        // Drop ticks with non-finite values (NaN / Infinity are not usable geometry).
         if (!Number.isFinite(r.left) ||
             !Number.isFinite(r.top) ||
             !Number.isFinite(r.width) ||
@@ -108,7 +109,24 @@ export function createViewAnchor(target, opts) {
             publishCandidate(ZERO);
         }
     };
-    apply();
+    let removeAbortListener = () => { };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        removeAbortListener();
+        removeAbortListener = () => { };
+        stopObserving();
+        targetRef = null;
+        publish = NOOP_PUBLISH;
+        lastPublished = null;
+    };
+    if (opts.signal?.aborted)
+        dispose();
+    else {
+        removeAbortListener = watchAbort(opts.signal, dispose);
+        apply();
+    }
     return {
         update(next) {
             if (disposed)
@@ -117,15 +135,7 @@ export function createViewAnchor(target, opts) {
             present = next.present;
             apply();
         },
-        dispose() {
-            if (disposed)
-                return;
-            disposed = true;
-            stopObserving();
-            targetRef = null;
-            publish = NOOP_PUBLISH;
-            lastPublished = null;
-        },
+        dispose,
     };
 }
 /**
@@ -422,7 +432,24 @@ export function createPlacementAnchor(target, opts) {
             publishCandidate(hidden);
         }
     };
-    apply();
+    let removeAbortListener = () => { };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        removeAbortListener();
+        removeAbortListener = () => { };
+        stopObserving();
+        targetRef = null;
+        publish = NOOP_PUBLISH;
+        lastPublished = null;
+    };
+    if (opts.signal?.aborted)
+        dispose();
+    else {
+        removeAbortListener = watchAbort(opts.signal, dispose);
+        apply();
+    }
     return {
         update(next) {
             if (disposed)
@@ -440,15 +467,7 @@ export function createPlacementAnchor(target, opts) {
             }
             apply();
         },
-        dispose() {
-            if (disposed)
-                return;
-            disposed = true;
-            stopObserving();
-            targetRef = null;
-            publish = NOOP_PUBLISH;
-            lastPublished = null;
-        },
+        dispose,
         pulse(durationMs) {
             if (disposed || !followGeometry)
                 return;

package/docs/bidirectional-design.md

@@ -2,8 +2,8 @@
 
 view-anchor 支持双向几何同步：
 
-- **正向（`createViewAnchor`）**：宿主测量 DOM 占位元素的位置和尺寸，通过 `publish(bounds)` 发送给主进程或外部容器，更新原生视图（如 `WebContentsView.setBounds`）。
-- **反向（`createSizeAdvertiser`）**：下游视图内部测量自身内容尺寸，通过 `publish(size)` 通知宿主调整占位大小，宿主再通过正向更新视图位置。
+- **正向（`createViewAnchor`）**：测量 DOM 占位元素的位置和尺寸，通过 `publish(bounds)` 把 `{ x, y, width, height }` 交给应用，由应用更新外部画面。
+- **反向（`createSizeAdvertiser`）**：内容区域测量自身尺寸，通过 `publish(size)` 把 `{ axis, extent }` 交给应用，由应用调整占位元素大小。
 
 常见场景：嵌套在宿主中的工具栏或面板，其宽度由宿主布局决定，高度则由子视图自身的内容决定。
 
@@ -12,9 +12,9 @@ view-anchor 支持双向几何同步：
 两个方向在性能和交互上的要求不同，因此没有共用同一套调度逻辑：
 
 - **正向（`createViewAnchor`）采用同步发布。**
-  原生视图的 `setBounds` 需要跨进程通信，相比渲染进程本身的页面绘制通常已经有大约一帧的延迟。如果测量和发布再走一次 `requestAnimationFrame`，拖拽时就会产生两帧以上的视觉延迟，出现明显的边框脱节。因此正向在 `ResizeObserver` 和窗口 `resize` 回调中**同步测量并发布**，高频触发的防抖则依赖前后数值的比对（相同矩形直接跳过）。
+  外部画面的更新本身可能已有延迟；测量后再等一次 `requestAnimationFrame` 会增加拖拽时的跟随延迟。因此正向在 `ResizeObserver` 和窗口 `resize` 回调中**同步测量并调用 `publish(bounds)`**，相同矩形直接跳过。
 - **反向（`createSizeAdvertiser`）采用 RAF 调度（`createMeasureLoop`）。**
-  反向构成了一条跨进程的反馈环：下游上报尺寸 → 宿主调整占位大小 → 下游重新布局与测量 → 再次上报。在这个链路中，将上报频率限制在每帧至多一次（与屏幕刷新率对齐）能够有效避免高频震荡，同时提供平滑的缓冲。
+  反向构成一条反馈环：内容上报尺寸 → 应用调整占位大小 → 内容重新布局与测量 → 再次上报。在这个链路中，将上报频率限制在每帧至多一次（与屏幕刷新率对齐）能够有效避免高频震荡，同时提供平滑的缓冲。
 
 ## 2. 反向接口说明
 
@@ -29,6 +29,7 @@ export interface AdvertisedSize {
 export interface SizeAdvertiserOptions {
   axis: AdvertisedAxis            // 创建后固定，每个 advertiser 只负责一条轴
   publish: Publisher<AdvertisedSize> // 接收尺寸发布的回调
+  signal?: AbortSignal            // abort 后停止监听并取消已排队的帧
 }
 
 export interface SizeAdvertiserHandle {
@@ -51,9 +52,9 @@ export function createSizeAdvertiser(
 
 为了避免死循环，必须遵循单轴控制原则：
 
-- 一个 advertiser 只测量并上报它负责的那条轴；另一条轴由宿主通过 `setBounds` 单向传入，下游只读。
-- 典型案例：宿主决定宽度，下游决定高度。因为高度是内容流式排版的结果而不是输入，整个尺寸传递是一条单向有向无环图（DAG），更新可以在单步内收敛。
-- 如果下游的高度又反过来改变了下游的宽度（或测量了 `<body>`/`<html>`），就会形成跨进程的循环调整，导致界面抖动。
+- 一个 advertiser 只测量并上报它负责的那条轴；另一条轴由应用单向设置，内容区域只读。
+- 典型案例：宿主决定宽度，下游决定高度。因为高度是内容流式排版的结果而不是输入，整个尺寸传递构成一个有向无环图（DAG），更新在单步内即可收敛。
+- 如果内容的高度又反过来改变宽度（或测量了 `<body>`/`<html>`），就会形成循环调整，导致界面抖动。
 
 ## 4. 职责与信任边界
 
@@ -65,7 +66,7 @@ export function createSizeAdvertiser(
 | 过滤 NaN / Infinity | view-anchor | 丢弃异常无效数值 |
 | 负数归零 | view-anchor | 保证尺寸非负，反映真实测量结果 |
 | 视口限制（clamp） | 宿主 | 依据当前窗口可用空间对上报值做范围约束，防止异常大值 |
-| 发送方身份校验 | 宿主 | 在接收 IPC 或 postMessage 时验证 senderFrame、origin 或 token |
+| 来源身份校验 | 应用 | 在接收数据前验证调用方或通道是否可信 |
 | 轴白名单校验 | 宿主 | 检查 `axis` 是否与宿主预期的控制轴一致 |
 | 位置与层级锁定 | 宿主 | 下游不能擅自修改自身的坐标位置或 z-index |
 
@@ -81,32 +82,20 @@ export function createSizeAdvertiser(
 
 ```mermaid
 flowchart LR
-  subgraph DOWN["下游渲染进程（如工具栏页面）"]
-    C["内容容器<br/>高度由自身内容决定"]
-  end
-  subgraph HOST["宿主渲染进程"]
-    H["宿主消息处理器<br/>校验来源、clamp 数值"]
-    DIV["占位 div"]
-    VA["createViewAnchor"]
-  end
-  subgraph MAIN["宿主主进程"]
-    NV["WebContentsView / 原生视图"]
-  end
-
-  C -->|"① publish(size)"| H
-  H -->|"② clamp 后写入 style.height"| DIV
-  DIV -->|"ResizeObserver 观测"| VA
-  VA -->|"③ 测出新矩形，publish(bounds)"| NV
-  NV -->|"④ setBounds 后下游视口变化，内容重排"| C
+  C["内容容器\n高度由自身内容决定"] -->|"① publish(size)"| H["应用回调\n校验并限制数值"]
+  H -->|"② 写入 style.height"| DIV["占位元素"]
+  DIV -->|"ResizeObserver 观测"| VA["createViewAnchor"]
+  VA -->|"③ publish(bounds)"| A["应用回调"]
+  A -->|"④ 应用矩形"| S["外部画面"]
 ```
 
-1. **下游**：通过 `createSizeAdvertiser` 测量高度并通过 IPC 发给宿主。
-2. **宿主**：对收到的高度做合规性限制（例如限制在 `minHeight` 和 `maxHeight` 之间），并写入占位 div 的样式。
-3. **宿主**：占位 div 尺寸改变，`createViewAnchor` 的 `ResizeObserver` 触发，测量出新的绝对矩形并发给主进程。
-4. **宿主主进程**：调用 `setBounds` 更新原生视图位置与尺寸。
+1. **内容区域**：通过 `createSizeAdvertiser` 测量高度并调用 `publish(size)`。
+2. **应用**：限制收到的高度（例如在 `minHeight` 和 `maxHeight` 之间），然后写入占位元素的样式。
+3. **占位元素**：尺寸改变后，`createViewAnchor` 的 `ResizeObserver` 会测量新的绝对矩形并调用 `publish(bounds)`。
+4. **应用**：把矩形用于定位外部画面。
 
-## 6. 与 Electron preferred-size 的关系
+## 6. 何时需要反向尺寸上报
 
-在纯 Electron 环境下，也可以使用 `enablePreferredSizeMode` 和 `preferred-size-changed` 事件由 Electron 主进程自动获取网页期望大小。
+只有外部画面的内容尺寸需要反过来改变宿主布局时，才需要 `createSizeAdvertiser`。如果应用已经能直接知道或设置这个尺寸，不需要引入反向反馈链路。
 
-view-anchor 的反向方案是平台无关的实现，适用于跨域 iframe、第三方 webview 或需要针对特定内部 DOM 节点测量尺寸的场景。两者并不冲突，可以根据具体的宿主架构按需选择。
+反向方案适用于需要测量特定内部 DOM 节点的场景。保持“一个方向只控制一个轴”，并在应用侧限制接收值，能避免尺寸互相驱动导致的抖动。

package/docs/index.html

@@ -3,8 +3,8 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>view-anchor 3D demo: align anything outside the DOM to a DOM element</title>
-<meta name="description" content="view-anchor is a high-performance geometry bridge that keeps an anchored view — an Electron WebContentsView, a native webview, a cross-origin iframe — aligned to a DOM element. This interactive 3D demo runs the real core in your browser.">
+<title>view-anchor 3D Demo: Keep External Surfaces Aligned with DOM Elements</title>
+<meta name="description" content="Interactive 3D demo showing view-anchor tracking DOM elements live in the browser, with zero frame lag and no external dependencies.">
 <style>
   :root {
     --bg:               hsl(  0  0%   7%);
@@ -125,7 +125,7 @@
     background: linear-gradient(180deg, hsl(160 40% 20%), hsl(160 38% 13%));
     border: 1.5px solid var(--native-bd);
     box-shadow: 0 0 0 1px hsl(160 72% 60% / 0.25), inset 0 0 24px hsl(160 72% 50% / 0.12);
-    /* position/size snap each frame (like a real setBounds) — only the
+    /* position/size snap each frame — only the
        explode lift + collapse fade animate; otherwise tracking rubber-bands. */
     transition: transform 900ms cubic-bezier(0.6,0,0.2,1), box-shadow 900ms, opacity 300ms;
     overflow: hidden;
@@ -213,7 +213,7 @@
       <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D24-339933">
     </div>
     <h1>view-anchor: interactive 3D demo</h1>
-    <p class="tag-en">Align an <b style="color:var(--native-bd)">anchored view</b> — an Electron <code>WebContentsView</code>, a native webview, a cross-origin iframe — to a DOM element's geometry. Resize the splitter, toggle <code>present</code>, or explode the 3D scene below: the green anchored view is positioned by the real view-anchor core running in this page.</p>
+    <p class="tag-en">Align external surfaces (native views, canvases, iframes) to DOM elements in real time. Drag the splitter or toggle controls below: the green surface is positioned live by view-anchor.</p>
     <div class="actions">
       <a href="https://github.com/lbb00/view-anchor">GitHub</a>
       <a href="https://www.npmjs.com/package/view-anchor">npm</a>
@@ -253,7 +253,7 @@
           <input type="checkbox" id="present" checked>
           <span class="track"></span><span class="thumb"></span>
         </span>
-        <label for="present"><code>present</code></label>
+        <label for="present">Mount (<code>present</code>)</label>
       </div>
       <div class="ctl">
         <label for="split">Split</label>
@@ -264,7 +264,7 @@
           <input type="checkbox" id="explode" checked>
           <span class="track"></span><span class="thumb"></span>
         </span>
-        <label for="explode">Explode</label>
+        <label for="explode">3D Explode</label>
       </div>
       <div class="readout" id="readout"></div>
     </div>
@@ -282,7 +282,7 @@
       <a href="https://www.npmjs.com/package/view-anchor">npm · view-anchor</a>
       <span style="color:var(--text-3)">MIT licensed</span>
     </div>
-    <div class="hint">Drag <code>Split</code> to resize the placeholder, toggle <code>present</code> to collapse or restore, and toggle <code>Explode</code> for the 3D perspective. The green anchored view's bounds come directly from view-anchor's <code>publish</code> callback.</div>
+    <div class="hint">Drag <b>Split</b> to resize the placeholder, or toggle <b>3D Explode</b> to inspect the Z-space layering. The green overlay tracks the layout synchronously via the <code>publish</code> callback.</div>
   </footer>
 
 </div>
@@ -295,6 +295,16 @@
 /* __VIEW_ANCHOR_CORE_START__ — generated from src/view-anchor.ts by `pnpm build:docs`; do not edit */
 var __viewAnchorCore = (function(exports) {
 	Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+	//#region src/abort.ts
+	const NOOP = () => {};
+	/** Attach a one-shot abort listener and return a function that detaches it. */
+	function watchAbort(signal, dispose) {
+		if (!signal) return NOOP;
+		const onAbort = () => dispose();
+		signal.addEventListener("abort", onAbort, { once: true });
+		return () => signal.removeEventListener("abort", onAbort);
+	}
+	//#endregion
 	//#region src/view-anchor.ts
 	const ZERO = {
 		x: 0,
@@ -320,8 +330,8 @@ var __viewAnchorCore = (function(exports) {
 	* - `dispose()`: stops observing and prevents any further publishes.
 	*
 	* Synchronous publishing: measurement and publishing occur directly in the
-	* observer tick. Cross-process setBounds calls already have a compositor delay;
-	* adding requestAnimationFrame would add a second frame of visual lag during drag
+	* observer tick. Applying geometry outside the DOM may already be delayed;
+	* adding requestAnimationFrame would add another frame of visual lag during drag
 	* operations. High-frequency updates are deduplicated against the last accepted rect.
 	*/
 	function createViewAnchor(target, opts) {
@@ -387,7 +397,22 @@ var __viewAnchorCore = (function(exports) {
 				publishCandidate(ZERO);
 			}
 		};
-		apply();
+		let removeAbortListener = () => {};
+		const dispose = () => {
+			if (disposed) return;
+			disposed = true;
+			removeAbortListener();
+			removeAbortListener = () => {};
+			stopObserving();
+			targetRef = null;
+			publish = NOOP_PUBLISH;
+			lastPublished = null;
+		};
+		if (opts.signal?.aborted) dispose();
+		else {
+			removeAbortListener = watchAbort(opts.signal, dispose);
+			apply();
+		}
 		return {
 			update(next) {
 				if (disposed) return;
@@ -395,14 +420,7 @@ var __viewAnchorCore = (function(exports) {
 				present = next.present;
 				apply();
 			},
-			dispose() {
-				if (disposed) return;
-				disposed = true;
-				stopObserving();
-				targetRef = null;
-				publish = NOOP_PUBLISH;
-				lastPublished = null;
-			}
+			dispose
 		};
 	}
 	/**
@@ -656,7 +674,22 @@ var __viewAnchorCore = (function(exports) {
 				publishCandidate({ visible: false });
 			}
 		};
-		apply();
+		let removeAbortListener = () => {};
+		const dispose = () => {
+			if (disposed) return;
+			disposed = true;
+			removeAbortListener();
+			removeAbortListener = () => {};
+			stopObserving();
+			targetRef = null;
+			publish = NOOP_PUBLISH;
+			lastPublished = null;
+		};
+		if (opts.signal?.aborted) dispose();
+		else {
+			removeAbortListener = watchAbort(opts.signal, dispose);
+			apply();
+		}
 		return {
 			update(next) {
 				if (disposed) return;
@@ -671,14 +704,7 @@ var __viewAnchorCore = (function(exports) {
 				}
 				apply();
 			},
-			dispose() {
-				if (disposed) return;
-				disposed = true;
-				stopObserving();
-				targetRef = null;
-				publish = NOOP_PUBLISH;
-				lastPublished = null;
-			},
+			dispose,
 			pulse(durationMs) {
 				if (disposed || !followGeometry) return;
 				if (durationMs !== void 0 && durationMs > 0) {
@@ -723,7 +749,7 @@ var __viewAnchorCore = (function(exports) {
   }
 
   // The host-side publish — view-anchor hands it the measured rect. A real app
-  // would go IPC → WebContentsView.setBounds; here we place the view in the
+  // application code would use the bounds here; this demo places the view in the
   // deck's local coordinates.
   function publish(bounds) {
     if (bounds.width === 0 || bounds.height === 0) {

package/docs/mechanism.md

@@ -1,35 +1,32 @@
 # view-anchor
 
-让宿主外部的视图（例如 Electron 的 `WebContentsView`）实时对齐某个 DOM 元素的屏幕位置。核心逻辑通过 `getBoundingClientRect()` 测量目标元素，把矩形数据交给注入的 `publish` 回调（通常由调用方转发 IPC 到 `setBounds`），并在元素移动或缩放时同步更新。
+将外部画面实时对齐到指定的 DOM 元素。核心逻辑通过 `getBoundingClientRect()` 测量目标元素，并把矩形数据交给 `publish` 回调；应用代码决定如何使用这个矩形。
 
-核心不依赖 React、Electron 或特定的布局引擎；React 相关的逻辑均隔离在 `view-anchor/react` 适配层中。
+核心不依赖 React、特定宿主或布局引擎；React 相关的逻辑均隔离在 `view-anchor/react` 适配层中。
 
-> 🎮 [3D 交互演示](https://lbb00.github.io/view-anchor/)：页面里跑的是真实核心代码。拖动分栏、切换面板显示，看原生视图实时跟随。源码见 [index.html](./index.html)。
+> **在线演示**：[3D 交互演示](https://lbb00.github.io/view-anchor/) 运行真实核心代码。拖动分栏、切换面板显示，看外部视图实时跟随。源码见 [index.html](./index.html)。
 
 ## 运行机制
 
 ```mermaid
 flowchart LR
-  subgraph R["渲染进程 · WebContents"]
-    DIV["占位 div<br/>（CSS 布局，自身不渲染）"]
-  end
-  subgraph M["主进程"]
-    WCV["WebContentsView<br/>（原生图层，覆盖在网页之上）"]
-  end
-  DIV -->|"getBoundingClientRect()"| VA["view-anchor"]
-  VA -->|"publish(bounds)<br/>IPC → setBounds"| WCV
+  DIV["占位元素\n参与 DOM 布局"] -->|"getBoundingClientRect()"| VA["view-anchor"]
+  VA -->|"publish(bounds)"| A["应用提供的回调"]
+  A -->|"应用矩形"| S["外部画面"]
 ```
 
-`WebContentsView` 运行在主进程，位置由主进程的 `setBounds` 设置；页面布局则由渲染进程通过 CSS 计算。两者不在同一个进程中，view-anchor 作为桥梁连接它们：占位 div 参与 DOM 布局，外部视图悬浮在上方，由 view-anchor 维持对齐。`publish` 是外部注入的回调，核心模块本身完全不感知 Electron。
+占位元素参与 DOM 布局，外部画面由应用代码定位。`view-anchor` 只负责测量和调用 `publish(bounds)`；它不创建外部画面，也不决定矩形通过什么方式到达那里。
 
 ## createViewAnchor(target, opts)
 
-命令式核心接口，将原生视图绑定到目标元素，返回 `{ update, dispose }`。
+命令式核心接口，将外部画面绑定到目标元素，返回 `{ update, dispose }`。
 
 ```ts
 const handle = createViewAnchor(target, {
-  present: true,                 // 是否显示原生视图
-  publish: (bounds) => { ... },  // 接收最新矩形，转发给 setBounds
+  present: true,
+  publish(bounds) {
+    applyBounds(bounds)
+  },
 })
 ```
 
@@ -38,18 +35,18 @@ const handle = createViewAnchor(target, {
 | `present: true` | 立即发布测量矩形，之后每次 `ResizeObserver` 触发或窗口 `resize` 时同步重发。 |
 | `present: false` | 停止观察，发布一次 `{ x: 0, y: 0, width: 0, height: 0 }`。 |
 | `update(opts)` | 应用新选项，重置去重缓存并立即重新发布一次。 |
-| `dispose()` | 停止所有监听并释放资源，此后不再发布。 |
+| `dispose()` / `AbortController.abort()` | 停止所有监听并释放资源，此后不再发布。 |
 
 测量结果使用 `Math.round` 取整。`width` 和 `height` 会限制为 `>= 0`（0 代表收起），但 `x` 和 `y` 允许为负数。当元素滚动出视口上边缘或左边缘时，原点自然会是负值，保留负值可以让视图正常跟随元素滚出屏幕。
 
-**为什么同步发布而不走 RAF：** 原生 overlay 处于另一个进程，IPC 传递到 `setBounds` 相比渲染进程本身的绘制已经有一帧左右的合成延迟。如果测量和发布再进一次 RAF，拖拽时就会叠加第二帧延迟，造成明显的跟随拖尾。在 observer 回调中直接同步测量和发布可以省掉这层额外延迟。同帧多次触发的防抖则交由同值去重处理：只有矩形数值与上一次不同时才触发 `publish`。调用 `update` 时会先清除去重基线，确保外部状态变化（如缩放系数变化）时即使几何数据未变也能重新发布。
+**为什么同步发布而不走 RAF：** 外部画面的更新本身可能已经有延迟。若测量后再等一帧，拖拽时会多出一帧跟随延迟。在 observer 回调中直接测量并调用 `publish` 可以避免这一步等待。同帧多次触发时，只要 4 个矩形数值有一项发生变化便会调用 `publish`，与上一帧完全一致则跳过。调用 `update` 会清除去重基线，因此即使矩形不变，也能把新的应用状态重新交给回调。
 
-调用 `dispose()` 或更新为 `present: false` 后，内部状态会立即置为停用，后续任何异步触发都会直接返回，避免过期数据覆盖新状态。
+调用 `dispose()`、`AbortController.abort()` 或更新为 `present: false` 后，内部状态会立即置为停用，后续任何异步触发都会直接返回，避免过期数据覆盖新状态。
 
 ## 收起与零矩形
 
-- **`present`**：标识原生视图当前是否需要显示。
-- **`{ x: 0, y: 0, width: 0, height: 0 }`（零矩形）**：收起信号。宿主可以将零面积理解为“从窗口中移出视图，但保留其 `WebContents` 实例”，实现秒开复用而不是反复销毁重建。
+- **`present`**：标识外部画面当前是否需要显示。
+- **`{ x: 0, y: 0, width: 0, height: 0 }`（零矩形）**：收起信号。应用可以把它解释为隐藏、移除，或仅保留最后一个状态。
 - **dispose 行为**：`dispose()` 只停止监听，不补发零矩形。如果需要在元素移除时通知宿主收起视图，应当在 dispose 之前调用 `update({ present: false, ... })`，React 适配层已自动处理了该生命周期。
 
 ## 显式可见性（createPlacementAnchor）
@@ -106,11 +103,14 @@ React 18 在卸载时会传入 `ref(null)`，React 19 支持 ref 清理函数。
 
 | 文件 | 用途 |
 |---|---|
-| `src/view-anchor.ts` | 正向命令式核心：`createViewAnchor`、`createPlacementAnchor`、`measurePlacement`。不含 React 和 Electron 依赖。 |
+| `src/view-anchor.ts` | 正向命令式核心：`createViewAnchor`、`createPlacementAnchor`、`measurePlacement`。不含 React 或宿主依赖。 |
 | `src/react.ts` | React 适配层：`useViewAnchor` 与 `usePlacementAnchor`。 |
 | `src/size-advertiser.ts` | 反向核心：`createSizeAdvertiser`。 |
 | `src/measure-loop.ts` | 反向专用的 RAF 调度与去重循环（内部实现，不对外导出）。 |
 | `src/types.ts` | 类型定义（`Bounds`、`Placement`、各模块配置与句柄）。 |
-| `src/index.ts` | 核心入口，默认不引入 React。 |
+| `src/abort.ts` | 内部实现：标准 `AbortSignal` 监听与注销辅助。 |
+| `src/index.ts` | 根入口，导出核心几何方法并兼容性重导出 `useViewAnchor`。 |
+
+消息协议模块（`src/protocol.ts`、`src/protocol-publisher.ts` 等）详见 [通信协议设计文档](./protocol.md)。
 
 核心运行时仅依赖标准 Web API（`ResizeObserver`、`getBoundingClientRect`、`addEventListener`）；`requestAnimationFrame` 仅在反向模块与可选的 `followGeometry` 中按需使用。

package/docs/performance-report.md

@@ -2,7 +2,7 @@
 
 本报告只保留当前工作树可由 `pnpm benchmark` 直接重建的绝对数据。命令启动 3 个全新的 Node.js 进程；每个进程预热 2 次、保留 7 个样本。CPU 表的“当前中位数”是三个进程中位数的中位数，完整 JSON 含全部 21 个原始样本。
 
-本次环境：Node.js 24.18.0、macOS arm64、Apple M4（10 个逻辑核心）。这些数字只适合同机比较，不是浏览器、Electron IPC 或 DOM layout 的耗时承诺。
+本次环境：Node.js 24.18.0、macOS arm64、Apple M4（10 个逻辑核心）。这些数字只适合同机比较，不是浏览器布局、序列化或数据传递的耗时承诺。
 
 ## CPU
 
@@ -60,4 +60,4 @@
 
 运行 `pnpm benchmark:v8 > /tmp/view-anchor-v8.log 2>&1` 时，三个新的 benchmark 进程会继承 `--trace-opt`、`--trace-deopt` 与 `--trace-turbo-inlining`。本文没有保留无对应当前 trace 工件的历史优化/反优化结论。
 
-当前测量不覆盖真实浏览器/Electron、DOM layout、structured clone、IPC 或生产工作负载；这些路径需在目标运行时另行测量。
+当前测量不覆盖真实浏览器布局、序列化、数据传递或生产工作负载；这些路径需在目标运行时另行测量。