view-anchor 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lbb00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# view-anchor
+
+> An engine-agnostic primitive that keeps a main-process native view aligned to a DOM element's geometry.
+
+[![npm version](https://img.shields.io/npm/v/view-anchor)](https://www.npmjs.com/package/view-anchor)
+[![npm downloads](https://img.shields.io/npm/dm/view-anchor)](https://www.npmjs.com/package/view-anchor)
+[![License](https://img.shields.io/npm/l/view-anchor)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
+
+[English](./README.md) · [简体中文](./README.zh-CN.md)
+
+In Electron, a native `WebContentsView` lives in the main process while your layout lives in the renderer. Layout libraries (flexbox, dockview, react-resizable-panels…) only move DOM nodes — they have no idea where the process boundary is. `view-anchor` is the bridge across it: it measures a target element's `getBoundingClientRect()`, hands the rectangle to a `publish` callback (your IPC → `setBounds`), and re-publishes whenever the element moves or resizes.
+
+The core has no dependencies on React, Electron, or any host layout engine. React code lives only in the adapter layer.
+
+## Features
+
+- **One-to-one binding** — a single native view follows a single DOM element. `update()` applies new options and re-publishes immediately.
+- **Synchronous, deduplicated publishes** — measures and publishes in the same observer tick, so the native view never trails the DOM by more than the unavoidable cross-process frame. Rects identical to the last publish are dropped.
+- **Collapse without destroying** — `present: false` publishes a zero rect and stops observing; the host can detach the subview while keeping the `WebContents` alive.
+- **Explicit visibility** — the `Placement` API distinguishes a genuinely 0×0-but-visible view from a hidden one, instead of inferring visibility from geometry.
+- **Content-driven sizing (reverse direction)** — `createSizeAdvertiser` reports a view's own content size back so a DOM placeholder can grow to match.
+- **React adapter** — `useViewAnchor` hook that attaches to a placeholder element.
+- **Zero-dependency core** — no React, no Electron, no layout-engine imports in the core.
+
+## Installation
+
+```bash
+pnpm add view-anchor
+# or
+npm install view-anchor
+```
+
+React is an optional peer dependency; you only need it for the `useViewAnchor` adapter.
+
+## Quick start
+
+### Imperative core
+
+```ts
+import { createViewAnchor } from 'view-anchor'
+
+const handle = createViewAnchor(target, {
+  present: true,                 // mount the native view
+  publish: (bounds) => { ... },  // receive live rectangles; wire IPC → setBounds
+})
+
+handle.update({ present, publish }) // apply new options, re-publishes immediately
+handle.dispose()                    // stop observing; never publishes again
+```
+
+### React
+
+```tsx
+import { useViewAnchor } from 'view-anchor'
+
+function DebugPanel({ visible }: { visible: boolean }) {
+  const ref = useViewAnchor({
+    present: visible,
+    publish: publishPanelBounds,
+  })
+  // The native view follows this placeholder div. Hiding the panel
+  // (visible=false or unmount) collapses it without destroying it.
+  return <div ref={ref} className="h-full w-full" />
+}
+```
+
+### Reverse: content size reporting
+
+When a `WebContentsView`'s size is driven by its own content (for example a toolbar owned by downstream code), run inside that view's own renderer process:
+
+```ts
+import { createSizeAdvertiser } from 'view-anchor'
+
+const handle = createSizeAdvertiser(contentWrapper, {
+  axis: 'block',                 // this advertiser owns one axis only (block=height / inline=width)
+  publish: (size) => { ... },    // receives { axis, extent }; wire IPC → host
+})
+
+handle.update(publish) // swap the publish channel and immediately report the current size
+handle.dispose()       // stop observing; never reports again
+```
+
+> **Warning:** the `target` must shrink-to-fit on the owned axis — if its size is set by the hosted view instead, the cross-process loop cannot converge. See [docs/bidirectional-design.md](./docs/bidirectional-design.md).
+
+## API
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `createViewAnchor(target, opts)` | function | Imperative core: measure and publish live bounds. Zero rect means collapsed. |
+| `createPlacementAnchor(target, opts)` | function | Same core with explicit `Placement` visibility, plus opt-in `followScroll` / `followGeometry` / `guardDisplayNone` and `pulse()`. |
+| `measurePlacement(target)` | function | Pure measurement: wraps the target rect as `{ visible: true, bounds }`. |
+| `useViewAnchor(opts)` | hook | React adapter returning a ref callback for a placeholder element. |
+| `createSizeAdvertiser(target, opts)` | function | Reverse core: report the view's own content size to the host. |
+| `Bounds` | type | `{ x, y, width, height }` in CSS pixels. |
+| `Placement` | type | `{ visible: true; bounds } \| { visible: false }` — explicit visibility. |
+| `ViewAnchorOptions` / `ViewAnchorHandle` | type | Options and handle for the forward zero-rect core. |
+| `PlacementAnchorOptions` / `PlacementAnchorHandle` | type | Options and handle for the `Placement` core. |
+| `UseViewAnchorOptions` / `ViewAnchorRef` | type | Options and ref shape for the React adapter. |
+| `AdvertisedAxis` / `AdvertisedSize` | type | Reverse axis and frame payload types. |
+| `SizeAdvertiserOptions` / `SizeAdvertiserHandle` | type | Options and handle for the reverse core. |
+
+## Documentation
+
+- [docs/mechanism.mdx](./docs/mechanism.mdx) — the forward mechanism in depth: synchronous publishing and stale-frame safety, the `present` / zero-rect / unmount contract, React 18 StrictMode behavior. Includes an interactive 3D demo at [docs/anchor-3d.html](./docs/anchor-3d.html).
+- [docs/bidirectional-design.md](./docs/bidirectional-design.md) — the bidirectional geometry bridge: the intentional sync/RAF asymmetry, single-axis ownership and convergence, trust boundaries.
+
+## Contributing
+
+Issues and pull requests are welcome. Before submitting, run the checks locally: `pnpm lint`, `pnpm check-types`, `pnpm test`, `pnpm build`.
+
+## License
+
+[MIT](./LICENSE) © lbb00

package/README.zh-CN.md

@@ -0,0 +1,114 @@
+# view-anchor
+
+> 让主进程的原生视图（Electron `WebContentsView`）始终对齐某个 DOM 元素的几何位置的引擎无关原语。
+
+[![npm version](https://img.shields.io/npm/v/view-anchor)](https://www.npmjs.com/package/view-anchor)
+[![npm downloads](https://img.shields.io/npm/dm/view-anchor)](https://www.npmjs.com/package/view-anchor)
+[![License](https://img.shields.io/npm/l/view-anchor)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
+
+[English](./README.md) · [简体中文](./README.zh-CN.md)
+
+在 Electron 里，原生 `WebContentsView` 住主进程，你的布局在渲染进程。DOM 布局库（flexbox、dockview、react-resizable-panels……）只移动 DOM 节点，不知道这道进程边界的存在。`view-anchor` 就是跨过这道边界的桥：它测量目标元素的 `getBoundingClientRect()`，把矩形交给一个 `publish` 回调（由你接上 IPC → `setBounds`），并在元素位移或缩放时重新发布。
+
+核心不依赖 React、Electron 或任何宿主布局引擎。涉及 React 的代码只在适配层。
+
+## 特性
+
+- **一对一绑定** —— 一个原生视图跟随一个 DOM 元素。`update()` 应用新选项并立即重新发布。
+- **同步、去重的发布** —— 在同一个观察回调里测量并发布，原生视图不会比 DOM 多拖一帧（除不可避免的跨进程帧外）。与上次逐字段相同的矩形会被跳过。
+- **收起而不销毁** —— `present: false` 发布零矩形并停止观察；宿主可以摘除子视图但保留 `WebContents` 存活。
+- **显式可见性** —— `Placement` API 能区分「真正 0×0 但在屏」和「隐藏」的视图，而不是从尺寸推断可见性。
+- **反向：内容尺寸回流** —— `createSizeAdvertiser` 把视图自身内容的尺寸回报给宿主，让 DOM 占位跟着内容长。
+- **React 适配层** —— `useViewAnchor` hook，挂到一个占位元素上即可。
+- **核心零依赖** —— 核心不 import React、Electron 或任何布局引擎。
+
+## 安装
+
+```bash
+pnpm add view-anchor
+# 或
+npm install view-anchor
+```
+
+React 是可选 peer 依赖，只有用 `useViewAnchor` 适配层时才需要。
+
+## 快速上手
+
+### 命令式核心
+
+```ts
+import { createViewAnchor } from 'view-anchor'
+
+const handle = createViewAnchor(target, {
+  present: true,                 // 挂载原生视图
+  publish: (bounds) => { ... },  // 接收实时矩形；由它负责 IPC → setBounds
+})
+
+handle.update({ present, publish }) // 应用新选项（会立即重新发布）
+handle.dispose()                    // 停止观察；此后不再发布
+```
+
+### React
+
+```tsx
+import { useViewAnchor } from 'view-anchor'
+
+function DebugPanel({ visible }: { visible: boolean }) {
+  const ref = useViewAnchor({
+    present: visible,
+    publish: publishPanelBounds,
+  })
+  // 原生视图跟随这个占位 div。隐藏面板
+  // （visible=false 或卸载）会让它收起，但不销毁。
+  return <div ref={ref} className="h-full w-full" />
+}
+```
+
+### 反向：内容尺寸上报
+
+当一块 `WebContentsView` 的尺寸由它**自己的内容**主导时（例如交给下游控制的 toolbar），在**下游视图自己的渲染进程**里跑：
+
+```ts
+import { createSizeAdvertiser } from 'view-anchor'
+
+const handle = createSizeAdvertiser(contentWrapper, {
+  axis: 'block',                 // 这个 advertiser 只主导一条轴（block=高 / inline=宽）
+  publish: (size) => { ... },    // 接收 { axis, extent }，由它负责 IPC → 宿主
+})
+
+handle.update(publish) // 换 publish（IPC 通道），并立即把当前尺寸发给它
+handle.dispose()       // 停止观察；此后不再上报
+```
+
+> **注意 footgun**：`target` 必须在主导轴上 shrink-to-fit——如果它的尺寸由宿主灌入的视图尺寸反向决定，跨进程环不会收敛。详见 [docs/bidirectional-design.md](./docs/bidirectional-design.md)。
+
+## API
+
+| 导出 | 类型 | 作用 |
+|---|---|---|
+| `createViewAnchor(target, opts)` | 函数 | 正向命令式核心：测量并发布实时边界。零矩形表示收起。 |
+| `createPlacementAnchor(target, opts)` | 函数 | 同款核心的显式 `Placement` 变体，另有 opt-in 的 `followScroll` / `followGeometry` / `guardDisplayNone` 与 `pulse()`。 |
+| `measurePlacement(target)` | 函数 | 纯测量：把目标矩形包成 `{ visible: true, bounds }`。 |
+| `useViewAnchor(opts)` | Hook | React 适配层，返回挂占位元素的 ref 回调。 |
+| `createSizeAdvertiser(target, opts)` | 函数 | 反向核心：把视图自身内容尺寸回报给宿主。 |
+| `Bounds` | 类型 | `{ x, y, width, height }`，单位 CSS 像素。 |
+| `Placement` | 类型 | `{ visible: true; bounds } \| { visible: false }` —— 显式可见性。 |
+| `ViewAnchorOptions` / `ViewAnchorHandle` | 类型 | 正向零矩形核心的选项与句柄形状。 |
+| `PlacementAnchorOptions` / `PlacementAnchorHandle` | 类型 | `Placement` 核心的选项与句柄形状。 |
+| `UseViewAnchorOptions` / `ViewAnchorRef` | 类型 | React 适配层的选项与 ref 形状。 |
+| `AdvertisedAxis` / `AdvertisedSize` | 类型 | 反向的轴与帧载荷类型。 |
+| `SizeAdvertiserOptions` / `SizeAdvertiserHandle` | 类型 | 反向核心的选项与句柄形状。 |
+
+## 文档
+
+- [docs/mechanism.mdx](./docs/mechanism.mdx) —— 正向机制的完整说明：同步发布与陈旧帧安全、`present` / 零矩形 / 卸载契约、React 18 StrictMode 行为。内含可交互 3D 演示 [docs/anchor-3d.html](./docs/anchor-3d.html)。
+- [docs/bidirectional-design.md](./docs/bidirectional-design.md) —— 双向几何桥：同步 / RAF 的刻意不对称、单轴所有权与收敛性、信任边界。
+
+## 贡献
+
+欢迎提 issue 和 PR。提交前请在本地跑一遍：`pnpm lint`、`pnpm check-types`、`pnpm test`、`pnpm build`。
+
+## License
+
+[MIT](./LICENSE) © lbb00

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,MAAM,EACN,SAAS,EACT,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3D,YAAY,EACV,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * 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 { useViewAnchor } from './react.js';
+export { createSizeAdvertiser } from './size-advertiser.js';

package/dist/measure-loop.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 declare 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>;
+//# sourceMappingURL=measure-loop.d.ts.map

package/dist/measure-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-loop.d.ts","sourceRoot":"","sources":["../src/measure-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,IAAI,IAAI,CAAA;IAChB,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAA;IACvB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IAC5B,MAAM,IAAI,IAAI,CAAA;IACd,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE;IACxC;;iDAE6C;IAC7C,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IACvB,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAA;IAC7B,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;CACzB,GAAG,WAAW,CAAC,CAAC,CAAC,CA4CjB"}

package/dist/measure-loop.js

@@ -0,0 +1,49 @@
+export function createMeasureLoop(cfg) {
+    const { produce, same, sink } = cfg;
+    let rafId = null;
+    let active = false;
+    let disposed = false;
+    let last = null;
+    const cancel = () => {
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    };
+    return {
+        schedule() {
+            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) {
+            if (disposed)
+                return;
+            last = value;
+            sink(value);
+        },
+        setActive(on) {
+            active = on;
+        },
+        cancel,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            cancel();
+        },
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,38 @@
+import type { Bounds, 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 declare function useViewAnchor(opts: UseViewAnchorOptions): ViewAnchorRef;
+export type { Bounds };
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAoB,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE7E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAA;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAgIvE;AAED,YAAY,EAAE,MAAM,EAAE,CAAA"}

package/dist/react.js

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { createViewAnchor } from './view-anchor.js';
+/**
+ * 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) {
+    const handleRef = useRef(null);
+    const elRef = useRef(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([
+        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(() => {
+        const handle = handleRef.current;
+        if (!handle)
+            return;
+        handle.update({ present: false, publish: optsRef.current.publish });
+        handle.dispose();
+        handleRef.current = null;
+    });
+    const ref = useCallback((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 = [
+            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;
+}

package/dist/size-advertiser.d.ts

@@ -0,0 +1,21 @@
+import type { SizeAdvertiserOptions, SizeAdvertiserHandle } from './types.js';
+/**
+ * Reverse of `createViewAnchor`: runs in a downstream WebContentsView's own
+ * renderer, measures the content's own size on ONE owned axis (from the
+ * `ResizeObserver` border-box — no `getBoundingClientRect`, no forced reflow),
+ * and advertises it via the injected `publish`. Shares the forward primitive's
+ * measure/coalesce/dedupe/dispose engine (`createMeasureLoop`).
+ *
+ * The extent is `Math.round`ed and clamped to `>= 0`; non-finite measurements
+ * drop the frame.
+ *
+ * FOOTGUN — `target` must be shrink-to-fit on the owned axis: its owned-axis
+ * size must NOT be driven by the host-applied view size, or the cross-process
+ * loop (advertise → host resizes view → remeasure) never converges (it
+ * oscillates or stays "stable but wrong"). Measuring `<body>`/`<html>` is the
+ * classic mistake — their size *is* the view size. See
+ * `docs/bidirectional-design.md`'s single-axis-ownership and trust-boundary
+ * sections.
+ */
+export declare function createSizeAdvertiser(target: HTMLElement, opts: SizeAdvertiserOptions): SizeAdvertiserHandle;
+//# sourceMappingURL=size-advertiser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"size-advertiser.d.ts","sourceRoot":"","sources":["../src/size-advertiser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAGnB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,qBAAqB,GAC1B,oBAAoB,CAkEtB"}