@toolpath/viewer 0.3.1 → 1.0.0

package/dist/engine/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PartModel, a as PartMeshRefs } from '../normalize-Bzzwwxt4.js';
-export { E as EnginePart, b as EnginePartProps, M as MIN_KERNEL_VERSION, c as assertSupportedKernelVersion, n as normalizePartReport, s as smoothRegionNormals } from '../normalize-Bzzwwxt4.js';
+import { P as PartModel, a as PartMeshRefs } from '../normalize-DsoIyM8B.js';
+export { E as EnginePart, b as EnginePartProps, M as MIN_KERNEL_VERSION, c as assertSupportedKernelVersion, n as normalizePartReport, s as smoothRegionNormals } from '../normalize-DsoIyM8B.js';
 import { BufferGeometry } from 'three';
 import 'react';
 

package/dist/engine/index.js

@@ -12,7 +12,7 @@ import {
   parsePartGeometry,
   partMeshAssets,
   smoothRegionNormals
-} from "../chunk-RICG6UVH.js";
+} from "../chunk-4BU4QZCL.js";
 export {
   EnginePart,
   MIN_KERNEL_VERSION,

package/dist/index.d.ts

@@ -1,10 +1,18 @@
-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-Bzzwwxt4.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-Bzzwwxt4.js';
+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-DsoIyM8B.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, N as NO_MODIFIERS, o as PICKED_SURFACE_LABEL, p as PartMesh, q as PartMeshProps, a as PartMeshRefs, r as PartObject, t as PartPick, u as PickModifiers, v as REGION_ATTRIBUTE, w as RegionHighlight, x as RegionPaint, S as SECTION_RENDER_ORDER, y as SectionAnchor, z as SectionBounds, A as SectionOptions, G as SectionPlacement, I as SectionState, J as SectionView, L as applyHighlightLayers, O as buildPick, Q as buildRegionAttribute, U as buildRegionTexels, W as createPart, X as directionColor, Y as dragPlane, Z as focusForPick, n as normalizePartReport, _ as pickedStartDepth, $ as resolveSectionPlane, a0 as resolveTheme, a1 as sectionBounds, a2 as sectionConstant, a3 as sectionDepth, a4 as sectionDepthConstant, a5 as sectionDepthRange, a6 as sectionFromPick, a7 as sectionOffset, a8 as sectionPlane, s as smoothRegionNormals, a9 as themesEqual, aa as viewDirection } from './normalize-DsoIyM8B.js';
+import { BufferGeometry, CanvasTexture, Vector3, Box3, OrthographicCamera, PerspectiveCamera, Object3D } from 'three';
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties } from 'react';
-import { BufferGeometry, CanvasTexture, Vector3, Box3 } from 'three';
 import CameraControls from 'camera-controls';
 
+/**
+ * Every face's neighbours, keyed by region index.
+ *
+ * One pass over the triangles: each contributes three edges, each edge names
+ * the region that owns it, and any edge named by two regions joins them.
+ */
+declare function regionAdjacency(model: PartModel, geometry: BufferGeometry): Map<number, Set<number>>;
+
 /**
  * The 26 standard views: the six faces of the cube, the twelve edges between
  * them, and its eight corners.
@@ -39,6 +47,21 @@ declare function viewVector(name: ViewName): Vec3;
  * come from here.
  */
 declare function viewUp(direction: Vec3): Vec3;
+/**
+ * The squared up vector nearest to the one the camera already has.
+ *
+ * A view has four square orientations, not one: {@link viewUp} rolled by 0°,
+ * 90°, 180° and 270° about the view direction. Snapping to the canonical one
+ * would spin the part on the way to a view somebody asked for because it was
+ * already nearly in front of them — arrive at the bottom view from the right
+ * and the part turns a quarter of a turn for no reason they can see.
+ *
+ * So the roll is chosen, not imposed: of the four, the one closest to where the
+ * camera is looking from now. The view still lands square — Bottom simply lands
+ * square in whichever of its four ways was already nearest, which is how the
+ * Fusion cube behaves and what somebody arriving from it will expect.
+ */
+declare function squaredUp(direction: Vec3, currentUp: 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`.
@@ -134,10 +157,15 @@ interface DirectionArrowsProps {
      */
     activeDirection?: number | null;
     /**
-     * Shows one direction's arrow without scoping anything, for "the feature
-     * being read came from this way". Falls back to `activeDirection`.
+     * Which arrows are drawn, without scoping anything: `null` for all of them,
+     * an index for one, `-1` for none — and **a list of indices for a set**, which
+     * is how a plan draws only the ways up it has confirmed.
+     *
+     * One prop rather than a singular and a plural, because two would need a rule
+     * about which wins, and a caller with an answer to give should not also have
+     * to say where to put it. Falls back to `activeDirection`.
      */
-    shownDirection?: number | null;
+    shownDirection?: number | readonly 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 —
@@ -227,14 +255,67 @@ interface TapTracker {
  * 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(): (event: TapPoint) => boolean;
+declare function useTapGuard(): TapGuard;
 
 interface GridSpec {
     /** Cell size in part units (millimetres). */
@@ -305,6 +386,200 @@ type SurfaceOf = ReadonlyMap<number, number>;
  */
 declare function visualSurfaces(regions: readonly PartModelRegion[]): SurfaceOf;
 
+type Projection = 'orthographic' | 'perspective';
+type ViewerCamera = OrthographicCamera | PerspectiveCamera;
+interface ViewportSize {
+    readonly width: number;
+    readonly height: number;
+}
+/** Vertical field of view, in degrees, for the perspective camera. */
+declare const PERSPECTIVE_FOV = 30;
+/** Padding around the framed bounds, as a multiple of its radius. */
+declare const DEFAULT_FIT_MARGIN = 1.2;
+/** Marks scene furniture — grid, axes — that the camera should not frame. */
+declare const EXCLUDE_FROM_FRAME = "viewerExcludeFromFrame";
+/**
+ * What the camera frames: a bounding *sphere*, not a box.
+ *
+ * A sphere makes framing rotation-invariant — the part stays fully visible from
+ * every angle, and a resize never needs to know the current pose. Framing
+ * per-axis box dimensions instead means recomputing the camera distance on
+ * every resize, and still clipping on some orientations.
+ */
+interface SceneBounds {
+    readonly center: Vector3;
+    readonly radius: number;
+}
+/**
+ * Bounds for a scene with nothing in it. A viewer is mounted before it has a
+ * part, and a camera with a zero-size frustum renders nothing at all.
+ */
+declare function defaultBounds(): SceneBounds;
+/**
+ * A container can be laid out at zero size, and a degenerate aspect ratio
+ * produces a `NaN` projection matrix that never recovers. Fall back to square.
+ */
+declare function aspectRatio(size: ViewportSize): number;
+/**
+ * A world length that covers `pixels` on screen at `point`.
+ *
+ * Anything sized in world units is a thumbnail on a plate and a wall on an
+ * insert; the whole reason a control is measured this way is that it is a
+ * control rather than part of the model. The section handle and the orbit
+ * target marker both size themselves with it, which is why it lives here with
+ * the camera rather than beside either of them.
+ *
+ * The two projections answer differently on purpose. An orthographic frustum
+ * covers the same world height wherever the point is, so distance does not
+ * enter; a perspective one covers more the further away it looks, so it does.
+ */
+declare function screenLength(camera: ViewerCamera, point: Vector3, viewport: ViewportSize, pixels: number): number;
+declare function boundsFromBox(box: Box3): SceneBounds;
+/**
+ * The bounds of everything worth framing under `root`.
+ *
+ * Skips objects flagged with {@link EXCLUDE_FROM_FRAME} and their descendants:
+ * a 100 mm grid around a 6 mm part would otherwise frame the grid, and the part
+ * would be a speck.
+ */
+declare function contentBounds(root: Object3D, into: Box3): SceneBounds;
+/**
+ * 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
+ * frames on width and a landscape one on height.
+ */
+declare function perspectiveFitDistance(fovDegrees: number, aspect: number, radius: number): number;
+/**
+ * Half-height of an orthographic frustum that fits a sphere of `radius`. A
+ * portrait viewport grows the height so the width still clears the sphere.
+ */
+declare function orthographicHalfHeight(aspect: number, radius: number): number;
+declare function fitDistance(projection: Projection, size: ViewportSize, bounds: SceneBounds, margin?: number): number;
+declare function startPosition(projection: Projection, size: ViewportSize, bounds: SceneBounds, margin?: number): Vector3;
+/**
+ * How far out the wheel may pull, as a fraction of the fitted framing: the part
+ * may shrink to a quarter of the view and no further. Past that it is a speck
+ * with no cue that Fit is the way back.
+ */
+declare const MIN_FRAME_RATIO = 0.25;
+/**
+ * How far in the wheel may push, as a multiple of the fitted framing.
+ *
+ * Both ratios are the legacy viewer's `minZoom` 0.25 / `maxZoom` 10
+ * (`three-object.tsx:289-311`), which transfer almost exactly: legacy's
+ * orthographic frustum was `largestDimension * 2` tall and this one is the
+ * fitted bounding sphere, which for a cube agree within a few percent. So the
+ * numbers are the ones that shipped, and here they carry a meaning they did not
+ * have there — `zoom` 1 *is* the fitted framing, so 0.25 and 10 say exactly
+ * what a reader thinks they say.
+ */
+declare const MAX_FRAME_RATIO = 10;
+/** How far the camera may travel, in the two units the two cameras travel in. */
+interface CameraLimits {
+    readonly minZoom: number;
+    readonly maxZoom: number;
+    readonly minDistance: number;
+    readonly maxDistance: number;
+}
+/**
+ * The clamps for a scene, so the wheel cannot leave the viewport empty.
+ *
+ * Without them it can, from either end, and both cameras can do it: an
+ * orthographic `camera.zoom` reaches 1e30 in sixty notches, and a perspective
+ * camera dives inside the part in eight, because `minDistance` defaults to
+ * `Number.EPSILON`. Fit recovers from both — but Fit is a double middle click
+ * and nothing on screen says so, which makes it a way out rather than an
+ * answer.
+ *
+ * One rule for both cameras: the wheel may take the part from a quarter of its
+ * fitted size to ten times it. Under an orthographic camera that scale *is* the
+ * frustum, so the ratios land on `zoom`; under a perspective camera apparent
+ * size is the inverse of distance, so they land on `distance` — which is why
+ * they swap sides between the two.
+ *
+ * Pure, and derived from `bounds`, so it re-derives wherever the scene is
+ * re-measured rather than being sampled once at mount.
+ *
+ * `framed` is what the view has been framed *on*, when that is not the whole
+ * scene — `frameBox` on a single feature. The band is then taken about that
+ * framing as well as about the scene's, because a band centred on the part is
+ * the wrong band for a view of a 3 mm hole in it: ten times the *part's* fitted
+ * size can be less than once the hole's, so the framing the caller asked for sat
+ * outside the clamps meant to keep it in view. Under an orthographic camera
+ * `zoom` is measured against a frustum still sized to the scene, so the framing
+ * enters as the zoom ratio it takes to reach; under a perspective one it enters
+ * as its own fitted distance.
+ *
+ * Widened to the union of the two rather than moved onto `framed`, and that is
+ * the whole of why this takes both. A band that simply followed the last framing
+ * would take the part away: framing a hole would put "far enough out to see what
+ * the hole is in" past `maxDistance`, so the wheel could no longer get back to
+ * the part it had just been looking at, and Fit — a gesture with nothing on
+ * screen to say so — would be the only way. Reaching further in must not cost
+ * the reach back out, so each end takes whichever bound is looser. With no
+ * `framed`, or one the size of the scene, both ends collapse to the scene's own
+ * and this is the function it was before.
+ */
+declare function cameraLimits(projection: Projection, size: ViewportSize, bounds: SceneBounds, margin?: number, framed?: SceneBounds): CameraLimits;
+/**
+ * The box the orbit target is confined to — the fitted framing, several frames
+ * over. Written into `into` so the per-frame path allocates nothing.
+ */
+declare function targetBoundary(bounds: SceneBounds, into: Box3, margin?: number): Box3;
+/**
+ * Points an existing camera's frustum at `bounds` for the current viewport.
+ * Pose is untouched — that belongs to the controls.
+ */
+declare function applyProjection(camera: ViewerCamera, size: ViewportSize, bounds: SceneBounds, margin?: number): void;
+/**
+ * The world-up convention. The part data is Z-up (millimetres, no conversion) —
+ * not the glTF-conventional Y-up — so the camera has to say so explicitly.
+ */
+declare const CAD_CAMERA_UP: Vector3;
+/**
+ * `up` re-squared against a view direction: the part of it perpendicular to
+ * `view`, written into `into`.
+ *
+ * This is what keeps the horizon level while a free orbit carries the camera
+ * over a pole — the up vector follows the view instead of flipping. The
+ * controls run it on every update, which is what makes the next sentence the
+ * important one.
+ *
+ * **It is path-dependent.** It is a projection, so it discards the component it
+ * removes and cannot put it back: running it at one view and then another does
+ * not give what running it once at the second view would. So a camera carries
+ * the roll of every pose it has passed through, and any pose that is meant to
+ * be canonical — the opening frame, a reset, a named view — has to say what
+ * `up` is rather than inherit it. `viewer.tsx` does, at `resetContent`. The
+ * test beside this pins both halves.
+ *
+ * `into` may be `view` or `up` — three.js `crossVectors` reads all six
+ * components before it writes any, and the intermediate is this module's own
+ * scratch, so writing the result over an input is safe. Said here because this
+ * is exported and an out-parameter invites the question; the test beside this
+ * pins it, so a three.js change cannot quietly turn the answer around.
+ *
+ * `view` and `up` being parallel is the one degenerate case: their cross is
+ * zero, `normalize` leaves it zero, and the result is a zero vector rather than
+ * an error. A caller with a free-orbiting camera reaches that at the pole,
+ * which is what `freeOrbit` and a squared `up` at every canonical pose exist to
+ * keep it away from.
+ */
+declare function adaptedUp(view: Vector3, up: Vector3, into: Vector3): Vector3;
+/** Named viewing directions, as unit vectors from the part toward the camera. */
+declare const cadViewDirections: {
+    readonly front: Vector3;
+    readonly back: Vector3;
+    readonly left: Vector3;
+    readonly right: Vector3;
+    readonly top: Vector3;
+    readonly bottom: Vector3;
+    readonly isometric: Vector3;
+};
+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;
+
 /**
  * Mouse and trackpad presets.
  *
@@ -341,6 +616,20 @@ type ExtendedCameraControlsOptions = {
 declare class ExtendedCameraControls extends CameraControls {
     #private;
     constructor(camera: ViewerCamera, domElement: HTMLElement, options?: ExtendedCameraControlsOptions);
+    /**
+     * Bounds how far the wheel may travel, and where the orbit target may go.
+     *
+     * Re-applied whenever the scene is re-measured rather than set once: the
+     * limits are derived from the part's bounds, and a viewer that loads a second
+     * part would otherwise keep the first part's idea of far.
+     *
+     * The boundary confines the *target*. Zoom-to-cursor moves it, and goes on
+     * moving it after the zoom clamp bites — which is a runaway no zoom clamp can
+     * catch. `boundaryEnclosesCamera` stays off: under an orthographic camera the
+     * camera sits well outside the framing it is looking at, so enclosing it would
+     * drag the target back in on every frame.
+     */
+    applyLimits(limits: CameraLimits, boundary?: Box3): void;
     get freeOrbit(): boolean;
     get scheme(): ControlScheme;
     /** Adds the listeners this subclass owns, on top of the base connection. */
@@ -368,6 +657,15 @@ interface CadCameraControlsProps {
      * about an orbit control.
      */
     freeOrbit?: boolean;
+    /**
+     * What the wheel zooms toward: the pointer, or the middle of the view.
+     *
+     * Fusion and SolidWorks zoom to the cursor and most people expect it — you
+     * point at the corner you want and lean in. It is not universally liked: on a
+     * trackpad it can walk the model off screen, which is why the other one
+     * stays.
+     */
+    zoomTo?: 'cursor' | 'centre';
 }
 /**
  * Mounts `camera-controls` against the R3F camera and canvas.
@@ -378,7 +676,7 @@ interface CadCameraControlsProps {
  * 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;
+declare const CadCameraControls: ({ controlsRef, scheme, freeOrbit, zoomTo, }: CadCameraControlsProps) => null;
 
 interface ViewerControls {
     /** Frames the part without changing the current viewing direction. */
@@ -410,16 +708,33 @@ interface ViewerControls {
 }
 interface ViewerHandle extends ViewerControls {
 }
+type VectorLike = Pick<Vector3, 'x' | 'y' | 'z'>;
 
 declare const useViewerControls: () => ViewerControls;
+/** Re-aims the orbit, or `null` when this viewer has the gesture turned off. */
+type Retarget = ((point: VectorLike) => void) | null;
+/**
+ * How the part reports "orbit about this from now on".
+ *
+ * Split this way because the two halves belong to different places: only the
+ * part knows *where* the pointer landed, and it knows it from the raycast the
+ * selection already ran, so nothing here casts a second ray. Only the viewer
+ * knows whether the gesture is wanted, because `retargetOnDoubleClick` is its
+ * prop. `null` is that answer, and it turns the pairing off at the source
+ * rather than making the part detect a gesture nobody will act on.
+ */
+declare const useRetarget: () => Retarget;
 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.
+     * **Orthographic by default.** It is what a machinist reads a part in:
+     * parallel edges stay parallel, so a wall that looks square is square, and
+     * two features the same size measure the same size wherever they sit.
+     *
+     * Perspective is the better answer for reading a deep pocket *as* depth, and
+     * is one prop away.
      */
     projection?: Projection;
     /**
@@ -430,6 +745,57 @@ interface ViewerProps {
     controls?: ControlScheme;
     /** Orbit past the poles instead of stopping there. On by default. */
     freeOrbit?: boolean;
+    /**
+     * What the wheel zooms toward: the pointer, or the middle of the view.
+     *
+     * `cursor` by default, which is what Fusion does and what most people reach
+     * for. It is a preference rather than a right answer — on a trackpad it can
+     * walk the model off screen.
+     */
+    zoomTo?: 'cursor' | 'centre';
+    /**
+     * Whether a double **middle** click re-frames the part. On by default — it is
+     * the way back from having zoomed into a corner, which zooming to the cursor
+     * makes easy to do.
+     */
+    recentreOnDoubleClick?: boolean;
+    /**
+     * Whether a double **left** click on the part orbits about what was clicked
+     * from then on. On by default.
+     *
+     * The clicked point moves to the middle of the view at the same size and
+     * angle, and stays the pivot until something else moves it. It is how you get
+     * from "the whole part" to "this corner" without losing the ability to turn
+     * what you are looking at — and under an orthographic camera it is the only
+     * gesture that re-aims the pivot at all, because the wheel there scales a
+     * frustum rather than travelling toward anything.
+     *
+     * The move is immediate rather than eased: the damping these controls ship
+     * with settles a transition inside one frame. Turn on {@link showOrbitTarget}
+     * if the pivot moving needs to be visible.
+     *
+     * The click is still a click. Its pick arrives with `doubled: true` on it, so
+     * an app that wants a double click to mean something of its own can say so,
+     * and one that would rather a double click left the selection alone can
+     * ignore it. What the viewport claims is the *view*, not the pick.
+     */
+    retargetOnDoubleClick?: boolean;
+    /**
+     * Whether to show two small circles at the orbit target — the point the view
+     * turns and zooms about. **Off by default.**
+     *
+     * They are up while a gesture is running and flash when the pivot moves on
+     * its own: a cursor zoom walking it, a double click re-aiming it, a Fit
+     * putting it back. Then they fade. It answers "why did the part swing that
+     * way", which nothing else on screen does, and it is what makes a wheel that
+     * has carried the pivot off the part legible while it is happening rather
+     * than after.
+     *
+     * Off by default because it is an aid rather than furniture: a viewer that
+     * grew a dot in the middle of every screenshot would be a surprise to anybody
+     * already rendering with this.
+     */
+    showOrbitTarget?: boolean;
     /** Lighting and background. The part's own colours are tuned against this rig. */
     theme?: Partial<ViewerTheme>;
     /**
@@ -602,4 +968,117 @@ declare function bestOwner(model: PartModel, owners: readonly FeatureTag[], cont
  */
 declare function cycleOwner(owners: readonly FeatureTag[], current: FeatureTag | null): FeatureTag | null;
 
-export { type ArrowPlacement, Axes, type AxesProps, CHAMFER, 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 };
+/** A camera and the point it orbits, together, because neither moves alone. */
+interface RetargetPose {
+    readonly position: Vec3;
+    readonly target: Vec3;
+}
+/**
+ * Where the camera and its orbit target go when somebody asks to orbit about a
+ * point on the part.
+ *
+ * The target moves to the point and the camera moves by the same delta, so the
+ * offset between them — the viewing direction and the distance along it — comes
+ * through untouched. Only the pivot changes: what was clicked ends up in the
+ * middle of the view, at the same size, seen from the same angle, and every
+ * orbit and zoom afterwards is about it. This says where the pose lands, not
+ * how it gets there — how fast is the caller's transition and the controls'
+ * damping, and in this viewer that is one frame.
+ *
+ * Moving the target alone would swing the camera to look at the new point from
+ * the old place, which reads as the part being knocked sideways. Moving the
+ * camera alone would not change what anything orbits about, which is the whole
+ * request.
+ *
+ * This is what makes an orthographic viewport navigable. Under a perspective
+ * camera the wheel travels toward the target and a mis-aimed pivot is something
+ * you can dolly out of; under an orthographic one the wheel scales a frustum,
+ * so nothing about zooming ever re-aims the pivot, and F9 measured a cursor
+ * zoom leaving it in space off the part's corner.
+ *
+ * Pure, so the arithmetic is testable without a scene: three vectors in, two
+ * out, no camera and no controls.
+ */
+declare function retargetPose(cameraPosition: Vec3, currentTarget: Vec3, hitPoint: Vec3): RetargetPose;
+
+/**
+ * The orbit target made briefly visible.
+ *
+ * The pivot is the one thing the viewport moves about and never shows. It is
+ * also the one thing that moves without being dragged: zooming to the cursor
+ * walks it, a double click re-aims it, Fit puts it back. So "why did the part
+ * swing that way" has an answer the screen has never given.
+ *
+ * It is an aid rather than furniture, which is why it is measured in time as
+ * well as in pixels — up while a gesture is running, a flash when the pivot
+ * moves on its own, and gone otherwise. A marker that stayed would be a dot in
+ * the middle of every screenshot.
+ */
+/** Radius of the solid centre dot, in CSS pixels. */
+declare const ORBIT_TARGET_PIXELS = 3;
+/** Outer radius of the ring around it, in CSS pixels. */
+declare const ORBIT_TARGET_RING_PIXELS = 14;
+/** The ring's thickness, as a fraction of its outer radius. */
+declare const ORBIT_TARGET_RING_WIDTH = 0.16;
+/**
+ * A dot inside a ring, rather than the legacy viewer's two nested spheres.
+ *
+ * Legacy paired a depth-tested outer ball with a dot drawn over everything, so
+ * the part burying the ball said the pivot was inside the material
+ * (`use-target.ts:10-25`). Rendered against a real part that reads as a fault
+ * rather than as a signal: a pivot sitting *on* a surface — which is exactly
+ * what a double-click re-target produces, and the commonest case there is —
+ * cuts the sphere in half, leaving a lens-shaped smudge with the dot off to one
+ * side of it. The depth it was reporting is a question almost nobody asks; that
+ * it looked broken is something everybody would see.
+ *
+ * A billboarded ring is the same marker with the ambiguity taken out. It is the
+ * same shape at every pose, over any surface, and it is what a viewport
+ * reticle looks like everywhere else.
+ */
+declare const ORBIT_TARGET_COLOR = 3948625;
+declare const ORBIT_TARGET_RING_COLOR = 7057587;
+/** A ring is a hint about where, not a second dot. */
+declare const ORBIT_TARGET_RING_OPACITY = 0.9;
+/**
+ * Both colours are the package's own rather than {@link ViewerTheme} roles.
+ *
+ * Adding a required field to that interface is a breaking type change for
+ * anybody who builds a whole theme by hand, which is a steep price for an aid
+ * that is off by default and on screen for about a second at a time. They are
+ * palette colours already in use — the slate the cube labels and the section
+ * handle outline take, and the teal that outlines a section cut — so the marker
+ * reads as part of the control family rather than as something imported. If a
+ * consumer asks to re-colour it, the roles go in at the next major and nothing
+ * about this module's shape changes.
+ */
+/**
+ * How long the marker stays at full strength after the pivot moves on its own,
+ * in milliseconds. Legacy's (`use-target.ts:96`).
+ */
+declare const ORBIT_TARGET_FLASH_MS = 100;
+/**
+ * How long it takes to fade once nothing is holding it up, in milliseconds.
+ *
+ * Legacy faded in twenty steps of 0.05 on a 50 ms timer, which is this number
+ * arrived at the long way round (`use-target.ts:79-87`). Long enough that
+ * letting go of an orbit does not make the marker vanish before the eye finds
+ * it, short enough that it is gone before anybody wonders what it is.
+ */
+declare const ORBIT_TARGET_FADE_MS = 1000;
+/**
+ * How visible the marker is, `sinceHold` milliseconds after the last thing
+ * holding it up let go.
+ *
+ * Linear, and negative input means something still is — a drag in progress, or
+ * a flash inside its window — so the caller can pass one number rather than
+ * branching on which of the two it is.
+ *
+ * Pure because the fade has to be driven from a frame rather than a timer:
+ * this viewer renders on demand, so a `setInterval` writing an opacity would
+ * change the material and never repaint it. The curve therefore has to be
+ * something a frame can ask for the value of, at whatever moment it runs.
+ */
+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 };