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

package/components/VirtualWalkthrough/gsplat-fade-crop-effect.js

@@ -1,6 +1,7 @@
-import { Vec3 } from "playcanvas";
-import { GSplatShaderEffect } from "playcanvas/scripts/esm/gsplat/gsplat-shader-effect.mjs";
-const shaderGLSL = `
+import { Vec3 } from 'playcanvas';
+import { GSplatShaderEffect } from 'playcanvas/scripts/esm/gsplat/gsplat-shader-effect.mjs';
+
+const shaderGLSL = /* glsl */`
 uniform vec3 uAabbMin;
 uniform vec3 uAabbMax;
 uniform float uFadeDistance;
@@ -43,7 +44,7 @@ void modifySplatColor(vec3 center, inout vec4 color) {
     // No color modification needed
 }
 `;
-const shaderWGSL = `
+const shaderWGSL = /* wgsl */`
 uniform uAabbMin: vec3f;
 uniform uAabbMax: vec3f;
 uniform uFadeDistance: f32;
@@ -86,37 +87,36 @@ fn modifySplatColor(center: vec3f, color: ptr<function, vec4f>) {
     // No color modification needed
 }
 `;
+
+/**
+ * Fade crop shader effect for gaussian splats.
+ * Applies a smooth fade to splats outside the AABB based on distance.
+ * Splats at the AABB edge are fully visible, and fade to invisible at fadeDistance away.
+ */
 class GsplatFadeCropShaderEffect extends GSplatShaderEffect {
-    static scriptName = 'gsplatFadeCropShaderEffect';
-    _aabbMinArray = [
-        0,
-        0,
-        0
-    ];
-    _aabbMaxArray = [
-        0,
-        0,
-        0
-    ];
-    aabbMin = new Vec3(-0.5, -0.5, -0.5);
-    aabbMax = new Vec3(0.5, 0.5, 0.5);
-    fadeDistance = 0.5;
-    getShaderGLSL() {
-        return shaderGLSL;
-    }
-    getShaderWGSL() {
-        return shaderWGSL;
-    }
-    updateEffect() {
-        this._aabbMinArray[0] = this.aabbMin.x;
-        this._aabbMinArray[1] = this.aabbMin.y;
-        this._aabbMinArray[2] = this.aabbMin.z;
-        this.setUniform('uAabbMin', this._aabbMinArray);
-        this._aabbMaxArray[0] = this.aabbMax.x;
-        this._aabbMaxArray[1] = this.aabbMax.y;
-        this._aabbMaxArray[2] = this.aabbMax.z;
-        this.setUniform('uAabbMax', this._aabbMaxArray);
-        this.setUniform('uFadeDistance', this.fadeDistance);
-    }
+  static scriptName = 'gsplatFadeCropShaderEffect';
+  _aabbMinArray = [0, 0, 0];
+  _aabbMaxArray = [0, 0, 0];
+  aabbMin = new Vec3(-0.5, -0.5, -0.5);
+  aabbMax = new Vec3(0.5, 0.5, 0.5);
+  fadeDistance = 0.5;
+  getShaderGLSL() {
+    return shaderGLSL;
+  }
+  getShaderWGSL() {
+    return shaderWGSL;
+  }
+  updateEffect() {
+    this._aabbMinArray[0] = this.aabbMin.x;
+    this._aabbMinArray[1] = this.aabbMin.y;
+    this._aabbMinArray[2] = this.aabbMin.z;
+    this.setUniform('uAabbMin', this._aabbMinArray);
+    this._aabbMaxArray[0] = this.aabbMax.x;
+    this._aabbMaxArray[1] = this.aabbMax.y;
+    this._aabbMaxArray[2] = this.aabbMax.z;
+    this.setUniform('uAabbMax', this._aabbMaxArray);
+    this.setUniform('uFadeDistance', this.fadeDistance);
+  }
 }
+
 export { GsplatFadeCropShaderEffect };

package/components/VirtualWalkthrough/splatFormat.js

@@ -1,18 +1,52 @@
+/*
+ * The playcanvas gsplat loader picks its parser from the asset's `filename`, not from the URL it
+ * actually downloads, because a splat is frequently served from a signed or extensionless URL. Each
+ * supported format therefore maps to a canonical filename whose extension/basename routes the asset
+ * to the matching engine parser:
+ *
+ *   model.sog     -> SogBundleParser      sog packed into a single zip archive
+ *   meta.json     -> SogParser            the same sog data left unpacked as separate files
+ *   lod-meta.json -> GSplatOctreeParser   sog with LOD levels, streamed in as the camera moves
+ *   model.ply     -> PlyParser
+ *
+ * `sog` and `sogUnbundled` are two packagings of one format, not two formats: both parsers build a
+ * GSplatSogData/GSplatSogResource and both await every texture before the resource exists. Only
+ * `sogStreamed` streams — playcanvas.d.ts on GSplatOctreeResource#numSplats: "Not all of these are
+ * resident at runtime: the LOD streaming system selects a subset per node based on view distance and
+ * the configured splat budget."
+ *
+ * Only the filename is faked; the textures an unbundled or streamed sog references are still
+ * resolved relative to the real URL, so no rewriting of splatSrc is needed.
+ */
 const LOADER_FILENAMES = {
-    sog: 'model.sog',
-    sogUnbundled: 'meta.json',
-    sogStreamed: 'lod-meta.json',
-    ply: 'model.ply'
+  sog: 'model.sog',
+  sogUnbundled: 'meta.json',
+  sogStreamed: 'lod-meta.json',
+  ply: 'model.ply'
 };
+/**
+ * Format assumed when a URL is too opaque to tell us anything. Kept as the bundled `.sog` archive so
+ * that existing extensionless splat URLs keep loading the way they did before the other formats were
+ * supported.
+ */
 const DEFAULT_SPLAT_FORMAT = 'sog';
-const splatLoaderFilename = (format)=>LOADER_FILENAMES[format];
-const detectSplatFormat = (splatSrc)=>{
-    const path = splatSrc.split(/[?#]/)[0];
-    const basename = path.slice(path.lastIndexOf('/') + 1).toLowerCase();
-    if ('lod-meta.json' === basename) return 'sogStreamed';
-    if ('meta.json' === basename) return 'sogUnbundled';
-    if (basename.endsWith('.ply')) return 'ply';
-    if (basename.endsWith('.sog')) return 'sog';
-    return DEFAULT_SPLAT_FORMAT;
+const splatLoaderFilename = format => LOADER_FILENAMES[format];
+const detectSplatFormat = splatSrc => {
+  const path = splatSrc.split(/[?#]/)[0];
+  const basename = path.slice(path.lastIndexOf('/') + 1).toLowerCase();
+  if (basename === 'lod-meta.json') {
+    return 'sogStreamed';
+  }
+  if (basename === 'meta.json') {
+    return 'sogUnbundled';
+  }
+  if (basename.endsWith('.ply')) {
+    return 'ply';
+  }
+  if (basename.endsWith('.sog')) {
+    return 'sog';
+  }
+  return DEFAULT_SPLAT_FORMAT;
 };
+
 export { DEFAULT_SPLAT_FORMAT, detectSplatFormat, splatLoaderFilename };

package/components/VirtualWalkthrough/useAdoptedCamera.js

@@ -1,24 +1,45 @@
-import { useLayoutEffect, useState } from "react";
-import { useApp } from "@playcanvas/react/hooks";
-import { adoptSceneCamera } from "./camera-adoption.js";
-const useAdoptedCamera = (rig, ownCamera)=>{
-    const app = useApp();
-    const [adopted, setAdopted] = useState(null);
-    useLayoutEffect(()=>{
-        if (!rig || !ownCamera) return;
-        const adoption = adoptSceneCamera(app.root, rig, ownCamera);
-        setAdopted(adoption?.camera ?? null);
-        return ()=>{
-            adoption?.release();
-            setAdopted(null);
-        };
-    }, [
-        app,
-        rig,
-        ownCamera
-    ]);
-    return adopted;
+import { useState, useLayoutEffect } from 'react';
+import { useApp } from '@playcanvas/react/hooks';
+import { adoptSceneCamera } from './camera-adoption.js';
+
+/**
+ * Keeps the walkthrough's rig holding a camera for as long as the viewer is mounted, adopting the
+ * scene's own when the viewer wasn't given one. See {@link adoptSceneCamera} for why.
+ *
+ * @param rig - The `camera-root` entity, or null before it exists.
+ * @param ownCamera - The entity the viewer mounts its own camera on, or null before it exists.
+ * @returns The adopted camera, or null when the viewer brought one of its own. Held as state so the
+ * viewer re-renders and re-points everything that addresses the camera at the entity now carrying
+ * it.
+ */
+const useAdoptedCamera = (rig, ownCamera) => {
+  const app = useApp();
+  const [adopted, setAdopted] = useState(null);
+
+  // A layout effect, so that the camera is handed back before the rig it was parented into is
+  // destroyed. `@playcanvas/react`'s Entity destroys its entity in a layout effect's teardown, and
+  // destroying an entity destroys its children — so a release deferred to a passive effect runs
+  // after the host's camera has already been destroyed along with the walkthrough, leaving the host
+  // scene with no camera to render through at all.
+  //
+  // The rig is a child of the viewer, and React tears an unmounting tree's layout effects down from
+  // the top, so this runs first.
+  useLayoutEffect(() => {
+    if (!rig || !ownCamera) {
+      return;
+    }
+
+    // Both entities are state set from refs, so this runs a commit after the child that mounts the
+    // camera component: a viewer that was given a camera is recognised as owning one rather than
+    // adopted on top of.
+    const adoption = adoptSceneCamera(app.root, rig, ownCamera);
+    setAdopted(adoption?.camera ?? null);
+    return () => {
+      adoption?.release();
+      setAdopted(null);
+    };
+  }, [app, rig, ownCamera]);
+  return adopted;
 };
-const VirtualWalkthrough_useAdoptedCamera = useAdoptedCamera;
-export default VirtualWalkthrough_useAdoptedCamera;
-export { useAdoptedCamera };
+
+export { useAdoptedCamera as default, useAdoptedCamera };

package/components/VirtualWalkthrough/useRestartOnVr.js

@@ -1,27 +1,38 @@
-import { useEffect } from "react";
-import { useApp } from "@playcanvas/react/hooks";
-import { XRTYPE_VR } from "playcanvas";
-const useRestartOnVr = (scriptRef, enabled)=>{
-    const app = useApp();
-    useEffect(()=>{
-        const xr = app?.xr;
-        if (!xr || !enabled) return;
-        const restart = ()=>{
-            const script = scriptRef.current;
-            if (!script || xr.type !== XRTYPE_VR) return;
-            script.enabled = false;
-            script.enabled = true;
-        };
-        xr.on('start', restart);
-        return ()=>{
-            xr.off('start', restart);
-        };
-    }, [
-        app,
-        enabled,
-        scriptRef
-    ]);
+import { useEffect } from 'react';
+import { useApp } from '@playcanvas/react/hooks';
+import { XRTYPE_VR } from 'playcanvas';
+
+/**
+ * Replays a one-shot script effect at the start of every VR session.
+ *
+ * `GSplatShaderEffect` zeroes its timeline on the script's `enable` event and switches itself off
+ * once the animation has played out, so re-enabling a finished effect runs it again. The `enabled`
+ * setter only fires the event on a change of state, which is why an effect still mid-play is taken
+ * back through disabled first.
+ *
+ * @param scriptRef - The script instance to replay, as handed back by `Script`'s ref.
+ * @param enabled - Whether the effect is in use at all. No session is watched while false.
+ */
+const useRestartOnVr = (scriptRef, enabled) => {
+  const app = useApp();
+  useEffect(() => {
+    const xr = app?.xr;
+    if (!xr || !enabled) {
+      return;
+    }
+    const restart = () => {
+      const script = scriptRef.current;
+      if (!script || xr.type !== XRTYPE_VR) {
+        return;
+      }
+      script.enabled = false;
+      script.enabled = true;
+    };
+    xr.on('start', restart);
+    return () => {
+      xr.off('start', restart);
+    };
+  }, [app, enabled, scriptRef]);
 };
-const VirtualWalkthrough_useRestartOnVr = useRestartOnVr;
-export default VirtualWalkthrough_useRestartOnVr;
-export { useRestartOnVr };
+
+export { useRestartOnVr as default, useRestartOnVr };

package/components/VirtualWalkthrough/useXrRenderTuning.js

@@ -1,34 +1,55 @@
-import { useEffect } from "react";
-import { useApp } from "@playcanvas/react/hooks";
-import { XR_FIXED_FOVEATION, applyGsplatTuning, restoreGsplatTuning } from "./xr-render-tuning.js";
-const useXrRenderTuning = ()=>{
-    const app = useApp();
-    useEffect(()=>{
-        const xr = app.xr;
-        if (!xr) return;
-        let previous = null;
-        const restore = ()=>{
-            if (previous) {
-                restoreGsplatTuning(app.scene.gsplat, previous);
-                previous = null;
-            }
-        };
-        const handleStart = ()=>{
-            if (!previous) previous = applyGsplatTuning(app.scene.gsplat);
-            xr.fixedFoveation = XR_FIXED_FOVEATION;
-        };
-        xr.on('start', handleStart);
-        xr.on('end', restore);
-        if (xr.active) handleStart();
-        return ()=>{
-            xr.off('start', handleStart);
-            xr.off('end', restore);
-            restore();
-        };
-    }, [
-        app
-    ]);
+import { useEffect } from 'react';
+import { useApp } from '@playcanvas/react/hooks';
+import { applyGsplatTuning, XR_FIXED_FOVEATION, restoreGsplatTuning } from './xr-render-tuning.js';
+
+/**
+ * Holds the XR render settings in place for the duration of a session, including one that is
+ * already running when this mounts.
+ *
+ * Call this once per application. The gsplat settings it writes are scene-global, so a second
+ * caller would capture the first caller's tuned values as the state to restore, and the scene would
+ * come out of the session still tuned.
+ */
+const useXrRenderTuning = () => {
+  const app = useApp();
+  useEffect(() => {
+    const xr = app.xr;
+    if (!xr) {
+      return;
+    }
+    let previous = null;
+    const restore = () => {
+      if (previous) {
+        restoreGsplatTuning(app.scene.gsplat, previous);
+        previous = null;
+      }
+    };
+    const handleStart = () => {
+      // Guards against capturing already-tuned values as the restore target if `start` ever
+      // fires again before a matching `end`.
+      if (!previous) {
+        previous = applyGsplatTuning(app.scene.gsplat);
+      }
+      // Only settable on an active session, so it cannot go in the start options alongside
+      // framebufferScaleFactor. A no-op when the presentation layer doesn't support it.
+      xr.fixedFoveation = XR_FIXED_FOVEATION;
+    };
+    xr.on('start', handleStart);
+    xr.on('end', restore);
+
+    // A viewer can be mounted into a scene that is already in a headset, in which case `start`
+    // fired before this hook existed and waiting for it would leave the whole session rendering
+    // with the desktop settings. `handleStart` is idempotent, so a session that goes on to fire
+    // `start` anyway does not capture the tuned values as the ones to restore.
+    if (xr.active) {
+      handleStart();
+    }
+    return () => {
+      xr.off('start', handleStart);
+      xr.off('end', restore);
+      restore();
+    };
+  }, [app]);
 };
-const VirtualWalkthrough_useXrRenderTuning = useXrRenderTuning;
-export default VirtualWalkthrough_useXrRenderTuning;
-export { useXrRenderTuning };
+
+export { useXrRenderTuning as default, useXrRenderTuning };

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

@@ -1,20 +1,29 @@
-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;
+/**
+ * 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.
+ */
+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;
 };
 const PANEL_CANVAS_WIDTH = 1024;
+/** Tallest the panel can grow; also the canvas the content is painted into. */
 const PANEL_MAX_HEIGHT = 768;
+/** Shortest the panel can shrink, so a bare title still reads as a panel rather than a sliver. */
 const PANEL_MIN_HEIGHT = 200;
 const PANEL_PAD_X = 48;
 const PANEL_PAD_Y = 40;
@@ -28,63 +37,86 @@ const CHIP_GAP = 24;
 const TITLE_LINE_HEIGHT = 56;
 const TITLE_GAP = 16;
 const BODY_LINE_HEIGHT = 40;
+
+/**
+ * Tallest canvas the body text is rasterised into. The body scrolls as a window onto this canvas,
+ * so it bounds how much text an annotation can show — far more than the panel itself holds.
+ */
 const TEXT_CANVAS_MAX_HEIGHT = 2048;
 const PANEL_FONTS = {
-    label: '600 28px sans-serif',
-    title: '700 48px sans-serif',
-    body: '400 32px sans-serif'
+  label: '600 28px sans-serif',
+  title: '700 48px sans-serif',
+  body: '400 32px sans-serif'
 };
-const fitLines = (lines, y, lineHeight)=>{
-    const room = Math.max(0, Math.floor((PANEL_MAX_HEIGHT - PANEL_PAD_Y - y) / lineHeight));
-    return lines.slice(0, room);
+/** Keeps the lines whose full line box fits above the bottom padding. */
+const fitLines = (lines, y, lineHeight) => {
+  const room = Math.max(0, Math.floor((PANEL_MAX_HEIGHT - PANEL_PAD_Y - y) / lineHeight));
+  return lines.slice(0, room);
 };
-const layoutPanel = ({ title, label, bodyText, imageCount, contentWidth, measure })=>{
-    let y = PANEL_PAD_Y;
-    const image = imageCount > 0 ? {
-        y,
-        height: IMAGE_BAND_HEIGHT
-    } : null;
-    let dotsY = null;
-    if (image) {
-        y += IMAGE_BAND_HEIGHT + IMAGE_GAP;
-        if (imageCount > 1) {
-            dotsY = y + DOTS_CENTER_OFFSET;
-            y += DOTS_BLOCK_HEIGHT;
-        }
-        y += IMAGE_GAP;
+
+/**
+ * Lays the panel's blocks out top-to-bottom and reports the height they need, so the quad
+ * can be sized to the content instead of a fixed aspect. Everything above the body is a header
+ * that has to fit within `PANEL_MAX_HEIGHT`; the body instead scrolls within whatever height
+ * the header leaves it.
+ */
+const layoutPanel = ({
+  title,
+  label,
+  bodyText,
+  imageCount,
+  contentWidth,
+  measure
+}) => {
+  let y = PANEL_PAD_Y;
+  const image = imageCount > 0 ? {
+    y,
+    height: IMAGE_BAND_HEIGHT
+  } : null;
+  let dotsY = null;
+  if (image) {
+    y += IMAGE_BAND_HEIGHT + IMAGE_GAP;
+    if (imageCount > 1) {
+      dotsY = y + DOTS_CENTER_OFFSET;
+      y += DOTS_BLOCK_HEIGHT;
+    }
+    y += IMAGE_GAP;
+  }
+  const chip = label ? {
+    y,
+    width: measure(label, 'label') + CHIP_PAD_X * 2,
+    height: CHIP_HEIGHT
+  } : null;
+  if (chip) {
+    y += CHIP_HEIGHT + CHIP_GAP;
+  }
+  const titleLines = wrapText(title, contentWidth, segment => measure(segment, 'title'));
+  const fittedTitle = fitLines(titleLines, y, TITLE_LINE_HEIGHT);
+  const titleY = y;
+  y += fittedTitle.length * TITLE_LINE_HEIGHT + TITLE_GAP;
+  const bodyLines = bodyText ? wrapText(bodyText, contentWidth, segment => measure(segment, 'body')) : [];
+  const fittedBody = bodyLines.slice(0, Math.floor(TEXT_CANVAS_MAX_HEIGHT / BODY_LINE_HEIGHT));
+  const bodyY = y;
+  const contentHeight = fittedBody.length * BODY_LINE_HEIGHT;
+  const viewportHeight = Math.min(contentHeight, Math.max(0, PANEL_MAX_HEIGHT - PANEL_PAD_Y - bodyY));
+  const height = Math.max(PANEL_MIN_HEIGHT, Math.min(PANEL_MAX_HEIGHT, bodyY + viewportHeight + PANEL_PAD_Y));
+  return {
+    height,
+    image,
+    dotsY,
+    chip,
+    title: {
+      y: titleY,
+      lines: fittedTitle
+    },
+    body: {
+      y: bodyY,
+      lines: fittedBody,
+      contentHeight,
+      viewportHeight,
+      scrollable: viewportHeight > 0 && contentHeight > viewportHeight
     }
-    const chip = label ? {
-        y,
-        width: measure(label, 'label') + 2 * CHIP_PAD_X,
-        height: CHIP_HEIGHT
-    } : null;
-    if (chip) y += CHIP_HEIGHT + CHIP_GAP;
-    const titleLines = wrapText(title, contentWidth, (segment)=>measure(segment, 'title'));
-    const fittedTitle = fitLines(titleLines, y, TITLE_LINE_HEIGHT);
-    const titleY = y;
-    y += fittedTitle.length * TITLE_LINE_HEIGHT + TITLE_GAP;
-    const bodyLines = bodyText ? wrapText(bodyText, contentWidth, (segment)=>measure(segment, 'body')) : [];
-    const fittedBody = bodyLines.slice(0, Math.floor(TEXT_CANVAS_MAX_HEIGHT / BODY_LINE_HEIGHT));
-    const bodyY = y;
-    const contentHeight = fittedBody.length * BODY_LINE_HEIGHT;
-    const viewportHeight = Math.min(contentHeight, Math.max(0, PANEL_MAX_HEIGHT - PANEL_PAD_Y - bodyY));
-    const height = Math.max(PANEL_MIN_HEIGHT, Math.min(PANEL_MAX_HEIGHT, bodyY + viewportHeight + PANEL_PAD_Y));
-    return {
-        height,
-        image,
-        dotsY,
-        chip,
-        title: {
-            y: titleY,
-            lines: fittedTitle
-        },
-        body: {
-            y: bodyY,
-            lines: fittedBody,
-            contentHeight,
-            viewportHeight,
-            scrollable: viewportHeight > 0 && contentHeight > viewportHeight
-        }
-    };
+  };
 };
+
 export { BODY_LINE_HEIGHT, CHIP_HEIGHT, IMAGE_BAND_HEIGHT, PANEL_CANVAS_WIDTH, PANEL_FONTS, PANEL_MAX_HEIGHT, PANEL_MIN_HEIGHT, PANEL_PAD_X, PANEL_PAD_Y, TEXT_CANVAS_MAX_HEIGHT, TITLE_LINE_HEIGHT, layoutPanel, wrapText };