@terraware/web-components 5.0.2 → 5.0.4

package/components/VirtualWalkthrough/vr-annotation-panel.js

@@ -1,19 +1,22 @@
-import { Vec3, Script, Quat, Texture, FILTER_LINEAR, ADDRESS_CLAMP_TO_EDGE, StandardMaterial, Color, BLEND_NORMAL, CULLFACE_NONE, MeshInstance, LAYERID_IMMEDIATE, Mesh } from 'playcanvas';
-import { wrapText } from './vr-annotation-panel-layout.js';
+import { Vec3, Script, Quat, StandardMaterial, MeshInstance, Color, BLEND_NORMAL, CULLFACE_NONE, LAYERID_IMMEDIATE, Texture, FILTER_LINEAR, ADDRESS_CLAMP_TO_EDGE, Mesh } from 'playcanvas';
+import { PANEL_MAX_HEIGHT, PANEL_CANVAS_WIDTH, layoutPanel, PANEL_PAD_X, PANEL_FONTS, TITLE_LINE_HEIGHT, BODY_LINE_HEIGHT } from './vr-annotation-panel-layout.js';
+import { readScrollAxis, nextScrollY } from './vr-annotation-scroll.js';
 import { rayQuadHit } from './xr-ray-quad.js';
 
-const CANVAS_WIDTH = 1024;
-const CANVAS_HEIGHT = 768;
 const PANEL_WIDTH = 7.5;
-const PANEL_HEIGHT = PANEL_WIDTH * CANVAS_HEIGHT / CANVAS_WIDTH;
 
 /** Gap (m) between the top of the hotspot and the bottom edge of the panel. */
 const PANEL_GAP = 0.75;
+const PX_TO_M = PANEL_WIDTH / PANEL_CANVAS_WIDTH;
 
-/** World-space offset from the anchored hotspot: raise the panel above it so the
- * (tall) panel clears the hotspot rather than covering it. */
-const PANEL_OFFSET = new Vec3(0, PANEL_HEIGHT / 2 + PANEL_GAP, 0);
-const PAD_X = 48;
+/** Local +z faces the viewer, so the overlay quads sit just in front of the chrome quad. Their
+ * draw order would otherwise depend on how the transparent sort breaks a tie between coplanar
+ * quads, all of which have depth testing off. */
+const TEXT_Z = 0.001;
+const THUMB_Z = 0.002;
+const SCROLLBAR_WIDTH = 10;
+const SCROLLBAR_INSET = 18;
+const SCROLLBAR_MIN_HEIGHT = 48;
 
 /** Local +z (the quad's front face) — used to derive the panel's yaw toward the viewer. */
 const FORWARD_Z = new Vec3(0, 0, 1);
@@ -22,10 +25,6 @@ const RIGHT_AXIS = new Vec3(1, 0, 0);
 const UP_AXIS = new Vec3(0, 1, 0);
 const RAD_TO_DEG = 180 / Math.PI;
 
-/** Fixed image band (canvas px) so arrows/dots keep a stable position while images load. */
-const IMAGE_Y = 40;
-const IMAGE_H = 360;
-
 /** Width (canvas px) of the left/right arrow hit + draw zones over the image band. */
 const ARROW_ZONE_W = 170;
 class VrAnnotationPanel extends Script {
@@ -37,6 +36,11 @@ class VrAnnotationPanel extends Script {
   _drawnSignature = null;
   _currentImage = 0;
   _loadToken = 0;
+  _scrollY = 0;
+  _maxScroll = 0;
+  /** Height (canvas px) the chrome occupies; the rest of its canvas is unused. */
+  _canvasHeight = PANEL_MAX_HEIGHT;
+  _panelHeight = PANEL_MAX_HEIGHT * PX_TO_M;
   _headRotation = new Quat();
   _anchor = new Vec3();
   _scratchDir = new Vec3();
@@ -49,73 +53,136 @@ class VrAnnotationPanel extends Script {
       return;
     }
     const images = this.imageUrls ?? [];
-    if (images.length <= 1) {
+    const band = this._layout?.image;
+    if (images.length <= 1 || !band) {
       return;
     }
     const hit = this._rayQuadHit(inputSource.getOrigin(), inputSource.getDirection());
     if (!hit) {
       return;
     }
-    const cx = (hit.u + 1) / 2 * CANVAS_WIDTH;
-    const cy = (1 - hit.v) / 2 * CANVAS_HEIGHT;
-    if (cy < IMAGE_Y || cy > IMAGE_Y + IMAGE_H) {
+    const cx = (hit.u + 1) / 2 * PANEL_CANVAS_WIDTH;
+    // The image sits on the chrome quad, which doesn't scroll, so this needs no scroll offset.
+    const cy = (1 - hit.v) / 2 * this._canvasHeight;
+    if (cy < band.y || cy > band.y + band.height) {
       return;
     }
     if (cx <= ARROW_ZONE_W) {
       this._setImage((this._currentImage - 1 + images.length) % images.length);
-    } else if (cx >= CANVAS_WIDTH - ARROW_ZONE_W) {
+    } else if (cx >= PANEL_CANVAS_WIDTH - ARROW_ZONE_W) {
       this._setImage((this._currentImage + 1) % images.length);
     }
   };
   initialize() {
-    this._canvas = document.createElement('canvas');
-    this._canvas.width = CANVAS_WIDTH;
-    this._canvas.height = CANVAS_HEIGHT;
-    this._texture = new Texture(this.app.graphicsDevice, {
-      name: 'vr-annotation-panel',
-      width: CANVAS_WIDTH,
-      height: CANVAS_HEIGHT,
+    this._chromeCanvas = document.createElement('canvas');
+    this._chromeCanvas.width = PANEL_CANVAS_WIDTH;
+    this._chromeCanvas.height = PANEL_MAX_HEIGHT;
+    this._chromeTexture = this._createTexture('vr-annotation-panel', this._chromeCanvas);
+    this._chromeMaterial = this._createTexturedMaterial(this._chromeTexture);
+    this._chromeMesh = this._createQuadMesh();
+
+    // Sized once the first layout runs; until then it has nothing to show.
+    this._textMesh = this._createQuadMesh();
+    this._textMaterial = new StandardMaterial();
+    this._textInstance = new MeshInstance(this._textMesh, this._textMaterial);
+    this._textInstance.visible = false;
+    this._thumbMaterial = new StandardMaterial();
+    this._thumbMaterial.useLighting = false;
+    this._thumbMaterial.emissive = new Color(0, 0, 0);
+    this._thumbMaterial.opacity = 0.3;
+    this._thumbMaterial.blendType = BLEND_NORMAL;
+    this._thumbMaterial.depthTest = false;
+    this._thumbMaterial.depthWrite = false;
+    this._thumbMaterial.cull = CULLFACE_NONE;
+    this._thumbMaterial.update();
+    this._thumbMesh = this._createQuadMesh();
+    this._thumbInstance = new MeshInstance(this._thumbMesh, this._thumbMaterial);
+    this._thumbInstance.visible = false;
+    this.entity.addComponent('render', {
+      meshInstances: [new MeshInstance(this._chromeMesh, this._chromeMaterial), this._textInstance, this._thumbInstance],
+      layers: [LAYERID_IMMEDIATE]
+    });
+    this.app.xr?.input?.on('select', this._onSelect);
+    // Script removal fires a 'destroy' event rather than calling a destroy() method, so the
+    // teardown has to be registered as a listener or the handler and GPU resources outlive us.
+    this.once('destroy', () => this._teardown());
+  }
+  _createTexture(name, source) {
+    const texture = new Texture(this.app.graphicsDevice, {
+      name,
+      width: source.width,
+      height: source.height,
       addressU: ADDRESS_CLAMP_TO_EDGE,
       addressV: ADDRESS_CLAMP_TO_EDGE,
       minFilter: FILTER_LINEAR,
       magFilter: FILTER_LINEAR,
       mipmaps: true
     });
-    this._texture.setSource(this._canvas);
+    texture.setSource(source);
+    return texture;
+  }
+  _createTexturedMaterial(texture) {
     const material = new StandardMaterial();
     material.useLighting = false;
     material.emissive = new Color(1, 1, 1);
-    material.emissiveMap = this._texture;
-    material.opacityMap = this._texture;
+    material.emissiveMap = texture;
+    material.opacityMap = texture;
     material.opacityMapChannel = 'a';
     material.blendType = BLEND_NORMAL;
     material.depthTest = false;
     material.depthWrite = false;
     material.cull = CULLFACE_NONE;
     material.update();
-    this._material = material;
-    this._mesh = this._createMesh();
-    const meshInstance = new MeshInstance(this._mesh, material);
-    this.entity.addComponent('render', {
-      meshInstances: [meshInstance],
-      layers: [LAYERID_IMMEDIATE]
-    });
-    this.app.xr?.input?.on('select', this._onSelect);
-    // Script removal fires a 'destroy' event rather than calling a destroy() method, so the
-    // teardown has to be registered as a listener or the handler and GPU resources outlive us.
-    this.once('destroy', () => this._teardown());
+    return material;
   }
-  _createMesh() {
-    const hw = PANEL_WIDTH / 2;
-    const hh = PANEL_HEIGHT / 2;
+  _createQuadMesh() {
     const mesh = new Mesh(this.app.graphicsDevice);
-    mesh.setPositions([-hw, -hh, 0, hw, -hh, 0, hw, hh, 0, -hw, hh, 0]);
     mesh.setNormals([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]);
-    mesh.setUvs(0, [0, 1, 1, 1, 1, 0, 0, 0]);
     mesh.setIndices([0, 1, 2, 0, 2, 3]);
-    mesh.update();
+    this._writeQuad(mesh, -PANEL_WIDTH / 2, PANEL_WIDTH / 2, 0, 0, 0, 0, 1);
     return mesh;
   }
+
+  /** Rewrites the quad's four corners and the slice of its texture they map to. */
+  _writeQuad(mesh, left, right, top, bottom, z, vTop, vBottom) {
+    mesh.setPositions([left, bottom, z, right, bottom, z, right, top, z, left, top, z]);
+    mesh.setUvs(0, [0, vBottom, 1, vBottom, 1, vTop, 0, vTop]);
+    mesh.update();
+  }
+
+  /** Converts a y in panel canvas coordinates to the entity's local space. */
+  _localY(canvasY) {
+    return this._panelHeight / 2 - canvasY * PX_TO_M;
+  }
+  _writeChromeQuad() {
+    if (!this._chromeMesh) {
+      return;
+    }
+    const hw = PANEL_WIDTH / 2;
+    const hh = this._panelHeight / 2;
+    this._writeQuad(this._chromeMesh, -hw, hw, hh, -hh, 0, 0, this._canvasHeight / PANEL_MAX_HEIGHT);
+  }
+
+  /** Maps the visible window of the (much taller) text texture onto the body quad. */
+  _writeTextQuad() {
+    const body = this._layout?.body;
+    if (!this._textMesh || !this._textInstance || !body || body.contentHeight === 0) {
+      return;
+    }
+    this._writeQuad(this._textMesh, -PANEL_WIDTH / 2, PANEL_WIDTH / 2, this._localY(body.y), this._localY(body.y + body.viewportHeight), TEXT_Z, this._scrollY / body.contentHeight, (this._scrollY + body.viewportHeight) / body.contentHeight);
+  }
+  _writeThumbQuad() {
+    const body = this._layout?.body;
+    if (!this._thumbMesh || !body?.scrollable) {
+      return;
+    }
+    // The minimum keeps the thumb grabbable on very long text, but never past the track itself.
+    const height = Math.min(body.viewportHeight, Math.max(SCROLLBAR_MIN_HEIGHT, body.viewportHeight * body.viewportHeight / body.contentHeight));
+    const travel = body.viewportHeight - height;
+    const top = body.y + (this._maxScroll > 0 ? this._scrollY / this._maxScroll * travel : 0);
+    const right = PANEL_CANVAS_WIDTH - SCROLLBAR_INSET;
+    this._writeQuad(this._thumbMesh, (right - SCROLLBAR_WIDTH) * PX_TO_M - PANEL_WIDTH / 2, right * PX_TO_M - PANEL_WIDTH / 2, this._localY(top), this._localY(top + height), THUMB_Z, 0, 1);
+  }
   _roundRect(ctx, x, y, w, h, r) {
     ctx.beginPath();
     ctx.moveTo(x + r, y);
@@ -143,7 +210,7 @@ class VrAnnotationPanel extends Script {
   }
   _drawDots(ctx, count, dotY) {
     const gap = 26;
-    const startX = CANVAS_WIDTH / 2 - (count - 1) * gap / 2;
+    const startX = PANEL_CANVAS_WIDTH / 2 - (count - 1) * gap / 2;
     for (let i = 0; i < count; i++) {
       ctx.beginPath();
       ctx.arc(startX + i * gap, dotY, 7, 0, Math.PI * 2);
@@ -151,83 +218,144 @@ class VrAnnotationPanel extends Script {
       ctx.fill();
     }
   }
-  _drawContent(image) {
-    const ctx = this._canvas?.getContext('2d');
+
+  /** Re-measures the content, resizes the panel, and repaints both canvases. */
+  _rebuild() {
+    const ctx = this._chromeCanvas?.getContext('2d');
     if (!ctx) {
       return;
     }
-    ctx.clearRect(0, 0, CANVAS_WIDTH, CANVAS_HEIGHT);
+    const images = this.imageUrls ?? [];
+    this._layout = layoutPanel({
+      title: this.title,
+      label: this.label,
+      bodyText: this.bodyText,
+      imageCount: images.length,
+      contentWidth: PANEL_CANVAS_WIDTH - PANEL_PAD_X * 2,
+      measure: (text, style) => {
+        ctx.font = PANEL_FONTS[style];
+        return ctx.measureText(text).width;
+      }
+    });
+    const {
+      body
+    } = this._layout;
+    this._maxScroll = body.contentHeight - body.viewportHeight;
+    this._canvasHeight = this._layout.height;
+    this._panelHeight = this._layout.height * PX_TO_M;
+    this._drawChrome();
+    this._drawText();
+    this._writeChromeQuad();
+    this._writeTextQuad();
+    this._writeThumbQuad();
+    if (this._textInstance) {
+      this._textInstance.visible = body.contentHeight > 0;
+    }
+    if (this._thumbInstance) {
+      this._thumbInstance.visible = body.scrollable;
+    }
+  }
+  _drawChrome() {
+    const ctx = this._chromeCanvas?.getContext('2d');
+    const layout = this._layout;
+    if (!ctx || !layout) {
+      return;
+    }
+    const contentWidth = PANEL_CANVAS_WIDTH - PANEL_PAD_X * 2;
+    const images = this.imageUrls ?? [];
+    ctx.clearRect(0, 0, PANEL_CANVAS_WIDTH, PANEL_MAX_HEIGHT);
     ctx.fillStyle = 'rgba(255, 255, 255, 0.96)';
-    this._roundRect(ctx, 0, 0, CANVAS_WIDTH, CANVAS_HEIGHT, 32);
+    this._roundRect(ctx, 0, 0, PANEL_CANVAS_WIDTH, layout.height, 32);
     ctx.fill();
-    let y = IMAGE_Y;
-    const contentWidth = CANVAS_WIDTH - PAD_X * 2;
-    const images = this.imageUrls ?? [];
-    if (images.length > 0) {
+    if (layout.image) {
+      const {
+        y: bandY,
+        height: bandH
+      } = layout.image;
       ctx.save();
-      this._roundRect(ctx, PAD_X, IMAGE_Y, contentWidth, IMAGE_H, 16);
+      this._roundRect(ctx, PANEL_PAD_X, bandY, contentWidth, bandH, 16);
       ctx.clip();
+      const image = this._loadedImage;
       if (image) {
-        const scale = Math.max(contentWidth / image.width, IMAGE_H / image.height);
+        const scale = Math.max(contentWidth / image.width, bandH / image.height);
         const dw = image.width * scale;
         const dh = image.height * scale;
-        ctx.drawImage(image, PAD_X + (contentWidth - dw) / 2, IMAGE_Y + (IMAGE_H - dh) / 2, dw, dh);
+        ctx.drawImage(image, PANEL_PAD_X + (contentWidth - dw) / 2, bandY + (bandH - dh) / 2, dw, dh);
       } else {
         ctx.fillStyle = 'rgba(0, 0, 0, 0.06)';
-        ctx.fillRect(PAD_X, IMAGE_Y, contentWidth, IMAGE_H);
+        ctx.fillRect(PANEL_PAD_X, bandY, contentWidth, bandH);
       }
       ctx.restore();
-      y = IMAGE_Y + IMAGE_H + 16;
-      if (images.length > 1) {
-        const bandCenterY = IMAGE_Y + IMAGE_H / 2;
+      if (layout.dotsY !== null) {
+        const bandCenterY = bandY + bandH / 2;
         this._drawArrow(ctx, ARROW_ZONE_W / 2, bandCenterY, true);
-        this._drawArrow(ctx, CANVAS_WIDTH - ARROW_ZONE_W / 2, bandCenterY, false);
-        this._drawDots(ctx, images.length, y + 4);
-        y += 32;
+        this._drawArrow(ctx, PANEL_CANVAS_WIDTH - ARROW_ZONE_W / 2, bandCenterY, false);
+        this._drawDots(ctx, images.length, layout.dotsY);
       }
-      y += 16;
     }
-    if (this.label) {
-      ctx.font = '600 28px sans-serif';
+    if (layout.chip && this.label) {
+      ctx.font = PANEL_FONTS.label;
       ctx.textBaseline = 'middle';
-      const chipW = ctx.measureText(this.label).width + 32;
-      const chipH = 44;
       ctx.fillStyle = 'rgba(44, 134, 88, 0.95)';
-      this._roundRect(ctx, PAD_X, y, chipW, chipH, 12);
+      this._roundRect(ctx, PANEL_PAD_X, layout.chip.y, layout.chip.width, layout.chip.height, 12);
       ctx.fill();
       ctx.fillStyle = '#ffffff';
-      ctx.fillText(this.label, PAD_X + 16, y + chipH / 2);
-      y += chipH + 24;
+      ctx.fillText(this.label, PANEL_PAD_X + 16, layout.chip.y + layout.chip.height / 2);
     }
     ctx.textBaseline = 'top';
     ctx.fillStyle = '#000000';
-    ctx.font = '700 48px sans-serif';
-    const titleLines = wrapText(this.title, contentWidth, s => ctx.measureText(s).width);
-    for (const line of titleLines) {
-      if (y > CANVAS_HEIGHT - 40) {
-        break;
-      }
-      ctx.fillText(line, PAD_X, y);
-      y += 56;
+    ctx.font = PANEL_FONTS.title;
+    layout.title.lines.forEach((line, index) => {
+      ctx.fillText(line, PANEL_PAD_X, layout.title.y + index * TITLE_LINE_HEIGHT);
+    });
+    if (layout.body.scrollable) {
+      ctx.fillStyle = 'rgba(0, 0, 0, 0.08)';
+      const trackX = PANEL_CANVAS_WIDTH - SCROLLBAR_INSET - SCROLLBAR_WIDTH;
+      this._roundRect(ctx, trackX, layout.body.y, SCROLLBAR_WIDTH, layout.body.viewportHeight, SCROLLBAR_WIDTH / 2);
+      ctx.fill();
     }
-    y += 16;
-    if (this.bodyText) {
-      ctx.font = '400 32px sans-serif';
-      ctx.fillStyle = 'rgba(0, 0, 0, 0.85)';
-      const lines = wrapText(this.bodyText, contentWidth, s => ctx.measureText(s).width);
-      for (const line of lines) {
-        if (y > CANVAS_HEIGHT - 40) {
-          break;
-        }
-        ctx.fillText(line, PAD_X, y);
-        y += 40;
+    this._chromeTexture?.upload();
+  }
+
+  /**
+   * Paints every body line onto its own canvas, tall enough to hold all of them. Scrolling then
+   * only moves the quad's UV window over this texture, so no repaint or upload happens per frame.
+   */
+  _drawText() {
+    const body = this._layout?.body;
+    if (!body) {
+      return;
+    }
+    const height = Math.max(1, body.contentHeight);
+    if (!this._textCanvas || this._textCanvas.height !== height) {
+      this._textCanvas = document.createElement('canvas');
+      this._textCanvas.width = PANEL_CANVAS_WIDTH;
+      this._textCanvas.height = height;
+      this._textTexture?.destroy();
+      this._textTexture = this._createTexture('vr-annotation-panel-text', this._textCanvas);
+      this._textMaterial?.destroy();
+      this._textMaterial = this._createTexturedMaterial(this._textTexture);
+      if (this._textInstance) {
+        this._textInstance.material = this._textMaterial;
       }
     }
-    this._texture?.upload();
+    const ctx = this._textCanvas.getContext('2d');
+    if (!ctx) {
+      return;
+    }
+    ctx.clearRect(0, 0, PANEL_CANVAS_WIDTH, height);
+    ctx.textBaseline = 'top';
+    ctx.font = PANEL_FONTS.body;
+    ctx.fillStyle = 'rgba(0, 0, 0, 0.85)';
+    body.lines.forEach((line, index) => {
+      ctx.fillText(line, PANEL_PAD_X, index * BODY_LINE_HEIGHT);
+    });
+    this._textTexture?.upload();
   }
   _setImage(index) {
     this._currentImage = index;
-    this._drawContent();
+    this._loadedImage = undefined;
+    this._drawChrome();
     this._loadCurrentImage();
   }
   _loadCurrentImage() {
@@ -241,7 +369,8 @@ class VrAnnotationPanel extends Script {
     img.onload = () => {
       // Ignore a stale load that a newer navigation has superseded.
       if (token === this._loadToken) {
-        this._drawContent(img);
+        this._loadedImage = img;
+        this._drawChrome();
       }
     };
     // onerror (e.g. a host without CORS headers): keep the placeholder + text already drawn.
@@ -253,7 +382,7 @@ class VrAnnotationPanel extends Script {
     rotation.transformVector(UP_AXIS, this._axisUp);
     this.entity.getWorldTransform().getScale(this._scratchScale);
     const halfWidth = PANEL_WIDTH / 2 * this._scratchScale.x;
-    const halfHeight = PANEL_HEIGHT / 2 * this._scratchScale.y;
+    const halfHeight = this._panelHeight / 2 * this._scratchScale.y;
     return rayQuadHit(origin, direction, this.entity.getPosition(), this._axisRight, this._axisUp, halfWidth, halfHeight);
   }
 
@@ -261,7 +390,7 @@ class VrAnnotationPanel extends Script {
   rayHitsPanel(origin, direction) {
     return this._rayQuadHit(origin, direction) !== null;
   }
-  update() {
+  update(dt) {
     if (this.app.xr?.active !== true) {
       return;
     }
@@ -269,16 +398,19 @@ class VrAnnotationPanel extends Script {
     if (signature !== this._drawnSignature) {
       this._drawnSignature = signature;
       this._currentImage = 0;
-      this._drawContent();
+      this._scrollY = 0;
+      this._loadedImage = undefined;
+      this._rebuild();
       this._loadCurrentImage();
     }
+    this._scroll(dt);
     this._trackHead();
     const anchor = this.app.root.findByName(`annotation-${this.annotationIndex}`);
     if (!anchor) {
       return;
     }
     this._anchor.copy(anchor.getPosition());
-    this.entity.setPosition(this._anchor.x + PANEL_OFFSET.x, this._anchor.y + PANEL_OFFSET.y, this._anchor.z + PANEL_OFFSET.z);
+    this.entity.setPosition(this._anchor.x, this._anchor.y + this._panelHeight / 2 + PANEL_GAP, this._anchor.z);
 
     // Billboard on yaw only: face the viewer horizontally but stay upright and level, so
     // tilting/rolling the headset does not tilt the panel. Derived from the head's forward
@@ -288,6 +420,25 @@ class VrAnnotationPanel extends Script {
     this._yawQuat.setFromEulerAngles(0, yaw, 0);
     this.entity.setRotation(this._yawQuat);
   }
+  _scroll(dt) {
+    if (this._maxScroll <= 0) {
+      return;
+    }
+    let axis = 0;
+    for (const inputSource of this.app.xr?.input?.inputSources ?? []) {
+      const sourceAxis = readScrollAxis(inputSource);
+      if (Math.abs(sourceAxis) > Math.abs(axis)) {
+        axis = sourceAxis;
+      }
+    }
+    const scrollY = nextScrollY(this._scrollY, axis, dt, this._maxScroll);
+    if (scrollY === this._scrollY) {
+      return;
+    }
+    this._scrollY = scrollY;
+    this._writeTextQuad();
+    this._writeThumbQuad();
+  }
   _trackHead() {
     const views = this.app.xr?.views?.list;
     if (!views || views.length === 0) {
@@ -300,12 +451,22 @@ class VrAnnotationPanel extends Script {
     if (this.entity.render) {
       this.entity.render.meshInstances = [];
     }
-    this._mesh?.destroy();
-    this._material?.destroy();
-    this._texture?.destroy();
-    this._mesh = undefined;
-    this._material = undefined;
-    this._texture = undefined;
+    this._chromeMesh?.destroy();
+    this._textMesh?.destroy();
+    this._thumbMesh?.destroy();
+    this._chromeMaterial?.destroy();
+    this._textMaterial?.destroy();
+    this._thumbMaterial?.destroy();
+    this._chromeTexture?.destroy();
+    this._textTexture?.destroy();
+    this._chromeMesh = undefined;
+    this._textMesh = undefined;
+    this._thumbMesh = undefined;
+    this._chromeMaterial = undefined;
+    this._textMaterial = undefined;
+    this._thumbMaterial = undefined;
+    this._chromeTexture = undefined;
+    this._textTexture = undefined;
   }
 }
 

package/components/VirtualWalkthrough/vr-annotation-scroll.d.ts

@@ -0,0 +1,23 @@
+/** Deflection the stick must pass before the text moves, so a resting thumb doesn't drift it. */
+export declare const SCROLL_DEADZONE = 0.15;
+/** Canvas px per second at full deflection. */
+export declare const SCROLL_SPEED = 1200;
+interface ThumbstickSource {
+    handedness: string;
+    gamepad?: {
+        axes: ArrayLike<number>;
+    } | null;
+}
+/**
+ * Thumbstick Y for a source that can scroll the panel. Only the right hand scrolls: the left
+ * stick drives locomotion, and right-stick Y is free because snap-vertical is turned off.
+ * Hand-tracked sources report a gamepad with no axes, which would read as NaN.
+ */
+export declare const readScrollAxis: (inputSource: ThumbstickSource) => number;
+/**
+ * Advances the scroll position for one frame of stick deflection, ramping from a standstill at
+ * the deadzone edge. A forward push reports negative Y and moves further into the text.
+ */
+export declare const nextScrollY: (scrollY: number, axisY: number, dt: number, maxScroll: number) => number;
+export {};
+//# sourceMappingURL=vr-annotation-scroll.d.ts.map

package/components/VirtualWalkthrough/vr-annotation-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vr-annotation-scroll.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/vr-annotation-scroll.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,+CAA+C;AAC/C,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,UAAU,gBAAgB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9C;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,gBAAgB,KAAG,MAO9D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,EAAE,IAAI,MAAM,EAAE,WAAW,MAAM,KAAG,MAU3F,CAAC"}

package/components/VirtualWalkthrough/vr-annotation-scroll.js

@@ -0,0 +1,33 @@
+/** Deflection the stick must pass before the text moves, so a resting thumb doesn't drift it. */
+const SCROLL_DEADZONE = 0.15;
+
+/** Canvas px per second at full deflection. */
+const SCROLL_SPEED = 1200;
+/**
+ * Thumbstick Y for a source that can scroll the panel. Only the right hand scrolls: the left
+ * stick drives locomotion, and right-stick Y is free because snap-vertical is turned off.
+ * Hand-tracked sources report a gamepad with no axes, which would read as NaN.
+ */
+const readScrollAxis = inputSource => {
+  const axes = inputSource.gamepad?.axes;
+  if (inputSource.handedness !== 'right' || !axes || axes.length < 4) {
+    return 0;
+  }
+  return axes[3];
+};
+
+/**
+ * Advances the scroll position for one frame of stick deflection, ramping from a standstill at
+ * the deadzone edge. A forward push reports negative Y and moves further into the text.
+ */
+const nextScrollY = (scrollY, axisY, dt, maxScroll) => {
+  const magnitude = Math.abs(axisY);
+  if (magnitude <= SCROLL_DEADZONE) {
+    return Math.min(Math.max(scrollY, 0), maxScroll);
+  }
+  const ramped = (magnitude - SCROLL_DEADZONE) / (1 - SCROLL_DEADZONE);
+  const delta = -Math.sign(axisY) * ramped * SCROLL_SPEED * dt;
+  return Math.min(Math.max(scrollY + delta, 0), maxScroll);
+};
+
+export { SCROLL_DEADZONE, SCROLL_SPEED, nextScrollY, readScrollAxis };

package/components/VirtualWalkthrough/xr-annotation-candidate-buffer.d.ts

@@ -0,0 +1,32 @@
+import { Vec3 } from 'playcanvas';
+/** Local half-extent of the unit-plane hotspot quad. */
+export declare const HOTSPOT_HALF_EXTENT = 0.5;
+export interface AnnotationCandidate {
+    entity: any;
+    script: any;
+    position: Vec3;
+    radius: number;
+}
+/** Pulls the stock annotation script off a hotspot entity, or undefined if it carries none. */
+export type AnnotationScriptLookup = (entity: any) => any;
+/**
+ * Collects world-space hit candidates for the openable annotation hotspots into a buffer it owns and
+ * reuses, so a caller running every frame allocates nothing. The returned array and the candidate
+ * objects inside it are overwritten by the next `collect`, which is why each caller holds its own
+ * buffer rather than sharing one.
+ *
+ * Positions and radii are re-read on every call, so hotspots that move or resize stay targetable.
+ * That read is cheap; it is the allocation around it that a per-frame caller cannot afford.
+ */
+export declare class AnnotationCandidateBuffer {
+    private readonly _getScript;
+    private readonly _candidates;
+    private _root;
+    constructor(_getScript: AnnotationScriptLookup);
+    /**
+     * Hit candidates for every openable hotspot except `excludeName`, with hit spheres derived from
+     * each hotspot's rendered world size and padded by `radiusPad` for easier aiming.
+     */
+    collect(app: any, radiusPad: number, excludeName?: string): AnnotationCandidate[];
+}
+//# sourceMappingURL=xr-annotation-candidate-buffer.d.ts.map

package/components/VirtualWalkthrough/xr-annotation-candidate-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-annotation-candidate-buffer.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-annotation-candidate-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+FAA+F;AAC/F,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;AAmB1D;;;;;;;;GAQG;AACH,qBAAa,yBAAyB;IAIxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAHvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,KAAK,CAAa;gBAEG,UAAU,EAAE,sBAAsB;IAE/D;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,mBAAmB,EAAE;CA6ClF"}