@preference-sl/pref-viewer 2.18.0 → 3.0.0-beta.0

package/index.d.ts

@@ -3,6 +3,9 @@ import type React from "react";
 /** Render mode. `loadConfig`/`loadDrawing` pick the matching one on their own. */
 export type PrefViewerMode = "2d" | "3d";
 
+/** Selectable orientation widget; Canvas is the default and uses a dedicated Babylon scene; SVG remains explicitly selectable. */
+export type PrefViewerViewCubeRenderer = "svg" | "canvas";
+
 /** Animation state as reported by `getAnimations()` and `prefviewer-animation-changed`. */
 export type PrefViewerAnimationState = 0 | 1 | 2 | 3 | 4;
 
@@ -27,14 +30,52 @@ export interface PrefViewerAsset {
   visible?: boolean;
 }
 
+/** Partial style overrides. Null leaves/groups remove customizations; omitted leaves are preserved. */
+export interface PrefViewerStyles {
+  colorPrimary?: string | null;
+  viewCube?: {
+    colors?: {
+      face?: string | null;
+      edge?: string | null;
+      corner?: string | null;
+      /** SVG outline only. */
+      border?: string | null;
+      text?: string | null;
+      hover?: string | null;
+      active?: string | null;
+    } | null;
+    hoverOpacity?: number | null;
+    activeOpacity?: number | null;
+    typography?: {
+      fontFamily?: string | null;
+      /** Positive reference pixels; scaled to Canvas texture resolution. */
+      fontSize?: number | null;
+      /** Integer from 1 to 1000. */
+      fontWeight?: number | null;
+      /** Nonnegative reference pixels. */
+      letterSpacing?: number | null;
+      textTransform?: "none" | "uppercase" | "lowercase" | null;
+    } | null;
+  } | null;
+}
+
+/** Optional origin-local persistence; configure before insertion to avoid storage reads when disabled. */
+export interface PrefViewerStylesPersistence {
+  enabled?: boolean;
+  /** Exact localStorage key; defaults to pref-viewer/styles. */
+  key?: string;
+}
+
 /** Payload for `loadConfig`. Pass the object; a JSON string is also accepted. */
 export interface PrefViewerConfig {
   /** Sets show-render-menu when supplied; omission preserves the current attribute. */
   showRenderMenu?: boolean;
   /** Sets show-view-cube when supplied; omission preserves the current attribute. */
   showViewCube?: boolean;
+  /** Selects the cube renderer when this queued configuration is processed; omission preserves it. */
+  viewCubeRenderer?: PrefViewerViewCubeRenderer;
   culture?: string;
-  styles?: Record<string, unknown> | string;
+  styles?: PrefViewerStyles | string;
   model?: PrefViewerAsset;
   scene?: PrefViewerAsset;
   materials?: PrefViewerAsset;
@@ -222,6 +263,9 @@ export interface PrefViewerEventMap {
 }
 
 export declare class PrefViewer extends HTMLElement {
+  /** Reflected view-cube-renderer preference; invalid/missing values use canvas. */
+  get viewCubeRenderer(): PrefViewerViewCubeRenderer;
+  set viewCubeRenderer(value: PrefViewerViewCubeRenderer);
   // ── Property setters (each mirrors the attribute of the same name) ──
   set config(v: PrefViewerConfig | string | null);
   set culture(v: string | null);
@@ -232,8 +276,14 @@ export declare class PrefViewer extends HTMLElement {
   set model(v: PrefViewerAsset | string | null);
   set options(v: Record<string, unknown> | string | null);
   set scene(v: PrefViewerAsset | string | null);
-  /** Supported style overrides; currently `{ colorPrimary }`. */
-  set styles(v: Record<string, unknown> | string | null);
+  /** Detached merged overrides, including effective primary; omitted leaves use internal defaults. */
+  get styles(): PrefViewerStyles;
+  /** Same queued partial patch as setStyles. */
+  set styles(v: PrefViewerStyles | string);
+  get stylesPersistence(): Required<PrefViewerStylesPersistence>;
+  set stylesPersistence(v: PrefViewerStylesPersistence);
+  /** Clears only the configured saved entry, preserving appearance. False when disabled/unavailable. */
+  clearPersistedStyles(): boolean;
 
   // ── Read-only state ──
   get culture(): string;
@@ -256,9 +306,8 @@ export declare class PrefViewer extends HTMLElement {
   setOptions(options: Record<string, unknown> | string): void;
   /** Convenience wrapper for `setOptions({ ibl })`. False when the payload is unusable. */
   setIBL(ibl: Record<string, unknown> | string): boolean | void;
-  /** Runtime style overrides; currently `{ colorPrimary }`. False when unusable. */
-  /** Updates primary UI and animation-opening highlight color, including an active highlight. */
-  setStyles(styles: Record<string, unknown> | string): boolean | void;
+  /** Queues validated primary/ViewCube overrides; false for a non-object payload, otherwise void. Malformed JSON throws. */
+  setStyles(styles: PrefViewerStyles | string): boolean | void;
   /** 3D runtime diagnostics, or null before the 3D component exists. */
   getDebugInfo(): Record<string, unknown> | null;
 
@@ -345,7 +394,13 @@ export declare class PrefViewer extends HTMLElement {
  * `materials`, `drawing`, `options`, `styles`) are JSON strings when written as attributes —
  * pass the objects through the matching method or property instead.
  */
+/** Control sizing; auto follows primary coarse-pointer capability, independently of DPR. */
+export type PrefViewerControlsDensity = "auto" | "compact" | "comfortable";
+
 export interface PrefViewerAttributes {
+  "view-cube-renderer"?: PrefViewerViewCubeRenderer;
+  /** Automatic or explicit control presentation; default auto. */
+  "controls-density"?: PrefViewerControlsDensity;
   config?: string;
   culture?: string;
   drawing?: string;
@@ -362,6 +417,17 @@ export interface PrefViewerAttributes {
   "show-view-cube"?: boolean | "true" | "false";
 }
 
+/** Standalone 3D element renderer preference; the root owns nested instances. */
+export interface PrefViewer3DElement extends HTMLElement {
+  viewCubeRenderer: PrefViewerViewCubeRenderer;
+}
+
+type PrefViewer3DJsxProps = React.DetailedHTMLProps<
+  React.HTMLAttributes<PrefViewer3DElement> & Pick<PrefViewerAttributes,
+    "view-cube-renderer" | "show-view-cube" | "show-model" | "show-scene" | "controls-density"> & { visible?: boolean | "true" | "false" },
+  PrefViewer3DElement
+>;
+
 /** <pref-viewer mode="3d" style="display:block; width:100%; height:600px" /> */
 type PrefViewerJsxProps = React.DetailedHTMLProps<
   React.HTMLAttributes<PrefViewer> & PrefViewerAttributes,
@@ -371,12 +437,14 @@ type PrefViewerJsxProps = React.DetailedHTMLProps<
 declare global {
   interface HTMLElementTagNameMap {
     "pref-viewer": PrefViewer;
+    "pref-viewer-3d": PrefViewer3DElement;
   }
 
   // React <= 18 (@types/react 18) resolves intrinsics through the global JSX namespace.
   namespace JSX {
     interface IntrinsicElements {
       "pref-viewer": PrefViewerJsxProps;
+      "pref-viewer-3d": PrefViewer3DJsxProps;
     }
   }
 }
@@ -388,6 +456,7 @@ declare module "react" {
   namespace JSX {
     interface IntrinsicElements {
       "pref-viewer": PrefViewerJsxProps;
+      "pref-viewer-3d": PrefViewer3DJsxProps;
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.18.0",
+    "version": "3.0.0-beta.0",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -10,7 +10,10 @@
         "release:beta": "standard-version --prerelease beta --releaseCommitMessageFormat \"chore(release): {{currentTag}} [skip ci]\"",
         "build": "esbuild src/index.js --bundle --platform=node --format=esm --outfile=dist/bundle.js --sourcemap",
         "start": "npm run build && http-server -c-1 . -p 8080",
-        "test": "vitest"
+        "test": "vitest",
+        "test:e2e": "node tests/e2e/run.mjs test",
+        "test:e2e:install": "node tests/e2e/run.mjs install webkit",
+        "test:e2e:report": "node tests/e2e/run.mjs show-report"
     },
     "repository": {
         "type": "git",
@@ -51,9 +54,12 @@
     "devDependencies": {
         "@babel/core": "^7.22.0",
         "@babel/preset-env": "^7.22.0",
+        "@playwright/test": "1.65.0-alpha-2026-10-15",
         "babel-loader": "^9.2.1",
         "clean-webpack-plugin": "^4.0.0",
+        "draco3dgltf": "1.5.7",
         "esbuild": "^0.25.10",
+        "fflate": "0.8.3",
         "http-server": "^14.1.1",
         "jsdom": "^26.1.0",
         "standard-version": "^9.5.0",

package/src/babylonjs-animation-controller.js

@@ -15,6 +15,7 @@ import BabylonJSAnimationOverlayController from "./babylonjs-animation-overlay-c
  *  - Tracks animated transformation nodes and their relationships to meshes.
  *  - Exposes animation availability through `hasAnimations()`.
  *  - Highlights animated nodes and their child meshes on pointer hover.
+ *  - Can restrict touch-hold feedback to nodes belonging to opening/closing animation pairs.
  *  - Avoids redundant highlight rebuilds using cached mesh/node IDs and order-insensitive node-id comparison.
  *  - Reports highlight-state deltas from `highlightMeshes()` so callers can react efficiently.
  *  - Displays and disposes the animation control menu for animated nodes.
@@ -311,10 +312,11 @@ export default class BabylonJSAnimationController {
      * highlighted node set has not changed.
      * @public
      * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
+     * @param {boolean} [openingOnly=false] - Restrict feedback to opening/closing pairs, preserving ordinary mouse hover otherwise.
      * @returns {{changed:boolean, highlighted:boolean}}
      * Returns whether highlight visuals changed in this call and whether any mesh remains highlighted.
      */
-    highlightMeshes(pickingInfo) {
+    highlightMeshes(pickingInfo, openingOnly = false) {
         // If highlight is disabled globally, just remove any existing highlight and return
         if (!BabylonJSAnimationController.#globalHighlightEnabled) {
             if (this.#lastHighlightedMeshId !== null) {
@@ -330,10 +332,11 @@ export default class BabylonJSAnimationController {
         let highlighted = false;
 
         // Check if we're hovering the same mesh to avoid recreating overlays/highlights
-        const pickedMeshId = !pickingInfo?.hit || !pickingInfo?.pickedMesh?.id ? null : pickingInfo.pickedMesh.id;
-        const pickedMesh = pickingInfo?.pickedMesh ? pickingInfo.pickedMesh : null;
+        const pickedMesh = pickingInfo?.hit ? pickingInfo.pickedMesh : null;
+        const nodeIds = this.#getNodesAnimatedByMesh(pickedMesh).filter(nodeId => !openingOnly || this.#getOpeningAnimationByNode(nodeId));
+        const pickedMeshId = nodeIds.length ? pickedMesh?.id ?? null : null;
 
-        if (this.#lastHighlightedMeshId === pickedMeshId) {
+        if (this.#lastHighlightedMeshId === pickedMeshId && this.#haveSameNodeIds(nodeIds, this.#lastHighlightedNodeIds)) {
             // No need to update if hovering the same mesh
             if (this.#lastHighlightedMeshId !== null) {
                 changed = false;
@@ -343,7 +346,6 @@ export default class BabylonJSAnimationController {
                 highlighted = false;
             }
         } else {
-            const nodeIds = this.#getNodesAnimatedByMesh(pickedMesh);
             if (!nodeIds.length) {
                 if (this.#lastHighlightedMeshId !== null) {
                     this.#removeHighlight();
@@ -372,9 +374,9 @@ export default class BabylonJSAnimationController {
     }
 
     /**
-     * Configures the highlight settings for animated nodes on hover.
+     * Configures highlights for animated nodes during mouse hover or a pending touch hold.
      * @public
-     * @param {{enabled?: boolean, color?: string}} config - Configuration object.
+     * @param {{enabled?: boolean, color?: string}} [config={}] - Configuration object.
      * @param {boolean} [config.enabled] - Whether to enable highlight on hover. If false, removes highlight.
      * @param {string} [config.color] - Hex color string for the highlight (e.g., "#FF0000"). Only used if enabled is not false.
      * @returns {void}
@@ -439,7 +441,9 @@ export default class BabylonJSAnimationController {
      */
     playAnimation(name, action) {
         const anim = this.#openingAnimations.find((a) => a.name === name);
-        if (!anim) return false;
+        if (!anim) {
+            return false;
+        }
         switch (action) {
             case "open": anim.playOpen(); break;
             case "close": anim.playClose(); break;
@@ -460,7 +464,9 @@ export default class BabylonJSAnimationController {
      */
     setAnimationProgress(name, progress) {
         const anim = this.#openingAnimations.find((a) => a.name === name);
-        if (!anim) return false;
+        if (!anim) {
+            return false;
+        }
         anim.setProgress(progress);
         return true;
     }
@@ -474,7 +480,9 @@ export default class BabylonJSAnimationController {
      */
     setAnimationLoop(name, loop) {
         const anim = this.#openingAnimations.find((a) => a.name === name);
-        if (!anim) return false;
+        if (!anim) {
+            return false;
+        }
         anim.setLoop(loop);
         return true;
     }

package/src/babylonjs-animation-opening-menu.js

@@ -16,7 +16,8 @@ import { PrefViewer3DAnimationMenuStyles } from "./styles.js";
  *  - Handles user interactions and invokes provided callbacks for animation actions.
  *  - Synchronizes the slider value with animation progress, avoiding callback loops.
  *  - Provides setters to update animation state, progress, and loop mode from external controllers.
- *  - Disposes and cleans up all DOM resources when no longer needed.
+ *  - Owns temporary touch feedback for playback, animation selectors and progress input.
+ *  - Disposes DOM resources and touch completion/blur subscriptions when no longer needed.
  *  - Resets other animation menus when switching between animations.
  *
  * Public Setters:
@@ -74,6 +75,53 @@ export default class OpeningAnimationMenu {
     #containerButtons = null;
     #slider = null;
 
+    #touchPressedControl = null;
+    #touchPointerId = null;
+
+    /**
+     * Marks an enabled playback/selector button or range during touch-down, including SVG descendants.
+     * A second touch cancels feedback; native clicks, range dragging and scrolling are not prevented.
+     * @param {PointerEvent} event - Pointer down bubbling within this menu.
+     * @returns {void}
+     */
+    #onTouchPress = event => {
+        if (event.pointerType !== "touch") {
+            return;
+        }
+        if (this.#touchPressedControl) {
+            this.#clearTouchPress();
+            return;
+        }
+        const control = event.target.closest?.('button, input[type="range"]');
+        if (!control || !this.#containerMain?.contains(control) || control.matches(':disabled, .disabled, .hidden')) {
+            return;
+        }
+        this.#touchPressedControl = control;
+        this.#touchPointerId = event.pointerId;
+        control.setAttribute("data-touch-pressed", "");
+    };
+
+    /**
+     * Releases feedback when the owning finger ends or is cancelled, including outside the menu.
+     * @param {PointerEvent} event - Document-level pointer completion.
+     * @returns {void}
+     */
+    #onTouchRelease = event => {
+        if (event.pointerId === this.#touchPointerId) {
+            this.#clearTouchPress();
+        }
+    };
+
+    /**
+     * Removes only this menu's temporary touch state, also on blur, disabling a control or disposal.
+     * @returns {void} Idempotent; does not change progress, focus or animation state.
+     */
+    #clearTouchPress = () => {
+        this.#touchPressedControl?.removeAttribute("data-touch-pressed");
+        this.#touchPressedControl = null;
+        this.#touchPointerId = null;
+    };
+
     #icon = {
         close: `<svg id="play-backwards" width="24px" height="24px" viewBox="0 0 24 24" version="1.1" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><path d="M16,18.86V4.86l-11,7,11,7Z"/></svg>`,
         closed: `<svg id="skip-backward" width="24px" height="24px" viewBox="0 0 24 24" version="1.1" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><path d="M20,5V19L13,12M6,5V19H4V5M13,5V19L6,12"/></svg>`,
@@ -114,13 +162,13 @@ export default class OpeningAnimationMenu {
 
     /**
      * Internal helper to add a button to the menu.
-     * Sets button appearance and attaches the callback for user interaction.
+     * Sets visual/native disabled state and attaches the callback for native click/tap interaction.
      * @private
      * @param {string} name - Button identifier.
      * @param {string} imageSVG - SVG markup for the button icon.
-     * @param {boolean} enabled - Whether the button is enabled.
-     * @param {boolean} active - Whether the button is visually active.
-     * @param {boolean} visible - Whether the button is visible.
+     * @param {boolean} [enabled=true] - Whether the button is enabled when not active.
+     * @param {boolean} [active=false] - Whether the button is visually active and actionable.
+     * @param {boolean} [visible=true] - Whether the button is visible.
      * @param {function} callback - Callback to invoke on button click.
      * @returns {void}
      */
@@ -130,6 +178,7 @@ export default class OpeningAnimationMenu {
 
         const button = document.createElement("button");
         button.classList.add(stateClass, visibilityClass);
+        button.disabled = stateClass === "disabled";
         button.setAttribute("name", `button_animation_${name}`);
         button.innerHTML = imageSVG;
         button.addEventListener("click", (event) => {
@@ -217,7 +266,8 @@ export default class OpeningAnimationMenu {
     }
 
     /**
-     * Initializes and renders the menu UI, including buttons and slider.
+     * Initializes the selector, buttons and slider and subscribes once to owned touch feedback.
+     * Document completion and window blur listeners are released by dispose().
      * @private
      * @returns {void}
      */
@@ -239,6 +289,10 @@ export default class OpeningAnimationMenu {
         this.#createSelector();
         this.#createButtons();
         this.#createSlider();
+        this.#containerMain.addEventListener("pointerdown", this.#onTouchPress);
+        this.#containerMain.ownerDocument.addEventListener("pointerup", this.#onTouchRelease);
+        this.#containerMain.ownerDocument.addEventListener("pointercancel", this.#onTouchRelease);
+        this.#containerMain.ownerDocument.defaultView?.addEventListener("blur", this.#clearTouchPress);
     }
 
     /**
@@ -332,12 +386,12 @@ export default class OpeningAnimationMenu {
     }
 
     /**
-     * Updates the visual state of a button (enabled, active, visible).
+     * Updates visual/native disabled state and clears touch feedback if the control becomes disabled or hidden.
      * @private
      * @param {string} name - Button identifier.
-     * @param {boolean} enabled
-     * @param {boolean} active
-     * @param {boolean} visible
+     * @param {boolean} enabled - Whether an inactive control can be activated.
+     * @param {boolean} active - Whether the control has the active appearance and remains actionable.
+     * @param {boolean} [visible=true] - Whether to display the control.
      * @returns {void}
      */
     #setButtonState(name, enabled, active, visible = true) {
@@ -350,6 +404,10 @@ export default class OpeningAnimationMenu {
         const stateClass = active ? "active" : enabled ? "enabled" : "disabled";
         const visibilityClass = visible ? "visible" : "hidden";
         button.classList.add(stateClass, visibilityClass);
+        button.disabled = stateClass === "disabled";
+        if (this.#touchPressedControl === button && (button.disabled || !visible)) {
+            this.#clearTouchPress();
+        }
     }
 
     /**
@@ -398,15 +456,23 @@ export default class OpeningAnimationMenu {
      */
 
     /**
-     * Disposes the animation menu and releases all associated DOM resources.
+     * Releases touch/input listeners, owned press feedback and DOM resources.
+     * Document/window subscriptions are removed before detaching the menu; repeated disposal is safe.
      * @public
      * @returns {void}
      */
     dispose() {
-        this.#slider.removeEventListener("input", this.#handler.onSliderInput);
-        if (this.isVisible) {
-            this.#containerMain.remove();
+        if (!this.#containerMain) {
+            return;
         }
+        const document = this.#containerMain.ownerDocument;
+        this.#containerMain.removeEventListener("pointerdown", this.#onTouchPress);
+        document.removeEventListener("pointerup", this.#onTouchRelease);
+        document.removeEventListener("pointercancel", this.#onTouchRelease);
+        document.defaultView?.removeEventListener("blur", this.#clearTouchPress);
+        this.#clearTouchPress();
+        this.#slider.removeEventListener("input", this.#handler.onSliderInput);
+        this.#containerMain.remove();
         this.#containerMain = null;
         this.#containerButtons = null;
         this.#slider = null;

package/src/babylonjs-animation-opening.js

@@ -156,7 +156,7 @@ export default class OpeningAnimation {
     /**
      * Moves the animation to the fully opened state, optionally looping to close.
      * @private
-     * @param {boolean} useLoop - If true, starts closing animation after opening.
+     * @param {boolean} [useLoop=false] - If true, starts closing animation after opening.
      * @returns {void}
      */
     #goToOpened(useLoop = false) {
@@ -186,7 +186,7 @@ export default class OpeningAnimation {
     /**
      * Moves the animation to the fully closed state, optionally looping to open.
      * @private
-     * @param {boolean} useLoop - If true, starts opening animation after closing.
+     * @param {boolean} [useLoop=false] - If true, starts opening animation after closing.
      * @returns {void}
      */
     #goToClosed(useLoop = false) {
@@ -515,7 +515,7 @@ export default class OpeningAnimation {
      * Synchronizes slider and button states with animation.
      * @public
      * @param {HTMLCanvasElement} canvas - The canvas element for rendering.
-     * @param {Array<OpeningAnimation>} openingAnimations - Array of OpeningAnimation instances to manage.
+     * @param {Array<OpeningAnimation>} [openingAnimations=[]] - Array of OpeningAnimation instances to manage.
      * @returns {void}
      */
     showControls(canvas, openingAnimations = []) {

package/src/babylonjs-ar-floor-bounds.js

@@ -0,0 +1,169 @@
+/**
+ * Pure geometry for fitting an authored model footprint on a convex detected horizontal floor.
+ * Selects native horizontal-plane axes independently of conservative footprint contours. All coordinates are scene-space metres. Owns no XR resources and never rescales geometry.
+ */
+export default class BabylonJSARFloorBounds {
+    /**
+     * Validates a convex contour and returns consistently inward-facing edge constraints.
+     * @private
+     * @param {{x:number,z:number}[]} polygon - Ordered contour; either winding is accepted.
+     * @returns {?Array<{x:number,z:number,dx:number,dz:number,sign:number}>} Edges or null for invalid/concave contours.
+     */
+    static #edges(polygon) {
+        if (!Array.isArray(polygon) || polygon.length < 3
+            || polygon.some(p => !p || !Number.isFinite(p.x) || !Number.isFinite(p.z))) {
+            return null;
+        }
+        let area = 0;
+        for (let i = 0; i < polygon.length; i++) {
+            const a = polygon[i], b = polygon[(i + 1) % polygon.length];
+            area += a.x * b.z - a.z * b.x;
+        }
+        if (Math.abs(area) <= 1e-10) {
+            return null;
+        }
+        const sign = Math.sign(area), edges = [];
+        for (let i = 0; i < polygon.length; i++) {
+            const a = polygon[i], b = polygon[(i + 1) % polygon.length];
+            const dx = b.x - a.x, dz = b.z - a.z;
+            const length = Math.hypot(dx, dz);
+            if (length <= 1e-10) {
+                continue;
+            }
+            const edge = { x: a.x, z: a.z, dx: dx / length, dz: dz / length, sign };
+            if (polygon.some(p => sign * (edge.dx * (p.z - a.z) - edge.dz * (p.x - a.x)) < -1e-7)) {
+                return null;
+            }
+            edges.push(edge);
+        }
+        return edges.length >= 3 ? edges : null;
+    }
+
+    /**
+     * Reads native horizontal contours containing an accepted floor hit in the active reference space.
+     * Returns matching contour yaws plus a separately selected orientation when a finite camera height is supplied.
+     * Prefer a matching contour; otherwise use the horizontal pose below the camera closest in height to the hit.
+     * Pose-only alignment never relaxes contour height/containment/convexity checks or claims a physical footprint fit.
+     * Footprint contours require vertices at the observed height (five-centimetre tracking tolerance).
+     * @param {XRFrame} frame - Active frame; plane data may be unavailable when the optional feature is unsupported.
+     * @param {XRReferenceSpace} referenceSpace - Reference used for both the accepted hit and plane poses.
+     * @param {{x:number,y:number,z:number}} floorPoint - Accepted floor hit in scene-space metres.
+     * @param {boolean} [rightHanded=false] - Whether native negative-Z coordinates already match the scene.
+     * @param {?number} [viewerY=null] - Finite camera height enables independent native-pose alignment selection.
+     * @returns {{polygons:Array<Array<{x:number,z:number}>>,yaws:number[],alignment:?{yaw:number,planeHeight:number,heightDifference:number,status:string},status:string,planeCount:number}} Detached contours/alignment/status;
+     * unsupported access or failed plane queries never escape into the XR frame observer.
+     */
+    static getFloorPolygons(frame, referenceSpace, floorPoint, rightHanded = false, viewerY = null) {
+        let planes;
+        try {
+            planes = frame.detectedPlanes;
+        } catch {
+            return { polygons: [], yaws: [], alignment: null, status: "bounds-unavailable", planeCount: 0 };
+        }
+        if (!planes) {
+            return { polygons: [], yaws: [], alignment: null, status: "bounds-unavailable", planeCount: 0 };
+        }
+        const polygons = [];
+        const yaws = [];
+        let alignment = null;
+        let matchedAlignment = null;
+        let nearestDistance = Infinity;
+        let planeCount = 0;
+        for (const plane of planes) {
+            planeCount++;
+            try {
+                if (plane.orientation && plane.orientation !== "horizontal") {
+                    continue;
+                }
+                const pose = frame.getPose(plane.planeSpace, referenceSpace);
+                const matrix = pose?.transform?.matrix;
+                if (!matrix || matrix.length !== 16 || !Array.from(matrix).every(Number.isFinite)
+                    || Math.abs(matrix[5]) < 0.95 || Math.hypot(matrix[0], matrix[2]) <= 1e-6) {
+                    continue;
+                }
+                const yaw = Math.atan2(rightHanded ? -matrix[2] : matrix[2], matrix[0]);
+                const heightDifference = Math.abs(matrix[13] - floorPoint.y);
+                const distance = Math.hypot(matrix[12] - floorPoint.x, (rightHanded ? matrix[14] : -matrix[14]) - floorPoint.z);
+                const eligible = Number.isFinite(viewerY) && matrix[13] < viewerY;
+                const candidate = { yaw, planeHeight: matrix[13], heightDifference, status: "nearest-horizontal-plane" };
+                if (eligible && (!alignment || heightDifference < alignment.heightDifference - 1e-6
+                    || (Math.abs(heightDifference - alignment.heightDifference) <= 1e-6 && distance < nearestDistance))) {
+                    alignment = candidate;
+                    nearestDistance = distance;
+                }
+                const polygon = [];
+                for (const point of plane.polygon) {
+                    const x = matrix[0] * point.x + matrix[4] * point.y + matrix[8] * point.z + matrix[12];
+                    const y = matrix[1] * point.x + matrix[5] * point.y + matrix[9] * point.z + matrix[13];
+                    const z = matrix[2] * point.x + matrix[6] * point.y + matrix[10] * point.z + matrix[14];
+                    if (!Number.isFinite(y) || Math.abs(y - floorPoint.y) > 0.05) {
+                        polygon.length = 0;
+                        break;
+                    }
+                    polygon.push({ x, z: rightHanded ? z : -z });
+                }
+                if (this.contains(polygon, floorPoint)) {
+                    polygons.push(polygon);
+                    yaws.push(yaw);
+                    if (eligible && !matchedAlignment) {
+                        matchedAlignment = { ...candidate, status: "matched-contour" };
+                    }
+                }
+            } catch {
+                // A disappearing/invalid plane must not interrupt the native frame pump.
+                continue;
+            }
+        }
+        return { polygons, yaws, alignment: matchedAlignment ?? alignment, status: polygons.length ? "bounds-ready" : "waiting-floor-contour", planeCount };
+    }
+
+    /**
+     * Checks whether a finite point lies on or inside a valid convex contour.
+     * @param {{x:number,z:number}[]} polygon - Ordered floor contour in scene coordinates.
+     * @param {{x:number,z:number}} point - Point to test against every edge.
+     * @returns {boolean} False for unavailable/invalid contours or points.
+     */
+    static contains(polygon, point) {
+        const edges = this.#edges(polygon);
+        return !!edges && !!point && Number.isFinite(point.x) && Number.isFinite(point.z)
+            && edges.every(e => e.sign * (e.dx * (point.z - e.z) - e.dz * (point.x - e.x)) >= -1e-7);
+    }
+
+    /**
+     * Clips a front-facing centre line against every contour edge for every footprint corner.
+     * Chooses the farthest feasible centre up to the preferred distance, including exactly that distance when it fits.
+     * @param {{x:number,z:number}[]} polygon - Convex detected floor contour, in either winding.
+     * @param {{x:number,z:number}[]} footprint - Rotated footprint offsets relative to the model bottom centre.
+     * @param {{x:number,z:number}} origin - Tracked camera horizontal position.
+     * @param {{x:number,z:number}} forward - Unit horizontal facing direction.
+     * @param {number} [preferredDistance=3] - Maximum requested initial centre distance in metres.
+     * @returns {?number} Feasible centre distance, or null when no full-footprint fit exists on that segment.
+     */
+    static getPlacementDistance(polygon, footprint, origin, forward, preferredDistance = 3) {
+        const edges = this.#edges(polygon);
+        if (!edges || !Array.isArray(footprint) || !footprint.length
+            || ![origin?.x, origin?.z, forward?.x, forward?.z, preferredDistance].every(Number.isFinite)
+            || preferredDistance < 0 || Math.abs(Math.hypot(forward.x, forward.z) - 1) > 1e-6
+            || footprint.some(p => !p || !Number.isFinite(p.x) || !Number.isFinite(p.z))) {
+            return null;
+        }
+        let near = 0, far = preferredDistance;
+        for (const edge of edges) {
+            const slope = edge.sign * (edge.dx * forward.z - edge.dz * forward.x);
+            for (const corner of footprint) {
+                const offset = edge.sign * (edge.dx * (origin.z + corner.z - edge.z)
+                    - edge.dz * (origin.x + corner.x - edge.x));
+                if (Math.abs(slope) <= 1e-10) {
+                    if (offset < -1e-7) {
+                        return null;
+                    }
+                } else if (slope > 0) {
+                    near = Math.max(near, -offset / slope);
+                } else {
+                    far = Math.min(far, -offset / slope);
+                }
+            }
+        }
+        return far >= near - 1e-7 && far >= 0 ? Math.max(0, far) : null;
+    }
+}