beckhoff-xts-viewer-3d 5.2.3 → 6.0.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
+import { Vector3, ColorRepresentation, Matrix4, Shape, Curve, CurvePath, WebGLRenderer, Object3D } from 'three';
 import * as React from 'react';
 import React__default from 'react';
-import { Vector3, ColorRepresentation, Matrix4, Shape, Curve, CurvePath, WebGLRenderer, Object3D } from 'three';
 import { GLTF } from 'three-stdlib';
 
 /**
@@ -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.3";
+declare const VERSION: "6.0.0";
 
 /**
  * Default CDN URL for the GLB asset bundle (`beckhoff-xts-viewer-3d-assets`).
@@ -32,7 +32,18 @@ declare const VERSION: "5.2.3";
  * 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@3.0.0/models";
+
+/**
+ * Scalar tuples shared by every other type module.
+ *
+ * The leaf of the type graph: `Vec3` is a position or an Euler triple in
+ * millimetres / degrees, `Vec2` a viewport or margin pair in pixels. Kept
+ * apart from the layout types so `display`, `annotations` and `config` can
+ * all reach them without importing each other.
+ */
+type Vec3 = [number, number, number];
+type Vec2 = [number, number];
 
 /**
  * Catalogue taxonomy — the string unions naming every module, mover, tool and
@@ -44,7 +55,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 +76,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_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,28 +97,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';
-
-/**
- * Scalar tuples shared by every other type module.
- *
- * The leaf of the type graph: `Vec3` is a position or an Euler triple in
- * millimetres / degrees, `Vec2` a viewport or margin pair in pixels. Kept
- * apart from the layout types so `display`, `annotations` and `config` can
- * all reach them without importing each other.
- */
-type Vec3 = [number, number, number];
-type Vec2 = [number, number];
+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';
 
 /**
  * Display options — how a layout is drawn, as opposed to what it is.
@@ -128,10 +147,10 @@ interface DisplayOptions {
      * `'viewer'` (no transform — current behaviour).
      */
     coordinateSystem?: CoordinateSystem;
-    displayStations?: boolean;
+    showStations?: boolean;
     /** Render configured areas. Default: true (when `areas[]` is set). */
-    displayAreas?: boolean;
-    displayDimensions?: boolean;
+    showAreas?: boolean;
+    showDimensions?: boolean;
     showDriveErrors?: boolean;
     showDriveWarnings?: boolean;
     /**
@@ -181,10 +200,6 @@ interface DisplayOptions {
      * boundary. Off by default.
      */
     showModuleCornerMarkers?: boolean;
-    /** Diameter (mm) of the corner-marker spheres. Default: 10. */
-    moduleCornerMarkerSizeMm?: number;
-    /** Color of the corner markers. Default: '#FF2030' (red). */
-    moduleCornerMarkerColor?: string;
     /**
      * Render a red dot + vertical centre-line at each mover's anchor point —
      * i.e. the track path point the mover is commanded to (its expected
@@ -196,10 +211,6 @@ interface DisplayOptions {
      * default.
      */
     showMoverAnchorMarker?: boolean;
-    /** Diameter (mm) of the anchor-marker dot. Default: 10. */
-    moverAnchorMarkerSizeMm?: number;
-    /** Color of the anchor marker. Default: '#FF2030' (red). */
-    moverAnchorMarkerColor?: string;
     /**
      * Print each module's type designation onto its type-plate panel.
      *
@@ -212,97 +223,114 @@ interface DisplayOptions {
      * Default: `true`.
      */
     moduleTypePlates?: boolean;
+    /** Size and colour of the module corner markers. */
+    moduleCornerMarkerOptions?: CalibrationMarkerOptions;
+    /** Size and colour of the mover anchor marker. */
+    moverAnchorMarkerOptions?: CalibrationMarkerOptions;
+    /** Lighting, environment map and tone mapping. */
+    lighting?: LightingOptions;
+    /** Screen-space effects (SSAO, bloom). */
+    postProcessing?: PostProcessingOptions;
+}
+/**
+ * Size and colour of a calibration marker.
+ *
+ * The corner markers and the anchor marker each used to carry a loose
+ * `...SizeMm` / `...Color` pair on `DisplayOptions`, which is four flat
+ * fields describing two objects.
+ */
+interface CalibrationMarkerOptions {
+    /** Diameter in mm. Default: 10. */
+    sizeMm?: number;
+    /** CSS colour. Default: `'#FF2030'` (red). */
+    color?: string;
+}
+/**
+ * Lighting and the renderer's colour pipeline.
+ *
+ * Grouped rather than flat because these travel together: the whole block is
+ * handed to `<SceneLighting>` and the renderer, and none of it describes a
+ * layout. `DisplayOptions` already models per-overlay styling this way
+ * (`stationOptions`, `areaOptions`, `dimensionOptions`), so eleven loose
+ * scalars sitting beside them was the odd shape out.
+ */
+interface LightingOptions {
     /**
      * Render shadows: enables the WebGL shadow map, makes one directional
-     * light cast shadows, and renders a transparent shadow-catcher plane
-     * so shadows from modules / movers / tools become visible. Default:
-     * false (no shadow-map cost when disabled). All loaded GLB meshes
-     * have their `castShadow` + `receiveShadow` flags set unconditionally
-     * — turning shadows on at the canvas level is the only thing that
-     * actually triggers the per-frame shadow pass.
+     * light cast shadows, and renders a transparent shadow-catcher plane so
+     * shadows from modules / movers / tools become visible. Default: false
+     * (no shadow-map cost when disabled). All loaded GLB meshes have their
+     * `castShadow` + `receiveShadow` flags set unconditionally — turning
+     * shadows on at the canvas level is the only thing that actually triggers
+     * the per-frame shadow pass.
      */
     shadows?: boolean;
     /**
-     * Image-based lighting via a procedural indoor environment map
-     * (three's `RoomEnvironment` processed through `PMREMGenerator` —
-     * no HTTP fetch, no asset shipped). Drives PBR reflections on
-     * metallic / roughness materials so aluminium rails and brushed
-     * mover plates read as actual metal instead of flat shaded surfaces.
+     * Image-based lighting via a procedural indoor environment map (three's
+     * `RoomEnvironment` processed through `PMREMGenerator` — no HTTP fetch, no
+     * asset shipped). Drives PBR reflections on metallic / roughness materials
+     * so aluminium rails and brushed mover plates read as actual metal instead
+     * of flat shaded surfaces.
      *
-     * Cost: one-time PMREM build on mount (≈ 1.5 MB GPU), zero per-frame
+     * Cost: one-time PMREM build on mount (~1.5 MB GPU), zero per-frame
      * overhead beyond the regular PBR shader's environment lookup.
      *
-     * Default: `true` — looks noticeably better at no measurable cost.
-     * Set `false` to fall back to direct-lighting only.
+     * Default: `true` — looks noticeably better at no measurable cost. Set
+     * `false` to fall back to direct-lighting only.
      */
-    environmentLighting?: boolean;
+    environment?: boolean;
     /**
-     * Strength of the environment-map contribution. Lower values keep
-     * the look closer to the previous direct-lighting-only baseline;
-     * higher values emphasise reflections.
-     *
-     * Default: `0.4` — reflections visible without overwhelming the
-     * directional + ambient lights. Range typically `0.0` … `1.5`.
+     * Strength of the environment-map contribution. Lower values keep the look
+     * closer to the direct-lighting-only baseline; higher values emphasise
+     * reflections. Default: `0.4`. Range typically `0.0` ... `1.5`.
      */
     environmentIntensity?: number;
     /**
-     * Renderer tone-mapping operator. ACES filmic compresses bright
-     * highlights into a perceptually pleasant rolloff and is the closest
-     * match to film / professional CAD viewers; `'linear'` reproduces the
-     * pre-tone-mapping behaviour for callers who relied on it.
-     *
-     * Default: `'aces'`.
+     * Renderer tone-mapping operator. ACES filmic compresses bright highlights
+     * into a perceptually pleasant rolloff and is the closest match to film /
+     * professional CAD viewers; `'linear'` reproduces the pre-tone-mapping
+     * behaviour for callers who relied on it. Default: `'aces'`.
      */
     toneMapping?: 'aces' | 'linear' | 'reinhard' | 'cineon' | 'agx' | 'none';
     /**
      * Tone-mapping exposure multiplier (analogous to a camera's exposure
-     * stop). 1.0 = neutral. Bumped above 1 brightens the result, below 1
-     * darkens it.
-     *
+     * stop). 1.0 = neutral. Above 1 brightens, below 1 darkens.
      * Default: `1.0`.
      */
     toneMappingExposure?: number;
+}
+/**
+ * Screen-space post-processing. Each effect is an extra half-res pass per
+ * frame, so both are opt-in.
+ *
+ * The whole block is forwarded to `<ScenePostProcessing>` unchanged — as
+ * seven flat fields it had to be re-threaded one by one, and every default
+ * restated at the far end.
+ */
+interface PostProcessingOptions {
     /**
-     * Screen-space ambient occlusion (GTAO). Adds contact shadows in
-     * crevices and between adjacent surfaces for significantly more visual
-     * depth. Cost: one half-res pass per frame.
-     *
+     * Screen-space ambient occlusion (GTAO). Adds contact shadows in crevices
+     * and between adjacent surfaces for significantly more visual depth.
      * Default: `false`.
      */
     ssao?: boolean;
-    /**
-     * SSAO blend intensity. Higher values darken crevices more.
-     * Range: 0.0–4.0. Default: `1.0`.
-     */
+    /** SSAO blend intensity; higher darkens crevices more. 0.0-4.0. Default `1.0`. */
     ssaoIntensity?: number;
-    /**
-     * SSAO sampling radius in world units (mm). Larger values spread the
-     * occlusion over a wider area. Default: `20`.
-     */
+    /** SSAO sampling radius in world units (mm). Default `20`. */
     ssaoRadius?: number;
     /**
      * Bloom (glow) for bright metallic surfaces. Adds a soft halo around
-     * polished rails and highlights, giving metals a more realistic
-     * reflective appearance. Cost: one half-res pass per frame.
-     *
-     * Default: `false`.
+     * polished rails and highlights. Default: `false`.
      */
     bloom?: boolean;
-    /**
-     * Bloom intensity (strength). Higher values produce brighter glow.
-     * Range: 0.0–3.0. Default: `0.4`.
-     */
+    /** Bloom strength; higher produces brighter glow. 0.0-3.0. Default `0.4`. */
     bloomIntensity?: number;
     /**
-     * Bloom luminance threshold. Only pixels brighter than this value
-     * contribute to the bloom. Lower values bloom more of the scene.
-     * Range: 0.0–1.0. Default: `0.85`.
+     * Bloom luminance threshold - only pixels brighter than this contribute.
+     * Lower values bloom more of the scene. 0.0-1.0. Default `0.85`.
      */
     bloomThreshold?: number;
-    /**
-     * Bloom blur radius. Controls how far the glow spreads.
-     * Range: 0.0–1.0. Default: `0.4`.
-     */
+    /** Bloom blur radius; how far the glow spreads. 0.0-1.0. Default `0.4`. */
     bloomRadius?: number;
 }
 /**
@@ -330,8 +358,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. */
@@ -457,7 +490,6 @@ interface DimensionOptions {
      */
     lateralDisplacementMm?: number;
     textOptions?: TextOptions;
-    textPattern?: number;
     /**
      * Show numeric mm-value labels at every dimension tick (module boundaries
      * and — when enabled — intermediate steps). Labels are billboards that
@@ -675,6 +707,27 @@ interface ProcessingUnitConfig {
      */
     objectId: number;
     moverType: MoverType3D;
+    /**
+     * Magnet plate set attached to the carriage.
+     *
+     * Only meaningful for a mover whose GLB ships bare — the whole Hepco
+     * `GFX2-1TC` family. 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.
+     *
+     * This is how pole count is chosen. A 7-pole M34, which used to be its own
+     * `Hepco_GFX2_1TC_M34_7P` mover type, is the same carriage with a different
+     * plate on it:
+     *
+     * ```ts
+     * { moverType: 'Hepco_GFX2_1TC_M34', magnetPlateType: 'AT9001_0775' }
+     * ```
+     *
+     * 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;
@@ -845,6 +898,20 @@ interface ModuleStatusEntry {
     warning?: boolean;
     error?: boolean;
 }
+/**
+ * Runtime state for a single mover tool — pushed through
+ * `XtsViewer3DRef.setMoverToolStates(update)`, keyed by `MoverConfig.id`
+ * and then by `MoverToolConfig.id`. A stored entry overrides the
+ * config-time `MoverToolConfig.visible`; `null` drops back to it.
+ *
+ * Visibility only: it is the state a host changes while a scene runs — a
+ * simulated line loading a product onto a mover at one station and taking
+ * it off at another. Placement, rotation and opacity describe what a tool
+ * IS and stay in the configuration.
+ */
+interface MoverToolStateEntry {
+    visible?: boolean;
+}
 interface MoverToolConfig {
     toolType: MoverToolType3D;
     /** Required when toolType === 'Custom'. */
@@ -902,1212 +969,1506 @@ interface CustomAssetConfig {
 }
 
 /**
- * Interaction surface — selection, highlighting and the camera.
+ * The transform gizmo — the translate / rotate / scale handles the viewer
+ * draws on whatever is selected.
  *
- * The types a host exchanges with the viewer at runtime rather than at
- * configuration time: what is addressed (`ModuleRef`, `MoverRef`), what is
- * picked out (`SelectionState`, `ModuleHighlight`, `FeedSegmentHighlight`),
- * and where the camera looks (`CameraState`, `FocusTarget`).
- */
-
-interface ModuleRef {
-    processingUnitObjectId: number;
-    partObjectId: number;
-    moduleIndex: number;
-}
-interface MoverRef {
-    processingUnitObjectId: number;
-    moverIndex: number;
-}
-interface SelectionState {
-    modules: ModuleRef[];
-    movers: MoverRef[];
-}
-type SelectionMode = 'Off' | 'Single' | 'Multi';
-/**
- * Declarative module highlight. All modules whose `moduleType` appears in
- * `moduleTypes` are tinted with the given `color` — same emissive effect as
- * selection, but independent of the selection state. Multiple highlights can
- * overlap; the first matching entry wins.
+ * Issue #107 asks for "OrbitControls … für Rotation, Translation und
+ * Scaling" on a selected object or a whole track. Those are two different
+ * things: `OrbitControls` is the camera, and what moves an *object* is a
+ * transform gizmo, so that is what this is called. The camera controls are
+ * unchanged and keep living behind `lock` / `keyboardNavigation`.
  *
- * Toggle on/off by setting `moduleHighlights` on `<XtsViewer3D>` to an
- * array (enabled) or `undefined` / `[]` (disabled).
- */
-interface ModuleHighlight {
-    /** Module types to highlight. */
-    moduleTypes: ModuleType3D[];
-    /** Highlight color (CSS color string, e.g. `'#FF6600'`). */
-    color: string;
-}
-/**
- * Addresses one feed segment (Einspeisestrang). Either form works — pick
- * whichever the host has at hand:
+ * What can be posed is what the configuration gives a free pose to:
  *
- *  - `{ infeedModuleGlobalNumber }` — the `ModuleEntry.globalNumber` of the
- *    infeed module that leads the segment. Stable across layout edits as long
- *    as the global numbering is stable.
- *  - `{ partObjectId, segmentIndex }` — ordinal address: `segmentIndex` counts
- *    0, 1, 2 … in chain order, starting at the part's first infeed module.
+ *   - a **track** (`ProcessingUnitConfig.trackTransform`) — position,
+ *     rotation and uniform scale;
+ *   - a **static custom asset** (`CustomAssetConfig.binding` with
+ *     `type: 'static'`) — the same three.
+ *
+ * A module or a mover is NOT a target and never grows handles: modules bolt
+ * together end-to-end along the chain and movers ride it, so neither has a
+ * pose of its own, and posing "the track it belongs to" instead would move
+ * something other than what the user picked. Select the track — that is
+ * what `selectionScope: 'track'` is for. A mover-bound custom asset rides
+ * its mover for the same reason and is not a target either.
  */
-type FeedSegmentSelector = {
-    infeedModuleGlobalNumber: number;
+
+/** Which handle set the gizmo shows. */
+type TransformGizmoMode = 'translate' | 'rotate' | 'scale';
+/** What the handles move. */
+type TransformGizmoTarget = {
+    kind: 'track';
+    processingUnitObjectId: number;
 } | {
-    partObjectId: number;
-    segmentIndex: number;
+    kind: 'customAsset';
+    assetId: string;
 };
 /**
- * Declarative feed-segment highlight. Every module belonging to one of the
- * selected segments is tinted with `color` — same emissive effect as
- * selection, but independent of the selection state.
- *
- * Multiple entries are allowed (that is how several segments get several
- * colors at once); on overlap the first matching entry wins, mirroring
- * `ModuleHighlight`.
- *
- * Toggle on/off by setting `feedSegmentHighlights` on `<XtsViewer3D>` to an
- * array (enabled) or `undefined` / `[]` (disabled).
+ * A free pose, in the frame the configuration states it in — the root
+ * `XtsConfig.orientation` frame for both target kinds.
  */
-interface FeedSegmentHighlight {
-    /** Segments to tint. */
-    segments: FeedSegmentSelector[];
-    /** Highlight color (CSS color string, e.g. `'#00AAFF'`). */
-    color: string;
+interface TransformGizmoPose {
+    positionMm: Vec3;
+    /** Intrinsic XYZ Euler angles in degrees. */
+    rotationDegEuler: Vec3;
+    /** Uniform scale factor. */
+    scaleUniform: number;
 }
-/**
- * One feed segment (Einspeisestrang) as detected in the configuration: the
- * contiguous run of modules starting at an infeed module (Einspeisemodul,
- * `ModuleCatalogEntry.isInfeed`) and ending right before the next infeed
- * module of the same part.
- *
- * On a closed chain (oval, U-turn pair — see `isChainClosed`) the modules
- * ahead of the part's first infeed module belong to the LAST segment, which
- * then carries `wrapsSeam: true`. On an open chain those leading modules
- * belong to no segment at all and cannot be tinted.
- *
- * Returned by `XtsViewer3DRef.getFeedSegments()`.
- */
-interface FeedSegment {
-    processingUnitObjectId: number;
-    partObjectId: number;
-    /** 0-based, in chain order, counted from the part's first infeed module. */
-    segmentIndex: number;
+/** One drag, reported to the host. */
+interface TransformGizmoChange {
+    target: TransformGizmoTarget;
+    /** Which kind of handle produced it — all three are on screen at once. */
+    mode: TransformGizmoMode;
+    /** The pose after the drag, in the host's own coordinate convention. */
+    pose: TransformGizmoPose;
     /**
-     * `ModuleEntry.globalNumber` of the leading infeed module. `undefined` when
-     * the config does not set it — such a segment can only be addressed via
-     * `{ partObjectId, segmentIndex }`.
+     * `pose` in the shape `trackTransformOverrides` / `trackTransform` take.
+     * Empty for a `'customAsset'` target.
      */
-    infeedModuleGlobalNumber?: number;
-    /** Module type of the leading infeed module. */
-    infeedModuleType: ModuleType3D;
-    /** Chain indices of every module in this segment, in chain order. */
-    moduleIndices: number[];
-    /** Σ of the segment's module lengths, in mm. */
-    lengthMm: number;
-    /** True when the segment wraps the closed-loop seam. */
-    wrapsSeam: boolean;
-}
-interface CameraState {
-    positionMm: Vec3;
-    targetMm: Vec3;
-    /** Always 'Z' in the current spec. */
-    upAxis: 'Z' | 'Y';
-    zoom?: number;
+    trackTransform?: TrackTransform;
 }
 /**
- * Live camera projection.
- *   - `'perspective'` (default) — the regular 3D view.
- *   - `'orthographic'` — paired with `topDown`, gives the flat 2D plan view
- *     that matches `exportScreenshot({ mode: 'top-down' })`.
- */
-type CameraProjection = 'perspective' | 'orthographic';
-/**
- * Target for the imperative `viewerRef.current.focusOn(target, opts)` camera
- * animation. The viewer computes the target's world-space bounding box and
- * flies the camera so the whole object fits the frame:
- *   - In `'perspective'` projection the current view angle is preserved
- *     (the camera only dollies / re-centres).
- *   - In `'orthographic'` top-down the frustum is re-framed and the camera
- *     pans straight over the object.
- */
-type FocusTarget = {
-    kind: 'scene';
-} | {
-    kind: 'station';
-    stationId: number;
-} | {
-    kind: 'area';
-    areaId: number;
-} | {
-    kind: 'mover';
-    ref: MoverRef;
-} | {
-    kind: 'module';
-    ref: ModuleRef;
-};
-interface FocusOptions {
-    /** Animation duration in ms. Default 700. `0` jumps immediately. */
-    durationMs?: number;
+ * Transform-gizmo configuration. Off unless `enabled` is set, so a viewer
+ * that only displays a layout never grows draggable handles.
+ *
+ * The gizmo is drawn in the same palette as the corner navigation gizmo —
+ * X red, Y green, Z blue — and sits at the target's origin.
+ *
+ * Applying a drag: the viewer shows it immediately, and reports it through
+ * `onTransformChange`. A host that persists the change (into its config, or
+ * into `trackTransformOverrides`) takes over from the viewer's own copy the
+ * moment its value arrives; a host that ignores the callback keeps the
+ * viewer's. Either way the object never jumps.
+ *
+ * @example
+ * ```tsx
+ * <XtsViewer3D
+ *   selectionMode="Single"
+ *   selectionScope="track"
+ *   transformGizmo={{
+ *     enabled: true,
+ *     translateSnapMm: 10,
+ *     onTransformChange: ({ target, trackTransform }) => {
+ *       if (target.kind === 'track' && trackTransform) {
+ *         setOverrides((o) => ({
+ *           ...o,
+ *           [target.processingUnitObjectId]: trackTransform,
+ *         }));
+ *       }
+ *     },
+ *   }}
+ * />
+ * ```
+ */
+interface TransformGizmoOptions {
+    /** Draw the handles at all. Default `false`. */
+    enabled?: boolean;
     /**
-     * Padding around the target's bounding box (1 = tight fit). Default 1.2 in
-     * perspective, 1.1 in orthographic top-down.
+     * Which handle sets to draw. Default: all three at once, which is the
+     * point of the thing — move, turn and scale without first telling a
+     * toolbar which of them you meant.
+     *
+     * They are told apart by shape and position rather than by a mode: the
+     * translation arrow runs out along the positive half of each axis, the
+     * scale cube along the negative half (drag away from the object to grow
+     * it), and the rotation ring circles both. Narrow the list to leave a
+     * kind of edit out entirely — `['translate', 'rotate']` for a layout
+     * whose tracks must keep their scale.
      */
-    paddingFactor?: number;
-    /** Easing curve. Default `'easeInOutCubic'`. */
-    easing?: 'linear' | 'easeInOutCubic';
+    handles?: TransformGizmoMode[];
+    /**
+     * What the handles move. Default `'selection'` — follow the selection: a
+     * selected custom asset, or a selected whole track (which is what a click
+     * produces under `selectionScope: 'track'`). A selected module or mover
+     * shows no handles at all.
+     *
+     * Pass a `TransformGizmoTarget` to drive the gizmo from outside instead;
+     * the selection is then ignored — that is the path for a host that picks
+     * the track from its own list rather than from the canvas. `'none'` keeps
+     * the feature configured but shows nothing.
+     */
+    target?: 'selection' | 'none' | TransformGizmoTarget;
+    /** On-screen length of one axis, in CSS px. Default `90`. */
+    sizePx?: number;
+    /**
+     * Axis colours in x / y / z order. Defaults to the navigation gizmo's
+     * palette, which is what makes the two read as one family.
+     */
+    axisColors?: readonly [string, string, string];
+    /** Round translation to this step, in mm. Default: no snapping. */
+    translateSnapMm?: number;
+    /** Round rotation to this step, in degrees. Default: no snapping. */
+    rotateSnapDeg?: number;
+    /** Round the scale factor to this step. Default: no snapping. */
+    scaleSnap?: number;
+    /** Smallest scale a drag can reach. Default `0.05`. */
+    minScale?: number;
+    /** A drag started. */
+    onTransformStart?: (target: TransformGizmoTarget) => void;
+    /** Fires continuously while dragging. */
+    onTransformChange?: (change: TransformGizmoChange) => void;
+    /** Fires once, on pointer release. */
+    onTransformEnd?: (change: TransformGizmoChange) => void;
 }
 
 /**
- * Viewer errors.
+ * Module catalog (3D-canonical).
  *
- * `XtsViewerErrorException` is the one runtime value in the public type
- * surface — everything else the viewer exports as `types` is erased at
- * compile time. It is thrown by the normalization pass for configurations
- * that cannot be rendered at all; recoverable problems are reported through
- * the `onError` callback as plain `XtsViewerError` records instead.
- */
-type XtsViewerErrorCode = 'asset-load-failed' | 'unknown-module-type' | 'unknown-mover-type' | 'unknown-tool-type' | 'invalid-config' | 'unmatched-clothoid-half' | 'webgl-context-lost';
-interface XtsViewerError {
-    code: XtsViewerErrorCode;
-    message: string;
-    details?: unknown;
-}
-declare class XtsViewerErrorException extends Error {
-    readonly code: XtsViewerErrorCode;
-    readonly details?: unknown;
-    constructor(code: XtsViewerErrorCode, message: string, details?: unknown);
-}
-
-/**
- * Asset manifest — per-type overrides for the GLB URLs the viewer loads.
+ * Every module declares its path topology (Straight / Curve / Free), its
+ * arc length, and — for curves — the signed end-of-module yaw delta in
+ * degrees. Centerline radius for analytic curves is derived from
+ * `R = L / |θ_rad|`.
  *
- * A host registers custom or relocated assets here instead of replacing the
- * whole `assetsBaseUrl`. Entries fall back to the default CDN mapping for any
- * type they do not name.
+ * Hygienic ATH variants share path math with their AT pendants — only the
+ * GLB mesh differs.
+ *
+ * This file is hand-curated. The geometry module imports from here directly
+ * (no JSON fetch) so the library has zero runtime data deps.
  */
 
-interface AssetManifest {
-    /** Override per moduleType. Falls back to default mapping otherwise. */
-    modules?: Partial<Record<ModuleType3D, ModuleAssetEntry>>;
-    movers?: Partial<Record<MoverType3D, MoverAssetEntry>>;
-    tools?: Partial<Record<MoverToolType3D, MoverToolAssetEntry>>;
-    guidingRails?: Partial<Record<RailType3D, RailAssetEntry>>;
+type PathType = 'Straight' | 'Curve' | 'Free';
+interface ModuleCatalogEntry {
+    moduleType: ModuleType3D;
+    /** Arc length along the centerline, in mm. */
+    moduleLengthMm: number;
+    pathType: PathType;
+    /**
+     * Encoder-side end-of-module yaw, in degrees, in the module-local 3D frame.
+     * Sign convention: positive endAngle ⇒ Y-flip math curves toward
+     * −Y (= right of path). 0 for Straight. 180 for AT2050_*_180 free path.
+     */
+    endAngleDeg: number;
+    /**
+     * Centerline radius for analytic curves, in mm. `null` for Straight + Free.
+     * Computed as R = L / |θ_rad|; equals 636.6198 for ±22.5° and 318.3099 for
+     * ±45° curves at L=250.
+     */
+    centerlineRadiusMm: number | null;
+    /**
+     * Free-path point cloud reference. Only set for `pathType==='Free'`.
+     * The string identifies the cloud by name; the actual data lives in
+     * geometry/PointClouds.ts.
+     */
+    freePathId?: string;
+    /** True if STP is not delivered yet. */
+    prepared?: boolean;
+    /** True for Einspeisemodule (power feed-in variants). */
+    isInfeed?: boolean;
 }
-interface RailAssetEntry {
-    glbUrl: string;
-    sidecarUrl?: string;
+declare const MODULE_CATALOG: Readonly<Record<ModuleType3D, ModuleCatalogEntry>>;
+/**
+ * Beckhoff XTS infeed module types (Einspeisemodule). Convenience constant
+ * for use with `moduleHighlights` on `<XtsViewer3D>`.
+ *
+ * Derived from the catalog (`isInfeed` flag) so it never drifts out of sync —
+ * mark a new module with `isInfeed: true` in `MODULE_CATALOG` and it is
+ * automatically included here.
+ */
+declare const INFEED_MODULE_TYPES: readonly ModuleType3D[];
+/** Lookup with type-narrowing. Returns undefined for unknown types. */
+declare function getModuleEntry(moduleType: ModuleType3D): ModuleCatalogEntry | undefined;
+/** Type-guard for safe lookups from untyped (e.g. JSON) sources. */
+declare function isKnownModuleType(value: string): value is ModuleType3D;
+
+/**
+ * ChainBuilder — builds the per-module `startWorldMatrix` for a Part.
+ *
+ * Chain composition (simplified — modules butt up edge-to-edge in this build):
+ *   chain_world = Identity
+ *   for each module_i:
+ *     module_i.startWorldMatrix       = chain_world
+ *     module_i.startPositionInPartMm  = cumulative
+ *     module_i.trackLengthMm          = module_i.moduleLengthMm
+ *     cumulative                     += trackLengthMm
+ *     end_local = T( ΔX, -ΔY_canvas, 0 ) ⊗ R_z( -θ )
+ *     chain_world = chain_world ⊗ end_local
+ *
+ * `chain_world` is a planar pose: 2D translation (X,Y) + Z-yaw. We carry it as
+ * a tiny struct rather than a full 4×4 to keep the pure-math layer free of
+ * Three.js. A Three.js helper in PathBuilder.ts converts to Matrix4 on demand.
+ */
+
+/** Planar pose (X,Y,yaw) in a 3D-RH-Z-up frame. Z is always 0 here. */
+interface PlanarPose {
+    positionMm: Vec3;
+    yawDeg: number;
 }
-interface ModuleAssetEntry {
-    /** Per-RailSystem GLB URL (relative to assetsBaseUrl). */
-    glbByRailSystem: {
-        Beckhoff: string | null;
-        HepcoGfx?: string | null;
+declare const IDENTITY_POSE: PlanarPose;
+interface BuiltModule {
+    moduleType: ModuleType3D;
+    catalog: ModuleCatalogEntry;
+    /** Pose of the module-local origin (= path entry). */
+    startWorldPose: PlanarPose;
+    /** Distance along the part where this module starts (mm). */
+    startPositionInPartMm: number;
+    /** moduleLength (mm). Used for findModuleContaining. */
+    trackLengthMm: number;
+    /** Forwarded from `ModuleEntry.globalNumber` — index into the runtime
+     *  `ModuleStatusStore` so renderers can subscribe per module. */
+    globalNumber?: number;
+    /** Forwarded from `ModuleEntry.status` so the renderer can light up
+     *  the per-module drive-status overlay without an extra lookup. */
+    status?: {
+        warning?: boolean;
+        error?: boolean;
     };
-    sidecarUrl?: string;
-}
-interface MoverAssetEntry {
-    glbUrl: string;
-    sidecarUrl?: string;
 }
-interface MoverToolAssetEntry {
-    glbUrl: string;
-    sidecarUrl?: string;
+interface BuiltChain {
+    modules: BuiltModule[];
+    /** Σ moduleLength_i. */
+    trackLengthMm: number;
+    /** End-of-chain pose; useful for closure-checks. */
+    endPose: PlanarPose;
 }
-
 /**
- * Public types for the measurement + annotation feature.
+ * Build a chain from a part's module list.
  *
- * Everything here is expressed in the viewer's WORLD frame — millimetres,
- * Z-up, identical to `XtsViewer3DRef.getMoverWorldTransform()` and
- * `CameraState.positionMm`. That is what makes one implementation serve both
- * the perspective 3D view and the orthographic 2D plan view
- * (`projection='orthographic'`): only the camera differs, the geometry does
- * not.
+ * Throws XtsViewerErrorException with code `unknown-module-type` on lookup
+ * miss.
+ */
+declare function buildChain(modules: ReadonlyArray<ModuleEntry>): BuiltChain;
+/**
+ * Locate the module containing `partPositionMm` along the chain.
+ * First module with partPosition < startInPart + trackLength; at boundary
+ * `partPosition == trackLength` the LAST module is returned with
+ * `localPos = trackLength`.
  */
+declare function findModuleAt(chain: BuiltChain, partPositionMm: number): {
+    module: BuiltModule;
+    localPosMm: number;
+} | null;
+/**
+ * Mover world pose at `partPositionMm`.
+ *
+ * The module's startWorldPose is composed with the local path sample at
+ * `localPosMm` along that module's path.
+ */
+declare function moverWorldAt(chain: BuiltChain, partPositionMm: number): PlanarPose | null;
+/** Convenience: chain from full ModuleEntry[] returning trackLength alone. */
+declare function trackLengthOf(modules: ReadonlyArray<ModuleEntry>): number;
 
 /**
- * How a measurement point was derived. `'free'` is the raw ray hit (surface
- * or ground plane); everything else is a snap the picker resolved to.
+ * 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)
  */
-type SnapKind = 'free' | 'vertex' | 'edge-midpoint' | 'face-center' | 'grid' | 'mover-center' | 'module-boundary' | 'module-center' | 'station-stop' | 'track-path';
-/** Scene entity a picked point belongs to, when the picker could resolve one. */
-type MeasuredEntityRef = {
-    kind: 'module';
-    ref: ModuleRef;
-} | {
-    kind: 'mover';
-    ref: MoverRef;
-} | {
-    kind: 'station';
-    stationId: number;
-};
-/** A position on a part's track path, in the XPU's user position frame. */
-interface TrackAnchor {
-    processingUnitObjectId: number;
-    /** `PartConfig.objectId`. */
-    partObjectId: number;
-    /** Position along the part, user frame (same convention as movers). */
-    partPositionMm: number;
-}
-/** One measurement vertex. */
-interface MeasurementPoint {
-    /** World position (mm). */
-    positionMm: Vec3;
-    /** How the point was obtained. Default `'free'` when omitted. */
-    snap?: SnapKind;
-    /** Entity the point sits on, when known. */
-    entity?: MeasuredEntityRef;
-    /**
-     * Track position, set whenever the point resolved onto a part's path.
-     * Required on both endpoints of a `'trackDistance'` measurement.
-     */
-    track?: TrackAnchor;
-}
-/** Snapping configuration. */
-interface SnapOptions {
-    /** Master switch. Default `true`. */
-    enabled?: boolean;
-    /**
-     * Snap kinds to consider, highest priority first. Default:
-     * `['vertex', 'edge-midpoint', 'mover-center', 'module-boundary',
-     *   'station-stop', 'track-path', 'face-center']`.
-     */
-    kinds?: SnapKind[];
-    /** Screen-space radius (px) a candidate must fall within. Default `14`. */
-    radiusPx?: number;
+
+interface NormalizedXtsConfig extends XtsConfig {
     /**
-     * Grid step (mm) for the `'grid'` snap, applied to the free hit point when
-     * no other candidate matched and `'grid'` is in `kinds`. Default `0` (off).
+     * 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.
      */
-    gridMm?: number;
-}
-type MeasurementId = string;
-type MeasurementKind = 'distance' | 'angle' | 'path' | 'trackDistance';
-/** Axis constraint for a distance measurement. */
-type MeasurementAxis = 'free' | 'x' | 'y' | 'z';
-interface MeasurementBase {
-    id: MeasurementId;
-    /** Optional caption rendered above the value. */
-    label?: string;
-    /** Overrides `MeasurementStyle.color` for this one measurement. */
-    color?: string;
-    /** Default `true`. */
-    visible?: boolean;
-    /** Free-form payload the host can round-trip (never read by the viewer). */
-    meta?: Record<string, unknown>;
-}
-/** Straight-line distance between two points. */
-interface DistanceMeasurement extends MeasurementBase {
-    kind: 'distance';
-    points: [MeasurementPoint, MeasurementPoint];
-    /** Constrain the reported value to one axis. Default `'free'`. */
-    axis?: MeasurementAxis;
-    /** Render dashed ΔX / ΔY / ΔZ guides. Default `false`. */
-    showComponents?: boolean;
-}
-/** Angle at `points[1]` between the legs to `points[0]` and `points[2]`. */
-interface AngleMeasurement extends MeasurementBase {
-    kind: 'angle';
-    /** `[legA, vertex, legB]` — the middle point is the vertex. */
-    points: [MeasurementPoint, MeasurementPoint, MeasurementPoint];
+    readonly __warnings: NormalizationWarning[];
 }
-/** Polyline through N points; reports per-segment and total length. */
-interface PathMeasurement extends MeasurementBase {
-    kind: 'path';
-    points: MeasurementPoint[];
-    /** Close the polyline back to the first point. Default `false`. */
-    closed?: boolean;
-    /** Label every segment, not just the total. Default `true`. */
-    showSegmentLengths?: boolean;
+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;
 }
 /**
- * Distance ALONG the XTS track between two points on the same part — the
- * distance a mover actually travels, not the straight line.
+ * 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.
  */
-interface TrackDistanceMeasurement extends MeasurementBase {
-    kind: 'trackDistance';
-    points: [MeasurementPoint, MeasurementPoint];
+declare class XtsConfigNormalizer {
+    normalize(config: XtsConfig): NormalizedXtsConfig;
+    /** No-op. Kept so existing callers keep compiling; there is no cache. */
+    clearCache(): void;
 }
-type Measurement = DistanceMeasurement | AngleMeasurement | PathMeasurement | TrackDistanceMeasurement;
-/** Same as `Measurement`, but the store generates the `id` when omitted. */
-type MeasurementInput = (Omit<DistanceMeasurement, 'id'> & {
-    id?: MeasurementId;
-}) | (Omit<AngleMeasurement, 'id'> & {
-    id?: MeasurementId;
-}) | (Omit<PathMeasurement, 'id'> & {
-    id?: MeasurementId;
-}) | (Omit<TrackDistanceMeasurement, 'id'> & {
-    id?: MeasurementId;
-});
-/** Computed value of a measurement. */
-interface MeasurementResult {
-    id: MeasurementId;
-    kind: MeasurementKind;
-    /** Millimetres for lengths, degrees for angles. */
-    value: number;
-    unit: 'mm' | 'deg';
-    /** Formatted value as rendered in the scene (e.g. `'1 234.5 mm'`). */
-    text: string;
-    /** Signed component deltas — `'distance'` only. */
-    deltaMm?: Vec3;
-    /** Per-segment lengths — `'path'` only. */
-    segmentLengthsMm?: number[];
+declare function normalizeXtsConfig(config: XtsConfig): NormalizedXtsConfig;
+
+/**
+ * Mover collision detection.
+ *
+ * Sub-millimetre accurate for the dominant XTS case: two movers travelling
+ * along the same chain. Each mover occupies a 1D footprint of
+ * `pathLengthMm` centred on `partPositionMm`, so the collision predicate
+ * collapses to one subtraction in path-space:
+ *
+ *     centerDistance = arc-length |pos_a − pos_b|
+ *     requiredGap    = (pathLength_a + pathLength_b) / 2
+ *     penetration    = requiredGap − centerDistance
+ *     collision iff  penetration > 0  (≥ 0 for "touching")
+ *
+ * For closed-loop chains (oval tracks, U-turn pairs) the arc-length is
+ * taken as the *minimum* of the forward and the wrap-around path so two
+ * movers near the seam (e.g. 50 mm and trackLength − 50 mm) are treated
+ * as physically adjacent. Open chains are detected by comparing the
+ * chain's start- and end-pose; for those the wrap-around distance is
+ * simply not considered.
+ *
+ * Floating-point precision: positions are kept in mm in float64. A typical
+ * XTS layout has trackLength ≤ 20 m → < 2×10⁴ mm, well inside the
+ * 2⁵³-mantissa range, so subtractive cancellation costs at most ~10⁻¹²
+ * mm — orders of magnitude below sub-millimetre.
+ *
+ * Multi-XPU (different chains): not handled here. Cross-track collisions
+ * are dominated by track-transform layout and would need an OBB / mesh
+ * test in 3D space; that's a different concern from "two movers on the
+ * same line about to crash".
+ */
+
+/**
+ * One detected pair. Result list is symmetric (a/b is reported once per
+ * pair, with `a` carrying the lower index pair-canonical).
+ */
+interface MoverCollision {
+    a: MoverRef;
+    b: MoverRef;
     /**
-     * `true` when the measurement could not be evaluated (e.g. a
-     * `trackDistance` whose endpoints sit on different parts). `value` is then
-     * the straight-line fallback.
+     * Stable IDs of the two movers (mirrors `MoverConfig.id`). Useful when
+     * the consumer keys by id rather than by `moverIndex`.
      */
-    incomplete?: boolean;
-}
-/** Where an annotation hangs. Mover anchors follow the live mover position. */
-type AnnotationAnchor = {
-    kind: 'world';
-    positionMm: Vec3;
-} | {
-    kind: 'mover';
-    ref: MoverRef;
-} | {
-    kind: 'module';
-    ref: ModuleRef;
-} | ({
-    kind: 'trackPosition';
-} & TrackAnchor);
-interface Annotation {
-    id: string;
-    text: string;
-    anchor: AnnotationAnchor;
+    idA: number;
+    idB: number;
     /**
-     * Leader-line offset from the anchor to the label (mm, world frame).
-     * Default `[0, 0, 250]`.
+     * Penetration along the 1D path:
+     *   • `> 0` — movers overlap by this many mm.
+     *   • `= 0` — touching exactly.
+     *   • `< 0` — closest-approach gap (only present in result when
+     *             `warningGapMm` is set; the magnitude is the free-space
+     *             distance between the closer footprint edges).
      */
-    offsetMm?: Vec3;
-    color?: string;
-    /** Text height (mm). Default `MeasurementStyle.labelSizeMm`. */
-    sizeMm?: number;
-    /** Marker drawn at the anchor. Default `'Sphere'`. */
-    markerShape?: MarkerShape;
-    markerSizeMm?: number;
-    /** Default `true`. */
-    visible?: boolean;
-    meta?: Record<string, unknown>;
-}
-type AnnotationInput = Omit<Annotation, 'id'> & {
-    id?: string;
-};
-type MeasurementTool = 'none' | 'distance' | 'angle' | 'path' | 'trackDistance' | 'annotation';
-/** In-progress pick. `null` while no tool is armed. */
-interface MeasurementDraft {
-    tool: Exclude<MeasurementTool, 'none'>;
-    /** Points committed so far. */
-    points: MeasurementPoint[];
-    /** Point currently under the cursor, or `null` when off the scene. */
-    hover: MeasurementPoint | null;
-}
-interface MeasurementStyle {
-    /** Line + label colour of committed measurements. Default `'#00E5FF'`. */
-    color?: string;
-    /** Colour of the in-progress draft. Default `'#FFC400'`. */
-    draftColor?: string;
-    /** Annotation colour. Default `'#FFFFFF'`. */
-    annotationColor?: string;
-    /** Line width in pixels. Default `2`. */
-    lineWidthPx?: number;
-    /** Text height (mm). Default `40`. */
-    labelSizeMm?: number;
-    /** Endpoint marker diameter (mm). Default `18`. */
-    pointSizeMm?: number;
-    /** Decimal places on values. Default `1`. */
-    decimals?: number;
-    /** Unit suffix appended to lengths. Default `' mm'`. */
-    unitSuffix?: string;
-    /** Font URL passed to troika (see `DEFAULT_LABEL_FONT_URL`). */
-    fontFamily?: string;
+    penetrationMm: number;
     /**
-     * Draw measurement lines and markers through solid geometry
-     * (`depthTest: false`). Default `true` — CAD viewers keep dimensions
-     * readable regardless of what is in front of them.
+     * Both `partPositionMm` values at the time of the test. Lets the
+     * consumer recompute or visualise without re-querying.
      */
-    alwaysOnTop?: boolean;
+    positionAMm: number;
+    positionBMm: number;
+    /** Mover lengths (catalog `pathLengthMm`). */
+    pathLengthAMm: number;
+    pathLengthBMm: number;
+    /** True when measurement wrapped around the chain end (closed-loop seam). */
+    viaWraparound: boolean;
 }
-/** Serializable snapshot of everything the measurement feature holds. */
-interface MeasurementDocument {
-    schemaVersion: 1;
-    measurements: Measurement[];
-    annotations: Annotation[];
+interface CheckMoverCollisionsOptions {
+    /**
+     * When `> 0`, near-misses with closest-approach gap up to this many mm
+     * are also returned (with `penetrationMm < 0`). Default 0 — only actual
+     * collisions / contacts.
+     */
+    warningGapMm?: number;
+    /**
+     * Force-treat the chain as closed (consider wrap-around distance) or
+     * open (don't). When omitted, auto-detected by comparing
+     * `chain.endPose` to `startPose ≈ identity` within ~0.1 mm tolerance.
+     */
+    forceClosedLoop?: boolean;
 }
 /**
- * `measurement` prop of `<XtsViewer3D>`. Data can be driven either
- * declaratively (`measurements` / `annotations` — controlled arrays) or
- * imperatively via `viewerRef.current.measurements`. When the controlled
- * arrays are supplied they win on every render, so a host that uses them must
- * persist what the change callbacks report.
+ * Effective mover state passed into the predicate. Decoupled from
+ * MoverConfig so consumers can plug in live positions from the
+ * MoverPositionStore (60-Hz tick) without round-tripping through React
+ * state.
  */
-interface MeasurementOptions {
-    /** Armed tool. Default `'none'` — no picking, no cursor change. */
-    tool?: MeasurementTool;
-    /** Controlled measurement list. Omit to let the viewer keep its own. */
-    measurements?: MeasurementInput[];
-    /** Controlled annotation list. Omit to let the viewer keep its own. */
-    annotations?: AnnotationInput[];
-    snap?: SnapOptions;
-    style?: MeasurementStyle;
-    /**
-     * Z of the fallback pick plane (mm) used when the ray misses all geometry,
-     * so free space can be measured. Default `0`; `null` disables the fallback.
-     */
-    groundPlaneZMm?: number | null;
-    /** Fired after every change to the measurement list. */
-    onMeasurementsChange?: (measurements: Measurement[], results: MeasurementResult[]) => void;
-    /** Fired once when a tool completes a measurement. */
-    onMeasurementCreate?: (measurement: Measurement, result: MeasurementResult) => void;
-    onAnnotationsChange?: (annotations: Annotation[]) => void;
-    onAnnotationCreate?: (annotation: Annotation) => void;
-    /** Fired on every draft change (point added, hover moved, cancelled). */
-    onDraftChange?: (draft: MeasurementDraft | null) => void;
+interface MoverProbe {
+    ref: MoverRef;
+    id: number;
+    partOid: number;
+    moverType: MoverType3D;
+    partPositionMm: number;
     /**
-     * Text for an annotation the `'annotation'` tool just placed. Return
-     * `null` to abort. Default: `'Annotation'`.
+     * Override the catalog `pathLengthMm`. Use for `Custom` movers where
+     * the layout's `pathLengthMm` is the source of truth.
      */
-    annotationTextFactory?: (point: MeasurementPoint) => string | null;
+    pathLengthMm?: number;
 }
-
 /**
- * `XtsModelDocument` — the canonical serialized form of a viewer scene.
+ * Pair-wise 1D collision test for movers on the same chain.
  *
- * What `viewerRef.current.exportModel()` produces and what a host persists:
- * the configuration, optionally the runtime mover state, and optionally the
- * measurements. The measurement half keeps its own types next to its
- * implementation (`measurement/types.ts`); only the serialized document
- * surfaces here.
- */
-
-interface XtsModelDocument {
-    schemaVersion: 1;
-    meta: {
-        generatedAt: string;
-        generator: string;
-        sourceFormat?: string;
-        sourceFileHash?: string;
-    };
-    config: XtsConfig;
-    runtime?: XtsRuntimeState;
-    railSystem?: RailSystem | {
-        byProcessingUnit: Record<number, RailSystem>;
-    };
-    /**
-     * Measurements + annotations placed on the layout, as returned by
-     * `XtsViewer3DRef.measurements.toJSON()`. Omitted when there are none, so
-     * documents written before the measurement feature stay byte-identical.
-     */
-    measurements?: MeasurementDocument;
-}
-interface XtsRuntimeState {
-    movers: Array<{
-        processingUnitObjectId: number;
-        moverIndex: number;
-        id: number;
-        partOid: number;
-        partPositionMm: number;
-        velocity?: {
-            mmPerSec: number;
-        };
-        status?: {
-            warning?: boolean;
-            error?: boolean;
-        };
-    }>;
-    selection?: SelectionState;
-    camera?: CameraState;
-    display?: Partial<DisplayOptions>;
-}
+ * `chain` is the BuiltChain corresponding to the partOid all probed
+ * movers travel on. `probes` may contain movers from *any* part — this
+ * function only considers pairs where `partOid` matches the chain.
+ *
+ * Returns one entry per colliding (or near-miss, when `warningGapMm > 0`)
+ * pair, sorted by `penetrationMm` descending so the deepest collisions
+ * 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[];
 
 /**
- * SidecarLoader — fetches per-asset JSON sidecars.
+ * Module collision / overlap detection.
  *
- * 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).
+ * The mover collision (moverCollision.ts) is a 1D arc-length test for two
+ * movers on the *same* chain; its header explicitly declines cross-XPU /
+ * cross-track cases, which "would need an OBB / mesh test in 3D space".
+ * This file is exactly that test, for the physical track *modules*.
  *
- * 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.
+ * Each module is modelled as a chain of oriented bounding boxes (OBBs) that
+ * follow its real centerline: the path is sampled (sampleModulePath) and each
+ * segment becomes a small box (±halfWidth in Y, 0..height in Z) oriented along
+ * the local tangent, then transformed into world space by
+ *
+ *     world = orientation ⊗ trackTransform ⊗ partTransformation ⊗ chainPose
+ *
+ * Sampling the path (rather than a single straight box per module) is what
+ * keeps curves and U-turns faithful — a single straight box would poke
+ * outside the arc and produce both false positives and false negatives on a
+ * closed oval. Straights collapse to one box; curves / free paths use several.
+ *
+ * Pairs are tested with the Separating Axis Theorem (15 axes) over their
+ * segment boxes, yielding a penetration depth (minimum translation distance)
+ * as `overlapMm`:
+ *
+ *     overlapMm  > 0  — boxes overlap by this many mm (deepest sub-box pair).
+ *     overlapMm  = 0  — touching exactly.
+ *     overlapMm  < 0  — closest-approach gap (only reported when
+ *                       `warningGapMm` is set).
+ *
+ * Adjacent modules in the same part butt up edge-to-edge (ChainBuilder), so
+ * consecutive `(i, i+1)` pairs — and the `(N-1, 0)` seam of a closed loop —
+ * are excluded; everything else (cross-part, cross-XPU, same-part
+ * non-adjacent) is tested.
+ *
+ * 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.
  */
 
-interface OriginCorrection {
-    translateMm: Vec3;
-    rotationDegEuler: Vec3;
+/** Default box half-width (Y) — matches `approximateModuleBounds`. */
+declare const DEFAULT_MODULE_HALF_WIDTH_MM = 50;
+/** Default box height (Z) — matches `approximateModuleBounds`. */
+declare const DEFAULT_MODULE_HEIGHT_MM = 100;
+/**
+ * One detected pair. Symmetric: `a`/`b` are canonicalised so the lower
+ * `(processingUnitObjectId, partObjectId, moduleIndex)` tuple is always `a`.
+ */
+interface ModuleCollision {
+    a: ModuleRef;
+    b: ModuleRef;
+    moduleTypeA: ModuleType3D;
+    moduleTypeB: ModuleType3D;
+    /** Forwarded `ModuleEntry.globalNumber` (status-store key), if present. */
+    globalNumberA?: number;
+    globalNumberB?: number;
+    /**
+     * Penetration depth along the minimum-translation axis of the deepest
+     * sub-box pair:
+     *   • `> 0` — overlap (mm).
+     *   • `= 0` — touching.
+     *   • `< 0` — closest-approach gap (only when `warningGapMm` is set).
+     */
+    overlapMm: number;
+    /** Centre-to-centre distance of the deepest sub-box pair (mm). */
+    centerDistanceMm: number;
+    /** Unit world-space axis of least penetration (the MTV direction). */
+    axis: Vec3;
 }
-interface ModuleSidecar {
+interface CheckModuleCollisionsOptions {
+    /**
+     * When `> 0`, near-misses with an axis-projected gap up to this many mm
+     * are also returned (with `overlapMm < 0`). Default 0 — only actual
+     * overlaps / contacts.
+     */
+    warningGapMm?: number;
+    /**
+     * Also test non-adjacent module pairs within the SAME part. Default true.
+     * Consecutive `(i, i+1)` pairs and the closed-loop `(N-1, 0)` seam are
+     * ALWAYS excluded regardless of this flag.
+     */
+    includeSamePart?: boolean;
+    /** Box half-width in Y (mm). Default 50. */
+    halfWidthMm?: number;
+    /**
+     * 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). */
+interface Obb {
+    center: Vector3;
+    axes: [Vector3, Vector3, Vector3];
+    halfExtents: [number, number, number];
+    /** Bounding-sphere radius (broad-phase reject). */
+    radius: number;
+}
+/** Pre-built per-module probe consumed by `checkModuleCollisions`. */
+interface ModuleProbe {
+    ref: ModuleRef;
     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;
-    };
+    globalNumber?: number;
+    /** Adjacency grouping key (part.globalNumber — system-wide unique). */
+    partKey: number;
+    /** Index of this module within its part's chain. */
+    moduleIndex: number;
+    /** Segment boxes following the module centerline (≥ 1). */
+    obbs: Obb[];
+    /** Module-level bounding sphere enclosing all segment boxes. */
+    sphereCenter: Vector3;
+    sphereRadius: number;
 }
-interface MoverSidecar {
-    moverType: MoverType3D;
-    glb: string;
-    originCorrection: OriginCorrection;
-    magnetPlateCenterMm: Vec3;
-    pathLengthMm: number;
+/** A part fed to `buildModuleProbes`. */
+interface ModuleCollisionPartInput {
+    /** ModuleRef.partObjectId (`PartConfig.objectId`). */
+    partObjectId: number;
+    /** Adjacency key (`PartConfig.globalNumber`). */
+    partKey: number;
+    partTransformation?: PartTransformation | null;
+    chain: BuiltChain;
 }
-interface MoverToolSidecar {
-    toolType: MoverToolType3D;
-    glbUrl: string;
-    originCorrection: OriginCorrection;
-    defaultOffsetMm: Vec3;
-    approximateBoundsMm?: {
-        min: Vec3;
-        max: Vec3;
-    };
-    label: string;
+/** An XPU fed to `buildModuleProbes`. */
+interface ModuleCollisionXpuInput {
+    xpuObjectId: number;
+    /** Effective (override-resolved) per-XPU track transform. */
+    trackTransform?: TrackTransform | null;
+    parts: ReadonlyArray<ModuleCollisionPartInput>;
 }
 /**
- * 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.
+ * Turn a list of XPUs (with effective track transforms) + parts (with built
+ * chains) into flat module probes plus a per-part adjacency map. Shared by
+ * the imperative ref and the reactive monitor so the world-matrix
+ * composition lives in one place.
+ *
+ * Hidden XPUs / parts (`visible === false`) are skipped to match the scene.
  */
-interface RailSidecar {
-    railType: RailType3D;
-    glb: string;
-    originCorrection: OriginCorrection;
-    approximateBoundsMm?: {
-        min: Vec3;
-        max: Vec3;
-    };
-}
-declare const DEFAULT_ORIGIN_CORRECTION: OriginCorrection;
+declare function buildModuleProbes(orientation: Orientation | undefined, xpus: ReadonlyArray<ModuleCollisionXpuInput>, opts?: CheckModuleCollisionsOptions): {
+    probes: ModuleProbe[];
+    adjacency: Map<number, {
+        count: number;
+        closed: boolean;
+    }>;
+};
 /**
- * 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).
+ * Pairwise OBB overlap test over all module probes. Same-part consecutive
+ * and closed-loop-seam pairs are excluded; everything else is tested.
+ * Returns one entry per overlapping (or near-miss, when `warningGapMm > 0`)
+ * pair, sorted deepest-overlap-first.
  */
-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;
-    };
-}
+declare function checkModuleCollisions(probes: ReadonlyArray<ModuleProbe>, adjacency: ReadonlyMap<number, {
+    count: number;
+    closed: boolean;
+}>, opts?: CheckModuleCollisionsOptions): ModuleCollision[];
 /**
- * Pure helper: pick the GLB filename with rail-system fallback. Returns null
- * when the entry marks the module 'prepared but not delivered'.
+ * 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.
  *
- * 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.
+ * 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.
+ *
+ * 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 function pickGlbForRail(entry: GlbByRailSystem | undefined, rail: RailSystem): string | null;
+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[];
 
 /**
- * Option shapes shared between the public `<XtsViewer3D>` props and the
- * internal `<XtsScene>` / `<ProcessingUnitRoot>` props.
+ * Interaction surface — selection, highlighting and the camera.
  *
- * 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.
+ * The types a host exchanges with the viewer at runtime rather than at
+ * configuration time: what is addressed (`ModuleRef`, `MoverRef`), what is
+ * picked out (`SelectionState`, `ModuleHighlight`, `FeedSegmentHighlight`),
+ * and where the camera looks (`CameraState`, `FocusTarget`).
  */
 
-/** Where the view cube sits in the canvas. */
-type ViewCubeAlignment = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center' | 'center-left' | 'center-right' | 'center-center';
-interface ViewCubeOptions {
-    enabled?: boolean;
-    /** Default `'bottom-right'`. */
-    alignment?: ViewCubeAlignment;
-    /** Distance from the aligned corner, in CSS px. Default `[80, 80]`. */
-    marginPx?: [number, number];
+interface ModuleRef {
+    processingUnitObjectId: number;
+    partObjectId: number;
+    moduleIndex: number;
 }
-/** Interaction locks. Each `true` disables that interaction. */
-interface InteractionLocks {
-    rotate?: boolean;
-    pan?: boolean;
-    zoom?: boolean;
-    selection?: boolean;
+interface MoverRef {
+    processingUnitObjectId: number;
+    moverIndex: number;
 }
-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;
+/**
+ * Addresses a whole track — one processing unit with everything anchored to
+ * it: its modules, movers, tools and overlays.
+ */
+interface TrackRef {
+    processingUnitObjectId: number;
+}
+/**
+ * Addresses one entry of `XtsConfig.customAssets` by its `id`. Only assets
+ * with a `'static'` binding are pickable — a mover-bound asset rides its
+ * mover and is selected by selecting that mover.
+ */
+interface CustomAssetRef {
+    assetId: string;
+}
+interface SelectionState {
+    modules: ModuleRef[];
+    movers: MoverRef[];
     /**
-     * Opt into the WebGPU renderer when the browser supports it. Falls back to
-     * WebGL automatically. Default: false (experimental).
+     * Selected whole tracks — what a click produces under
+     * `selectionScope: 'track'`. A selected track counts as selecting
+     * everything on it: `isModuleSelected` and `isMoverSelected` both answer
+     * `true` for its contents, so the whole track tints as one.
      */
-    webgpu?: boolean;
+    tracks?: TrackRef[];
     /**
-     * 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.
+     * Selected static custom assets. Optional so a host that only ever
+     * selects modules and movers keeps building the object it always did.
      */
-    ktx2TranscoderUrl?: string;
+    customAssets?: CustomAssetRef[];
 }
-/**
- * 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>>;
-    rails?: Partial<Record<RailType3D, OriginCorrection>>;
+/** Per-entity selection highlight colours. */
+interface SelectionColors {
+    module?: string;
+    mover?: string;
+    customAsset?: string;
 }
-
+type SelectionMode = 'Off' | 'Single' | 'Multi';
 /**
- * Module catalog (3D-canonical).
+ * What a click into the track picks out.
  *
- * Every module declares its path topology (Straight / Curve / Free), its
- * arc length, and — for curves — the signed end-of-module yaw delta in
- * degrees. Centerline radius for analytic curves is derived from
- * `R = L / |θ_rad|`.
+ *   - `'module'` (default) — the module or mover clicked, as before.
+ *   - `'track'` — the whole processing unit it belongs to, whichever of its
+ *     parts was hit. Individual modules and movers cannot be selected in
+ *     this scope at all.
  *
- * Hygienic ATH variants share path math with their AT pendants — only the
- * GLB mesh differs.
+ * A static custom asset is always selected in its own right: it stands free
+ * in the scene rather than on a track.
  *
- * This file is hand-curated. The geometry module imports from here directly
- * (no JSON fetch) so the library has zero runtime data deps.
+ * This is what the transform gizmo follows. A module has no pose of its own
+ * — modules bolt together end-to-end along the chain — so a module
+ * selection never grows handles; a track selection does.
  */
-
-type PathType = 'Straight' | 'Curve' | 'Free';
-interface ModuleCatalogEntry {
-    moduleType: ModuleType3D;
-    /** Arc length along the centerline, in mm. */
-    moduleLengthMm: number;
-    pathType: PathType;
-    /**
-     * Encoder-side end-of-module yaw, in degrees, in the module-local 3D frame.
-     * Sign convention: positive endAngle ⇒ Y-flip math curves toward
-     * −Y (= right of path). 0 for Straight. 180 for AT2050_*_180 free path.
-     */
-    endAngleDeg: number;
-    /**
-     * Centerline radius for analytic curves, in mm. `null` for Straight + Free.
-     * Computed as R = L / |θ_rad|; equals 636.6198 for ±22.5° and 318.3099 for
-     * ±45° curves at L=250.
-     */
-    centerlineRadiusMm: number | null;
-    /**
-     * Free-path point cloud reference. Only set for `pathType==='Free'`.
-     * The string identifies the cloud by name; the actual data lives in
-     * geometry/PointClouds.ts.
-     */
-    freePathId?: string;
-    /** True if STP is not delivered yet. */
-    prepared?: boolean;
-    /** True for Einspeisemodule (power feed-in variants). */
-    isInfeed?: boolean;
+type SelectionScope = 'module' | 'track';
+/**
+ * Declarative module highlight. All modules whose `moduleType` appears in
+ * `moduleTypes` are tinted with the given `color` — same emissive effect as
+ * selection, but independent of the selection state. Multiple highlights can
+ * overlap; the first matching entry wins.
+ *
+ * Toggle on/off by setting `moduleHighlights` on `<XtsViewer3D>` to an
+ * array (enabled) or `undefined` / `[]` (disabled).
+ */
+interface ModuleHighlight {
+    /** Module types to highlight. */
+    moduleTypes: ModuleType3D[];
+    /** Highlight color (CSS color string, e.g. `'#FF6600'`). */
+    color: string;
 }
-declare const MODULE_CATALOG: Readonly<Record<ModuleType3D, ModuleCatalogEntry>>;
 /**
- * Beckhoff XTS infeed module types (Einspeisemodule). Convenience constant
- * for use with `moduleHighlights` on `<XtsViewer3D>`.
+ * Addresses one feed segment (Einspeisestrang). Either form works — pick
+ * whichever the host has at hand:
  *
- * Derived from the catalog (`isInfeed` flag) so it never drifts out of sync —
- * mark a new module with `isInfeed: true` in `MODULE_CATALOG` and it is
- * automatically included here.
+ *  - `{ infeedModuleGlobalNumber }` — the `ModuleEntry.globalNumber` of the
+ *    infeed module that leads the segment. Stable across layout edits as long
+ *    as the global numbering is stable.
+ *  - `{ partObjectId, segmentIndex }` — ordinal address: `segmentIndex` counts
+ *    0, 1, 2 … in chain order, starting at the part's first infeed module.
  */
-declare const INFEED_MODULE_TYPES: readonly ModuleType3D[];
-/** Lookup with type-narrowing. Returns undefined for unknown types. */
-declare function getModuleEntry(moduleType: ModuleType3D): ModuleCatalogEntry | undefined;
-/** Type-guard for safe lookups from untyped (e.g. JSON) sources. */
-declare function isKnownModuleType(value: string): value is ModuleType3D;
-
+type FeedSegmentSelector = {
+    infeedModuleGlobalNumber: number;
+} | {
+    partObjectId: number;
+    segmentIndex: number;
+};
 /**
- * ChainBuilder — builds the per-module `startWorldMatrix` for a Part.
+ * Declarative feed-segment highlight. Every module belonging to one of the
+ * selected segments is tinted with `color` — same emissive effect as
+ * selection, but independent of the selection state.
  *
- * Chain composition (simplified — modules butt up edge-to-edge in this build):
- *   chain_world = Identity
- *   for each module_i:
- *     module_i.startWorldMatrix       = chain_world
- *     module_i.startPositionInPartMm  = cumulative
- *     module_i.trackLengthMm          = module_i.moduleLengthMm
- *     cumulative                     += trackLengthMm
- *     end_local = T( ΔX, -ΔY_canvas, 0 ) ⊗ R_z( -θ )
- *     chain_world = chain_world ⊗ end_local
+ * Multiple entries are allowed (that is how several segments get several
+ * colors at once); on overlap the first matching entry wins, mirroring
+ * `ModuleHighlight`.
  *
- * `chain_world` is a planar pose: 2D translation (X,Y) + Z-yaw. We carry it as
- * a tiny struct rather than a full 4×4 to keep the pure-math layer free of
- * Three.js. A Three.js helper in PathBuilder.ts converts to Matrix4 on demand.
+ * Toggle on/off by setting `feedSegmentHighlights` on `<XtsViewer3D>` to an
+ * array (enabled) or `undefined` / `[]` (disabled).
  */
-
-/** Planar pose (X,Y,yaw) in a 3D-RH-Z-up frame. Z is always 0 here. */
-interface PlanarPose {
-    positionMm: Vec3;
-    yawDeg: number;
+interface FeedSegmentHighlight {
+    /** Segments to tint. */
+    segments: FeedSegmentSelector[];
+    /** Highlight color (CSS color string, e.g. `'#00AAFF'`). */
+    color: string;
 }
-declare const IDENTITY_POSE: PlanarPose;
-interface BuiltModule {
-    moduleType: ModuleType3D;
-    catalog: ModuleCatalogEntry;
-    /** Pose of the module-local origin (= path entry). */
-    startWorldPose: PlanarPose;
-    /** Distance along the part where this module starts (mm). */
-    startPositionInPartMm: number;
-    /** moduleLength (mm). Used for findModuleContaining. */
-    trackLengthMm: number;
-    /** Forwarded from `ModuleEntry.globalNumber` — index into the runtime
-     *  `ModuleStatusStore` so renderers can subscribe per module. */
-    globalNumber?: number;
-    /** Forwarded from `ModuleEntry.status` so the renderer can light up
-     *  the per-module drive-status overlay without an extra lookup. */
-    status?: {
-        warning?: boolean;
-        error?: boolean;
+/**
+ * One feed segment (Einspeisestrang) as detected in the configuration: the
+ * contiguous run of modules starting at an infeed module (Einspeisemodul,
+ * `ModuleCatalogEntry.isInfeed`) and ending right before the next infeed
+ * module of the same part.
+ *
+ * On a closed chain (oval, U-turn pair — see `isChainClosed`) the modules
+ * ahead of the part's first infeed module belong to the LAST segment, which
+ * then carries `wrapsSeam: true`. On an open chain those leading modules
+ * belong to no segment at all and cannot be tinted.
+ *
+ * Returned by `XtsViewer3DRef.getFeedSegments()`.
+ */
+interface FeedSegment {
+    processingUnitObjectId: number;
+    partObjectId: number;
+    /** 0-based, in chain order, counted from the part's first infeed module. */
+    segmentIndex: number;
+    /**
+     * `ModuleEntry.globalNumber` of the leading infeed module. `undefined` when
+     * the config does not set it — such a segment can only be addressed via
+     * `{ partObjectId, segmentIndex }`.
+     */
+    infeedModuleGlobalNumber?: number;
+    /** Module type of the leading infeed module. */
+    infeedModuleType: ModuleType3D;
+    /** Chain indices of every module in this segment, in chain order. */
+    moduleIndices: number[];
+    /** Σ of the segment's module lengths, in mm. */
+    lengthMm: number;
+    /** True when the segment wraps the closed-loop seam. */
+    wrapsSeam: boolean;
+}
+interface CameraState {
+    positionMm: Vec3;
+    targetMm: Vec3;
+    /** Always 'Z' in the current spec. */
+    upAxis: 'Z' | 'Y';
+    zoom?: number;
+}
+/**
+ * Live camera projection.
+ *   - `'perspective'` (default) — the regular 3D view.
+ *   - `'orthographic'` — gives the flat 2D plan view
+ *     that matches `exportScreenshot({ mode: 'top-down' })`.
+ */
+type CameraProjection = 'perspective' | 'orthographic';
+/**
+ * Target for the imperative `viewerRef.current.focusOn(target, opts)` camera
+ * animation. The viewer computes the target's world-space bounding box and
+ * flies the camera so the whole object fits the frame:
+ *   - In `'perspective'` projection the current view angle is preserved
+ *     (the camera only dollies / re-centres).
+ *   - In `'orthographic'` top-down the frustum is re-framed and the camera
+ *     pans straight over the object.
+ */
+type FocusTarget = {
+    kind: 'scene';
+} | {
+    kind: 'station';
+    stationId: number;
+} | {
+    kind: 'area';
+    areaId: number;
+} | {
+    kind: 'mover';
+    ref: MoverRef;
+} | {
+    kind: 'module';
+    ref: ModuleRef;
+};
+interface FocusOptions {
+    /** Animation duration in ms. Default 700. `0` jumps immediately. */
+    durationMs?: number;
+    /**
+     * Padding around the target's bounding box (1 = tight fit). Default 1.2 in
+     * perspective, 1.1 in orthographic top-down.
+     */
+    paddingFactor?: number;
+    /** Easing curve. Default `'easeInOutCubic'`. */
+    easing?: 'linear' | 'easeInOutCubic';
+}
+/**
+ * Collision monitoring.
+ *
+ * Movers and modules are watched by different machinery — movers move at
+ * 60 Hz through the position store and are checked in `useFrame`, modules
+ * only move when the configuration or a `trackTransform` changes and are
+ * checked in an effect — but from the outside they configure the same way,
+ * which is why they now sit under one prop.
+ */
+interface CollisionOptions {
+    /** Continuous mover collision monitoring. */
+    movers?: MoverCollisionOptions;
+    /**
+     * Static MODULE overlap monitoring. Detects track modules that physically
+     * overlap in 3D space — different XPUs / parts placed via `trackTransform`
+     * / `orientation` / `partTransformation`, plus non-adjacent modules of the
+     * same part. Adjacent (seam) modules and the closed-loop seam are
+     * excluded. Recomputed on config / track-transform change (NOT per-frame,
+     * since modules don't move at 60 Hz) — `onCollisionsChange` fires only
+     * when the overlap set actually changes.
+     */
+    modules?: ModuleCollisionOptions;
+}
+interface MoverCollisionOptions {
+    enabled?: boolean;
+    /** Report a pair as colliding while their gap is below this. Default 0. */
+    warningGapMm?: number;
+    /** Throttle the check (e.g. 50 for 20 Hz). Default 0 = every frame. */
+    intervalMs?: number;
+    /** Treat the part as a closed loop regardless of chain geometry. */
+    forceClosedLoop?: boolean;
+    onCollisionsChange?: (collisions: MoverCollision[]) => void;
+}
+interface ModuleCollisionOptions {
+    enabled?: boolean;
+    /** Report a pair as overlapping while their gap is below this. Default 0. */
+    warningGapMm?: number;
+    onCollisionsChange?: (collisions: ModuleCollision[]) => void;
+}
+
+/**
+ * Viewer errors.
+ *
+ * `XtsViewerErrorException` is the one runtime value in the public type
+ * surface — everything else the viewer exports as `types` is erased at
+ * compile time. It is thrown by the normalization pass for configurations
+ * that cannot be rendered at all; recoverable problems are reported through
+ * the `onError` callback as plain `XtsViewerError` records instead.
+ */
+type XtsViewerErrorCode = 'asset-load-failed' | 'unknown-module-type' | 'unknown-mover-type' | 'unknown-tool-type' | 'invalid-config' | 'unmatched-clothoid-half' | 'webgl-context-lost';
+interface XtsViewerError {
+    code: XtsViewerErrorCode;
+    message: string;
+    details?: unknown;
+}
+declare class XtsViewerErrorException extends Error {
+    readonly code: XtsViewerErrorCode;
+    readonly details?: unknown;
+    constructor(code: XtsViewerErrorCode, message: string, details?: unknown);
+}
+
+/**
+ * Asset manifest — per-type overrides for the GLB URLs the viewer loads.
+ *
+ * A host registers custom or relocated assets here instead of replacing the
+ * whole `assetsBaseUrl`. Entries fall back to the default CDN mapping for any
+ * type they do not name.
+ */
+
+interface AssetManifest {
+    /** Override per moduleType. Falls back to default mapping otherwise. */
+    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 {
+    glbUrl: string;
+    sidecarUrl?: string;
+}
+interface ModuleAssetEntry {
+    /** Per-RailSystem GLB URL (relative to assetsBaseUrl). */
+    glbByRailSystem: {
+        Beckhoff: string | null;
+        HepcoGfx?: string | null;
     };
+    sidecarUrl?: string;
 }
-interface BuiltChain {
-    modules: BuiltModule[];
-    /** Σ moduleLength_i. */
-    trackLengthMm: number;
-    /** End-of-chain pose; useful for closure-checks. */
-    endPose: PlanarPose;
+interface MoverAssetEntry {
+    glbUrl: string;
+    sidecarUrl?: string;
+}
+interface MoverToolAssetEntry {
+    glbUrl: string;
+    sidecarUrl?: string;
+}
+interface MagnetPlateAssetEntry {
+    glbUrl: string;
+    sidecarUrl?: string;
+}
+
+/**
+ * Public types for the measurement + annotation feature.
+ *
+ * Everything here is expressed in the viewer's WORLD frame — millimetres,
+ * Z-up, identical to `XtsViewer3DRef.getMoverWorldTransform()` and
+ * `CameraState.positionMm`. That is what makes one implementation serve both
+ * the perspective 3D view and the orthographic 2D plan view
+ * (`projection='orthographic'`): only the camera differs, the geometry does
+ * not.
+ */
+
+/**
+ * How a measurement point was derived. `'free'` is the raw ray hit (surface
+ * or ground plane); everything else is a snap the picker resolved to.
+ */
+type SnapKind = 'free' | 'vertex' | 'edge-midpoint' | 'face-center' | 'grid' | 'mover-center' | 'module-boundary' | 'module-center' | 'station-stop' | 'track-path';
+/** Scene entity a picked point belongs to, when the picker could resolve one. */
+type MeasuredEntityRef = {
+    kind: 'module';
+    ref: ModuleRef;
+} | {
+    kind: 'mover';
+    ref: MoverRef;
+} | {
+    kind: 'station';
+    stationId: number;
+};
+/** A position on a part's track path, in the XPU's user position frame. */
+interface TrackAnchor {
+    processingUnitObjectId: number;
+    /** `PartConfig.objectId`. */
+    partObjectId: number;
+    /** Position along the part, user frame (same convention as movers). */
+    partPositionMm: number;
+}
+/** One measurement vertex. */
+interface MeasurementPoint {
+    /** World position (mm). */
+    positionMm: Vec3;
+    /** How the point was obtained. Default `'free'` when omitted. */
+    snap?: SnapKind;
+    /** Entity the point sits on, when known. */
+    entity?: MeasuredEntityRef;
+    /**
+     * Track position, set whenever the point resolved onto a part's path.
+     * Required on both endpoints of a `'trackDistance'` measurement.
+     */
+    track?: TrackAnchor;
+}
+/** Snapping configuration. */
+interface SnapOptions {
+    /** Master switch. Default `true`. */
+    enabled?: boolean;
+    /**
+     * Snap kinds to consider, highest priority first. Default:
+     * `['vertex', 'edge-midpoint', 'mover-center', 'module-boundary',
+     *   'station-stop', 'track-path', 'face-center']`.
+     */
+    kinds?: SnapKind[];
+    /** Screen-space radius (px) a candidate must fall within. Default `14`. */
+    radiusPx?: number;
+    /**
+     * Grid step (mm) for the `'grid'` snap, applied to the free hit point when
+     * no other candidate matched and `'grid'` is in `kinds`. Default `0` (off).
+     */
+    gridMm?: number;
+}
+type MeasurementId = string;
+type MeasurementKind = 'distance' | 'angle' | 'path' | 'trackDistance';
+/** Axis constraint for a distance measurement. */
+type MeasurementAxis = 'free' | 'x' | 'y' | 'z';
+interface MeasurementBase {
+    id: MeasurementId;
+    /** Optional caption rendered above the value. */
+    label?: string;
+    /** Overrides `MeasurementStyle.color` for this one measurement. */
+    color?: string;
+    /** Default `true`. */
+    visible?: boolean;
+    /** Free-form payload the host can round-trip (never read by the viewer). */
+    meta?: Record<string, unknown>;
+}
+/** Straight-line distance between two points. */
+interface DistanceMeasurement extends MeasurementBase {
+    kind: 'distance';
+    points: [MeasurementPoint, MeasurementPoint];
+    /** Constrain the reported value to one axis. Default `'free'`. */
+    axis?: MeasurementAxis;
+    /** Render dashed ΔX / ΔY / ΔZ guides. Default `false`. */
+    showComponents?: boolean;
+}
+/** Angle at `points[1]` between the legs to `points[0]` and `points[2]`. */
+interface AngleMeasurement extends MeasurementBase {
+    kind: 'angle';
+    /** `[legA, vertex, legB]` — the middle point is the vertex. */
+    points: [MeasurementPoint, MeasurementPoint, MeasurementPoint];
+}
+/** Polyline through N points; reports per-segment and total length. */
+interface PathMeasurement extends MeasurementBase {
+    kind: 'path';
+    points: MeasurementPoint[];
+    /** Close the polyline back to the first point. Default `false`. */
+    closed?: boolean;
+    /** Label every segment, not just the total. Default `true`. */
+    showSegmentLengths?: boolean;
+}
+/**
+ * Distance ALONG the XTS track between two points on the same part — the
+ * distance a mover actually travels, not the straight line.
+ */
+interface TrackDistanceMeasurement extends MeasurementBase {
+    kind: 'trackDistance';
+    points: [MeasurementPoint, MeasurementPoint];
+}
+type Measurement = DistanceMeasurement | AngleMeasurement | PathMeasurement | TrackDistanceMeasurement;
+/** Same as `Measurement`, but the store generates the `id` when omitted. */
+type MeasurementInput = (Omit<DistanceMeasurement, 'id'> & {
+    id?: MeasurementId;
+}) | (Omit<AngleMeasurement, 'id'> & {
+    id?: MeasurementId;
+}) | (Omit<PathMeasurement, 'id'> & {
+    id?: MeasurementId;
+}) | (Omit<TrackDistanceMeasurement, 'id'> & {
+    id?: MeasurementId;
+});
+/** Computed value of a measurement. */
+interface MeasurementResult {
+    id: MeasurementId;
+    kind: MeasurementKind;
+    /** Millimetres for lengths, degrees for angles. */
+    value: number;
+    unit: 'mm' | 'deg';
+    /** Formatted value as rendered in the scene (e.g. `'1 234.5 mm'`). */
+    text: string;
+    /** Signed component deltas — `'distance'` only. */
+    deltaMm?: Vec3;
+    /** Per-segment lengths — `'path'` only. */
+    segmentLengthsMm?: number[];
+    /**
+     * `true` when the measurement could not be evaluated (e.g. a
+     * `trackDistance` whose endpoints sit on different parts). `value` is then
+     * the straight-line fallback.
+     */
+    incomplete?: boolean;
+}
+/** Where an annotation hangs. Mover anchors follow the live mover position. */
+type AnnotationAnchor = {
+    kind: 'world';
+    positionMm: Vec3;
+} | {
+    kind: 'mover';
+    ref: MoverRef;
+} | {
+    kind: 'module';
+    ref: ModuleRef;
+} | ({
+    kind: 'trackPosition';
+} & TrackAnchor);
+interface Annotation {
+    id: string;
+    text: string;
+    anchor: AnnotationAnchor;
+    /**
+     * Leader-line offset from the anchor to the label (mm, world frame).
+     * Default `[0, 0, 250]`.
+     */
+    offsetMm?: Vec3;
+    color?: string;
+    /** Text height (mm). Default `MeasurementStyle.labelSizeMm`. */
+    sizeMm?: number;
+    /** Marker drawn at the anchor. Default `'Sphere'`. */
+    markerShape?: MarkerShape;
+    markerSizeMm?: number;
+    /** Default `true`. */
+    visible?: boolean;
+    meta?: Record<string, unknown>;
+}
+type AnnotationInput = Omit<Annotation, 'id'> & {
+    id?: string;
+};
+type MeasurementTool = 'none' | 'distance' | 'angle' | 'path' | 'trackDistance' | 'annotation';
+/** In-progress pick. `null` while no tool is armed. */
+interface MeasurementDraft {
+    tool: Exclude<MeasurementTool, 'none'>;
+    /** Points committed so far. */
+    points: MeasurementPoint[];
+    /** Point currently under the cursor, or `null` when off the scene. */
+    hover: MeasurementPoint | null;
+}
+interface MeasurementStyle {
+    /** Line + label colour of committed measurements. Default `'#00E5FF'`. */
+    color?: string;
+    /** Colour of the in-progress draft. Default `'#FFC400'`. */
+    draftColor?: string;
+    /** Annotation colour. Default `'#FFFFFF'`. */
+    annotationColor?: string;
+    /** Line width in pixels. Default `2`. */
+    lineWidthPx?: number;
+    /** Text height (mm). Default `40`. */
+    labelSizeMm?: number;
+    /** Endpoint marker diameter (mm). Default `18`. */
+    pointSizeMm?: number;
+    /** Decimal places on values. Default `1`. */
+    decimals?: number;
+    /** Unit suffix appended to lengths. Default `' mm'`. */
+    unitSuffix?: string;
+    /** Font URL passed to troika (see `DEFAULT_LABEL_FONT_URL`). */
+    fontFamily?: string;
+    /**
+     * Draw measurement lines and markers through solid geometry
+     * (`depthTest: false`). Default `true` — CAD viewers keep dimensions
+     * readable regardless of what is in front of them.
+     */
+    alwaysOnTop?: boolean;
+}
+/** Serializable snapshot of everything the measurement feature holds. */
+interface MeasurementDocument {
+    schemaVersion: 1;
+    measurements: Measurement[];
+    annotations: Annotation[];
 }
 /**
- * Build a chain from a part's module list.
- *
- * Throws XtsViewerErrorException with code `unknown-module-type` on lookup
- * miss.
- */
-declare function buildChain(modules: ReadonlyArray<ModuleEntry>): BuiltChain;
-/**
- * Locate the module containing `partPositionMm` along the chain.
- * First module with partPosition < startInPart + trackLength; at boundary
- * `partPosition == trackLength` the LAST module is returned with
- * `localPos = trackLength`.
+ * `measurement` prop of `<XtsViewer3D>`. Data can be driven either
+ * declaratively (`measurements` / `annotations` — controlled arrays) or
+ * imperatively via `viewerRef.current.measurements`. When the controlled
+ * arrays are supplied they win on every render, so a host that uses them must
+ * persist what the change callbacks report.
  */
-declare function findModuleAt(chain: BuiltChain, partPositionMm: number): {
-    module: BuiltModule;
-    localPosMm: number;
-} | null;
+interface MeasurementOptions {
+    /** Armed tool. Default `'none'` — no picking, no cursor change. */
+    tool?: MeasurementTool;
+    /** Controlled measurement list. Omit to let the viewer keep its own. */
+    measurements?: MeasurementInput[];
+    /** Controlled annotation list. Omit to let the viewer keep its own. */
+    annotations?: AnnotationInput[];
+    snap?: SnapOptions;
+    style?: MeasurementStyle;
+    /**
+     * Z of the fallback pick plane (mm) used when the ray misses all geometry,
+     * so free space can be measured. Default `0`; `null` disables the fallback.
+     */
+    groundPlaneZMm?: number | null;
+    /** Fired after every change to the measurement list. */
+    onMeasurementsChange?: (measurements: Measurement[], results: MeasurementResult[]) => void;
+    /** Fired once when a tool completes a measurement. */
+    onMeasurementCreate?: (measurement: Measurement, result: MeasurementResult) => void;
+    onAnnotationsChange?: (annotations: Annotation[]) => void;
+    onAnnotationCreate?: (annotation: Annotation) => void;
+    /** Fired on every draft change (point added, hover moved, cancelled). */
+    onDraftChange?: (draft: MeasurementDraft | null) => void;
+    /**
+     * Text for an annotation the `'annotation'` tool just placed. Return
+     * `null` to abort. Default: `'Annotation'`.
+     */
+    annotationTextFactory?: (point: MeasurementPoint) => string | null;
+}
 /**
- * Mover world pose at `partPositionMm`.
+ * A partial measurement, kind by kind.
  *
- * The module's startWorldPose is composed with the local path sample at
- * `localPosMm` along that module's path.
+ * `Omit` does not distribute over a union: `Omit<Measurement, 'id' | 'kind'>`
+ * keeps only the properties every measurement kind has, which dropped `axis`
+ * and `showComponents` — fields `MeasurementOverlay` actually renders. Mapping
+ * over the union first keeps them.
  */
-declare function moverWorldAt(chain: BuiltChain, partPositionMm: number): PlanarPose | null;
-/** Convenience: chain from full ModuleEntry[] returning trackLength alone. */
-declare function trackLengthOf(modules: ReadonlyArray<ModuleEntry>): number;
+type MeasurementPatch = Partial<Measurement extends infer M ? M extends Measurement ? Omit<M, 'id' | 'kind'> : never : never>;
 
 /**
- * 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)
+ * `XtsModelDocument` — the canonical serialized form of a viewer scene.
  *
- * 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)
+ * What `viewerRef.current.exportModel()` produces and what a host persists:
+ * the configuration, optionally the runtime mover state, and optionally the
+ * measurements. The measurement half keeps its own types next to its
+ * implementation (`measurement/types.ts`); only the serialized document
+ * surfaces here.
  */
 
-interface NormalizedXtsConfig extends XtsConfig {
+interface XtsModelDocument {
+    schemaVersion: 1;
+    meta: {
+        generatedAt: string;
+        generator: string;
+        sourceFormat?: string;
+        sourceFileHash?: string;
+    };
+    config: XtsConfig;
+    runtime?: XtsRuntimeState;
+    railSystem?: RailSystem | {
+        byProcessingUnit: Record<number, RailSystem>;
+    };
     /**
-     * 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.
+     * Measurements + annotations placed on the layout, as returned by
+     * `XtsViewer3DRef.measurements.toJSON()`. Omitted when there are none, so
+     * documents written before the measurement feature stay byte-identical.
      */
-    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;
+    measurements?: MeasurementDocument;
 }
-/**
- * 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;
+interface XtsRuntimeState {
+    movers: Array<{
+        processingUnitObjectId: number;
+        moverIndex: number;
+        id: number;
+        partOid: number;
+        partPositionMm: number;
+        velocity?: {
+            mmPerSec: number;
+        };
+        status?: {
+            warning?: boolean;
+            error?: boolean;
+        };
+    }>;
+    selection?: SelectionState;
+    camera?: CameraState;
+    display?: Partial<DisplayOptions>;
 }
-declare function normalizeXtsConfig(config: XtsConfig): NormalizedXtsConfig;
 
 /**
- * Mover collision detection.
- *
- * Sub-millimetre accurate for the dominant XTS case: two movers travelling
- * along the same chain. Each mover occupies a 1D footprint of
- * `pathLengthMm` centred on `partPositionMm`, so the collision predicate
- * collapses to one subtraction in path-space:
- *
- *     centerDistance = arc-length |pos_a − pos_b|
- *     requiredGap    = (pathLength_a + pathLength_b) / 2
- *     penetration    = requiredGap − centerDistance
- *     collision iff  penetration > 0  (≥ 0 for "touching")
- *
- * For closed-loop chains (oval tracks, U-turn pairs) the arc-length is
- * taken as the *minimum* of the forward and the wrap-around path so two
- * movers near the seam (e.g. 50 mm and trackLength − 50 mm) are treated
- * as physically adjacent. Open chains are detected by comparing the
- * chain's start- and end-pose; for those the wrap-around distance is
- * simply not considered.
+ * SidecarLoader — fetches per-asset JSON sidecars.
  *
- * Floating-point precision: positions are kept in mm in float64. A typical
- * XTS layout has trackLength ≤ 20 m → < 2×10⁴ mm, well inside the
- * 2⁵³-mantissa range, so subtractive cancellation costs at most ~10⁻¹²
- * mm — orders of magnitude below sub-millimetre.
+ * 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).
  *
- * Multi-XPU (different chains): not handled here. Cross-track collisions
- * are dominated by track-transform layout and would need an OBB / mesh
- * test in 3D space; that's a different concern from "two movers on the
- * same line about to crash".
+ * 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;
+}
 /**
- * One detected pair. Result list is symmetric (a/b is reported once per
- * pair, with `a` carrying the lower index pair-canonical).
+ * 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 MoverCollision {
-    a: MoverRef;
-    b: MoverRef;
-    /**
-     * Stable IDs of the two movers (mirrors `MoverConfig.id`). Useful when
-     * the consumer keys by id rather than by `moverIndex`.
-     */
-    idA: number;
-    idB: number;
-    /**
-     * Penetration along the 1D path:
-     *   • `> 0` — movers overlap by this many mm.
-     *   • `= 0` — touching exactly.
-     *   • `< 0` — closest-approach gap (only present in result when
-     *             `warningGapMm` is set; the magnitude is the free-space
-     *             distance between the closer footprint edges).
-     */
-    penetrationMm: number;
-    /**
-     * Both `partPositionMm` values at the time of the test. Lets the
-     * consumer recompute or visualise without re-querying.
-     */
-    positionAMm: number;
-    positionBMm: number;
-    /** Mover lengths (catalog `pathLengthMm`). */
-    pathLengthAMm: number;
-    pathLengthBMm: number;
-    /** True when measurement wrapped around the chain end (closed-loop seam). */
-    viaWraparound: boolean;
+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;
 }
-interface CheckMoverCollisionsOptions {
-    /**
-     * When `> 0`, near-misses with closest-approach gap up to this many mm
-     * are also returned (with `penetrationMm < 0`). Default 0 — only actual
-     * collisions / contacts.
-     */
-    warningGapMm?: number;
-    /**
-     * Force-treat the chain as closed (consider wrap-around distance) or
-     * open (don't). When omitted, auto-detected by comparing
-     * `chain.endPose` to `startPose ≈ identity` within ~0.1 mm tolerance.
-     */
-    forceClosedLoop?: boolean;
+/**
+ * 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;
 /**
- * Effective mover state passed into the predicate. Decoupled from
- * MoverConfig so consumers can plug in live positions from the
- * MoverPositionStore (60-Hz tick) without round-tripping through React
- * state.
+ * 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).
  */
-interface MoverProbe {
-    ref: MoverRef;
-    id: number;
-    partOid: number;
-    moverType: MoverType3D;
-    partPositionMm: number;
+declare class SidecarLoader {
+    private readonly timeoutMs;
+    private readonly cache;
+    constructor(timeoutMs?: number);
+    clear(): void;
     /**
-     * Override the catalog `pathLengthMm`. Use for `Custom` movers where
-     * the layout's `pathLengthMm` is the source of truth.
+     * 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.
      */
-    pathLengthMm?: number;
+    fetch<T>(url: string): Promise<T | undefined>;
 }
 /**
- * Pair-wise 1D collision test for movers on the same chain.
- *
- * `chain` is the BuiltChain corresponding to the partOid all probed
- * movers travel on. `probes` may contain movers from *any* part — this
- * function only considers pairs where `partOid` matches the chain.
- *
- * Returns one entry per colliding (or near-miss, when `warningGapMm > 0`)
- * pair, sorted by `penetrationMm` descending so the deepest collisions
- * appear first.
+ * Resolve the effective origin correction for a module sidecar — falls back
+ * to identity when the sidecar is absent.
  */
-declare function checkSamePathCollisions(chain: BuiltChain, partOid: number, probes: ReadonlyArray<MoverProbe>, opts?: CheckMoverCollisionsOptions): MoverCollision[];
+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;
+    };
+}
 /**
- * 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.
+ * Pure helper: pick the GLB filename with rail-system fallback. Returns null
+ * when the entry marks the module 'prepared but not delivered'.
  *
- * Results are sorted so the deepest collision in the scene comes first.
+ * 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 checkAllMoverCollisions(config: NormalizedXtsConfig, livePositionOf: (moverId: number) => number | undefined, opts?: CheckMoverCollisionsOptions): MoverCollision[];
+declare function pickGlbForRail(entry: GlbByRailSystem | undefined, rail: RailSystem): string | null;
 
 /**
- * Module collision / overlap detection.
- *
- * The mover collision (moverCollision.ts) is a 1D arc-length test for two
- * movers on the *same* chain; its header explicitly declines cross-XPU /
- * cross-track cases, which "would need an OBB / mesh test in 3D space".
- * This file is exactly that test, for the physical track *modules*.
- *
- * Each module is modelled as a chain of oriented bounding boxes (OBBs) that
- * follow its real centerline: the path is sampled (sampleModulePath) and each
- * segment becomes a small box (±halfWidth in Y, 0..height in Z) oriented along
- * the local tangent, then transformed into world space by
- *
- *     world = orientation ⊗ trackTransform ⊗ partTransformation ⊗ chainPose
- *
- * Sampling the path (rather than a single straight box per module) is what
- * keeps curves and U-turns faithful — a single straight box would poke
- * outside the arc and produce both false positives and false negatives on a
- * closed oval. Straights collapse to one box; curves / free paths use several.
- *
- * Pairs are tested with the Separating Axis Theorem (15 axes) over their
- * segment boxes, yielding a penetration depth (minimum translation distance)
- * as `overlapMm`:
- *
- *     overlapMm  > 0  — boxes overlap by this many mm (deepest sub-box pair).
- *     overlapMm  = 0  — touching exactly.
- *     overlapMm  < 0  — closest-approach gap (only reported when
- *                       `warningGapMm` is set).
- *
- * Adjacent modules in the same part butt up edge-to-edge (ChainBuilder), so
- * consecutive `(i, i+1)` pairs — and the `(N-1, 0)` seam of a closed loop —
- * are excluded; everything else (cross-part, cross-XPU, same-part
- * non-adjacent) is tested.
+ * Option shapes shared between the public `<XtsViewer3D>` props and the
+ * internal `<XtsScene>` / `<ProcessingUnitRoot>` props.
  *
- * 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.
+ * 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.
  */
 
-/** Default box half-width (Y) — matches `approximateModuleBounds`. */
-declare const DEFAULT_MODULE_HALF_WIDTH_MM = 50;
-/** Default box height (Z) — matches `approximateModuleBounds`. */
-declare const DEFAULT_MODULE_HEIGHT_MM = 100;
+/** 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';
 /**
- * One detected pair. Symmetric: `a`/`b` are canonicalised so the lower
- * `(processingUnitObjectId, partObjectId, moduleIndex)` tuple is always `a`.
+ * 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 ModuleCollision {
-    a: ModuleRef;
-    b: ModuleRef;
-    moduleTypeA: ModuleType3D;
-    moduleTypeB: ModuleType3D;
-    /** Forwarded `ModuleEntry.globalNumber` (status-store key), if present. */
-    globalNumberA?: number;
-    globalNumberB?: number;
+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;
     /**
-     * Penetration depth along the minimum-translation axis of the deepest
-     * sub-box pair:
-     *   • `> 0` — overlap (mm).
-     *   • `= 0` — touching.
-     *   • `< 0` — closest-approach gap (only when `warningGapMm` is set).
+     * Multiplier on the default travel rate, which is ~0.6 × the current
+     * orbit distance per second. Default `1`.
      */
-    overlapMm: number;
-    /** Centre-to-centre distance of the deepest sub-box pair (mm). */
-    centerDistanceMm: number;
-    /** Unit world-space axis of least penetration (the MTV direction). */
-    axis: Vec3;
+    speed?: number;
 }
-interface CheckModuleCollisionsOptions {
+/** Interaction locks. Each `true` disables that interaction. */
+interface InteractionLocks {
+    rotate?: boolean;
+    pan?: boolean;
+    zoom?: boolean;
+    selection?: boolean;
+}
+interface PerformanceOptions {
     /**
-     * When `> 0`, near-misses with an axis-projected gap up to this many mm
-     * are also returned (with `overlapMm < 0`). Default 0 — only actual
-     * overlaps / contacts.
+     * 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.
      */
-    warningGapMm?: number;
+    instancing?: boolean;
+    /** Stop the frameloop while the tab is hidden. Default: true. */
+    autoPauseOnHidden?: boolean;
     /**
-     * Also test non-adjacent module pairs within the SAME part. Default true.
-     * Consecutive `(i, i+1)` pairs and the closed-loop `(N-1, 0)` seam are
-     * ALWAYS excluded regardless of this flag.
+     * 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.
      */
-    includeSamePart?: boolean;
-    /** Box half-width in Y (mm). Default 50. */
-    halfWidthMm?: number;
-    /** Box height in Z (mm). Default 100. */
-    heightMm?: number;
-}
-/** Oriented bounding box in world space (unit axes + scaled half-extents). */
-interface Obb {
-    center: Vector3;
-    axes: [Vector3, Vector3, Vector3];
-    halfExtents: [number, number, number];
-    /** Bounding-sphere radius (broad-phase reject). */
-    radius: number;
-}
-/** Pre-built per-module probe consumed by `checkModuleCollisions`. */
-interface ModuleProbe {
-    ref: ModuleRef;
-    moduleType: ModuleType3D;
-    globalNumber?: number;
-    /** Adjacency grouping key (part.globalNumber — system-wide unique). */
-    partKey: number;
-    /** Index of this module within its part's chain. */
-    moduleIndex: number;
-    /** Segment boxes following the module centerline (≥ 1). */
-    obbs: Obb[];
-    /** Module-level bounding sphere enclosing all segment boxes. */
-    sphereCenter: Vector3;
-    sphereRadius: number;
-}
-/** A part fed to `buildModuleProbes`. */
-interface ModuleCollisionPartInput {
-    /** ModuleRef.partObjectId (`PartConfig.objectId`). */
-    partObjectId: number;
-    /** Adjacency key (`PartConfig.globalNumber`). */
-    partKey: number;
-    partTransformation?: PartTransformation | null;
-    chain: BuiltChain;
-}
-/** An XPU fed to `buildModuleProbes`. */
-interface ModuleCollisionXpuInput {
-    xpuObjectId: number;
-    /** Effective (override-resolved) per-XPU track transform. */
-    trackTransform?: TrackTransform | null;
-    parts: ReadonlyArray<ModuleCollisionPartInput>;
+    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;
+    /**
+     * 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;
 }
 /**
- * Turn a list of XPUs (with effective track transforms) + parts (with built
- * chains) into flat module probes plus a per-part adjacency map. Shared by
- * the imperative ref and the reactive monitor so the world-matrix
- * composition lives in one place.
- *
- * Hidden XPUs / parts (`visible === false`) are skipped to match the scene.
- */
-declare function buildModuleProbes(orientation: Orientation | undefined, xpus: ReadonlyArray<ModuleCollisionXpuInput>, opts?: CheckModuleCollisionsOptions): {
-    probes: ModuleProbe[];
-    adjacency: Map<number, {
-        count: number;
-        closed: boolean;
-    }>;
-};
-/**
- * Pairwise OBB overlap test over all module probes. Same-part consecutive
- * and closed-loop-seam pairs are excluded; everything else is tested.
- * Returns one entry per overlapping (or near-miss, when `warningGapMm > 0`)
- * pair, sorted deepest-overlap-first.
- */
-declare function checkModuleCollisions(probes: ReadonlyArray<ModuleProbe>, adjacency: ReadonlyMap<number, {
-    count: number;
-    closed: boolean;
-}>, opts?: CheckModuleCollisionsOptions): ModuleCollision[];
-/**
- * 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.
- *
- * 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.
- *
- * 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.
+ * 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`.
  */
-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[];
+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>>;
+}
 
 /**
  * Shared, mostly-pure plumbing behind `exportScreenshot` and
@@ -2525,7 +2886,7 @@ declare function trackPolylineWorld(entry: TrackIndexEntry, fromChainMm: number,
  * `getLivePositionMm` supplies the imperative store value; without it the
  * config-time position is used.
  */
-declare function moverAnchorWorld(config: NormalizedXtsConfig, index: TrackIndex, ref: MoverRef, getLivePositionMm?: (moverId: number) => number | undefined): Vec3 | null;
+declare function moverAnchorWorld(config: NormalizedXtsConfig, index: TrackIndex, ref: MoverRef, getLivePositionMm?: (moverId: number) => number | undefined, getLivePartObjectId?: (moverId: number) => number | undefined): Vec3 | null;
 /** World centre of a module, for `AnnotationAnchor` of kind `'module'`. */
 declare function moduleAnchorWorld(index: TrackIndex, processingUnitObjectId: number, partObjectId: number, moduleIndex: number): Vec3 | null;
 /** World position of a `TrackAnchor` (user-frame mm on a part). */
@@ -2561,7 +2922,7 @@ interface MeasurementApi {
     /** Close the current pick — the polyline tool's "done". */
     finish(): Measurement | null;
     add(measurement: MeasurementInput): Measurement;
-    update(id: MeasurementId, patch: Partial<Omit<Measurement, 'id' | 'kind'>>): Measurement | null;
+    update(id: MeasurementId, patch: MeasurementPatch): Measurement | null;
     remove(id: MeasurementId): boolean;
     clear(): void;
     /** Replace the whole list (e.g. restoring a persisted session). */
@@ -2619,15 +2980,6 @@ 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];
         rotationDegEuler: [number, number, number];
@@ -2691,16 +3043,6 @@ 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;
     /**
      * Push mover positions in bulk. Two accepted forms:
@@ -2724,6 +3066,26 @@ interface XtsViewer3DRef {
     setModuleStatuses(statuses: ReadonlyArray<ModuleStatusEntry | null | undefined>): void;
     /** Clear all live module statuses (revert to config-time `ModuleEntry.status`). */
     clearModuleStatuses(): void;
+    /**
+     * Push live mover-tool state, keyed by `MoverConfig.id` and then by
+     * `MoverToolConfig.id` — `update[mover.id][tool.id] = { visible }`.
+     *
+     * For state that changes while the scene runs: a simulated line loads a
+     * product onto a mover at one station and takes it off at another, so the
+     * tool drawing that product appears and disappears several times a minute.
+     * Saying it through `config` would replace the whole configuration on every
+     * change; this is one call and one `invalidate()`, however many movers it
+     * carries.
+     *
+     * A live entry OVERRIDES the config-time `MoverToolConfig.visible`. `null`
+     * for a tool drops it back to the configuration. Only movers named in
+     * `update` are touched, and only the movers that actually changed
+     * re-render. A tool with no `id` cannot be addressed and always follows its
+     * configuration.
+     */
+    setMoverToolStates(update: Readonly<Record<number, Readonly<Record<string, MoverToolStateEntry | null>>>>): void;
+    /** Clear all live mover-tool state (revert to config-time `MoverToolConfig.visible`). */
+    clearMoverToolStates(): void;
     checkMoverCollisions(opts?: CheckMoverCollisionsOptions): MoverCollision[];
     /**
      * On-demand check for physically overlapping track MODULES across the
@@ -2757,8 +3119,8 @@ interface XtsViewer3DRef {
 }
 
 /**
- * HepcoGfxRailProfile — cross-section of the Hepco GFX guiding rail used by
- * the procedural extrusion in <HepcoGfxRail>.
+ * HepcoGfxRailProfile — cross-sections of the Hepco GFX 1-Trak (TL1) guideway
+ * used by the procedural extrusion in <HepcoGfxRail>.
  *
  * The profile is expressed in the Beckhoff path-frame convention:
  *   - path tangent = +X (extrusion direction)
@@ -2770,76 +3132,159 @@ interface XtsViewer3DRef {
  * plane the initial Frenet frame computed by three.js is:
  *   normal   = (0, 0, -1)     -> shape.x maps to world  -Z
  *   binormal = lateral in XY  -> shape.y maps to world  ±Y
- * To keep this module's public dimensions in natural "Z-up" coordinates,
- * the Shape factory negates Z when emitting shape.x. Callers should think
- * in (lateral Y, vertical Z); the negation is an implementation detail.
+ * To keep this module's public dimensions in natural "Z-up" coordinates, the
+ * outlines below are built as (y, z) point lists and only converted to the
+ * shape frame by `toShape()`. All the geometry — including the arcs — is
+ * therefore expressed and testable in natural terms; the negation of Z is an
+ * implementation detail of one function.
+ *
+ * The guideway cross-section is THREE disconnected regions, one mesh each:
+ *
+ *  1. Baseplate — a flat plate, 30 mm thick. The real part is 270 mm wide and
+ *     carries both tracks of the oval; the viewer extrudes one 135 mm half per
+ *     Part, so two Parts (or the two straights of one closed Part) together
+ *     span the full width. Its inner edge carries half of the 30 mm central
+ *     slot; the other half comes from the opposite track.
+ *
+ *  2. Rail — the hardened steel V-rail the mover's rollers engage. Apex to
+ *     apex 44 mm ("NM44"), 15.6 mm tall, with 35° V flanks, a shallow groove
+ *     in its top face, a waisted neck and two feet standing on the plate.
+ *
+ *  3. Bracket — the GFX-UMB upper mounting bracket that carries the XTS motor
+ *     modules above the plate. One per Part, on the inner side of the rail.
  *
- * The Hepco GFX cross-section is TWO disconnected regions:
+ * ## Where the numbers come from
  *
- *  1. Baseplate — a wide flat plate at the bottom (134.45 mm × 30.1 mm).
- *     One per track; the two plates of an XTS oval sit side-by-side and
- *     together span the full ~268.9 mm system width.
+ * Every dimension below is measured off the original CAD, not estimated:
+ * `stepfiles/hepco-gfx-rail/BA-GFX-1TL-3M-B.stp`, which is an assembly of
+ * named parts — `GFX-1TLBP-3S-B` (baseplate), `AT-XTS_GFX-NM44-L500` (straight
+ * rail), `GFX-SEG-NM44-CSA_` (curved rail), `GFX-UMB-1RH`/`-2LH`/`-EB`
+ * (brackets and end block). The same section was cross-checked against
+ * HepcoMotion's own `GFX-1TL-8M-B` download, which agrees to 0.1 mm.
  *
- *  2. Rail — a separate spear-profile bar (40 mm × 20 mm) sitting on top
- *     of the baseplate at its +Y edge. Has horizontally pointed apexes on
- *     both lateral sides; the mover's V-rollers engage these apexes.
+ * ## The one constraint that must not move
  *
- * Two shape factories are exported so the consumer can extrude each region
- * as its own mesh; merging them into a single Shape would require a thin
- * connecting sliver that misrepresents the real geometry.
+ * All nine Hepco carriage sidecars (`public/models/Hepco-GFX2-*.meta.json`)
+ * are calibrated to seat their V-roller grooves on the two apexes at
+ * chain-frame (Y, Z) = (9, -43) and (-35, -43), with only 0.7-1.6 mm of
+ * clearance left. The apexes are the datum: every other dimension here is
+ * derived relative to them, so the carriages stay seated.
  *
- * The `stackYOffsetMm` / `stackZOffsetMm` fields shift both regions
- * together — used by the playground calibration UI to fine-tune position
- * relative to the path origin without changing the inherent geometry.
+ *   apex centre Y = stackYOffsetMm                       = -13
+ *   apex Z        = railTopZMm - spearBaseHalfHeightMm
+ *                   + stackZOffsetMm                     = -43
+ *   plate top Z   = railTopZMm - railHeightMm + stackZOffsetMm = -55.5
+ *
+ * `HepcoGfxRailProfile.test.ts` pins this contract directly.
  */
 
+/** A point in the natural (lateral Y, vertical Z) profile frame, in mm. */
+type ProfilePoint = readonly [y: number, z: number];
 interface HepcoGfxRailProfileDims {
-    /** Baseplate Y-extent per track (mm). Half of the XTS oval's full
-     *  cross-section width. */
+    /** Baseplate Y-extent per track (mm) — half of the real 270 mm plate. */
     readonly baseplateWidthMm: number;
     /** Baseplate Z-extent (mm). */
     readonly baseplateThicknessMm: number;
-    /** Z-coordinate of the baseplate's top face in the path frame (before
-     *  stackZOffsetMm is applied). Also the Z of the rail's bottom face. */
+    /**
+     * Z of the baseplate's top face in the path frame (before stackZOffsetMm).
+     * Also the Z the rail and the bracket stand on.
+     */
     readonly baseplateTopZMm: number;
-    /** Rail Y-extent, spear-apex to spear-apex (mm). */
+    /**
+     * Lateral distance from the rail centreline to the plate's OUTER edge (mm),
+     * on the +Y side. The real rail overhangs the plate edge, so this is smaller
+     * than half the rail width. The inner edge follows from `baseplateWidthMm`.
+     */
+    readonly baseplateOuterExtentMm: number;
+    /**
+     * Depth of the central-slot notch cut into the plate's inner edge (mm) —
+     * half of the real 30 mm slot, the other half belonging to the opposite
+     * track's plate.
+     */
+    readonly baseplateSlotDepthMm: number;
+    /** Length of one central slot along the path (mm). */
+    readonly baseplateSlotLengthMm: number;
+    /** Spacing of the central slots along the path (mm). */
+    readonly baseplateSlotPitchMm: number;
+    /** Rail Y-extent, apex to apex (mm). */
     readonly railWidthMm: number;
-    /** Rail Z-extent, main-body top to main-body bottom (mm). */
+    /** Rail Z-extent, top face down to the feet (mm). */
     readonly railHeightMm: number;
-    /** Z-coordinate of the rail's main-body top in the path frame (before
-     *  stackZOffsetMm is applied). */
+    /** Z of the rail's top face in the path frame (before stackZOffsetMm). */
     readonly railTopZMm: number;
-    /** Lateral protrusion of each spear apex beyond the rail's main body (mm). */
-    readonly spearProtrusionMm: number;
-    /** Half-height of the spear at its inner (main-body-side) edge (mm) —
-     *  measured from the apex Z toward both top and bottom shoulders. */
+    /**
+     * Drop from the rail's top face to the apex centre (mm). Together with
+     * `railTopZMm` and `stackZOffsetMm` this fixes the apex height, which the
+     * carriage sidecars depend on — see the module header.
+     */
     readonly spearBaseHalfHeightMm: number;
-    /** Concave-undercut inset on the rail's bottom face just inboard of
-     *  each spear (mm) — the rail's bottom edge is shorter than its top
-     *  edge by 2× this value. */
-    readonly undercutInsetMm: number;
-    /** Calibration shift in Y applied to baseplate + rail together (mm). */
+    /** Height of the small vertical flat at the very tip of each apex (mm). */
+    readonly apexFlatHeightMm: number;
+    /** V flank angle measured from horizontal (deg). Both flanks are equal. */
+    readonly vFlankAngleDeg: number;
+    /** Height of the rail's underside wings above the plate (mm). */
+    readonly railWingHeightMm: number;
+    /** Half-width of the underside wing flat, inner end (mm). */
+    readonly railWingInnerHalfWidthMm: number;
+    /** Width of the recessed groove in the rail's top face (mm). */
+    readonly topGrooveWidthMm: number;
+    /** Depth of that groove below the top face (mm). */
+    readonly topGrooveDepthMm: number;
+    /** Radius of the two tangent arcs forming each groove edge (mm). */
+    readonly topGrooveFilletMm: number;
+    /** Convex round below each wing: centre (half-width, height) and radius. */
+    readonly neckRoundCentreMm: ProfilePoint;
+    readonly neckRoundRadiusMm: number;
+    /** Concave waist scallop: centre (half-width, height) and radius. */
+    readonly neckWaistCentreMm: ProfilePoint;
+    readonly neckWaistRadiusMm: number;
+    /** Where the convex round hands over to the concave waist (half-width, height). */
+    readonly neckJunctionMm: ProfilePoint;
+    /** Half-width of the rail feet at their outer wall (mm). */
+    readonly footOuterHalfWidthMm: number;
+    /** Height at which the foot's outer wall meets the waist scallop (mm). */
+    readonly footTopHeightMm: number;
+    /** 45° chamfer on every foot corner at the plate face (mm). */
+    readonly footChamferMm: number;
+    /** Half-width of the channel between the two feet (mm). */
+    readonly channelHalfWidthMm: number;
+    /** Height of that channel (mm) — its floor is the plate's top face. */
+    readonly channelHeightMm: number;
+    /** Bracket footprint width (mm). */
+    readonly bracketWidthMm: number;
+    /** Bracket total height above the plate's top face (mm). */
+    readonly bracketHeightMm: number;
+    /** Height of the bracket's full-width base block (mm). */
+    readonly bracketBaseHeightMm: number;
+    /** Width of the upper wall standing on the base block's outer edge (mm). */
+    readonly bracketWallWidthMm: number;
+    /**
+     * Lateral distance from the rail centreline to the bracket's OUTER face,
+     * measured toward -Y (mm). The bracket sits between the rail and the oval's
+     * centreline, and the XTS module bolts to the outer face of its wall.
+     */
+    readonly bracketOuterOffsetMm: number;
+    /** Calibration shift in Y applied to every region together (mm). */
     readonly stackYOffsetMm: number;
-    /** Calibration shift in Z applied to baseplate + rail together (mm). */
+    /** Calibration shift in Z applied to every region together (mm). */
     readonly stackZOffsetMm: number;
+    /**
+     * @deprecated Described the straight-chamfer approximation of the old
+     * scaffolding profile. No longer read by any shape factory; kept so that
+     * callers passing it through `hepcoGfxProfile` keep type-checking.
+     */
+    readonly spearProtrusionMm: number;
+    /**
+     * @deprecated See `spearProtrusionMm`. The real undercut is the waisted
+     * neck described by `neckWaist*` / `neckRound*`.
+     */
+    readonly undercutInsetMm: number;
 }
 /**
- * Default dimensions (mm). The stack offsets bake in the calibration so the
- * rendered geometry is correct out of the box; the playground / a
- * `*.meta.json` sidecar (`Hepco-GFX.rail.meta.json`) can override them.
- *
- * Cross-checked against the exact Hepco TL1 (1-Trak loop) guideway STP
- * `stepfiles/hepco-gfx-rail/BA-GFX-1TL-3M-B.stp`: a perpendicular section of
- * a straight run shows the full beam is ~270 mm wide in the lateral axis
- * (matches `baseplateWidthMm` 134.45 × 2 tracks = 268.9 mm) and the steel
- * guide-rail block the V-rollers engage is ~37 mm wide × ~18 mm tall (close to
- * `railWidthMm` 44 / `railHeightMm` 15 here). The tall central structure in
- * the STP is the motor stator track, which the viewer renders as the module
- * GLB — not part of this guide-rail profile.
+ * Default dimensions (mm), measured from the CAD named in the module header.
  *
- * These values are kept in sync with the calibrated runtime override in
- * `public/models/Hepco-GFX.rail.meta.json`. PRT2 (22.5° / 45°) currently has
- * no dedicated STP and reuses this TL1-derived profile.
+ * Kept in sync by hand with `public/models/Hepco-GFX.rail.meta.json`, which the
+ * playground loads so the calibration panel can override them at runtime.
  */
 declare const HEPCO_GFX_PROFILE: HepcoGfxRailProfileDims;
 /**
@@ -2849,22 +3294,64 @@ declare const HEPCO_GFX_PROFILE: HepcoGfxRailProfileDims;
  */
 declare function resolveHepcoGfxProfile(override?: Partial<HepcoGfxRailProfileDims>): HepcoGfxRailProfileDims;
 /**
- * Build the baseplate cross-section (mm). Simple rectangle positioned so
- * the rail's +Y spear apex sits flush with the baseplate's +Y edge; the
- * baseplate extends in -Y direction from there. Both axes are shifted by
- * `stackYOffsetMm` / `stackZOffsetMm` before being emitted.
+ * Build the rail's closed outline in natural (Y, Z) coordinates, before the
+ * stack offsets are applied. Exported so tests and calibration tooling can
+ * reason about the real cross-section without going through the shape frame.
+ *
+ * Traversal starts at the top face's -Y end and runs to +Y, down the +Y flank,
+ * along the underside (through the channel between the two feet) and back up
+ * the -Y flank — the same winding the previous scaffolding outline used.
+ */
+declare function buildHepcoGfxRailOutline(dims?: HepcoGfxRailProfileDims): ProfilePoint[];
+/**
+ * Build the baseplate outline in natural (Y, Z) coordinates.
+ *
+ * `slotDepthMm` trims the plate's inner edge back by that much — used to
+ * extrude the plate's continuous web, with `buildHepcoGfxBaseplateBridgeOutline`
+ * filling the trimmed strip back in between the central slots. Pass 0 (the
+ * default) for the plain full-width section.
+ */
+declare function buildHepcoGfxBaseplateOutline(dims?: HepcoGfxRailProfileDims, slotDepthMm?: number): ProfilePoint[];
+/**
+ * The strip the central slot removes from the plate's inner edge. Extruded in
+ * short runs between the slots so the slots come out as real openings rather
+ * than painted-on darkness.
+ */
+declare function buildHepcoGfxBaseplateBridgeOutline(dims?: HepcoGfxRailProfileDims): ProfilePoint[];
+/**
+ * Build the GFX-UMB bracket outline: a full-width base block with the upper
+ * wall standing on its outer edge, so the section is an L opening toward the
+ * oval's centreline.
  */
-declare function createHepcoGfxBaseplateShape(dims?: HepcoGfxRailProfileDims): Shape;
+declare function buildHepcoGfxBracketOutline(dims?: HepcoGfxRailProfileDims): ProfilePoint[];
+/** The bracket's upper wall alone — the part the windows interrupt. */
+declare function buildHepcoGfxBracketWallOutline(dims?: HepcoGfxRailProfileDims): ProfilePoint[];
 /**
- * Build the rail cross-section (mm). Symmetric spear-profile bar centered
- * on Y=0 (before stackYOffsetMm). The mover's V-rollers grip the two
- * spear apexes (at Y=±railWidth/2, Z=midZ).
+ * The GFX-UMB-EB end block that caps an open end of the bracket run: the
+ * bracket's full width, but only over the upper wall's height band.
  *
- * The profile's top edge is flush with the spear shoulder top — there is
- * NO rectangular section above the spear shoulders. `railHeightMm` therefore
- * spans only from the main-body bottom up to the spear shoulder top.
+ * The real part is 84.7 mm wide and ties the Part's bracket to its opposite
+ * number across the oval's centreline. The viewer draws one bracket per Part,
+ * so it gets the half that belongs to this one — full bracket width, which is
+ * what closes the visible end of the wall.
  */
+declare function buildHepcoGfxBracketEndBlockOutline(dims?: HepcoGfxRailProfileDims): ProfilePoint[];
+/** The bracket's base block alone — continuous under the windowed wall. */
+declare function buildHepcoGfxBracketBaseOutline(dims?: HepcoGfxRailProfileDims): ProfilePoint[];
+/** Baseplate cross-section (mm). See `buildHepcoGfxBaseplateOutline`. */
+declare function createHepcoGfxBaseplateShape(dims?: HepcoGfxRailProfileDims, slotDepthMm?: number): Shape;
+/** Baseplate inner-edge strip between two central slots (mm). */
+declare function createHepcoGfxBaseplateBridgeShape(dims?: HepcoGfxRailProfileDims): Shape;
+/** Rail cross-section (mm). See `buildHepcoGfxRailOutline`. */
 declare function createHepcoGfxRailShape(dims?: HepcoGfxRailProfileDims): Shape;
+/** Full GFX-UMB bracket cross-section (mm). */
+declare function createHepcoGfxBracketShape(dims?: HepcoGfxRailProfileDims): Shape;
+/** GFX-UMB base block cross-section (mm). */
+declare function createHepcoGfxBracketBaseShape(dims?: HepcoGfxRailProfileDims): Shape;
+/** GFX-UMB upper wall cross-section (mm). */
+declare function createHepcoGfxBracketWallShape(dims?: HepcoGfxRailProfileDims): Shape;
+/** GFX-UMB-EB end block cross-section (mm). */
+declare function createHepcoGfxBracketEndBlockShape(dims?: HepcoGfxRailProfileDims): Shape;
 
 /**
  * <XtsViewer3D> — Top-level React component.
@@ -2913,30 +3400,38 @@ interface XtsViewer3DProps {
     /**
      * Live camera projection. Default `'perspective'`.
      *
-     * `'orthographic'` (together with `topDown`, on by default) renders the flat
-     * 2D plan view — straight down +Z, up = +Y — pixel-consistent with
+     * `'orthographic'` renders the flat 2D plan view — straight down +Z, up = +Y — pixel-consistent with
      * `exportScreenshot({ mode: 'top-down' })`. Switching at runtime does NOT
      * recreate the WebGL context. In orthographic top-down, rotation is
      * auto-disabled (pan + zoom stay on) unless you set `lock.rotate` explicitly.
      */
     projection?: CameraProjection;
-    /**
-     * When `projection === 'orthographic'`, frame the scene straight from above.
-     * Default `true`. (Only `true` is meaningful today; reserved for future
-     * orthographic side/front views.)
-     */
-    topDown?: boolean;
     /** Lock interactions. */
     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;
+    /**
+     * What a click picks out. Default `'module'` — the module or mover under
+     * the pointer, as before.
+     *
+     * `'track'` selects the whole processing unit instead, whichever part of
+     * it was hit: that is the granularity the transform gizmo works at, since
+     * a single module has no pose of its own. Static custom assets are always
+     * selected in their own right, in either scope.
+     */
+    selectionScope?: SelectionScope;
     /** Controlled selection. */
     selection?: SelectionState;
     /** Selection-Highlight-Farben. */
-    selectionColors?: {
-        module?: string;
-        mover?: string;
-    };
+    selectionColors?: SelectionColors;
     /**
      * Declarative module highlights — tint all modules matching the given
      * types with the specified color. Works independently of selection:
@@ -3007,6 +3502,8 @@ interface XtsViewer3DProps {
     onCameraChange?: (c: CameraState) => void;
     onMoverClick?: (m: MoverRef) => void;
     onModuleClick?: (m: ModuleRef) => void;
+    /** A click on a static custom asset (`binding.type === 'static'`). */
+    onCustomAssetClick?: (a: CustomAssetRef) => void;
     onMoverHover?: (m: MoverRef | null) => void;
     onModuleHover?: (m: ModuleRef | null) => void;
     onError?: (err: XtsViewerError) => void;
@@ -3030,30 +3527,35 @@ interface XtsViewer3DProps {
     hepcoGfxProfile?: Partial<HepcoGfxRailProfileDims>;
     /** CAD-style ViewCube overlay. */
     viewCube?: ViewCubeOptions;
+    /**
+     * Translate / rotate / scale handles on the selection — a whole track, or
+     * a static custom asset picked in its own right (issue #107). A single
+     * module or mover has no pose of its own and never gets handles, which is
+     * what `selectionScope: 'track'` is for. Off by default; see
+     * `TransformGizmoOptions` for what a drag reports and how it reaches the
+     * configuration.
+     *
+     * @example
+     * ```tsx
+     * <XtsViewer3D
+     *   selectionMode="Single"
+     *   selectionScope="track"
+     *   transformGizmo={{ enabled: true, mode: 'translate' }}
+     * />
+     * ```
+     */
+    transformGizmo?: TransformGizmoOptions;
     /** Stator heatmap data — coloured tube along each part's centerline. */
     statorHeatmap?: StatorHeatmap;
-    /** Continuous mover collision monitoring. */
-    collisionDetection?: {
-        enabled?: boolean;
-        warningGapMm?: number;
-        intervalMs?: number;
-        forceClosedLoop?: boolean;
-        onCollisionsChange?: (collisions: MoverCollision[]) => void;
-    };
     /**
-     * Static MODULE overlap monitoring. Detects track modules that physically
-     * overlap in 3D space — different XPUs / parts placed via `trackTransform`
-     * / `orientation` / `partTransformation`, plus non-adjacent modules of the
-     * same part. Adjacent (seam) modules and the closed-loop seam are
-     * excluded. Recomputed on config / track-transform change (NOT per-frame,
-     * since modules don't move at 60 Hz) — `onCollisionsChange` fires only
-     * when the overlap set actually changes.
+     * Collision monitoring, for movers and for modules.
+     *
+     * One prop with two halves rather than two near-identical props: both
+     * carry `enabled`, `warningGapMm` and `onCollisionsChange`, and a caller
+     * reading the API had no way to tell from the names that
+     * `collisionDetection` meant movers specifically.
      */
-    moduleCollisionDetection?: {
-        enabled?: boolean;
-        warningGapMm?: number;
-        onCollisionsChange?: (collisions: ModuleCollision[]) => void;
-    };
+    collision?: CollisionOptions;
     /**
      * CAD-style measurement tools + annotations, in the 3D view and the 2D
      * plan view alike.
@@ -3111,9 +3613,72 @@ 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>>;
+/**
+ * Plate to attach when a bare carriage has not been given one explicitly.
+ * The 5-pole AT9001-0550 is what the equivalent `_C25` carriage ships with,
+ * and it models the encoder flag the bare S25 is otherwise missing.
+ */
+declare const DEFAULT_MAGNET_PLATE_TYPE: MagnetPlateType3D;
+/**
+ * The plate that should render on top of `moverType`, or `null` when the
+ * mover already has one of its own (or is `Custom`).
+ */
+declare function resolveAttachedPlateType(moverType: MoverType3D, configured?: MagnetPlateType3D): 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.
  *
@@ -3155,33 +3720,21 @@ interface EndDelta {
 declare function moduleEndDelta(module: ModuleCatalogEntry): EndDelta;
 
 /**
- * XtsArcCurve3 — Three.js Curve3 wrapper around the analytic Curve sample.
+ * XtsModuleCurve3 — Three.js Curve3 wrapper around a module's centreline.
  *
- * Each module exposes a THREE.Curve<Vector3> that the part-level CurvePath
- * chains together. For analytic Curves we just wrap the math from
- * pathMath.ts; for Free paths see XtsPointCloudCurve3.
- *
- * Note: CurvePath delegates to subcurve length-proportional, so `getLength()`
- * MUST return the actual arc length so subcurves are weighted correctly.
- * Our subcurves are arc-length parametrised (t = s / L), so this just-works.
- */
-
-declare class XtsArcCurve3 extends Curve<Vector3> {
-    readonly module: ModuleCatalogEntry;
-    constructor(module: ModuleCatalogEntry);
-    getPoint(t: number, optionalTarget?: Vector3): Vector3;
-    getTangent(t: number, optionalTarget?: Vector3): Vector3;
-    getLength(): number;
-}
-
-/**
- * XtsPointCloudCurve3 — Three.js Curve3 wrapper around the Free-path sample.
+ * One class for every `pathType`, because there was never more than one
+ * implementation: `sampleModulePath` already dispatches Straight / Curve /
+ * Free itself, so the two classes this replaces (`XtsArcCurve3` and
+ * `XtsPointCloudCurve3`) were byte-for-byte identical apart from the
+ * `pathType` string each rejected in its constructor.
  *
- * The off-by-one clamp at s == ModuleLength is handled in
- * pathMath.sampleModulePath.
+ * Note: CurvePath delegates to subcurves length-proportionally, so
+ * `getLength()` MUST return the actual arc length for them to be weighted
+ * correctly. Our subcurves are arc-length parametrised (t = s / L), so this
+ * just works.
  */
 
-declare class XtsPointCloudCurve3 extends Curve<Vector3> {
+declare class XtsModuleCurve3 extends Curve<Vector3> {
     readonly module: ModuleCatalogEntry;
     constructor(module: ModuleCatalogEntry);
     getPoint(t: number, optionalTarget?: Vector3): Vector3;
@@ -3192,11 +3745,10 @@ declare class XtsPointCloudCurve3 extends Curve<Vector3> {
 /**
  * PathBuilder — assemble a `THREE.CurvePath<Vector3>` for a Part.
  *
- * One CurvePath per part, chaining all module curves end-to-end.
- * Per module:
- *   - Straight → THREE.LineCurve3 (module geometry baked in)
- *   - Curve    → XtsArcCurve3 (analytic)
- *   - Free     → XtsPointCloudCurve3
+ * One CurvePath per part, chaining all module curves end-to-end. Every
+ * module — Straight, Curve or Free alike — becomes an `XtsModuleCurve3`,
+ * which defers to `sampleModulePath`; that function already dispatches on
+ * `pathType`, so doing it a second time here bought nothing.
  *
  * Each subcurve here is expressed in **module-local coordinates** (origin at
  * module entry). The world transform of the module = chain.startWorldPose
@@ -3224,6 +3776,34 @@ 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.
+ *
+ * The field defaults come from `resolvePose`, which `<PoseGroup>` also uses
+ * to build the corresponding three.js `<group>`. That is what keeps the
+ * matrix these functions return describing the same pose the renderer draws;
+ * `pose.test.ts` asserts it directly.
+ *
+ * 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.
  *
@@ -3328,6 +3908,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.
  *
@@ -3345,6 +3986,34 @@ declare function normaliseToHeatmapRange(value: number, min: number, max: number
  */
 declare function isChainClosed(chain: BuiltChain): boolean;
 
+/**
+ * ARGB integers ↔ CSS hex.
+ *
+ * `StationConfig.stationColor` and `AreaConfig.color` arrive as 32-bit ARGB
+ * ints, which is how the 2D canvas tooling upstream of this viewer stores
+ * colour. three.js wants `#RRGGBB`.
+ *
+ * These lived inside `XtsStations.tsx` and were imported across to
+ * `XtsAreas` and `XtsStopPositionMovers` — a bit-twiddling function reached
+ * through a component. They were also not exported from the package, so the
+ * playground wrote its own copy of the same shifts to render the colour
+ * pickers.
+ */
+/**
+ * `0xAARRGGBB` → `'#RRGGBB'`.
+ *
+ * Alpha is dropped: three.js handles opacity through
+ * `Material.transparent` / `.opacity`, separately from base colour.
+ */
+declare function argbIntToHex(argb: number): string;
+/**
+ * `'#RRGGBB'` → `0xFFRRGGBB`, the inverse of {@link argbIntToHex}.
+ *
+ * Alpha is set to fully opaque, since the hex form carries none. A string
+ * that is not a six-digit hex colour yields opaque black rather than `NaN`.
+ */
+declare function hexToArgbInt(hex: string): number;
+
 /**
  * Feed segments (Einspeisestränge).
  *
@@ -3435,8 +4104,126 @@ declare function collectFeedSegmentsForXpu(xpu: ProcessingUnitConfig, chainsByPa
  * (rendering, imperative API, bounding-box) sees the corrected values.
  */
 
+/**
+ * The Y / Z-Euler flip on a single track transform.
+ *
+ * The flip is its own inverse, so this is also how a value the viewer
+ * computed in its own frame — a pose dragged with the transform gizmo — is
+ * handed back in the convention the host states its transforms in.
+ */
+declare function applyBeckhoffXtsConventionToTrackTransform(tt: TrackTransform): TrackTransform;
+/**
+ * The same Y / Z-Euler flip, applied to the imperative
+ * `trackTransformOverrides` map.
+ *
+ * `effectiveTrackTransform` returns an override *instead of* the config
+ * value, so an override that skipped this pass would be interpreted in the
+ * opposite Y convention from the config entry it replaces — the track would
+ * jump to the mirrored side the moment a caller touched it. Both inputs have
+ * to cross the convention boundary together.
+ */
+declare function applyBeckhoffXtsConventionToOverrides(overrides: Record<number, TrackTransform> | undefined): Record<number, TrackTransform> | undefined;
 declare function applyBeckhoffXtsConvention(config: NormalizedXtsConfig): NormalizedXtsConfig;
 
+/**
+ * HepcoGfxLayout — where the Hepco GFX guideway's repeating features sit along
+ * a Part's chained path.
+ *
+ * Everything here is pure arc-length arithmetic: spans are `[startMm, endMm]`
+ * measured from the start of the chain, and holes are `{ atMm, lateralMm }`.
+ * <HepcoGfxRail> turns those into curve parameters and transforms. Keeping the
+ * layout out of the component is what makes the pattern testable without a
+ * renderer, the same split `moverInstancing.ts` uses for the mover batch.
+ *
+ * ## Where the patterns come from
+ *
+ * Measured off `stepfiles/hepco-gfx-rail/BA-GFX-1TL-3M-B.stp`. In that assembly
+ * the baseplate's module grid runs at 250 mm, and every feature keys off it:
+ *
+ *   - Central plate slots: 104.78 mm long, centred ON the module boundaries.
+ *   - Plate M8 bores: Ø8.5, 62.5 mm pitch (= 250/4) from a module boundary,
+ *     in rows at 30 and 80 mm either side of the plate's centreline.
+ *   - Bracket lightening bores: Ø18, 125 mm pitch, on the 30 mm row so they sit
+ *     directly over every second M8 bore.
+ *   - Bracket wall windows: one 40.23 mm window and two 5.96 mm slots per
+ *     250 mm, at the offsets in `WALL_WINDOWS_MM`.
+ *
+ * The brackets themselves come as `GFX-UMB-1RH` (240.30 mm) and `-2LH`
+ * (490.30 mm) parts — i.e. 250·n − 9.70. Consecutive parts butt exactly on a
+ * module boundary; the 9.70 mm shortfall is taken once at each END of a run,
+ * not as a gap at every joint, and a `GFX-UMB-EB` end block closes each end.
+ *
+ * ## Where a bracket can go
+ *
+ * Not everywhere. The bracket's inner face sits 114 mm inboard of the path, so
+ * on a tight enough turn that face is swept on a radius near zero and the beam
+ * is crushed into the centre of the arc, inside the very module it carries. See
+ * `carriesBracket` for the criterion and the numbers behind it — the catalogue
+ * splits cleanly, with the 22.5 and 45 degree curves nowhere near the limit and
+ * only the AT2050 clothoids past it.
+ *
+ * The 250 mm grid is measured from the start of the chain rather than from each
+ * module, so it stays continuous across the 233 mm and 249 mm short modules —
+ * which is also what the real extruded bracket does, being stock cut to length.
+ */
+
+/** A run along the path, in mm from the start of the chain. */
+interface Span {
+    readonly startMm: number;
+    readonly endMm: number;
+}
+/** One bore, as a point on the path plus a lateral offset in the path frame. */
+interface BorePlacement {
+    readonly atMm: number;
+    /** Lateral offset from the rail centreline, before `stackYOffsetMm` (mm). */
+    readonly lateralMm: number;
+}
+/**
+ * The strips of plate that survive between the central slots — the inner-edge
+ * band the slots would otherwise remove, put back between them.
+ *
+ * The slots are centred on the feature grid, so the first and last are cut off
+ * by the ends of the chain; `invertSpans` clips them rather than dropping them,
+ * which is what a plate cut to length actually looks like.
+ */
+declare function hepcoGfxBaseplateBridgeSpans(chain: BuiltChain, dims: HepcoGfxRailProfileDims): Span[];
+/** A stretch of bracket, and whether each of its ends is a real end. */
+interface BracketRun extends Span {
+    /** The run begins at an end of the bracket, not at a wrap-around seam. */
+    readonly capStart: boolean;
+    readonly capEnd: boolean;
+}
+/**
+ * The stretches the bracket occupies: one per contiguous run of modules that
+ * can carry one, each inset by `HEPCO_BRACKET_END_INSET_MM` at its capped ends.
+ *
+ * A closed chain that begins and ends mid-straight has one run split across the
+ * seam. Those two halves are still extruded separately — the spline runs from 0
+ * to L and cannot cross the seam — but neither is inset or capped there, so the
+ * bracket reads as continuous through it.
+ */
+declare function hepcoGfxBracketRuns(chain: BuiltChain, closed: boolean, dims: HepcoGfxRailProfileDims): BracketRun[];
+/**
+ * The solid stretches of the bracket's upper wall — the complement of the
+ * windows, clipped to the bracket run.
+ */
+declare function hepcoGfxBracketWallSpans(run: Span): Span[];
+/**
+ * The GFX-UMB-EB end blocks: one at each capped end of each run.
+ *
+ * They occupy the first and last 15 mm OF a run, not a further 15 mm beyond it:
+ * in the CAD the run starts at X = -378.04 and the end block occupies
+ * -378.04 to -363.04. The block spans the bracket's full 40 mm width where the
+ * wall above it is only 15 mm, so what it does is close off the open end of the
+ * wall — which is why it has to sit inside the run to be seen. A seam end on a
+ * closed chain is not an end and gets none.
+ */
+declare function hepcoGfxBracketEndBlockSpans(runs: readonly BracketRun[]): Span[];
+/** Every M8 clearance bore in the plate that falls on open plate. */
+declare function hepcoGfxPlateBores(chain: BuiltChain, dims: HepcoGfxRailProfileDims): BorePlacement[];
+/** Every lightening bore through the bracket's base blocks. */
+declare function hepcoGfxBracketBores(runs: readonly BracketRun[], dims: HepcoGfxRailProfileDims): BorePlacement[];
+
 /**
  * Path-sample helpers — convert a chain + a [startMm, endMm] range into a
  * world-frame polyline of Vector3s. Used by Stations, Dimensions and
@@ -3482,9 +4269,15 @@ declare function sampleChainPoint(chain: BuiltChain, positionMm: number, liftZ?:
  *   - Multi  → ctrl/meta-click adds, shift-click range-selects (modules
  *             within the same part only)
  *
- * Range-select is module-only. For movers, shift-click behaves as a
- * plain replacing click — there is no natural "range" along the mover
- * list. Use ctrl/meta for additive mover selection.
+ * Range-select is module-only. For movers, tracks and static custom assets,
+ * shift-click behaves as a plain replacing click — there is no natural
+ * "range" along any of those lists. Use ctrl/meta for additive selection.
+ *
+ * Selecting a whole track (`applyTrackClick`, what `selectionScope: 'track'`
+ * dispatches to) selects everything on it: `isModuleSelected` and
+ * `isMoverSelected` answer `true` for its contents without those entries
+ * being listed one by one, so the track tints as one object and a host
+ * asking "is this module selected" gets the answer it means.
  */
 
 type ClickModifiers = {
@@ -3493,11 +4286,24 @@ type ClickModifiers = {
     meta?: boolean;
 };
 declare const EMPTY_SELECTION: SelectionState;
+declare function isTrackSelected(selection: SelectionState, ref: TrackRef): boolean;
 declare function isModuleSelected(selection: SelectionState, ref: ModuleRef): boolean;
 declare function isMoverSelected(selection: SelectionState, ref: MoverRef): boolean;
+declare function isCustomAssetSelected(selection: SelectionState, ref: CustomAssetRef): boolean;
 declare function deselectAll(): SelectionState;
 declare function applyModuleClick(selection: SelectionState, ref: ModuleRef, mode: SelectionMode, modifiers?: ClickModifiers): SelectionState;
 declare function applyMoverClick(selection: SelectionState, ref: MoverRef, mode: SelectionMode, modifiers?: ClickModifiers): SelectionState;
+/**
+ * A click anywhere on a track, under `selectionScope: 'track'`. Whichever
+ * module or mover was hit, what ends up selected is the processing unit —
+ * the thing that actually has a pose to edit.
+ */
+declare function applyTrackClick(selection: SelectionState, ref: TrackRef, mode: SelectionMode, modifiers?: ClickModifiers): SelectionState;
+/**
+ * A click on a static custom asset. Same modes as the others, minus
+ * range-select: custom assets have no order to range over.
+ */
+declare function applyCustomAssetClick(selection: SelectionState, ref: CustomAssetRef, mode: SelectionMode, modifiers?: ClickModifiers): SelectionState;
 declare function applyEmptyClick(selection: SelectionState, mode: SelectionMode): SelectionState;
 
 /**
@@ -3530,24 +4336,70 @@ 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.
+ * Default axis palette — the red / green / blue triple used by the common
+ * viewport gizmos (three-viewport-gizmo, Blender, Fusion). Bright enough to
+ * stay readable on both the light and the dark canvas backgrounds.
  */
+declare const GIZMO_AXIS_COLORS: readonly [string, string, string];
+/** Default handle letters, positive axes first. */
+declare const GIZMO_AXIS_LABELS: readonly [string, string, string];
 
 /**
- * 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.
+ * 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).
+ *
+ * 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
@@ -3558,7 +4410,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 {
@@ -3579,9 +4431,10 @@ declare const MoverIdLabel: React__default.FC<MoverIdLabelProps>;
  * so the viewer renders correctly without a matching CDN mirror.
  *
  * Module count: 27
- * Mover count:  13
+ * Mover count:  12
  * Tool count:   2
- * Rail count:   8
+ * Plate count:  7
+ * Rail count:   11
  */
 
 /**
@@ -3635,8 +4488,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). */
@@ -3662,7 +4515,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
@@ -3672,12 +4525,15 @@ declare const MODULE_GUIDING_RAIL_MAP: Readonly<Partial<Record<ModuleType3D, Rai
 /** Resolve a module's GLB URL with manifest override + rail-system fallback. */
 declare function resolveModuleGlbUrl(moduleType: ModuleType3D, rail: RailSystem, override?: AssetManifest['modules']): string | null;
 declare function resolveMoverGlbUrl(moverType: MoverType3D, override?: AssetManifest['movers']): string;
+declare function resolvePlateGlbUrl(plateType: MagnetPlateType3D, override?: AssetManifest['magnetPlates']): 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.
@@ -3774,9 +4630,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
@@ -3803,6 +4659,10 @@ interface SidecarKinds {
         id: MoverToolType3D;
         sidecar: MoverToolSidecar;
     };
+    plate: {
+        id: MagnetPlateType3D;
+        sidecar: MagnetPlateSidecar;
+    };
     rail: {
         id: RailType3D;
         sidecar: RailSidecar;
@@ -3922,4 +4782,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 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, 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, 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 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, chainToUserPositionMm, checkAllModuleCollisions, checkAllMoverCollisions, 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, toModuleCollisionInputs, 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 BorePlacement, type BracketRun, type BuiltChain, type BuiltModule, type CalibrationMarkerOptions, type CameraProjection, type CameraState, type CaptureDimensions, type CaptureMode, type CaptureRequest, type CheckModuleCollisionsOptions, type CheckMoverCollisionsOptions, type ClickModifiers, type CollisionOptions, type CoordinateSystem, type CustomAssetBinding, type CustomAssetConfig, type CustomAssetRef, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MAGNET_PLATE_TYPE, 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, GIZMO_AXIS_COLORS, GIZMO_AXIS_LABELS, 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, type LightingOptions, 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 MeasurementPatch, type MeasurementPoint, type MeasurementResult, type MeasurementSnapshot, type MeasurementStyle, type MeasurementTool, type ModuleAssetEntry, type ModuleCatalogEntry, type ModuleCollision, type ModuleCollisionOptions, 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 MoverCollisionOptions, type MoverConfig, MoverIdLabel, type MoverIdLabelOptions, type MoverPositionEntry, type MoverProbe, type MoverRef, type MoverSidecar, type MoverToolAssetEntry, type MoverToolConfig, type MoverToolSidecar, type MoverToolStateEntry, 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 PostProcessingOptions, type ProcessingUnitConfig, type ProfilePoint, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, type ResolvedMeasurementStyle, SIDECAR_KINDS, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionColors, type SelectionMode, type SelectionScope, 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 Span, 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 TrackRef, type TrackTransform, type TransformGizmoChange, type TransformGizmoMode, type TransformGizmoOptions, type TransformGizmoPose, type TransformGizmoTarget, VERSION, type Vec2, type Vec3, type ViewCubeAlignment, type ViewCubeOptions, XtsModuleCurve3 as XtsArcCurve3, type XtsConfig, XtsConfigNormalizer, type XtsModelDocument, XtsModuleCurve3, XtsModuleCurve3 as XtsPointCloudCurve3, type XtsRuntimeState, XtsViewer3D, type XtsViewer3DProps, type XtsViewer3DRef, type XtsViewerError, type XtsViewerErrorCode, XtsViewerErrorException, angleDeg, applyBeckhoffXtsConvention, applyBeckhoffXtsConventionToOverrides, applyBeckhoffXtsConventionToTrackTransform, applyCustomAssetClick, applyEmptyClick, applyModuleClick, applyMoverClick, applyTrackClick, arcPoints, argbIntToHex, axisDistanceMm, buildChain, buildHepcoGfxBaseplateBridgeOutline, buildHepcoGfxBaseplateOutline, buildHepcoGfxBracketBaseOutline, buildHepcoGfxBracketEndBlockOutline, buildHepcoGfxBracketOutline, buildHepcoGfxBracketWallOutline, buildHepcoGfxRailOutline, buildModuleProbes, buildPartPath, buildTrackIndex, bundledLabelFontUrl, chainToUserPositionMm, checkAllModuleCollisions, checkAllMoverCollisions, checkModuleCollisions, checkSamePathCollisions, chooseSnapCandidate, coarseHeightSpan, collectFeedSegments, collectFeedSegmentsForXpu, collectTriangleSnapCandidates, composeAssetUrl, computeMeasurementResult, createHepcoGfxBaseplateBridgeShape, createHepcoGfxBaseplateShape, createHepcoGfxBracketBaseShape, createHepcoGfxBracketEndBlockShape, createHepcoGfxBracketShape, createHepcoGfxBracketWallShape, createHepcoGfxRailShape, deselectAll, distanceMm, findModuleAt, formatAngleDeg, formatLengthMm, getMagnetPlateEntry, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, heightSpanOf, hepcoGfxBaseplateBridgeSpans, hepcoGfxBracketBores, hepcoGfxBracketEndBlockSpans, hepcoGfxBracketRuns, hepcoGfxBracketWallSpans, hepcoGfxPlateBores, hexToArgbInt, interpolateHeatmapValue, isChainClosed, isCustomAssetSelected, isKnownMagnetPlateType, isKnownModuleType, isKnownMoverType, isModuleSelected, isMoverSelected, isTrackSelected, labelAnchorFor, moduleAnchorWorld, moduleEndDelta, moduleHeightSpan, moduleSidecarFilename, moverAnchorWorld, moverSidecarFilename, moverWorldAt, nearestTrackPoint, normaliseToHeatmapRange, normalizeXtsConfig, pathLengthsMm, pickGlbForRail, poseToMatrix4, railSidecarFilename, registerPointCloud, resolveAttachedPlateType, resolveEntityFromObject, resolveGuidingRailGlbUrl, resolveGuidingRailType, resolveHepcoGfxProfile, resolveMeasurementStyle, resolveModuleGlbUrl, resolveMoverGlbUrl, resolveOriginCorrection, resolvePlateGlbUrl, resolveStopPositionMm, resolveToolGlbUrl, sampleChainPoint, sampleChainRange, sampleModulePath, snapToGrid, sortHeatmapSamples, splitIntoFeedSegments, toModuleCollisionInputs, toolSidecarFilename, trackAnchorWorld, trackDistanceMm, trackLengthOf, trackPolylineWorld, unregisterPointCloud, useSidecarSource, userToChainPositionMm, worldPointOnPart };