beckhoff-xts-viewer-3d 0.3.1 → 2.0.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default from 'react';
-import { ColorRepresentation, Curve, Vector3, CurvePath, Matrix4 } from 'three';
+import { ColorRepresentation, Shape, Curve, Vector3, CurvePath, Matrix4 } 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: "0.3.1";
+declare const VERSION: "2.0.0";
 
 /**
  * Default CDN URL for the GLB asset bundle (`beckhoff-xts-viewer-3d-assets`).
@@ -24,9 +24,13 @@ declare const VERSION: "0.3.1";
  *   `Cannot access 'JSDELIVR_ASSETS_BASE_URL' before initialization`
  * because the const sits in the TDZ when XtsViewer3D's module body runs.
  *
- * Pinned to this package's version so a `viewer@x.y.z` install always
- * resolves to `assets@x.y.z` — no version drift between the calibration
- * data baked into the JS bundle and the GLB geometry served by the CDN.
+ * Pinned to the assets package version this viewer build targets (see
+ * ./assetsVersion.ts). The assets release line is decoupled from the
+ * viewer release line — assets only publish a new version when GLB
+ * geometry actually changes — so `viewer@x.y.z` does NOT generally
+ * resolve to `assets@x.y.z`. The exact version is captured at viewer
+ * 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@0.3.1/models";
 
@@ -42,15 +46,20 @@ type ModuleType3D = 'AT2000_0250' | 'AT2001_0250' | 'AT2002_0250' | 'AT2002_0249
 /**
  * Schienensystem unter dem Modul. Beeinflusst nur das visuelle Mesh
  * (Beckhoff Aluminium-Schiene vs. Hepco GFX), nicht die Pfad-Math.
+ *
+ * `Beckhoff` ist die Beckhoff-Aluminium-Führungsschiene (alle
+ * AT-Standard- + Eco-Familien); `HepcoGfx` ist das alternative
+ * Hepco-GFX-Profil. ATH-Module bringen ihre Schiene im Modul-GLB
+ * mit und sind von dieser Wahl unabhängig.
  */
-type RailSystem = 'BeckhoffGuidingRail' | 'HepcoGfx';
+type RailSystem = 'Beckhoff' | 'HepcoGfx';
 /** Beckhoff XTS + Hepco mover types. `Custom` requires `customMoverLayout`. */
 type MoverType3D = 'AT9011_0050' | 'AT9011_0070' | 'AT9012_0050' | 'AT9014_0055' | 'AT9014_0070' | 'ATH9011_0075' | 'ATH9013_0075' | 'Hepco_GFX2_1TC_S25' | 'Custom';
 /** Predefined mover-tool / carrier-plate types (spec §4.8). */
 type MoverToolType3D = 'AT8200_1000_0100' | 'AT8200_2000_0100' | 'Custom';
 /**
  * Beckhoff guiding-rail GLB variants. Rendered alongside the motor modules
- * when `RailSystem === 'BeckhoffGuidingRail'` to visualise the outer guide
+ * when `RailSystem === 'Beckhoff'` to visualise the outer guide
  * profile that the mover wheels engage.
  *
  * Curve sign drives the selection (see `MODULE_GUIDING_RAIL_MAP`):
@@ -139,10 +148,15 @@ interface XtsConfig {
     customAssets?: CustomAssetConfig[];
 }
 interface ProcessingUnitConfig {
-    index: number;
+    /**
+     * Stable host-supplied 32-bit unique identifier for this XPU. Required
+     * at runtime — must be a non-negative integer that fits in a uint32
+     * and is unique across all XPUs in the config.
+     */
+    objectId: number;
     moverType: MoverType3D;
     customMoverLayout?: CustomMoverLayout;
-    /** Default: 'BeckhoffGuidingRail'. */
+    /** Default: 'Beckhoff'. */
     railSystem?: RailSystem;
     parts: PartConfig[];
     movers: MoverConfig[];
@@ -192,20 +206,46 @@ interface TrackTransform {
     visible?: boolean;
 }
 interface PartConfig {
+    /**
+     * Stable host-supplied 32-bit unique identifier for this part. Distinct
+     * from `globalNumber` (server-side ObjectId): callers reference parts
+     * by `objectId` at runtime — e.g. in the array form of
+     * `XtsViewer3DRef.setMoverPositions` (`{partObjectId, partPosition}`).
+     * Required at runtime — must be a non-negative integer that fits in a
+     * uint32 and is unique across all parts in the system.
+     * `normalizeXtsConfig` emits a `missing-part-object-id` /
+     * `invalid-part-object-id` / `duplicate-part-object-id` warning when
+     * the contract is violated.
+     */
+    objectId: number;
     /** = ServerTypes.PartModel.ObjectId — eindeutig systemweit. */
     globalNumber: number;
-    /** 0-basiert in der XPU. */
-    index: number;
     modules: ModuleEntry[];
     partTransformation?: PartTransformation;
 }
 interface ModuleEntry {
     moduleType: ModuleType3D;
+    /**
+     * Stable host-supplied number for this module. Required at runtime —
+     * simply counted up per module (1, 2, 3, …) across the whole system
+     * and used as the index in `XtsViewer3DRef.setModuleStatuses(array)` —
+     * i.e. `statuses[m.globalNumber] === { warning?: …, error?: … }`.
+     * `normalizeXtsConfig` emits a `missing-module-global-number` /
+     * `invalid-module-global-number` / `duplicate-module-global-number`
+     * warning when the contract is violated. Typed optional only so
+     * legacy configs and tests keep compiling; new code MUST set it.
+     */
+    globalNumber?: number;
     /**
      * Optional drive-status overlay for this module. Mirrors the
      * `MoverConfig.status` shape; the same per-mesh emissive blink +
      * billboard <DriveStatusIcon> surfaces both. Filtered by
      * `display.showDriveWarnings` / `display.showDriveErrors`.
+     *
+     * For live updates (e.g. drive warnings/errors streamed from PLC),
+     * prefer the imperative
+     * `XtsViewer3DRef.setModuleStatuses(array)` channel — index = this
+     * module's `globalNumber`. The store wins over this config-time value.
      */
     status?: {
         warning?: boolean;
@@ -213,23 +253,44 @@ interface ModuleEntry {
     };
 }
 /**
- * All fields are optional and default to identity (offset = [0,0],
- * rotation = 0). `applyLayout.resolvePartTransformation` produces a value
- * where `offsetMm` and `rotationDeg` are always populated (`?? 0`), but
- * raw host-supplied transforms may omit either side of the split.
+ * Per-part 3D pose, applied to EVERYTHING anchored to the part:
+ * modules, guiding rails, movers, mover tools, mover-bound custom assets,
+ * and the path-derived overlays (stations, areas, dimensions, info bars,
+ * stop-position ghost movers, stator heatmap). Composes inside the
+ * per-XPU `trackTransform`:
+ *
+ *     world = orientation ⊗ trackTransform ⊗ partTransformation ⊗ chain
+ *
+ * All fields are optional and default to identity (offset = [0,0,0],
+ * rotation = [0,0,0]). Whole-track placement is done via
+ * `ProcessingUnitConfig.trackTransform`; this transform is for moving a
+ * part WITHIN its XPU — e.g. lifts that translate along Z, parts
+ * mounted at an angle, or live-editable kinematics in the playground.
+ *
+ * Multi-part overlays (stations / areas spanning multiple `partOids`)
+ * follow the transform of their FIRST partOid — the chain math
+ * upstream is part-local, and points from differently-transformed
+ * parts can't be stitched into a single tube. Anchor multi-part
+ * overlays to the part you want them to track.
  */
 interface PartTransformation {
-    offsetMm?: Vec2;
-    rotationDeg?: number;
+    /** Translation in mm, in the XPU's track-transform frame. */
+    offsetMm?: Vec3;
+    /** Intrinsic XYZ Euler angles in degrees. */
+    rotationDegEuler?: Vec3;
     partSide?: 'Default' | 'Driver' | 'Encoder';
+    /** Hide everything on this part when false. Default true. */
     visible?: boolean;
-    /** Server-Side-Werte für SystemView-Layout (additiv). */
-    serverOffsetMm?: Vec2;
-    serverRotationDeg?: number;
 }
 interface MoverConfig {
-    moverIndex: number;
-    id: string;
+    /** Position-on-track index within the XPU. */
+    index: number;
+    /**
+     * Stable host-supplied 32-bit unique identifier for this mover.
+     * Required, must be a non-negative integer that fits in a uint32 and
+     * is unique across all movers in the config.
+     */
+    id: number;
     /** Verweist auf PartConfig.globalNumber. */
     partOid: number;
     /** [0, part.trackLengthMm] — clamped wenn out-of-bounds. */
@@ -242,6 +303,28 @@ interface MoverConfig {
     /** Vordefinierte Werkzeug-Carrier oder Custom-GLBs an diesem Mover. */
     tools?: MoverToolConfig[];
 }
+/**
+ * Runtime mover-position update entry — pushed through
+ * `XtsViewer3DRef.setMoverPositions(array)`. The array is indexed by
+ * `MoverConfig.index` (i.e. entry `i` targets the mover with
+ * `index === i`); use `null` / `undefined` to skip a slot. The
+ * `partObjectId` field references `PartConfig.objectId`.
+ */
+interface MoverPositionEntry {
+    /** = PartConfig.objectId (the host-side 32-bit unique part ID). */
+    partObjectId: number;
+    /** Position along the referenced part, in user-frame mm. */
+    partPosition: number;
+}
+/**
+ * Runtime drive-status entry for a single module — pushed through
+ * `XtsViewer3DRef.setModuleStatuses(array)`. The array is indexed by
+ * `ModuleEntry.globalNumber`; use `null` / `undefined` to clear a slot.
+ */
+interface ModuleStatusEntry {
+    warning?: boolean;
+    error?: boolean;
+}
 interface MoverToolConfig {
     toolType: MoverToolType3D;
     /** Required when toolType === 'Custom'. */
@@ -276,7 +359,7 @@ type CustomAssetBinding = {
 } | {
     type: 'mover';
     moverRef: {
-        processingUnitIndex: number;
+        processingUnitObjectId: number;
         moverIndex: number;
     };
     offsetMm?: Vec3;
@@ -297,7 +380,6 @@ interface CustomAssetConfig {
     opacity?: number;
     visible?: boolean;
 }
-type LayoutMode = 'SystemView' | 'InvertedSystemView' | 'Custom';
 interface DisplayOptions {
     displayStations?: boolean;
     /** Render konfigurierte Areas. Default: true (wenn `areas[]` gesetzt ist). */
@@ -305,9 +387,20 @@ interface DisplayOptions {
     displayDimensions?: boolean;
     showDriveErrors?: boolean;
     showDriveWarnings?: boolean;
+    /**
+     * Render each mover's `id` as a billboarded 3D text label above the
+     * mover. Toggle on/off without re-creating the scene. Visual options
+     * (font size, color, offset, font URL, outline) are configurable via
+     * `moverIdLabelOptions`. Default: false.
+     */
     showMoverIds?: boolean;
+    /**
+     * Style + placement overrides for the mover-id labels. Only applied
+     * when `showMoverIds === true`. All fields optional; sensible defaults
+     * shipped by the renderer.
+     */
+    moverIdLabelOptions?: MoverIdLabelOptions;
     invertDimensions?: boolean;
-    layout?: LayoutMode;
     stationOptions?: StationOptions;
     stationMarkerOptions?: MarkerOptions;
     /**
@@ -396,6 +489,40 @@ interface DisplayOptions {
      */
     toneMappingExposure?: number;
 }
+/**
+ * Style + placement overrides for the per-mover-id 3D text labels
+ * surfaced when `DisplayOptions.showMoverIds === true`.
+ *
+ * Defaults (all in scene units / mm; chosen for legibility on the
+ * default mover GLB at typical XTS layouts):
+ *   - `fontSizeMm`: 15
+ *   - `color`: '#000000'
+ *   - `offsetMm`: [0, 0, 55]  // centred above the mover's magnet plate
+ *   - `fontUrl`: `DEFAULT_LABEL_FONT_URL` (Roboto Condensed)
+ *   - `outlineWidthMm`: 0    // no outline
+ *   - `outlineColor`: '#FFFFFF'
+ */
+interface MoverIdLabelOptions {
+    /** Text height in mm (world units). Default: 15. */
+    fontSizeMm?: number;
+    /** CSS color for the text fill. Default: '#000000'. */
+    color?: string;
+    /**
+     * Offset of the label's anchor point relative to the mover's local
+     * origin (= magnet-plate center), in mm.
+     * `[x, y, z]` — Z is up. Default: `[0, 0, 25]`.
+     */
+    offsetMm?: Vec3;
+    /**
+     * URL of a TTF / OTF / WOFF font, passed straight to troika-three-text.
+     * Default: `DEFAULT_LABEL_FONT_URL` (Roboto Condensed via jsDelivr).
+     */
+    fontUrl?: string;
+    /** Outline thickness in mm. 0 disables the outline. Default: 0. */
+    outlineWidthMm?: number;
+    /** Outline color. Only applied if `outlineWidthMm > 0`. Default: '#FFFFFF'. */
+    outlineColor?: string;
+}
 interface StationOptions {
     thicknessMm?: number;
     /** Vertical Z lift (mm). Positive = above the table. */
@@ -609,8 +736,8 @@ interface AreaConfig {
     color: number;
 }
 interface InfoBarConfig {
-    processingUnitIndex: number;
-    partIndex: number;
+    processingUnitObjectId: number;
+    partObjectId: number;
     partStartPositionMm: number;
     partEndPositionMm: number;
     thickness: number;
@@ -633,12 +760,12 @@ interface InfoBarMarkerConfig {
     color?: string;
 }
 interface ModuleRef {
-    processingUnitIndex: number;
-    partIndex: number;
+    processingUnitObjectId: number;
+    partObjectId: number;
     moduleIndex: number;
 }
 interface MoverRef {
-    processingUnitIndex: number;
+    processingUnitObjectId: number;
     moverIndex: number;
 }
 interface SelectionState {
@@ -678,7 +805,7 @@ interface RailAssetEntry {
 interface ModuleAssetEntry {
     /** Per-RailSystem GLB URL (relative to assetsBaseUrl). */
     glbByRailSystem: {
-        BeckhoffGuidingRail: string | null;
+        Beckhoff: string | null;
         HepcoGfx?: string | null;
     };
     sidecarUrl?: string;
@@ -707,9 +834,9 @@ interface XtsModelDocument {
 }
 interface XtsRuntimeState {
     movers: Array<{
-        processingUnitIndex: number;
+        processingUnitObjectId: number;
         moverIndex: number;
-        id: string;
+        id: number;
         partOid: number;
         partPositionMm: number;
         velocity?: {
@@ -807,6 +934,9 @@ interface BuiltModule {
     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?: {
@@ -890,8 +1020,8 @@ interface MoverCollision {
      * Stable IDs of the two movers (mirrors `MoverConfig.id`). Useful when
      * the consumer keys by id rather than by `moverIndex`.
      */
-    idA: string;
-    idB: string;
+    idA: number;
+    idB: number;
     /**
      * Penetration along the 1D path:
      *   • `> 0` — movers overlap by this many mm.
@@ -935,7 +1065,7 @@ interface CheckMoverCollisionsOptions {
  */
 interface MoverProbe {
     ref: MoverRef;
-    id: string;
+    id: number;
     partOid: number;
     moverType: MoverType3D;
     partPositionMm: number;
@@ -985,7 +1115,7 @@ interface NormalizedXtsConfig extends XtsConfig {
     readonly __warnings: NormalizationWarning[];
 }
 interface NormalizationWarning {
-    code: 'mover-out-of-range' | 'mover-orphan' | 'mover-duplicate-id' | 'empty-part' | 'prepared-module';
+    code: 'mover-out-of-range' | 'mover-orphan' | 'mover-duplicate-id' | 'mover-missing-id' | 'mover-invalid-id' | 'empty-part' | 'prepared-module' | 'duplicate-xpu-object-id' | 'missing-xpu-object-id' | 'invalid-xpu-object-id' | 'duplicate-part-object-id' | 'missing-part-object-id' | 'invalid-part-object-id' | 'duplicate-module-global-number' | 'missing-module-global-number' | 'invalid-module-global-number';
     message: string;
     details?: unknown;
 }
@@ -1005,10 +1135,10 @@ interface NormalizationWarning {
  */
 declare class XtsConfigNormalizer {
     private _cache;
-    normalize(config: XtsConfig, layout?: LayoutMode): NormalizedXtsConfig;
+    normalize(config: XtsConfig): NormalizedXtsConfig;
     clearCache(): void;
 }
-declare function normalizeXtsConfig(config: XtsConfig, layout?: LayoutMode): NormalizedXtsConfig;
+declare function normalizeXtsConfig(config: XtsConfig): NormalizedXtsConfig;
 
 /**
  * captureScreenshot — render the live r3f scene into an offscreen
@@ -1141,9 +1271,29 @@ interface XtsViewer3DRef {
     }): XtsModelDocument;
     exportScreenshot(opts?: ScreenshotOptions): Promise<ScreenshotResult>;
     reloadAssets(): Promise<void>;
-    setMoverPosition(moverId: string, partPositionMm: number): void;
-    setMoverPositions(record: Record<string, number>): void;
-    getMoverPosition(moverId: string): number | null;
+    setMoverPosition(moverId: number, partPositionMm: number): void;
+    /**
+     * Push mover positions in bulk. Two accepted forms:
+     *
+     *  1. `Record<moverId, partPositionMm>` — backwards-compatible single-
+     *     part-per-mover update. The mover stays on its config-time part.
+     *  2. `MoverPositionEntry[]` — array indexed by `MoverConfig.index`
+     *     (entry `i` targets the mover with `index === i`); each entry
+     *     supplies the `partObjectId` (= `PartConfig.objectId`) the mover is
+     *     currently on plus its position. `null` / `undefined` entries are
+     *     skipped — leave them untouched in the store.
+     */
+    setMoverPositions(update: Record<number, number> | ReadonlyArray<MoverPositionEntry | null | undefined>): void;
+    getMoverPosition(moverId: number): number | null;
+    /**
+     * Push live drive-status (warning / error) onto motor modules. The
+     * `statuses` array is indexed by `ModuleEntry.globalNumber` — i.e.
+     * `statuses[m.globalNumber] === { warning, error }`. `null` clears a
+     * slot; `undefined` leaves it unchanged.
+     */
+    setModuleStatuses(statuses: ReadonlyArray<ModuleStatusEntry | null | undefined>): void;
+    /** Clear all live module statuses (revert to config-time `ModuleEntry.status`). */
+    clearModuleStatuses(): void;
     checkMoverCollisions(opts?: CheckMoverCollisionsOptions): MoverCollision[];
 }
 
@@ -1166,7 +1316,7 @@ interface OriginCorrection {
 interface ModuleSidecar {
     moduleType: ModuleType3D;
     glbByRailSystem: {
-        BeckhoffGuidingRail: string | null;
+        Beckhoff: string | null;
         HepcoGfx?: string | null;
     };
     originCorrection: OriginCorrection;
@@ -1245,6 +1395,103 @@ declare function railSidecarFilename(railType: RailType3D): string;
  */
 declare function pickGlbForRail(sidecar: ModuleSidecar | undefined, rail: RailSystem): string | null;
 
+/**
+ * HepcoGfxRailProfile — cross-section of the Hepco GFX guiding rail used by
+ * the procedural extrusion in <HepcoGfxRail>.
+ *
+ * The profile is expressed in the Beckhoff path-frame convention:
+ *   - path tangent = +X (extrusion direction)
+ *   - lateral      = ±Y (left/right of the path)
+ *   - vertical     = ±Z (Z-up, path origin at Z=0)
+ *
+ * THREE.ExtrudeGeometry maps a Shape's local X to the curve's Frenet normal
+ * and Shape's local Y to the binormal. For a planar curve in the world XY
+ * 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.
+ *
+ * The Hepco GFX cross-section is TWO disconnected regions:
+ *
+ *  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.
+ *
+ *  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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+interface HepcoGfxRailProfileDims {
+    /** Baseplate Y-extent per track (mm). Half of the XTS oval's full
+     *  cross-section width. */
+    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. */
+    readonly baseplateTopZMm: number;
+    /** Rail Y-extent, spear-apex to spear-apex (mm). */
+    readonly railWidthMm: number;
+    /** Rail Z-extent, main-body top to main-body bottom (mm). */
+    readonly railHeightMm: number;
+    /** Z-coordinate of the rail's main-body top in the path frame (before
+     *  stackZOffsetMm is applied). */
+    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. */
+    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). */
+    readonly stackYOffsetMm: number;
+    /** Calibration shift in Z applied to baseplate + rail together (mm). */
+    readonly stackZOffsetMm: number;
+}
+/**
+ * Scaffolding dimensions (mm). The stack offsets bake in the user-
+ * requested calibration so the rendered geometry is correct out of the
+ * box; the playground / a `*.meta.json` sidecar can override them.
+ */
+declare const HEPCO_GFX_PROFILE: HepcoGfxRailProfileDims;
+/**
+ * Merge a partial profile override onto the default profile. Used by the
+ * playground / sidecar loader so callers only need to supply the fields
+ * they want to override.
+ */
+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.
+ */
+declare function createHepcoGfxBaseplateShape(dims?: HepcoGfxRailProfileDims): Shape;
+/**
+ * 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 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.
+ */
+declare function createHepcoGfxRailShape(dims?: HepcoGfxRailProfileDims): Shape;
+
 /**
  * <XtsViewer3D> — Top-level React component (spec §6.1).
  *
@@ -1335,6 +1582,12 @@ interface XtsViewer3DProps {
      * Live override of per-XPU `trackTransform`. Keyed by `xpu.index`.
      */
     trackTransformOverrides?: Record<number, TrackTransform>;
+    /**
+     * Live override of the procedural Hepco-GFX rail profile dimensions.
+     * Only the fields you supply are merged onto the defaults — useful for
+     * the playground calibration UI / a sidecar-style `*.meta.json`.
+     */
+    hepcoGfxProfile?: Partial<HepcoGfxRailProfileDims>;
     /** CAD-style ViewCube overlay. */
     viewCube?: {
         enabled?: boolean;
@@ -1604,24 +1857,6 @@ declare function interpolateHeatmapValue(samples: ReadonlyArray<HeatmapSample>,
  */
 declare function normaliseToHeatmapRange(value: number, min: number, max: number): number;
 
-/**
- * applyLayout — resolve PartTransformation per Layout-Mode.
- *
- * Spec §5:
- *   - SystemView         → effective = serverTransform ⊕ clientTransform
- *   - InvertedSystemView → effective = invertX(serverTransform) ⊕ clientTransform
- *   - Custom             → effective = clientTransform (server ignored)
- *
- * "Invert" only flips the X-component of the offset.
- *
- * The function returns a NEW PartTransformation with no separate server/
- * client split — downstream components only need the resolved value.
- */
-
-declare function resolvePartTransformation(part: PartConfig, layout: LayoutMode): PartTransformation | undefined;
-/** Pre-resolve PartTransformations across the whole config. */
-declare function applyLayoutMode(xpus: ReadonlyArray<ProcessingUnitConfig>, layout: LayoutMode): ProcessingUnitConfig[];
-
 /**
  * Path-sample helpers — convert a chain + a [startMm, endMm] range into a
  * world-frame polyline of Vector3s. Used by Stations, Dimensions and
@@ -1734,6 +1969,25 @@ declare const ModuleCornerMarkers: React__default.FC<Props>;
  */
 declare const DEFAULT_LABEL_FONT_URL: "https://cdn.jsdelivr.net/npm/@fontsource/roboto-condensed@5.2.7/files/roboto-condensed-latin-400-normal.woff";
 
+/**
+ * <MoverIdLabel> — Camera-facing 3D text label that shows a mover's
+ * `id` above the mover GLB. Mounted by `<XtsMover>` when
+ * `DisplayOptions.showMoverIds === true`.
+ *
+ * Renders via drei's `<Billboard>` + `<Text>` (troika-three-text under
+ * 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).
+ */
+
+interface MoverIdLabelProps {
+    /** The mover's `id` — rendered verbatim. */
+    text: string;
+    options?: MoverIdLabelOptions;
+}
+declare const MoverIdLabel: React__default.FC<MoverIdLabelProps>;
+
 /**
  * AUTO-GENERATED — do not edit by hand.
  *
@@ -1747,7 +2001,7 @@ declare const DEFAULT_LABEL_FONT_URL: "https://cdn.jsdelivr.net/npm/@fontsource/
  * Module count: 27
  * Mover count:  4
  * Tool count:   2
- * Rail count:   7
+ * Rail count:   8
  */
 
 /**
@@ -1798,10 +2052,10 @@ declare function useSidecarSource(): SidecarSourceConfig;
  * skins, or to plug in user GLBs).
  *
  * Hygienic ATH modules carry per-RailSystem URLs. Standard AT/Eco modules
- * only set `BeckhoffGuidingRail`; the loader silently falls back to that
+ * only set `Beckhoff`; the loader silently falls back to that
  * variant when `HepcoGfx` is requested but unavailable (spec §4.3).
  *
- * `null` for `BeckhoffGuidingRail` marks "prepared but not delivered"
+ * `null` for `Beckhoff` marks "prepared but not delivered"
  * (AT2042 / AT2140) — the loader renders a placeholder AABB mesh
  * (spec §14.4).
  */
@@ -1816,7 +2070,7 @@ declare const DEFAULT_TOOL_MANIFEST: Readonly<Record<MoverToolType3D, {
 }>>;
 /**
  * Beckhoff guiding-rail GLBs (the outer rail profile that the mover wheels
- * engage). Rendered per module when `RailSystem === 'BeckhoffGuidingRail'`;
+ * engage). Rendered per module when `RailSystem === 'Beckhoff'`;
  * Hepco GFX uses a different profile and is handled separately.
  */
 declare const DEFAULT_RAIL_MANIFEST: Readonly<Record<RailType3D, {
@@ -1913,4 +2167,4 @@ declare const SPEC_VERSION: "v5";
 /** Returns the spec version this package targets. */
 declare function specVersion(): string;
 
-export { type AreaConfig, type AreaOptions, AssetLoader, type AssetManifest, BUILTIN_MODULE_SIDECARS, BUILTIN_MOVER_SIDECARS, BUILTIN_RAIL_SIDECARS, BUILTIN_TOOL_SIDECARS, type BuiltChain, type BuiltModule, type CameraState, type CheckMoverCollisionsOptions, type ClickModifiers, type CustomAssetBinding, type CustomAssetConfig, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MODULE_MANIFEST, DEFAULT_MOVER_MANIFEST, DEFAULT_ORIGIN_CORRECTION, DEFAULT_RAIL_MANIFEST, DEFAULT_TOOL_MANIFEST, type DimensionOptions, type DisplayOptions, EMPTY_SELECTION, type EndDelta, type HeatmapSample, IDENTITY_POSE, type InfoBarConfig, type InfoBarMarkerConfig, type InfoBarOptions, JSDELIVR_ASSETS_BASE_URL, type LayoutMode, MODULE_CATALOG, MODULE_GUIDING_RAIL_MAP, MOVER_CATALOG, type MarkerOptions, type MarkerShape, type ModuleAssetEntry, type ModuleCatalogEntry, ModuleCornerMarkers, type ModuleEntry, type ModuleRef, type ModuleSidecar, type ModuleType3D, type MoverAssetEntry, type MoverCatalogEntry, type MoverCollision, type MoverConfig, 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 PathSample, type PathType, type PlanarPose, type PointCloud, type PositionFrame, type ProcessingUnitConfig, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, SPEC_VERSION, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionMode, type SelectionState, SidecarLoader, type SidecarOverrides, type SidecarSourceConfig, SidecarSourceContext, type StationConfig, type StationOptions, type StatorHeatmap, type StopPositionMoverOptions, type TextOptions, type TrackTransform, VERSION, type Vec2, type Vec3, XtsArcCurve3, type XtsConfig, XtsConfigNormalizer, type XtsModelDocument, XtsPointCloudCurve3, type XtsRuntimeState, XtsViewer3D, type XtsViewer3DProps, type XtsViewer3DRef, type XtsViewerError, type XtsViewerErrorCode, XtsViewerErrorException, applyEmptyClick, applyLayoutMode, applyModuleClick, applyMoverClick, buildChain, buildPartPath, chainToUserPositionMm, checkSamePathCollisions, composeAssetUrl, deselectAll, findModuleAt, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, interpolateHeatmapValue, isKnownModuleType, isKnownMoverType, isModuleSelected, isMoverSelected, moduleEndDelta, moduleSidecarFilename, moverSidecarFilename, moverWorldAt, normaliseToHeatmapRange, normalizeXtsConfig, pickGlbForRail, poseToMatrix4, railSidecarFilename, registerPointCloud, resolveGuidingRailGlbUrl, resolveGuidingRailType, resolveModuleGlbUrl, resolveMoverGlbUrl, resolveOriginCorrection, resolvePartTransformation, resolveStopPositionMm, resolveToolGlbUrl, sampleChainPoint, sampleChainRange, sampleModulePath, sortHeatmapSamples, specVersion, toolSidecarFilename, trackLengthOf, unregisterPointCloud, useSidecarSource, userToChainPositionMm };
+export { type AreaConfig, type AreaOptions, AssetLoader, type AssetManifest, BUILTIN_MODULE_SIDECARS, BUILTIN_MOVER_SIDECARS, BUILTIN_RAIL_SIDECARS, BUILTIN_TOOL_SIDECARS, type BuiltChain, type BuiltModule, type CameraState, type CheckMoverCollisionsOptions, type ClickModifiers, type CustomAssetBinding, type CustomAssetConfig, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MODULE_MANIFEST, DEFAULT_MOVER_MANIFEST, DEFAULT_ORIGIN_CORRECTION, DEFAULT_RAIL_MANIFEST, DEFAULT_TOOL_MANIFEST, type DimensionOptions, type DisplayOptions, EMPTY_SELECTION, type EndDelta, HEPCO_GFX_PROFILE, type HeatmapSample, type HepcoGfxRailProfileDims, IDENTITY_POSE, type InfoBarConfig, type InfoBarMarkerConfig, type InfoBarOptions, JSDELIVR_ASSETS_BASE_URL, MODULE_CATALOG, MODULE_GUIDING_RAIL_MAP, MOVER_CATALOG, type MarkerOptions, type MarkerShape, type ModuleAssetEntry, type ModuleCatalogEntry, ModuleCornerMarkers, type ModuleEntry, 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 PathSample, type PathType, type PlanarPose, type PointCloud, type PositionFrame, type ProcessingUnitConfig, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, SPEC_VERSION, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionMode, type SelectionState, SidecarLoader, type SidecarOverrides, type SidecarSourceConfig, SidecarSourceContext, type StationConfig, type StationOptions, type StatorHeatmap, type StopPositionMoverOptions, type TextOptions, type TrackTransform, VERSION, type Vec2, type Vec3, XtsArcCurve3, type XtsConfig, XtsConfigNormalizer, type XtsModelDocument, XtsPointCloudCurve3, type XtsRuntimeState, XtsViewer3D, type XtsViewer3DProps, type XtsViewer3DRef, type XtsViewerError, type XtsViewerErrorCode, XtsViewerErrorException, applyEmptyClick, applyModuleClick, applyMoverClick, buildChain, buildPartPath, chainToUserPositionMm, checkSamePathCollisions, composeAssetUrl, createHepcoGfxBaseplateShape, createHepcoGfxRailShape, deselectAll, findModuleAt, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, interpolateHeatmapValue, isKnownModuleType, isKnownMoverType, isModuleSelected, isMoverSelected, moduleEndDelta, moduleSidecarFilename, moverSidecarFilename, moverWorldAt, normaliseToHeatmapRange, normalizeXtsConfig, pickGlbForRail, poseToMatrix4, railSidecarFilename, registerPointCloud, resolveGuidingRailGlbUrl, resolveGuidingRailType, resolveHepcoGfxProfile, resolveModuleGlbUrl, resolveMoverGlbUrl, resolveOriginCorrection, resolveStopPositionMm, resolveToolGlbUrl, sampleChainPoint, sampleChainRange, sampleModulePath, sortHeatmapSamples, specVersion, toolSidecarFilename, trackLengthOf, unregisterPointCloud, useSidecarSource, userToChainPositionMm };