beckhoff-xts-viewer-3d 5.2.3 → 5.3.0

package/dist/index.d.cts

@@ -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: "5.3.0";
 
 /**
  * Default CDN URL for the GLB asset bundle (`beckhoff-xts-viewer-3d-assets`).
@@ -32,7 +32,7 @@ declare const VERSION: "5.2.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@2.1.0/models";
 
 /**
  * Catalogue taxonomy — the string unions naming every module, mover, tool and
@@ -44,7 +44,7 @@ declare const JSDELIVR_ASSETS_BASE_URL: "https://cdn.jsdelivr.net/npm/beckhoff-x
  * public type surface. Nothing here imports anything.
  */
 /** Beckhoff XTS module types supported by the 3D viewer. */
-type ModuleType3D = 'AT2000_0250' | 'AT2001_0250' | 'AT2002_0250' | 'AT2002_0249' | 'AT2002_0249_ZX2002_0001' | 'AT2000_0233' | 'AT2000_0249' | 'AT2100_0250' | 'AT2102_0250' | 'AT2020_0250' | 'AT2021_0250' | 'AT2025_0250' | 'AT2026_0250' | 'AT2040_0250' | 'AT2041_0250' | 'AT2042_0250' | 'AT2140_0250' | 'AT2050_0500' | 'AT2050_0501' | 'AT2050_0500_180' | 'AT2200_0500' | 'AT2202_0500' | 'ATH2000_0250' | 'ATH2001_0250' | 'ATH2002_0250' | 'ATH2020_0250' | 'ATH2040_0250' | 'ATH2041_0250' | 'ATH2042_0250' | 'ATH2050_0500' | 'ATH2050_0501' | 'ATH2050_0500_180';
+type ModuleType3D = 'AT2000_0250' | 'AT2001_0250' | 'AT2002_0250' | 'AT2002_0249' | 'AT2000_0233' | 'AT2000_0249' | 'AT2100_0250' | 'AT2102_0250' | 'AT2020_0250' | 'AT2021_0250' | 'AT2025_0250' | 'AT2026_0250' | 'AT2040_0250' | 'AT2041_0250' | 'AT2050_0500' | 'AT2050_0501' | 'AT2050_0500_180' | 'AT2200_0500' | 'AT2202_0500' | 'ATH2000_0250' | 'ATH2001_0250' | 'ATH2002_0250' | 'ATH2020_0250' | 'ATH2040_0250' | 'ATH2041_0250' | 'ATH2042_0250' | 'ATH2050_0500' | 'ATH2050_0501' | 'ATH2050_0500_180';
 /**
  * Rail system beneath the module. Only affects the visual mesh
  * (Beckhoff aluminium rail vs. Hepco GFX), not the path math.
@@ -65,7 +65,20 @@ type RailSystem = 'Beckhoff' | 'HepcoGfx';
  * The `_S25` carrier ships without a magnet plate; the `_C25/_C34/_M34/_M40`
  * variants include the Beckhoff magnet plate set (`7P`/`10P` = 7/10-pole).
  */
-type MoverType3D = 'AT9011_0050' | 'AT9011_0070' | 'AT9012_0050' | 'AT9014_0055' | 'AT9014_0070' | 'ATH9011_0075' | 'ATH9013_0075' | 'Hepco_GFX2_1TC_S25' | 'Hepco_GFX2_1TC_C25' | 'Hepco_GFX2_1TC_C34' | 'Hepco_GFX2_1TC_M34' | 'Hepco_GFX2_1TC_M34_7P' | 'Hepco_GFX2_FCC_C25' | 'Hepco_GFX2_FCC_M34' | 'Hepco_GFX2_FCC_M34_7P' | 'Hepco_GFX2_FCC_M34_10P' | 'Hepco_GFX2_FCC_M40_10P' | 'Custom';
+type MoverType3D = 'AT9014_0055' | 'AT9014_0070' | 'ATH9011_0075' | 'Hepco_GFX2_1TC_S25' | 'Hepco_GFX2_1TC_C25' | 'Hepco_GFX2_1TC_C34' | 'Hepco_GFX2_1TC_M34' | 'Hepco_GFX2_1TC_M34_7P' | 'Hepco_GFX2_FCC_C25' | 'Hepco_GFX2_FCC_M34' | 'Hepco_GFX2_FCC_M34_7P' | 'Hepco_GFX2_FCC_M34_10P' | 'Hepco_GFX2_FCC_M40_10P' | 'Custom';
+/**
+ * Beckhoff magnet plate sets — the part carrying the mover's magnets and,
+ * on the AT9001 family, the encoder flag ("Geberfahne").
+ *
+ * The digit after the dash is the pole count in base 16 (`0450` → 4,
+ * `0550` → 5, `0775` → 7, `0AA0` → 10), verified by counting magnets in each
+ * converted mesh rather than read off the part number. `ATH9001` is the
+ * hygienic family, whose rows are encapsulated in sealed stainless.
+ *
+ * Every set is symmetric about its own travel axis, so its GLB origin already
+ * sits on the magnet-plate centre that the mover frame is defined around.
+ */
+type MagnetPlateType3D = 'AT9001_0450' | 'AT9001_0550' | 'AT9001_0775' | 'AT9001_0AA0' | 'ATH9001_0550' | 'ATH9001_0550_0001' | 'ATH9001_0AA0';
 /** Predefined mover-tool / carrier-plate types. */
 type MoverToolType3D = 'AT8200_1000_0100' | 'AT8200_2000_0100' | 'Custom';
 /**
@@ -73,17 +86,23 @@ type MoverToolType3D = 'AT8200_1000_0100' | 'AT8200_2000_0100' | 'Custom';
  * when `RailSystem === 'Beckhoff'` to visualise the outer guide
  * profile that the mover wheels engage.
  *
- * Curve sign drives the selection (see `MODULE_GUIDING_RAIL_MAP`):
+ * Curve sign drives the selection, and on curves so does the mover — see
+ * `resolveGuidingRailType`:
  *   - Straights: AT9000_0249 / AT9000_0250 / AT9000_0500
  *   - +22.5° curve: AT9020_1250
  *   - −22.5° curve: AT9025_1466
  *   - 45° curve:    AT9040_0750
  *   - 180° clothoid (entire AT2050 500 mm path): AT9050_0500
  *
+ * Beckhoff builds the curve rails per mover: the unsuffixed types above are
+ * the `-0055` order variants, made for the AT9014-0055, and the `_0170` ones
+ * are the `-0170` variants for the wider AT9014-0070. The straights carry no
+ * such variant — one AT9000 profile serves every mover.
+ *
  * Hygienic ATH modules ship with their guide profile baked into the module
  * GLB and therefore do NOT receive a separate guiding-rail mesh.
  */
-type RailType3D = 'AT9000_0249' | 'AT9000_0250' | 'AT9000_0500' | 'AT9020_1250' | 'AT9025_1466' | 'AT9040_0750' | 'AT9050_0500';
+type RailType3D = 'AT9000_0249' | 'AT9000_0250' | 'AT9000_0500' | 'AT9020_1250' | 'AT9020_1250_0170' | 'AT9025_1466' | 'AT9025_1466_0170' | 'AT9040_0750' | 'AT9050_0500' | 'AT9050_0500_0170';
 
 /**
  * Scalar tuples shared by every other type module.
@@ -330,8 +349,13 @@ interface MoverIdLabelOptions {
      */
     offsetMm?: Vec3;
     /**
-     * URL of a TTF / OTF / WOFF font, passed straight to troika-three-text.
-     * Default: `DEFAULT_LABEL_FONT_URL` (Roboto Condensed via jsDelivr).
+     * URL of a TTF / OTF / WOFF font for the label.
+     *
+     * Default: the viewer's built-in Roboto Condensed, compiled into the
+     * bundle and served from a blob URL — no request, and nothing that can
+     * fail. A custom URL is fetched once and shared by every label; until
+     * it answers, and permanently if it never does, labels render in the
+     * built-in font and the failure is reported once via `console.warn`.
      */
     fontUrl?: string;
     /** Outline thickness in mm. 0 disables the outline. Default: 0. */
@@ -675,6 +699,20 @@ interface ProcessingUnitConfig {
      */
     objectId: number;
     moverType: MoverType3D;
+    /**
+     * Magnet plate set attached to the carriage.
+     *
+     * Only meaningful for a mover whose GLB ships bare — today just
+     * `Hepco_GFX2_1TC_S25`. Every other mover models its plate already
+     * (see `MOVER_INTEGRATED_PLATE`) and ignores this, so setting it there
+     * cannot double-plate the mover. Defaults to `AT9001_0550`, the 5-pole set
+     * the equivalent `_C25` carriage ships with.
+     *
+     * Deliberately per processing unit rather than per mover: `moverType` is
+     * too, and a plate that varied between movers would force every one of them
+     * to claim its own scene node, disabling the instanced render path.
+     */
+    magnetPlateType?: MagnetPlateType3D;
     customMoverLayout?: CustomMoverLayout;
     /** Default: 'Beckhoff'. */
     railSystem?: RailSystem;
@@ -1090,6 +1128,7 @@ interface AssetManifest {
     modules?: Partial<Record<ModuleType3D, ModuleAssetEntry>>;
     movers?: Partial<Record<MoverType3D, MoverAssetEntry>>;
     tools?: Partial<Record<MoverToolType3D, MoverToolAssetEntry>>;
+    magnetPlates?: Partial<Record<MagnetPlateType3D, MagnetPlateAssetEntry>>;
     guidingRails?: Partial<Record<RailType3D, RailAssetEntry>>;
 }
 interface RailAssetEntry {
@@ -1112,6 +1151,10 @@ interface MoverToolAssetEntry {
     glbUrl: string;
     sidecarUrl?: string;
 }
+interface MagnetPlateAssetEntry {
+    glbUrl: string;
+    sidecarUrl?: string;
+}
 
 /**
  * Public types for the measurement + annotation feature.
@@ -1459,6 +1502,18 @@ interface MoverSidecar {
     magnetPlateCenterMm: Vec3;
     pathLengthMm: number;
 }
+/**
+ * Calibration sidecar for a standalone magnet plate set. The plate is drawn
+ * in the mover-local frame (+X travel, +Z up) with this correction applied,
+ * so `originCorrection` is what seats it on the carriage.
+ */
+interface MagnetPlateSidecar {
+    plateType: MagnetPlateType3D;
+    glb: string;
+    originCorrection: OriginCorrection;
+    poleCount: number;
+    lengthMm: number;
+}
 interface MoverToolSidecar {
     toolType: MoverToolType3D;
     glbUrl: string;
@@ -1542,8 +1597,15 @@ declare function pickGlbForRail(entry: GlbByRailSystem | undefined, rail: RailSy
  * here and imported by both.
  */
 
-/** Where the view cube sits in the canvas. */
+/** Where the orientation gizmo sits in the canvas. */
 type ViewCubeAlignment = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center' | 'center-left' | 'center-right' | 'center-center';
+/**
+ * The corner navigation gizmo: three labelled X / Y / Z axis handles that
+ * track the camera and snap it onto an axis when clicked.
+ *
+ * Named `ViewCube*` for backwards compatibility — earlier versions drew a
+ * navigation cube in the same spot.
+ */
 interface ViewCubeOptions {
     enabled?: boolean;
     /** Default `'bottom-right'`. */
@@ -1551,6 +1613,28 @@ interface ViewCubeOptions {
     /** Distance from the aligned corner, in CSS px. Default `[80, 80]`. */
     marginPx?: [number, number];
 }
+/**
+ * Keyboard navigation — moving the camera *through* the scene rather than
+ * orbiting it around a fixed point.
+ *
+ * The arrow keys (and the WASD block) walk the camera and the orbit pivot
+ * together along the ground plane, PageUp / PageDown climb, Shift goes
+ * faster and Alt finer. Keys are read from the canvas once it has focus,
+ * which it takes on pointer-down, so an embedded viewer never swallows the
+ * host page's arrow keys.
+ *
+ * Off automatically while `lock.pan` is set — moving through the scene is
+ * panning by another input device.
+ */
+interface KeyboardNavigationOptions {
+    /** Default `true`. */
+    enabled?: boolean;
+    /**
+     * Multiplier on the default travel rate, which is ~0.6 × the current
+     * orbit distance per second. Default `1`.
+     */
+    speed?: number;
+}
 /** Interaction locks. Each `true` disables that interaction. */
 interface InteractionLocks {
     rotate?: boolean;
@@ -1612,6 +1696,7 @@ 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>>;
 }
 
@@ -1970,12 +2055,17 @@ declare function checkAllMoverCollisions(config: NormalizedXtsConfig, livePositi
  * are excluded; everything else (cross-part, cross-XPU, same-part
  * non-adjacent) is tested.
  *
- * The box cross-section (`halfWidthMm` 50, `heightMm` 100) is a coarse but
- * deterministic, asset-independent envelope. Real per-module CAD bounds live
- * in the GLB sidecars (`approximateBoundsMm`) and could refine it later.
- * Likewise the `warningGapMm` near-miss is an axis-projected SAT separation,
- * not a true Euclidean (GJK) distance — slightly conservative for
- * corner-to-corner cases.
+ * The box height comes from the module's own GLB sidecar
+ * (`moduleHeightSpan`, moduleCrossSection.ts): a motor module measures about
+ * 40 mm and straddles the path plane. It used to be one coarse box per type,
+ * `0 … 100` mm and entirely above the plane, which reported an overlap between
+ * any two tracks stacked closer than 100 mm — the arrangement a doublesided
+ * guide rail is built as. The half-width stays the coarse `halfWidthMm` 50,
+ * because a curved module's sidecar box spans its whole arc in X and Y and is
+ * a cross-section only in Z; moduleCrossSection.ts sets that out.
+ *
+ * The `warningGapMm` near-miss is an axis-projected SAT separation, not a true
+ * Euclidean (GJK) distance — slightly conservative for corner-to-corner cases.
  */
 
 /** Default box half-width (Y) — matches `approximateModuleBounds`. */
@@ -2022,7 +2112,16 @@ interface CheckModuleCollisionsOptions {
     includeSamePart?: boolean;
     /** Box half-width in Y (mm). Default 50. */
     halfWidthMm?: number;
-    /** Box height in Z (mm). Default 100. */
+    /**
+     * Force one box height in Z (mm), spanning `0 … heightMm` above the path
+     * plane for every module type.
+     *
+     * Left unset — the default — each module is given the vertical extent its
+     * GLB sidecar reports (`moduleHeightSpan`), which both is the real height
+     * and sits on the real side of the path plane. Setting this restores the one
+     * coarse box the check used before that, for a caller who wants a
+     * deliberately conservative envelope.
+     */
     heightMm?: number;
 }
 /** Oriented bounding box in world space (unit axes + scaled half-extents). */
@@ -2928,6 +3027,14 @@ interface XtsViewer3DProps {
     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;
     /** Controlled selection. */
@@ -3111,9 +3218,61 @@ interface MoverCatalogEntry {
     magnetPlateCenterMm: Vec3;
 }
 declare const MOVER_CATALOG: Readonly<Record<MoverType3D, MoverCatalogEntry>>;
+/**
+ * The magnet plate set already modelled into each mover's own GLB, or `null`
+ * for a carriage that ships bare and needs one attached.
+ *
+ * Nearly every mover asset is a combined carriage+plate assembly: the Beckhoff
+ * movers say so in the filename (`AT9014-0055-0550` carries an AT9001-0550),
+ * and each Hepco carriage records the plate it was ordered with in its
+ * sidecar's `_calibration.hepcoPartNumber` (`…_AT9001-0775` and friends).
+ * Attaching a second plate to one of those would draw a plate through a plate,
+ * so `<XtsMoverPlate>` renders only where this table says `null`.
+ *
+ * `Custom` is `null` because its geometry comes from `customMoverLayout`,
+ * which may or may not include a plate — the host decides.
+ *
+ * Exhaustive over `MoverType3D` on purpose (`Record`, not `Partial<Record>`):
+ * a new mover type has to state which it is, so it cannot silently end up
+ * double-plated or plate-less.
+ */
+declare const MOVER_INTEGRATED_PLATE: Readonly<Record<MoverType3D, MagnetPlateType3D | null>>;
 declare function getMoverEntry(moverType: MoverType3D): MoverCatalogEntry | undefined;
 declare function isKnownMoverType(value: string): value is MoverType3D;
 
+/**
+ * Magnet plate set catalog (3D-canonical).
+ *
+ * A plate set is the part that carries the mover's magnets. Most mover GLBs
+ * ship with one already modelled in (see `MOVER_INTEGRATED_PLATE`); these
+ * entries describe the sets that exist as assets of their own, so a bare
+ * carriage can be given any pole count without a new combined CAD assembly.
+ *
+ * `lengthMm` is the plate's extent along the travel axis, measured from the
+ * converted GLB rather than inferred from the part number. Pole count was
+ * likewise counted in the mesh: each magnet is 7.7 mm wide and sits in a row
+ * just proud of its backing plate, so the magnets separate cleanly along the
+ * travel axis. That count is what establishes the part-number rule (the digit
+ * after the dash is the pole count in base 16) — it is not assumed from it.
+ */
+
+interface MagnetPlateCatalogEntry {
+    plateType: MagnetPlateType3D;
+    /** Magnets in one row, i.e. the pole count the part number encodes. */
+    poleCount: number;
+    /** Plate extent along the travel axis, mm (GLB-measured). */
+    lengthMm: number;
+    /**
+     * Whether the set models the encoder flag ("Geberfahne"). The AT9001 sets
+     * all carry it as a thin sheet reaching back along −Z; the hygienic ATH9001
+     * sets encapsulate their rows in sealed stainless and model none.
+     */
+    hasEncoderFlag: boolean;
+}
+declare const MAGNET_PLATE_CATALOG: Readonly<Record<MagnetPlateType3D, MagnetPlateCatalogEntry>>;
+declare function getMagnetPlateEntry(plateType: MagnetPlateType3D): MagnetPlateCatalogEntry | undefined;
+declare function isKnownMagnetPlateType(value: unknown): value is MagnetPlateType3D;
+
 /**
  * Module-local path math.
  *
@@ -3224,6 +3383,29 @@ declare function buildPartPath(modules: ReadonlyArray<ModuleEntry>): PartPath;
  */
 declare function poseToMatrix4(pose: PlanarPose, out?: Matrix4): Matrix4;
 
+/**
+ * Pure helpers for composing per-XPU `trackTransform` and root
+ * `XtsConfig.orientation` into Three.js Matrix4 instances. Lives in geometry/
+ * so the component layer (XtsViewer3D, XtsScene) and the test suite share a
+ * single source of truth — no duplicated math.
+ *
+ * Composition order:
+ *
+ *     world = orientation ⊗ trackTransform ⊗ partTransformation ⊗ chain
+ *
+ * `partTransformation` is applied inside the per-XPU group by XtsScene, so
+ * the helpers here only cover the outermost two layers.
+ */
+
+/**
+ * Default Z lift for a track that does not specify `positionMm`. The XTS
+ * track sits on a base plate / table top in real installations, so 0 mm
+ * (= floor) is rarely what the user wants. 200 mm matches the standard
+ * Beckhoff table height used throughout the demo configs and renders
+ * correctly under the default shadow-casting ground plane.
+ */
+declare const DEFAULT_TRACK_Z_MM = 200;
+
 /**
  * Point-cloud registry for Free-path modules.
  *
@@ -3328,6 +3510,67 @@ declare function interpolateHeatmapValue(samples: ReadonlyArray<HeatmapSample>,
  */
 declare function normaliseToHeatmapRange(value: number, min: number, max: number): number;
 
+/**
+ * The vertical extent of a track module, in the path frame.
+ *
+ * `moduleCollision.ts` needs to know how tall a module is and where it sits
+ * relative to the mover path. It used to assume one coarse box for every type —
+ * `0 … DEFAULT_MODULE_HEIGHT_MM`, entirely *above* the path plane — which is
+ * neither the right height nor the right side: a motor module measures about
+ * 40 mm and straddles the plane, roughly half above and half below. Two tracks
+ * stacked closer than 100 mm therefore reported an overlap that does not exist,
+ * and the deepest ones reported it on every module pair.
+ *
+ * ## Why only Z, and not the width too
+ *
+ * The GLB sidecar carries `approximateBoundsMm`, the axis-aligned box of the
+ * CAD body *before* `originCorrection` is applied. Composing the two gives the
+ * body in the path frame — but only its **Z** range is a cross-section.
+ *
+ * Module paths are planar in XY and curves bend about Z, so a curved module's
+ * GLB spans its whole arc in X and Y: the 180° AT2050_0500 measures 307 mm
+ * across in Y, which is the sweep of the U-turn and not how wide the beam is.
+ * Its Z range, on the other hand, is the same 40.1 mm as the straight it is
+ * built from, because the sweep never leaves the plane.
+ *
+ * So the height is read from the asset and the half-width stays the coarse
+ * constant. Taking the width from the same box would inflate every curve
+ * segment to the size of its arc and report a collision for every oval.
+ *
+ * Overrides are not consulted: `SidecarOverrides` can replace a module's
+ * `originCorrection` but carries no bounds, so there is nothing to override.
+ */
+
+/** Where a module's body sits along Z, relative to the mover path plane. */
+interface ModuleHeightSpan {
+    /** Lowest point of the body [mm]; negative means below the path plane. */
+    minZMm: number;
+    /** Highest point of the body [mm]. */
+    maxZMm: number;
+}
+/**
+ * The span a module without usable bounds falls back to: the historic coarse
+ * box, so a type the asset package does not describe behaves as it always did.
+ */
+declare function coarseHeightSpan(heightMm: number): ModuleHeightSpan;
+/**
+ * Compose `approximateBoundsMm` through `originCorrection` and keep the Z range.
+ *
+ * All eight corners are transformed rather than only the two extremes: every
+ * shipped correction happens to be a multiple of 90°, which would keep the box
+ * axis-aligned, but nothing in the sidecar format promises that, and under a
+ * 45° correction two corners would describe a box far too small.
+ */
+declare function heightSpanOf(sidecar: ModuleSidecar): ModuleHeightSpan | null;
+/**
+ * How tall `moduleType` is and where it sits, or the coarse fallback.
+ *
+ * Resolved per module type rather than once per run: an Eco straight, a
+ * hygienic module with its tower and an AT2002 with its infeed box are three
+ * different heights, and a stack has to be judged against the one it holds.
+ */
+declare function moduleHeightSpan(moduleType: ModuleType3D, fallbackHeightMm: number): ModuleHeightSpan;
+
 /**
  * Shared closed-loop detection for built chains.
  *
@@ -3530,24 +3773,61 @@ interface Props {
 declare const ModuleCornerMarkers: React__default.FC<Props>;
 
 /**
- * <DimensionLabel> — camera-facing text used by the Dimensions overlay
- * (and re-usable elsewhere). Wraps drei's `<Billboard>` + `<Text>` so the
- * label always reads horizontally regardless of camera orbit, and is
- * placed at a small +Z offset above the dimension tick so the text and
- * the marker don't z-fight.
+ * labelFont — resolution of the font URL every 3D text label is drawn
+ * with, and the reason none of them can stall the scene any more.
+ *
+ * troika-three-text loads its font over XHR and, when that request
+ * fails, only logs `Failure loading font <url>`: the internal callback
+ * queue for that URL is never drained. drei's `<Text>` wraps exactly
+ * that callback in `suspend(...)`, so a dangling load becomes a promise
+ * that never settles. With one `<Suspense fallback={null}>` around the
+ * scene, a single unreachable font blanked the whole viewer — geometry,
+ * grid, ViewCube and all — with nothing in the console beyond troika's
+ * own line. Every sample that carried a station or an area label went
+ * dark that way.
+ *
+ * Two things prevent that here:
+ *
+ *  1. The default font is compiled in (`labelFontData.ts`) and handed to
+ *     troika as a `blob:` URL, so the common path never touches the
+ *     network and cannot fail.
+ *  2. A caller-supplied font URL is HEAD/GET-probed before it is handed
+ *     over. Until it answers, labels render in the built-in font; if it
+ *     never answers, they keep rendering in the built-in font and the
+ *     failure is reported once, loudly. troika is never given a URL that
+ *     has not already been fetched successfully.
+ *
+ * `<DimensionLabel>` / `<MoverIdLabel>` additionally wrap their `<Text>`
+ * in a local Suspense boundary, so even a font that parses badly costs
+ * one label rather than the scene.
  */
-
 /**
- * Default 3D-text font: Roboto Condensed (Latin, regular weight) served
- * from jsDelivr's @fontsource mirror. Pinned to a fixed major version so
- * the stack stays reproducible; the URL responds with a long
- * Cache-Control TTL so repeated reads come from the browser cache.
+ * Default 3D-text font: Roboto Condensed (Latin, regular weight).
+ *
+ * The value is the jsDelivr `@fontsource` mirror it was originally
+ * fetched from, kept stable because it is part of the public API. It is
+ * no longer fetched: the viewer ships the same WOFF compiled in, and
+ * treats this URL as "use the built-in copy", so passing it explicitly
+ * is equivalent to passing nothing and costs no request.
  *
- * `font` on troika-three-text expects an OTF / TTF / WOFF URL — NOT a CSS
- * font-family name. Consumers can override via `<DimensionLabel
- * fontFamily="https://…/whatever.woff" />` to swap in a brand font.
+ * `font` on troika-three-text expects an OTF / TTF / WOFF URL — NOT a
+ * CSS font-family name. Any other URL is used as given, once a probe
+ * has confirmed it actually loads.
  */
 declare const DEFAULT_LABEL_FONT_URL: "https://cdn.jsdelivr.net/npm/@fontsource/roboto-condensed@5.2.7/files/roboto-condensed-latin-400-normal.woff";
+/**
+ * URL of the compiled-in Roboto Condensed WOFF, as a `blob:` object URL
+ * created on first use and cached for the lifetime of the document.
+ *
+ * A blob URL rather than a `data:` URL on purpose: troika loads fonts
+ * through `XMLHttpRequest` and discards any response whose `status` is
+ * 0, which is what several engines report for non-HTTP schemes. Blob
+ * URLs answer with a regular 200.
+ *
+ * Falls back to a `data:` URL where `URL.createObjectURL` is missing
+ * (jsdom, some SSR shims) so the value is always a usable string.
+ */
+declare function bundledLabelFontUrl(): string;
 
 /**
  * <MoverIdLabel> — Camera-facing 3D text label that shows a mover's
@@ -3558,7 +3838,7 @@ declare const DEFAULT_LABEL_FONT_URL: "https://cdn.jsdelivr.net/npm/@fontsource/
  * the hood) so the label stays readable as the camera orbits. All
  * styling is driven by `MoverIdLabelOptions`; the component supplies
  * the documented defaults (15 mm black text, 55 mm above the mover's
- * magnet-plate origin, Roboto Condensed via jsDelivr).
+ * magnet-plate origin, the viewer's built-in Roboto Condensed).
  */
 
 interface MoverIdLabelProps {
@@ -3581,7 +3861,8 @@ declare const MoverIdLabel: React__default.FC<MoverIdLabelProps>;
  * Module count: 27
  * Mover count:  13
  * Tool count:   2
- * Rail count:   8
+ * Plate count:  7
+ * Rail count:   11
  */
 
 /**
@@ -3635,8 +3916,8 @@ declare function useSidecarSource(): SidecarSourceConfig;
  * only set `Beckhoff`; the loader silently falls back to that variant when
  * `HepcoGfx` is requested but unavailable.
  *
- * `null` for `Beckhoff` marks "prepared but not delivered"
- * (AT2042 / AT2140) — the loader renders a placeholder AABB mesh.
+ * A `null` `Beckhoff` entry marks a module type that is catalogued but has
+ * no GLB — the loader renders a placeholder AABB mesh instead.
  */
 
 /** Filename mapping per ModuleType3D (relative to assetsBaseUrl). */
@@ -3662,7 +3943,7 @@ declare const DEFAULT_RAIL_MANIFEST: Readonly<Record<RailType3D, {
  *   - Straights pick the matching-length AT9000 rail (0249 / 0250 / 0500).
  *   - +22.5° curves (AT2020 / AT2021) use AT9020.
  *   - −22.5° curves (AT2025 / AT2026) use AT9025.
- *   - 45° curves  (AT2040 / AT2041 / AT2042 / AT2140) use AT9040.
+ *   - 45° curves  (AT2040 / AT2041) use AT9040.
  *   - The 180° clothoid pair (AT2050 0500/0501 + merged 0500_180) uses
  *     AT9050, whose GLB already covers the full 500 mm path.
  *   - Hygienic ATH modules already include the rail in their module GLB
@@ -3674,10 +3955,12 @@ declare function resolveModuleGlbUrl(moduleType: ModuleType3D, rail: RailSystem,
 declare function resolveMoverGlbUrl(moverType: MoverType3D, override?: AssetManifest['movers']): string;
 declare function resolveToolGlbUrl(toolType: MoverToolType3D, override?: AssetManifest['tools']): string;
 /**
- * Pick the guiding-rail RailType for a module, or `null` if no separate
- * rail mesh should render (ATH variants, undeclared module types).
+ * Which guiding rail a module gets, given the mover running on it.
+ *
+ * `moverType` is optional so existing callers keep the -0055 default; pass it
+ * to get the variant Beckhoff actually pairs with that mover.
  */
-declare function resolveGuidingRailType(moduleType: ModuleType3D): RailType3D | null;
+declare function resolveGuidingRailType(moduleType: ModuleType3D, moverType?: MoverType3D): RailType3D | null;
 /**
  * Resolve the GLB filename for a guiding-rail type, honoring user-supplied
  * manifest overrides. Returns empty string when the rail is unknown.
@@ -3774,9 +4057,9 @@ declare function getSharedAssetLoader(): AssetLoader;
 declare function composeAssetUrl(baseUrl: string, filename: string): string;
 
 /**
- * The four sidecar kinds as data.
+ * The five sidecar kinds as data.
  *
- * Modules, movers, tools and rails all resolve their calibration the same
+ * Modules, movers, tools, magnet plates and rails all resolve the same
  * way — compiled-in table, else `<assetsBaseUrl>/<filename>`, else identity.
  * Only two things differ per kind: which built-in table to read and how the
  * filename is spelled. Keeping those two as a table (rather than four copies
@@ -3803,6 +4086,10 @@ interface SidecarKinds {
         id: MoverToolType3D;
         sidecar: MoverToolSidecar;
     };
+    plate: {
+        id: MagnetPlateType3D;
+        sidecar: MagnetPlateSidecar;
+    };
     rail: {
         id: RailType3D;
         sidecar: RailSidecar;
@@ -3922,4 +4209,4 @@ declare function snapToGrid(positionMm: Vec3, gridMm: number): Vec3;
 /** Convenience: `resolveSceneContext` + `toEntityRef`. */
 declare function resolveEntityFromObject(object: Object3D | null, instanceId?: number): MeasuredEntityRef | null;
 
-export { type AngleMeasurement, type Annotation, type AnnotationAnchor, type AnnotationInput, type AreaConfig, type AreaOptions, AssetLoader, type AssetManifest, BUILTIN_MODULE_SIDECARS, BUILTIN_MOVER_SIDECARS, BUILTIN_RAIL_SIDECARS, BUILTIN_TOOL_SIDECARS, type BuiltChain, type BuiltModule, type CameraProjection, type CameraState, type 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 BuiltChain, type BuiltModule, type CameraProjection, type CameraState, type CaptureDimensions, type CaptureMode, type CaptureRequest, type CheckModuleCollisionsOptions, type CheckMoverCollisionsOptions, type ClickModifiers, type CoordinateSystem, type CustomAssetBinding, type CustomAssetConfig, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MEASUREMENT_STYLE, DEFAULT_MODULE_HALF_WIDTH_MM, DEFAULT_MODULE_HEIGHT_MM, DEFAULT_MODULE_MANIFEST, DEFAULT_MOVER_MANIFEST, DEFAULT_ORIGIN_CORRECTION, DEFAULT_RAIL_MANIFEST, DEFAULT_SNAP_KINDS, DEFAULT_SNAP_RADIUS_PX, DEFAULT_TOOL_MANIFEST, DEFAULT_TRACK_Z_MM, type DimensionOptions, type DisplayOptions, type DistanceMeasurement, EMPTY_SELECTION, type EndDelta, type FeedSegment, type FeedSegmentHighlight, type FeedSegmentSelector, type FeedSegmentSpan, type FocusOptions, type FocusTarget, type FrameCaptureOptions, type FrameCaptureSession, HEPCO_GFX_PROFILE, type HeatmapSample, type HepcoGfxRailProfileDims, IDENTITY_POSE, INFEED_MODULE_TYPES, type InfoBarConfig, type InfoBarMarkerConfig, type InfoBarOptions, type InteractionLocks, JSDELIVR_ASSETS_BASE_URL, type KeyboardNavigationOptions, MAGNET_PLATE_CATALOG, MODULE_CATALOG, MODULE_GUIDING_RAIL_MAP, MOVER_CATALOG, MOVER_INTEGRATED_PLATE, type MagnetPlateAssetEntry, type MagnetPlateCatalogEntry, type MagnetPlateType3D, type MarkerOptions, type MarkerShape, type MeasuredEntityRef, type Measurement, type MeasurementApi, type MeasurementAxis, type MeasurementDocument, type MeasurementDraft, type MeasurementFormatOptions, type MeasurementId, type MeasurementInput, type MeasurementKind, type MeasurementOptions, type MeasurementPoint, type MeasurementResult, type MeasurementSnapshot, type MeasurementStyle, type MeasurementTool, type ModuleAssetEntry, type ModuleCatalogEntry, type ModuleCollision, type ModuleCollisionPartInput, type ModuleCollisionXpuInput, ModuleCornerMarkers, type ModuleEntry, type ModuleHeightSpan, type ModuleHighlight, type ModuleProbe, type ModuleRef, type ModuleSidecar, type ModuleStatusEntry, type ModuleType3D, type MoverAssetEntry, type MoverCatalogEntry, type MoverCollision, type MoverConfig, MoverIdLabel, type MoverIdLabelOptions, type MoverPositionEntry, type MoverProbe, type MoverRef, type MoverSidecar, type MoverToolAssetEntry, type MoverToolConfig, type MoverToolSidecar, type MoverToolType3D, type MoverType3D, type NormalizationWarning, type NormalizedXtsConfig, type Orientation, type OriginCorrection, type PartConfig, type PartPath, type PartTransformation, type PathMeasurement, type PathSample, type PathType, type PerformanceOptions, type PlanarPose, type PointCloud, type PointProjector, type PositionFrame, type ProcessingUnitConfig, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, type ResolvedMeasurementStyle, SIDECAR_KINDS, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionMode, type SelectionState, type SidecarIdOf, type SidecarKind, type SidecarKindSpec, type SidecarKinds, SidecarLoader, type SidecarOf, type SidecarOverrides, type SidecarSourceConfig, SidecarSourceContext, type SnapCandidate, type SnapKind, type SnapOptions, type SplitFeedSegmentsOptions, type StationConfig, type StationOptions, type StatorHeatmap, type StopPositionMoverOptions, type TextOptions, type TrackAnchor, type TrackDistanceMeasurement, type TrackIndex, type TrackIndexEntry, type TrackMetrics, type TrackMetricsResolver, type TrackProjection, type TrackTransform, VERSION, type Vec2, type Vec3, type ViewCubeAlignment, type ViewCubeOptions, XtsArcCurve3, type XtsConfig, XtsConfigNormalizer, type XtsModelDocument, XtsPointCloudCurve3, type XtsRuntimeState, XtsViewer3D, type XtsViewer3DProps, type XtsViewer3DRef, type XtsViewerError, type XtsViewerErrorCode, XtsViewerErrorException, angleDeg, applyBeckhoffXtsConvention, applyEmptyClick, applyModuleClick, applyMoverClick, arcPoints, axisDistanceMm, buildChain, buildModuleProbes, buildPartPath, buildTrackIndex, bundledLabelFontUrl, chainToUserPositionMm, checkAllModuleCollisions, checkAllMoverCollisions, checkModuleCollisions, checkSamePathCollisions, chooseSnapCandidate, coarseHeightSpan, collectFeedSegments, collectFeedSegmentsForXpu, collectTriangleSnapCandidates, composeAssetUrl, computeMeasurementResult, createHepcoGfxBaseplateShape, createHepcoGfxRailShape, deselectAll, distanceMm, findModuleAt, formatAngleDeg, formatLengthMm, getMagnetPlateEntry, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, heightSpanOf, interpolateHeatmapValue, isChainClosed, isKnownMagnetPlateType, isKnownModuleType, isKnownMoverType, isModuleSelected, isMoverSelected, labelAnchorFor, moduleAnchorWorld, moduleEndDelta, moduleHeightSpan, moduleSidecarFilename, moverAnchorWorld, moverSidecarFilename, moverWorldAt, nearestTrackPoint, normaliseToHeatmapRange, normalizeXtsConfig, pathLengthsMm, pickGlbForRail, poseToMatrix4, railSidecarFilename, registerPointCloud, resolveEntityFromObject, resolveGuidingRailGlbUrl, resolveGuidingRailType, resolveHepcoGfxProfile, resolveMeasurementStyle, resolveModuleGlbUrl, resolveMoverGlbUrl, resolveOriginCorrection, resolveStopPositionMm, resolveToolGlbUrl, sampleChainPoint, sampleChainRange, sampleModulePath, snapToGrid, sortHeatmapSamples, splitIntoFeedSegments, toModuleCollisionInputs, toolSidecarFilename, trackAnchorWorld, trackDistanceMm, trackLengthOf, trackPolylineWorld, unregisterPointCloud, useSidecarSource, userToChainPositionMm, worldPointOnPart };