beckhoff-xts-viewer-3d 5.2.2 → 5.3.0

package/dist/index.d.ts

@@ -12,7 +12,7 @@ import { GLTF } from 'three-stdlib';
  * Run `npm run sync-version` (or any script that depends on it) to refresh
  * after bumping the package version.
  */
-declare const VERSION: "5.2.2";
+declare const VERSION: "5.3.0";
 
 /**
  * Default CDN URL for the GLB asset bundle (`beckhoff-xts-viewer-3d-assets`).
@@ -32,7 +32,7 @@ declare const VERSION: "5.2.2";
  * build time so every install streams from a known-compatible GLB
  * release.
  */
-declare const JSDELIVR_ASSETS_BASE_URL: "https://cdn.jsdelivr.net/npm/beckhoff-xts-viewer-3d-assets@2.0.1/models";
+declare const JSDELIVR_ASSETS_BASE_URL: "https://cdn.jsdelivr.net/npm/beckhoff-xts-viewer-3d-assets@2.1.0/models";
 
 /**
  * Catalogue taxonomy — the string unions naming every module, mover, tool and
@@ -44,7 +44,7 @@ declare const JSDELIVR_ASSETS_BASE_URL: "https://cdn.jsdelivr.net/npm/beckhoff-x
  * public type surface. Nothing here imports anything.
  */
 /** Beckhoff XTS module types supported by the 3D viewer. */
-type ModuleType3D = 'AT2000_0250' | 'AT2001_0250' | 'AT2002_0250' | 'AT2002_0249' | 'AT2002_0249_ZX2002_0001' | 'AT2000_0233' | 'AT2000_0249' | 'AT2100_0250' | 'AT2102_0250' | 'AT2020_0250' | 'AT2021_0250' | 'AT2025_0250' | 'AT2026_0250' | 'AT2040_0250' | 'AT2041_0250' | 'AT2042_0250' | 'AT2140_0250' | 'AT2050_0500' | 'AT2050_0501' | 'AT2050_0500_180' | 'AT2200_0500' | 'AT2202_0500' | 'ATH2000_0250' | 'ATH2001_0250' | 'ATH2002_0250' | 'ATH2020_0250' | 'ATH2040_0250' | 'ATH2041_0250' | 'ATH2042_0250' | 'ATH2050_0500' | 'ATH2050_0501' | 'ATH2050_0500_180';
+type ModuleType3D = 'AT2000_0250' | 'AT2001_0250' | 'AT2002_0250' | 'AT2002_0249' | 'AT2000_0233' | 'AT2000_0249' | 'AT2100_0250' | 'AT2102_0250' | 'AT2020_0250' | 'AT2021_0250' | 'AT2025_0250' | 'AT2026_0250' | 'AT2040_0250' | 'AT2041_0250' | 'AT2050_0500' | 'AT2050_0501' | 'AT2050_0500_180' | 'AT2200_0500' | 'AT2202_0500' | 'ATH2000_0250' | 'ATH2001_0250' | 'ATH2002_0250' | 'ATH2020_0250' | 'ATH2040_0250' | 'ATH2041_0250' | 'ATH2042_0250' | 'ATH2050_0500' | 'ATH2050_0501' | 'ATH2050_0500_180';
 /**
  * Rail system beneath the module. Only affects the visual mesh
  * (Beckhoff aluminium rail vs. Hepco GFX), not the path math.
@@ -65,7 +65,20 @@ type RailSystem = 'Beckhoff' | 'HepcoGfx';
  * The `_S25` carrier ships without a magnet plate; the `_C25/_C34/_M34/_M40`
  * variants include the Beckhoff magnet plate set (`7P`/`10P` = 7/10-pole).
  */
-type MoverType3D = 'AT9011_0050' | 'AT9011_0070' | 'AT9012_0050' | 'AT9014_0055' | 'AT9014_0070' | 'ATH9011_0075' | 'ATH9013_0075' | 'Hepco_GFX2_1TC_S25' | 'Hepco_GFX2_1TC_C25' | 'Hepco_GFX2_1TC_C34' | 'Hepco_GFX2_1TC_M34' | 'Hepco_GFX2_1TC_M34_7P' | 'Hepco_GFX2_FCC_C25' | 'Hepco_GFX2_FCC_M34' | 'Hepco_GFX2_FCC_M34_7P' | 'Hepco_GFX2_FCC_M34_10P' | 'Hepco_GFX2_FCC_M40_10P' | 'Custom';
+type MoverType3D = 'AT9014_0055' | 'AT9014_0070' | 'ATH9011_0075' | 'Hepco_GFX2_1TC_S25' | 'Hepco_GFX2_1TC_C25' | 'Hepco_GFX2_1TC_C34' | 'Hepco_GFX2_1TC_M34' | 'Hepco_GFX2_1TC_M34_7P' | 'Hepco_GFX2_FCC_C25' | 'Hepco_GFX2_FCC_M34' | 'Hepco_GFX2_FCC_M34_7P' | 'Hepco_GFX2_FCC_M34_10P' | 'Hepco_GFX2_FCC_M40_10P' | 'Custom';
+/**
+ * Beckhoff magnet plate sets — the part carrying the mover's magnets and,
+ * on the AT9001 family, the encoder flag ("Geberfahne").
+ *
+ * The digit after the dash is the pole count in base 16 (`0450` → 4,
+ * `0550` → 5, `0775` → 7, `0AA0` → 10), verified by counting magnets in each
+ * converted mesh rather than read off the part number. `ATH9001` is the
+ * hygienic family, whose rows are encapsulated in sealed stainless.
+ *
+ * Every set is symmetric about its own travel axis, so its GLB origin already
+ * sits on the magnet-plate centre that the mover frame is defined around.
+ */
+type MagnetPlateType3D = 'AT9001_0450' | 'AT9001_0550' | 'AT9001_0775' | 'AT9001_0AA0' | 'ATH9001_0550' | 'ATH9001_0550_0001' | 'ATH9001_0AA0';
 /** Predefined mover-tool / carrier-plate types. */
 type MoverToolType3D = 'AT8200_1000_0100' | 'AT8200_2000_0100' | 'Custom';
 /**
@@ -73,17 +86,23 @@ type MoverToolType3D = 'AT8200_1000_0100' | 'AT8200_2000_0100' | 'Custom';
  * when `RailSystem === 'Beckhoff'` to visualise the outer guide
  * profile that the mover wheels engage.
  *
- * Curve sign drives the selection (see `MODULE_GUIDING_RAIL_MAP`):
+ * Curve sign drives the selection, and on curves so does the mover — see
+ * `resolveGuidingRailType`:
  *   - Straights: AT9000_0249 / AT9000_0250 / AT9000_0500
  *   - +22.5° curve: AT9020_1250
  *   - −22.5° curve: AT9025_1466
  *   - 45° curve:    AT9040_0750
  *   - 180° clothoid (entire AT2050 500 mm path): AT9050_0500
  *
+ * Beckhoff builds the curve rails per mover: the unsuffixed types above are
+ * the `-0055` order variants, made for the AT9014-0055, and the `_0170` ones
+ * are the `-0170` variants for the wider AT9014-0070. The straights carry no
+ * such variant — one AT9000 profile serves every mover.
+ *
  * Hygienic ATH modules ship with their guide profile baked into the module
  * GLB and therefore do NOT receive a separate guiding-rail mesh.
  */
-type RailType3D = 'AT9000_0249' | 'AT9000_0250' | 'AT9000_0500' | 'AT9020_1250' | 'AT9025_1466' | 'AT9040_0750' | 'AT9050_0500';
+type RailType3D = 'AT9000_0249' | 'AT9000_0250' | 'AT9000_0500' | 'AT9020_1250' | 'AT9020_1250_0170' | 'AT9025_1466' | 'AT9025_1466_0170' | 'AT9040_0750' | 'AT9050_0500' | 'AT9050_0500_0170';
 
 /**
  * Scalar tuples shared by every other type module.
@@ -330,8 +349,13 @@ interface MoverIdLabelOptions {
      */
     offsetMm?: Vec3;
     /**
-     * URL of a TTF / OTF / WOFF font, passed straight to troika-three-text.
-     * Default: `DEFAULT_LABEL_FONT_URL` (Roboto Condensed via jsDelivr).
+     * URL of a TTF / OTF / WOFF font for the label.
+     *
+     * Default: the viewer's built-in Roboto Condensed, compiled into the
+     * bundle and served from a blob URL — no request, and nothing that can
+     * fail. A custom URL is fetched once and shared by every label; until
+     * it answers, and permanently if it never does, labels render in the
+     * built-in font and the failure is reported once via `console.warn`.
      */
     fontUrl?: string;
     /** Outline thickness in mm. 0 disables the outline. Default: 0. */
@@ -675,6 +699,20 @@ interface ProcessingUnitConfig {
      */
     objectId: number;
     moverType: MoverType3D;
+    /**
+     * Magnet plate set attached to the carriage.
+     *
+     * Only meaningful for a mover whose GLB ships bare — today just
+     * `Hepco_GFX2_1TC_S25`. Every other mover models its plate already
+     * (see `MOVER_INTEGRATED_PLATE`) and ignores this, so setting it there
+     * cannot double-plate the mover. Defaults to `AT9001_0550`, the 5-pole set
+     * the equivalent `_C25` carriage ships with.
+     *
+     * Deliberately per processing unit rather than per mover: `moverType` is
+     * too, and a plate that varied between movers would force every one of them
+     * to claim its own scene node, disabling the instanced render path.
+     */
+    magnetPlateType?: MagnetPlateType3D;
     customMoverLayout?: CustomMoverLayout;
     /** Default: 'Beckhoff'. */
     railSystem?: RailSystem;
@@ -1090,6 +1128,7 @@ interface AssetManifest {
     modules?: Partial<Record<ModuleType3D, ModuleAssetEntry>>;
     movers?: Partial<Record<MoverType3D, MoverAssetEntry>>;
     tools?: Partial<Record<MoverToolType3D, MoverToolAssetEntry>>;
+    magnetPlates?: Partial<Record<MagnetPlateType3D, MagnetPlateAssetEntry>>;
     guidingRails?: Partial<Record<RailType3D, RailAssetEntry>>;
 }
 interface RailAssetEntry {
@@ -1112,6 +1151,10 @@ interface MoverToolAssetEntry {
     glbUrl: string;
     sidecarUrl?: string;
 }
+interface MagnetPlateAssetEntry {
+    glbUrl: string;
+    sidecarUrl?: string;
+}
 
 /**
  * Public types for the measurement + annotation feature.
@@ -1420,6 +1463,243 @@ interface XtsRuntimeState {
     display?: Partial<DisplayOptions>;
 }
 
+/**
+ * SidecarLoader — fetches per-asset JSON sidecars.
+ *
+ * Sidecars carry origin-correction (translateMm + rotationDegEuler) plus
+ * path metadata. They live next to the GLB at <baseUrl>/<id>.meta.json (or
+ * <id>.tool.meta.json for mover tools).
+ *
+ * On 404 the loader falls back to default origin-correction `(0,0,0)` /
+ * `(0,0,0)`. The renderer can still place the GLB; the calibration tool is
+ * the authoritative source for sidecar values.
+ */
+
+interface OriginCorrection {
+    translateMm: Vec3;
+    rotationDegEuler: Vec3;
+}
+interface ModuleSidecar {
+    moduleType: ModuleType3D;
+    glbByRailSystem: {
+        Beckhoff: string | null;
+        HepcoGfx?: string | null;
+    };
+    originCorrection: OriginCorrection;
+    pathType: 'Straight' | 'Curve' | 'Free';
+    moduleLengthMm: number;
+    endAngleDeg: number;
+    freePathFile?: string;
+    approximateBoundsMm?: {
+        min: Vec3;
+        max: Vec3;
+    };
+}
+interface MoverSidecar {
+    moverType: MoverType3D;
+    glb: string;
+    originCorrection: OriginCorrection;
+    magnetPlateCenterMm: Vec3;
+    pathLengthMm: number;
+}
+/**
+ * Calibration sidecar for a standalone magnet plate set. The plate is drawn
+ * in the mover-local frame (+X travel, +Z up) with this correction applied,
+ * so `originCorrection` is what seats it on the carriage.
+ */
+interface MagnetPlateSidecar {
+    plateType: MagnetPlateType3D;
+    glb: string;
+    originCorrection: OriginCorrection;
+    poleCount: number;
+    lengthMm: number;
+}
+interface MoverToolSidecar {
+    toolType: MoverToolType3D;
+    glbUrl: string;
+    originCorrection: OriginCorrection;
+    defaultOffsetMm: Vec3;
+    approximateBoundsMm?: {
+        min: Vec3;
+        max: Vec3;
+    };
+    label: string;
+}
+/**
+ * Calibration sidecar for a guiding-rail GLB. The rail is rendered in the
+ * same module-local frame as the module (i.e. under the module's
+ * `startWorldPose`) with this correction applied to the GLB scene.
+ */
+interface RailSidecar {
+    railType: RailType3D;
+    glb: string;
+    originCorrection: OriginCorrection;
+    approximateBoundsMm?: {
+        min: Vec3;
+        max: Vec3;
+    };
+}
+declare const DEFAULT_ORIGIN_CORRECTION: OriginCorrection;
+/**
+ * Generic sidecar fetch with promise caching + graceful fallback. Returns
+ * `undefined` on 404 (caller substitutes a default), and surfaces network or
+ * parse errors as `Error` (caller is expected to forward to onError).
+ */
+declare class SidecarLoader {
+    private readonly timeoutMs;
+    private readonly cache;
+    constructor(timeoutMs?: number);
+    clear(): void;
+    /**
+     * Fetch and cache the sidecar at `url`. The loader validates the one field
+     * every sidecar shape shares (`originCorrection`) and hands the rest to the
+     * caller as `T` — the kind is a property of the URL, not of the loader.
+     */
+    fetch<T>(url: string): Promise<T | undefined>;
+}
+/**
+ * Resolve the effective origin correction for a module sidecar — falls back
+ * to identity when the sidecar is absent.
+ */
+declare function resolveOriginCorrection(sidecar: {
+    originCorrection?: OriginCorrection;
+} | undefined): OriginCorrection;
+/** Standard sidecar filename from a base id. */
+declare function moduleSidecarFilename(moduleType: ModuleType3D): string;
+declare function moverSidecarFilename(moverType: MoverType3D): string;
+declare function toolSidecarFilename(toolType: MoverToolType3D): string;
+declare function railSidecarFilename(railType: RailType3D): string;
+/** Anything that names a GLB per rail system — a sidecar or a manifest entry. */
+interface GlbByRailSystem {
+    glbByRailSystem: {
+        Beckhoff: string | null;
+        HepcoGfx?: string | null;
+    };
+}
+/**
+ * Pure helper: pick the GLB filename with rail-system fallback. Returns null
+ * when the entry marks the module 'prepared but not delivered'.
+ *
+ * Takes the structural shape rather than `ModuleSidecar` so
+ * `resolveModuleGlbUrl`, which used to carry a line-for-line identical copy
+ * of this body over manifest entries, can delegate here. Both are public
+ * API, so both stay — but there is one implementation of the fallback rule.
+ */
+declare function pickGlbForRail(entry: GlbByRailSystem | undefined, rail: RailSystem): string | null;
+
+/**
+ * Option shapes shared between the public `<XtsViewer3D>` props and the
+ * internal `<XtsScene>` / `<ProcessingUnitRoot>` props.
+ *
+ * Each of these used to be declared twice — once on each side of that
+ * boundary, character for character — so the two could drift silently, and
+ * `SidecarOverrides` was even exported under two public names. Declared once
+ * here and imported by both.
+ */
+
+/** Where the orientation gizmo sits in the canvas. */
+type ViewCubeAlignment = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center' | 'center-left' | 'center-right' | 'center-center';
+/**
+ * The corner navigation gizmo: three labelled X / Y / Z axis handles that
+ * track the camera and snap it onto an axis when clicked.
+ *
+ * Named `ViewCube*` for backwards compatibility — earlier versions drew a
+ * navigation cube in the same spot.
+ */
+interface ViewCubeOptions {
+    enabled?: boolean;
+    /** Default `'bottom-right'`. */
+    alignment?: ViewCubeAlignment;
+    /** Distance from the aligned corner, in CSS px. Default `[80, 80]`. */
+    marginPx?: [number, number];
+}
+/**
+ * Keyboard navigation — moving the camera *through* the scene rather than
+ * orbiting it around a fixed point.
+ *
+ * The arrow keys (and the WASD block) walk the camera and the orbit pivot
+ * together along the ground plane, PageUp / PageDown climb, Shift goes
+ * faster and Alt finer. Keys are read from the canvas once it has focus,
+ * which it takes on pointer-down, so an embedded viewer never swallows the
+ * host page's arrow keys.
+ *
+ * Off automatically while `lock.pan` is set — moving through the scene is
+ * panning by another input device.
+ */
+interface KeyboardNavigationOptions {
+    /** Default `true`. */
+    enabled?: boolean;
+    /**
+     * Multiplier on the default travel rate, which is ~0.6 × the current
+     * orbit distance per second. Default `1`.
+     */
+    speed?: number;
+}
+/** Interaction locks. Each `true` disables that interaction. */
+interface InteractionLocks {
+    rotate?: boolean;
+    pan?: boolean;
+    zoom?: boolean;
+    selection?: boolean;
+}
+interface PerformanceOptions {
+    /** Cap the frameloop rate. Unset = uncapped. */
+    maxFps?: number;
+    /**
+     * Draw a processing unit's movers as one `InstancedMesh` instead of one
+     * scene node each, cutting mover draw calls from N to 1. Default: false.
+     *
+     * Applies from four movers up, and only to movers with nothing bound to
+     * them: a mover carrying tools, a mover-bound custom asset, or a visible
+     * drive status still gets its own node. Turning on the anchor marker or
+     * mover-id labels gives every mover a child object, so the batch is
+     * skipped for that unit entirely. Selection and clicks work either way.
+     */
+    instancing?: boolean;
+    /** Stop the frameloop while the tab is hidden. Default: true. */
+    autoPauseOnHidden?: boolean;
+    /**
+     * Enable demand rendering: frames only render when something changes
+     * (camera move, mover position update, selection). Saves >90% GPU time
+     * when the scene is idle. Default: true.
+     */
+    demandRendering?: boolean;
+    /**
+     * Cap the device pixel ratio. Values above 2 rarely improve perceptible
+     * quality but double fill-rate cost on Retina/4K displays. Default: 2.
+     */
+    maxDpr?: number;
+    /**
+     * Disable automatic per-frame shadow map updates. Shadows only re-render
+     * on camera change. Default: true (when shadows enabled).
+     */
+    shadowOnDemand?: boolean;
+    /**
+     * Opt into the WebGPU renderer when the browser supports it. Falls back to
+     * WebGL automatically. Default: false (experimental).
+     */
+    webgpu?: boolean;
+    /**
+     * Override the KTX2 (Basis) transcoder path used to decode compressed
+     * textures in the GLB assets. Defaults to a CDN copy pinned to the bundled
+     * three.js revision. Point this at a self-hosted
+     * `basis_transcoder.{js,wasm}` directory for offline / air-gapped use.
+     */
+    ktx2TranscoderUrl?: string;
+}
+/**
+ * Live override of the per-asset origin-correction sidecars, keyed by asset
+ * type. Useful for calibration tooling that adjusts a model's origin without
+ * re-publishing its `.meta.json`.
+ */
+interface SidecarOverrides {
+    modules?: Partial<Record<ModuleType3D, OriginCorrection>>;
+    movers?: Partial<Record<MoverType3D, OriginCorrection>>;
+    tools?: Partial<Record<MoverToolType3D, OriginCorrection>>;
+    magnetPlates?: Partial<Record<MagnetPlateType3D, OriginCorrection>>;
+    rails?: Partial<Record<RailType3D, OriginCorrection>>;
+}
+
 /**
  * Module catalog (3D-canonical).
  *
@@ -1556,6 +1836,67 @@ declare function moverWorldAt(chain: BuiltChain, partPositionMm: number): Planar
 /** Convenience: chain from full ModuleEntry[] returning trackLength alone. */
 declare function trackLengthOf(modules: ReadonlyArray<ModuleEntry>): number;
 
+/**
+ * normalizeXtsConfig — pre-render pass.
+ *
+ * Fail-fast validation + AT2050 half-clothoid merging:
+ *   AT2050_0500 + AT2050_0501 (gap=0)        → AT2050_0500_180
+ *   ATH2050_0500 + ATH2050_0501 (gap=0)      → ATH2050_0500_180
+ *
+ * Errors thrown via XtsViewerErrorException:
+ *   - 'unknown-module-type'
+ *   - 'unknown-mover-type'
+ *   - 'unmatched-clothoid-half'   (0500 without 0501 or vice versa)
+ *
+ * Warnings (collected, non-fatal) returned alongside the normalized config:
+ *   - mover.partOid not in part-list
+ *   - duplicate mover.id within an XPU
+ *   - mover.partPositionMm out of range (clamped)
+ */
+
+interface NormalizedXtsConfig extends XtsConfig {
+    /**
+     * Same shape as the input, with all parts' modules pre-merged + validated.
+     * Mover positions are clamped, but the original values are preserved in
+     * `__warnings` for diagnostics.
+     */
+    readonly __warnings: NormalizationWarning[];
+}
+interface NormalizationWarning {
+    code: 'mover-out-of-range' | 'mover-orphan' | 'mover-duplicate-id' | 'mover-missing-id' | 'mover-invalid-id' | 'empty-part' | 'prepared-module' | 'duplicate-xpu-object-id' | 'missing-xpu-object-id' | 'invalid-xpu-object-id' | 'duplicate-part-object-id' | 'missing-part-object-id' | 'invalid-part-object-id' | 'duplicate-part-global-number' | 'missing-part-global-number' | 'invalid-part-global-number' | 'duplicate-module-global-number' | 'missing-module-global-number' | 'invalid-module-global-number';
+    message: string;
+    details?: unknown;
+}
+/**
+ * Normalizer handle.
+ *
+ * This used to carry a single-slot structural cache keyed on a
+ * `JSON.stringify` of the config with the frame-paced fields stripped out.
+ * It was removed: the only production caller is `useNormalizedConfig`, whose
+ * `useMemo` already collapses repeat calls on an unchanged config, so the
+ * cache could fire only when the config identity changed but its structure
+ * did not — and in exactly that case the "fast path" cost a full stringify
+ * of the config plus a full rebuild of every XPU, which is strictly more
+ * work than the single O(n) pass it was avoiding.
+ *
+ * It also cost correctness twice over. The key stripped `status` by name at
+ * every depth, so it removed `ModuleEntry.status` along with the mover field
+ * it was aimed at, while the clone path rebuilt only movers — freezing
+ * declarative module warnings after the first normalize. And it forced a
+ * second copy of the mover clamp that had already drifted from `clampMover`
+ * (different `details` key, different `original` value), so hosts parsing
+ * warning details saw two shapes for one warning code.
+ *
+ * The class stays because it is part of the published API. It is now a thin
+ * handle over the pure function.
+ */
+declare class XtsConfigNormalizer {
+    normalize(config: XtsConfig): NormalizedXtsConfig;
+    /** No-op. Kept so existing callers keep compiling; there is no cache. */
+    clearCache(): void;
+}
+declare function normalizeXtsConfig(config: XtsConfig): NormalizedXtsConfig;
+
 /**
  * Mover collision detection.
  *
@@ -1665,6 +2006,20 @@ interface MoverProbe {
  * appear first.
  */
 declare function checkSamePathCollisions(chain: BuiltChain, partOid: number, probes: ReadonlyArray<MoverProbe>, opts?: CheckMoverCollisionsOptions): MoverCollision[];
+/**
+ * Collision check across a whole config: build a probe per mover, group by
+ * part, and run `checkSamePathCollisions` on each group with two or more.
+ *
+ * `livePositionOf` supplies the current position of a mover when one is
+ * being driven imperatively — the `MoverPositionStore` at 60 Hz — falling
+ * back to the config value. Passing it as a function rather than the store
+ * itself is what keeps this a pure geometry function: it was previously
+ * trapped inside the `useImperativeHandle` closure of `useXtsViewerHandle`,
+ * where it could only be exercised through a mounted canvas.
+ *
+ * Results are sorted so the deepest collision in the scene comes first.
+ */
+declare function checkAllMoverCollisions(config: NormalizedXtsConfig, livePositionOf: (moverId: number) => number | undefined, opts?: CheckMoverCollisionsOptions): MoverCollision[];
 
 /**
  * Module collision / overlap detection.
@@ -1700,12 +2055,17 @@ declare function checkSamePathCollisions(chain: BuiltChain, partOid: number, pro
  * are excluded; everything else (cross-part, cross-XPU, same-part
  * non-adjacent) is tested.
  *
- * The box cross-section (`halfWidthMm` 50, `heightMm` 100) is a coarse but
- * deterministic, asset-independent envelope. Real per-module CAD bounds live
- * in the GLB sidecars (`approximateBoundsMm`) and could refine it later.
- * Likewise the `warningGapMm` near-miss is an axis-projected SAT separation,
- * not a true Euclidean (GJK) distance — slightly conservative for
- * corner-to-corner cases.
+ * The box height comes from the module's own GLB sidecar
+ * (`moduleHeightSpan`, moduleCrossSection.ts): a motor module measures about
+ * 40 mm and straddles the path plane. It used to be one coarse box per type,
+ * `0 … 100` mm and entirely above the plane, which reported an overlap between
+ * any two tracks stacked closer than 100 mm — the arrangement a doublesided
+ * guide rail is built as. The half-width stays the coarse `halfWidthMm` 50,
+ * because a curved module's sidecar box spans its whole arc in X and Y and is
+ * a cross-section only in Z; moduleCrossSection.ts sets that out.
+ *
+ * The `warningGapMm` near-miss is an axis-projected SAT separation, not a true
+ * Euclidean (GJK) distance — slightly conservative for corner-to-corner cases.
  */
 
 /** Default box half-width (Y) — matches `approximateModuleBounds`. */
@@ -1752,7 +2112,16 @@ interface CheckModuleCollisionsOptions {
     includeSamePart?: boolean;
     /** Box half-width in Y (mm). Default 50. */
     halfWidthMm?: number;
-    /** Box height in Z (mm). Default 100. */
+    /**
+     * Force one box height in Z (mm), spanning `0 … heightMm` above the path
+     * plane for every module type.
+     *
+     * Left unset — the default — each module is given the vertical extent its
+     * GLB sidecar reports (`moduleHeightSpan`), which both is the real height
+     * and sits on the real side of the path plane. Setting this restores the one
+     * coarse box the check used before that, for a caller who wants a
+     * deliberately conservative envelope.
+     */
     heightMm?: number;
 }
 /** Oriented bounding box in world space (unit axes + scaled half-extents). */
@@ -1819,58 +2188,25 @@ declare function checkModuleCollisions(probes: ReadonlyArray<ModuleProbe>, adjac
     count: number;
     closed: boolean;
 }>, opts?: CheckModuleCollisionsOptions): ModuleCollision[];
-
 /**
- * normalizeXtsConfig — pre-render pass.
- *
- * Fail-fast validation + AT2050 half-clothoid merging:
- *   AT2050_0500 + AT2050_0501 (gap=0)        → AT2050_0500_180
- *   ATH2050_0500 + ATH2050_0501 (gap=0)      → ATH2050_0500_180
- *
- * Errors thrown via XtsViewerErrorException:
- *   - 'unknown-module-type'
- *   - 'unknown-mover-type'
- *   - 'unmatched-clothoid-half'   (0500 without 0501 or vice versa)
+ * Resolve a normalized config into the per-XPU inputs `buildModuleProbes`
+ * takes, applying the same override precedence the scene uses: an imperative
+ * `trackTransformOverrides` entry beats the config value.
  *
- * Warnings (collected, non-fatal) returned alongside the normalized config:
- *   - mover.partOid not in part-list
- *   - duplicate mover.id within an XPU
- *   - mover.partPositionMm out of range (clamped)
- */
-
-interface NormalizedXtsConfig extends XtsConfig {
-    /**
-     * Same shape as the input, with all parts' modules pre-merged + validated.
-     * Mover positions are clamped, but the original values are preserved in
-     * `__warnings` for diagnostics.
-     */
-    readonly __warnings: NormalizationWarning[];
-}
-interface NormalizationWarning {
-    code: 'mover-out-of-range' | 'mover-orphan' | 'mover-duplicate-id' | 'mover-missing-id' | 'mover-invalid-id' | 'empty-part' | 'prepared-module' | 'duplicate-xpu-object-id' | 'missing-xpu-object-id' | 'invalid-xpu-object-id' | 'duplicate-part-object-id' | 'missing-part-object-id' | 'invalid-part-object-id' | 'duplicate-module-global-number' | 'missing-module-global-number' | 'invalid-module-global-number';
-    message: string;
-    details?: unknown;
-}
-/**
- * Stateful normalizer with a single-slot structural cache. The key
- * intentionally excludes `mover.partPositionMm` so that frame-paced
- * position updates fall into the fast path: when the structure (modules,
- * parts, transforms, mover ids/partOids) hasn't changed between calls,
- * we return a clone of the cached result with only the mover positions
- * re-clamped against the current input.
+ * This adapter was written out twice, character for character — once in
+ * `<ModuleCollisionMonitor>` and once inside the `checkModuleCollisions`
+ * closure of `useXtsViewerHandle` — with the only difference being where the
+ * orientation came from.
  *
- * Construct your own instance when you need an isolated cache (e.g. in
- * tests, or when multiple viewers in the same JS realm would otherwise
- * thrash a shared single-slot cache). The standalone `normalizeXtsConfig`
- * function delegates to a process-wide singleton for backwards
- * compatibility.
+ * A part whose chain cannot be built is skipped, as before, but no longer in
+ * silence: `normalizeXtsConfig` has already made that impossible, so if it
+ * ever happens it means a part has silently dropped out of collision
+ * detection, which is a safety feature. Reported rather than thrown, because
+ * both callers run inside React and a throw would take the scene down.
  */
-declare class XtsConfigNormalizer {
-    private _cache;
-    normalize(config: XtsConfig): NormalizedXtsConfig;
-    clearCache(): void;
-}
-declare function normalizeXtsConfig(config: XtsConfig): NormalizedXtsConfig;
+declare function toModuleCollisionInputs(config: NormalizedXtsConfig, trackTransformOverrides?: Record<number, TrackTransform>): ModuleCollisionXpuInput[];
+/** `toModuleCollisionInputs` → `buildModuleProbes` → `checkModuleCollisions`. */
+declare function checkAllModuleCollisions(config: NormalizedXtsConfig, orientation: Orientation | undefined, trackTransformOverrides?: Record<number, TrackTransform>, opts?: CheckModuleCollisionsOptions): ModuleCollision[];
 
 /**
  * Shared, mostly-pure plumbing behind `exportScreenshot` and
@@ -1891,16 +2227,99 @@ declare function normalizeXtsConfig(config: XtsConfig): NormalizedXtsConfig;
  */
 
 type CaptureMode = 'current' | 'top-down' | 'custom';
-
 /**
- * captureScreenshot — render the live r3f scene into an offscreen
- * WebGLRenderTarget at any resolution, in any of three camera modes:
+ * The options `exportScreenshot` and `beginFrameCapture` share.
  *
- *   • 'current'  — clone the live camera at its current pose (image aspect
- *                  adjusted to the requested width/height). Handles both
- *                  the perspective view and the orthographic 2D plan view.
- *   • 'top-down' — orthographic camera placed above the scene's AABB
- *                  centre, looking straight down -Z, with up = world +Y.
+ * They used to be written out twice — `ScreenshotOptions` and
+ * `FrameCaptureOptions` each hand-documented the same nine fields, and the
+ * two `updateShadows` comments already described the same behaviour in
+ * different words. Documented once here; each path intersects this with the
+ * handful of options that are genuinely its own.
+ */
+interface CaptureRequest {
+    /** Camera mode. Default `'current'`. */
+    mode?: CaptureMode;
+    /** Required when `mode === 'custom'`. Ignored otherwise. */
+    camera?: CameraState;
+    /**
+     * Dimensions in pixels. Supply at least one; the other follows the scene
+     * aspect (`top-down`) or the live canvas aspect (`current` / `custom`).
+     * Omit both to use the live canvas dimensions x pixel ratio.
+     *
+     * Both are clamped to what the GPU can actually allocate — read
+     * `widthPx` / `heightPx` / `clamped` back for what was really rendered.
+     */
+    width?: number;
+    height?: number;
+    /**
+     * Background colour:
+     *   - `null` (default) → transparent frames, matching the live canvas
+     *     contract. JPEG falls back to white because it has no alpha.
+     *   - `'#RRGGBB'` / any three.js ColorRepresentation → solid fill.
+     */
+    backgroundColor?: ColorRepresentation | null;
+    /** Margin around the scene AABB in `top-down` mode. Default 1.1 (10 %). */
+    paddingFactor?: number;
+    /**
+     * Multiplier applied to every Light in the scene for the render, restored
+     * afterwards. The default differs per path: 1.35 for a still, which
+     * otherwise reads dim next to the live canvas, and 1 for a clip, where
+     * that boost would make the whole video brighter than the run the user
+     * watched. Pass 1 to disable.
+     */
+    exposureBoost?: number;
+    /**
+     * MSAA sample count for the offscreen target. Default 4 where the context
+     * supports it, 0 otherwise; 0 disables. The live canvas is created with
+     * `antialias: true`, so without this every geometry edge in an export is
+     * hard-aliased while the live view stays smooth. The effective count,
+     * clamped to the hardware maximum, is reported back.
+     */
+    samples?: number;
+    /**
+     * Refresh the shadow map before rendering. Default `true`.
+     *
+     * `performance.shadowOnDemand` leaves `shadowMap.autoUpdate` off and only
+     * dirties the map on camera change, so movers driven through
+     * `setMoverPositions` would otherwise cast shadows from a stale position.
+     * Costs one shadow pass; pass `false` to skip it.
+     */
+    updateShadows?: boolean;
+    /**
+     * Pin wall-clock animations (the drive-status blink) for the render.
+     * Default `true`.
+     *
+     * Unpinned, a capture catches whatever phase the last live frame left
+     * behind: two stills of the same scene differ, and a clip flickers at an
+     * irregular rate because its frames are not produced at wall-clock speed.
+     */
+    freezeAnimations?: boolean;
+}
+/** What a capture reports back about the frame it actually produced. */
+interface CaptureDimensions {
+    /** Dimensions actually rendered — after hardware / budget clamping. */
+    widthPx: number;
+    heightPx: number;
+    /** Dimensions requested, before clamping. */
+    requestedWidthPx: number;
+    requestedHeightPx: number;
+    /** True when the request exceeded what the GPU could allocate. */
+    clamped: boolean;
+    /** MSAA samples actually used (0 = off). */
+    samples: number;
+    /** Camera the frame was rendered with. */
+    camera: CameraState;
+}
+
+/**
+ * captureScreenshot — render the live r3f scene into an offscreen
+ * WebGLRenderTarget at any resolution, in any of three camera modes:
+ *
+ *   • 'current'  — clone the live camera at its current pose (image aspect
+ *                  adjusted to the requested width/height). Handles both
+ *                  the perspective view and the orthographic 2D plan view.
+ *   • 'top-down' — orthographic camera placed above the scene's AABB
+ *                  centre, looking straight down -Z, with up = world +Y.
  *                  Frustum sized to fit the AABB plus padding. Mirrors
  *                  the 2D viewer convention (path along image X,
  *                  encoder-side along image Y).
@@ -1931,79 +2350,26 @@ type CaptureMode = 'current' | 'top-down' | 'custom';
  *     background and boosted lights.
  */
 
-type ScreenshotMode = 'current' | 'top-down' | 'custom';
+/**
+ * @deprecated Use `CaptureMode`. This was a byte-for-byte re-declaration of
+ * it, so the package shipped two public names for one union.
+ */
+type ScreenshotMode = CaptureMode;
 type ScreenshotFormat = 'png' | 'jpeg' | 'webp';
-interface ScreenshotOptions {
-    /** Camera mode. Default: `'current'`. */
-    mode?: ScreenshotMode;
-    /** Required when `mode === 'custom'`. Ignored otherwise. */
-    camera?: CameraState;
-    /**
-     * Image dimensions in pixels.
-     * - Both supplied: the rendered frustum (top-down) is adjusted to
-     *   match the resulting aspect; the camera (current / custom) is
-     *   fitted to `width / height`.
-     * - One supplied: the other is derived to keep the scene's aspect
-     *   ratio (top-down) or the live canvas aspect (current / custom).
-     * - Neither: canvas CSS dimensions × `pixelRatio`.
-     *
-     * Both are clamped to what the GPU can actually allocate — check
-     * `widthPx` / `heightPx` / `clamped` on the result for what was
-     * really rendered.
-     */
-    width?: number;
-    height?: number;
+/**
+ * `CaptureRequest` carries the nine options shared with `beginFrameCapture`;
+ * these three are the still-image path's own.
+ */
+interface ScreenshotOptions extends CaptureRequest {
     format?: ScreenshotFormat;
     /** 0..1 — JPEG / WebP quality. Default 0.92. Ignored for PNG. */
     quality?: number;
     /**
-     * Padding factor around the scene AABB in `top-down` mode. Default
-     * 1.1 (10 % margin on each side). Higher = more whitespace.
-     */
-    paddingFactor?: number;
-    /**
-     * Background colour:
-     *   - `null` (default) → transparent PNG, matches the live canvas
-     *     contract. JPEG falls back to white because the format has no
-     *     alpha channel.
-     *   - `'#RRGGBB'` / any three.js ColorRepresentation → solid fill.
-     */
-    backgroundColor?: ColorRepresentation | null;
-    /**
-     * Pixel ratio for offscreen renders. Default = renderer's current
-     * pixel ratio (matches the live canvas sharpness on high-DPI
-     * displays). Set explicitly for fixed-resolution exports.
+     * Pixel ratio for the offscreen render. Default = the renderer's current
+     * pixel ratio, which matches live-canvas sharpness on high-DPI displays.
+     * Set explicitly for fixed-resolution exports.
      */
     pixelRatio?: number;
-    /**
-     * Multiplier applied to every Light in the scene during the offscreen
-     * render. Default 1.35 — screenshots tend to feel dim compared to
-     * the live canvas because the live tone-mapping pipeline picks up
-     * the surrounding monitor luminance, which the offscreen render
-     * doesn't. Pass 1 to disable, > 1 for a brighter result. Restored
-     * after capture.
-     */
-    exposureBoost?: number;
-    /**
-     * MSAA sample count for the offscreen target. Default 4 where the
-     * context supports it, 0 otherwise. 0 disables.
-     *
-     * The live canvas is created with `antialias: true`; without this the
-     * offscreen pass had no MSAA at all, so every geometry edge in an
-     * export was hard-aliased while the live view stayed smooth. The
-     * effective count (clamped to the hardware maximum) comes back on the
-     * result.
-     */
-    samples?: number;
-    /**
-     * Refresh the shadow map before rendering. Default `true`.
-     *
-     * `performance.shadowOnDemand` leaves `shadowMap.autoUpdate` off and
-     * only dirties the map when the camera moves, so movers driven purely
-     * through `setMoverPositions` would otherwise cast shadows from a
-     * stale position. Costs one shadow pass; pass `false` to skip it.
-     */
-    updateShadows?: boolean;
 }
 interface ScreenshotResult {
     blob: Blob;
@@ -2079,69 +2445,13 @@ interface ScreenshotResult {
  * `exportScreenshot` does.
  */
 
-interface FrameCaptureOptions {
-    /**
-     * Frame dimensions in px. Supply at least one; the other follows the scene
-     * aspect (`top-down`) or the live canvas aspect (`current` / `custom`).
-     * Omit both to use the live canvas dimensions × pixel ratio.
-     *
-     * Sessions tolerate a render size well above the live canvas — supersampling
-     * for the encoder is the expected usage. Both values are clamped to what the
-     * GPU can allocate; check `widthPx` / `heightPx` / `clamped` for what you
-     * actually get.
-     */
-    width?: number;
-    height?: number;
-    /** Camera mode. Default `'current'`. */
-    mode?: CaptureMode;
-    /** Required when `mode === 'custom'`. */
-    camera?: CameraState;
-    /** `null` (default) → transparent frames. */
-    backgroundColor?: ColorRepresentation | null;
-    /** Top-down margin. Fixed for the session. Default 1.1. */
-    paddingFactor?: number;
-    /**
-     * Light multiplier. Default **1** — unlike `exportScreenshot`, which uses
-     * 1.35 because a single still reads dim next to the live canvas. Applying
-     * that to every frame of a clip would make the whole video uniformly
-     * brighter than the run the user watched.
-     */
-    exposureBoost?: number;
-    /** MSAA samples. Default 4, clamped to the hardware maximum. 0 disables. */
-    samples?: number;
-    /**
-     * Pin wall-clock-driven effects (the drive-status blink) to a fixed value
-     * for every frame. Default `true`.
-     *
-     * Export frames are not produced at wall-clock speed, so an unpinned blink
-     * flickers at an irregular rate in the clip and two exports of the same run
-     * differ pixel-wise.
-     */
-    freezeAnimations?: boolean;
-    /**
-     * Refresh the shadow map on every frame. Default `true` when shadows are
-     * enabled.
-     *
-     * `performance.shadowOnDemand` leaves `shadowMap.autoUpdate` off and only
-     * dirties on camera change, so movers driven through `setMoverPositions`
-     * would drag their first-frame shadows through the whole clip. Costs one
-     * shadow pass per frame; set `false` to trade correctness for speed.
-     */
-    updateShadows?: boolean;
-}
-interface FrameCaptureSession {
-    /** Dimensions actually rendered — after hardware / budget clamping. */
-    readonly widthPx: number;
-    readonly heightPx: number;
-    /** Dimensions requested, before clamping. */
-    readonly requestedWidthPx: number;
-    readonly requestedHeightPx: number;
-    /** True when the request exceeded what the GPU could allocate. */
-    readonly clamped: boolean;
-    /** MSAA samples actually used (0 = off). */
-    readonly samples: number;
-    /** Camera pinned for the whole session. */
-    readonly camera: CameraState;
+/**
+ * `CaptureRequest` carries the nine options shared with `exportScreenshot`.
+ * The clip path adds nothing of its own; it only differs in the default for
+ * `exposureBoost` (1 rather than 1.35 — see the field's doc).
+ */
+type FrameCaptureOptions = CaptureRequest;
+interface FrameCaptureSession extends Readonly<CaptureDimensions> {
     /** True until `dispose()`. */
     readonly disposed: boolean;
     /**
@@ -2408,6 +2718,14 @@ interface XtsViewer3DRef {
     focusOn(target: FocusTarget, opts?: FocusOptions): void;
     setCamera(cam: CameraState): void;
     getCamera(): CameraState | null;
+    /**
+     * @deprecated Not implemented — this is a no-op that warns in development.
+     *
+     * `orientation` is a static prop in this build; there is no state behind
+     * it to update. Set it through `<XtsViewer3D orientation={…}>` instead.
+     * The method is kept only so the published interface does not change
+     * shape mid-major, and will be removed in the next major.
+     */
     setOrientation(orientation: XtsConfig['orientation']): void;
     getMoverWorldTransform(ref: MoverRef): {
         positionMm: [number, number, number];
@@ -2472,6 +2790,15 @@ interface XtsViewer3DRef {
      * frameloop tick.
      */
     renderFrameNow(): void;
+    /**
+     * @deprecated Not implemented — this is a no-op that warns in development.
+     *
+     * GLB caching lives in `useGLTF`'s global cache, which r3f exposes no
+     * per-instance handle to clear. Use `useGLTF.clear()` from
+     * `@react-three/drei` directly if you need to drop cached assets. Kept
+     * only so the published interface does not change shape mid-major, and
+     * will be removed in the next major.
+     */
     reloadAssets(): Promise<void>;
     setMoverPosition(moverId: number, partPositionMm: number): void;
     /**
@@ -2528,107 +2855,6 @@ interface XtsViewer3DRef {
     measurements: MeasurementApi;
 }
 
-/**
- * SidecarLoader — fetches per-asset JSON sidecars.
- *
- * Sidecars carry origin-correction (translateMm + rotationDegEuler) plus
- * path metadata. They live next to the GLB at <baseUrl>/<id>.meta.json (or
- * <id>.tool.meta.json for mover tools).
- *
- * On 404 the loader falls back to default origin-correction `(0,0,0)` /
- * `(0,0,0)`. The renderer can still place the GLB; the calibration tool is
- * the authoritative source for sidecar values.
- */
-
-interface OriginCorrection {
-    translateMm: Vec3;
-    rotationDegEuler: Vec3;
-}
-interface ModuleSidecar {
-    moduleType: ModuleType3D;
-    glbByRailSystem: {
-        Beckhoff: string | null;
-        HepcoGfx?: string | null;
-    };
-    originCorrection: OriginCorrection;
-    pathType: 'Straight' | 'Curve' | 'Free';
-    moduleLengthMm: number;
-    endAngleDeg: number;
-    freePathFile?: string;
-    approximateBoundsMm?: {
-        min: Vec3;
-        max: Vec3;
-    };
-}
-interface MoverSidecar {
-    moverType: MoverType3D;
-    glb: string;
-    originCorrection: OriginCorrection;
-    magnetPlateCenterMm: Vec3;
-    pathLengthMm: number;
-}
-interface MoverToolSidecar {
-    toolType: MoverToolType3D;
-    glbUrl: string;
-    originCorrection: OriginCorrection;
-    defaultOffsetMm: Vec3;
-    approximateBoundsMm?: {
-        min: Vec3;
-        max: Vec3;
-    };
-    label: string;
-}
-/**
- * Calibration sidecar for a guiding-rail GLB. The rail is rendered in the
- * same module-local frame as the module (i.e. under the module's
- * `startWorldPose`) with this correction applied to the GLB scene.
- */
-interface RailSidecar {
-    railType: RailType3D;
-    glb: string;
-    originCorrection: OriginCorrection;
-    approximateBoundsMm?: {
-        min: Vec3;
-        max: Vec3;
-    };
-}
-declare const DEFAULT_ORIGIN_CORRECTION: OriginCorrection;
-/**
- * Generic sidecar fetch with promise caching + graceful fallback. Returns
- * `undefined` on 404 (caller substitutes a default), and surfaces network or
- * parse errors as `Error` (caller is expected to forward to onError).
- */
-declare class SidecarLoader {
-    private readonly timeoutMs;
-    private readonly cache;
-    constructor(timeoutMs?: number);
-    clear(): void;
-    /**
-     * Fetch and cache the sidecar at `url`. The loader validates the one field
-     * every sidecar shape shares (`originCorrection`) and hands the rest to the
-     * caller as `T` — the kind is a property of the URL, not of the loader.
-     */
-    fetch<T>(url: string): Promise<T | undefined>;
-}
-/**
- * Resolve the effective origin correction for a module sidecar — falls back
- * to identity when the sidecar is absent.
- */
-declare function resolveOriginCorrection(sidecar: {
-    originCorrection?: OriginCorrection;
-} | undefined): OriginCorrection;
-/** Standard sidecar filename from a base id. */
-declare function moduleSidecarFilename(moduleType: ModuleType3D): string;
-declare function moverSidecarFilename(moverType: MoverType3D): string;
-declare function toolSidecarFilename(toolType: MoverToolType3D): string;
-declare function railSidecarFilename(railType: RailType3D): string;
-/**
- * Pure helper: pick the GLB filename for a moduleSidecar with rail-system
- * fallback. Returns null when the sidecar marks the module 'prepared but
- * not delivered'.
- */
-declare function pickGlbForRail(sidecar: ModuleSidecar | undefined, rail: RailSystem): string | null;
-
 /**
  * HepcoGfxRailProfile — cross-section of the Hepco GFX guiding rail used by
  * the procedural extrusion in <HepcoGfxRail>.
@@ -2756,12 +2982,6 @@ declare function createHepcoGfxRailShape(dims?: HepcoGfxRailProfileDims): Shape;
  * Live overrides for module/mover/tool origin-correction sidecars. Used by
  * the calibration tool to preview adjustments without writing files.
  */
-interface SidecarOverrides {
-    modules?: Partial<Record<ModuleType3D, OriginCorrection>>;
-    movers?: Partial<Record<MoverType3D, OriginCorrection>>;
-    tools?: Partial<Record<MoverToolType3D, OriginCorrection>>;
-    rails?: Partial<Record<RailType3D, OriginCorrection>>;
-}
 interface XtsViewer3DProps {
     /** Complete XTS configuration. */
     config: XtsConfig;
@@ -2806,12 +3026,15 @@ interface XtsViewer3DProps {
      */
     topDown?: boolean;
     /** Lock interactions. */
-    lock?: {
-        rotate?: boolean;
-        pan?: boolean;
-        zoom?: boolean;
-        selection?: boolean;
-    };
+    lock?: InteractionLocks;
+    /**
+     * Move the camera through the scene with the keyboard instead of only
+     * orbiting it: arrow keys / WASD walk along the ground plane, PageUp /
+     * PageDown climb, Shift is faster and Alt finer. On by default; the canvas
+     * takes focus on pointer-down, so the keys arm themselves on the first
+     * click into the viewer.
+     */
+    keyboardNavigation?: KeyboardNavigationOptions;
     /** Selection-Mode. Default: 'Off'. */
     selectionMode?: SelectionMode;
     /** Controlled selection. */
@@ -2896,40 +3119,7 @@ interface XtsViewer3DProps {
     onError?: (err: XtsViewerError) => void;
     onAssetsLoaded?: () => void;
     /** Performance-Tuning. */
-    performance?: {
-        maxFps?: number;
-        instancing?: boolean;
-        autoPauseOnHidden?: boolean;
-        /**
-         * Enable demand rendering: frames only render when something changes
-         * (camera move, mover position update, selection). Saves >90% GPU
-         * time when the scene is idle. Default: true.
-         */
-        demandRendering?: boolean;
-        /**
-         * Cap the device pixel ratio. Values above 2 rarely improve
-         * perceptible quality but double fill-rate cost on Retina/4K
-         * displays. Default: 2.
-         */
-        maxDpr?: number;
-        /**
-         * Disable automatic per-frame shadow map updates. Shadows only
-         * re-render on camera change. Default: true (when shadows enabled).
-         */
-        shadowOnDemand?: boolean;
-        /**
-         * Opt into the WebGPU renderer when the browser supports it.
-         * Falls back to WebGL automatically. Default: false (experimental).
-         */
-        webgpu?: boolean;
-        /**
-         * Override the KTX2 (Basis) transcoder path used to decode compressed
-         * textures in the GLB assets. Defaults to a CDN copy pinned to the
-         * bundled three.js revision. Point this at a self-hosted
-         * `basis_transcoder.{js,wasm}` directory for offline / air-gapped use.
-         */
-        ktx2TranscoderUrl?: string;
-    };
+    performance?: PerformanceOptions;
     /**
      * Live override of the per-asset origin-correction sidecars. Useful for
      * the calibration tool.
@@ -2946,11 +3136,7 @@ interface XtsViewer3DProps {
      */
     hepcoGfxProfile?: Partial<HepcoGfxRailProfileDims>;
     /** CAD-style ViewCube overlay. */
-    viewCube?: {
-        enabled?: boolean;
-        alignment?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center' | 'center-left' | 'center-right' | 'center-center';
-        marginPx?: [number, number];
-    };
+    viewCube?: ViewCubeOptions;
     /** Stator heatmap data — coloured tube along each part's centerline. */
     statorHeatmap?: StatorHeatmap;
     /** Continuous mover collision monitoring. */
@@ -3032,9 +3218,61 @@ interface MoverCatalogEntry {
     magnetPlateCenterMm: Vec3;
 }
 declare const MOVER_CATALOG: Readonly<Record<MoverType3D, MoverCatalogEntry>>;
+/**
+ * The magnet plate set already modelled into each mover's own GLB, or `null`
+ * for a carriage that ships bare and needs one attached.
+ *
+ * Nearly every mover asset is a combined carriage+plate assembly: the Beckhoff
+ * movers say so in the filename (`AT9014-0055-0550` carries an AT9001-0550),
+ * and each Hepco carriage records the plate it was ordered with in its
+ * sidecar's `_calibration.hepcoPartNumber` (`…_AT9001-0775` and friends).
+ * Attaching a second plate to one of those would draw a plate through a plate,
+ * so `<XtsMoverPlate>` renders only where this table says `null`.
+ *
+ * `Custom` is `null` because its geometry comes from `customMoverLayout`,
+ * which may or may not include a plate — the host decides.
+ *
+ * Exhaustive over `MoverType3D` on purpose (`Record`, not `Partial<Record>`):
+ * a new mover type has to state which it is, so it cannot silently end up
+ * double-plated or plate-less.
+ */
+declare const MOVER_INTEGRATED_PLATE: Readonly<Record<MoverType3D, MagnetPlateType3D | null>>;
 declare function getMoverEntry(moverType: MoverType3D): MoverCatalogEntry | undefined;
 declare function isKnownMoverType(value: string): value is MoverType3D;
 
+/**
+ * Magnet plate set catalog (3D-canonical).
+ *
+ * A plate set is the part that carries the mover's magnets. Most mover GLBs
+ * ship with one already modelled in (see `MOVER_INTEGRATED_PLATE`); these
+ * entries describe the sets that exist as assets of their own, so a bare
+ * carriage can be given any pole count without a new combined CAD assembly.
+ *
+ * `lengthMm` is the plate's extent along the travel axis, measured from the
+ * converted GLB rather than inferred from the part number. Pole count was
+ * likewise counted in the mesh: each magnet is 7.7 mm wide and sits in a row
+ * just proud of its backing plate, so the magnets separate cleanly along the
+ * travel axis. That count is what establishes the part-number rule (the digit
+ * after the dash is the pole count in base 16) — it is not assumed from it.
+ */
+
+interface MagnetPlateCatalogEntry {
+    plateType: MagnetPlateType3D;
+    /** Magnets in one row, i.e. the pole count the part number encodes. */
+    poleCount: number;
+    /** Plate extent along the travel axis, mm (GLB-measured). */
+    lengthMm: number;
+    /**
+     * Whether the set models the encoder flag ("Geberfahne"). The AT9001 sets
+     * all carry it as a thin sheet reaching back along −Z; the hygienic ATH9001
+     * sets encapsulate their rows in sealed stainless and model none.
+     */
+    hasEncoderFlag: boolean;
+}
+declare const MAGNET_PLATE_CATALOG: Readonly<Record<MagnetPlateType3D, MagnetPlateCatalogEntry>>;
+declare function getMagnetPlateEntry(plateType: MagnetPlateType3D): MagnetPlateCatalogEntry | undefined;
+declare function isKnownMagnetPlateType(value: unknown): value is MagnetPlateType3D;
+
 /**
  * Module-local path math.
  *
@@ -3145,6 +3383,29 @@ declare function buildPartPath(modules: ReadonlyArray<ModuleEntry>): PartPath;
  */
 declare function poseToMatrix4(pose: PlanarPose, out?: Matrix4): Matrix4;
 
+/**
+ * Pure helpers for composing per-XPU `trackTransform` and root
+ * `XtsConfig.orientation` into Three.js Matrix4 instances. Lives in geometry/
+ * so the component layer (XtsViewer3D, XtsScene) and the test suite share a
+ * single source of truth — no duplicated math.
+ *
+ * Composition order:
+ *
+ *     world = orientation ⊗ trackTransform ⊗ partTransformation ⊗ chain
+ *
+ * `partTransformation` is applied inside the per-XPU group by XtsScene, so
+ * the helpers here only cover the outermost two layers.
+ */
+
+/**
+ * Default Z lift for a track that does not specify `positionMm`. The XTS
+ * track sits on a base plate / table top in real installations, so 0 mm
+ * (= floor) is rarely what the user wants. 200 mm matches the standard
+ * Beckhoff table height used throughout the demo configs and renders
+ * correctly under the default shadow-casting ground plane.
+ */
+declare const DEFAULT_TRACK_Z_MM = 200;
+
 /**
  * Point-cloud registry for Free-path modules.
  *
@@ -3249,6 +3510,67 @@ declare function interpolateHeatmapValue(samples: ReadonlyArray<HeatmapSample>,
  */
 declare function normaliseToHeatmapRange(value: number, min: number, max: number): number;
 
+/**
+ * The vertical extent of a track module, in the path frame.
+ *
+ * `moduleCollision.ts` needs to know how tall a module is and where it sits
+ * relative to the mover path. It used to assume one coarse box for every type —
+ * `0 … DEFAULT_MODULE_HEIGHT_MM`, entirely *above* the path plane — which is
+ * neither the right height nor the right side: a motor module measures about
+ * 40 mm and straddles the plane, roughly half above and half below. Two tracks
+ * stacked closer than 100 mm therefore reported an overlap that does not exist,
+ * and the deepest ones reported it on every module pair.
+ *
+ * ## Why only Z, and not the width too
+ *
+ * The GLB sidecar carries `approximateBoundsMm`, the axis-aligned box of the
+ * CAD body *before* `originCorrection` is applied. Composing the two gives the
+ * body in the path frame — but only its **Z** range is a cross-section.
+ *
+ * Module paths are planar in XY and curves bend about Z, so a curved module's
+ * GLB spans its whole arc in X and Y: the 180° AT2050_0500 measures 307 mm
+ * across in Y, which is the sweep of the U-turn and not how wide the beam is.
+ * Its Z range, on the other hand, is the same 40.1 mm as the straight it is
+ * built from, because the sweep never leaves the plane.
+ *
+ * So the height is read from the asset and the half-width stays the coarse
+ * constant. Taking the width from the same box would inflate every curve
+ * segment to the size of its arc and report a collision for every oval.
+ *
+ * Overrides are not consulted: `SidecarOverrides` can replace a module's
+ * `originCorrection` but carries no bounds, so there is nothing to override.
+ */
+
+/** Where a module's body sits along Z, relative to the mover path plane. */
+interface ModuleHeightSpan {
+    /** Lowest point of the body [mm]; negative means below the path plane. */
+    minZMm: number;
+    /** Highest point of the body [mm]. */
+    maxZMm: number;
+}
+/**
+ * The span a module without usable bounds falls back to: the historic coarse
+ * box, so a type the asset package does not describe behaves as it always did.
+ */
+declare function coarseHeightSpan(heightMm: number): ModuleHeightSpan;
+/**
+ * Compose `approximateBoundsMm` through `originCorrection` and keep the Z range.
+ *
+ * All eight corners are transformed rather than only the two extremes: every
+ * shipped correction happens to be a multiple of 90°, which would keep the box
+ * axis-aligned, but nothing in the sidecar format promises that, and under a
+ * 45° correction two corners would describe a box far too small.
+ */
+declare function heightSpanOf(sidecar: ModuleSidecar): ModuleHeightSpan | null;
+/**
+ * How tall `moduleType` is and where it sits, or the coarse fallback.
+ *
+ * Resolved per module type rather than once per run: an Eco straight, a
+ * hygienic module with its tower and an AT2002 with its infeed box are three
+ * different heights, and a stack has to be judged against the one it holds.
+ */
+declare function moduleHeightSpan(moduleType: ModuleType3D, fallbackHeightMm: number): ModuleHeightSpan;
+
 /**
  * Shared closed-loop detection for built chains.
  *
@@ -3451,24 +3773,61 @@ interface Props {
 declare const ModuleCornerMarkers: React__default.FC<Props>;
 
 /**
- * <DimensionLabel> — camera-facing text used by the Dimensions overlay
- * (and re-usable elsewhere). Wraps drei's `<Billboard>` + `<Text>` so the
- * label always reads horizontally regardless of camera orbit, and is
- * placed at a small +Z offset above the dimension tick so the text and
- * the marker don't z-fight.
+ * labelFont — resolution of the font URL every 3D text label is drawn
+ * with, and the reason none of them can stall the scene any more.
+ *
+ * troika-three-text loads its font over XHR and, when that request
+ * fails, only logs `Failure loading font <url>`: the internal callback
+ * queue for that URL is never drained. drei's `<Text>` wraps exactly
+ * that callback in `suspend(...)`, so a dangling load becomes a promise
+ * that never settles. With one `<Suspense fallback={null}>` around the
+ * scene, a single unreachable font blanked the whole viewer — geometry,
+ * grid, ViewCube and all — with nothing in the console beyond troika's
+ * own line. Every sample that carried a station or an area label went
+ * dark that way.
+ *
+ * Two things prevent that here:
+ *
+ *  1. The default font is compiled in (`labelFontData.ts`) and handed to
+ *     troika as a `blob:` URL, so the common path never touches the
+ *     network and cannot fail.
+ *  2. A caller-supplied font URL is HEAD/GET-probed before it is handed
+ *     over. Until it answers, labels render in the built-in font; if it
+ *     never answers, they keep rendering in the built-in font and the
+ *     failure is reported once, loudly. troika is never given a URL that
+ *     has not already been fetched successfully.
+ *
+ * `<DimensionLabel>` / `<MoverIdLabel>` additionally wrap their `<Text>`
+ * in a local Suspense boundary, so even a font that parses badly costs
+ * one label rather than the scene.
  */
-
 /**
- * Default 3D-text font: Roboto Condensed (Latin, regular weight) served
- * from jsDelivr's @fontsource mirror. Pinned to a fixed major version so
- * the stack stays reproducible; the URL responds with a long
- * Cache-Control TTL so repeated reads come from the browser cache.
+ * Default 3D-text font: Roboto Condensed (Latin, regular weight).
+ *
+ * The value is the jsDelivr `@fontsource` mirror it was originally
+ * fetched from, kept stable because it is part of the public API. It is
+ * no longer fetched: the viewer ships the same WOFF compiled in, and
+ * treats this URL as "use the built-in copy", so passing it explicitly
+ * is equivalent to passing nothing and costs no request.
  *
- * `font` on troika-three-text expects an OTF / TTF / WOFF URL — NOT a CSS
- * font-family name. Consumers can override via `<DimensionLabel
- * fontFamily="https://…/whatever.woff" />` to swap in a brand font.
+ * `font` on troika-three-text expects an OTF / TTF / WOFF URL — NOT a
+ * CSS font-family name. Any other URL is used as given, once a probe
+ * has confirmed it actually loads.
  */
 declare const DEFAULT_LABEL_FONT_URL: "https://cdn.jsdelivr.net/npm/@fontsource/roboto-condensed@5.2.7/files/roboto-condensed-latin-400-normal.woff";
+/**
+ * URL of the compiled-in Roboto Condensed WOFF, as a `blob:` object URL
+ * created on first use and cached for the lifetime of the document.
+ *
+ * A blob URL rather than a `data:` URL on purpose: troika loads fonts
+ * through `XMLHttpRequest` and discards any response whose `status` is
+ * 0, which is what several engines report for non-HTTP schemes. Blob
+ * URLs answer with a regular 200.
+ *
+ * Falls back to a `data:` URL where `URL.createObjectURL` is missing
+ * (jsdom, some SSR shims) so the value is always a usable string.
+ */
+declare function bundledLabelFontUrl(): string;
 
 /**
  * <MoverIdLabel> — Camera-facing 3D text label that shows a mover's
@@ -3479,7 +3838,7 @@ declare const DEFAULT_LABEL_FONT_URL: "https://cdn.jsdelivr.net/npm/@fontsource/
  * the hood) so the label stays readable as the camera orbits. All
  * styling is driven by `MoverIdLabelOptions`; the component supplies
  * the documented defaults (15 mm black text, 55 mm above the mover's
- * magnet-plate origin, Roboto Condensed via jsDelivr).
+ * magnet-plate origin, the viewer's built-in Roboto Condensed).
  */
 
 interface MoverIdLabelProps {
@@ -3502,7 +3861,8 @@ declare const MoverIdLabel: React__default.FC<MoverIdLabelProps>;
  * Module count: 27
  * Mover count:  13
  * Tool count:   2
- * Rail count:   8
+ * Plate count:  7
+ * Rail count:   11
  */
 
 /**
@@ -3556,8 +3916,8 @@ declare function useSidecarSource(): SidecarSourceConfig;
  * only set `Beckhoff`; the loader silently falls back to that variant when
  * `HepcoGfx` is requested but unavailable.
  *
- * `null` for `Beckhoff` marks "prepared but not delivered"
- * (AT2042 / AT2140) — the loader renders a placeholder AABB mesh.
+ * A `null` `Beckhoff` entry marks a module type that is catalogued but has
+ * no GLB — the loader renders a placeholder AABB mesh instead.
  */
 
 /** Filename mapping per ModuleType3D (relative to assetsBaseUrl). */
@@ -3583,7 +3943,7 @@ declare const DEFAULT_RAIL_MANIFEST: Readonly<Record<RailType3D, {
  *   - Straights pick the matching-length AT9000 rail (0249 / 0250 / 0500).
  *   - +22.5° curves (AT2020 / AT2021) use AT9020.
  *   - −22.5° curves (AT2025 / AT2026) use AT9025.
- *   - 45° curves  (AT2040 / AT2041 / AT2042 / AT2140) use AT9040.
+ *   - 45° curves  (AT2040 / AT2041) use AT9040.
  *   - The 180° clothoid pair (AT2050 0500/0501 + merged 0500_180) uses
  *     AT9050, whose GLB already covers the full 500 mm path.
  *   - Hygienic ATH modules already include the rail in their module GLB
@@ -3595,10 +3955,12 @@ declare function resolveModuleGlbUrl(moduleType: ModuleType3D, rail: RailSystem,
 declare function resolveMoverGlbUrl(moverType: MoverType3D, override?: AssetManifest['movers']): string;
 declare function resolveToolGlbUrl(toolType: MoverToolType3D, override?: AssetManifest['tools']): string;
 /**
- * Pick the guiding-rail RailType for a module, or `null` if no separate
- * rail mesh should render (ATH variants, undeclared module types).
+ * Which guiding rail a module gets, given the mover running on it.
+ *
+ * `moverType` is optional so existing callers keep the -0055 default; pass it
+ * to get the variant Beckhoff actually pairs with that mover.
  */
-declare function resolveGuidingRailType(moduleType: ModuleType3D): RailType3D | null;
+declare function resolveGuidingRailType(moduleType: ModuleType3D, moverType?: MoverType3D): RailType3D | null;
 /**
  * Resolve the GLB filename for a guiding-rail type, honoring user-supplied
  * manifest overrides. Returns empty string when the rail is unknown.
@@ -3695,9 +4057,9 @@ declare function getSharedAssetLoader(): AssetLoader;
 declare function composeAssetUrl(baseUrl: string, filename: string): string;
 
 /**
- * The four sidecar kinds as data.
+ * The five sidecar kinds as data.
  *
- * Modules, movers, tools and rails all resolve their calibration the same
+ * Modules, movers, tools, magnet plates and rails all resolve the same
  * way — compiled-in table, else `<assetsBaseUrl>/<filename>`, else identity.
  * Only two things differ per kind: which built-in table to read and how the
  * filename is spelled. Keeping those two as a table (rather than four copies
@@ -3724,6 +4086,10 @@ interface SidecarKinds {
         id: MoverToolType3D;
         sidecar: MoverToolSidecar;
     };
+    plate: {
+        id: MagnetPlateType3D;
+        sidecar: MagnetPlateSidecar;
+    };
     rail: {
         id: RailType3D;
         sidecar: RailSidecar;
@@ -3843,4 +4209,4 @@ declare function snapToGrid(positionMm: Vec3, gridMm: number): Vec3;
 /** Convenience: `resolveSceneContext` + `toEntityRef`. */
 declare function resolveEntityFromObject(object: Object3D | null, instanceId?: number): MeasuredEntityRef | null;
 
-export { type AngleMeasurement, type Annotation, type AnnotationAnchor, type AnnotationInput, type AreaConfig, type AreaOptions, AssetLoader, type AssetManifest, BUILTIN_MODULE_SIDECARS, BUILTIN_MOVER_SIDECARS, BUILTIN_RAIL_SIDECARS, BUILTIN_TOOL_SIDECARS, type BuiltChain, type BuiltModule, type CameraProjection, type CameraState, type CaptureMode, type CheckModuleCollisionsOptions, type CheckMoverCollisionsOptions, type ClickModifiers, type CoordinateSystem, type CustomAssetBinding, type CustomAssetConfig, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MEASUREMENT_STYLE, DEFAULT_MODULE_HALF_WIDTH_MM, DEFAULT_MODULE_HEIGHT_MM, DEFAULT_MODULE_MANIFEST, DEFAULT_MOVER_MANIFEST, DEFAULT_ORIGIN_CORRECTION, DEFAULT_RAIL_MANIFEST, DEFAULT_SNAP_KINDS, DEFAULT_SNAP_RADIUS_PX, DEFAULT_TOOL_MANIFEST, type DimensionOptions, type DisplayOptions, type DistanceMeasurement, EMPTY_SELECTION, type EndDelta, type FeedSegment, type FeedSegmentHighlight, type FeedSegmentSelector, type FeedSegmentSpan, type FocusOptions, type FocusTarget, type FrameCaptureOptions, type FrameCaptureSession, HEPCO_GFX_PROFILE, type HeatmapSample, type HepcoGfxRailProfileDims, IDENTITY_POSE, INFEED_MODULE_TYPES, type InfoBarConfig, type InfoBarMarkerConfig, type InfoBarOptions, JSDELIVR_ASSETS_BASE_URL, MODULE_CATALOG, MODULE_GUIDING_RAIL_MAP, MOVER_CATALOG, type MarkerOptions, type MarkerShape, type MeasuredEntityRef, type Measurement, type MeasurementApi, type MeasurementAxis, type MeasurementDocument, type MeasurementDraft, type MeasurementFormatOptions, type MeasurementId, type MeasurementInput, type MeasurementKind, type MeasurementOptions, type MeasurementPoint, type MeasurementResult, type MeasurementSnapshot, type MeasurementStyle, type MeasurementTool, type ModuleAssetEntry, type ModuleCatalogEntry, type ModuleCollision, type ModuleCollisionPartInput, type ModuleCollisionXpuInput, ModuleCornerMarkers, type ModuleEntry, type ModuleHighlight, type ModuleProbe, type ModuleRef, type ModuleSidecar, type ModuleStatusEntry, type ModuleType3D, type MoverAssetEntry, type MoverCatalogEntry, type MoverCollision, type MoverConfig, MoverIdLabel, type MoverIdLabelOptions, type MoverPositionEntry, type MoverProbe, type MoverRef, type MoverSidecar, type MoverToolAssetEntry, type MoverToolConfig, type MoverToolSidecar, type MoverToolType3D, type MoverType3D, type NormalizationWarning, type NormalizedXtsConfig, type Orientation, type OriginCorrection, type PartConfig, type PartPath, type PartTransformation, type PathMeasurement, type PathSample, type PathType, type PlanarPose, type PointCloud, type PointProjector, type PositionFrame, type ProcessingUnitConfig, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, type ResolvedMeasurementStyle, SIDECAR_KINDS, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionMode, type SelectionState, type SidecarIdOf, type SidecarKind, type SidecarKindSpec, type SidecarKinds, SidecarLoader, type SidecarOf, type SidecarOverrides, type SidecarSourceConfig, SidecarSourceContext, type SnapCandidate, type SnapKind, type SnapOptions, type SplitFeedSegmentsOptions, type StationConfig, type StationOptions, type StatorHeatmap, type StopPositionMoverOptions, type TextOptions, type TrackAnchor, type TrackDistanceMeasurement, type TrackIndex, type TrackIndexEntry, type TrackMetrics, type TrackMetricsResolver, type TrackProjection, type TrackTransform, VERSION, type Vec2, type Vec3, XtsArcCurve3, type XtsConfig, XtsConfigNormalizer, type XtsModelDocument, XtsPointCloudCurve3, type XtsRuntimeState, XtsViewer3D, type XtsViewer3DProps, type XtsViewer3DRef, type XtsViewerError, type XtsViewerErrorCode, XtsViewerErrorException, angleDeg, applyBeckhoffXtsConvention, applyEmptyClick, applyModuleClick, applyMoverClick, arcPoints, axisDistanceMm, buildChain, buildModuleProbes, buildPartPath, buildTrackIndex, chainToUserPositionMm, checkModuleCollisions, checkSamePathCollisions, chooseSnapCandidate, collectFeedSegments, collectFeedSegmentsForXpu, collectTriangleSnapCandidates, composeAssetUrl, computeMeasurementResult, createHepcoGfxBaseplateShape, createHepcoGfxRailShape, deselectAll, distanceMm, findModuleAt, formatAngleDeg, formatLengthMm, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, interpolateHeatmapValue, isChainClosed, isKnownModuleType, isKnownMoverType, isModuleSelected, isMoverSelected, labelAnchorFor, moduleAnchorWorld, moduleEndDelta, moduleSidecarFilename, moverAnchorWorld, moverSidecarFilename, moverWorldAt, nearestTrackPoint, normaliseToHeatmapRange, normalizeXtsConfig, pathLengthsMm, pickGlbForRail, poseToMatrix4, railSidecarFilename, registerPointCloud, resolveEntityFromObject, resolveGuidingRailGlbUrl, resolveGuidingRailType, resolveHepcoGfxProfile, resolveMeasurementStyle, resolveModuleGlbUrl, resolveMoverGlbUrl, resolveOriginCorrection, resolveStopPositionMm, resolveToolGlbUrl, sampleChainPoint, sampleChainRange, sampleModulePath, snapToGrid, sortHeatmapSamples, splitIntoFeedSegments, toolSidecarFilename, trackAnchorWorld, trackDistanceMm, trackLengthOf, trackPolylineWorld, unregisterPointCloud, useSidecarSource, userToChainPositionMm, worldPointOnPart };
+export { type AngleMeasurement, type Annotation, type AnnotationAnchor, type AnnotationInput, type AreaConfig, type AreaOptions, AssetLoader, type AssetManifest, BUILTIN_MODULE_SIDECARS, BUILTIN_MOVER_SIDECARS, BUILTIN_RAIL_SIDECARS, BUILTIN_TOOL_SIDECARS, type BuiltChain, type BuiltModule, type CameraProjection, type CameraState, type CaptureDimensions, type CaptureMode, type CaptureRequest, type CheckModuleCollisionsOptions, type CheckMoverCollisionsOptions, type ClickModifiers, type CoordinateSystem, type CustomAssetBinding, type CustomAssetConfig, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MEASUREMENT_STYLE, DEFAULT_MODULE_HALF_WIDTH_MM, DEFAULT_MODULE_HEIGHT_MM, DEFAULT_MODULE_MANIFEST, DEFAULT_MOVER_MANIFEST, DEFAULT_ORIGIN_CORRECTION, DEFAULT_RAIL_MANIFEST, DEFAULT_SNAP_KINDS, DEFAULT_SNAP_RADIUS_PX, DEFAULT_TOOL_MANIFEST, DEFAULT_TRACK_Z_MM, type DimensionOptions, type DisplayOptions, type DistanceMeasurement, EMPTY_SELECTION, type EndDelta, type FeedSegment, type FeedSegmentHighlight, type FeedSegmentSelector, type FeedSegmentSpan, type FocusOptions, type FocusTarget, type FrameCaptureOptions, type FrameCaptureSession, HEPCO_GFX_PROFILE, type HeatmapSample, type HepcoGfxRailProfileDims, IDENTITY_POSE, INFEED_MODULE_TYPES, type InfoBarConfig, type InfoBarMarkerConfig, type InfoBarOptions, type InteractionLocks, JSDELIVR_ASSETS_BASE_URL, type KeyboardNavigationOptions, MAGNET_PLATE_CATALOG, MODULE_CATALOG, MODULE_GUIDING_RAIL_MAP, MOVER_CATALOG, MOVER_INTEGRATED_PLATE, type MagnetPlateAssetEntry, type MagnetPlateCatalogEntry, type MagnetPlateType3D, type MarkerOptions, type MarkerShape, type MeasuredEntityRef, type Measurement, type MeasurementApi, type MeasurementAxis, type MeasurementDocument, type MeasurementDraft, type MeasurementFormatOptions, type MeasurementId, type MeasurementInput, type MeasurementKind, type MeasurementOptions, type MeasurementPoint, type MeasurementResult, type MeasurementSnapshot, type MeasurementStyle, type MeasurementTool, type ModuleAssetEntry, type ModuleCatalogEntry, type ModuleCollision, type ModuleCollisionPartInput, type ModuleCollisionXpuInput, ModuleCornerMarkers, type ModuleEntry, type ModuleHeightSpan, type ModuleHighlight, type ModuleProbe, type ModuleRef, type ModuleSidecar, type ModuleStatusEntry, type ModuleType3D, type MoverAssetEntry, type MoverCatalogEntry, type MoverCollision, type MoverConfig, MoverIdLabel, type MoverIdLabelOptions, type MoverPositionEntry, type MoverProbe, type MoverRef, type MoverSidecar, type MoverToolAssetEntry, type MoverToolConfig, type MoverToolSidecar, type MoverToolType3D, type MoverType3D, type NormalizationWarning, type NormalizedXtsConfig, type Orientation, type OriginCorrection, type PartConfig, type PartPath, type PartTransformation, type PathMeasurement, type PathSample, type PathType, type PerformanceOptions, type PlanarPose, type PointCloud, type PointProjector, type PositionFrame, type ProcessingUnitConfig, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, type ResolvedMeasurementStyle, SIDECAR_KINDS, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionMode, type SelectionState, type SidecarIdOf, type SidecarKind, type SidecarKindSpec, type SidecarKinds, SidecarLoader, type SidecarOf, type SidecarOverrides, type SidecarSourceConfig, SidecarSourceContext, type SnapCandidate, type SnapKind, type SnapOptions, type SplitFeedSegmentsOptions, type StationConfig, type StationOptions, type StatorHeatmap, type StopPositionMoverOptions, type TextOptions, type TrackAnchor, type TrackDistanceMeasurement, type TrackIndex, type TrackIndexEntry, type TrackMetrics, type TrackMetricsResolver, type TrackProjection, type TrackTransform, VERSION, type Vec2, type Vec3, type ViewCubeAlignment, type ViewCubeOptions, XtsArcCurve3, type XtsConfig, XtsConfigNormalizer, type XtsModelDocument, XtsPointCloudCurve3, type XtsRuntimeState, XtsViewer3D, type XtsViewer3DProps, type XtsViewer3DRef, type XtsViewerError, type XtsViewerErrorCode, XtsViewerErrorException, angleDeg, applyBeckhoffXtsConvention, applyEmptyClick, applyModuleClick, applyMoverClick, arcPoints, axisDistanceMm, buildChain, buildModuleProbes, buildPartPath, buildTrackIndex, bundledLabelFontUrl, chainToUserPositionMm, checkAllModuleCollisions, checkAllMoverCollisions, checkModuleCollisions, checkSamePathCollisions, chooseSnapCandidate, coarseHeightSpan, collectFeedSegments, collectFeedSegmentsForXpu, collectTriangleSnapCandidates, composeAssetUrl, computeMeasurementResult, createHepcoGfxBaseplateShape, createHepcoGfxRailShape, deselectAll, distanceMm, findModuleAt, formatAngleDeg, formatLengthMm, getMagnetPlateEntry, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, heightSpanOf, interpolateHeatmapValue, isChainClosed, isKnownMagnetPlateType, isKnownModuleType, isKnownMoverType, isModuleSelected, isMoverSelected, labelAnchorFor, moduleAnchorWorld, moduleEndDelta, moduleHeightSpan, moduleSidecarFilename, moverAnchorWorld, moverSidecarFilename, moverWorldAt, nearestTrackPoint, normaliseToHeatmapRange, normalizeXtsConfig, pathLengthsMm, pickGlbForRail, poseToMatrix4, railSidecarFilename, registerPointCloud, resolveEntityFromObject, resolveGuidingRailGlbUrl, resolveGuidingRailType, resolveHepcoGfxProfile, resolveMeasurementStyle, resolveModuleGlbUrl, resolveMoverGlbUrl, resolveOriginCorrection, resolveStopPositionMm, resolveToolGlbUrl, sampleChainPoint, sampleChainRange, sampleModulePath, snapToGrid, sortHeatmapSamples, splitIntoFeedSegments, toModuleCollisionInputs, toolSidecarFilename, trackAnchorWorld, trackDistanceMm, trackLengthOf, trackPolylineWorld, unregisterPointCloud, useSidecarSource, userToChainPositionMm, worldPointOnPart };