@toolpath/viewer 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { P as PartModel, V as Vec3, d as ViewerTheme, e as PartModelRegion, T as TriangleRange, F as FeatureTag, R as RegionIndex, f as PartModelFeature, g as FeatureType } from './normalize-OULo7e0F.js';
-export { B as BuildPickInput, C as CANDIDATE_WEIGHT, D as DEFAULT_THEME, h as DIRECTION_COLORS, E as EnginePart, i as FeatureHighlight, H as HANDLE_PIXELS, j as HIGHLIGHT_COLORS, k as HIGHLIGHT_WEIGHT, l as HOVER_WEIGHT, m as HighlightLayers, K as KnownFeatureType, o as KnownShapeKind, N as NO_MODIFIERS, p as PICKED_SURFACE_LABEL, q as PartMesh, r as PartMeshProps, a as PartMeshRefs, t as PartObject, u as PartPick, v as PickModifiers, w as REGION_ATTRIBUTE, x as RegionHighlight, y as RegionPaint, S as SECTION_RENDER_ORDER, z as SectionAnchor, A as SectionBounds, G as SectionOptions, I as SectionPlacement, J as SectionState, L as SectionView, O as ShapeKind, Q as applyHighlightLayers, U as buildPick, W as buildRegionAttribute, X as buildRegionTexels, Y as createPart, Z as directionColor, _ as dragPlane, $ as focusForPick, n as normalizePartReport, a0 as pickedStartDepth, a1 as resolveSectionPlane, a2 as resolveTheme, a3 as sectionBounds, a4 as sectionConstant, a5 as sectionDepth, a6 as sectionDepthConstant, a7 as sectionDepthRange, a8 as sectionFromPick, a9 as sectionOffset, aa as sectionPlane, s as smoothRegionNormals, ab as themesEqual, ac as viewDirection } from './normalize-OULo7e0F.js';
-import { BufferGeometry, CanvasTexture, Vector3, Box3, OrthographicCamera, PerspectiveCamera, Object3D } from 'three';
+import { P as PartModel, V as Vec3, d as ViewerTheme, S as SectionOptions, e as SectionState, f as PartModelRegion, T as TriangleRange, F as FeatureTag, R as RegionIndex, g as PartModelFeature, h as FeatureType } from './normalize-DHOSNiuO.js';
+export { A as AXES_PLANE_OFFSET, i as AXES_PLANE_SCALE, j as AxesPlane, B as BuildPickInput, C as CANDIDATE_WEIGHT, k as CAP_HATCH, D as DEFAULT_SECTION_NORMAL, l as DEFAULT_THEME, m as DIRECTION_COLORS, o as DISABLED_SECTION, E as EnginePart, p as FeatureHighlight, H as HANDLE_PIXELS, q as HIGHLIGHT_COLORS, r as HIGHLIGHT_WEIGHT, t as HOVER_WEIGHT, u as HighlightLayers, K as KnownFeatureType, v as KnownShapeKind, N as NO_MODIFIERS, O as OUTLINE_SCALE, w as PICKED_SURFACE_LABEL, x as PREVIEW_SCALE, y as PartMesh, z as PartMeshProps, a as PartMeshRefs, G as PartObject, I as PartPick, J as PickModifiers, L as REGION_ATTRIBUTE, Q as RegionHighlight, U as RegionPaint, W as SECTION_RENDER_ORDER, X as SectionAnchor, Y as SectionBounds, Z as SectionPlacement, _ as ShapeKind, $ as SurfaceHit, a0 as applyHighlightLayers, a1 as axesPlanes, a2 as buildPick, a3 as buildRegionAttribute, a4 as buildRegionTexels, a5 as createPart, a6 as directionColor, a7 as dragPlane, a8 as focusForPick, a9 as hitUnderRay, n as normalizePartReport, aa as pickedStartDepth, ab as resolveTheme, ac as sectionAnchor, ad as sectionBounds, ae as sectionConstant, af as sectionDepth, ag as sectionDepthConstant, ah as sectionDepthRange, ai as sectionFromPick, aj as sectionOffset, ak as sectionOptionsFromState, al as sectionPlane, s as smoothRegionNormals, am as surfaceUnderRay, an as themesEqual, ao as viewDirection } from './normalize-DHOSNiuO.js';
+import { BufferGeometry, CanvasTexture, Box3, Plane, Vector3, OrthographicCamera, PerspectiveCamera, Object3D, Matrix4, Vector2, ShaderMaterial, Texture, Color, MeshBasicMaterial, WebGLRenderTarget } from 'three';
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties } from 'react';
 import CameraControls from 'camera-controls';
@@ -114,7 +114,7 @@ interface GridProps {
  * fixed cells is either invisible on a 900 mm plate or a solid wash under a
  * 12 mm insert.
  */
-declare const Grid: ({ step, extent, color, opacity }: GridProps) => react.JSX.Element;
+declare const Grid: ({ step, extent, color, opacity }: GridProps) => react.JSX.Element | null;
 interface AxesProps {
     size?: number;
 }
@@ -192,199 +192,62 @@ interface DirectionArrowsProps {
  */
 declare const DirectionArrows: ({ directions, activeDirection, shownDirection, previewDirection, namedDirections, onPickDirection, theme, visible, }: DirectionArrowsProps) => react.JSX.Element | null;
 
-interface ArrowPlacement {
-    /** Where the arrow's tip sits: outside the box, on the direction's ray. */
-    readonly tip: Vector3;
-    readonly length: number;
+/** The cut's plane for a set of options, or `null` when there is no cut. */
+declare function resolveSectionPlane(options: SectionOptions | undefined, box: Box3): {
+    plane: Plane;
+    state: SectionState;
+} | null;
+interface SectionViewProps {
+    geometry: BufferGeometry;
+    box: Box3;
+    plane: Plane;
+    theme: ViewerTheme;
+    showHandle: boolean;
+    onDrag?: (constant: number) => void;
 }
 /**
- * Where an arrow for `direction` sits relative to the part.
- *
- * The exit distance is the smallest `halfExtent / |component|` over the axes the
- * direction actually moves along — the first face of the box the ray leaves
- * through. That formulation is what makes this work for **arbitrary unit
- * vectors** rather than only for axes: real reports carry tilted directions,
- * one of them a 36° five-axis setup, and an axis-aligned simplification would
- * bury those arrows inside the part.
+ * A clipping plane with a hatched cap over the cut, and an arrow that drags it.
+ *
+ * The cap is the standard two-pass stencil trick: draw the clipped geometry's
+ * back faces incrementing the stencil and its front faces decrementing it, so a
+ * non-zero stencil marks exactly where the plane passes through solid material,
+ * then fill that region with a quad. Without it a section shows the inside of
+ * the far wall and the part reads as hollow.
+ *
+ * The fill is hatched and outlined — see `render/section-cap.ts` — which takes
+ * a pre-pass: the same stencil trick is run once more into a render target on
+ * its own, so the cap's shader can find its edge by sampling that mask. That
+ * pass draws a scene of its own holding nothing but the stencil meshes and the
+ * mask quad, at a priority ahead of R3F's own render.
+ *
+ * **The renderer must be created with `stencil: true`.** three defaults it to
+ * false, and without it every one of those stencil operations is a silent
+ * no-op — the cut still happens and the part still looks hollow, which is a
+ * confusing way to find out.
  */
-declare function arrowPlacement(direction: Vec3, box: Box3): ArrowPlacement;
+declare const SectionView: ({ geometry, box, plane, theme, showHandle, onDrag, }: SectionViewProps) => react.JSX.Element;
 
-/**
- * The bounds of the part, for the overlays that have to be sized against it.
- *
- * Measured on a frame rather than in an effect, because a Suspense-loaded mesh
- * does not exist yet when the effects around it run — the same reason the
- * viewer's opening frame waits. Measured once: an overlay that re-fitted itself
- * while the part was being orbited would be a grid that breathes.
- *
- * Scene furniture is excluded, so the grid and the axes do not size each other.
- */
-declare function useContentBox(): Box3;
-
-/**
- * Telling a click apart from the end of a drag.
- *
- * The browser calls both a click: press, move, release over the same element
- * fires `click` however far the pointer travelled in between. In a viewport
- * that is the difference between "select this face" and "I have finished
- * orbiting" — and the part is one mesh, so releasing over a different face is
- * still the same element and still a click.
- *
- * Left unguarded, every orbit that happens to end over the part selects
- * whatever it ended on, throwing away the selection the orbit was made to look
- * at.
- */
-/** How far a pointer may travel and still be a click, in CSS pixels. */
-declare const TAP_SLOP = 4;
-interface TapPoint {
-    readonly clientX: number;
-    readonly clientY: number;
-}
-/** Whether the pointer travelled far enough for this to be a drag. */
-declare function movedFar(from: TapPoint, to: TapPoint, slop?: number): boolean;
-interface TapTracker {
-    /** Whether the gesture ending at this event was a click rather than a drag. */
-    isTap(event: TapPoint): boolean;
-    dispose(): void;
-}
-/**
- * Watches an element for the start of every gesture, so its end can be judged.
- *
- * Listens in the capture phase: whatever else handles the press — the camera
- * controls, a drag handle — the start of the gesture still has to be recorded,
- * and a listener that runs after `stopPropagation` runs never.
- */
-declare function trackTaps(element: HTMLElement): TapTracker;
-/**
- * How long between two presses still reads as one gesture, in milliseconds.
- *
- * The browser's own `dblclick` threshold is a platform setting and is not
- * readable from script, so a hand-paired gesture has to pick a number. 400ms is
- * inside every default and outside a deliberate pair of separate clicks.
- */
-declare const DOUBLE_TAP_MS = 400;
-interface DoubleTapPoint extends TapPoint {
-    readonly timeStamp: number;
-}
-interface DoubleTapTracker {
-    /** Whether this press completes a double tap begun by the last one. */
-    isDouble(event: DoubleTapPoint): boolean;
-    /**
-     * Forgets the press being waited on, so the next one starts a fresh pair.
-     *
-     * For the caller that knows the gesture was interrupted by something this
-     * has no way to see — the pointer leaving the thing being clicked, most of
-     * all. Two presses either side of a trip to a panel are two clicks that
-     * happen to be quick, however close together the clock puts them.
-     */
-    reset(): void;
-}
-/**
- * Pairing presses into a double tap by hand.
- *
- * Needed because `dblclick` fires for the **primary button only** — there is no
- * such event for the middle button, however many times it is pressed. So a
- * middle-button gesture has to be assembled from single presses.
- *
- * Position matters as well as time: two presses at opposite corners inside the
- * window are two clicks that happened to be quick, not one gesture, and
- * treating them as a double would re-frame the view out from under somebody
- * who was doing something else. The same {@link TAP_SLOP} the click guard uses.
- *
- * A completed double clears the state rather than leaving it, so three presses
- * are one double and one single rather than two overlapping doubles.
- *
- * Time and position are all this can judge on, which is not enough on its own:
- * clicking a face, pressing something in a panel and clicking the same face
- * again is three gestures the clock cannot tell from two, and it is quick
- * enough to land inside the window. {@link DoubleTapTracker.reset} is how the
- * caller says the pair was broken by something it could see and this could not.
- */
-declare function trackDoubleTaps(within?: number, slop?: number): DoubleTapTracker;
-
-/** Whether the gesture ending at this event was a click rather than a drag. */
-type TapGuard = (event: TapPoint) => boolean;
-/**
- * A click that is a click, for anything inside the canvas.
- *
- * Bound to the canvas element rather than to the object, because the gesture
- * being judged started before any object knew about it.
- *
- * Under a `<Viewer>` this returns the tracker the scene already owns and
- * attaches nothing. Called outside one — it is exported, so a consumer may use
- * it in a scene of their own — it owns a tracker of its own instead. The effect
- * is what differs, not the hooks: they run in the same order either way.
- */
-declare function useTapGuard(): TapGuard;
-
-interface GridSpec {
-    /** Cell size in part units (millimetres). */
-    readonly step: number;
-    /** Half-width of the grid, so it spans `2 × extent`. */
-    readonly extent: number;
-    /** The plane the grid sits on: the bottom of the part, snapped to a step. */
-    readonly z: number;
-    readonly center: Vector3;
+interface SectionToolProps {
+    theme?: Partial<ViewerTheme>;
 }
 /**
- * Sizes a ground grid for a part.
- *
- * The step comes from a 1-2-5 progression rather than a fixed size, so the same
- * code reads sensibly for a 12 mm insert and a 900 mm plate — the Engine emits
- * millimetres but says nothing about scale.
- *
- * The plane is the *bottom* of the part, not `z = 0`: parts usually sit on
- * `z = 0` and then the two agree, but one modelled about its centre would
- * otherwise be sliced in half by its own grid.
- */
-declare function gridSpec(box: Box3): GridSpec;
-/**
- * A ground grid on the part's Z-up base plane.
- *
- * Built directly rather than with `GridHelper`, which lays out on XZ for a Y-up
- * world and has to be rotated into place — the Engine is Z-up, and a rotated
- * helper is a thing to remember rather than a thing that is true.
- */
-declare function gridGeometry(spec: GridSpec): BufferGeometry;
-
-/**
- * The lines between regions, and nothing else.
- *
- * `EdgesGeometry` draws an edge wherever two facets meet at more than some
- * angle, which is a guess standing in for "is this a real edge". On a machined
- * part the guess is wrong in both directions: a small bore tessellated into
- * twelve facets has 30° between them and gets drawn as a nut, while a shallow
- * chamfer meeting a wall at 12° gets no line at all.
- *
- * The report already knows. A region is one analytic surface, so an edge inside
- * one is tessellation and an edge between two is a real boundary — the same
- * fact that makes region-aware shading possible, used for the other half of
- * what makes a part read as a part.
- *
- * With one qualification. The Engine splits a surface where that makes a better
- * machining plan, and those splits are boundaries between regions without being
- * edges of the part: a floor cut in two to be reached from two directions is
- * still one face to look at. So the walk is over *visual surfaces* — regions
- * grouped by the kernel's exact `splitOrigin` lineage — and a split leaves no
- * line. Nothing about picking or features goes through that grouping.
- *
- * The mesh must be non-indexed, which `parsePartGeometry` guarantees.
- */
-declare function regionEdgesGeometry(geometry: BufferGeometry, model: Pick<PartModel, 'regions' | 'regionIndex'>): BufferGeometry;
-
-/** Region index → the visual surface it belongs to. */
-type SurfaceOf = ReadonlyMap<number, number>;
-/**
- * The visual surface of each post-split region.
- *
- * The kernel divides B-rep faces to make machining relationships unambiguous.
- * Those divisions remain meaningful to feature extraction and picking, but
- * they are not physical edges. `splitOrigin` is the kernel's exact lineage
- * relation: equal values mean the regions were one face before that analysis
- * split. It is therefore the single grouping used for rendering, rather than
- * attempting to infer continuations from mesh normals or surface kinds.
+ * The interactive way to cut a part open. Mount it beside `<PartMesh>`.
+ *
+ * With no cut in place it offers two: hover a face and a small square previews
+ * a cut through it — click to make it — or click one of the three global
+ * planes standing behind the part to sweep along that axis. Once there is a
+ * cut it draws the cutting plane as a translucent sheet with an outline, and
+ * `Escape` clears it. The handle that drags the cut, and the hatched cap, are
+ * the part's own and appear whether or not this is mounted.
+ *
+ * Nothing needs wiring. The cut lives in the viewer, `<PartMesh>` follows it
+ * when it is given no `section` of its own, and `ViewerHandle.setSection` is
+ * the way to set or clear it from outside the canvas. While this is mounted
+ * the part reports no hovers or picks: a click on a face cuts through it
+ * without also selecting it, and a cut part is looked at rather than picked
+ * at. Unmounting it hands the pointer back.
  */
-declare function visualSurfaces(regions: readonly PartModelRegion[]): SurfaceOf;
+declare const SectionTool: ({ theme }: SectionToolProps) => react.JSX.Element | null;
 
 type Projection = 'orthographic' | 'perspective';
 type ViewerCamera = OrthographicCamera | PerspectiveCamera;
@@ -443,6 +306,13 @@ declare function boundsFromBox(box: Box3): SceneBounds;
  * would be a speck.
  */
 declare function contentBounds(root: Object3D, into: Box3): SceneBounds;
+/**
+ * Whether `object`, or anything between it and `root`, carries
+ * {@link EXCLUDE_FROM_FRAME}. The flag is set on an overlay's outermost group
+ * and means the whole subtree, so the walk goes up rather than reading the
+ * object alone.
+ */
+declare function excludedFromFrame(object: Object3D, root: Object3D): boolean;
 /**
  * The distance at which a sphere of `radius` fits inside a perspective frustum.
  * Uses the narrower of the two field-of-view angles, so a portrait viewport
@@ -580,6 +450,551 @@ type ViewerView = keyof typeof cadViewDirections;
 /** The current orbit direction, so Fit can retain the direction being looked from. */
 declare function currentViewDirection(camera: ViewerCamera, target: Vector3, into: Vector3): Vector3;
 
+/**
+ * Measuring, without a canvas: where a pointer snaps to, what two or three
+ * points measure, and how that is written down. `measure-tool.tsx` is the
+ * React surface over this.
+ */
+/** Draws over the part and the section cap, under nothing. */
+declare const MEASURE_RENDER_ORDER = 7;
+/**
+ * One colour per world axis, the hue `<Axes>` draws that axis in — lightened,
+ * because a pure primary through 30% on a dark page is mud, and the blue one
+ * was not there at all. The section tool's three global planes and a
+ * distance's X, Y, Z legs both wear them, so an axis is one colour everywhere.
+ */
+declare const AXIS_COLORS: Record<Axis, number>;
+/**
+ * How close, in CSS pixels, the pointer has to be for a snap to take.
+ *
+ * A vertex or a midpoint is a point, so it gets the wider reach; an edge is a
+ * line the pointer can sit on, so it needs less. The pointer snaps to the
+ * strongest kind it is within reach of — a corner over the edge it ends, the
+ * edge over the face it bounds — which is what makes clicking the corner of a
+ * part produce the corner rather than a point a pixel off it.
+ */
+declare const SNAP_PIXELS: {
+    readonly vertex: 14;
+    readonly midpoint: 12;
+    readonly edge: 9;
+};
+/** The snap indicator's radius on screen, by what it is on, in CSS pixels. */
+declare const SNAP_MARKER_PIXELS: {
+    readonly vertex: 6;
+    readonly midpoint: 5;
+    readonly edge: 4;
+    readonly face: 3.5;
+};
+/** A measurement's end marker, in CSS pixels. */
+declare const MEASURE_MARKER_PIXELS = 3.5;
+/**
+ * Line widths in CSS pixels: a measurement's own line, a delta leg, and the
+ * edge the pointer is snapped to.
+ */
+declare const MEASURE_LINE_PIXELS: {
+    readonly line: 2;
+    readonly leg: 1.5;
+    readonly edge: 3;
+};
+/** Dash and gap of a delta leg, in CSS pixels. */
+declare const DELTA_DASH_PIXELS = 6;
+/** How much of the shorter arm an angle's arc is drawn at. */
+declare const ANGLE_ARC_FRACTION = 0.3;
+/** Segments in an angle's arc. */
+declare const ANGLE_ARC_SEGMENTS = 24;
+type SnapKind = 'vertex' | 'midpoint' | 'edge' | 'face';
+/** Where the pointer landed after snapping, and what it landed on. */
+interface Snap {
+    readonly kind: SnapKind;
+    readonly point: Vector3;
+    /** The outward normal of the surface under the pointer, in world space. */
+    readonly normal: Vector3;
+    /** For an edge or midpoint snap, the edge in world space. */
+    readonly edge: readonly [Vector3, Vector3] | null;
+}
+/**
+ * The edges a pointer can snap to: segment endpoints, six floats per segment,
+ * in the space `matrixWorld` maps to the world.
+ *
+ * In practice this is the part's own edge overlay — `regionEdgesGeometry` —
+ * which draws a line only where two analytic surfaces meet. Those are the edges
+ * a machinist would put a caliper on; the diagonal a tessellator drew across a
+ * flat face is not, and snapping to it would measure the mesh rather than the
+ * part.
+ */
+interface SnapEdges {
+    readonly positions: ArrayLike<number>;
+    readonly matrixWorld: Matrix4;
+}
+/** What the ray hit, before snapping. */
+interface SnapHit {
+    readonly point: Vector3;
+    readonly normal: Vector3;
+}
+/**
+ * Where a hit on the part snaps to.
+ *
+ * Nearness is judged on screen, in pixels, because that is where the pointer
+ * is: a corner three pixels away is a corner however far the camera is. The
+ * search is bounded in world space first — a segment further from the hit than
+ * the widest reach could ever cover is skipped without being projected — and
+ * held to the surface the hit is on: an edge that is within reach of the point
+ * but well off its tangent plane is on the far side of a wall, and snapping to
+ * it would put a measurement on something the eye cannot see.
+ */
+declare function snapAt(hit: SnapHit, edges: SnapEdges | null, camera: ViewerCamera, viewport: ViewportSize): Snap;
+/** Where a world point lands on the canvas, in CSS pixels from the top left. */
+declare function screenPoint(camera: ViewerCamera, point: Vector3, viewport: ViewportSize, into?: Vector2): Vector2;
+type MeasureMode = 'distance' | 'angle';
+/** How many clicks each kind of measurement takes. */
+declare const POINTS_PER_MEASUREMENT: Record<MeasureMode, number>;
+interface DistanceMeasurement {
+    readonly id: number;
+    readonly kind: 'distance';
+    readonly points: readonly [Vec3, Vec3];
+}
+/** Three points: the two arms' ends, with the vertex between them. */
+interface AngleMeasurement {
+    readonly id: number;
+    readonly kind: 'angle';
+    readonly points: readonly [Vec3, Vec3, Vec3];
+}
+type Measurement = DistanceMeasurement | AngleMeasurement;
+/**
+ * A measurement from the points clicked so far, or `null` while there are not
+ * enough of them yet.
+ */
+declare function measurementFromPoints(kind: MeasureMode, points: readonly Vec3[], id: number): Measurement | null;
+/** An id no measurement in `held` has. */
+declare function nextMeasurementId(held: readonly Measurement[]): number;
+declare function distanceBetween(a: Vec3, b: Vec3): number;
+/** `b − a`, per axis. */
+declare function deltaBetween(a: Vec3, b: Vec3): Vec3;
+declare function midpoint(a: Vec3, b: Vec3): Vec3;
+/**
+ * The angle at `vertex` between the arms to `a` and `b`, in degrees, from 0 to
+ * 180. An arm with no length has no direction, and the angle is 0.
+ */
+declare function angleAt(vertex: Vec3, a: Vec3, b: Vec3): number;
+type Axis = 'x' | 'y' | 'z';
+/** One leg of a distance's X, Y, Z breakdown. */
+interface DeltaLeg {
+    readonly axis: Axis;
+    readonly from: Vec3;
+    readonly to: Vec3;
+    readonly length: number;
+}
+/** Where a point lands when it is held to one axis from `from`. */
+interface AxisLock {
+    readonly axis: Axis;
+    readonly point: Vec3;
+}
+/**
+ * `to`, held to the one axis it has moved furthest along from `from`.
+ *
+ * The ortho lock a CAD user reaches for with Shift: the next point is dropped
+ * onto the X, Y or Z line through the last one, so a distance meant to be "how
+ * long is this" is not "how long is this, and a little sideways". Which axis is
+ * whichever the pointer is furthest along, and a pointer that has not moved
+ * stays put on X.
+ */
+declare function lockToAxis(from: Vec3, to: Vec3): AxisLock;
+/**
+ * A distance broken into its X, Y and Z parts, as a path from `a` to `b` that
+ * runs along one axis at a time.
+ *
+ * Only the legs with length are returned, and none at all when the distance
+ * already runs along an axis: a single leg would lie on top of the line it
+ * explains and say nothing the line does not.
+ */
+declare function deltaLegs(a: Vec3, b: Vec3): readonly DeltaLeg[];
+/**
+ * Points along the arc an angle is drawn with, from the arm to `a` round to
+ * the arm to `b`, at `radius` from the vertex.
+ *
+ * Interpolated on the sphere rather than along the chord, so the arc is an
+ * arc. Two arms that point the same way, or opposite ways, have no plane to
+ * draw in, and get their two ends and nothing between.
+ */
+declare function angleArc(vertex: Vec3, a: Vec3, b: Vec3, radius: number, segments?: number): Vector3[];
+/** The radius an angle's arc is drawn at: a fraction of the shorter arm. */
+declare function angleArcRadius(vertex: Vec3, a: Vec3, b: Vec3): number;
+/** A length in millimetres, as the tool writes it when told nothing else. */
+declare function formatMillimetres(mm: number, digits?: number): string;
+declare function formatDegrees(degrees: number, digits?: number): string;
+/** What a measurement's label says. `format` writes a length; angles write themselves. */
+declare function measurementLabel(measurement: Measurement, format?: (mm: number) => string): string;
+/** Where a measurement's label sits: the middle of a distance, the vertex of an angle. */
+declare function measurementLabelAnchor(measurement: Measurement): Vec3;
+
+/**
+ * The class every label carries, for a stylesheet to find.
+ *
+ * The labels ship with no styling at all. Each one is a `<div>` with this
+ * class, `data-measure-label` naming what it is — `distance`, `angle`, `delta`
+ * for one leg of a distance's breakdown, or `live` for the readout that
+ * follows the pointer — `data-axis` on a leg, and `data-measurement-id` on
+ * anything belonging to a finished measurement. The README shows a stylesheet
+ * to start from.
+ */
+declare const MEASURE_LABEL_CLASS = "toolpath-measure-label";
+/** What a label is, for a stylesheet to tell them apart. */
+type MeasureLabelKind = 'distance' | 'angle' | 'delta' | 'live';
+interface MeasureToolProps {
+    /**
+     * What a click sequence measures. `distance` takes two points; `angle` takes
+     * three — one arm's end, the vertex, the other arm's end. Changing it drops
+     * any points already placed.
+     */
+    mode?: MeasureMode;
+    /**
+     * The measurements on screen. Pass it to own them; omit it and the tool keeps
+     * its own list, which `onChange` still reports.
+     */
+    measurements?: readonly Measurement[];
+    /** The list changed: a measurement finished, or Delete removed the last one. */
+    onChange?: (measurements: readonly Measurement[]) => void;
+    /**
+     * Whether a distance also shows its X, Y and Z parts, as dashed legs in the
+     * axis colours with their own labels. On by default; a distance that already
+     * runs along an axis shows none either way.
+     */
+    showDeltas?: boolean;
+    /**
+     * Writes a length. Millimetres to two places unless told otherwise — the part
+     * is in millimetres, and converting is the consumer's call.
+     */
+    format?: (mm: number) => string;
+    /**
+     * Added to every label's `className`, beside {@link MEASURE_LABEL_CLASS} —
+     * a Tailwind utility list, or a CSS module's class.
+     */
+    labelClassName?: string;
+    theme?: Partial<ViewerTheme>;
+}
+/**
+ * Measure the part from inside the viewport. Mount it beside `<PartMesh>`.
+ *
+ * The pointer snaps to what is under it — a corner first, then an edge's
+ * midpoint, then the edge, then the face — and a marker shows where the click
+ * will land. A distance is two clicks and an angle three; the line follows the
+ * pointer between them with a live readout. Finished measurements stay up,
+ * drawn over the part with a label each, until Delete removes the last one or
+ * the tool is unmounted. Escape drops the points of one in progress. Holding
+ * Shift holds the next point to the X, Y or Z line through the last one — the
+ * axis the pointer is furthest along — so a length along an edge is measured
+ * along the edge and not a little across it.
+ *
+ * Nothing needs wiring. While it is mounted the part reports no hovers or
+ * picks — a click that places a point is not a click that selects a face — and
+ * unmounting it hands the pointer back. It snaps to the edges the part draws,
+ * which are the boundaries between analytic surfaces rather than the mesh's
+ * triangles, so a corner is a corner of the part and not of a facet.
+ *
+ * Lines are drawn at a width in pixels, through drei's `Line`, because a
+ * WebGL line is one pixel wide whatever is asked of it and one pixel of blue
+ * over a white face is not a measurement anybody can see.
+ *
+ * Labels are DOM elements laid over the canvas, so they are text a test can
+ * read — and they are **unstyled**. This is a headless component: what a
+ * label looks like is the consumer's stylesheet's, through
+ * {@link MEASURE_LABEL_CLASS} and the data attributes on each one. The one
+ * thing set here is that the element each label is wrapped in takes no
+ * pointer events, because a label over the part that took the click meant
+ * for the face under it would be a bug rather than a look.
+ */
+declare const MeasureTool: ({ mode, measurements, onChange, showDeltas, format, labelClassName, theme, }: MeasureToolProps) => react.JSX.Element | null;
+
+/**
+ * The cut a viewer holds for itself, when nobody else is holding it.
+ *
+ * `<PartMesh section>` is the controlled path and is untouched by this. The
+ * store exists for the other one: `<SectionTool>` mounted beside the part with
+ * no wiring at all. The two are siblings and cannot see each other, so the
+ * viewer keeps one of these and each reads or writes it — the tool sets the
+ * cut, the part clips to it and moves it when the handle is dragged.
+ *
+ * It also carries whether a tool is **engaged** — mounted at all. While one
+ * is, the pointer over the part belongs to it: the part reports no hovers or
+ * picks, so clicking a face to cut through it does not also select it, the
+ * hover paint does not sit under the tool's own preview, and a cut part is
+ * read as a cut rather than picked at. Unmounting the tool hands the pointer
+ * back. `<MeasureTool>` engages it too — a click that puts a measurement point
+ * on a face is not a request to select the face — which is why the flag is a
+ * count rather than a boolean: two tools up at once let go one at a time.
+ *
+ * A subscription rather than React state, so a drag re-renders the two
+ * subscribers and not everything under the canvas.
+ */
+interface SectionStore {
+    get(): SectionOptions | null;
+    set(next: SectionOptions | null): void;
+    /** Whether a tool is mounted, and the part should stay out of the way. */
+    isEngaged(): boolean;
+    /** Counted: a tool engages on mount and disengages on unmount, and the part waits for the last. */
+    setEngaged(engaged: boolean): void;
+    /** Notified on every change to either the cut or the engaged flag. */
+    subscribe(listener: () => void): () => void;
+}
+declare function createSectionStore(): SectionStore;
+
+type CapUniforms = {
+    uMask: {
+        value: Texture | null;
+    };
+    uResolution: {
+        value: Vector2;
+    };
+    uFill: {
+        value: Color;
+    };
+    uHatch: {
+        value: Color;
+    };
+    uOutline: {
+        value: Color;
+    };
+    uPitch: {
+        value: number;
+    };
+    uLine: {
+        value: number;
+    };
+    uThickness: {
+        value: number;
+    };
+};
+type CapMaterial = ShaderMaterial & {
+    uniforms: CapUniforms;
+};
+/**
+ * The render target the mask is drawn into. Sized later, to the drawing
+ * buffer, because that is what `gl_FragCoord` is measured in and a mask at
+ * any other size would put the outline beside the edge rather than on it.
+ */
+declare function createMaskTarget(): WebGLRenderTarget;
+/**
+ * The cap's own material, filled only where the main pass's stencil says the
+ * plane is inside material. Unthemed until {@link applyCapTheme} is called.
+ */
+declare function createCapMaterial(mask: Texture): CapMaterial;
+/** Re-themes a cap in place, and re-scales its hatch for the device pixel ratio. */
+declare function applyCapTheme(material: CapMaterial, theme: ViewerTheme, dpr: number): void;
+/**
+ * The two materials of the stencil pass: back faces count up, front faces
+ * count down, and what is left non-zero is where the plane is inside solid
+ * material. Nothing is written but the stencil.
+ */
+declare function createStencilMaterials(clip: Plane[]): [MeshBasicMaterial, MeshBasicMaterial];
+/** The quad the mask pass draws where the stencil is set — white on black. */
+declare function createMaskMaterial(): MeshBasicMaterial;
+
+interface ArrowPlacement {
+    /** Where the arrow's tip sits: outside the box, on the direction's ray. */
+    readonly tip: Vector3;
+    readonly length: number;
+}
+/**
+ * Where an arrow for `direction` sits relative to the part.
+ *
+ * The exit distance is the smallest `halfExtent / |component|` over the axes the
+ * direction actually moves along — the first face of the box the ray leaves
+ * through. That formulation is what makes this work for **arbitrary unit
+ * vectors** rather than only for axes: real reports carry tilted directions,
+ * one of them a 36° five-axis setup, and an axis-aligned simplification would
+ * bury those arrows inside the part.
+ */
+declare function arrowPlacement(direction: Vec3, box: Box3): ArrowPlacement;
+
+/**
+ * The bounds of the part, for the overlays that have to be sized against it.
+ *
+ * Measured on a frame rather than in an effect, because a Suspense-loaded mesh
+ * does not exist yet when the effects around it run — the same reason the
+ * viewer's opening frame waits. Measured once: an overlay that re-fitted itself
+ * while the part was being orbited would be a grid that breathes.
+ *
+ * Scene furniture is excluded, so the grid and the axes do not size each other.
+ */
+declare function useContentBox(): Box3;
+
+/**
+ * Telling a click apart from the end of a drag.
+ *
+ * The browser calls both a click: press, move, release over the same element
+ * fires `click` however far the pointer travelled in between. In a viewport
+ * that is the difference between "select this face" and "I have finished
+ * orbiting" — and the part is one mesh, so releasing over a different face is
+ * still the same element and still a click.
+ *
+ * Left unguarded, every orbit that happens to end over the part selects
+ * whatever it ended on, throwing away the selection the orbit was made to look
+ * at.
+ */
+/** How far a pointer may travel and still be a click, in CSS pixels. */
+declare const TAP_SLOP = 4;
+interface TapPoint {
+    readonly clientX: number;
+    readonly clientY: number;
+}
+/** Whether the pointer travelled far enough for this to be a drag. */
+declare function movedFar(from: TapPoint, to: TapPoint, slop?: number): boolean;
+interface TapTracker {
+    /** Whether the gesture ending at this event was a click rather than a drag. */
+    isTap(event: TapPoint): boolean;
+    dispose(): void;
+}
+/**
+ * Watches an element for the start of every gesture, so its end can be judged.
+ *
+ * Listens in the capture phase: whatever else handles the press — the camera
+ * controls, a drag handle — the start of the gesture still has to be recorded,
+ * and a listener that runs after `stopPropagation` runs never.
+ */
+declare function trackTaps(element: HTMLElement): TapTracker;
+/**
+ * How long between two presses still reads as one gesture, in milliseconds.
+ *
+ * The browser's own `dblclick` threshold is a platform setting and is not
+ * readable from script, so a hand-paired gesture has to pick a number. 400ms is
+ * inside every default and outside a deliberate pair of separate clicks.
+ */
+declare const DOUBLE_TAP_MS = 400;
+interface DoubleTapPoint extends TapPoint {
+    readonly timeStamp: number;
+}
+interface DoubleTapTracker {
+    /** Whether this press completes a double tap begun by the last one. */
+    isDouble(event: DoubleTapPoint): boolean;
+    /**
+     * Forgets the press being waited on, so the next one starts a fresh pair.
+     *
+     * For the caller that knows the gesture was interrupted by something this
+     * has no way to see — the pointer leaving the thing being clicked, most of
+     * all. Two presses either side of a trip to a panel are two clicks that
+     * happen to be quick, however close together the clock puts them.
+     */
+    reset(): void;
+}
+/**
+ * Pairing presses into a double tap by hand.
+ *
+ * Needed because `dblclick` fires for the **primary button only** — there is no
+ * such event for the middle button, however many times it is pressed. So a
+ * middle-button gesture has to be assembled from single presses.
+ *
+ * Position matters as well as time: two presses at opposite corners inside the
+ * window are two clicks that happened to be quick, not one gesture, and
+ * treating them as a double would re-frame the view out from under somebody
+ * who was doing something else. The same {@link TAP_SLOP} the click guard uses.
+ *
+ * A completed double clears the state rather than leaving it, so three presses
+ * are one double and one single rather than two overlapping doubles.
+ *
+ * Time and position are all this can judge on, which is not enough on its own:
+ * clicking a face, pressing something in a panel and clicking the same face
+ * again is three gestures the clock cannot tell from two, and it is quick
+ * enough to land inside the window. {@link DoubleTapTracker.reset} is how the
+ * caller says the pair was broken by something it could see and this could not.
+ */
+declare function trackDoubleTaps(within?: number, slop?: number): DoubleTapTracker;
+
+/** Whether the gesture ending at this event was a click rather than a drag. */
+type TapGuard = (event: TapPoint) => boolean;
+/**
+ * A click that is a click, for anything inside the canvas.
+ *
+ * Bound to the canvas element rather than to the object, because the gesture
+ * being judged started before any object knew about it.
+ *
+ * Under a `<Viewer>` this returns the tracker the scene already owns and
+ * attaches nothing. Called outside one — it is exported, so a consumer may use
+ * it in a scene of their own — it owns a tracker of its own instead. The effect
+ * is what differs, not the hooks: they run in the same order either way.
+ */
+declare function useTapGuard(): TapGuard;
+
+interface GridSpec {
+    /** Cell size in part units (millimetres). */
+    readonly step: number;
+    /** Half-width of the grid, so it spans `2 × extent`. */
+    readonly extent: number;
+    /** The plane the grid sits on: the bottom of the part, snapped to a step. */
+    readonly z: number;
+    readonly center: Vector3;
+}
+/**
+ * Sizes a ground grid for a part.
+ *
+ * The step comes from a 1-2-5 progression rather than a fixed size, so the same
+ * code reads sensibly for a 12 mm insert and a 900 mm plate — the Engine emits
+ * millimetres but says nothing about scale.
+ *
+ * The plane is the *bottom* of the part, not `z = 0`: parts usually sit on
+ * `z = 0` and then the two agree, but one modelled about its centre would
+ * otherwise be sliced in half by its own grid.
+ *
+ * **Give this a measured box.** The plane is `box.min.z`, which is `+Infinity`
+ * for an empty one. Nothing else in the spec shows it — `getSize` and
+ * `getCenter` both short-circuit to zero for an empty `Box3` — so the step and
+ * the extent come back looking ordinary and {@link gridGeometry} then builds
+ * every vertex on a plane at infinity, which three.js reports as "Computed
+ * radius is NaN" once per mount.
+ *
+ * `useContentBox` hands back an empty box until the scene has been
+ * measured, so a caller pairing the two wants `if (box.isEmpty()) return null`
+ * ahead of this. That is what the package's own `Grid` does, and it is why it
+ * draws nothing on the opening frame rather than a grid nobody asked for.
+ */
+declare function gridSpec(box: Box3): GridSpec;
+/**
+ * A ground grid on the part's Z-up base plane.
+ *
+ * Built directly rather than with `GridHelper`, which lays out on XZ for a Y-up
+ * world and has to be rotated into place — the Engine is Z-up, and a rotated
+ * helper is a thing to remember rather than a thing that is true.
+ */
+declare function gridGeometry(spec: GridSpec): BufferGeometry;
+
+/**
+ * The lines between regions, and nothing else.
+ *
+ * `EdgesGeometry` draws an edge wherever two facets meet at more than some
+ * angle, which is a guess standing in for "is this a real edge". On a machined
+ * part the guess is wrong in both directions: a small bore tessellated into
+ * twelve facets has 30° between them and gets drawn as a nut, while a shallow
+ * chamfer meeting a wall at 12° gets no line at all.
+ *
+ * The report already knows. A region is one analytic surface, so an edge inside
+ * one is tessellation and an edge between two is a real boundary — the same
+ * fact that makes region-aware shading possible, used for the other half of
+ * what makes a part read as a part.
+ *
+ * With one qualification. The Engine splits a surface where that makes a better
+ * machining plan, and those splits are boundaries between regions without being
+ * edges of the part: a floor cut in two to be reached from two directions is
+ * still one face to look at. So the walk is over *visual surfaces* — regions
+ * grouped by the kernel's exact `splitOrigin` lineage — and a split leaves no
+ * line. Nothing about picking or features goes through that grouping.
+ *
+ * The mesh must be non-indexed, which `parsePartGeometry` guarantees.
+ */
+declare function regionEdgesGeometry(geometry: BufferGeometry, model: Pick<PartModel, 'regions' | 'regionIndex'>): BufferGeometry;
+
+/** Region index → the visual surface it belongs to. */
+type SurfaceOf = ReadonlyMap<number, number>;
+/**
+ * The visual surface of each post-split region.
+ *
+ * The kernel divides B-rep faces to make machining relationships unambiguous.
+ * Those divisions remain meaningful to feature extraction and picking, but
+ * they are not physical edges. `splitOrigin` is the kernel's exact lineage
+ * relation: equal values mean the regions were one face before that analysis
+ * split. It is therefore the single grouping used for rendering, rather than
+ * attempting to infer continuations from mesh normals or surface kinds.
+ */
+declare function visualSurfaces(regions: readonly PartModelRegion[]): SurfaceOf;
+
 /**
  * Mouse and trackpad presets.
  *
@@ -705,12 +1120,26 @@ interface ViewerControls {
      * see a wall and then asks to zoom to it wants it closer, not re-oriented.
      */
     frameBox(box: Box3): void;
+    /**
+     * Sets or clears the cut the viewer holds for itself — the one `<SectionTool>`
+     * places and `<PartMesh>` follows when it is given no `section` of its own.
+     *
+     * `null` clears it. A `<PartMesh section>` is not affected: that cut is the
+     * consumer's, and this one is the viewer's.
+     */
+    setSection(options: SectionOptions | null): void;
 }
 interface ViewerHandle extends ViewerControls {
 }
 type VectorLike = Pick<Vector3, 'x' | 'y' | 'z'>;
 
 declare const useViewerControls: () => ViewerControls;
+/**
+ * The cut this viewer holds for itself. See `render/section-store.ts` for why
+ * it is a store: `<SectionTool>` writes it and `<PartMesh>` reads it, and the
+ * two are siblings.
+ */
+declare const useSectionStore: () => SectionStore;
 /** Re-aims the orbit, or `null` when this viewer has the gesture turned off. */
 type Retarget = ((point: VectorLike) => void) | null;
 /**
@@ -1081,4 +1510,4 @@ declare const ORBIT_TARGET_FADE_MS = 1000;
  */
 declare function orbitTargetOpacity(sinceHold: number, fade?: number): number;
 
-export { type ArrowPlacement, Axes, type AxesProps, CAD_CAMERA_UP, CHAMFER, CadCameraControls, type CadCameraControlsProps, type CameraLimits, type ControlScheme, type CubeZone, DEFAULT_FIT_MARGIN, DOUBLE_TAP_MS, DirectionArrows, type DirectionArrowsProps, type DirectionGroup, type DoubleTapPoint, type DoubleTapTracker, EXCLUDE_FROM_FRAME, ExtendedCameraControls, type ExtendedCameraControlsOptions, FEATURE_TYPE_RANKS, FeatureTag, FeatureType, Grid, type GridProps, type GridSpec, MAX_FRAME_RATIO, MIN_FRAME_RATIO, type NamedDirection, ORBIT_TARGET_COLOR, ORBIT_TARGET_FADE_MS, ORBIT_TARGET_FLASH_MS, ORBIT_TARGET_PIXELS, ORBIT_TARGET_RING_COLOR, ORBIT_TARGET_RING_OPACITY, ORBIT_TARGET_RING_PIXELS, ORBIT_TARGET_RING_WIDTH, PERSPECTIVE_FOV, PartModel, PartModelFeature, PartModelRegion, PartReportFormatError, type Projection, type RankingContext, RegionIndex, type Retarget, type RetargetPose, type SceneBounds, type SurfaceOf, TAP_SLOP, type TapPoint, type TapTracker, TriangleRange, UnsupportedKernelVersionError, VIEW_NAMES, VIEW_SIGNS, Vec3, ViewCube, type ViewCubeProps, type ViewKind, type ViewName, Viewer, type ViewerCamera, type ViewerControls, type ViewerHandle, type ViewerProps, ViewerTheme, type ViewerView, type ViewportSize, adaptedUp, applyProjection, arrowPlacement, aspectRatio, bestOwner, boundsFromBox, buildRegionIndex, cadViewDirections, cameraLimits, contentBounds, cubeOutlineGeometry, cubeZones, currentViewDirection, cycleOwner, defaultBounds, directionIndexOf, directionLabel, featureTypeRank, fitDistance, gridGeometry, gridSpec, groupByDirection, labelGeometry, labelTexture, movedFar, orbitTargetOpacity, orthographicHalfHeight, panelGeometry, perspectiveFitDistance, rankOwners, regionAdjacency, regionEdgesGeometry, regionNormals, retargetPose, sameDirection, screenLength, squaredUp, startPosition, targetBoundary, trackDoubleTaps, trackTaps, useContentBox, useRetarget, useTapGuard, useViewerControls, viewKind, viewUp, viewVector, visualSurfaces };
+export { ANGLE_ARC_FRACTION, ANGLE_ARC_SEGMENTS, AXIS_COLORS, type AngleMeasurement, type ArrowPlacement, Axes, type AxesProps, type Axis, type AxisLock, CAD_CAMERA_UP, CHAMFER, CadCameraControls, type CadCameraControlsProps, type CameraLimits, type CapMaterial, type CapUniforms, type ControlScheme, type CubeZone, DEFAULT_FIT_MARGIN, DELTA_DASH_PIXELS, DOUBLE_TAP_MS, type DeltaLeg, DirectionArrows, type DirectionArrowsProps, type DirectionGroup, type DistanceMeasurement, type DoubleTapPoint, type DoubleTapTracker, EXCLUDE_FROM_FRAME, ExtendedCameraControls, type ExtendedCameraControlsOptions, FEATURE_TYPE_RANKS, FeatureTag, FeatureType, Grid, type GridProps, type GridSpec, MAX_FRAME_RATIO, MEASURE_LABEL_CLASS, MEASURE_LINE_PIXELS, MEASURE_MARKER_PIXELS, MEASURE_RENDER_ORDER, MIN_FRAME_RATIO, type MeasureLabelKind, type MeasureMode, MeasureTool, type MeasureToolProps, type Measurement, type NamedDirection, ORBIT_TARGET_COLOR, ORBIT_TARGET_FADE_MS, ORBIT_TARGET_FLASH_MS, ORBIT_TARGET_PIXELS, ORBIT_TARGET_RING_COLOR, ORBIT_TARGET_RING_OPACITY, ORBIT_TARGET_RING_PIXELS, ORBIT_TARGET_RING_WIDTH, PERSPECTIVE_FOV, POINTS_PER_MEASUREMENT, PartModel, PartModelFeature, PartModelRegion, PartReportFormatError, type Projection, type RankingContext, RegionIndex, type Retarget, type RetargetPose, SNAP_MARKER_PIXELS, SNAP_PIXELS, type SceneBounds, SectionOptions, SectionState, type SectionStore, SectionTool, type SectionToolProps, SectionView, type Snap, type SnapEdges, type SnapHit, type SnapKind, type SurfaceOf, TAP_SLOP, type TapPoint, type TapTracker, TriangleRange, UnsupportedKernelVersionError, VIEW_NAMES, VIEW_SIGNS, Vec3, ViewCube, type ViewCubeProps, type ViewKind, type ViewName, Viewer, type ViewerCamera, type ViewerControls, type ViewerHandle, type ViewerProps, ViewerTheme, type ViewerView, type ViewportSize, adaptedUp, angleArc, angleArcRadius, angleAt, applyCapTheme, applyProjection, arrowPlacement, aspectRatio, bestOwner, boundsFromBox, buildRegionIndex, cadViewDirections, cameraLimits, contentBounds, createCapMaterial, createMaskMaterial, createMaskTarget, createSectionStore, createStencilMaterials, cubeOutlineGeometry, cubeZones, currentViewDirection, cycleOwner, defaultBounds, deltaBetween, deltaLegs, directionIndexOf, directionLabel, distanceBetween, excludedFromFrame, featureTypeRank, fitDistance, formatDegrees, formatMillimetres, gridGeometry, gridSpec, groupByDirection, labelGeometry, labelTexture, lockToAxis, measurementFromPoints, measurementLabel, measurementLabelAnchor, midpoint, movedFar, nextMeasurementId, orbitTargetOpacity, orthographicHalfHeight, panelGeometry, perspectiveFitDistance, rankOwners, regionAdjacency, regionEdgesGeometry, regionNormals, resolveSectionPlane, retargetPose, sameDirection, screenLength, screenPoint, snapAt, squaredUp, startPosition, targetBoundary, trackDoubleTaps, trackTaps, useContentBox, useRetarget, useSectionStore, useTapGuard, useViewerControls, viewKind, viewUp, viewVector, visualSurfaces };