beckhoff-xts-viewer-3d 5.0.0 → 5.2.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default from 'react';
-import { Vector3, ColorRepresentation, Shape, Curve, CurvePath, Matrix4, WebGLRenderer } from 'three';
+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.0.0";
+declare const VERSION: "5.2.0";
 
 /**
  * Default CDN URL for the GLB asset bundle (`beckhoff-xts-viewer-3d-assets`).
@@ -32,14 +32,276 @@ declare const VERSION: "5.0.0";
  * 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@1.0.0/models";
+declare const JSDELIVR_ASSETS_BASE_URL: "https://cdn.jsdelivr.net/npm/beckhoff-xts-viewer-3d-assets@2.0.1/models";
+
+/**
+ * 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[];
+}
+/**
+ * `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.
+ */
+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;
+}
 
 /**
  * Public type surface for beckhoff-xts-viewer-3d.
  *
  * Anything that crosses the Component boundary — props, refs, callbacks —
  * is declared here.
+ *
+ * The measurement feature keeps its own public types next to its
+ * implementation (`measurement/types.ts`); only the serialized document shows
+ * up here, as part of `XtsModelDocument`.
  */
+
 /** 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';
 /**
@@ -482,6 +744,18 @@ interface DisplayOptions {
     moverAnchorMarkerSizeMm?: number;
     /** Color of the anchor marker. Default: '#FF2030' (red). */
     moverAnchorMarkerColor?: string;
+    /**
+     * Print each module's type designation onto its type-plate panel.
+     *
+     * The hygienic ATH modules and the AT2100 / AT2102 variants carry their
+     * labelling as modelled geometry and are unaffected. The remaining AT2
+     * modules only have a blank plate panel in their CAD data, so the
+     * designation is drawn onto it at render time. No logo is reproduced —
+     * only the type designation.
+     *
+     * Default: `true`.
+     */
+    moduleTypePlates?: boolean;
     /**
      * Render shadows: enables the WebGL shadow map, makes one directional
      * light cast shadows, and renders a transparent shadow-catcher plane
@@ -1041,6 +1315,12 @@ interface XtsModelDocument {
     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<{
@@ -1808,6 +2088,221 @@ interface FrameCaptureSession {
     dispose(): void;
 }
 
+/**
+ * Pure measurement math — no three.js scene, no React.
+ *
+ * Everything the measurement feature reports goes through here, so the values
+ * a host reads back from `XtsViewer3DRef.measurements.results()` are produced
+ * by the same code the scene labels are drawn from.
+ *
+ * Vectors are plain `[x, y, z]` tuples in the viewer's world frame (mm).
+ */
+
+interface MeasurementFormatOptions {
+    decimals?: number;
+    unitSuffix?: string;
+}
+/** Track metrics of the part an endpoint sits on. */
+interface TrackMetrics {
+    trackLengthMm: number;
+    /** Closed chains measure the shorter way around. */
+    closed: boolean;
+}
+/** Resolves the metrics of the part a `TrackAnchor` addresses. */
+type TrackMetricsResolver = (anchor: TrackAnchor) => TrackMetrics | null;
+/** Straight-line distance (mm). */
+declare function distanceMm(a: Vec3, b: Vec3): number;
+/**
+ * Distance under an axis constraint: `'free'` is the 3D distance, `'x' | 'y' |
+ * 'z'` the absolute delta along that world axis.
+ */
+declare function axisDistanceMm(a: Vec3, b: Vec3, axis: MeasurementAxis): number;
+/**
+ * Angle at `vertex` between the legs to `a` and `b`, in degrees `[0, 180]`.
+ * Returns `0` when a leg is degenerate (both picks landed on the vertex).
+ */
+declare function angleDeg(a: Vec3, vertex: Vec3, b: Vec3): number;
+/** Per-segment and total length of a polyline. */
+declare function pathLengthsMm(points: readonly Vec3[], closed?: boolean): {
+    segments: number[];
+    total: number;
+};
+/**
+ * Distance along a part's path between two positions on it. On a closed chain
+ * the shorter of the two directions wins — that is the distance a mover
+ * actually travels.
+ */
+declare function trackDistanceMm(aMm: number, bMm: number, metrics: TrackMetrics): number;
+/**
+ * Polyline approximating the angle arc at `vertex`, from the `a` leg to the
+ * `b` leg at `radiusMm`. Returns `[]` for a degenerate angle.
+ */
+declare function arcPoints(a: Vec3, vertex: Vec3, b: Vec3, radiusMm: number, segments?: number): Vec3[];
+/** Where the value label of a measurement belongs (world mm). */
+declare function labelAnchorFor(measurement: Measurement): Vec3;
+/**
+ * Format a length. Plain-space thousands grouping keeps four-digit millimetre
+ * values readable in the 3D label without dragging in a locale dependency —
+ * and without relying on a glyph (thin space) the label font may not ship.
+ */
+declare function formatLengthMm(valueMm: number, options?: MeasurementFormatOptions): string;
+/** Format an angle in degrees. */
+declare function formatAngleDeg(valueDeg: number, options?: MeasurementFormatOptions): string;
+interface ComputeResultOptions {
+    format?: MeasurementFormatOptions;
+    /** Required for `'trackDistance'`; without it the result falls back to 3D. */
+    resolveTrack?: TrackMetricsResolver;
+}
+/** Evaluate a measurement into the value + label the scene renders. */
+declare function computeMeasurementResult(measurement: Measurement, options?: ComputeResultOptions): MeasurementResult;
+
+/**
+ * Track-aware snap candidates — the "XTS semantics" half of the picker.
+ *
+ * Geometry snaps (vertex / edge / face, see `snapping.ts`) know nothing about
+ * what they hit. These helpers add the points an XTS layout is actually
+ * measured against: positions on a part's path, module boundaries, station
+ * stop positions and mover centres — all resolved through the same
+ * `orientation ⊗ trackTransform ⊗ partTransformation ⊗ chain` composition
+ * the renderer uses (`composePartWorldMatrix`), so a snap lands exactly where
+ * the geometry is drawn.
+ *
+ * Pure: no three.js scene, no React — only `Matrix4` / `Vector3` math.
+ */
+
+/** One part, resolved to everything the picker needs about it. */
+interface TrackIndexEntry {
+    processingUnitObjectId: number;
+    /** `PartConfig.objectId`. */
+    partObjectId: number;
+    /** `PartConfig.globalNumber` — what `StationConfig.partOids` addresses. */
+    partGlobalNumber: number;
+    chain: BuiltChain;
+    /** orientation ⊗ trackTransform ⊗ partTransformation. */
+    matrix: Matrix4;
+    positionFrame?: PositionFrame;
+    closed: boolean;
+}
+type TrackIndex = TrackIndexEntry[];
+/** A point resolved onto a part's path. */
+interface TrackProjection {
+    entry: TrackIndexEntry;
+    /** Chain-frame position (mm from chain start). */
+    chainPositionMm: number;
+    /** User-frame position — what `MeasurementPoint.track` carries. */
+    partPositionMm: number;
+    positionMm: Vec3;
+    /** Distance from the queried point to the path (mm). */
+    distanceMm: number;
+}
+/**
+ * Resolve every visible part of a configuration once. Cheap enough to rebuild
+ * on config change, far too expensive to rebuild per pointer move — callers
+ * memoize it.
+ */
+declare function buildTrackIndex(config: NormalizedXtsConfig, trackTransformOverrides?: Record<number, TrackTransform>): TrackIndex;
+/**
+ * World position of a chain-frame position on a part. Positions outside
+ * `[0, trackLengthMm]` clamp to the chain ends (`moverWorldAt` semantics);
+ * `null` only for a chain without modules.
+ */
+declare function worldPointOnPart(entry: TrackIndexEntry, chainPositionMm: number): Vec3 | null;
+interface NearestTrackPointOptions {
+    /** Restrict the search to one part (from the hit's scene context). */
+    partGlobalNumber?: number;
+    processingUnitObjectId?: number;
+    /** Coarse scan step (mm). Default 50 restricted, 150 unrestricted. */
+    coarseStepMm?: number;
+    /** Reject results further away than this (mm). Default: no limit. */
+    maxDistanceMm?: number;
+}
+/**
+ * Project a world point onto the nearest part path: coarse scan, then a local
+ * refinement around the best coarse sample. Deterministic and allocation-light
+ * so it can run on every pointer move.
+ */
+declare function nearestTrackPoint(index: TrackIndex, worldPointMm: Vec3, options?: NearestTrackPointOptions): TrackProjection | null;
+/**
+ * World polyline following a part's path between two chain positions.
+ *
+ * On a closed chain the route across the seam is drawn whenever it is the
+ * shorter one — the polyline then matches what `trackDistanceMm` reports, so
+ * the drawn line and the printed value never disagree.
+ */
+declare function trackPolylineWorld(entry: TrackIndexEntry, fromChainMm: number, toChainMm: number, stepMm?: number): Vec3[];
+/**
+ * World position of a mover — the same math `getMoverWorldTransform` reports,
+ * so an annotation anchored to a mover sits exactly on it while it drives.
+ * `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;
+/** 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). */
+declare function trackAnchorWorld(index: TrackIndex, anchor: TrackAnchor): Vec3 | null;
+
+/**
+ * `XtsViewer3DRef.measurements` — the public imperative surface of the
+ * measurement feature.
+ *
+ * A thin, dependency-injected facade over `MeasurementStore`: the store owns
+ * the data, this module adds the evaluated results (which need the track
+ * index and the host's formatting options) and the snapshot shape hosts
+ * subscribe to. Keeping it out of the React handle means the whole API can be
+ * exercised in a unit test without mounting a canvas.
+ */
+
+/** Everything the feature holds, handed to `subscribe` listeners. */
+interface MeasurementSnapshot {
+    measurements: Measurement[];
+    results: MeasurementResult[];
+    annotations: Annotation[];
+    tool: MeasurementTool;
+    draft: MeasurementDraft | null;
+}
+interface MeasurementApi {
+    /** Arm a tool (or `'none'`). Discards a half-finished pick. */
+    setTool(tool: MeasurementTool): void;
+    getTool(): MeasurementTool;
+    /** Points picked so far, `null` while no tool is armed. */
+    getDraft(): MeasurementDraft | null;
+    /** Discard the current pick; the tool stays armed. */
+    cancel(): void;
+    /** 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;
+    remove(id: MeasurementId): boolean;
+    clear(): void;
+    /** Replace the whole list (e.g. restoring a persisted session). */
+    set(measurements: readonly MeasurementInput[]): Measurement[];
+    list(): Measurement[];
+    get(id: MeasurementId): Measurement | null;
+    /** Evaluated values of every measurement, in list order. */
+    results(): MeasurementResult[];
+    result(id: MeasurementId): MeasurementResult | null;
+    addAnnotation(annotation: AnnotationInput): Annotation;
+    updateAnnotation(id: string, patch: Partial<Omit<Annotation, 'id'>>): Annotation | null;
+    removeAnnotation(id: string): boolean;
+    clearAnnotations(): void;
+    setAnnotations(annotations: readonly AnnotationInput[]): Annotation[];
+    listAnnotations(): Annotation[];
+    /**
+     * One-off computation between two world points — nothing is added to the
+     * scene. Useful for readouts a host derives from its own data.
+     */
+    measureBetween(a: Vec3, b: Vec3, options?: {
+        axis?: 'free' | 'x' | 'y' | 'z';
+    }): MeasurementResult;
+    /** Fires after every change; returns an unsubscribe function. */
+    subscribe(listener: (snapshot: MeasurementSnapshot) => void): () => void;
+    /** Current state as one object. */
+    snapshot(): MeasurementSnapshot;
+    toJSON(): MeasurementDocument;
+    fromJSON(document: MeasurementDocument): void;
+}
+
 /**
  * Imperative ref API for <XtsViewer3D>.
  *
@@ -1858,6 +2353,12 @@ interface XtsViewer3DRef {
     getRuntimeState(): XtsRuntimeState;
     exportModel(opts?: {
         includeRuntime?: boolean;
+        /**
+         * Include measurements + annotations (default `true` when any exist).
+         * The key is omitted entirely for a layout without measurements, so
+         * documents stay identical to pre-measurement exports.
+         */
+        includeMeasurements?: boolean;
     }): XtsModelDocument;
     exportScreenshot(opts?: ScreenshotOptions): Promise<ScreenshotResult>;
     /**
@@ -1928,6 +2429,25 @@ interface XtsViewer3DRef {
      * sorted deepest-overlap-first.
      */
     checkModuleCollisions(opts?: CheckModuleCollisionsOptions): ModuleCollision[];
+    /**
+     * CAD-style measurements and annotations — see `MeasurementApi`.
+     *
+     * The namespace is stable for the lifetime of the component, so it can be
+     * captured once:
+     *
+     * ```ts
+     * const measure = viewerRef.current.measurements;
+     * measure.setTool('distance');                  // user picks two points
+     * measure.add({ kind: 'distance', points: [    // or place one directly
+     *   { positionMm: [0, 0, 200] },
+     *   { positionMm: [1000, 0, 200] },
+     * ]});
+     * const doc = measure.toJSON();                 // persist
+     * ```
+     *
+     * Works the same in the 2D plan view (`projection='orthographic'`).
+     */
+    measurements: MeasurementApi;
 }
 
 /**
@@ -2376,6 +2896,28 @@ interface XtsViewer3DProps {
         warningGapMm?: number;
         onCollisionsChange?: (collisions: ModuleCollision[]) => void;
     };
+    /**
+     * CAD-style measurement tools + annotations, in the 3D view and the 2D
+     * plan view alike.
+     *
+     * Arm a tool (`measurement={{ tool: 'distance' }}`) and the user picks
+     * points in the scene with snapping; everything already measured is
+     * available — and editable — through `viewerRef.current.measurements`.
+     * Selection is suppressed while a tool is armed so a measuring click never
+     * also selects a mover.
+     *
+     * @example
+     * ```tsx
+     * <XtsViewer3D
+     *   measurement={{
+     *     tool,
+     *     snap: { enabled: true, radiusPx: 14 },
+     *     onMeasurementCreate: (m, result) => console.log(result.text),
+     *   }}
+     * />
+     * ```
+     */
+    measurement?: MeasurementOptions;
     /** Dev/Debug. */
     debug?: {
         showPathSplines?: boolean;
@@ -3073,4 +3615,105 @@ declare function getSharedAssetLoader(): AssetLoader;
 /** Compose a URL from a base + a filename, normalising trailing slashes. */
 declare function composeAssetUrl(baseUrl: string, filename: string): 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 CameraProjection, type CameraState, type CaptureMode, type CheckModuleCollisionsOptions, type CheckMoverCollisionsOptions, type ClickModifiers, type CoordinateSystem, type CustomAssetBinding, type CustomAssetConfig, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MODULE_HALF_WIDTH_MM, DEFAULT_MODULE_HEIGHT_MM, DEFAULT_MODULE_MANIFEST, DEFAULT_MOVER_MANIFEST, DEFAULT_ORIGIN_CORRECTION, DEFAULT_RAIL_MANIFEST, DEFAULT_TOOL_MANIFEST, type DimensionOptions, type DisplayOptions, EMPTY_SELECTION, type EndDelta, type FeedSegment, type FeedSegmentHighlight, type FeedSegmentSelector, type FeedSegmentSpan, type FocusOptions, type FocusTarget, type FrameCaptureOptions, type FrameCaptureSession, HEPCO_GFX_PROFILE, type HeatmapSample, type HepcoGfxRailProfileDims, IDENTITY_POSE, INFEED_MODULE_TYPES, type InfoBarConfig, type InfoBarMarkerConfig, type InfoBarOptions, JSDELIVR_ASSETS_BASE_URL, MODULE_CATALOG, MODULE_GUIDING_RAIL_MAP, MOVER_CATALOG, type MarkerOptions, type MarkerShape, type 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 PathSample, type PathType, type PlanarPose, type PointCloud, type PositionFrame, type ProcessingUnitConfig, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionMode, type SelectionState, SidecarLoader, type SidecarOverrides, type SidecarSourceConfig, SidecarSourceContext, type SplitFeedSegmentsOptions, 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, applyBeckhoffXtsConvention, applyEmptyClick, applyModuleClick, applyMoverClick, buildChain, buildModuleProbes, buildPartPath, chainToUserPositionMm, checkModuleCollisions, checkSamePathCollisions, collectFeedSegments, collectFeedSegmentsForXpu, composeAssetUrl, createHepcoGfxBaseplateShape, createHepcoGfxRailShape, deselectAll, findModuleAt, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, interpolateHeatmapValue, isChainClosed, 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, splitIntoFeedSegments, toolSidecarFilename, trackLengthOf, unregisterPointCloud, useSidecarSource, userToChainPositionMm };
+/**
+ * Style resolution for the measurement overlay — one place where every
+ * default lives, so the scene, the draft preview and the value formatting
+ * agree without each component re-deriving fallbacks.
+ */
+
+interface ResolvedMeasurementStyle {
+    color: string;
+    draftColor: string;
+    annotationColor: string;
+    lineWidthPx: number;
+    labelSizeMm: number;
+    pointSizeMm: number;
+    decimals: number;
+    unitSuffix: string;
+    fontFamily?: string;
+    alwaysOnTop: boolean;
+}
+declare const DEFAULT_MEASUREMENT_STYLE: Omit<ResolvedMeasurementStyle, 'fontFamily'>;
+declare function resolveMeasurementStyle(style?: MeasurementStyle): ResolvedMeasurementStyle;
+
+/**
+ * Snap candidate collection + selection.
+ *
+ * A pick is resolved in two steps:
+ *   1. collect candidates — corners / edge midpoints / face centre of the
+ *      triangle the ray hit (`collectTriangleSnapCandidates`), plus the
+ *      semantic XTS points from `trackSnapping.ts`;
+ *   2. choose one — `chooseSnapCandidate` scores them in SCREEN space, so a
+ *      snap feels the same whether the user is 300 mm or 30 m from the
+ *      geometry, in the perspective view and in the 2D plan view alike.
+ *
+ * `chooseSnapCandidate` takes the projection as a function rather than a
+ * camera, which keeps the selection rule testable without a renderer.
+ */
+
+interface SnapCandidate {
+    kind: SnapKind;
+    positionMm: Vec3;
+    entity?: MeasuredEntityRef;
+    track?: TrackAnchor;
+}
+/** Screen-space point in CSS pixels, relative to the canvas. */
+interface PointerPx {
+    x: number;
+    y: number;
+}
+/** Projects a world point to canvas pixels, or `null` when off-screen. */
+type PointProjector = (positionMm: Vec3) => PointerPx | null;
+/**
+ * Default priority order. Corners beat everything (they are what a CAD user
+ * aims at), the semantic XTS points come next, and the face centre is last —
+ * it is the weakest hint and would otherwise mask a nearby vertex.
+ */
+declare const DEFAULT_SNAP_KINDS: SnapKind[];
+declare const DEFAULT_SNAP_RADIUS_PX = 14;
+interface ChooseSnapOptions {
+    radiusPx?: number;
+    /** Allowed kinds, highest priority first. Default {@link DEFAULT_SNAP_KINDS}. */
+    kinds?: readonly SnapKind[];
+}
+/**
+ * Pick the best candidate within `radiusPx` of the pointer: higher-priority
+ * kinds win outright, ties break on screen distance. Returns `null` when
+ * nothing qualifies — the caller then keeps the raw hit point.
+ */
+declare function chooseSnapCandidate(candidates: readonly SnapCandidate[], project: PointProjector, pointerPx: PointerPx, options?: ChooseSnapOptions): SnapCandidate | null;
+/** Minimal structural view of a raycast hit — keeps this testable. */
+interface TriangleHit {
+    object: Object3D;
+    face?: {
+        a: number;
+        b: number;
+        c: number;
+    } | null | undefined;
+    instanceId?: number | undefined;
+}
+/**
+ * Corners, edge midpoints and centre of the triangle the ray hit, in world
+ * space. Returns `[]` for hits without face information (lines, points,
+ * sprites) or geometry without a position attribute.
+ */
+declare function collectTriangleSnapCandidates(hit: TriangleHit, entity?: MeasuredEntityRef): SnapCandidate[];
+/** Round a point onto a `gridMm` lattice. `gridMm <= 0` returns the input. */
+declare function snapToGrid(positionMm: Vec3, gridMm: number): Vec3;
+
+/**
+ * Scene identity tags — how a raycast hit becomes an XTS entity reference.
+ *
+ * The renderer already names its groups (`xpu-3`, `part-1`, …), but a name is
+ * a debug aid, not a contract: it carries no object ids and would break the
+ * moment a name is reworded. Instead every group that corresponds to a
+ * configuration entity carries a structured `userData.xtsTag`, and the picker
+ * walks the parent chain to assemble the reference — nearest tag of each kind
+ * wins, which is exactly the nesting the scene builds
+ * (xpu → part → module | mover).
+ */
+
+/** Convenience: `resolveSceneContext` + `toEntityRef`. */
+declare function resolveEntityFromObject(object: Object3D | null, instanceId?: number): MeasuredEntityRef | null;
+
+export { type AngleMeasurement, type Annotation, type AnnotationAnchor, type AnnotationInput, type AreaConfig, type AreaOptions, AssetLoader, type AssetManifest, BUILTIN_MODULE_SIDECARS, BUILTIN_MOVER_SIDECARS, BUILTIN_RAIL_SIDECARS, BUILTIN_TOOL_SIDECARS, type BuiltChain, type BuiltModule, type CameraProjection, type CameraState, type CaptureMode, type CheckModuleCollisionsOptions, type CheckMoverCollisionsOptions, type ClickModifiers, type CoordinateSystem, type CustomAssetBinding, type CustomAssetConfig, type CustomMoverLayout, DEFAULT_LABEL_FONT_URL, DEFAULT_MEASUREMENT_STYLE, DEFAULT_MODULE_HALF_WIDTH_MM, DEFAULT_MODULE_HEIGHT_MM, DEFAULT_MODULE_MANIFEST, DEFAULT_MOVER_MANIFEST, DEFAULT_ORIGIN_CORRECTION, DEFAULT_RAIL_MANIFEST, DEFAULT_SNAP_KINDS, DEFAULT_SNAP_RADIUS_PX, DEFAULT_TOOL_MANIFEST, type DimensionOptions, type DisplayOptions, type DistanceMeasurement, EMPTY_SELECTION, type EndDelta, type FeedSegment, type FeedSegmentHighlight, type FeedSegmentSelector, type FeedSegmentSpan, type FocusOptions, type FocusTarget, type FrameCaptureOptions, type FrameCaptureSession, HEPCO_GFX_PROFILE, type HeatmapSample, type HepcoGfxRailProfileDims, IDENTITY_POSE, INFEED_MODULE_TYPES, type InfoBarConfig, type InfoBarMarkerConfig, type InfoBarOptions, JSDELIVR_ASSETS_BASE_URL, MODULE_CATALOG, MODULE_GUIDING_RAIL_MAP, MOVER_CATALOG, type MarkerOptions, type MarkerShape, type MeasuredEntityRef, type Measurement, type MeasurementApi, type MeasurementAxis, type MeasurementDocument, type MeasurementDraft, type MeasurementFormatOptions, type MeasurementId, type MeasurementInput, type MeasurementKind, type MeasurementOptions, type MeasurementPoint, type MeasurementResult, type MeasurementSnapshot, type MeasurementStyle, type MeasurementTool, type ModuleAssetEntry, type ModuleCatalogEntry, type ModuleCollision, type ModuleCollisionPartInput, type ModuleCollisionXpuInput, ModuleCornerMarkers, type ModuleEntry, type ModuleHighlight, type ModuleProbe, type ModuleRef, type ModuleSidecar, type ModuleStatusEntry, type ModuleType3D, type MoverAssetEntry, type MoverCatalogEntry, type MoverCollision, type MoverConfig, MoverIdLabel, type MoverIdLabelOptions, type MoverPositionEntry, type MoverProbe, type MoverRef, type MoverSidecar, type MoverToolAssetEntry, type MoverToolConfig, type MoverToolSidecar, type MoverToolType3D, type MoverType3D, type NormalizationWarning, type NormalizedXtsConfig, type Orientation, type OriginCorrection, type PartConfig, type PartPath, type PartTransformation, type PathMeasurement, type PathSample, type PathType, type PlanarPose, type PointCloud, type PointProjector, type PositionFrame, type ProcessingUnitConfig, type RailAssetEntry, type RailSidecar, type RailSystem, type RailType3D, type ResolvedMeasurementStyle, type ScreenshotFormat, type ScreenshotMode, type ScreenshotOptions, type ScreenshotResult, type SelectionMode, type SelectionState, SidecarLoader, type SidecarOverrides, type SidecarSourceConfig, SidecarSourceContext, type SnapCandidate, type SnapKind, type SnapOptions, type SplitFeedSegmentsOptions, type StationConfig, type StationOptions, type StatorHeatmap, type StopPositionMoverOptions, type TextOptions, type TrackAnchor, type TrackDistanceMeasurement, type TrackIndex, type TrackIndexEntry, type TrackMetrics, type TrackMetricsResolver, type TrackProjection, type TrackTransform, VERSION, type Vec2, type Vec3, XtsArcCurve3, type XtsConfig, XtsConfigNormalizer, type XtsModelDocument, XtsPointCloudCurve3, type XtsRuntimeState, XtsViewer3D, type XtsViewer3DProps, type XtsViewer3DRef, type XtsViewerError, type XtsViewerErrorCode, XtsViewerErrorException, angleDeg, applyBeckhoffXtsConvention, applyEmptyClick, applyModuleClick, applyMoverClick, arcPoints, axisDistanceMm, buildChain, buildModuleProbes, buildPartPath, buildTrackIndex, chainToUserPositionMm, checkModuleCollisions, checkSamePathCollisions, chooseSnapCandidate, collectFeedSegments, collectFeedSegmentsForXpu, collectTriangleSnapCandidates, composeAssetUrl, computeMeasurementResult, createHepcoGfxBaseplateShape, createHepcoGfxRailShape, deselectAll, distanceMm, findModuleAt, formatAngleDeg, formatLengthMm, getModuleEntry, getMoverEntry, getPointCloud, getSharedAssetLoader, interpolateHeatmapValue, isChainClosed, isKnownModuleType, isKnownMoverType, isModuleSelected, isMoverSelected, labelAnchorFor, moduleAnchorWorld, moduleEndDelta, moduleSidecarFilename, moverAnchorWorld, moverSidecarFilename, moverWorldAt, nearestTrackPoint, normaliseToHeatmapRange, normalizeXtsConfig, pathLengthsMm, pickGlbForRail, poseToMatrix4, railSidecarFilename, registerPointCloud, resolveEntityFromObject, resolveGuidingRailGlbUrl, resolveGuidingRailType, resolveHepcoGfxProfile, resolveMeasurementStyle, resolveModuleGlbUrl, resolveMoverGlbUrl, resolveOriginCorrection, resolveStopPositionMm, resolveToolGlbUrl, sampleChainPoint, sampleChainRange, sampleModulePath, snapToGrid, sortHeatmapSamples, splitIntoFeedSegments, toolSidecarFilename, trackAnchorWorld, trackDistanceMm, trackLengthOf, trackPolylineWorld, unregisterPointCloud, useSidecarSource, userToChainPositionMm, worldPointOnPart };