@realsee/dnalogel 3.64.23-alpha.3 → 3.64.23-ke-webgpu.1

package/libs/shared-utils/five/mode.d.ts

@@ -1,3 +1,3 @@
-import type { Mode } from '@realsee/five';
+import type { Mode } from '@realsee/five-webgpu';
 export declare function isPanoramaLike(mode: Mode): boolean;
 export declare function isModelLike(mode: Mode): boolean;

package/libs/shared-utils/getPxmm.d.ts

@@ -1,4 +1,4 @@
-import type { Five } from '@realsee/five';
+import type { Five } from '@realsee/five-webgpu';
 import { FLOOR_PLAN_ATTACHED_TO } from '../floorplan/constant';
 interface GetPxmmOption {
     attachedTo: FLOOR_PLAN_ATTACHED_TO;

package/libs/shared-utils/index.js

@@ -2,12 +2,12 @@ import "./tag.js";
 import "three";
 import "../vendor/hammerjs/hammer.js";
 import "./three/PointSelector/index.js";
+import "three/webgpu";
+import "three/tsl";
 import "../vendor/@tweenjs/tween/dist/tween.esm.js.js";
 import "./five/FivePuppet.js";
-import "./three/CSS3DRenderer/index.js";
 import "../CSS3DRenderPlugin/utils/generateBehindFiveElement.js";
-import "@realsee/five/line";
-import "./three/core/Five_LineMaterial2.js";
+import "three/examples/jsm/lines/LineGeometry.js";
+import "three/examples/jsm/lines/webgpu/Line2.js";
 import "./three/core/Sphere.js";
 import "../vendor/animejs/lib/anime.es.js";
-import "../CSS3DRenderPlugin/utils/three/CSS3DRender.js";

package/libs/shared-utils/logger.js

@@ -1,6 +1,6 @@
 function A() {
   console.debug(
-    "%c %c@realsee/dnalogel %cv3.64.23-alpha.3",
+    "%c %c@realsee/dnalogel %cv3.64.23-ke-webgpu.1",
     [
       "background: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAkAAAAMCAMAAACHgmeRAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAABLFBMVEUAAAAapPoap/oaqvkbrfkbr/gZnfwZoPsaqfnD4v/E4/8Ylv0clPm93/+/4P/B4f8Yj/683/8Wif+33P8Uhv+x2f8ShP+s1v8Pgf+n0/8Nf/+h0f8Lff8Lff8Nf/9dl/+czv8KfP8KfP+Lxf+Uyv+Xy/+Hwv+Jw/+Mxf+Oxv+RyP8aovsapfoap/oZmfwZm/wZnvsYnPsYkf4YlP0NePsDYfgYcfi43f+63v8Xiv8Xjf4EWfwCV/sWZ/qz2v+02/8Vh/8WiP8EUf8CTf4WXv2u1/+v2P8Thf8Thv8ETf8CR/8VV/+o1f+q1f8Qgv8Rg/8DSv8BRf8UVP+j0v+k0v8OgP8Pgf8DR/8DQv9Nhf+dzv+fz/+Kv/+Vyv+Xy/+azf+Oxv+Qx/+SyP////8MUhLdAAAAK3RSTlMACEWQ2bd98uQECPXxqO7c+Pb49vj2+Pb49vj23Oul8fMHA+TwerXXjEIG2P+bHgAAAAFiS0dEY1y+LaoAAAB+SURBVAjXY2BgZGJmYWVgYGBgY9fW0eVg4ORi4NbTNzDk4eXjZxAwMjYxNTO3EGQQsrSytrG1sxdmEHFwdHJ2cXUTZRBz9/D08vbxFWeQ8PMPCAwKDpFkkAoNC4+IjIqWZpCRlZOPiY2LV2BQVGJQTkhMUlEFWaOmrqGpxQAAyg0S9Dq+VPYAAAAASUVORK5CYII=')",
       "background-repeat: no-repeat",

package/libs/shared-utils/object3d2LocalMatrix.d.ts

@@ -8,5 +8,5 @@ declare const bject3d2LocalMatrix: (mesh: THREE.Object3D, { scale, rotation, pos
         y: number;
         z: number;
     };
-}) => THREE.Object3D;
+}) => THREE.Object3D<THREE.Object3DEventMap>;
 export default bject3d2LocalMatrix;

package/libs/shared-utils/tag.d.ts

@@ -1,4 +1,4 @@
-import type { Five } from '@realsee/five';
+import type { Five } from '@realsee/five-webgpu';
 import { type AnyPosition } from './positionToVector3';
 import * as THREE from 'three';
 export declare class LightTag {

package/libs/shared-utils/tag.js

@@ -27,15 +27,15 @@ import { resizeObserver as x } from "./dom/resizeObserver.js";
 import { fiveEveryReadyListener as E } from "./five/fiveEveryReadyListener.js";
 import "../vendor/hammerjs/hammer.js";
 import "./three/PointSelector/index.js";
-import "./three/CSS3DRenderer/index.js";
+import "three/webgpu";
+import "three/tsl";
 import { waitFiveModelLoaded as F } from "./five/fiveModelLoad.js";
 import "../CSS3DRenderPlugin/utils/generateBehindFiveElement.js";
-import "@realsee/five/line";
-import "./three/core/Five_LineMaterial2.js";
+import "three/examples/jsm/lines/LineGeometry.js";
+import "three/examples/jsm/lines/webgpu/Line2.js";
 import "./three/core/Sphere.js";
 import "../vendor/animejs/lib/anime.es.js";
 import "../vendor/@tweenjs/tween/dist/tween.esm.js.js";
-import "../CSS3DRenderPlugin/utils/three/CSS3DRender.js";
 import "./five/FivePuppet.js";
 const R = new C.Vector2();
 class M {
@@ -224,7 +224,7 @@ class M {
       if (!this.simulate3D)
         return 1;
       const s = 3 * Math.tan(0.5 * this.five.camera.fov / 180 * Math.PI), i = this.transformedPosition.distanceTo(this.five.camera.position);
-      return Math.max(Math.min(1 - s * i / 40, 1), 0.75);
+      return Math.max(Math.min(1 - s * i / 40, 1), 0.5);
     })(), n = (() => {
       if (this.positionsForRotate === void 0 || this.positionsForRotate.length !== 2)
         return 0;

package/libs/shared-utils/three/CSS3DRenderer/index.js

@@ -1,95 +1,95 @@
-import { Object3D as w, Matrix4 as k } from "three";
-var c = function(p) {
-  w.call(this), this.element = p, this.element.style.position = "absolute", this.element.style.pointerEvents = "auto", this.element.style.userSelect = "none", this.element.setAttribute("draggable", !1), this.addEventListener("removed", function() {
-    this.traverse(function(y) {
-      y.element instanceof Element && y.element.parentNode !== null && y.element.remove();
+import { Object3D as w, Matrix4 as _ } from "three";
+class b extends w {
+  constructor(u) {
+    super(), this.element = u, this.element.style.position = "absolute", this.element.style.pointerEvents = "auto", this.element.style.userSelect = "none", this.element.setAttribute("draggable", !1), this.addEventListener("removed", function() {
+      this.traverse(function(f) {
+        f.element instanceof Element && f.element.parentNode !== null && f.element.remove();
+      });
     });
-  });
-};
-c.prototype = Object.create(w.prototype);
-c.prototype.constructor = c;
-var C = function(p) {
-  c.call(this, p);
-};
-C.prototype = Object.create(c.prototype);
-C.prototype.constructor = C;
-let I = function(p) {
-  let y = this, x, S, M, g, o = new k(), f = {
+  }
+}
+class P extends b {
+  constructor(u) {
+    super(u);
+  }
+}
+let I = function(h) {
+  let u = this, f, v, g, S, o = new _(), d = {
     camera: { fov: 0, style: "" },
     objects: /* @__PURE__ */ new Map()
   }, a = document.createElement("div");
   a.style.overflow = "hidden", this.domElement = a;
-  let n = document.createElement("div");
-  n.style.WebkitTransformStyle = "preserve-3d", n.style.transformStyle = "preserve-3d", n.style.pointerEvents = "none", a.appendChild(n), this.getSize = function() {
+  let i = document.createElement("div");
+  i.style.WebkitTransformStyle = "preserve-3d", i.style.transformStyle = "preserve-3d", i.style.pointerEvents = "none", a.appendChild(i), this.getSize = function() {
     return {
-      width: x,
-      height: S
+      width: f,
+      height: v
     };
   }, this.setSize = function(t, e) {
-    x = t, S = e, M = x / 2, g = S / 2, a.style.width = t + "px", a.style.height = e + "px", n.style.width = t + "px", n.style.height = e + "px";
+    f = t, v = e, g = f / 2, S = v / 2, a.style.width = t + "px", a.style.height = e + "px", i.style.width = t + "px", i.style.height = e + "px";
   };
-  function r(t) {
+  function n(t) {
     return Math.abs(t) < 1e-10 ? 0 : t;
   }
-  function O(t) {
+  function C(t) {
     let e = t.elements;
-    return "matrix3d(" + r(e[0]) + "," + r(-e[1]) + "," + r(e[2]) + "," + r(e[3]) + "," + r(e[4]) + "," + r(-e[5]) + "," + r(e[6]) + "," + r(e[7]) + "," + r(e[8]) + "," + r(-e[9]) + "," + r(e[10]) + "," + r(e[11]) + "," + r(e[12]) + "," + r(-e[13]) + "," + r(e[14]) + "," + r(e[15]) + ")";
+    return "matrix3d(" + n(e[0]) + "," + n(-e[1]) + "," + n(e[2]) + "," + n(e[3]) + "," + n(e[4]) + "," + n(-e[5]) + "," + n(e[6]) + "," + n(e[7]) + "," + n(e[8]) + "," + n(-e[9]) + "," + n(e[10]) + "," + n(e[11]) + "," + n(e[12]) + "," + n(-e[13]) + "," + n(e[14]) + "," + n(e[15]) + ")";
   }
-  function W(t, e) {
+  function M(t, e) {
     let l = t.elements;
-    return "translate(-50%,-50%)" + ("matrix3d(" + r(l[0]) + "," + r(l[1]) + "," + r(l[2]) + "," + r(l[3]) + "," + r(-l[4]) + "," + r(-l[5]) + "," + r(-l[6]) + "," + r(-l[7]) + "," + r(l[8]) + "," + r(l[9]) + "," + r(l[10]) + "," + r(l[11]) + "," + r(l[12]) + "," + r(l[13]) + "," + r(l[14]) + "," + r(l[15]) + ")");
+    return "translate(-50%,-50%)" + ("matrix3d(" + n(l[0]) + "," + n(l[1]) + "," + n(l[2]) + "," + n(l[3]) + "," + n(-l[4]) + "," + n(-l[5]) + "," + n(-l[6]) + "," + n(-l[7]) + "," + n(l[8]) + "," + n(l[9]) + "," + n(l[10]) + "," + n(l[11]) + "," + n(l[12]) + "," + n(l[13]) + "," + n(l[14]) + "," + n(l[15]) + ")");
   }
-  function E(t) {
+  function W(t) {
     var e;
     if (t.isCSS3DObject) {
       const l = (e = t.mode) != null ? e : "front";
-      (!p || l === p) && (t.element.style.display = "none");
+      (!h || l === h) && (t.element.style.display = "none");
     }
-    for (let l = 0, h = t.children.length; l < h; l++)
-      E(t.children[l]);
+    for (let l = 0, y = t.children.length; l < y; l++)
+      W(t.children[l]);
   }
-  function D(t, e, l, h, v) {
-    var u;
+  function E(t, e, l, y, c) {
+    var x;
     if (t.visible === !1) {
-      E(t);
+      W(t);
       return;
     }
     if (t.isCSS3DObject) {
-      const i = (u = t.mode) != null ? u : "front";
-      if (p && i !== p)
+      const r = (x = t.mode) != null ? x : "front";
+      if (h && r !== h)
         return;
-      t.flag = v;
-      const d = t.layers.test(l.layers) === !0, m = t.element;
-      if (m.style.display = d === !0 ? "" : "none", d) {
-        t.onBeforeRender(y, e, l);
+      t.flag = c;
+      const p = t.layers.test(l.layers) === !0, m = t.element;
+      if (m.style.display = p === !0 ? "" : "none", p) {
+        t.onBeforeRender(u, e, l);
         let s;
-        t.isCSS3DSprite ? (o.copy(l.matrixWorldInverse), o.transpose(), o.copyPosition(t.matrixWorld), o.scale(t.scale), o.elements[3] = 0, o.elements[7] = 0, o.elements[11] = 0, o.elements[15] = 1, s = W(o)) : s = W(t.matrixWorld);
-        let b = f.objects.get(t);
-        if (b === void 0 || b.style !== s) {
+        t.isCSS3DSprite ? (o.copy(l.matrixWorldInverse), o.transpose(), o.copyPosition(t.matrixWorld), o.scale(t.scale), o.elements[3] = 0, o.elements[7] = 0, o.elements[11] = 0, o.elements[15] = 1, s = M(o)) : s = M(t.matrixWorld);
+        let O = d.objects.get(t);
+        if (O === void 0 || O.style !== s) {
           m.style.WebkitTransform = s, m.style.transform = s;
-          let _ = { style: s };
-          f.objects.set(t, _);
+          let D = { style: s };
+          d.objects.set(t, D);
         }
-        m.style.display = t.visible ? "" : "none", m.parentNode !== n && n.appendChild(m), t.onAfterRender(y, e, l);
+        m.style.display = t.visible ? "" : "none", m.parentNode !== i && i.appendChild(m), t.onAfterRender(u, e, l);
       }
     }
-    for (let i = 0, d = t.children.length; i < d; i++)
-      D(t.children[i], e, l, h, v);
+    for (let r = 0, p = t.children.length; r < p; r++)
+      E(t.children[r], e, l, y, c);
   }
   this.render = function(t, e) {
-    let l = e.projectionMatrix.elements[5] * g;
-    if (f.camera.fov !== l && (e.isPerspectiveCamera ? (a.style.WebkitPerspective = l + "px", a.style.perspective = l + "px") : (a.style.WebkitPerspective = "", a.style.perspective = ""), f.camera.fov = l), t.autoUpdate === !0 && t.updateMatrixWorld(), e.parent === null && e.updateMatrixWorld(), e.isOrthographicCamera)
-      var h = -(e.right + e.left) / 2, v = (e.top + e.bottom) / 2;
-    let u = e.isOrthographicCamera ? "scale(" + l + ")translate(" + r(h) + "px," + r(v) + "px)" + O(e.matrixWorldInverse) : "translateZ(" + l + "px)" + O(e.matrixWorldInverse), i = u + "translate(" + M + "px," + g + "px)";
-    f.camera.style !== i && (n.style.WebkitTransform = i, n.style.transform = i, f.camera.style = i);
-    const d = t.uuid + "_" + performance.now().toString();
-    D(t, t, e, u, d), f.objects.forEach(function(m, s) {
-      s.flag !== d && (s.element.remove(), f.objects.delete(s));
+    let l = e.projectionMatrix.elements[5] * S;
+    if (d.camera.fov !== l && (e.isPerspectiveCamera ? (a.style.WebkitPerspective = l + "px", a.style.perspective = l + "px") : (a.style.WebkitPerspective = "", a.style.perspective = ""), d.camera.fov = l), t.autoUpdate === !0 && t.updateMatrixWorld(), e.parent === null && e.updateMatrixWorld(), e.isOrthographicCamera)
+      var y = -(e.right + e.left) / 2, c = (e.top + e.bottom) / 2;
+    let x = e.isOrthographicCamera ? "scale(" + l + ")translate(" + n(y) + "px," + n(c) + "px)" + C(e.matrixWorldInverse) : "translateZ(" + l + "px)" + C(e.matrixWorldInverse), r = x + "translate(" + g + "px," + S + "px)";
+    d.camera.style !== r && (i.style.WebkitTransform = r, i.style.transform = r, d.camera.style = r);
+    const p = t.uuid + "_" + performance.now().toString();
+    E(t, t, e, x, p), d.objects.forEach(function(m, s) {
+      s.flag !== p && (s.element.remove(), d.objects.delete(s));
     });
   };
 };
 export {
-  c as CSS3DObject,
+  b as CSS3DObject,
   I as CSS3DRenderer,
-  C as CSS3DSprite
+  P as CSS3DSprite
 };

package/libs/shared-utils/three/Extras/Curves/BezierCurve3.d.ts

@@ -1,12 +1,13 @@
 import * as THREE from 'three';
 declare class CustomBezierCurve3 extends THREE.Curve<THREE.Vector3> {
-    type: string;
+    /** r183 起 Curve.type 是 readonly，不能像原实现那样在构造函数里赋值，改为字段声明 */
+    readonly type = "CustomBezierCurve3";
     controlPoints: THREE.Vector3[];
     constructor(controlPoints?: THREE.Vector3[]);
     getPoint(t: number, optionalTarget?: THREE.Vector3): THREE.Vector3;
     copy(source: CustomBezierCurve3): this;
-    toJSON(): object & {
-        controlPoints: number[][];
+    toJSON(): THREE.CurveJSON & {
+        controlPoints: THREE.Vector3Tuple[];
     };
     fromJSON(json: any): this;
 }

package/libs/shared-utils/three/Extras/Curves/BezierCurve3.js

@@ -1,14 +1,15 @@
-var p = Object.defineProperty;
-var a = (n, o, t) => o in n ? p(n, o, { enumerable: !0, configurable: !0, writable: !0, value: t }) : n[o] = t;
-var i = (n, o, t) => (a(n, typeof o != "symbol" ? o + "" : o, t), t);
+var a = Object.defineProperty;
+var p = (n, o, t) => o in n ? a(n, o, { enumerable: !0, configurable: !0, writable: !0, value: t }) : n[o] = t;
+var i = (n, o, t) => (p(n, typeof o != "symbol" ? o + "" : o, t), t);
 import * as c from "three";
 import { Bezier as u } from "../Core/Interpolations.js";
 class P extends c.Curve {
   constructor(t = []) {
     super();
-    i(this, "type");
+    /** r183 起 Curve.type 是 readonly，不能像原实现那样在构造函数里赋值，改为字段声明 */
+    i(this, "type", "CustomBezierCurve3");
     i(this, "controlPoints");
-    this.type = "CustomBezierCurve3", this.controlPoints = t;
+    this.controlPoints = t;
   }
   getPoint(t, r = new c.Vector3()) {
     const s = r, e = u(t, this.controlPoints);

package/libs/shared-utils/three/FragmentTransparencyMaterial.d.ts

@@ -1,17 +1,15 @@
 import * as THREE from 'three';
-export declare class FragmentTransparencyMaterial extends THREE.ShaderMaterial {
-    uniforms: {
-        map: {
-            value: THREE.Texture;
-        };
-    };
-    transparent: boolean;
-    blending: THREE.Blending;
-    blendSrc: THREE.BlendingDstFactor;
-    blendDst: THREE.BlendingDstFactor;
-    blendSrcAlpha: THREE.BlendingDstFactor;
-    blendDstAlpha: THREE.BlendingDstFactor;
-    vertexShader: string;
-    fragmentShader: string;
+/**
+ * 「保持在不透明渲染队列里，但仍做 alpha 混合」的贴图材质。
+ *
+ * 原实现是一个 `ShaderMaterial`，但它的 GLSL 只有一行 `gl_FragColor = texture2D(map, vUv)`，
+ * 即纯粹的贴图采样，没有任何自定义计算 —— 真正起作用的是下面那套自定义混合配置
+ * （`transparent = false` 保证它留在不透明队列、不参与透明排序，同时用 `CustomBlending`
+ * 强制开启 SrcAlpha / OneMinusSrcAlpha 混合）。
+ *
+ * WebGPU 不消费裸 GLSL，而这个 shader 又无需保留，因此直接降级为内置 `MeshBasicMaterial`
+ * 并原样保留混合参数，视觉与原实现等价。
+ */
+export declare class FragmentTransparencyMaterial extends THREE.MeshBasicMaterial {
     constructor(texture: THREE.Texture);
 }

package/libs/shared-utils/three/FragmentTransparencyMaterial.js

@@ -1,46 +1,18 @@
-var i = Object.defineProperty;
-var o = (n, a, e) => a in n ? i(n, a, { enumerable: !0, configurable: !0, writable: !0, value: e }) : n[a] = e;
-var r = (n, a, e) => (o(n, typeof a != "symbol" ? a + "" : a, e), e);
-import * as t from "three";
-class s extends t.ShaderMaterial {
-  constructor(e) {
-    super();
-    r(this, "transparent", !1);
-    r(this, "blending", t.CustomBlending);
-    r(this, "blendSrc", t.SrcAlphaFactor);
-    r(this, "blendDst", t.OneMinusSrcAlphaFactor);
-    r(this, "blendSrcAlpha", t.OneFactor);
-    r(this, "blendDstAlpha", t.OneMinusSrcAlphaFactor);
-    r(
-      this,
-      "vertexShader",
-      /* glsl */
-      `
-    varying vec2 vUv;
-    void main() {
-      vUv = uv;
-      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
-    }
-  `
-    );
-    r(
-      this,
-      "fragmentShader",
-      /* glsl */
-      `
-    uniform sampler2D map;
-    // 纹理坐标
-    varying vec2 vUv;
-    void main() {
-      gl_FragColor = texture2D(map, vUv);
-    }
-  `
-    );
-    this.uniforms = {
-      map: { value: e }
-    };
+import * as a from "three";
+class n extends a.MeshBasicMaterial {
+  constructor(r) {
+    super({
+      map: r,
+      // 以下混合配置与原 ShaderMaterial 逐项一致
+      transparent: !1,
+      blending: a.CustomBlending,
+      blendSrc: a.SrcAlphaFactor,
+      blendDst: a.OneMinusSrcAlphaFactor,
+      blendSrcAlpha: a.OneFactor,
+      blendDstAlpha: a.OneMinusSrcAlphaFactor
+    });
   }
 }
 export {
-  s as FragmentTransparencyMaterial
+  n as FragmentTransparencyMaterial
 };

package/libs/shared-utils/three/GLTFLoader.d.ts

@@ -1,2 +1,13 @@
-import type { GLTF } from '@realsee/five/gltf-loader';
-export default function loadGLTF(url: string): Promise<GLTF>;
+import { loadGltf } from '@realsee/five-webgpu';
+export type GLTFLoadResult = Awaited<ReturnType<typeof loadGltf>>;
+/**
+ * five-webgpu 移除了 `gltf-loader` 入口，改为顶层导出 `loadGltf`（url → Promise）。
+ * 本函数对外契约不变，仍是 `loadGLTF(url): Promise<...>`，只是结果类型从 `GLTF` 变成
+ * five 的 `LoadResultType`（`scene` / `textures` / `animations` / `dispose` 等）。
+ *
+ * ⚠️ `upAxis: 'Y'` 不可省略。`loadGltf` 默认 `modelUpAxis='Y'` + `upAxis='Z'`，会给内容
+ * 叠一次 ROTATE_X_MATRIX 把模型从 Y-up 转成 Z-up；而原先的 three GLTFLoader 不做任何旋转。
+ * 显式传 `upAxis: 'Y'` 会再叠一次 ROTATE_X_MATRIX_INVERSE，两次抵消，从而保持原朝向。
+ * 若省略，PanoTag 的 3D 模型标签会整体躺倒 90°。
+ */
+export default function loadGLTF(url: string): Promise<import("@realsee/five-webgpu").LoadResultType>;

package/libs/shared-utils/three/GLTFLoader.js

@@ -1,15 +1,6 @@
-import { GLTFLoader as i } from "@realsee/five/gltf-loader";
-const a = new i();
-function f(n) {
-  return new Promise((r, e) => {
-    function t(o) {
-      r(o);
-    }
-    function d(o) {
-      e(o);
-    }
-    a.load(n, t, void 0, d);
-  });
+import { loadGltf as r } from "@realsee/five-webgpu";
+function f(o) {
+  return r(o, { upAxis: "Y" });
 }
 export {
   f as loadGLTF

package/libs/shared-utils/three/Magnifier.d.ts

@@ -1,4 +1,4 @@
-import type { Five, SubscribeEventMap } from '@realsee/five';
+import type { Five, SubscribeEventMap } from '@realsee/five-webgpu';
 import Hammer from 'hammerjs';
 import * as THREE from 'three';
 import { Subscribe } from '../Subscribe';
@@ -57,7 +57,25 @@ export declare class Magnifier {
         y: number;
     }): void;
     resetOffset(): void;
-    render(): void;
+    /**
+     * WebGPU 不支持同步回读像素，five-webgpu 的 `getPixels()` 因此返回 `Promise`，本方法随之变为 async。
+     *
+     * 现有约 10 个调用点都是即发即忘（不 await），签名变化对它们透明；
+     * 但异步化带来了并发问题：逐帧调用时多个回读可能交错完成、乱序写入 canvas。
+     *
+     * 这里的策略是「丢中间帧、但绝不丢最后一帧」：
+     * 有回读在途时不再并发发起，只登记 `renderRequested`；当前这次结束后再补跑一次。
+     *
+     * ⚠️ 不能简单地「在途就 return」了事：调用方是先更新 `renderCenter` 再调 `render()` 的
+     * （见 renderWithPoint / renderWithScreenPoint）。若直接丢弃，手指抬起前的最后一次调用
+     * 恰好撞上在途回读时，这一帧就永远不会被渲染，放大镜会停在上一个位置不动。
+     * `renderOnce()` 每次都重新读 `this.renderCenter`，所以补跑拿到的是最新位置。
+     */
+    render(): Promise<void>;
+    private renderPending;
+    /** 在途期间是否又来了新的渲染请求，用于结束后补跑最后一帧 */
+    private renderRequested;
+    private renderOnce;
     protected getRenderCenter(): THREE.Vector3 | {
         x: number;
         y: number;