npm - view-anchor - Versions diffs - 0.1.2 → 0.2.0 - Mend

view-anchor 0.1.2 → 0.2.0

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 (44) hide show

package/README.md +118 -34
package/README.zh-CN.md +128 -44
package/dist/index.d.ts +4 -16
package/dist/index.d.ts.map +1 -1
package/dist/index.js +2 -14
package/dist/measure-loop.d.ts +9 -28
package/dist/measure-loop.d.ts.map +1 -1
package/dist/measure-loop.js +37 -16
package/dist/protocol-publisher.d.ts +41 -0
package/dist/protocol-publisher.d.ts.map +1 -0
package/dist/protocol-publisher.js +191 -0
package/dist/protocol-types.d.ts +36 -0
package/dist/protocol-types.d.ts.map +1 -0
package/dist/protocol-types.js +10 -0
package/dist/protocol.d.ts +35 -0
package/dist/protocol.d.ts.map +1 -0
package/dist/protocol.js +131 -0
package/dist/react.d.ts +18 -30
package/dist/react.d.ts.map +1 -1
package/dist/react.js +125 -122
package/dist/size-advertiser.d.ts +9 -14
package/dist/size-advertiser.d.ts.map +1 -1
package/dist/size-advertiser.js +20 -28
package/dist/types.d.ts +29 -73
package/dist/types.d.ts.map +1 -1
package/dist/types.js +1 -15
package/dist/view-anchor.d.ts +36 -77
package/dist/view-anchor.d.ts.map +1 -1
package/dist/view-anchor.js +206 -174
package/docs/bidirectional-design.md +64 -96
package/docs/{anchor-3d.html → index.html} +215 -73
package/docs/mechanism.mdx +55 -49
package/docs/performance-report.md +63 -0
package/docs/protocol.md +79 -0
package/package.json +30 -4
package/src/index.ts +6 -15
package/src/measure-loop.ts +36 -41
package/src/protocol-publisher.ts +236 -0
package/src/protocol-types.ts +43 -0
package/src/protocol.ts +193 -0
package/src/react.ts +186 -141
package/src/size-advertiser.ts +24 -31
package/src/types.ts +34 -79
package/src/view-anchor.ts +228 -212

package/docs/{anchor-3d.html → index.html} RENAMED Viewed

@@ -1,9 +1,10 @@
 <!DOCTYPE html>
-<html lang="zh-CN">
+<html lang="en">
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>view-anchor —— 渲染进程 DOM → 主进程 WebContentsView</title>
+<title>view-anchor 3D demo: align an Electron WebContentsView, webview or iframe to a DOM element</title>
+<meta name="description" content="view-anchor is a high-performance geometry bridge that keeps an Electron WebContentsView, native webview or cross-origin iframe aligned to a DOM element. This interactive 3D demo runs the real core in your browser.">
 <style>
   :root {
     --bg:               hsl(  0  0%   7%);
@@ -189,22 +190,44 @@
   footer.note { margin-top: 22px; color: var(--text-3); font-size: 12px; line-height: 1.6; }
   footer.note code { color: var(--text-2); }
+  /* ---- landing intro ---- */
+  .badges { display: flex; gap: 8px; flex-wrap: wrap; margin: 0 0 16px; }
+  .badges img { display: block; }
+  .tag-en { color: var(--text-2); font-size: 14.5px; margin: 10px 0 0; max-width: 72ch; }
+  .actions { display: flex; gap: 18px; flex-wrap: wrap; margin-top: 12px; font-size: 13px; }
+  .actions a { color: var(--placeholder-bd); text-decoration: none; border-bottom: 1px solid hsl(249 100% 72% / 0.3); }
+  .actions a:hover { color: var(--text); border-bottom-color: var(--text-2); }
+  footer.note { display: flex; flex-direction: column; gap: 10px; }
+  footer.note .hint { color: var(--text-3); font-size: 12.5px; }
 </style>
 </head>
 <body>
 <div class="wrap">
   <header>
-    <h1>view-anchor —— 原生视图贴住 DOM 矩形</h1>
-    <p>绿色 <b style="color:var(--native-bd)">WebContentsView</b> 跟随蓝色<b style="color:var(--placeholder-bd)">占位 div</b>，由 view-anchor 实时驱动。</p>
+    <div class="badges">
+      <img alt="npm version" src="https://img.shields.io/npm/v/view-anchor">
+      <img alt="npm downloads" src="https://img.shields.io/npm/dm/view-anchor">
+      <img alt="License" src="https://img.shields.io/npm/l/view-anchor">
+      <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D24-339933">
+    </div>
+    <h1>view-anchor: interactive 3D demo</h1>
+    <p class="tag-en">Align a native <b style="color:var(--native-bd)">WebContentsView</b> to a DOM element's geometry. Resize the splitter, toggle <code>present</code>, or explode the 3D scene below: the green view is positioned by the real view-anchor core running in this page.</p>
+    <div class="actions">
+      <a href="https://github.com/lbb00/view-anchor">GitHub</a>
+      <a href="https://www.npmjs.com/package/view-anchor">npm</a>
+      <a href="https://github.com/lbb00/view-anchor/blob/main/README.md">README</a>
+    </div>
   </header>
-  <div class="stage-shell">
+<div class="stage-shell">
     <div class="scene" id="scene">
       <div class="deck" id="deck">
-        <!-- 底层：渲染进程 DOM 窗口 -->
+        <!-- bottom layer: the renderer / DOM window -->
         <div class="window">
           <div class="chrome-bar"><div class="traffic"></div></div>
-          <div class="caption"><b>渲染进程 DOM</b></div>
+          <div class="caption"><b>Renderer DOM</b></div>
           <div class="dom-area">
             <div class="dom-sidebar"><i></i><i></i><i></i><i></i><i></i></div>
             <div class="placeholder" id="placeholder">
@@ -213,10 +236,10 @@
           </div>
         </div>
-        <!-- 连接柱：沿 Z 轴从占位 div 指向上方的原生视图 -->
+        <!-- connector pillar: from the placeholder up to the native view along Z -->
         <div class="pillar" id="pillar"></div>
-        <!-- 顶层：原生 WebContentsView，由 view-anchor 驱动 -->
+        <!-- top layer: the native WebContentsView, driven by view-anchor -->
         <div class="follower" id="follower">
           <div class="row-marker"></div>
           <div class="nv-label">WebContentsView</div>
@@ -233,31 +256,41 @@
         <label for="present"><code>present</code></label>
       </div>
       <div class="ctl">
-        <label for="split">分栏</label>
+        <label for="split">Split</label>
         <input type="range" id="split" min="34" max="78" value="58">
       </div>
       <div class="ctl">
         <span class="switch">
-          <input type="checkbox" id="explode">
+          <input type="checkbox" id="explode" checked>
           <span class="track"></span><span class="thumb"></span>
         </span>
-        <label for="explode">拆开图层</label>
+        <label for="explode">Explode</label>
       </div>
       <div class="readout" id="readout"></div>
     </div>
     <div class="legend">
-      <span><span class="sw r"></span> DOM 窗口</span>
-      <span><span class="sw p"></span> 占位 div</span>
+      <span><span class="sw r"></span> DOM window</span>
+      <span><span class="sw p"></span> Placeholder div</span>
       <span><span class="sw n"></span> WebContentsView</span>
     </div>
   </div>
+  <footer class="note">
+    <div class="actions">
+      <a href="https://github.com/lbb00/view-anchor">GitHub repository</a>
+      <a href="https://www.npmjs.com/package/view-anchor">npm · view-anchor</a>
+      <span style="color:var(--text-3)">MIT licensed</span>
+    </div>
+    <div class="hint">Drag <code>Split</code> to resize the placeholder, toggle <code>present</code> to collapse or restore, and toggle <code>Explode</code> for the 3D perspective. The green view's bounds come directly from view-anchor's <code>publish</code> callback.</div>
+  </footer>
 </div>
-<!-- view-anchor 的真实构建产物，由 `pnpm -C packages/view-anchor build:docs`
-     从 src/view-anchor.ts 用 esbuild 打包后内联到此处（不另写一份实现）。
-     内联而非 import 是因为本页要支持 file:// 直接打开，浏览器会把跨源 ES 模块
-     import 拦掉。下面这段是生成的，请勿手改。 -->
+<!-- Bootstrapped from src/view-anchor.ts by `pnpm build:docs` and inlined here
+     as an esbuild IIFE — this block is GENERATED, do not hand-edit. Inlined
+     rather than imported so the page can open from file://, where browsers
+     block cross-origin ES module imports. -->
 <script>
 /* __VIEW_ANCHOR_CORE_START__ — generated from src/view-anchor.ts by `pnpm build:docs`; do not edit */
 "use strict";
@@ -299,18 +332,33 @@ var __viewAnchorCore = (() => {
     let publish = opts.publish;
     let observer = null;
     let lastPublished = null;
+    let publicationRevision = 0;
     let disposed = false;
     const measure = () => {
       const r = target.getBoundingClientRect();
+      if (!Number.isFinite(r.left) || !Number.isFinite(r.top) || !Number.isFinite(r.width) || !Number.isFinite(r.height)) return null;
       return clampRect({ x: r.left, y: r.top, width: r.width, height: r.height });
     };
     const sameRect = (a, b) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+    const publishCandidate = (candidate) => {
+      const previous = lastPublished;
+      const attempt = ++publicationRevision;
+      lastPublished = candidate;
+      try {
+        const accepted = publish(candidate) !== false;
+        if (!accepted && publicationRevision === attempt) lastPublished = previous;
+        return accepted;
+      } catch (error) {
+        if (publicationRevision === attempt) lastPublished = previous;
+        throw error;
+      }
+    };
     const emit = () => {
       if (disposed || !present) return;
       const m = measure();
+      if (!m) return;
       if (lastPublished && sameRect(lastPublished, m)) return;
-      lastPublished = m;
-      publish(m);
+      publishCandidate(m);
     };
     const startObserving = () => {
       if (observer) return;
@@ -329,11 +377,11 @@ var __viewAnchorCore = (() => {
       lastPublished = null;
       if (present) {
         startObserving();
-        lastPublished = measure();
-        publish(lastPublished);
+        const measured = measure();
+        if (measured) publishCandidate(measured);
       } else {
         stopObserving();
-        publish(ZERO);
+        publishCandidate(ZERO);
       }
     };
     apply();
@@ -368,32 +416,54 @@ var __viewAnchorCore = (() => {
   function createPlacementAnchor(target, opts) {
     let visible = opts.visible;
     let publish = opts.publish;
-    const guardDisplayNone = opts.guardDisplayNone ?? false;
-    const followScroll = opts.followScroll ?? false;
-    const followGeometry = opts.followGeometry ?? false;
+    let guardDisplayNone = opts.guardDisplayNone ?? false;
+    let followScroll = opts.followScroll ?? false;
+    let followGeometry = opts.followGeometry ?? false;
     let observer = null;
     let io = null;
+    let scrollListening = false;
+    let geometryListening = false;
+    const capture = { capture: true };
+    const passiveCapture = { capture: true, passive: true };
     let lastPublished = null;
+    let publicationRevision = 0;
     let disposed = false;
     let rafId = null;
     let steadyFrames = 0;
     const STEADY_CLOSE_FRAMES = 2;
     const MAX_HIDDEN_FOLLOW_FRAMES = 30;
+    const MAX_INVALID_FOLLOW_FRAMES = 30;
+    let invalidFrames = 0;
     let pointerHeld = false;
+    let activePointerId = null;
     let sentinelDeadline = null;
     const computePlacement = () => {
       const p = measurePlacement(target);
+      if (p.visible && (!Number.isFinite(p.bounds.x) || !Number.isFinite(p.bounds.y) || !Number.isFinite(p.bounds.width) || !Number.isFinite(p.bounds.height))) return null;
       if (guardDisplayNone && p.visible && (p.bounds.width === 0 || p.bounds.height === 0)) {
         return { visible: false };
       }
       return p;
     };
+    const publishCandidate = (candidate) => {
+      const previous = lastPublished;
+      const attempt = ++publicationRevision;
+      lastPublished = candidate;
+      try {
+        const accepted = publish(candidate) !== false;
+        if (!accepted && publicationRevision === attempt) lastPublished = previous;
+        return accepted;
+      } catch (error) {
+        if (publicationRevision === attempt) lastPublished = previous;
+        throw error;
+      }
+    };
     const emit = () => {
       if (disposed || !visible) return;
       const p = computePlacement();
+      if (!p) return;
       if (lastPublished && samePlacement(lastPublished, p)) return;
-      lastPublished = p;
-      publish(p);
+      publishCandidate(p);
     };
     const shouldCloseOnHiddenPoll = () => {
       if (lastPublished?.visible === false) return true;
@@ -410,12 +480,29 @@ var __viewAnchorCore = (() => {
         return;
       }
       const p = computePlacement();
+      if (!p) {
+        if (invalidFrames++ >= MAX_INVALID_FOLLOW_FRAMES) {
+          sentinelDeadline = null;
+          return;
+        }
+        if (!disposed && visible && followGeometry) {
+          rafId = requestAnimationFrame(sentinelFrame);
+        } else {
+          sentinelDeadline = null;
+        }
+        return;
+      }
+      invalidFrames = 0;
       if (!p.visible) {
         if (shouldCloseOnHiddenPoll()) {
           sentinelDeadline = null;
           return;
         }
-        rafId = requestAnimationFrame(sentinelFrame);
+        if (!disposed && visible && followGeometry) {
+          rafId = requestAnimationFrame(sentinelFrame);
+        } else {
+          sentinelDeadline = null;
+        }
         return;
       }
       if (lastPublished && samePlacement(lastPublished, p)) {
@@ -425,11 +512,10 @@ var __viewAnchorCore = (() => {
           return;
         }
       } else {
-        lastPublished = p;
-        publish(p);
+        publishCandidate(p);
         steadyFrames = 0;
       }
-      if (!disposed && visible) {
+      if (!disposed && visible && followGeometry) {
         rafId = requestAnimationFrame(sentinelFrame);
       } else {
         sentinelDeadline = null;
@@ -438,7 +524,10 @@ var __viewAnchorCore = (() => {
     const openSentinel = () => {
       if (!followGeometry || disposed) return;
       steadyFrames = 0;
-      if (rafId === null) rafId = requestAnimationFrame(sentinelFrame);
+      if (rafId === null) {
+        invalidFrames = 0;
+        rafId = requestAnimationFrame(sentinelFrame);
+      }
     };
     const closeSentinel = () => {
       if (rafId !== null) {
@@ -446,8 +535,10 @@ var __viewAnchorCore = (() => {
         rafId = null;
       }
       steadyFrames = 0;
+      invalidFrames = 0;
       sentinelDeadline = null;
       pointerHeld = false;
+      activePointerId = null;
     };
     const onScroll = () => {
       if (followGeometry) openSentinel();
@@ -456,67 +547,105 @@ var __viewAnchorCore = (() => {
     const onPointerDown = (e) => {
       const t = e.target;
       if (t && t.closest && t.closest('[role="separator"]')) {
+        if (!pointerHeld) activePointerId = e.pointerId;
         pointerHeld = true;
         openSentinel();
       }
     };
-    const onPointerUp = () => {
+    const releasePointer = (e) => {
       if (!pointerHeld) return;
+      if (e && activePointerId !== e.pointerId) return;
       pointerHeld = false;
+      activePointerId = null;
       openSentinel();
     };
-    const startObserving = () => {
-      if (observer) return;
-      observer = new ResizeObserver(emit);
-      observer.observe(target);
-      window.addEventListener("resize", emit);
-      if (guardDisplayNone && typeof IntersectionObserver !== "undefined") {
+    const onPointerUp = (e) => {
+      releasePointer(e);
+    };
+    const onPointerCancel = (e) => {
+      releasePointer(e);
+    };
+    const onWindowBlur = () => {
+      releasePointer();
+    };
+    const startOptionalObserving = () => {
+      if (guardDisplayNone && !io && typeof IntersectionObserver !== "undefined") {
         io = new IntersectionObserver(emit);
         io.observe(target);
       }
-      if (followScroll) {
-        window.addEventListener("scroll", onScroll, {
-          capture: true,
-          passive: true
-        });
+      if (followScroll && !scrollListening) {
+        window.addEventListener("scroll", onScroll, passiveCapture);
+        scrollListening = true;
       }
-      if (followGeometry) {
-        window.addEventListener("pointerdown", onPointerDown, { capture: true });
-        window.addEventListener("pointerup", onPointerUp, { capture: true });
+      if (followGeometry && !geometryListening) {
+        window.addEventListener("pointerdown", onPointerDown, capture);
+        window.addEventListener("pointerup", onPointerUp, capture);
+        window.addEventListener("pointercancel", onPointerCancel, capture);
+        window.addEventListener("blur", onWindowBlur);
+        geometryListening = true;
       }
     };
-    const stopObserving = () => {
-      if (observer) {
-        observer.disconnect();
-        observer = null;
+    const stopOptionalObserving = () => {
+      if (io && !guardDisplayNone) {
+        io.disconnect();
+        io = null;
       }
+      if (scrollListening && !followScroll) {
+        window.removeEventListener("scroll", onScroll, passiveCapture);
+        scrollListening = false;
+      }
+      if (geometryListening && !followGeometry) {
+        window.removeEventListener("pointerdown", onPointerDown, capture);
+        window.removeEventListener("pointerup", onPointerUp, capture);
+        window.removeEventListener("pointercancel", onPointerCancel, capture);
+        window.removeEventListener("blur", onWindowBlur);
+        geometryListening = false;
+        closeSentinel();
+      }
+    };
+    const stopAllOptionalObserving = () => {
       if (io) {
         io.disconnect();
         io = null;
       }
-      window.removeEventListener("resize", emit);
-      window.removeEventListener("scroll", onScroll, {
-        capture: true
-      });
-      window.removeEventListener("pointerdown", onPointerDown, {
-        capture: true
-      });
-      window.removeEventListener("pointerup", onPointerUp, {
-        capture: true
-      });
+      if (scrollListening) {
+        window.removeEventListener("scroll", onScroll, passiveCapture);
+        scrollListening = false;
+      }
+      if (geometryListening) {
+        window.removeEventListener("pointerdown", onPointerDown, capture);
+        window.removeEventListener("pointerup", onPointerUp, capture);
+        window.removeEventListener("pointercancel", onPointerCancel, capture);
+        window.removeEventListener("blur", onWindowBlur);
+        geometryListening = false;
+      }
       closeSentinel();
     };
+    const startObserving = () => {
+      if (observer) return;
+      observer = new ResizeObserver(emit);
+      observer.observe(target);
+      window.addEventListener("resize", emit);
+      startOptionalObserving();
+    };
+    const stopObserving = () => {
+      if (observer) {
+        observer.disconnect();
+        observer = null;
+      }
+      window.removeEventListener("resize", emit);
+      stopAllOptionalObserving();
+    };
     const apply = () => {
       lastPublished = null;
       if (visible) {
         startObserving();
-        lastPublished = computePlacement();
-        publish(lastPublished);
+        const placement = computePlacement();
+        if (placement) publishCandidate(placement);
       } else {
         stopObserving();
         const hidden = { visible: false };
-        lastPublished = hidden;
-        publish(hidden);
+        publishCandidate(hidden);
       }
     };
     apply();
@@ -525,6 +654,13 @@ var __viewAnchorCore = (() => {
         if (disposed) return;
         publish = next.publish;
         visible = next.visible;
+        guardDisplayNone = next.guardDisplayNone ?? guardDisplayNone;
+        followScroll = next.followScroll ?? followScroll;
+        followGeometry = next.followGeometry ?? followGeometry;
+        if (visible && observer) {
+          stopOptionalObserving();
+          startOptionalObserving();
+        }
         apply();
       },
       dispose() {
@@ -562,16 +698,18 @@ var __viewAnchorCore = (() => {
   const scene       = document.getElementById('scene')
   const readout     = document.getElementById('readout')
-  // 占位 div 在 deck 内的布局矩形（沿 offsetParent 链累加，与 3D 变换无关）——
-  // 这样无论平铺还是倾斜，绿色视图都摆在占位 div 正上方，对齐不漂。
+  // The placeholder's rect inside the deck (accumulated along the offsetParent
+  // chain, independent of the 3D transform) — flat or tilted, the native view
+  // stays registered directly above the placeholder.
   function deckLocalRect(el) {
     let x = 0, y = 0, n = el
     while (n && n !== deck) { x += n.offsetLeft; y += n.offsetTop; n = n.offsetParent }
     return { x, y, width: el.offsetWidth, height: el.offsetHeight }
   }
-  // 这是宿主侧的 publish —— view-anchor 把测量到的矩形交给它。真实应用里它会走
-  // IPC → WebContentsView.setBounds；这里把绿色视图摆到 deck 局部坐标的对应位置。
+  // The host-side publish — view-anchor hands it the measured rect. A real app
+  // would go IPC → WebContentsView.setBounds; here we place the view in the
+  // deck's local coordinates.
   function publish(bounds) {
     if (bounds.width === 0 || bounds.height === 0) {
       follower.classList.add('collapsed')
@@ -584,7 +722,8 @@ var __viewAnchorCore = (() => {
     follower.style.top    = r.y + 'px'
     follower.style.width  = r.width + 'px'
     follower.style.height = r.height + 'px'
-    // 连接柱立在占位 div 中线，沿 Z 伸到原生视图所在高度（120px）。
+    // Pillar stands on the placeholder's centerline, rising along Z to the
+    // view's height (120px).
     pillar.style.left = (r.x + r.width / 2) + 'px'
     pillar.style.top  = (r.y + r.height / 2) + 'px'
     pillar.style.height = '120px'
@@ -595,10 +734,10 @@ var __viewAnchorCore = (() => {
     readout.innerHTML =
       '<span class="k">publish</span>({ x:' + b.x + ', y:' + b.y +
       ', w:' + b.width + ', h:' + b.height + ' })' +
-      (present ? '' : '  <span class="k">// 已摘除</span>')
+      (present ? '' : '  <span class="k">// detached</span>')
   }
-  // 启动真实 anchor。之后分栏 resize 全由 view-anchor 自己的 ResizeObserver 驱动。
+  // Start the real anchor; split resizes are driven by view-anchor's own ResizeObserver.
   const handle = createViewAnchor(placeholder, { present: presentEl.checked, publish })
   presentEl.addEventListener('change', () => {
@@ -607,6 +746,9 @@ var __viewAnchorCore = (() => {
   splitEl.addEventListener('input', () => {
     placeholder.style.flexBasis = splitEl.value + '%'
   })
+  // Explode defaults ON: apply the exploded pose at boot — uncheck to see the flat view.
+  if (explodeEl.checked) scene.classList.add('exploded')
   explodeEl.addEventListener('change', () => {
     scene.classList.toggle('exploded', explodeEl.checked)
   })