@terraware/web-components 4.2.21 → 4.2.22

package/components/VirtualWalkthrough/boundary-wall.d.ts

@@ -0,0 +1,86 @@
+import { Color, Script, Vec3 } from 'playcanvas';
+export type BoundaryWallGeometryParams = {
+    center: Vec3;
+    radius: number;
+    /** Three world-space points defining the ground the wall stands on. Empty or degenerate falls back to baseY. */
+    groundPlane: Vec3[];
+    /** Flat base height used when no usable ground plane is supplied. */
+    baseY: number;
+    /** Absolute world Y of the wall's top edge, giving a flat top ring however the ground below tilts. */
+    topY: number;
+    /** Target grid cell size in world units. Rounded so cells divide the circumference and height evenly. */
+    gridSpacing: number;
+    segments?: number;
+};
+/**
+ * Flat-array geometry ready for `Mesh.setPositions` / `Mesh.setUvs` / `Mesh.setIndices`, plus the
+ * grid cell counts the shader needs to know how far the UVs run.
+ */
+export type BoundaryWallGeometry = {
+    positions: number[];
+    uvs: number[];
+    indices: number[];
+    columns: number;
+    rows: number;
+};
+/**
+ * Triangle geometry for an upright cylinder standing on the boundary circle. Each segment is a quad
+ * (two triangles) spanning from the ground up to `topY`; the base is sampled on the ground plane so
+ * the wall meets the dashed BoundaryRing exactly, while the top is a flat ring at `topY` — the user
+ * stands on the rig floor, not on the splat's ground plane, so the top is positioned relative to the
+ * former and only the base follows the latter.
+ *
+ * UVs are emitted in **grid cell units** rather than metres — u runs 0..columns around the
+ * circumference and v runs 0..rows up the wall — so the shader can draw a line at every whole number
+ * and have the seam at u = columns line up perfectly with u = 0.
+ */
+export declare const boundaryWallMesh: ({ center, radius, groundPlane, baseY, topY, gridSpacing, segments, }: BoundaryWallGeometryParams) => BoundaryWallGeometry;
+/**
+ * Draws a Quest-guardian-style boundary wall: an upright cylinder on the bounds circle whose grid
+ * fades in and shifts toward a warning colour as the head approaches, and goes to full intensity
+ * while XR navigation is actively holding the user back.
+ *
+ * center / radius / groundPlane / baseY are set imperatively by the BoundaryWall component (see
+ * BoundaryWall.tsx for why they are not reactive Script props), which calls `rebuild()` afterwards.
+ * All of them are world-space: this entity is deliberately mounted outside `content-root`, which
+ * carries the scene's scaleFactor.
+ */
+export declare class BoundaryWallScript extends Script {
+    static scriptName: string;
+    center: Vec3;
+    radius: number;
+    groundPlane: Vec3[];
+    /** Flat bottom height used when no usable ground plane is supplied. */
+    baseY: number;
+    /**
+     * Absolute world Y of the wall's top edge. The default puts it 2.5 m above a rig floor at y = 0,
+     * which is where the user actually stands - the splat's ground plane can be well below that.
+     */
+    topY: number;
+    segments: number;
+    gridSpacing: number;
+    /** Grid line thickness in world metres. */
+    lineWidth: number;
+    /** Head distance, in world metres, at which the wall starts to appear. */
+    fadeDistance: number;
+    /** Multiplier applied to fadeDistance while movement is being clamped. */
+    blockedFadeScale: number;
+    calmColor: Color;
+    warnColor: Color;
+    private _material?;
+    private _mesh?;
+    private _camera;
+    private _navigation;
+    private _headParam;
+    initialize(): void;
+    /**
+     * The camera and the navigation script both live on entities this one does not own. They are
+     * resolved lazily rather than once, because script initialize order across sibling entities is not
+     * guaranteed and this entity mounts when an XR session starts.
+     */
+    private _resolveDependencies;
+    rebuild(): void;
+    update(): void;
+    private _clearMesh;
+}
+//# sourceMappingURL=boundary-wall.d.ts.map

package/components/VirtualWalkthrough/boundary-wall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-wall.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/boundary-wall.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,EAOL,MAAM,EAEN,IAAI,EACL,MAAM,YAAY,CAAC;AAKpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,gHAAgH;IAChH,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,sEAQ9B,0BAA0B,KAAG,oBAqD/B,CAAC;AA2EF;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;IAC5C,MAAM,CAAC,UAAU,SAAkB;IAEnC,MAAM,OAAc;IACpB,MAAM,SAAK;IACX,WAAW,EAAE,IAAI,EAAE,CAAM;IACzB,uEAAuE;IACvE,KAAK,SAAK;IACV;;;OAGG;IACH,IAAI,SAAO;IACX,QAAQ,SAAM;IACd,WAAW,SAAO;IAClB,2CAA2C;IAC3C,SAAS,SAAS;IAClB,0EAA0E;IAC1E,YAAY,SAAO;IACnB,0EAA0E;IAC1E,gBAAgB,SAAO;IACvB,SAAS,QAA2B;IACpC,SAAS,QAA2B;IAEpC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,KAAK,CAAC,CAAO;IACrB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,UAAU,CAAuB;IAEzC,UAAU;IAwBV;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAW5B,OAAO;IA6CP,MAAM;IAgCN,OAAO,CAAC,UAAU;CASnB"}

package/components/VirtualWalkthrough/boundary-wall.js

@@ -0,0 +1,331 @@
+import { BLEND_NORMAL, CULLFACE_NONE, Color, LAYERID_IMMEDIATE, Mesh, MeshInstance, SEMANTIC_POSITION, SEMANTIC_TEXCOORD0, Script, ShaderMaterial, Vec3 } from 'playcanvas';
+import { computeGroundPlane, yOnPlane } from './groundPlane';
+import { distanceToCircleEdge } from './xr-scene-bounds';
+
+/**
+ * Flat-array geometry ready for `Mesh.setPositions` / `Mesh.setUvs` / `Mesh.setIndices`, plus the
+ * grid cell counts the shader needs to know how far the UVs run.
+ */
+
+/**
+ * Triangle geometry for an upright cylinder standing on the boundary circle. Each segment is a quad
+ * (two triangles) spanning from the ground up to `topY`; the base is sampled on the ground plane so
+ * the wall meets the dashed BoundaryRing exactly, while the top is a flat ring at `topY` — the user
+ * stands on the rig floor, not on the splat's ground plane, so the top is positioned relative to the
+ * former and only the base follows the latter.
+ *
+ * UVs are emitted in **grid cell units** rather than metres — u runs 0..columns around the
+ * circumference and v runs 0..rows up the wall — so the shader can draw a line at every whole number
+ * and have the seam at u = columns line up perfectly with u = 0.
+ */
+export const boundaryWallMesh = ({
+  center,
+  radius,
+  groundPlane,
+  baseY,
+  topY,
+  gridSpacing,
+  segments = 96
+}) => {
+  if (radius <= 0 || segments <= 0 || gridSpacing <= 0) {
+    return {
+      positions: [],
+      uvs: [],
+      indices: [],
+      columns: 0,
+      rows: 0
+    };
+  }
+  const plane = computeGroundPlane(groundPlane);
+  const step = Math.PI * 2 / segments;
+
+  // First pass: the bottom of every column, which the row count and the extent guard both need
+  // before any vertex can be emitted.
+  const bottoms = Array.from({
+    length: segments
+  }, (_, index) => {
+    const angle = index * step;
+    const x = center.x + radius * Math.cos(angle);
+    const z = center.z + radius * Math.sin(angle);
+    return {
+      x,
+      z,
+      y: plane ? yOnPlane(x, z, plane.normal, plane.point, baseY) : baseY
+    };
+  });
+  if (bottoms.some(bottom => bottom.y >= topY)) {
+    return {
+      positions: [],
+      uvs: [],
+      indices: [],
+      columns: 0,
+      rows: 0
+    };
+  }
+
+  // Every column has its own world height once the ground tilts, but v still runs 0..rows uniformly
+  // for all of them, so a single row count has to stand for the whole wall. Deriving it from the
+  // average bottom is exact for a flat ground plane (the common case) and keeps the cells square on
+  // average when the plane is tilted.
+  const averageBottomY = bottoms.reduce((total, bottom) => total + bottom.y, 0) / bottoms.length;
+  const columns = Math.max(1, Math.round(Math.PI * 2 * radius / gridSpacing));
+  const rows = Math.max(1, Math.round((topY - averageBottomY) / gridSpacing));
+  const positions = [];
+  const uvs = [];
+  const indices = [];
+  const pushColumn = index => {
+    // The closing column (index === segments) reuses column 0's position so the loop shuts exactly,
+    // while u keeps counting up to `columns` to place the seam.
+    const {
+      x,
+      z,
+      y
+    } = bottoms[index % segments];
+    const u = index / segments * columns;
+    positions.push(x, y, z, x, topY, z);
+    uvs.push(u, 0, u, rows);
+  };
+  for (let i = 0; i < segments; i++) {
+    const base = i * 4;
+    // Per segment: v0 bottom@a0, v1 top@a0, v2 bottom@a1, v3 top@a1.
+    pushColumn(i);
+    pushColumn(i + 1);
+    indices.push(base, base + 1, base + 3, base, base + 3, base + 2);
+  }
+  return {
+    positions,
+    uvs,
+    indices,
+    columns,
+    rows
+  };
+};
+
+// GLSL only: @playcanvas/react's Application defaults to deviceTypes [DEVICETYPE_WEBGL2], so the
+// WGSL variants the engine's own shaders carry would never be compiled here.
+const wallVertexGLSL = /* glsl */`
+    attribute vec3 vertex_position;
+    attribute vec2 aUv0;
+
+    uniform mat4 matrix_model;
+    uniform mat4 matrix_viewProjection;
+
+    varying vec2 uv0;
+    varying vec3 vWorld;
+
+    void main(void) {
+        vec4 world = matrix_model * vec4(vertex_position, 1.0);
+        vWorld = world.xyz;
+        uv0 = aUv0;
+        gl_Position = matrix_viewProjection * world;
+    }
+`;
+const wallFragmentGLSL = /* glsl */`
+    uniform vec3 uHeadPos;
+    uniform float uFadeDistance;
+    uniform float uBlockedFadeScale;
+    uniform float uBlocked;
+    uniform float uRows;
+    uniform vec3 uCalmColor;
+    uniform vec3 uWarnColor;
+    uniform float uLineHalfWidth;
+
+    varying vec2 uv0;
+    varying vec3 vWorld;
+
+    // Antialiased line mask: 1 at whole-number coordinates, 0 between them.
+    //
+    // The line has a solid core uLineHalfWidth cells wide either side of the coordinate, so its
+    // thickness is fixed in world space and holds up close to the wall. The smoothstep then feathers
+    // it over exactly one pixel (fwidth), which both antialiases the edge and keeps distant lines
+    // from aliasing into moire: once a cell shrinks below a pixel the feather swallows the core and
+    // the grid fades out instead of shimmering.
+    float gridLine(float coord) {
+        float w = fwidth(coord);
+        float d = abs(fract(coord + 0.5) - 0.5);
+        return 1.0 - smoothstep(uLineHalfWidth, uLineHalfWidth + w, d);
+    }
+
+    void main(void) {
+        // gridLine takes derivatives, which are undefined in non-uniform control flow, so it has to
+        // run before any discard.
+        float grid = max(gridLine(uv0.x), gridLine(uv0.y));
+
+        // Distance from this fragment to the head, so only the arc of wall near the user lights up.
+        float fade = uFadeDistance * mix(1.0, uBlockedFadeScale, uBlocked);
+        float proximity = 1.0 - clamp(distance(vWorld.xz, uHeadPos.xz) / fade, 0.0, 1.0);
+        if (proximity <= 0.0) discard;
+
+        // Soften the open top edge so the wall does not end in a hard rim.
+        float topFade = 1.0 - smoothstep(0.6, 1.0, uv0.y / uRows);
+
+        float alpha = proximity * topFade * grid;
+        if (alpha <= 0.0) discard;
+
+        gl_FragColor = vec4(mix(uCalmColor, uWarnColor, max(proximity, uBlocked)), alpha);
+    }
+`;
+
+/**
+ * Structural shape of TfXrNavigation this script depends on, kept local so it does not have to
+ * import the navigation script. `enabled` is optional because a disabled script (e.g. while edit
+ * mode is on) stops receiving postUpdate and would otherwise latch a stale clampDistance.
+ */
+
+/**
+ * Draws a Quest-guardian-style boundary wall: an upright cylinder on the bounds circle whose grid
+ * fades in and shifts toward a warning colour as the head approaches, and goes to full intensity
+ * while XR navigation is actively holding the user back.
+ *
+ * center / radius / groundPlane / baseY are set imperatively by the BoundaryWall component (see
+ * BoundaryWall.tsx for why they are not reactive Script props), which calls `rebuild()` afterwards.
+ * All of them are world-space: this entity is deliberately mounted outside `content-root`, which
+ * carries the scene's scaleFactor.
+ */
+export class BoundaryWallScript extends Script {
+  static scriptName = 'boundaryWall';
+  center = new Vec3();
+  radius = 0;
+  groundPlane = [];
+  /** Flat bottom height used when no usable ground plane is supplied. */
+  baseY = 0;
+  /**
+   * Absolute world Y of the wall's top edge. The default puts it 2.5 m above a rig floor at y = 0,
+   * which is where the user actually stands - the splat's ground plane can be well below that.
+   */
+  topY = 2.5;
+  segments = 96;
+  gridSpacing = 0.5;
+  /** Grid line thickness in world metres. */
+  lineWidth = 0.025;
+  /** Head distance, in world metres, at which the wall starts to appear. */
+  fadeDistance = 1.5;
+  /** Multiplier applied to fadeDistance while movement is being clamped. */
+  blockedFadeScale = 2.5;
+  calmColor = new Color(0.35, 0.7, 1);
+  warnColor = new Color(1, 0.45, 0.2);
+  _camera = null;
+  _navigation = null;
+  _headParam = new Float32Array(3);
+  initialize() {
+    this._material = new ShaderMaterial({
+      uniqueName: 'boundary-wall',
+      vertexGLSL: wallVertexGLSL,
+      fragmentGLSL: wallFragmentGLSL,
+      attributes: {
+        vertex_position: SEMANTIC_POSITION,
+        aUv0: SEMANTIC_TEXCOORD0
+      }
+    });
+    this._material.blendType = BLEND_NORMAL;
+    this._material.cull = CULLFACE_NONE;
+    this._material.depthWrite = false;
+    this._material.update();
+    this._resolveDependencies();
+    this.rebuild();
+    this.once('destroy', () => {
+      this._clearMesh();
+      this._material?.destroy();
+      this._material = undefined;
+      this._camera = null;
+      this._navigation = null;
+    });
+  }
+
+  /**
+   * The camera and the navigation script both live on entities this one does not own. They are
+   * resolved lazily rather than once, because script initialize order across sibling entities is not
+   * guaranteed and this entity mounts when an XR session starts.
+   */
+  _resolveDependencies() {
+    if (!this._camera) {
+      this._camera = this.app.root.findByName('camera');
+    }
+    if (!this._navigation) {
+      const rig = this.app.root.findByName('camera-root');
+      // @ts-expect-error - scripts are added dynamically to the entity
+      this._navigation = rig?.script?.tfXrNavigation ?? null;
+    }
+  }
+  rebuild() {
+    this._clearMesh();
+    const geometry = boundaryWallMesh({
+      center: this.center,
+      radius: this.radius,
+      groundPlane: this.groundPlane,
+      baseY: this.baseY,
+      topY: this.topY,
+      gridSpacing: this.gridSpacing,
+      segments: this.segments
+    });
+    if (geometry.positions.length === 0 || !this._material) {
+      return;
+    }
+
+    // The shader measures distance in grid cells, so convert. A cell is gridSpacing across only
+    // approximately - columns and rows are rounded to whole numbers - but that error is well under
+    // a line width, so it is not worth carrying the exact cell size through as a second uniform.
+    this._material.setParameter('uLineHalfWidth', this.lineWidth / this.gridSpacing * 0.5);
+    this._material.setParameter('uFadeDistance', this.fadeDistance);
+    this._material.setParameter('uBlockedFadeScale', this.blockedFadeScale);
+    this._material.setParameter('uRows', geometry.rows);
+    this._material.setParameter('uCalmColor', [this.calmColor.r, this.calmColor.g, this.calmColor.b]);
+    this._material.setParameter('uWarnColor', [this.warnColor.r, this.warnColor.g, this.warnColor.b]);
+    this._material.setParameter('uBlocked', 0);
+    this._material.setParameter('uHeadPos', [0, 0, 0]);
+    const mesh = new Mesh(this.app.graphicsDevice);
+    mesh.setPositions(geometry.positions);
+    mesh.setUvs(0, geometry.uvs);
+    mesh.setIndices(geometry.indices);
+    mesh.update();
+    this._mesh = mesh;
+    const meshInstance = new MeshInstance(mesh, this._material);
+    if (this.entity.render) {
+      this.entity.render.meshInstances = [meshInstance];
+    } else {
+      // Immediate layer, drawn after the World layer where the splats render, so the wall is not
+      // composited behind them - same reason BoundaryRingScript uses it.
+      this.entity.addComponent('render', {
+        meshInstances: [meshInstance],
+        layers: [LAYERID_IMMEDIATE]
+      });
+    }
+  }
+  update() {
+    this._resolveDependencies();
+    const material = this._material;
+    const camera = this._camera;
+    if (!material || !camera || !this.entity.render) {
+      return;
+    }
+    const navigation = this._navigation;
+    // A disabled navigation script (e.g. edit mode) stops receiving postUpdate, so its
+    // clampDistance would otherwise latch whatever value it last held.
+    const blocked = navigation?.enabled !== false && (navigation?.clampDistance ?? 0) > 0 ? 1 : 0;
+    const reveal = this.fadeDistance * (blocked ? this.blockedFadeScale : 1);
+    const head = camera.getPosition();
+
+    // Skip the transparent draw entirely while the head is deeper inside than the widest reveal
+    // radius - every fragment would discard anyway. Toggling render.enabled rather than
+    // entity.enabled keeps this update running so the wall can come back.
+    const edgeDistance = distanceToCircleEdge(head.x, head.z, this.center.x, this.center.z, this.radius);
+    this.entity.render.enabled = this.radius > 0 && edgeDistance > -reveal;
+    if (!this.entity.render.enabled) {
+      return;
+    }
+    this._headParam[0] = head.x;
+    this._headParam[1] = head.y;
+    this._headParam[2] = head.z;
+    material.setParameter('uHeadPos', this._headParam);
+    material.setParameter('uBlocked', blocked);
+  }
+  _clearMesh() {
+    if (this.entity.render) {
+      this.entity.render.meshInstances = [];
+    }
+    if (this._mesh) {
+      this._mesh.destroy();
+      this._mesh = undefined;
+    }
+  }
+}

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']);
+  });
+});