@toolpath/viewer 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,637 @@
+import { V as Vec3, d as ViewerTheme, P as PartModel, e as PartModelRegion, f as ViewerCamera, g as ViewerView, h as Projection, T as TriangleRange, F as FeatureTag, R as RegionIndex, i as PartModelFeature, j as FeatureType } from './normalize-B0HBvzGu.js';
+export { B as BuildPickInput, C as CAD_CAMERA_UP, k as CANDIDATE_WEIGHT, D as DEFAULT_FIT_MARGIN, l as DEFAULT_THEME, m as DIRECTION_COLORS, o as EXCLUDE_FROM_FRAME, 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, N as NO_MODIFIERS, v as PERSPECTIVE_FOV, w as PICKED_SURFACE_LABEL, x as PartMesh, y as PartMeshProps, a as PartMeshRefs, z as PartObject, A as PartPick, G as PickModifiers, I as REGION_ATTRIBUTE, J as RegionHighlight, L as RegionPaint, S as SECTION_RENDER_ORDER, O as SceneBounds, Q as SectionAnchor, U as SectionBounds, W as SectionOptions, X as SectionPlacement, Y as SectionState, Z as SectionView, _ as ViewportSize, $ as applyHighlightLayers, a0 as applyProjection, a1 as aspectRatio, a2 as boundsFromBox, a3 as buildPick, a4 as buildRegionAttribute, a5 as buildRegionTexels, a6 as cadViewDirections, a7 as contentBounds, a8 as createPart, a9 as currentViewDirection, aa as defaultBounds, ab as directionColor, ac as dragPlane, ad as fitDistance, ae as focusForPick, n as normalizePartReport, af as orthographicHalfHeight, ag as perspectiveFitDistance, ah as pickedStartDepth, ai as resolveSectionPlane, aj as resolveTheme, ak as screenLength, al as sectionBounds, am as sectionConstant, an as sectionDepth, ao as sectionDepthConstant, ap as sectionDepthRange, aq as sectionFromPick, ar as sectionOffset, as as sectionPlane, s as smoothRegionNormals, at as startPosition, au as themesEqual, av as viewDirection } from './normalize-B0HBvzGu.js';
+import * as react from 'react';
+import { RefObject, ReactNode, CSSProperties } from 'react';
+import { BufferGeometry, CanvasTexture, Vector3, Box3 } from 'three';
+import CameraControls from 'camera-controls';
+
+/**
+ * The 26 standard views: the six faces of the cube, the twelve edges between
+ * them, and its eight corners.
+ *
+ * Ordered top/bottom, then front/back, then left/right, all the way through, so
+ * a caller has a rule to rely on.
+ */
+declare const VIEW_NAMES: readonly ["top", "bottom", "front", "back", "left", "right", "top-front", "top-back", "top-left", "top-right", "bottom-front", "bottom-back", "bottom-left", "bottom-right", "front-left", "front-right", "back-left", "back-right", "top-front-left", "top-front-right", "top-back-left", "top-back-right", "bottom-front-left", "bottom-front-right", "bottom-back-left", "bottom-back-right"];
+type ViewName = (typeof VIEW_NAMES)[number];
+/** A face, one of the chamfers between two faces, or a corner chamfer. */
+type ViewKind = 'face' | 'edge' | 'corner';
+/**
+ * Which way each view lies, as the sign of each axis in the Z-up frame the part
+ * data is authored in: **+Z is the top, −Y is the front, +X is the right**.
+ *
+ * Signs rather than unit vectors because these are numbers a reader can check.
+ * `top-front-left` is three components of ±1/√3 and nobody proofreads those.
+ */
+declare const VIEW_SIGNS: Record<ViewName, readonly [number, number, number]>;
+/** How many axes a view is off: one for a face, two for an edge, three for a corner. */
+declare function viewKind(name: ViewName): ViewKind;
+/** The unit direction the camera sits in for a view. */
+declare function viewVector(name: ViewName): Vec3;
+/**
+ * Which way is up when looking from `direction`.
+ *
+ * Z is up for every view except the two that look straight down it, where an up
+ * vector parallel to the view is degenerate and the camera would have no
+ * defined roll. Those get ±Y, so the top view puts the front edge at the bottom
+ * of the screen and the bottom view mirrors it — the convention every CAD
+ * package uses, and the one the cube's own face labels are drawn to, since both
+ * come from here.
+ */
+declare function viewUp(direction: Vec3): Vec3;
+/**
+ * Half-width of a face panel, where the cube's half-extent is 1 — so the
+ * chamfer taken off each edge is the remaining `1 - CHAMFER`.
+ */
+declare const CHAMFER = 0.5834;
+/** One clickable panel of the cube: a face, an edge chamfer, or a corner. */
+interface CubeZone {
+    readonly name: ViewName;
+    readonly kind: ViewKind;
+    /** The panel's outward normal, and the direction the camera moves to. */
+    readonly direction: Vec3;
+    /** Its polygon in cube space, wound counter-clockwise seen from outside. */
+    readonly polygon: readonly Vec3[];
+}
+/**
+ * The chamfered cube, one planar polygon per view — a square for each face, a
+ * rectangle for each edge, a triangle for each corner. Pure, and the only
+ * description of the cube's shape: the panels, the outline and the hit test are
+ * all built from what this returns.
+ */
+declare function cubeZones(chamfer?: number): CubeZone[];
+/** A zone's polygon as a flat, outward-facing triangle fan. */
+declare function panelGeometry(zone: CubeZone): BufferGeometry;
+/** The outline around every panel, as line segments. */
+declare function cubeOutlineGeometry(zones: readonly CubeZone[]): BufferGeometry;
+/**
+ * A face's name on a quad floating just proud of it.
+ *
+ * The quad is built from the face's own polygon in its stored order, which
+ * {@link cubeZones} lays out as (−right, −up), (+right, −up), (+right, +up),
+ * (−right, +up) — so mapping UVs onto it in that order puts the text the right
+ * way up for the camera pose {@link viewUp} chooses for the same view.
+ */
+declare function labelGeometry(zone: CubeZone): BufferGeometry;
+/** A face name, drawn on a transparent canvas and sized to fit. */
+declare function labelTexture(label: string, color: number): CanvasTexture;
+
+interface GridProps {
+    /** Cell size in millimetres. Sized from the scene when omitted. */
+    step?: number;
+    extent?: number;
+    color?: string | number;
+    opacity?: number;
+}
+/**
+ * A ground grid on the part's base plane, sized to the part.
+ *
+ * Measured from whatever else is in the scene rather than given a fixed size:
+ * the Engine emits millimetres but says nothing about scale, and a grid of
+ * 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;
+interface AxesProps {
+    size?: number;
+}
+declare const Axes: ({ size }: AxesProps) => react.JSX.Element;
+interface ViewCubeProps {
+    alignment?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    margin?: [number, number];
+    theme?: Partial<ViewerTheme>;
+    /** Called with the view a panel was clicked for, after the camera moves. */
+    onViewChange?: (view: ViewName) => void;
+}
+/**
+ * The orientation cube, in the corner of the viewport.
+ *
+ * Twenty-six clickable panels rather than six: the chamfers between faces are
+ * the edge and corner views, which is how you reach an isometric without
+ * dragging for it. A drei `GizmoViewport` gives three labelled axes and no
+ * views at all.
+ */
+declare const ViewCube: ({ alignment, margin, theme, onViewChange, }: ViewCubeProps) => react.JSX.Element;
+
+interface NamedDirection {
+    readonly direction: Vec3;
+    readonly color: number;
+    readonly index: number;
+}
+interface DirectionArrowsProps {
+    /**
+     * The ways up the part can be held — a report's `candidateDirections`.
+     *
+     * The directions rather than the report: an arrow is drawn from a unit vector
+     * and the part's bounds, and nothing else about a part is needed to place one.
+     */
+    directions: readonly Vec3[];
+    /**
+     * Shows one direction on its own. Choosing a direction is a way of asking
+     * about that direction, so the others leave rather than dimming: five faded
+     * arrows still cross the part, still hide surfaces behind them, and still
+     * read as choices when only one is being asked about.
+     */
+    activeDirection?: number | null;
+    /**
+     * Shows one direction's arrow without scoping anything, for "the feature
+     * being read came from this way". Falls back to `activeDirection`.
+     */
+    shownDirection?: number | null;
+    /**
+     * A direction being named, drawn while it is aimed. Not a candidate and not a
+     * selection: a way up that does not exist yet, so it is drawn over the part —
+     * an arrow being aimed that hides behind the geometry looks like it has
+     * stopped responding.
+     */
+    previewDirection?: Vec3 | null;
+    /**
+     * Ways up that are held but were never candidates. A direction somebody named
+     * is as real as one the Engine proposed, and without an arrow it is a row in a
+     * list describing an orientation nothing on the part shows.
+     */
+    namedDirections?: readonly NamedDirection[];
+    onPickDirection?: (index: number) => void;
+    theme?: Partial<ViewerTheme>;
+    visible?: boolean;
+}
+/**
+ * One arrow per candidate direction, pointing at the part.
+ *
+ * Aimed *inward* on purpose: a machining direction is the direction the tool
+ * comes from, so an arrow flying toward the surface reads as the setup rather
+ * than as a surface normal.
+ */
+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;
+}
+/**
+ * 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;
+
+/**
+ * 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.
+ */
+declare function useTapGuard(): (event: TapPoint) => boolean;
+
+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.
+ */
+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 flat floor. So the walk is over *visual surfaces* — regions grouped
+ * where they continue each other — and a split leaves no line. See
+ * `visualSurfaces`; nothing about picking or features goes through it.
+ *
+ * The mesh must be non-indexed, which `parsePartGeometry` guarantees.
+ */
+declare function regionEdgesGeometry(geometry: BufferGeometry, model: Pick<PartModel, 'regions' | 'regionIndex'>): BufferGeometry;
+
+/**
+ * Which regions are one surface to look at.
+ *
+ * The Engine splits a surface where that makes a better machining plan — a
+ * floor cut in two so each half can be reached from a different direction, say.
+ * Those splits are real and features depend on them, but they are not edges of
+ * the part: a plane divided in two is still flat, and drawing the join or
+ * shading across it makes a clean model look faceted and creased where nothing
+ * creases.
+ *
+ * So this groups regions that continue each other, and the grouping is used for
+ * the two things that are about how the part *looks* — its edges and its
+ * shading. Nothing about picking, highlighting or features goes through here:
+ * a split is still two regions to click on and still two regions a feature can
+ * own, which is the whole reason the Engine made it.
+ *
+ * Two regions continue each other when they meet along an edge, are both
+ * **planes**, and are flat to within a degree of one another — which for a
+ * plane means they are the same plane.
+ *
+ * Planes only, and that is a limit of what the report says rather than caution.
+ * A region carries an `idx`, a `shapeKind`, an area and a triangle range: there
+ * is nothing in it that says which analytic surface a region was cut from. On a
+ * flat face that does not matter, because two coplanar planes meeting along an
+ * edge *are* one plane and no part has an edge there. On a curved one it
+ * matters entirely: a fillet running tangentially into a shaft and a fillet
+ * split down the middle look identical from the facets alone, and guessing
+ * between them either rubs out a line the part has or leaves one it does not.
+ * A line the part has is the worse of the two to lose, so curved boundaries are
+ * all drawn.
+ *
+ * The exact version of this wants the Engine to say which surface a region came
+ * from. Until it does, this is the half that can be proved.
+ */
+/**
+ * How far two planes may disagree across a shared edge and still be one plane.
+ *
+ * A degree, which is a rounding error rather than a judgement: a split is
+ * exactly coplanar, and anything a part actually turns through is a chamfer at
+ * fifteen degrees or more.
+ */
+declare const CONTINUES_WITHIN: number;
+/** Region index → the surface it belongs to, by region `idx`. */
+type SurfaceOf = ReadonlyMap<number, number>;
+declare function visualSurfaces(geometry: BufferGeometry, regions: readonly PartModelRegion[]): SurfaceOf;
+
+/**
+ * Mouse and trackpad presets.
+ *
+ * - `toolpath` — left-drag orbits, right- and middle-drag pan. The product
+ *   default.
+ * - `fusion` — middle-drag and two-finger scroll pan, shift makes them orbit,
+ *   pinch zooms. Matches Fusion 360, which is what most of our users have open
+ *   in the other window.
+ */
+type ControlScheme = 'toolpath' | 'fusion';
+type ExtendedCameraControlsOptions = {
+    /**
+     * Orbit past the poles instead of stopping there. When enabled the up vector
+     * is re-derived from the view each frame, so there is no gimbal stop.
+     */
+    readonly freeOrbit?: boolean | undefined;
+};
+/**
+ * `CameraControls` with free orbit, camera-relative up, and the Fusion wheel
+ * scheme.
+ *
+ * Two departures from the legacy implementation, both deliberate:
+ *
+ * - It does **not** override `connect`/`disconnect`. Legacy declared them as
+ *   arrow-function class fields, which shadowed the base methods of the same
+ *   name — so `connect()` added a pointer listener but never did what the base
+ *   class's `connect` does, and the base's own connection came from the
+ *   constructor instead. The extra listeners live on `attach`/`detach` here,
+ *   and the base methods are left alone.
+ * - Modifier state is tracked internally. Legacy read Shift and Control from a
+ *   React hook and reapplied the whole preset on every keypress, which coupled
+ *   the controls to the component tree for two booleans.
+ */
+declare class ExtendedCameraControls extends CameraControls {
+    #private;
+    constructor(camera: ViewerCamera, domElement: HTMLElement, options?: ExtendedCameraControlsOptions);
+    get freeOrbit(): boolean;
+    get scheme(): ControlScheme;
+    /** Adds the listeners this subclass owns, on top of the base connection. */
+    attach(): void;
+    detach(): void;
+    dispose(): void;
+    /**
+     * Reapplies the current preset. The Viewer calls this after a projection
+     * change too, because the correct wheel action differs between an
+     * orthographic and a perspective camera.
+     */
+    applyScheme(scheme: ControlScheme): void;
+    setFreeOrbit(freeOrbit: boolean): void;
+    /** Returns the camera to Z-up, the orientation the part data is authored in. */
+    resetUpVector(): void;
+}
+
+interface CadCameraControlsProps {
+    /** Filled with the controls once they exist, for imperative framing. */
+    controlsRef: RefObject<ExtendedCameraControls | null>;
+    scheme?: ControlScheme;
+    /**
+     * Orbit past the poles instead of stopping there. On by default: a CAD view
+     * that sticks when it reaches straight-down is the single most-reported thing
+     * about an orbit control.
+     */
+    freeOrbit?: boolean;
+}
+/**
+ * Mounts `camera-controls` against the R3F camera and canvas.
+ *
+ * `frameloop="demand"` means no frame runs unless something asks for one, so
+ * the controls' own `control` and `update` events drive `invalidate` — without
+ * that the view would move only when React happened to render. The controls are
+ * also registered as R3F's default `controls`, which is how anything else in
+ * the scene reaches the orbit target.
+ */
+declare const CadCameraControls: ({ controlsRef, scheme, freeOrbit, }: CadCameraControlsProps) => null;
+
+interface ViewerControls {
+    /** Frames the part without changing the current viewing direction. */
+    fit(): void;
+    /** Returns to the opening view and frames the part. */
+    reset(): void;
+    setView(view: ViewerView): void;
+    /**
+     * Frames the part from an arbitrary direction — a unit vector from the part
+     * toward the camera.
+     *
+     * The named views are the six a keyboard shortcut reaches; the orientation
+     * cube offers twenty-six, and the twenty that are not axis-aligned have no
+     * names worth inventing.
+     */
+    setViewDirection(direction: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    /**
+     * Frames arbitrary bounds from the direction being looked from, for zooming
+     * to one feature rather than to the whole part.
+     *
+     * Keeps the viewing direction on purpose: somebody who has turned the part to
+     * see a wall and then asks to zoom to it wants it closer, not re-oriented.
+     */
+    frameBox(box: Box3): void;
+}
+interface ViewerHandle extends ViewerControls {
+}
+
+declare const useViewerControls: () => ViewerControls;
+interface ViewerProps {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Perspective by default. Orthographic is what a machinist reads a part in —
+     * parallel edges stay parallel, so two features the same size measure the
+     * same size wherever they sit.
+     */
+    projection?: Projection;
+    /**
+     * `toolpath` — left-drag orbits, right-drag pans. `fusion` — middle-drag and
+     * two-finger scroll pan, shift makes them orbit, pinch zooms; it matches
+     * Fusion 360, which is what most users have open in the other window.
+     */
+    controls?: ControlScheme;
+    /** Orbit past the poles instead of stopping there. On by default. */
+    freeOrbit?: boolean;
+    /** Lighting and background. The part's own colours are tuned against this rig. */
+    theme?: Partial<ViewerTheme>;
+    /**
+     * A click that hit nothing in the scene — not the part, not an arrow, not a
+     * section handle. The usual meaning is "put the selection down".
+     */
+    onPointerMissed?: () => void;
+}
+declare const Viewer: react.ForwardRefExoticComponent<ViewerProps & react.RefAttributes<ViewerHandle>>;
+
+/**
+ * A report that cannot be turned into a `PartModel`.
+ *
+ * Contract mismatches are caught at normalization rather than deep in the
+ * renderer. A region table that does not tile the mesh would otherwise surface
+ * as mysterious mis-picking — that is, as a *shader* bug — hours away from its
+ * cause.
+ */
+declare class PartReportFormatError extends Error {
+    readonly name = "PartReportFormatError";
+    /** Every problem found, not just the first. */
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+/**
+ * A report from a kernel older than the one this package targets.
+ *
+ * `0.2.0` identified features by a dense `featureIndex` and published no
+ * `regions[]`; `0.3.0` replaced that with an opaque `featureTag` and a region
+ * table. The two are mutually incompatible on feature identity, so this package
+ * targets one version and fails loudly rather than carrying a permanent
+ * compatibility shim.
+ */
+declare class UnsupportedKernelVersionError extends Error {
+    readonly name = "UnsupportedKernelVersionError";
+    readonly kernelVersion: string;
+    readonly minimumKernelVersion: string;
+    constructor(kernelVersion: string, minimumKernelVersion: string);
+}
+
+/** The minimum a region must expose to be indexed. */
+interface IndexableRegion {
+    readonly idx: number;
+    readonly triangles: TriangleRange;
+}
+/** The minimum a feature must expose to be indexed. */
+interface IndexableFeature {
+    readonly tag: FeatureTag;
+    readonly regionIdxs: readonly number[];
+}
+interface BuildRegionIndexInput {
+    readonly regions: readonly IndexableRegion[];
+    readonly features: readonly IndexableFeature[];
+    readonly triangleCount: number;
+}
+/**
+ * Builds the `feature ↔ region ↔ triangle` index, validating the region table
+ * on the way through.
+ *
+ * The index is three typed arrays plus two maps. Picking is a binary search
+ * over region starts — no per-triangle lookup table, no material per feature,
+ * and no allocation on the pointer-move path.
+ *
+ * Validation is deliberately strict and happens **once**, here. Regions are
+ * guaranteed to tile `[0, triangleCount)` completely, so a gap, an overlap, or
+ * a range past the end of the mesh means the report is broken or the report and
+ * the mesh do not belong together. Failing at load turns that into one clear
+ * error instead of a highlight landing on the wrong surface much later.
+ *
+ * Emission order is *not* validated — the regions are sorted defensively rather
+ * than trusting the order they arrived in. What must hold is that the sorted
+ * ranges tile the mesh.
+ */
+declare function buildRegionIndex(input: BuildRegionIndexInput): RegionIndex;
+
+interface DirectionGroup {
+    /**
+     * Position in `candidateDirections`, or `-1` for the group holding features
+     * whose direction is not among them — which no observed report produces, but
+     * which must not silently drop features if one ever does.
+     */
+    readonly index: number;
+    readonly direction: Vec3;
+    readonly features: readonly PartModelFeature[];
+}
+declare function sameDirection(a: Vec3, b: Vec3): boolean;
+/** The index of a direction in `candidateDirections`, or `-1`. */
+declare function directionIndexOf(model: Pick<PartModel, 'candidateDirections'>, direction: Vec3): number;
+/**
+ * Features by machining direction, in `candidateDirections` order.
+ *
+ * Every feature's `machiningDirection` is one of `candidateDirections` — zero
+ * exceptions across 1122 features on three parts — so the unmatched group is
+ * defensive rather than expected. Groups are returned even when empty, since a
+ * direction with no features is still a direction the part can be set up in.
+ */
+declare function groupByDirection(model: PartModel): readonly DirectionGroup[];
+/**
+ * A direction as a label: `+Z` when it is an axis, three decimals otherwise.
+ *
+ * Not every direction is axis-aligned — real parts report tilted ones, a 36°
+ * five-axis setup among them — so the general form is the fallback rather than
+ * an error case.
+ */
+declare function directionLabel(direction: Vec3): string;
+
+/**
+ * Which way each face points, taken off the mesh.
+ *
+ * The report says which triangles belong to a region and how big it is; it does
+ * not say which way it faces. That is in the geometry, and it is what any
+ * question of the form "could this be cut from over there" starts with.
+ *
+ * Area-weighted, so a region made of one large triangle and a sliver reads as
+ * the large one. A perfectly flat region gives its own normal exactly; a curved
+ * one gives an average, which is honest — a bore's wall does not point one way,
+ * and a single vector for it is a simplification whoever uses it should know
+ * about.
+ */
+declare function regionNormals(geometry: BufferGeometry, regions: readonly PartModelRegion[]): Map<number, Vec3>;
+
+/**
+ * Feature types from most specific to least, for resolving a viewport click.
+ *
+ * Nothing geometric can separate a region's owners — two `wall` features on the
+ * same physical face from different directions reference an *identical* region
+ * set, so they have identical area by construction. Specificity is the only
+ * ordering left, and it is a judgement about intent: a hole is what someone
+ * means when they click a hole's wall.
+ *
+ * `profile` ranks last, alone. It is a boundary contour rather than a machined
+ * surface, so it should never win a click against the surface it traces — and
+ * because every direction's profile overlaps most of that direction's regions,
+ * this one rule resolves every in-direction collision on the cube.
+ */
+declare const FEATURE_TYPE_RANKS: readonly (readonly FeatureType[])[];
+declare function featureTypeRank(type: FeatureType): number;
+interface RankingContext {
+    /**
+     * The active machining direction. Narrows a region's owners to two, one, or
+     * **none** — the empty case is real, and is reported as "nothing here in this
+     * direction" rather than as a pick that missed.
+     */
+    readonly activeDirection?: Vec3 | null;
+    /**
+     * A unit vector from the part toward the camera. The owner whose machining
+     * direction most nearly faces the viewer wins: looking down at the cube,
+     * `(0,0,1)` resolves to `+Z:face` rather than to a `±Y:wall` reading.
+     */
+    readonly viewDirection?: Vec3 | null;
+}
+/**
+ * Orders a region's owning features for the single-selection case.
+ *
+ * A *default*, never a claim of correctness — which is why it must never be the
+ * only way to reach a feature. Every hover and pick carries the full owner set
+ * alongside the ranked one, the panel can be scoped to the candidates, and
+ * repeated clicks cycle (see {@link cycleOwner}).
+ *
+ * With an active direction the result is **filtered**, not merely reordered: a
+ * region the direction cannot reach yields an empty list.
+ */
+declare function rankOwners(model: PartModel, owners: readonly FeatureTag[], context?: RankingContext): readonly FeatureTag[];
+/** The ranked pick, or `null` when the scope holds no owner at all. */
+declare function bestOwner(model: PartModel, owners: readonly FeatureTag[], context?: RankingContext): FeatureTag | null;
+/**
+ * The next owner after `current`, wrapping — the standard CAD escape hatch for
+ * an ambiguous click. `null` cycles in from the start; an owner that is not in
+ * the list restarts rather than dead-ends.
+ */
+declare function cycleOwner(owners: readonly FeatureTag[], current: FeatureTag | null): FeatureTag | null;
+
+export { type ArrowPlacement, Axes, type AxesProps, CHAMFER, CONTINUES_WITHIN, CadCameraControls, type CadCameraControlsProps, type ControlScheme, type CubeZone, DirectionArrows, type DirectionArrowsProps, type DirectionGroup, ExtendedCameraControls, type ExtendedCameraControlsOptions, FEATURE_TYPE_RANKS, FeatureTag, FeatureType, Grid, type GridProps, type GridSpec, type NamedDirection, PartModel, PartModelFeature, PartModelRegion, PartReportFormatError, Projection, type RankingContext, RegionIndex, type SurfaceOf, TAP_SLOP, type TapPoint, type TapTracker, TriangleRange, UnsupportedKernelVersionError, VIEW_NAMES, VIEW_SIGNS, Vec3, ViewCube, type ViewCubeProps, type ViewKind, type ViewName, Viewer, ViewerCamera, type ViewerControls, type ViewerHandle, type ViewerProps, ViewerTheme, ViewerView, arrowPlacement, bestOwner, buildRegionIndex, cubeOutlineGeometry, cubeZones, cycleOwner, directionIndexOf, directionLabel, featureTypeRank, gridGeometry, gridSpec, groupByDirection, labelGeometry, labelTexture, movedFar, panelGeometry, rankOwners, regionEdgesGeometry, regionNormals, sameDirection, trackTaps, useContentBox, useTapGuard, useViewerControls, viewKind, viewUp, viewVector, visualSurfaces };