@terraware/web-components 4.2.22-rc.0 → 4.2.22

package/components/VirtualWalkthrough/boundary-wall.test.js

@@ -0,0 +1,203 @@
+import { Vec3 } from 'playcanvas';
+import { boundaryWallMesh } from './boundary-wall';
+const FLAT = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(0, 0, 1)];
+const BASE = {
+  center: new Vec3(0, 0, 0),
+  radius: 5,
+  groundPlane: FLAT,
+  baseY: 0,
+  topY: 2.5,
+  gridSpacing: 0.5
+};
+const toVertices = positions => {
+  const out = [];
+  for (let i = 0; i < positions.length; i += 3) {
+    out.push([positions[i], positions[i + 1], positions[i + 2]]);
+  }
+  return out;
+};
+describe('boundaryWallMesh', () => {
+  it('produces four vertices, four UVs and six indices per segment', () => {
+    const geom = boundaryWallMesh({
+      ...BASE,
+      segments: 16
+    });
+    expect(geom.positions).toHaveLength(16 * 4 * 3);
+    expect(geom.uvs).toHaveLength(16 * 4 * 2);
+    expect(geom.indices).toHaveLength(16 * 6);
+  });
+  it('places every vertex at the boundary radius in XZ', () => {
+    const center = new Vec3(2, 0, -3);
+    const geom = boundaryWallMesh({
+      ...BASE,
+      center,
+      radius: 4,
+      segments: 32
+    });
+    for (const [x,, z] of toVertices(geom.positions)) {
+      expect(Math.sqrt((x - center.x) ** 2 + (z - center.z) ** 2)).toBeCloseTo(4);
+    }
+  });
+  it('puts the top ring flat at topY for every column, even over tilted ground', () => {
+    // y = z, so the bottom sweeps -3..3 while the top has to stay pinned at 4.
+    const tilted = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(0, 1, 1)];
+    const geom = boundaryWallMesh({
+      ...BASE,
+      groundPlane: tilted,
+      radius: 3,
+      topY: 4,
+      segments: 8
+    });
+    const verts = toVertices(geom.positions);
+    // Per segment the order is: bottom@a0, top@a0, bottom@a1, top@a1.
+    for (let i = 0; i < verts.length; i += 4) {
+      expect(verts[i + 1][1]).toBeCloseTo(4);
+      expect(verts[i + 3][1]).toBeCloseTo(4);
+    }
+  });
+  it('sits the base on a tilted ground plane (y = z)', () => {
+    const tilted = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(0, 1, 1)];
+    const geom = boundaryWallMesh({
+      ...BASE,
+      groundPlane: tilted,
+      radius: 3,
+      topY: 4,
+      segments: 8
+    });
+    const verts = toVertices(geom.positions);
+    for (let i = 0; i < verts.length; i += 4) {
+      expect(verts[i][1]).toBeCloseTo(verts[i][2]);
+      expect(verts[i + 2][1]).toBeCloseTo(verts[i + 2][2]);
+    }
+  });
+  it('falls back to a flat base at baseY when no ground plane is supplied', () => {
+    const geom = boundaryWallMesh({
+      ...BASE,
+      groundPlane: [],
+      baseY: 1.5,
+      topY: 3.5,
+      segments: 8
+    });
+    const verts = toVertices(geom.positions);
+    expect(verts).not.toHaveLength(0);
+    for (let i = 0; i < verts.length; i += 4) {
+      expect(verts[i][1]).toBeCloseTo(1.5);
+      expect(verts[i + 1][1]).toBeCloseTo(3.5);
+    }
+  });
+  it('falls back to a flat base for a degenerate ground plane', () => {
+    const collinear = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(2, 0, 0)];
+    const geom = boundaryWallMesh({
+      ...BASE,
+      groundPlane: collinear,
+      baseY: -2,
+      segments: 8
+    });
+    const verts = toVertices(geom.positions);
+    expect(verts).not.toHaveLength(0);
+    expect(verts[0][1]).toBeCloseTo(-2);
+    expect(verts[1][1]).toBeCloseTo(2.5);
+  });
+  it('reports whole-number grid cell counts derived from gridSpacing', () => {
+    // Circumference 2*pi*5 = 31.4159; at 0.5 m spacing that rounds to 63 columns.
+    // The ground is flat at y = 0, so rows = round((2.5 - 0) / 0.5) = 5.
+    const geom = boundaryWallMesh({
+      ...BASE,
+      radius: 5,
+      topY: 2.5,
+      gridSpacing: 0.5,
+      segments: 8
+    });
+    expect(geom.columns).toBe(63);
+    expect(geom.rows).toBe(5);
+  });
+  it('derives rows from the average bottom, not from any single column', () => {
+    // Plane y = x - 1, sampled on a radius-3 circle at 6 columns (0, 60, 120, 180, 240, 300 deg):
+    // bottoms are 2, 0.5, -2.5, -4, -2.5, 0.5 -> average -1, which no column matches.
+    // rows = round((2.5 - -1) / 0.5) = round(7) = 7.
+    const tilted = [new Vec3(1, 0, 0), new Vec3(2, 1, 0), new Vec3(1, 0, 1)];
+    const geom = boundaryWallMesh({
+      ...BASE,
+      groundPlane: tilted,
+      radius: 3,
+      topY: 2.5,
+      segments: 6
+    });
+    const bottoms = toVertices(geom.positions).filter((_, index) => index % 2 === 0).map(([, y]) => y);
+    expect(bottoms).toHaveLength(12);
+    for (const y of bottoms) {
+      expect(Math.abs(y + 1)).toBeGreaterThan(1);
+    }
+    expect(geom.rows).toBe(7);
+  });
+  it('emits u in cell units that wrap exactly at `columns`', () => {
+    const geom = boundaryWallMesh({
+      ...BASE,
+      segments: 8
+    });
+    const us = [];
+    for (let i = 0; i < geom.uvs.length; i += 2) {
+      us.push(geom.uvs[i]);
+    }
+    expect(us[0]).toBeCloseTo(0);
+    // Last vertex of the last segment closes the loop at exactly `columns`.
+    expect(us[us.length - 1]).toBeCloseTo(geom.columns);
+  });
+  it('emits v as 0 at the base and `rows` at the top', () => {
+    const geom = boundaryWallMesh({
+      ...BASE,
+      segments: 8
+    });
+    for (let i = 0; i < geom.uvs.length; i += 8) {
+      expect(geom.uvs[i + 1]).toBeCloseTo(0);
+      expect(geom.uvs[i + 3]).toBeCloseTo(geom.rows);
+    }
+  });
+  it('references only in-range vertices from the index buffer', () => {
+    const geom = boundaryWallMesh({
+      ...BASE,
+      segments: 8
+    });
+    const vertexCount = geom.positions.length / 3;
+    for (const idx of geom.indices) {
+      expect(idx).toBeGreaterThanOrEqual(0);
+      expect(idx).toBeLessThan(vertexCount);
+    }
+  });
+  it('returns empty geometry for a non-positive radius', () => {
+    const geom = boundaryWallMesh({
+      ...BASE,
+      radius: 0
+    });
+    expect(geom.positions).toHaveLength(0);
+    expect(geom.indices).toHaveLength(0);
+  });
+  it('returns empty geometry for a non-positive segment count', () => {
+    expect(boundaryWallMesh({
+      ...BASE,
+      segments: 0
+    }).positions).toHaveLength(0);
+  });
+  it('returns empty geometry for a non-positive grid spacing', () => {
+    expect(boundaryWallMesh({
+      ...BASE,
+      gridSpacing: 0
+    }).positions).toHaveLength(0);
+  });
+  it('returns empty geometry when topY is level with the base', () => {
+    expect(boundaryWallMesh({
+      ...BASE,
+      topY: 0
+    }).positions).toHaveLength(0);
+  });
+  it('returns empty geometry when topY clears only part of a tilted base', () => {
+    // y = z on a radius-3 circle reaches 3, so a top at 2 is below the far half of the wall.
+    const tilted = [new Vec3(0, 0, 0), new Vec3(1, 0, 0), new Vec3(0, 1, 1)];
+    expect(boundaryWallMesh({
+      ...BASE,
+      groundPlane: tilted,
+      radius: 3,
+      topY: 2
+    }).positions).toHaveLength(0);
+  });
+});

package/components/VirtualWalkthrough/vr-annotation-panel-layout.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Greedily wraps `text` into lines no wider than `maxWidth`, using `measure` to size
+ * each candidate line. A single word wider than `maxWidth` still gets its own line.
+ */
+export declare const wrapText: (text: string, maxWidth: number, measure: (segment: string) => number) => string[];
+//# sourceMappingURL=vr-annotation-panel-layout.d.ts.map

package/components/VirtualWalkthrough/vr-annotation-panel-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vr-annotation-panel-layout.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/vr-annotation-panel-layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,UAAU,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,KAAG,MAAM,EAoBrG,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * Greedily wraps `text` into lines no wider than `maxWidth`, using `measure` to size
+ * each candidate line. A single word wider than `maxWidth` still gets its own line.
+ */
+export const wrapText = (text, maxWidth, measure) => {
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = '';
+  words.forEach(word => {
+    const candidate = current ? `${current} ${word}` : word;
+    if (!current || measure(candidate) <= maxWidth) {
+      current = candidate;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  });
+  if (current) {
+    lines.push(current);
+  }
+  return lines;
+};

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

@@ -0,0 +1,26 @@
+import { wrapText } from './vr-annotation-panel-layout';
+
+// Each character is 1 unit wide; a space counts as a character within a line.
+const measure = s => s.length;
+describe('wrapText', () => {
+  it('returns an empty array for empty or whitespace-only input', () => {
+    expect(wrapText('', 10, measure)).toEqual([]);
+    expect(wrapText('   ', 10, measure)).toEqual([]);
+  });
+  it('keeps text on one line when it fits', () => {
+    expect(wrapText('hello world', 11, measure)).toEqual(['hello world']);
+  });
+  it('wraps to a new line when the next word would exceed the width', () => {
+    // 'hello world' is 11 wide; width 10 forces a break before 'world'.
+    expect(wrapText('hello world', 10, measure)).toEqual(['hello', 'world']);
+  });
+  it('packs as many words as fit per line greedily', () => {
+    expect(wrapText('a bb cc d', 5, measure)).toEqual(['a bb', 'cc d']);
+  });
+  it('puts an over-long word on its own line rather than dropping it', () => {
+    expect(wrapText('tiny enormouslylongword end', 8, measure)).toEqual(['tiny', 'enormouslylongword', 'end']);
+  });
+  it('collapses runs of whitespace', () => {
+    expect(wrapText('a    b', 10, measure)).toEqual(['a b']);
+  });
+});

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

@@ -0,0 +1,40 @@
+import { Script, Vec3 } from 'playcanvas';
+export declare class VrAnnotationPanel extends Script {
+    static scriptName: string;
+    title: string;
+    label?: string;
+    bodyText?: string;
+    imageUrls?: string[];
+    annotationIndex: number;
+    scaleFactor: number;
+    private _material?;
+    private _texture?;
+    private _mesh?;
+    private _canvas?;
+    private _drawnSignature;
+    private _currentImage;
+    private _loadToken;
+    private _headRotation;
+    private _anchor;
+    private _scratchDir;
+    private _yawQuat;
+    private _axisRight;
+    private _axisUp;
+    private _scratchScale;
+    private _onSelect;
+    initialize(): void;
+    private _createMesh;
+    private _roundRect;
+    private _drawArrow;
+    private _drawDots;
+    private _drawContent;
+    private _setImage;
+    private _loadCurrentImage;
+    private _rayQuadHit;
+    /** True when the ray points at the panel quad (used to suppress the empty-select dismiss). */
+    rayHitsPanel(origin: Vec3, direction: Vec3): boolean;
+    update(): void;
+    private _trackHead;
+    private _teardown;
+}
+//# sourceMappingURL=vr-annotation-panel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vr-annotation-panel.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/vr-annotation-panel.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,MAAM,EAGN,IAAI,EAEL,MAAM,YAAY,CAAC;AAiCpB,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,MAAM,CAAC,UAAU,SAAuB;IAGxC,KAAK,SAAM;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,SAAM;IACrB,WAAW,SAAK;IAEhB,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAC,CAAoB;IACpC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,aAAa,CAAc;IAEnC,OAAO,CAAC,SAAS,CAsBf;IAEF,UAAU;IAwCV,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;IAkBlB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,YAAY;IAqFpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,WAAW;IAmBnB,8FAA8F;IAC9F,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO;IAIpD,MAAM;IAsCN,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAYlB"}

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

@@ -0,0 +1,312 @@
+import { ADDRESS_CLAMP_TO_EDGE, BLEND_NORMAL, CULLFACE_NONE, Color, FILTER_LINEAR, LAYERID_IMMEDIATE, Mesh, MeshInstance, Quat, Script, StandardMaterial, Texture, Vec3 } from 'playcanvas';
+import { wrapText } from './vr-annotation-panel-layout';
+import { rayQuadHit } from './xr-ray-quad';
+const CANVAS_WIDTH = 1024;
+const CANVAS_HEIGHT = 768;
+
+/** Panel width in world meters; height derived from the canvas aspect ratio. */
+const PANEL_WIDTH = 0.5;
+const PANEL_HEIGHT = PANEL_WIDTH * CANVAS_HEIGHT / 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 + 0.05, 0);
+const PAD_X = 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);
+/** Quad in-plane axes in local space, transformed to world for ray hit-testing. */
+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;
+export class VrAnnotationPanel extends Script {
+  static scriptName = 'vrAnnotationPanel';
+
+  // Props assigned by the React wrapper.
+  title = '';
+  annotationIndex = -1;
+  scaleFactor = 1;
+  _drawnSignature = null;
+  _currentImage = 0;
+  _loadToken = 0;
+  _headRotation = new Quat();
+  _anchor = new Vec3();
+  _scratchDir = new Vec3();
+  _yawQuat = new Quat();
+  _axisRight = new Vec3();
+  _axisUp = new Vec3();
+  _scratchScale = new Vec3();
+  _onSelect = inputSource => {
+    if (this.app.xr?.active !== true) {
+      return;
+    }
+    const images = this.imageUrls ?? [];
+    if (images.length <= 1) {
+      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) {
+      return;
+    }
+    if (cx <= ARROW_ZONE_W) {
+      this._setImage((this._currentImage - 1 + images.length) % images.length);
+    } else if (cx >= 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,
+      addressU: ADDRESS_CLAMP_TO_EDGE,
+      addressV: ADDRESS_CLAMP_TO_EDGE,
+      minFilter: FILTER_LINEAR,
+      magFilter: FILTER_LINEAR,
+      mipmaps: true
+    });
+    this._texture.setSource(this._canvas);
+    const material = new StandardMaterial();
+    material.useLighting = false;
+    material.emissive = new Color(1, 1, 1);
+    material.emissiveMap = this._texture;
+    material.opacityMap = this._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());
+  }
+  _createMesh() {
+    const hw = PANEL_WIDTH / 2;
+    const hh = PANEL_HEIGHT / 2;
+    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();
+    return mesh;
+  }
+  _roundRect(ctx, x, y, w, h, r) {
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.arcTo(x + w, y, x + w, y + h, r);
+    ctx.arcTo(x + w, y + h, x, y + h, r);
+    ctx.arcTo(x, y + h, x, y, r);
+    ctx.arcTo(x, y, x + w, y, r);
+    ctx.closePath();
+  }
+  _drawArrow(ctx, cx, cy, pointsLeft) {
+    ctx.beginPath();
+    ctx.arc(cx, cy, 40, 0, Math.PI * 2);
+    ctx.fillStyle = 'rgba(0, 0, 0, 0.45)';
+    ctx.fill();
+    const s = 16;
+    const tip = pointsLeft ? cx - s * 0.6 : cx + s * 0.6;
+    const base = pointsLeft ? cx + s * 0.6 : cx - s * 0.6;
+    ctx.beginPath();
+    ctx.moveTo(base, cy - s);
+    ctx.lineTo(tip, cy);
+    ctx.lineTo(base, cy + s);
+    ctx.closePath();
+    ctx.fillStyle = '#ffffff';
+    ctx.fill();
+  }
+  _drawDots(ctx, count, dotY) {
+    const gap = 26;
+    const startX = 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);
+      ctx.fillStyle = i === this._currentImage ? 'rgba(0, 0, 0, 0.85)' : 'rgba(0, 0, 0, 0.25)';
+      ctx.fill();
+    }
+  }
+  _drawContent(image) {
+    const ctx = this._canvas?.getContext('2d');
+    if (!ctx) {
+      return;
+    }
+    ctx.clearRect(0, 0, CANVAS_WIDTH, CANVAS_HEIGHT);
+    ctx.fillStyle = 'rgba(255, 255, 255, 0.96)';
+    this._roundRect(ctx, 0, 0, CANVAS_WIDTH, CANVAS_HEIGHT, 32);
+    ctx.fill();
+    let y = IMAGE_Y;
+    const contentWidth = CANVAS_WIDTH - PAD_X * 2;
+    const images = this.imageUrls ?? [];
+    if (images.length > 0) {
+      ctx.save();
+      this._roundRect(ctx, PAD_X, IMAGE_Y, contentWidth, IMAGE_H, 16);
+      ctx.clip();
+      if (image) {
+        const scale = Math.max(contentWidth / image.width, IMAGE_H / 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);
+      } else {
+        ctx.fillStyle = 'rgba(0, 0, 0, 0.06)';
+        ctx.fillRect(PAD_X, IMAGE_Y, contentWidth, IMAGE_H);
+      }
+      ctx.restore();
+      y = IMAGE_Y + IMAGE_H + 16;
+      if (images.length > 1) {
+        const bandCenterY = IMAGE_Y + IMAGE_H / 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;
+      }
+      y += 16;
+    }
+    if (this.label) {
+      ctx.font = '600 28px sans-serif';
+      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);
+      ctx.fill();
+      ctx.fillStyle = '#ffffff';
+      ctx.fillText(this.label, PAD_X + 16, y + chipH / 2);
+      y += chipH + 24;
+    }
+    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;
+    }
+    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._texture?.upload();
+  }
+  _setImage(index) {
+    this._currentImage = index;
+    this._drawContent();
+    this._loadCurrentImage();
+  }
+  _loadCurrentImage() {
+    const url = this.imageUrls?.[this._currentImage];
+    if (!url) {
+      return;
+    }
+    const token = ++this._loadToken;
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.onload = () => {
+      // Ignore a stale load that a newer navigation has superseded.
+      if (token === this._loadToken) {
+        this._drawContent(img);
+      }
+    };
+    // onerror (e.g. a host without CORS headers): keep the placeholder + text already drawn.
+    img.src = url;
+  }
+  _rayQuadHit(origin, direction) {
+    const rotation = this.entity.getRotation();
+    rotation.transformVector(RIGHT_AXIS, this._axisRight);
+    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;
+    return rayQuadHit(origin, direction, this.entity.getPosition(), this._axisRight, this._axisUp, halfWidth, halfHeight);
+  }
+
+  /** True when the ray points at the panel quad (used to suppress the empty-select dismiss). */
+  rayHitsPanel(origin, direction) {
+    return this._rayQuadHit(origin, direction) !== null;
+  }
+  update() {
+    if (this.app.xr?.active !== true) {
+      return;
+    }
+    const signature = `${this.title}|${this.label ?? ''}|${this.bodyText ?? ''}|${(this.imageUrls ?? []).join(',')}`;
+    if (signature !== this._drawnSignature) {
+      this._drawnSignature = signature;
+      this._currentImage = 0;
+      this._drawContent();
+      this._loadCurrentImage();
+    }
+    this._trackHead();
+    const anchor = this.app.root.findByName(`annotation-${this.annotationIndex}`);
+    if (!anchor) {
+      return;
+    }
+    this._anchor.copy(anchor.getPosition());
+    // Panel size and its offset from the hotspot scale with the scene so the panel keeps its
+    // proportions relative to the (content-root-scaled) annotations across scenes.
+    this.entity.setLocalScale(this.scaleFactor, this.scaleFactor, this.scaleFactor);
+    this.entity.setPosition(this._anchor.x + PANEL_OFFSET.x * this.scaleFactor, this._anchor.y + PANEL_OFFSET.y * this.scaleFactor, this._anchor.z + PANEL_OFFSET.z * this.scaleFactor);
+
+    // 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
+    // heading, so it matches the level head-rotation orientation but with pitch/roll removed.
+    this._headRotation.transformVector(FORWARD_Z, this._scratchDir);
+    const yaw = Math.atan2(this._scratchDir.x, this._scratchDir.z) * RAD_TO_DEG;
+    this._yawQuat.setFromEulerAngles(0, yaw, 0);
+    this.entity.setRotation(this._yawQuat);
+  }
+  _trackHead() {
+    const views = this.app.xr?.views?.list;
+    if (!views || views.length === 0) {
+      return;
+    }
+    this._headRotation.setFromMat4(views[0].viewInvOffMat);
+  }
+  _teardown() {
+    this.app.xr?.input?.off('select', this._onSelect);
+    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;
+  }
+}

package/components/VirtualWalkthrough/xr-annotation-candidates.d.ts

@@ -0,0 +1,18 @@
+import { Vec3 } from 'playcanvas';
+/** Local half-extent of the unit-plane hotspot quad. */
+export declare const HOTSPOT_HALF_EXTENT = 0.5;
+/** Multiplier on the hotspot's world radius to make controller targeting forgiving. */
+export declare const HIT_RADIUS_PAD = 2.5;
+export interface AnnotationCandidate {
+    entity: any;
+    script: any;
+    position: Vec3;
+    radius: number;
+}
+/**
+ * World-space hit candidates for every openable annotation hotspot: its entity, its stock
+ * annotation script (which carries `onVrOpenCallback`), its world position, and a hit-sphere
+ * radius derived from the hotspot's rendered world size, padded by `radiusPad` for easier aiming.
+ */
+export declare const collectAnnotationHitCandidates: (app: any, radiusPad: number) => AnnotationCandidate[];
+//# sourceMappingURL=xr-annotation-candidates.d.ts.map

package/components/VirtualWalkthrough/xr-annotation-candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-annotation-candidates.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/xr-annotation-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGlC,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,uFAAuF;AACvF,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,GAAG,CAAC;IACZ,MAAM,EAAE,GAAG,CAAC;IACZ,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,GAAI,KAAK,GAAG,EAAE,WAAW,MAAM,KAAG,mBAAmB,EAmB/F,CAAC"}

package/components/VirtualWalkthrough/xr-annotation-candidates.js

@@ -0,0 +1,38 @@
+import { Vec3 } from 'playcanvas';
+import { Annotation as PcAnnotation } from 'playcanvas/scripts/esm/annotations.mjs';
+
+/** Local half-extent of the unit-plane hotspot quad. */
+export const HOTSPOT_HALF_EXTENT = 0.5;
+
+/** Multiplier on the hotspot's world radius to make controller targeting forgiving. */
+export const HIT_RADIUS_PAD = 2.5;
+const scratchScale = new Vec3();
+
+/**
+ * World-space hit candidates for every openable annotation hotspot: its entity, its stock
+ * annotation script (which carries `onVrOpenCallback`), its world position, and a hit-sphere
+ * radius derived from the hotspot's rendered world size, padded by `radiusPad` for easier aiming.
+ */
+export const collectAnnotationHitCandidates = (app, radiusPad) => {
+  const root = app.root.findByName('annotations-root');
+  if (!root) {
+    return [];
+  }
+  return root.children.map(entity => ({
+    entity,
+    script: entity.script?.get(PcAnnotation.scriptName)
+  })).filter(({
+    script
+  }) => script && script.enabled !== false && typeof script.onVrOpenCallback === 'function').map(({
+    entity,
+    script
+  }) => {
+    entity.getWorldTransform().getScale(scratchScale);
+    return {
+      entity,
+      script,
+      position: entity.getPosition(),
+      radius: HOTSPOT_HALF_EXTENT * scratchScale.x * radiusPad
+    };
+  });
+};