@dimina-kit/view-anchor 0.1.0-dev.20260610082053

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EchoTechFE and dimina-kit contributors
+
+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,87 @@
+# @dimina-kit/view-anchor
+
+让一块主进程原生视图（Electron `WebContentsView`）始终贴住某个 DOM 元素的屏幕矩形，一对一绑定。
+
+DOM 布局库（flexbox、dockview、react-resizable-panels……）都不管渲染进程与主进程之间那道边界，它们移动的永远只是 DOM 节点。`view-anchor` 就是跨过这道边界的桥：它测量目标元素的 `getBoundingClientRect()`，把得到的矩形交给一个 `publish` 回调（由你接上 IPC → `setBounds`），并在元素发生位移或缩放时重新发布。
+
+核心不依赖 React、Electron 或任何宿主布局引擎。涉及 React 的代码只在适配层。
+
+## 安装
+
+```sh
+pnpm add @dimina-kit/view-anchor
+```
+
+## 快速上手
+
+命令式核心：
+
+```ts
+import { createViewAnchor } from '@dimina-kit/view-anchor'
+
+const handle = createViewAnchor(target, {
+  present: true,                 // 挂载原生视图
+  publish: (bounds) => { ... },  // 接收实时矩形；由它负责 IPC → setBounds
+})
+
+handle.update({ present, publish }) // 应用新选项（会立即重新发布）
+handle.dispose()                    // 停止观察；此后不再发布
+```
+
+React 适配层：
+
+```tsx
+import { useViewAnchor } from '@dimina-kit/view-anchor'
+
+function DebugPanel({ visible }: { visible: boolean }) {
+  const ref = useViewAnchor({
+    present: visible,
+    publish: publishSimulatorDevtoolsBounds,
+  })
+  // 原生视图会跟随这个占位 div；隐藏面板
+  // （visible=false 或卸载）会让它收起，但不销毁。
+  return <div ref={ref} className="h-full w-full" />
+}
+```
+
+## 工作原理（一句话版）
+
+- `present: true`：立即发布测量矩形，之后在每次 `ResizeObserver` 触发、窗口 `resize` 时**同步**重新发布（不走 RAF——原生 overlay 的 setBounds 本就慢一帧，RAF 再叠一帧会拖尾）。与上次逐字段相同的矩形会被去重跳过。x/y 取整但**允许负**（滚出边缘时跟随），width/height 钳到 ≥0。
+- `present: false`：发布一次 `{0,0,0,0}` 并停止观察（已有的观察器一并拆除）。宿主把「面积为零」读作「摘除子视图，但保留其 `WebContents` 存活」，即收起而非销毁。
+- `dispose()` 之后不再发布任何内容，也不会补发一帧零矩形（那是调用方的责任；React 适配层已替你在元素消失时处理好）。
+
+## 反向：`createSizeAdvertiser`（内容尺寸回流）
+
+正向让原生视图跟随 DOM；反向让 DOM 占位跟随内容。当一块 `WebContentsView` 的尺寸由它**自己的内容**主导时（例如交给下游控制的 toolbar），在**下游视图自己的渲染进程**里跑：
+
+```ts
+import { createSizeAdvertiser } from '@dimina-kit/view-anchor'
+
+const handle = createSizeAdvertiser(contentWrapper, {
+  axis: 'block',                 // 这个 advertiser 只主导一条轴（block=高 / inline=宽），不可变
+  publish: (size) => { ... },    // 接收 { axis, extent }，由它负责 IPC → 宿主
+})
+
+handle.update(publish) // 换 publish（IPC 通道），并立即把当前尺寸发给它
+handle.dispose()       // 停止观察；此后不再上报
+```
+
+它从 `ResizeObserver` 的 border-box 取主导轴尺寸（不调 `getBoundingClientRect`、不强制 reflow），`Math.round` + 钳零，复用与正向同一套 RAF 合并 + 去重。宿主收到尺寸后调整占位、再由正向把视图贴上去——两个单向原语经占位 div 串成一座双向桥。**注意 footgun**：`target` 必须在主导轴上 shrink-to-fit（其尺寸不能被宿主灌入的视图尺寸反向决定），否则跨进程环不收敛。详见 [`docs/bidirectional-design.md`](./docs/bidirectional-design.md)。
+
+## 文档
+
+- [`docs/mechanism.mdx`](./docs/mechanism.mdx) —— 正向完整机制：RAF 与陈旧帧安全性、`present` / 零矩形 / 卸载契约、React 18 StrictMode 生命周期。内嵌可交互 3D 演示 [`docs/anchor-3d.html`](./docs/anchor-3d.html)。
+- [`docs/bidirectional-design.md`](./docs/bidirectional-design.md) —— 双向化设计：共享 `createMeasureLoop` 核心、单轴所有权与收敛性、信任边界、以及两个原语如何「锚」到一起。
+
+## API
+
+| 导出 | 类型 | 作用 |
+|---|---|---|
+| `createViewAnchor(target, opts)` | 函数 | 正向命令式核心，返回 `{ update, dispose }`。不依赖 React、不依赖 Electron。 |
+| `useViewAnchor(opts)` | Hook | 正向 React 适配层，返回一个挂到占位元素上的 ref 回调。 |
+| `createSizeAdvertiser(target, opts)` | 函数 | 反向命令式核心，返回 `{ update, dispose }`。下游量内容尺寸回流给宿主。 |
+| `Bounds` | 类型 | `{ x, y, width, height }`，单位为 CSS 像素。 |
+| `ViewAnchorOptions` / `ViewAnchorHandle` | 类型 | 正向核心的选项与句柄形状。 |
+| `UseViewAnchorOptions` / `ViewAnchorRef` | 类型 | 正向适配层的选项与 ref 回调形状。 |
+| `AdvertisedAxis` / `AdvertisedSize` | 类型 | 反向的轴（`'block'\|'inline'`）与帧载荷 `{ axis, extent }`。 |
+| `SizeAdvertiserOptions` / `SizeAdvertiserHandle` | 类型 | 反向核心的选项与句柄形状。 |

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 (P1 fix): 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
+ * DevTools 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 (P1 fix): 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
+ * DevTools 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,20 @@
+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` §4/§5.
+ */
+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;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,qBAAqB,GAC1B,oBAAoB,CAkEtB"}

package/dist/size-advertiser.js

@@ -0,0 +1,82 @@
+import { createMeasureLoop } from './measure-loop.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` §4/§5.
+ */
+export function createSizeAdvertiser(target, opts) {
+    const axis = opts.axis; // immutable for the advertiser's life
+    let publish = opts.publish;
+    let observer = null;
+    let disposed = false;
+    // Latest border-box, stashed by the RO callback and read by `produce` in the
+    // RAF body (keep the entry out of the shared, DOM-agnostic loop).
+    let latest = null;
+    const produce = () => {
+        if (!latest)
+            return null;
+        const raw = axis === 'block' ? latest.blockSize : latest.inlineSize;
+        if (!Number.isFinite(raw))
+            return null;
+        return { axis, extent: Math.max(0, Math.round(raw)) };
+    };
+    const loop = createMeasureLoop({
+        produce,
+        same: (a, b) => a.extent === b.extent, // axis is constant
+        sink: (size) => publish(size),
+    });
+    const onResize = (entries) => {
+        const entry = entries[entries.length - 1];
+        if (entry) {
+            latest = entry.borderBoxSize?.[0] ?? entry.contentBoxSize?.[0] ?? latest;
+        }
+        loop.schedule();
+    };
+    // One cheap, once-per-advertiser guard for the textbook feedback-loop footgun.
+    const doc = target.ownerDocument;
+    if (target === doc.body || target === doc.documentElement) {
+        console.warn(`[view-anchor] size-advertiser: <${target === doc.body ? 'body' : 'html'}>'s ` +
+            `${axis} size is the host-given view size, not the content size — the ` +
+            `advertiser will never shrink to content. Measure a shrink-to-fit wrapper. ` +
+            `See bidirectional-design.md §4.`);
+    }
+    loop.setActive(true);
+    observer = new ResizeObserver(onResize);
+    observer.observe(target);
+    return {
+        update(nextPublish) {
+            if (disposed)
+                return;
+            publish = nextPublish;
+            // Re-advertise the current size to the new sink immediately (mirrors the
+            // forward anchor's re-publish on update) so the new channel is not left
+            // sizeless until the next ResizeObserver tick.
+            const cur = produce();
+            if (cur)
+                loop.emitNow(cur);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            loop.cancel();
+            if (observer) {
+                observer.disconnect();
+                observer = null;
+            }
+            loop.dispose();
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * view-anchor — sync a main-process native view's bounds to a DOM element.
+ *
+ * Self-contained, engine-agnostic primitive. It knows nothing about
+ * Electron (the `publish` callback owns the IPC → `setBounds`), nothing
+ * about React (the core is imperative; see `react.ts` for the adapter),
+ * and nothing about the host layout engine (the `target` element may come
+ * from our own `compile`/`FrameTree`, or — later — a dockview panel's
+ * `content.element`; the mechanism is identical).
+ *
+ * It is the modern, alive replacement for the archived
+ * `react-electron-browser-view`: the cross-process bridge that DOM layout
+ * libraries (dockview included) deliberately do not provide. dockview's
+ * internal `OverlayRenderContainer` does the same getBoundingClientRect →
+ * RAF → reposition dance, but its follower is a DOM node; ours is a native
+ * `WebContentsView` positioned via the injected `publish`.
+ */
+/** A screen-space rectangle, in CSS pixels. Structurally compatible with
+ *  the host's `ViewBounds` so a publisher typed against either works. */
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Explicit visibility + geometry for a native view, replacing the legacy
+ * magic-`{0,0,0,0}` "hidden" convention (`present:false → ZERO bounds`).
+ *
+ * Visibility is a DISCRIMINANT, never inferred from geometry. The whole
+ * reason this type exists: a genuinely zero-SIZED but on-screen view
+ * (`{ visible:true, bounds:{...,width:0,height:0} }`) is now distinct from a
+ * detached/hidden one (`{ visible:false }`, which carries no `bounds` at
+ * all). Under the old ZERO convention both collapsed to the same value and
+ * were indistinguishable.
+ */
+export type Placement = {
+    visible: true;
+    bounds: Bounds;
+} | {
+    visible: false;
+};
+export interface ViewAnchorOptions {
+    /**
+     * Whether the native view should be attached. When `false`, the anchor
+     * publishes zero bounds (`{0,0,0,0}`) — the host treats `width === 0 ||
+     * height === 0` as "detach the child view but keep its WebContents
+     * alive" (detach-but-keep-alive). No DOM measurement is needed in this
+     * state.
+     */
+    present: boolean;
+    /** Receives the live rect, or `{0,0,0,0}` when detached. Owns IPC. */
+    publish: (bounds: Bounds) => void;
+}
+export interface ViewAnchorHandle {
+    /**
+     * Apply new options. Re-publishes immediately to reflect the new state
+     * (present=true → measure + observe; present=false → zero bounds).
+     */
+    update(opts: ViewAnchorOptions): void;
+    /** Stop observing and remove listeners. After dispose the anchor never
+     *  publishes again (every emit reads `disposed` synchronously, so there is
+     *  no queued frame that could fire late). */
+    dispose(): void;
+}
+/** Which axis this advertiser owns. `block` = height, `inline` = width
+ *  (logical-property naming, axis-agnostic to writing mode). */
+export type AdvertisedAxis = 'block' | 'inline';
+/**
+ * One frame of advertised size. A pure scalar plus the owning axis — there is
+ * deliberately no field for the *other* axis, so "advertise two axes" is not
+ * expressible (single-axis ownership is enforced in the type, not at runtime).
+ */
+export interface AdvertisedSize {
+    /** Mirrors the factory's `axis`; constant across frames. Lets the host
+     *  whitelist-check the axis it is willing to accept. */
+    readonly axis: AdvertisedAxis;
+    /** The owned axis's content extent, in CSS px — already rounded and clamped
+     *  to `>= 0`. */
+    readonly extent: number;
+}
+export interface SizeAdvertiserOptions {
+    /** The single axis this advertiser owns. Fixed for the advertiser's life. */
+    axis: AdvertisedAxis;
+    /** Receives each advertised size. Owns the IPC/postMessage → host. Mirrors
+     *  the forward `publish` (same role: the injected, transport-owning sink). */
+    publish: (size: AdvertisedSize) => void;
+}
+export interface SizeAdvertiserHandle {
+    /**
+     * Swap the `publish` sink (e.g. a new IPC channel) and immediately
+     * re-advertise the current size to it (mirrors the forward anchor's
+     * re-publish on update), so the new channel is not left sizeless until the
+     * next `ResizeObserver` tick.
+     *
+     * Takes only the new sink — `axis` is immutable by construction, so it is
+     * deliberately not expressible here (you cannot attempt to change it). To
+     * advertise a different axis, dispose and create a new advertiser.
+     */
+    update(publish: (size: AdvertisedSize) => void): void;
+    /**
+     * Stop observing, cancel any pending RAF. After dispose nothing is
+     * advertised again. (There is no ZERO/terminal value — collapsing is the
+     * host's policy, unlike the forward anchor's `present:false`.)
+     *
+     * The first advertised value is asynchronous: it awaits the observer's first
+     * frame, and a `display:none` target advertises nothing until shown.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=types.d.ts.map