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/src/size-advertiser.ts ADDED Viewed

@@ -0,0 +1,95 @@
+import type {
+  AdvertisedSize,
+  SizeAdvertiserOptions,
+  SizeAdvertiserHandle,
+} from './types.js'
+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: HTMLElement,
+  opts: SizeAdvertiserOptions,
+): SizeAdvertiserHandle {
+  const axis = opts.axis // immutable for the advertiser's life
+  let publish = opts.publish
+  let observer: ResizeObserver | null = 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: ResizeObserverSize | null = null
+  const produce = (): AdvertisedSize | null => {
+    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<AdvertisedSize>({
+    produce,
+    same: (a, b) => a.extent === b.extent, // axis is constant
+    sink: (size) => publish(size),
+  })
+  const onResize: ResizeObserverCallback = (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: (size: AdvertisedSize) => void): void {
+      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(): void {
+      if (disposed) return
+      disposed = true
+      loop.cancel()
+      if (observer) {
+        observer.disconnect()
+        observer = null
+      }
+      loop.dispose()
+    },
+  }
+}

package/src/types.ts ADDED Viewed

@@ -0,0 +1,123 @@
+/**
+ * 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
+}
+// ── Reverse direction: size advertiser ───────────────────────────────
+//
+// The mirror of the forward anchor. Runs in a DOWNSTREAM WebContentsView's own
+// renderer: it measures the content's own size and advertises it to the host,
+// which sizes the placeholder accordingly (and the forward anchor then keeps the
+// view positioned). One advertiser owns exactly ONE axis — the other axis is a
+// host-driven, read-only input — so the cross-process loop stays a one-way DAG.
+/** 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
+}