view-anchor 0.2.1 → 0.2.2

package/docs/protocol.md

@@ -1,6 +1,6 @@
 # 通信协议
 
-`view-anchor` 核心模块只负责测量并同步调用 `publish`。如果需要在进程或 iframe 边界上传输几何数据，可以使用可选的 `view-anchor/protocol` 模块。它提供带版本的消息结构、输入校验、消息防乱序和微任务批处理，不绑定具体的传输通道。
+`view-anchor` 核心模块只负责测量并同步调用 `publish`。如果应用要把几何数据交给异步或不完全可信的通道，可以使用可选的 `view-anchor/protocol` 模块。它提供带版本的消息结构、输入校验、消息防乱序和微任务批处理，不绑定具体的传递方式。
 
 一条消息从锚点走到宿主要经过的环节：
 
@@ -16,12 +16,12 @@ sequenceDiagram
   A->>P: publish(placement)
   P->>B: 带 anchorId、generation、seq 的消息
   Note over B: 同一微任务内合并，<br/>每个 anchorId 的 placement 和 size<br/>各自只留最新一条
-  B->>D: IPC / postMessage
+  B->>D: 应用传递原始数据
   D->>D: 校验版本、类型、整数范围、批次上限
   alt 校验不通过
     D-->>H: 返回 ok: false，不抛异常
   else 校验通过
-    Note over D,G: 宿主先验证发送方身份<br/>senderFrame / origin / token
+    Note over D,G: 接收方先验证来源身份
     D->>G: 逐条交给 guard
     alt generation 更旧，或同类型 seq 不大于已见最大值
       G-->>H: 丢弃
@@ -42,7 +42,7 @@ sequenceDiagram
 - `seq`：同一 publisher 内单调递增的序列号。
 - `placement` 或 `size`：具体的位置或尺寸数据。
 
-`generation` 作用于同一个 `anchorId`：一旦接收到新一代的消息，所有该锚点的旧代消息都会被直接丢弃。`generation` 与 `seq` 只负责保证消息顺序，不作为鉴权凭据。接收端依然应当在分发前验证发送方身份（如校验 `senderFrame`、域名或访问令牌）。
+`generation` 作用于同一个 `anchorId`：一旦接收到新一代的消息，所有该锚点的旧代消息都会被直接丢弃。`generation` 与 `seq` 只负责保证消息顺序，不作为鉴权凭据。接收端仍应在分发前验证来源身份。
 
 ## 发送端
 
@@ -53,7 +53,7 @@ import {
 } from 'view-anchor/protocol'
 
 const batcher = createGeometryBatcher(
-  (batch) => ipc.send('geometry', batch),
+  sendGeometryBatch,
   { onError: (err) => console.error(err) },
 )
 
@@ -88,7 +88,7 @@ if (result.ok) {
 
   for (const message of messages) {
     if (
-      isAuthorized(event.senderFrame, message.anchorId) &&
+      isAuthorized(message.anchorId) &&
       guard.accept(message)
     ) {
       applyGeometry(message)
@@ -105,4 +105,4 @@ if (result.ok) {
 - 返回 `true` 或 `void`：表示数据已成功接收或已加入发送队列。
 - 返回 `false`：表示当前未接收。核心会在下一次测量触发时重新尝试该值。
 
-如果底层传输是异步的（例如异步 IPC 或网络请求），应当先在同步回调中将消息放入本地发送队列并返回 `true`，后续的重试由发送队列自行管理。
+如果底层传递是异步的，应当先在同步回调中将消息放入本地队列并返回 `true`，后续的重试由发送队列自行管理。

package/package.json

@@ -1,16 +1,8 @@
 {
   "name": "view-anchor",
-  "version": "0.2.1",
-  "description": "High-performance geometry bridge that keeps anything outside the DOM (an Electron WebContentsView, a native webview, a cross-origin iframe) aligned to a DOM element: synchronous, deduplicated updates, optional versioned message batching, React adapter, framework-free core.",
+  "version": "0.2.2",
+  "description": "High-performance geometry bridge that measures a DOM element and synchronously gives application code its current bounds: deduplicated updates, optional versioned message batching, React adapter, framework-free core.",
   "keywords": [
-    "electron",
-    "webcontentsview",
-    "browserview",
-    "webview",
-    "native view",
-    "iframe",
-    "postmessage",
-    "ipc",
     "dom",
     "geometry",
     "bounds",
@@ -73,6 +65,7 @@
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
+    "@changesets/cli": "^3.0.2",
     "@types/node": "^26.5.1",
     "@types/react": "^18.3.12",
     "@vitejs/plugin-react": "^6.0.1",
@@ -91,16 +84,17 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && pnpm run build:docs",
-    "build:docs": "node scripts/build-docs.mjs",
-    "check-types": "tsc --noEmit",
-    "lint": "oxlint . --deny-warnings",
+    "build:docs": "node scripts/build-docs.js",
+    "check-types": "tsc --noEmit -p tsconfig.test.json",
+    "lint": "oxlint . --deny-warnings --report-unused-disable-directives",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
     "test": "vitest run --reporter=default --reporter=json --outputFile.json=test-report.json --coverage.enabled --coverage.reporter=json-summary --coverage.reportsDirectory=coverage",
     "test:dev": "vitest",
     "test:coverage": "vitest run --coverage",
-    "benchmark": "node --expose-gc scripts/performance-report.mjs",
-    "benchmark:v8": "node --trace-opt --trace-deopt --trace-turbo-inlining --expose-gc scripts/performance-report.mjs",
-    "check-package": "node scripts/check-package.mjs"
+    "benchmark": "node --expose-gc scripts/performance-report.js",
+    "benchmark:v8": "node --trace-opt --trace-deopt --trace-turbo-inlining --expose-gc scripts/performance-report.js",
+    "check-package": "node scripts/check-package.js",
+    "release": "pnpm run build && pnpm run test && pnpm run check-package && changeset publish"
   }
 }

package/src/abort.ts

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

package/src/protocol-publisher.ts

@@ -1,4 +1,5 @@
 import type { AdvertisedSize, Placement, Publisher } from './types.js'
+import { watchAbort } from './abort.js'
 import {
   GEOMETRY_PROTOCOL_VERSION,
   type GeometryAddress,
@@ -14,6 +15,8 @@ export type GeometryBatchSend = Publisher<GeometryBatch>
 export interface GeometryBatcherOptions {
   /** Observes every batch-delivery error, including explicit flushes; it must not throw. */
   onError?: (error: unknown) => void
+  /** Stops this batcher when aborted. An already-aborted signal starts no work. */
+  signal?: AbortSignal
 }
 
 export interface GeometryBatcher {
@@ -85,8 +88,8 @@ const NOOP_SEND: GeometryBatchSend = () => false
 
 /**
  * Coalesces same-task messages without adding a rendering-frame delay. It owns
- * no authorization policy: callers must associate addresses with trusted IPC
- * senders before accepting a delivered batch.
+ * no authorization policy: callers must associate addresses with trusted
+ * sources before accepting a delivered batch.
  */
 export function createGeometryBatcher(
   send: GeometryBatchSend,
@@ -107,6 +110,7 @@ export function createGeometryBatcher(
   let disposed = false
   let scheduled = false
   let flushing = false
+  let removeAbortListener = (): void => {}
 
   // `activeOptions` lets a caller keep reporting to the options object that
   // was live when its flush() call started, even if a reentrant dispose()
@@ -192,6 +196,25 @@ export function createGeometryBatcher(
     })
   }
 
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    removeAbortListener()
+    removeAbortListener = (): void => {}
+    anchors.clear()
+    pendingAnchors.clear()
+    // Callers may still mutate the original options object after
+    // construction (e.g. reassigning onError); flush() captures its own
+    // reference before send() runs, so an in-flight error report keeps
+    // reading that object even though dispose() drops the instance's
+    // long-lived reference here.
+    options = {}
+    send = NOOP_SEND
+  }
+
+  if (options.signal?.aborted) dispose()
+  else removeAbortListener = watchAbort(options.signal, dispose)
+
   return {
     publish(message) {
       if (disposed) return false
@@ -238,17 +261,6 @@ export function createGeometryBatcher(
       if (state !== undefined) pendingAnchors.delete(state)
       anchors.delete(anchorId)
     },
-    dispose() {
-      disposed = true
-      anchors.clear()
-      pendingAnchors.clear()
-      // Callers may still mutate the original options object after
-      // construction (e.g. reassigning onError); flush() captures its own
-      // reference before send() runs, so an in-flight error report keeps
-      // reading that object even though dispose() drops the instance's
-      // long-lived reference here.
-      options = {}
-      send = NOOP_SEND
-    },
+    dispose,
   }
 }

package/src/react.ts

@@ -50,14 +50,11 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
   const handleRef = useRef<Handle | null>(null)
   const elementRef = useRef<HTMLElement | null>(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.
@@ -116,7 +113,6 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
       return () => deferDetach(element)
     }
     return undefined
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- helpers only read stable refs
   }, [])
 
   useEffect(() => {
@@ -131,7 +127,7 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
       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(() => {
@@ -140,7 +136,6 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
       const element = elementRef.current
       if (element) deferDetach(element)
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- helpers only read stable refs
   }, [])
 
   return ref

package/src/size-advertiser.ts

@@ -4,6 +4,7 @@ import type {
   SizeAdvertiserOptions,
   SizeAdvertiserHandle,
 } from './types.js'
+import { watchAbort } from './abort.js'
 import { createMeasureLoop } from './measure-loop.js'
 
 // Replaces a disposed instance's publish callback so a retained handle does
@@ -68,9 +69,30 @@ export function createSizeAdvertiser(
     )
   }
 
-  loop.setActive(true)
-  observer = new ResizeObserver(onResize)
-  observer.observe(target)
+  let removeAbortListener = (): void => {}
+
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    removeAbortListener()
+    removeAbortListener = (): void => {}
+    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: Publisher<AdvertisedSize>): void {
@@ -81,17 +103,6 @@ export function createSizeAdvertiser(
       const cur = produce()
       if (cur !== null) loop.emitNow(cur)
     },
-    dispose(): void {
-      if (disposed) return
-      disposed = true
-      loop.cancel()
-      if (observer) {
-        observer.disconnect()
-        observer = null
-      }
-      loop.dispose()
-      publish = NOOP_PUBLISH
-      latest = null
-    },
+    dispose,
   }
 }

package/src/types.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 {
@@ -66,6 +68,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 {

package/src/view-anchor.ts

@@ -1,4 +1,5 @@
 import type { Bounds, Placement, Publisher, ViewAnchorOptions, ViewAnchorHandle } from './types.js'
+import { watchAbort } from './abort.js'
 
 const ZERO: Bounds = { x: 0, y: 0, width: 0, height: 0 }
 
@@ -27,8 +28,8 @@ const clampRect = (r: { x: number; y: number; width: number; height: number }):
  * - `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: HTMLElement, opts: ViewAnchorOptions): ViewAnchorHandle {
@@ -46,7 +47,7 @@ export function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions):
 
   const measure = (): Bounds | null => {
     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) ||
@@ -115,7 +116,24 @@ export function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions):
     }
   }
 
-  apply()
+  let removeAbortListener = (): void => {}
+
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    removeAbortListener()
+    removeAbortListener = (): void => {}
+    stopObserving()
+    targetRef = null
+    publish = NOOP_PUBLISH
+    lastPublished = null
+  }
+
+  if (opts.signal?.aborted) dispose()
+  else {
+    removeAbortListener = watchAbort(opts.signal, dispose)
+    apply()
+  }
 
   return {
     update(next: ViewAnchorOptions): void {
@@ -124,14 +142,7 @@ export function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions):
       present = next.present
       apply()
     },
-    dispose(): void {
-      if (disposed) return
-      disposed = true
-      stopObserving()
-      targetRef = null
-      publish = NOOP_PUBLISH
-      lastPublished = null
-    },
+    dispose,
   }
 }
 
@@ -145,6 +156,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
@@ -485,7 +498,24 @@ export function createPlacementAnchor(
     }
   }
 
-  apply()
+  let removeAbortListener = (): void => {}
+
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    removeAbortListener()
+    removeAbortListener = (): void => {}
+    stopObserving()
+    targetRef = null
+    publish = NOOP_PUBLISH
+    lastPublished = null
+  }
+
+  if (opts.signal?.aborted) dispose()
+  else {
+    removeAbortListener = watchAbort(opts.signal, dispose)
+    apply()
+  }
 
   return {
     update(next: PlacementAnchorOptions): void {
@@ -503,14 +533,7 @@ export function createPlacementAnchor(
       }
       apply()
     },
-    dispose(): void {
-      if (disposed) return
-      disposed = true
-      stopObserving()
-      targetRef = null
-      publish = NOOP_PUBLISH
-      lastPublished = null
-    },
+    dispose,
     pulse(durationMs?: number): void {
       if (disposed || !followGeometry) return
       if (durationMs !== undefined && durationMs > 0) {