npm - view-anchor - Versions diffs - 0.1.1 - Mend

view-anchor 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/LICENSE +21 -0
package/README.md +114 -0
package/README.zh-CN.md +114 -0
package/dist/index.d.ts +23 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +18 -0
package/dist/measure-loop.d.ts +43 -0
package/dist/measure-loop.d.ts.map +1 -0
package/dist/measure-loop.js +49 -0
package/dist/react.d.ts +38 -0
package/dist/react.d.ts.map +1 -0
package/dist/react.js +145 -0
package/dist/size-advertiser.d.ts +21 -0
package/dist/size-advertiser.d.ts.map +1 -0
package/dist/size-advertiser.js +83 -0
package/dist/types.d.ts +111 -0
package/dist/types.d.ts.map +1 -0
package/dist/types.js +18 -0
package/dist/view-anchor.d.ts +111 -0
package/dist/view-anchor.d.ts.map +1 -0
package/dist/view-anchor.js +413 -0
package/docs/anchor-3d.html +615 -0
package/docs/bidirectional-design.md +140 -0
package/docs/mechanism.mdx +119 -0
package/package.json +83 -0
package/src/index.ts +39 -0
package/src/measure-loop.ts +87 -0
package/src/react.ts +171 -0
package/src/size-advertiser.ts +95 -0
package/src/types.ts +123 -0
package/src/view-anchor.ts +500 -0

package/dist/size-advertiser.js ADDED Viewed

@@ -0,0 +1,83 @@
+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`'s single-axis-ownership and trust-boundary
+ * sections.
+ */
+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's single-axis-ownership section.`);
+    }
+    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 ADDED Viewed

@@ -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 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

package/dist/types.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;yEACyE;AACzE,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAEtB,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,sEAAsE;IACtE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACrC;;iDAE6C;IAC7C,OAAO,IAAI,IAAI,CAAA;CAChB;AAUD;gEACgE;AAChE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;4DACwD;IACxD,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B;qBACiB;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,IAAI,EAAE,cAAc,CAAA;IACpB;kFAC8E;IAC9E,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAA;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI,CAAA;IACrD;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB"}

package/dist/types.js ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * 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 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`.
+ */
+export {};

package/dist/view-anchor.d.ts ADDED Viewed

@@ -0,0 +1,111 @@
+import type { Placement, ViewAnchorOptions, ViewAnchorHandle } from './types.js';
+/**
+ * Create an anchor binding ONE native view's bounds to `target`'s geometry.
+ *
+ * Imperative core — no React, no Electron. Behaviour:
+ *   - `present === true`: publish `target.getBoundingClientRect()` (x/y rounded,
+ *     width/height `Math.max(0, Math.round(...))`) immediately, then re-publish
+ *     SYNCHRONOUSLY on every `ResizeObserver` tick and window `resize`.
+ *   - `present === false`: publish `{0,0,0,0}` immediately; do not observe.
+ *   - `update(opts)`: re-apply synchronously.
+ *   - `dispose()`: stop observing, never publish again.
+ *
+ * Synchronous, NOT RAF-deferred: the native overlay is a cross-process
+ * `WebContentsView` whose `setBounds` already lands ~1 compositor frame behind
+ * the renderer's DOM paint (the two processes composite on different frames).
+ * Deferring the measure+publish to a RAF stacked a SECOND frame on top — during
+ * a height/splitter drag that read as the overlay visibly trailing the region
+ * edge (worst when GROWING, where the not-yet-followed edge exposes background).
+ * Publishing in the observer tick itself removes that self-inflicted frame and
+ * leaves only the unavoidable cross-process frame (masked by matching the
+ * placeholder/desk background colour). The anti-flood role the RAF used to play
+ * — collapsing a burst of RO+resize ticks in one frame into one publish — is now
+ * served by `lastPublished` dedup: a tick whose measured rect is byte-identical
+ * to the last published one is dropped, so a continuous drag still emits at most
+ * one publish per distinct rect.
+ *
+ * Teardown safety: there is no queued frame to outrun a state change — every
+ * emit reads `disposed`/`present` synchronously, so a tick after
+ * `update`/`dispose` can never write a stale rect over the live one.
+ */
+export declare function createViewAnchor(target: HTMLElement, opts: ViewAnchorOptions): ViewAnchorHandle;
+export interface PlacementAnchorOptions {
+    /**
+     * Caller's INTENT: should the native view be on-screen? `true` →
+     * publish the measured rect as `{ visible:true, bounds }`; `false` →
+     * publish `{ visible:false }`. Crucially, hiddenness comes from this
+     * flag, not from a measured zero size — so a legitimately 0-sized but
+     * visible target still publishes `visible:true`.
+     */
+    visible: boolean;
+    /** Receives each explicit Placement. Owns IPC → host. */
+    publish: (placement: Placement) => void;
+    /**
+     * Opt-in geometry detach. When true, a measured zero-area target (no
+     * geometry box — display:none / unmounted / unstable first layout) publishes
+     * `{ visible:false }` (detach-but-keep) instead of `{ visible:true,
+     * bounds:0×0 }`, and an IntersectionObserver is attached so a display:none
+     * transition (which ResizeObserver does not report) re-publishes. Default
+     * false keeps the legitimate 0×0-visible semantics.
+     */
+    guardDisplayNone?: boolean;
+    /**
+     * Opt-in capture-phase ancestor-scroll follow. When true, the anchor
+     * listens for `scroll` on `window` in the CAPTURE phase (scroll events don't
+     * bubble, but reach `window` while capturing), so an ancestor scroll
+     * container scrolling the target re-measures and re-publishes. With
+     * `followGeometry` off, the scroll callback does a single synchronous
+     * `emit()`; with it on, the scroll OPENS the RAF sentinel window so the
+     * follow tracks every frame of a scroll burst. Default false.
+     */
+    followScroll?: boolean;
+    /**
+     * Opt-in windowed RAF geometry sentinel. Catches ancestor
+     * transform / reflow moves that no DOM event reports. The sentinel is
+     * NON-resident: it is OPENED on demand (a scroll burst, a `[role="separator"]`
+     * splitter pointerdown, or an explicit `pulse()`), polls geometry once per
+     * animation frame publishing IN-FRAME, and AUTO-CLOSES once the rect goes
+     * steady (a few unchanged frames). While closed it schedules no frame, so the
+     * static cost when idle is exactly zero. Default false.
+     */
+    followGeometry?: boolean;
+}
+export interface PlacementAnchorHandle {
+    /** Apply new options; re-publishes immediately (mirrors `createViewAnchor`). */
+    update(opts: PlacementAnchorOptions): void;
+    /** Stop observing; never publish again. */
+    dispose(): void;
+    /**
+     * Open the RAF sentinel window (animation follow); auto-closes after going
+     * steady or after `durationMs`. No-op when `followGeometry` is false.
+     */
+    pulse(durationMs?: number): void;
+}
+/**
+ * Pure measure: read `target`'s rect and wrap it as an explicit visible
+ * Placement. Always `{ visible:true }` — hiddenness is a caller decision
+ * (see `createPlacementAnchor`), so this never returns `{ visible:false }`
+ * and never infers visibility from a 0 size. A collapsed (0×0) but present
+ * element therefore yields `{ visible:true, bounds:{...,width:0,height:0} }`,
+ * distinct from any hidden Placement.
+ */
+export declare function measurePlacement(target: HTMLElement): Placement;
+/**
+ * The explicit-Placement mirror of `createViewAnchor`. Same observer/dedup/
+ * teardown machinery, but the sink receives a `Placement`:
+ *   - `visible === true`  → publish `measurePlacement(target)` and re-publish
+ *     SYNCHRONOUSLY on every `ResizeObserver`/`resize` tick.
+ *   - `visible === false` → publish `{ visible:false }` (NOT a ZERO bounds);
+ *     do not observe.
+ *
+ * Dedup carries the discriminant (`samePlacement`), so a visibility flip is
+ * never coalesced away.
+ *
+ * Opt-in `guardDisplayNone` (default false): when on, a measured zero-area
+ * target (display:none / unmounted / unstable first layout) publishes
+ * `{ visible:false }` instead of `{ visible:true, bounds:0×0 }`, and an
+ * IntersectionObserver is attached so a display:none transition (which
+ * ResizeObserver does not report) re-publishes.
+ */
+export declare function createPlacementAnchor(target: HTMLElement, opts: PlacementAnchorOptions): PlacementAnchorHandle;
+//# sourceMappingURL=view-anchor.d.ts.map

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

@@ -0,0 +1 @@

+ {"version":3,"file":"view-anchor.d.ts","sourceRoot":"","sources":["../src/view-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAwBnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,iBAAiB,GACtB,gBAAgB,CA6ElB;AASD,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,OAAO,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAA;IACvC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,MAAM,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAA;IAC1C,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAM/D;AAiBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,sBAAsB,GAC3B,qBAAqB,CAuPvB"}