view-anchor 0.1.1

package/docs/bidirectional-design.md

@@ -0,0 +1,140 @@
+# view-anchor 双向几何桥
+
+view-anchor 是一座**双向几何桥**，引擎无关、传输注入：
+
+- **正向** `createViewAnchor(target, { present, publish })` —— 宿主渲染进程量 DOM 占位矩形 → `publish(bounds)` → IPC → 主进程 `WebContentsView.setBounds`。
+- **反向** `createSizeAdvertiser(target, { axis, publish })` —— 下游 WebContentsView 自己的渲染进程量自身内容尺寸 → `publish(size)` → IPC → 宿主，宿主据此调整占位尺寸，再经正向把视图贴上去。
+
+适用场景：toolbar 这类「**交给下游控制**」的 WebContentsView，尺寸的事实来源在下游一侧（典型：宽由宿主主导、高由下游内容主导），占位映射是动态的。
+
+范围之外：不是同层渲染（合成器层面、另一套机制）；包里不提供 React 反向适配、不提供宿主决策 `decide`（见 §3/§6）。
+
+## 1. 正反向不共享发射核心——两个方向最优时机不同
+
+正反向的最优发射时机本就不同，所以它们**不共享发射核心**，采取**正向同步、反向 RAF** 的刻意不对称。
+
+**正向 `createViewAnchor` = 同步发布，不走 RAF。** 原生 overlay 的 `setBounds` 是跨进程、本就晚约 1 合成帧；RAF 再叠一帧 → 拖拽可见拖尾。所以正向在每个 `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：
+
+```ts
+function createMeasureLoop<T>(cfg: {
+  produce: () => T | null        // RAF 体内取值：读最近一帧 borderBoxSize（null=跳过帧）
+  same: (a: T, b: T) => boolean  // 去重谓词（反向 = extent 相等）
+  sink: (value: T) => void       // = 注入的 publish
+}): { schedule, emitNow, setActive, cancel, dispose }
+```
+
+**为什么不对称是对的**：正向是单向跟随者，少一帧直接消除可见拖尾；反向是反馈环，多一帧阻尼更稳。把两者塞进一个核心要么逼出 `if(direction)` flag，要么把正向也拖进 RAF（带回拖尾）。所以**正向内联同步、反向用 RAF 引擎**，各取所需。
+
+## 2. 反向原语契约
+
+```ts
+export type AdvertisedAxis = 'block' | 'inline'
+
+// 帧载荷：纯标量，连「哪条轴」都无从携带 → 单轴在类型层不可拼写。
+export interface AdvertisedSize {
+  readonly axis: AdvertisedAxis   // 镜像工厂常量，逐帧恒等，供宿主白名单校验
+  readonly extent: number         // 主导轴内容尺寸，CSS px，已 round，钳到 >= 0
+}
+
+export interface SizeAdvertiserOptions {
+  axis: AdvertisedAxis                       // 创建期定死，一个 advertiser 一生只报一条轴
+  publish: (size: AdvertisedSize) => void    // 注入；下游接 IPC/postMessage → 宿主（与正向 publish 同名同形）
+}
+
+export interface SizeAdvertiserHandle {
+  update(publish: (size: AdvertisedSize) => void): void  // 只能换 publish（换 IPC 通道）；axis 不可变
+  dispose(): void                            // 停 observe、取消 RAF，此后永不再 publish
+}
+
+export function createSizeAdvertiser(target: HTMLElement, opts: SizeAdvertiserOptions): SizeAdvertiserHandle
+```
+
+- 跑在**下游**渲染进程；从 `ResizeObserverEntry.borderBoxSize` 读尺寸（零强制 reflow，**禁**回调内 `getBoundingClientRect`/`scrollHeight`）；上报前 `Math.round` + `Math.max(0, ...)`（与正向 `measure` 的 round/钳零对称）。
+- `target` 由调用方选成「主导轴上 shrink-to-fit、不被宿主写入反向决定」的 wrapper（与 `createViewAnchor` 一样，原语不碰调用方 DOM/样式）。
+- **没有 `present`**：反向「停止上报」无指令语义（塌缩还是保持是宿主策略），停就 `dispose`、恢复就重建。不给不可信下游一个隐式控宿主的布尔旁路。
+- 双轴需求 = **两个独立 advertiser 各管一轴**，不是一个 payload 塞两轴（后者把两条单向流伪装成一条双向流，使 DAG 退化成有环图）。
+
+## 3. 单轴所有权（收敛性地基，不可协商）
+
+- 一个 advertiser 只测量并只上报**它主导的那条轴**；另一条轴由宿主经 `setBounds` 单向灌入、对下游**只读**。
+- 为什么收敛：宽 = 宿主输入（无回边）；高 = block layout 的**输出**而非输入（无回边）→ 整条尺寸传播是单向 DAG，**一步收敛**。违反单轴 = 跨进程双 RAF 乒乓，是抖动/极限环根因。去环靠**拓扑**（单轴 + 类型不可拼写），不靠 epsilon 死区/低通滤波。
+
+## 4. 信任边界（精确划线）
+
+> 反向把「尺寸控制权」交给一个**下游控制**（半信任/不可信）的视图。上报值是攻击者输入，不是测量结果。
+
+判据：**凡只需测量上下文的归原语；凡需 viewport/策略/对端身份的归宿主。**
+
+| 责任 | 归属 | 说明 |
+|---|---|---|
+| `Math.round` 量化 | 原语 | 测量副产物，出生地最便宜 |
+| 丢 `NaN`/`Infinity` | 原语 | 测量噪声，不该塞进 IPC |
+| 负值 → **钳到 0**（非丢弃） | 原语 | 与正向 `Math.max(0,...)` 对称；钳零＝诚实上报「现在测出来是 0」，丢弃会让宿主停在过期值 |
+| 限流 | **两边都不额外加** | 原语的 RAF 合并 + 去重已是终极限流（跟随刷新率、静止零发）；宿主用 clamp + `decide` 幂等吸收突发，**不做时间节流**（会吞掉合法离散事件） |
+| `clamp(min, max)` | 宿主 | 唯一持有 viewport/available/策略的一方；对抗恶意巨值的**主防线** |
+| 来源校验（senderFrame/origin/token） | 宿主 | 只能发生在收 IPC 那一刻 |
+| 白名单轴 | 宿主 | 用 payload 的 `axis` 常量比对，`axis !== expected` 则丢弃 |
+| 位置 / 另一轴 / z-order 锁定 | 宿主 | 下游无任何途径改变 → 杜绝全窗覆盖类点击劫持 |
+
+**target 选错（反馈环）的防护——克制为主，不过度防御。** 关键事实：违反单轴所有权时，RAF 合并把「死循环」**封顶为每帧一次**——它退化成可见的抖动 / 每帧一次冗余 IPC，而**不是冻死 UI**。既然不是灾难性故障，就不在每帧路径上堆检测器。只保留：
+
+- **一条构造期廉价守卫**：`target` 是 `<body>`/`<html>` 时 `console.warn`——这是「stable-but-wrong」（占位永远撑成视图高、不缩到内容）最常见的成因，一次性、零每帧成本。
+- **其余靠文档**：JSDoc 与本节把「target 必须主导轴 shrink-to-fit、不被宿主灌入的尺寸反向决定」讲清。
+- **明确不做**：每帧的 2-cycle / 单调发散检测器（复杂度与「非灾难性、RAF 封顶」的故障不成正比）、运行时熔断（会把可见症状盖成静默失效）、向宿主回传灌入值做对比（会亲手造出 §3 要消灭的反馈边）。发散的真正兜底是宿主侧 `clamp(max)`。
+
+## 5. 两个原语如何「锚」到一起
+
+正向与反向**不直接相互调用**——各自只有一个注入的 `publish` 往 IPC 上发。把两端串到一起的是宿主里的**占位 div** + 宿主的 `decide` 函数。占位 div 是会合点（join point）：
+
+- **`createSizeAdvertiser` 写**占位 div 的尺寸（经宿主）——内容多高，占位就多高。
+- **`createViewAnchor` 读**占位 div 的矩形——占位在哪、多大，原生视图就贴哪、多大。
+
+即：反向喂占位的「一条轴的大小」，正向把占位的「完整矩形」投到原生视图上。占位 div 是几何的**唯一真相**，两端都围着它转。
+
+### 闭环（以 toolbar 为例）
+
+```
+宿主渲染进程                          宿主主进程           下游渲染进程（toolbar 自己的页面）
+──────────                          ────────            ────────────────────────────
+[占位 div]                                               [内容 wrapper（shrink-to-fit）]
+  │ ▲                                                      │
+  │ │ ② decide 把高写进占位 div                             │ ① createSizeAdvertiser
+  │ │    div.style.height = clamp(size.extent)             │    量 wrapper 的 block-size
+  │ └─────────── IPC ◀─────────────────────────────────────┘    publish(size) ──▶
+  │
+  │ ③ 占位 div 尺寸变 → createViewAnchor 的 ResizeObserver 触发
+  │    量占位新矩形 → publish(bounds)
+  ▼
+  ──── IPC ──▶ ④ view.setBounds(bounds) ──▶ [WebContentsView（这块 toolbar）]
+                                               │ 视图变 → 下游 viewport 变 → 内容重新布局
+                                               └──▶ 回到 ① advertiser 再量（收敛）
+```
+
+1. **下游**：`createSizeAdvertiser(wrapper, { axis:'block', publish })` 量内容高 → IPC 发回宿主。
+2. **宿主**：纯函数 `decide(size, { axis, min, max, available })` 夹一夹，把结果写进**占位 div 的高**（`div.style.height = …`）。
+3. **宿主**：占位 div 高一变，`createViewAnchor` 挂在它上的 `ResizeObserver` 立刻触发 → 量出占位新矩形（宽 = 宿主布局给的满宽，高 = 刚写进去的内容高）→ `publish(bounds)`。
+4. **宿主主进程**：`view.setBounds(bounds)` → toolbar 这块 `WebContentsView` 变成新尺寸 → 下游 viewport 变 → 内容重新布局 → 回到 ①。
+
+### 谁负责什么
+
+| 角色 | 谁提供 | 在 view-anchor 里？ |
+|---|---|---|
+| `createSizeAdvertiser`（量内容 → 发 size） | view-anchor | ✅ |
+| `createViewAnchor`（量占位 → 发 bounds） | view-anchor | ✅ |
+| `decide`（把 size 写进占位 div 的高）+ 两条 IPC 通道 | **宿主（workbench）** | ❌（刻意，属宿主胶水） |
+| 占位 div、shrink-to-fit wrapper | 调用方的 DOM | ❌ |
+
+- 收敛逻辑收进宿主一个**纯函数** `decide(...)`（可单测、无跨进程协议）。`decide` 住宿主侧，**不进 view-anchor**——包只出两个单向原语，不出收敛策略，否则就从原语滑向框架（§7）。
+- 连续交互（拖窗改宽）走宿主**单向**路径，不进闭环；反向只服务下游内容的**离散**尺寸变化。
+
+## 6. 与 Electron preferred-size 的关系（宿主侧可选数据源，非替代）
+
+宿主若在 Electron 且能接受零下游代码，可用 `enablePreferredSizeMode` + `preferred-size-changed` 作为反向「**源**」喂给同一个 `decide`，省掉下游注入。但它是 Electron 私有，且依赖两个前提：① 在 `WebContentsView` 上触发且上报值吸收 zoom；② `setBounds.height` 不回灌 layout（否则正反馈震荡）。
+
+view-anchor 的反向原语是**引擎无关/可移植**那条路（非 Electron / iframe 宿主、需选子 target 的场景）。两者并存：preferred-size 是 Electron 捷径，advertiser 是可移植机制，`decide` + §4 安全红线是二者共用的公共底座。这也是反向逻辑留在 view-anchor、而非写死成 Electron 事件的理由——宿主选哪个**源**不改变反向原语本身。
+
+## 7. 包定位守恒（一个原语，不是框架）
+
+view-anchor 是「DOM 几何 ↔ 跨进程视图」的**单一职责双向桥**。守住四条即不滑向框架：① 导出面只含 `createViewAnchor` / `createPlacementAnchor` / `createSizeAdvertiser` / `measurePlacement` / `useViewAnchor` + 其类型；② `createMeasureLoop` 不导出；③ 不提供 React 反向适配（下游不保证是 React）；④ `decide` 留宿主、不进包。

package/docs/mechanism.mdx

@@ -0,0 +1,119 @@
+---
+title: view-anchor
+description: 让主进程原生视图（Electron WebContentsView）始终贴住一个 DOM 元素的矩形。
+---
+
+# view-anchor
+
+让一块主进程原生视图（Electron `WebContentsView`）始终贴住一个 DOM 元素的屏幕矩形。它测量目标元素的 `getBoundingClientRect()`，把矩形交给注入的 `publish` 回调（由你接上 IPC → `setBounds`），并在元素位移或缩放时重新发布。
+
+核心不依赖 React、Electron 或任何宿主布局引擎；涉及 React 的代码只在适配层。
+
+<iframe
+  src="./anchor-3d.html"
+  title="view-anchor 交互演示"
+  style={{ width: '100%', height: '560px', border: '0', borderRadius: '12px' }}
+/>
+
+## 架构
+
+```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
+```
+
+`WebContentsView` 是主进程对象，位置只能由主进程 `setBounds` 设定；而布局是渲染进程用 CSS 算的。两边不直接接触，view-anchor 就是它们之间的桥：占位 div 在 DOM 里占位但不渲染，原生视图浮在其上，由 view-anchor 维持贴合。`publish` 是注入的，所以核心对 Electron 一无所知——测试里它是 spy，生产里是一次 IPC 发送。
+
+## createViewAnchor(target, opts)
+
+命令式核心，把一块原生视图绑定到一个元素，返回 `{ update, dispose }`。
+
+```ts
+const handle = createViewAnchor(target, {
+  present: true,                 // 是否挂载原生视图
+  publish: (bounds) => { ... },  // 接收实时矩形，负责 IPC → setBounds
+})
+```
+
+| 状态 / 调用 | 行为 |
+|---|---|
+| `present: true` | 立即发布测量矩形，之后在每次 `ResizeObserver` 触发、窗口 `resize` 时**同步**重新发布。 |
+| `present: false` | 停止观察，发布一次 `{0,0,0,0}`。 |
+| `update(opts)` | 按新选项同步重新应用（重置去重基线，强制重发一次）。 |
+| `dispose()` | 停止观察、移除监听，此后不再发布（也不补发零矩形）。 |
+
+测量矩形按 `Math.round` 取整；**width/height 钳到 ≥0（0=隐藏信号），但 x/y 允许负**——元素滚出上 / 左边缘时原点本就该是负的，钳零会把原生视图钉在边缘而非跟随它移出屏外（各消费者的 IPC schema 自己定 origin 策略）。
+
+**同步发布，不走 RAF**：原生 overlay 是跨进程 `WebContentsView`，`setBounds` 本就比渲染进程的 DOM 绘制晚约 1 个合成帧；再用 RAF 推迟一帧 → 拖拽时 overlay 可见拖尾（放大时露背景最明显）。在触发回调里直接测量+发布去掉这一自加的帧。RAF 原本承担的「合并同帧多次触发」由**同值去重**接管：若本次测量矩形与上次已发布的逐字段相等就丢弃，所以一次连续拖拽里每个不同矩形至多发一次。`update` 会先把去重基线清空，保证状态变化（zoom 骑在 `publish` 闭包里、不在 `Bounds` 里）即使几何不变也重发一次。
+
+撤销安全：没有排队的帧可以「跑赢」状态变化——每次发布开头同步读 `disposed`/`present`，`update`/`dispose` 之后的触发立即 bail。
+
+## present / 零矩形 语义
+
+- **`present`** —— 「原生视图是否该挂载」的唯一事实来源，与 DOM 生命周期解耦。
+- **`{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 回调。
+
+```tsx
+const ref = useViewAnchor({
+  present,            // boolean
+  publish,            // (bounds) => void
+  deps: [signature],  // 可选：会移动矩形、但 DOM 看不见的状态
+})
+return <div ref={ref} />
+```
+
+| 时机 | 行为 |
+|---|---|
+| 挂载 | `createViewAnchor(el, opts)` |
+| `opts` / `deps` 变化 | `update` |
+| 卸下（`ref → null`）或卸载 | 先发一帧零矩形，再 `dispose` |
+
+**`deps`** —— `ResizeObserver` 只响应纯几何变化。会移动矩形却不改变被观察元素尺寸的状态（布局拓扑签名、路由切换、兄弟标签页 `display:none`）要放进 `deps`。数组长度需在每次渲染间保持稳定。
+
+> 适配层已处理 React 18 StrictMode 的 effect 双触发，以及 hidden→shown 重挂载——保证恰好发布一次真实矩形、不误发零矩形。
+
+## 文件
+
+| 文件 | 作用 |
+|---|---|
+| `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` 只在反向 `createSizeAdvertiser`（经 `createMeasureLoop`）和 `createPlacementAnchor` 的 opt-in `followGeometry` 哨兵里用；正向的 `createViewAnchor` 同步发布、不走 RAF。

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "view-anchor",
+  "version": "0.1.1",
+  "description": "Engine-agnostic primitive that keeps a main-process native view (Electron WebContentsView) aligned to a DOM element's geometry.",
+  "keywords": [
+    "electron",
+    "webcontentsview",
+    "layout",
+    "react"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "author": "lbb00",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lbb00/view-anchor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lbb00/view-anchor/issues"
+  },
+  "homepage": "https://github.com/lbb00/view-anchor#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.*",
+    "!**/*.spec.*"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@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.1",
+    "eslint": "^10.2.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-only-warn": "^1.2.1",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.5.0",
+    "jsdom": "^29.0.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "5.9.2",
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && pnpm run build:docs",
+    "build:docs": "node scripts/build-docs.mjs",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "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"
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * view-anchor — engine-agnostic primitive that keeps a main-process native
+ * view (Electron `WebContentsView`) aligned to a DOM element's geometry.
+ *
+ * Public surface:
+ *   - `createViewAnchor`    — forward: DOM rect → native view bounds.
+ *   - `useViewAnchor`       — React adapter returning a ref callback.
+ *   - `createSizeAdvertiser`— reverse: downstream content size → host.
+ *   - `Bounds` / `AdvertisedSize` / option + handle types.
+ *
+ * Self-contained on purpose: the only runtime deps are `react` (adapter
+ * only) and browser APIs (`ResizeObserver` / `requestAnimationFrame` /
+ * `getBoundingClientRect`). See the design notes and the interactive 3D
+ * walkthrough in `docs/` (`mechanism.mdx` / `anchor-3d.html`).
+ */
+export {
+  createViewAnchor,
+  measurePlacement,
+  createPlacementAnchor,
+} from './view-anchor.js'
+export type {
+  PlacementAnchorOptions,
+  PlacementAnchorHandle,
+} from './view-anchor.js'
+export type {
+  Bounds,
+  Placement,
+  ViewAnchorOptions,
+  ViewAnchorHandle,
+} from './types.js'
+export { useViewAnchor } from './react.js'
+export type { UseViewAnchorOptions, ViewAnchorRef } from './react.js'
+export { createSizeAdvertiser } from './size-advertiser.js'
+export type {
+  AdvertisedAxis,
+  AdvertisedSize,
+  SizeAdvertiserOptions,
+  SizeAdvertiserHandle,
+} from './types.js'

package/src/measure-loop.ts

@@ -0,0 +1,87 @@
+/**
+ * Internal — the RAF-coalesced measure/dedupe/dispose engine behind the REVERSE
+ * primitive `createSizeAdvertiser`.
+ *
+ * The forward `createViewAnchor` deliberately does NOT use this: it publishes
+ * SYNCHRONOUSLY (a native overlay's `setBounds` already lands a cross-process
+ * frame late, and a RAF stacked a second frame of visible trailing). The
+ * reverse direction is different — it is a cross-process FEEDBACK loop
+ * (advertise → host resizes the view → content re-measures → re-advertise), so
+ * the RAF's one-publish-per-frame coalescing is a useful damper. The two
+ * directions thus have different optimal emit timing; this engine serves only
+ * the reverse.
+ *
+ * NOT exported from the package: it is pure mechanism with no knowledge of
+ * direction, the DOM, `ResizeObserver`, or the structure of the value `T` it
+ * carries. The wrapping primitive injects `produce` / `same` / `sink` and
+ * drives the lifecycle.
+ *
+ *   - `schedule()`  — coalesce a burst of triggers into ONE RAF; the frame
+ *     body re-`produce()`s, dedupes against the last emit (`same`), and `sink`s.
+ *     Bails if inactive or disposed (stale-RAF safe).
+ *   - `emitNow(v)`  — explicit synchronous emit (create / update path). Always
+ *     fires, bypassing the dedupe check, and refreshes the dedupe baseline.
+ *   - `setActive`   — gate the observer stream; a queued frame bails on `!active`.
+ *   - `cancel`      — drop any in-flight RAF.
+ *   - `dispose`     — cancel + go inert; after dispose nothing emits again.
+ */
+export interface MeasureLoop<T> {
+  schedule(): void
+  emitNow(value: T): void
+  setActive(on: boolean): void
+  cancel(): void
+  dispose(): void
+}
+
+export function createMeasureLoop<T>(cfg: {
+  /** Produce the value to emit in the RAF body. Return `null` to decline the
+   *  frame entirely (no dedupe, no sink, baseline untouched) — e.g. a
+   *  non-finite or unavailable measurement. */
+  produce: () => T | null
+  same: (a: T, b: T) => boolean
+  sink: (value: T) => void
+}): MeasureLoop<T> {
+  const { produce, same, sink } = cfg
+  let rafId: number | null = null
+  let active = false
+  let disposed = false
+  let last: T | null = null
+
+  const cancel = (): void => {
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
+  }
+
+  return {
+    schedule(): void {
+      if (disposed || !active || rafId !== null) return
+      rafId = requestAnimationFrame(() => {
+        rafId = null
+        if (disposed || !active) return
+        const value = produce()
+        if (value === null) return // producer declined this frame
+        // last-value dedupe: a frame whose produced value equals the last one
+        // we emitted costs nothing (no IPC / setBounds).
+        if (last !== null && same(value, last)) return
+        last = value
+        sink(value)
+      })
+    },
+    emitNow(value: T): void {
+      if (disposed) return
+      last = value
+      sink(value)
+    },
+    setActive(on: boolean): void {
+      active = on
+    },
+    cancel,
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      cancel()
+    },
+  }
+}

package/src/react.ts

@@ -0,0 +1,171 @@
+import { useCallback, useEffect, useRef } from 'react'
+import { createViewAnchor } from './view-anchor.js'
+import type { Bounds, ViewAnchorHandle, ViewAnchorOptions } from './types.js'
+
+/**
+ * React adapter over the imperative `createViewAnchor` core.
+ *
+ * (React lint forces the `use` prefix on any hook returning a ref
+ * callback; the library's identity is still the `ViewAnchor` core — this is
+ * just the React binding.)
+ */
+export interface UseViewAnchorOptions extends ViewAnchorOptions {
+  /**
+   * Non-DOM dependencies that move the target's rect and must force a
+   * re-publish (layout signature, project path, a tab toggle's
+   * `display:none`, …). A `ResizeObserver` covers pure geometry; `deps`
+   * covers state it cannot see. Keep the array length stable across
+   * renders (React effect-deps rule).
+   */
+  deps?: ReadonlyArray<unknown>
+}
+
+export type ViewAnchorRef = (el: HTMLElement | null) => void
+
+/**
+ * Bind a native view's bounds to whichever DOM element the returned ref
+ * callback is attached to. On attach → `createViewAnchor(el, opts)`; on
+ * detach (`null`) → publish ZERO then `dispose()`; on `opts`/`deps` change →
+ * `update`; on unmount → publish ZERO then `dispose`.
+ *
+ * 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
+ * receives `{0,0,0,0}` (isHidden). In production the debug cell is *unmounted*
+ * (not `display:none`) when hidden, so the ref goes to `null` and the native
+ * view would otherwise stay frozen at its last bounds, floating on
+ * top and occluding content. So the adapter (not core) must emit one ZERO via
+ * the already-tested `update({ present:false })` path before disposing.
+ */
+export function useViewAnchor(opts: UseViewAnchorOptions): ViewAnchorRef {
+  const handleRef = useRef<ViewAnchorHandle | null>(null)
+  const elRef = useRef<HTMLElement | null>(null)
+  // Latest opts, read by the stable ref callback when it creates the anchor.
+  // Synced render-synchronously (NOT in an effect): the ref callback reads
+  // `optsRef.current` during *commit* (when the element attaches), which runs
+  // before passive effects. An effect-synced ref would be one render stale at
+  // that point, so a hidden→shown remount (`present` flips false→true together
+  // with the element re-mounting, exactly what the debug cell does) would
+  // create the anchor with the old `present:false` and emit a spurious ZERO
+  // before the real rect. A render write keeps it current at commit, and is
+  // idempotent under StrictMode's double render.
+  const optsRef = useRef(opts)
+  // eslint-disable-next-line react-hooks/refs -- see above: must be current at commit, before effects run
+  optsRef.current = opts
+
+  // Baseline for the re-apply effect's change detection. Declared here (before
+  // the ref callback) so the callback can re-seed it on (re)create.
+  const appliedRef = useRef<ReadonlyArray<unknown>>([
+    opts.present,
+    opts.publish,
+    ...(opts.deps ?? []),
+  ])
+
+  // Collapse the native view (publish ZERO) and tear the anchor down. Reuse
+  // the existing, tested `update({ present:false })` path: it synchronously
+  // publishes `{0,0,0,0}` and stops observing (core Contract 5), then
+  // `dispose()` makes the anchor inert. Idempotent via the `handleRef.current`
+  // null-check so the two callers below can never double-emit ZERO.
+  const collapseAndDispose = useRef((): void => {
+    const handle = handleRef.current
+    if (!handle) return
+    handle.update({ present: false, publish: optsRef.current.publish })
+    handle.dispose()
+    handleRef.current = null
+  })
+
+  const ref = useCallback<ViewAnchorRef>((el) => {
+    if (el === elRef.current) return
+    elRef.current = el
+    if (handleRef.current) {
+      if (el) {
+        // Swapping to *another* live element: dispose the old anchor without a
+        // ZERO. The new element publishes its real rect immediately below, so
+        // a transient ZERO between the two would only cause a needless
+        // detach/re-attach flicker of the native view.
+        handleRef.current.dispose()
+        handleRef.current = null
+      } else {
+        // Element detached (ref → null): the anchor point is gone, so collapse
+        // the native view (one ZERO) before disposing.
+        collapseAndDispose.current()
+      }
+    }
+    if (el) {
+      handleRef.current = createViewAnchor(el, {
+        present: optsRef.current.present,
+        publish: optsRef.current.publish,
+      })
+      // The anchor was just created at the current (present, publish, deps), so
+      // seed the re-apply baseline to match. Otherwise the post-commit re-apply
+      // effect would see this fresh state as a change and publish a second time
+      // — on a remount with a changed `present` that is a double-emit.
+      appliedRef.current = [
+        optsRef.current.present,
+        optsRef.current.publish,
+        ...(optsRef.current.deps ?? []),
+      ]
+    }
+  }, [])
+
+  // Re-apply on opts/deps change. We must `update` whenever the
+  // (present, publish, …deps) tuple actually changes, but NOT on the mount run
+  // (the ref callback already created the anchor and published once) and NOT on
+  // a StrictMode replay (dev double-fires this effect's setup with the *same*
+  // tuple — a blind `update` then re-publishes the mount rect a second time).
+  // So instead of guessing "is this the first run?", compare against the
+  // last-applied tuple and apply only on a genuine change. The tuple is seeded
+  // with the mount opts, so the mount run and its StrictMode replay both see
+  // "unchanged" and skip — idempotent by construction. `deps` keeps a stable
+  // length across renders (documented above), so positional compare is sound.
+  useEffect(() => {
+    const next: ReadonlyArray<unknown> = [
+      opts.present,
+      opts.publish,
+      ...(opts.deps ?? []),
+    ]
+    const prev = appliedRef.current
+    const changed =
+      next.length !== prev.length || next.some((v, i) => !Object.is(v, prev[i]))
+    if (!changed) return
+    appliedRef.current = next
+    handleRef.current?.update({ present: opts.present, publish: opts.publish })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [opts.present, opts.publish, ...(opts.deps ?? [])])
+
+  // Collapse the native view + dispose on teardown.
+  //
+  // StrictMode-safe lifecycle: this effect's setup/cleanup is double-fired in
+  // dev (setup → cleanup → setup). The anchor itself is created/owned by the
+  // ref callback, which in React 18 fires exactly once on mount and once with
+  // `null` on a real detach — it is NOT replayed by StrictMode. So this effect
+  // must not destroy the ref-owned anchor on a *throwaway* unmount, or the
+  // re-setup would have nothing to restore.
+  //
+  // Discriminator: on a real teardown React detaches the element first
+  // (`ref(null)` → `elRef.current === null`, and that path already emitted the
+  // single ZERO + disposed); on a StrictMode throwaway unmount the element is
+  // still attached (`elRef.current !== null`, ref never fired `null`). So we
+  // only collapse here when the element is genuinely gone, and otherwise leave
+  // the live anchor intact for the immediate re-setup.
+  //
+  // The setup re-establishes the anchor if a prior cleanup ever tore it down
+  // while the element is still attached, keeping setup/cleanup symmetric.
+  useEffect(() => {
+    const collapse = collapseAndDispose.current
+    if (elRef.current && !handleRef.current) {
+      handleRef.current = createViewAnchor(elRef.current, {
+        present: optsRef.current.present,
+        publish: optsRef.current.publish,
+      })
+    }
+    return () => {
+      if (elRef.current === null) collapse()
+    }
+  }, [])
+
+  return ref
+}
+
+export type { Bounds }