@toolpath/viewer 0.2.0

package/dist/normalize-B0HBvzGu.d.ts

@@ -0,0 +1,868 @@
+import * as react from 'react';
+import { Group, Mesh, LineSegments, Box3, Plane, BufferGeometry, Camera, Vector3, OrthographicCamera, PerspectiveCamera, Object3D } from 'three';
+
+/**
+ * The normalized part — the only thing the renderer consumes.
+ *
+ * `engine/` produces this; nothing under `model/` or `render/` sees a
+ * `PartReportResponse`. The renderer therefore survives an API change, and the
+ * viewer can be driven from a local file with no API at all, which is also how
+ * it gets tested.
+ *
+ * The mesh is **millimetres** and **Z-up** — not the glTF-conventional Y-up.
+ * Machining and candidate directions are unit vectors, and are not always
+ * axis-aligned: real reports carry tilted 5-axis setups alongside the six
+ * axis-aligned ones.
+ */
+interface Vec3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * Opaque per-feature identity — 16 hex characters (64 bits).
+ *
+ * Never substitute an array position for this. The `features` array is not
+ * sorted by anything, and a position-derived identity institutionalizes that
+ * mistake.
+ */
+type FeatureTag = string;
+/**
+ * Feature types the Engine is known to report. The set is **open** — the
+ * kernel adds more — so this stays a widened union rather than a closed enum
+ * that breaks on the next kernel release.
+ */
+type KnownFeatureType = 'blind_hole' | 'boss' | 'chamfer' | 'contour_surface' | 'face' | 'filleted_blind_hole' | 'filleted_boss' | 'filleted_open_pocket' | 'filleted_pocket' | 'inner_fillet' | 'open_pocket' | 'outer_fillet' | 'pocket' | 'profile' | 'sink' | 'slanted_face' | 'through_hole' | 'through_pocket' | 'undercut_dovetail' | 'undercut_filleted_tslot' | 'undercut_tslot' | 'wall';
+type FeatureType = KnownFeatureType | (string & Record<never, never>);
+/**
+ * The analytic surface classification of a region. The kernel classifies more
+ * than the two seen most often, so the union stays open.
+ */
+type KnownShapeKind = 'Cylinder' | 'Plane';
+type ShapeKind = KnownShapeKind | (string & Record<never, never>);
+/** A half-open triangle range: `[start, end)`. */
+interface TriangleRange {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * The `feature ↔ region ↔ triangle` mapping, as a pure projection of the report.
+ *
+ * The asymmetry it encodes is the single most important fact about selection:
+ *
+ * ```text
+ * feature → regions     always well-defined     (regionIdxs, given)
+ * region  → feature     genuinely one-to-many   (no rule fixes this)
+ * ```
+ *
+ * A region is owned by five to eight features *even on a cube* — measured, not
+ * estimated — because the same physical face is a `face` under one machining
+ * direction and a `wall` under others, and every direction's `profile` overlaps
+ * the surfaces it traces. Nothing here tries to reduce that to one; ranking a
+ * viewport click depends on viewer state (active direction, camera) and lives
+ * in `render/selection.ts`.
+ *
+ * The interface exists so a future change in how the Engine expresses the
+ * mapping — a per-triangle array, a vertex attribute — is absorbed in one file.
+ */
+interface RegionIndex {
+    readonly regionCount: number;
+    /**
+     * Triangle index → region idx, `O(log R)`.
+     *
+     * `null` means the report is malformed or the mesh and report are mismatched,
+     * **not** a state the UI needs to render gracefully: regions are guaranteed
+     * to tile the mesh completely, and `buildRegionIndex` rejects a table that
+     * does not. Treat a `null` here as a bug worth logging.
+     */
+    regionForTriangle(triangle: number): number | null;
+    /** Every feature owning a region, in report order. Measured at 5–8 entries. */
+    featuresForRegion(region: number): readonly FeatureTag[];
+    /** A feature's regions, for highlight, framing, and isolation. */
+    regionsForFeature(tag: FeatureTag): readonly number[];
+    /** `null` for an unknown region idx. */
+    rangeForRegion(region: number): TriangleRange | null;
+}
+interface PartModelRegion {
+    readonly idx: number;
+    readonly shapeKind: ShapeKind;
+    /**
+     * **Analytic** area, not faceted. Use it to sort, filter, and display — never
+     * to validate geometry: a computed-vs-reported area check fails by around a
+     * percent on perfectly correct data and reads as a triangle-ordering bug.
+     */
+    readonly area: number;
+    readonly triangles: TriangleRange;
+}
+interface PartModelFeature {
+    /** Opaque identity. Never an array position. */
+    readonly tag: FeatureTag;
+    readonly featureType: FeatureType;
+    /** A unit vector, not necessarily axis-aligned. */
+    readonly machiningDirection: Vec3;
+    /**
+     * The feature's own axis, where it has one — a bore's centreline, a wall's
+     * normal — and `null` on anything without a natural axis.
+     *
+     * Kept because it is how somebody names an orientation without knowing its
+     * numbers: "hold it square to that hole" is a sentence a machinist says, and
+     * this is the vector behind it.
+     */
+    readonly axis: Vec3 | null;
+    readonly regionIdxs: readonly number[];
+}
+interface PartMeshRefs {
+    readonly pointCount: number;
+    readonly triangleCount: number;
+    /**
+     * Presigned and short-lived. Fetch promptly; refetch the report rather than
+     * persisting the URL.
+     */
+    readonly glbUrl: string | null;
+    readonly stlUrl: string | null;
+    readonly thumbnailUrl: string | null;
+}
+interface PartModel {
+    readonly partId: string;
+    readonly kernelVersion: string;
+    readonly features: readonly PartModelFeature[];
+    readonly regions: readonly PartModelRegion[];
+    readonly candidateDirections: readonly Vec3[];
+    readonly mesh: PartMeshRefs;
+    readonly regionIndex: RegionIndex;
+    /** Non-fatal problems found while normalizing. */
+    readonly warnings: readonly string[];
+}
+
+/**
+ * Viewer colors.
+ *
+ * Plain hex numbers rather than CSS custom properties because three needs
+ * numbers; wiring these to a design-token source is a separate decision. The
+ * values are tuned against the viewer's light rig, and changing either in
+ * isolation changes how every part reads.
+ */
+interface ViewerTheme {
+    /** `null` keeps the canvas transparent so the page background shows through. */
+    readonly background: number | null;
+    readonly hemisphereSky: number;
+    readonly hemisphereGround: number;
+    readonly hemisphereIntensity: number;
+    readonly ambient: number;
+    readonly ambientIntensity: number;
+    /** Unhighlighted part surface. */
+    readonly part: number;
+    readonly partEmissive: number;
+    /** The region under the cursor. */
+    readonly hover: number;
+    /** Selected features; see also {@link HIGHLIGHT_COLORS}. */
+    readonly highlight: number;
+    /**
+     * The faces a click just picked — the one thing on the part that is about
+     * this moment rather than about the plan.
+     */
+    readonly picked: number;
+    /** `EdgesGeometry` line color and opacity. */
+    readonly edge: number;
+    readonly edgeOpacity: number;
+    /** The capped face of a section cut, and the cutting plane's outline. */
+    readonly sectionCap: number;
+    readonly sectionOutline: number;
+    /**
+     * The arrow that drags the cut, and the shell that outlines it. Hovered it
+     * takes {@link ViewerTheme.hover}, like every other control here.
+     */
+    readonly sectionHandle: number;
+    readonly sectionHandleOutline: number;
+    /**
+     * The view cube's panels, the lines between them, and its face names. A
+     * hovered panel takes {@link ViewerTheme.hover}, the same color the part uses
+     * — the cube is a control, and one hover color across the viewport is one
+     * thing to learn.
+     */
+    readonly cube: number;
+    readonly cubeEdge: number;
+    readonly cubeLabel: number;
+}
+/**
+ * Selection highlight by issue type. `default` is the plain selection color;
+ * the other two mark a feature the analysis flagged.
+ */
+declare const HIGHLIGHT_COLORS: {
+    readonly default: 16753434;
+    readonly toolIssue: 9647082;
+    readonly geometryIssue: 16711680;
+};
+/**
+ * Per-direction color cycle for the machining-direction overlay.
+ *
+ * Nine entries, so a part with ten candidate directions wraps — real reports
+ * carry exactly ten, which is what makes the wrap reachable rather than
+ * theoretical.
+ *
+ * The same color identifies a direction in three places at once: on the part,
+ * on its arrow, and on its row in the directions list. That triple is the point
+ * of the palette — it is an identity, not a ranking, which is why the colors
+ * are unordered and deliberately not a scale.
+ */
+declare const DIRECTION_COLORS: readonly [3900150, 1357990, 14239471, 440020, 6660877, 15485081, 6583435, 1096065, 6514417];
+declare const DEFAULT_THEME: ViewerTheme;
+declare function resolveTheme(overrides?: Partial<ViewerTheme>): ViewerTheme;
+/**
+ * Whether two themes would paint identically.
+ *
+ * Written out rather than derived from `Object.keys`, which cannot be typed
+ * without an assertion — and this way adding a field to {@link ViewerTheme}
+ * makes the compiler point here.
+ */
+declare function themesEqual(a: ViewerTheme, b: ViewerTheme): boolean;
+/** The color for a candidate direction, wrapping at {@link DIRECTION_COLORS}. */
+declare function directionColor(index: number): number;
+
+/** The vertex attribute carrying each vertex's column in the state texture. */
+declare const REGION_ATTRIBUTE = "aRegion";
+/**
+ * A part on screen: one mesh, one draw call, one material.
+ *
+ * Highlighting is a texture write, not a material change. Every region owns one
+ * texel of a `regionCount + 1` wide RGBA texture holding a color and a blend
+ * weight, and every vertex carries its region's column in {@link
+ * REGION_ATTRIBUTE}. Hover, select, candidate, and dim are then all the same
+ * operation — write a texel, flag the texture — with no material churn, no
+ * geometry rebuild, and no re-upload of positions.
+ *
+ * What it replaces allocated a material per visual state and rebuilt the
+ * geometry's draw groups on every hover, which is a draw call per highlighted
+ * feature and a buffer walk per pointer move.
+ */
+interface PartObject {
+    /** Add this to the scene. Holds the mesh and its edges. */
+    readonly object: Group;
+    readonly mesh: Mesh;
+    /** The overlaid edge lines, exposed so a consumer can hide them. */
+    readonly edges: LineSegments;
+    readonly model: PartModel;
+    /** Paints one region. `weight` 0 clears it, 1 replaces the surface color. */
+    paintRegion(region: number, color: number, weight: number): void;
+    /** What a region is painted with now. `null` for a region it does not have. */
+    regionPaint(region: number): RegionPaint | null;
+    /** Paints every region a feature owns. */
+    paintFeature(tag: FeatureTag, color: number, weight: number): void;
+    clearPaint(): void;
+    /** A feature's bounds in part space, for framing. `null` if it has none. */
+    boxForFeature(tag: FeatureTag): Box3 | null;
+    /**
+     * Applies a section's clipping plane to the part and its edges. `null`
+     * removes it. A setter rather than a constructor argument because a section
+     * is toggled far more often than a part is loaded.
+     */
+    setClippingPlanes(planes: readonly Plane[] | null): void;
+    setTheme(theme: ViewerTheme): void;
+    dispose(): void;
+}
+interface RegionPaint {
+    readonly color: number;
+    /** 0 for untouched, 1 for fully painted. */
+    readonly weight: number;
+}
+/** The part of a `PartModel` the buffer builders need. */
+type RegionTable = Pick<PartModel, 'regions'>;
+/**
+ * Maps a region's `idx` to its column in the state texture.
+ *
+ * Real reports number regions densely from zero, but `idx` is documented as an
+ * identifier rather than a position, so it is looked up instead of assumed —
+ * the same discipline `regionIdxs` needs. The extra column past the end is a
+ * permanently transparent slot for a vertex belonging to no region; region
+ * tiling is enforced at normalization so nothing should land there, and if
+ * something does, it paints nothing rather than painting region zero.
+ */
+declare function buildRegionTexels(model: RegionTable): Map<number, number>;
+/**
+ * The per-vertex region attribute, built by walking the region table once.
+ *
+ * The mesh must be non-indexed — `engine/geometry.ts` guarantees it — because a
+ * shared vertex belongs to several regions and there is no single value to
+ * write into it. With three vertices per triangle, region `[start, end)` owns
+ * the vertex range `[start * 3, end * 3)`, which makes this a handful of `fill`
+ * calls.
+ */
+declare function buildRegionAttribute(model: RegionTable, texels: Map<number, number>, vertexCount: number): Float32Array;
+/**
+ * Builds the renderable part.
+ *
+ * Takes exclusive use of `geometry`: it adds {@link REGION_ATTRIBUTE} to it and
+ * removes that again on dispose, but never disposes the geometry itself — the
+ * loader's caller owns it, and a viewer destroying an object it was handed is a
+ * good way to break a cache that is legitimately sharing it. One geometry backs
+ * one part; sharing it between two parts at once is unsupported.
+ */
+declare function createPart(model: PartModel, geometry: BufferGeometry, theme: ViewerTheme): PartObject;
+
+/**
+ * A feature the consumer wants coloured, for a reason the viewer does not need
+ * to know — a difficulty band, a setup, a material.
+ *
+ * A colour rather than a concept: the viewer paints it and stays out of what it
+ * means. `weight` is how strongly it covers the surface beneath, 0 to 1;
+ * omitted, it takes a wash that stays under the selection and candidate layers.
+ */
+interface FeatureHighlight {
+    readonly tag: FeatureTag;
+    readonly color: number;
+    readonly weight?: number;
+}
+/**
+ * A colour on one face, named directly rather than through a feature.
+ *
+ * Features are the usual way to say what a colour means, but a face is a thing
+ * in its own right: a consumer proposing work face by face, or showing which
+ * part of a feature it is talking about, has no feature tag for "these four
+ * faces and not the fifth". So regions can be painted too, over the feature
+ * layer and under selection.
+ */
+interface RegionHighlight {
+    readonly region: number;
+    readonly color: number;
+    readonly weight?: number;
+}
+/**
+ * How strongly a consumer's own layer paints.
+ *
+ * Below a candidate and well below a selection: a wash the whole part can wear
+ * at once — every feature banded by how hard it is to cut — has to stay legible
+ * underneath the two layers that answer "what did I just click".
+ */
+declare const HIGHLIGHT_WEIGHT = 0.7;
+/** How strongly a candidate paints, relative to a pick. */
+declare const CANDIDATE_WEIGHT = 0.4;
+/** Hover, just under a selection: a question, not a decision. */
+declare const HOVER_WEIGHT = 0.85;
+interface HighlightLayers {
+    /** The consumer's own colouring, painted under everything else. */
+    readonly highlights?: readonly FeatureHighlight[];
+    /** Colours on named faces, over the feature highlights. */
+    readonly regionHighlights?: readonly RegionHighlight[];
+    /**
+     * Every feature a click could have meant, each faintly in its own direction's
+     * colour. Distinct from `selection` on purpose: a ranked guess that quietly
+     * discarded its alternatives is the main way this interaction goes wrong.
+     */
+    readonly candidates?: readonly FeatureTag[];
+    /** The features being read. */
+    readonly selection?: readonly FeatureTag[];
+    /**
+     * The faces a click just picked, painted over the reading they resolved to.
+     *
+     * Above the selection rather than below it, which is where the feature picker
+     * puts them — because the picker paints nothing for a guessed reading, so its
+     * picked faces are never covered. Here the guess *is* painted, so held faces
+     * under it would vanish and a modifier-click would look like it did nothing.
+     */
+    readonly pickedRegions?: readonly number[];
+    /** Features shown as hovered from outside the viewport — a list row. */
+    readonly hoveredFeatures?: readonly FeatureTag[];
+    /** The face under the pointer. */
+    readonly hoverRegion?: number | null;
+}
+/**
+ * Paints the layer stack onto a part.
+ *
+ * **A face can only be one colour.** The part is one mesh and each region
+ * carries a single texel, so every question the part answers has to be answered
+ * by one mark. Layers are therefore painted weakest first and each one
+ * overwrites what is under it outright — nothing blends.
+ *
+ * The order is the argument. Layers 1–2 are the consumer's standing opinion;
+ * 3–4 are this moment; 5–6 are the pointer. A question asked with the mouse
+ * always beats a decision already made, because the decision is still there
+ * when the pointer moves away.
+ */
+declare function applyHighlightLayers(part: PartObject, layers: HighlightLayers, theme: ViewerTheme): void;
+
+/**
+ * Which modifier keys were down when the pick happened.
+ *
+ * Reported rather than interpreted: "hold this to add to the selection" is a
+ * platform convention — command on a Mac, control everywhere else — and which
+ * key means what belongs to the app, not to a viewport.
+ */
+interface PickModifiers {
+    readonly alt: boolean;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+    readonly shift: boolean;
+    /** The right button, on a click that did not become a pan. */
+    readonly secondary: boolean;
+}
+declare const NO_MODIFIERS: PickModifiers;
+/**
+ * A pointer event on the part, resolved to the face it landed on and the
+ * features that own it.
+ *
+ * `owners` travels alongside `best` on purpose. A click resolves to five to
+ * eight readings and the ranking puts one of them up; that is a *default*, not
+ * a claim of correctness, and a consumer that was handed only the winner could
+ * not offer the alternatives it silently discarded.
+ */
+interface PartPick {
+    readonly region: number;
+    /** Every feature owning the face, in report order. */
+    readonly owners: readonly FeatureTag[];
+    /** The same set, ranked for this click. Filtered by an active direction. */
+    readonly ranked: readonly FeatureTag[];
+    /** The ranked pick, or `null` when nothing here is reachable that way. */
+    readonly best: FeatureTag | null;
+    readonly triangleIndex: number;
+    readonly point: readonly [number, number, number];
+    /** The surface's outward normal in world space — the plane under the cursor. */
+    readonly normal: readonly [number, number, number];
+    readonly modifiers: PickModifiers;
+}
+/** A unit vector from the part toward the camera, for the owner ranking. */
+declare function viewDirection(camera: Camera, target: Vector3): Vec3;
+interface BuildPickInput {
+    readonly model: PartModel;
+    readonly region: number;
+    readonly triangleIndex: number;
+    readonly point: readonly [number, number, number];
+    readonly normal: readonly [number, number, number];
+    readonly modifiers?: PickModifiers;
+    /**
+     * The machining direction the pick is scoped to, as an index into
+     * `candidateDirections`. Narrows the owners to two, one, or **none** — the
+     * empty case is real, and reads as "nothing here in this direction" rather
+     * than as a pick that missed.
+     */
+    readonly activeDirection?: number | null;
+    readonly viewDirection?: Vec3 | null;
+}
+declare function buildPick(input: BuildPickInput): PartPick;
+/**
+ * The owner to focus for a click, given what the last click focused.
+ *
+ * Clicking the same face again walks its readings — the standard CAD escape
+ * hatch for an ambiguous click — while a click on a different face starts from
+ * that face's own best answer.
+ */
+declare function focusForPick(pick: PartPick, previousRegion: number | null, previousFocus: FeatureTag | null): FeatureTag | null;
+
+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;
+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;
+/**
+ * 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;
+/** 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;
+
+/**
+ * Render order. The stencil pass must precede the cap, and the part must draw
+ * after both or it overwrites the cap it is supposed to be capped by. The part
+ * draws at 3 and its edges at 4, so the handle sits above the cap it stands on.
+ */
+declare const SECTION_RENDER_ORDER: {
+    readonly stencil: 1;
+    readonly cap: 2;
+    readonly handle: 6;
+};
+/** The handle's length on screen, in CSS pixels, whatever the zoom. */
+declare const HANDLE_PIXELS = 78;
+interface SectionBounds {
+    /** Plane constant at which the whole part is clipped away. */
+    readonly min: number;
+    /** Plane constant at which nothing is clipped. */
+    readonly max: number;
+}
+/** A point the cut's depth is measured from, and what to call it in a panel. */
+interface SectionAnchor {
+    readonly point: Vec3;
+    readonly label: string;
+}
+/**
+ * A plane placed at a point rather than swept through the part.
+ *
+ * `normal` is the plane's own — three keeps the half-space it points into — so
+ * it faces *away* from the material the cut removes. Use {@link sectionFromPick}
+ * to build one from a picked surface rather than negating by hand.
+ */
+interface SectionPlacement {
+    readonly normal: Vec3;
+    readonly point: Vec3;
+    /** Shown as the cut's reference. Defaults to {@link PICKED_SURFACE_LABEL}. */
+    readonly label?: string;
+}
+declare const PICKED_SURFACE_LABEL = "Part surface";
+/**
+ * The range of plane constants that sweeps a box along `normal`.
+ *
+ * Derived from the eight corners rather than from a single axis extent, which is
+ * what makes an arbitrary normal work: a tilted plane leaves the box through a
+ * corner, and an axis-aligned approximation either stops short of cutting the
+ * part or sweeps a long way through empty space before reaching it.
+ *
+ * `Plane` keeps the half-space where `normal · p + constant > 0`, so a *larger*
+ * constant clips less. `min` and `max` are named for the constant, not for how
+ * much they remove.
+ */
+declare function sectionBounds(box: Box3, normal: Vec3): SectionBounds;
+/** The plane constant at `t`, from 0 (uncut) to 1 (fully cut away). */
+declare function sectionConstant(bounds: SectionBounds, t: number): number;
+/**
+ * Where a plane constant sits in the sweep, inverting {@link sectionConstant}.
+ *
+ * A part with no extent along the normal has a degenerate range and no
+ * meaningful position within it; 0 keeps a slider at rest rather than at NaN.
+ */
+declare function sectionOffset(bounds: SectionBounds, constant: number): number;
+/**
+ * How far past `anchor` a plane at `constant` cuts, along its own normal.
+ *
+ * Positive is into the material the anchor's surface faces away from: pick the
+ * top of a part and a depth of 3 removes the top 3 mm. Its own inverse, since
+ * `depth = −(n · a) − constant` either way.
+ */
+declare function sectionDepth(normal: Vec3, anchor: Vec3, constant: number): number;
+/** The plane constant that cuts `depth` past `anchor`. */
+declare function sectionDepthConstant(normal: Vec3, anchor: Vec3, depth: number): number;
+/** The depths at which the cut starts and finishes, for a bounded control. */
+declare function sectionDepthRange(bounds: SectionBounds, normal: Vec3, anchor: Vec3): {
+    readonly min: number;
+    readonly max: number;
+};
+/**
+ * Turns a picked surface into a cut that starts at it.
+ *
+ * The pick reports the surface normal, which faces the viewer; the plane keeps
+ * what its own normal points into, so the two are opposite. Getting this
+ * backwards leaves the part whole with a plane drawn behind it, which is the
+ * failure this helper exists to make unrepeatable.
+ */
+declare function sectionFromPick(surface: {
+    readonly point: Vec3;
+    readonly normal: Vec3;
+}, label?: string): SectionPlacement;
+/**
+ * The starting depth for a cut keyed off a picked surface.
+ *
+ * A plane placed exactly on the surface it was picked from cuts nothing and
+ * z-fights with that surface, so the click reads as having done nothing. It
+ * starts a hair inside instead — engaged, and still "at" the face.
+ */
+declare function pickedStartDepth(box: Box3): number;
+/** The plane a cut sits on, for a placement or a swept offset. */
+declare function sectionPlane(box: Box3, normal: Vec3, offset: number, into?: Plane): Plane;
+/**
+ * A world length that covers `pixels` on screen at `point`.
+ *
+ * A handle sized in world units is a thumbnail on a plate and a wall on an
+ * insert; the whole reason it is measured this way is that it is a control
+ * rather than part of the model.
+ */
+declare function screenLength(camera: ViewerCamera, point: Vector3, viewport: ViewportSize, pixels: number): number;
+/**
+ * The plane a drag is projected onto: the one containing the handle's axis and
+ * facing the camera as squarely as it can.
+ *
+ * Dragging along a line in a 3D view has to resolve a 2D pointer to a distance,
+ * and this is the surface that makes the pointer track the arrow rather than
+ * running away from it when the axis is nearly edge-on.
+ */
+declare function dragPlane(axis: Vector3, view: Vector3, point: Vector3, into?: Plane): Plane;
+
+interface SectionOptions {
+    enabled: boolean;
+    /**
+     * The half-space that stays. Defaults to +Z, which keeps the top of the part
+     * and eats upward from the bottom as `offset` grows.
+     */
+    normal?: Vec3;
+    /** Where the sweep sits, 0 (whole part) to 1 (gone). */
+    offset?: number;
+    /** Key the cut off one surface instead, usually from `sectionFromPick`. */
+    plane?: SectionPlacement | null;
+    /** How far past that surface to cut, in model units. */
+    depth?: number;
+}
+interface SectionState {
+    readonly enabled: boolean;
+    readonly normal: Vec3;
+    readonly offset: number;
+    readonly constant: number;
+    readonly plane: SectionPlacement | null;
+    readonly depth: number | null;
+    /**
+     * How far the cut can travel from its anchor, in model units, or `null` for a
+     * sweep — which is measured as a fraction of the part rather than a distance.
+     *
+     * Reported because a control that moves the cut has to be bounded by the same
+     * numbers the cut is, and only the viewer knows the part's extent along a
+     * given normal.
+     */
+    readonly depthRange: {
+        readonly min: number;
+        readonly max: number;
+    } | null;
+}
+/** 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;
+}
+/**
+ * A clipping plane with a solid 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 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 const SectionView: ({ geometry, box, plane, theme, showHandle, onDrag, }: SectionViewProps) => react.JSX.Element;
+
+interface PartMeshProps {
+    /** The normalized report. `engine/normalize.ts` produces it. */
+    model: PartModel;
+    /**
+     * The part's mesh, from `loadPartMesh`, which checks the two describe the
+     * same artifact. Owned by the caller: this adds a region attribute to it and
+     * removes that again, but never disposes it.
+     */
+    geometry: BufferGeometry;
+    /**
+     * The features being read. The consumer owns this — a feature panel is
+     * authoritative for what is selected, because `region → feature` is
+     * one-to-many and no scoping rule fixes that.
+     */
+    selection?: readonly FeatureTag[];
+    /**
+     * Every feature a click could have meant, painted faintly in each one's own
+     * direction colour, under the selection.
+     */
+    candidates?: readonly FeatureTag[];
+    /** The consumer's own colouring, painted under everything else. */
+    highlights?: readonly FeatureHighlight[];
+    /** Colours on named faces, over the feature highlights. */
+    regionHighlights?: readonly RegionHighlight[];
+    /**
+     * The faces a click just picked, painted over the reading they resolved to so
+     * that holding a second face shows what it did even when the reading is
+     * unchanged.
+     */
+    pickedRegions?: readonly number[];
+    /**
+     * Features to show as hovered from outside the viewport — a list row under
+     * the pointer. The face under the pointer *in* the viewport is tracked here
+     * and needs no prop.
+     */
+    hoveredFeatureIds?: readonly FeatureTag[];
+    /**
+     * Scopes a pick to one machining direction, as an index into the model's
+     * `candidateDirections`. A face that direction cannot reach then picks to
+     * nothing, which is a real answer rather than a missed click.
+     */
+    activeDirection?: number | null;
+    /**
+     * The section cut. Omit, or pass `enabled: false`, for none.
+     *
+     * Either sweep an axis — `normal` points into the half that stays and
+     * `offset` runs 0 (whole) to 1 (gone) — or key the cut off one surface with
+     * `plane`, which `depth` then moves in model units. `sectionFromPick` turns a
+     * pick into that placement with the normal the right way round.
+     */
+    section?: SectionOptions;
+    /**
+     * The cut changed, including when the handle was dragged. Emitted only on a
+     * real change, so echoing it into state is safe.
+     */
+    onSectionChange?: (state: SectionState) => void;
+    /**
+     * A feature to frame. Framed when it changes, so setting it to the feature
+     * already framed does nothing — a zoom is a request, not a state to hold.
+     */
+    focusFeature?: FeatureTag | null;
+    onHover?: (pick: PartPick | null) => void;
+    /**
+     * A click on the part.
+     *
+     * Never `null`: a mesh's own "missed" event fires whenever *it* was not hit,
+     * including when the click landed on an arrow or a section handle, so
+     * emitting an empty pick from here made pressing an arrow clear the
+     * selection. Clicking nothing at all is a fact about the scene, and
+     * `<Viewer onPointerMissed>` is where it is reported.
+     */
+    onPick?: (pick: PartPick) => void;
+    theme?: Partial<ViewerTheme>;
+    showEdges?: boolean;
+}
+/**
+ * The part, as one mesh with one material.
+ *
+ * Highlighting writes texels rather than swapping materials or rebuilding draw
+ * groups — see `render/part.ts` — so a repaint costs one texture upload. That is
+ * why the paint runs in a layout effect against a ref rather than being
+ * expressed as JSX, and why moving the pointer over the part repaints with no
+ * React render at all: the hovered face lives in a ref, and routing it through
+ * state is what this rewrite exists to stop doing.
+ */
+declare const PartMesh: ({ model, geometry, selection, candidates, highlights, regionHighlights, pickedRegions, hoveredFeatureIds, activeDirection, section, onSectionChange, focusFeature, onHover, onPick, theme, showEdges, }: PartMeshProps) => react.JSX.Element;
+
+interface EnginePartProps extends Omit<PartMeshProps, 'model' | 'geometry'> {
+    /**
+     * A Toolpath Engine part report, exactly as the API returned it.
+     *
+     * Typed `unknown` because it is validated rather than trusted: a report read
+     * from a file is treated the same as one off the wire. A malformed one throws
+     * `PartReportFormatError`, and one from a pre-0.3.0 kernel throws
+     * `UnsupportedKernelVersionError` — both worth catching in an error boundary,
+     * since neither is a state the viewport can render.
+     */
+    report: unknown;
+}
+/**
+ * Renders a Toolpath Engine report, fetching the mesh it describes.
+ *
+ * Suspends while the mesh loads and throws its failure, so a caller wraps it in
+ * `<Suspense>` and an error boundary rather than threading loading state
+ * through props.
+ */
+declare const EnginePart: ({ report, ...props }: EnginePartProps) => react.JSX.Element;
+
+/**
+ * Shades each region smoothly and every boundary between them hard.
+ *
+ * The Engine's mesh carries positions and nothing else, so the normals have to
+ * be invented. Averaging them across the whole mesh smooth-shades a cube —
+ * every corner reads as a ball bearing. Not averaging at all gives every
+ * triangle its own normal, which is honest but leaves a bore looking like a
+ * fifty-sided nut, because that is exactly what its triangles are.
+ *
+ * Neither is necessary here, because the report says which triangles belong to
+ * one analytic surface. Averaging *within* a region and never *across* one
+ * gives a bore that shades like a bore and an edge that stays an edge: the
+ * distinction a mesh cannot express is one the region table can.
+ *
+ * Two vertices are the same point if their coordinates match exactly. That is
+ * safe rather than optimistic — `toNonIndexed` copies each shared vertex from
+ * one source value, so the duplicates it makes are bit-identical, which is the
+ * only case this needs to find.
+ *
+ * The geometry must be non-indexed, which `parsePartGeometry` guarantees.
+ */
+declare function smoothRegionNormals(geometry: BufferGeometry, regions: readonly PartModelRegion[]): void;
+
+/**
+ * The first kernel to publish `regions[]` and `featureTag`, and therefore the
+ * first that can drive feature selection at all.
+ */
+declare const MIN_KERNEL_VERSION = "0.3.0";
+/**
+ * Validates a part report and projects it into the `PartModel` the renderer
+ * consumes.
+ *
+ * Takes `unknown` on purpose: a report read from a file gets exactly the same
+ * treatment as one off the wire, which is what makes the viewer drivable — and
+ * testable — with no API at all. `openapi/openapi.json` is the contract this
+ * validates against; the checks are structural so that a response which does
+ * not match cannot reach the renderer regardless of how it was typed upstream.
+ *
+ * Throws `UnsupportedKernelVersionError` for a pre-`0.3.0` report, and
+ * `PartReportFormatError` (carrying every problem found, not just the first)
+ * for anything else.
+ */
+declare function normalizePartReport(report: unknown): PartModel;
+/**
+ * Rejects reports from a kernel older than `0.3.0`.
+ *
+ * `0.2.0` reports parse *almost* correctly — same envelope, same mesh — but
+ * carry `featureIndex` instead of `featureTag` and no `regions[]` at all, so
+ * every selection path would silently do nothing. Failing here, with the
+ * version named, is the whole point.
+ */
+declare function assertSupportedKernelVersion(kernelVersion: string): void;
+
+export { applyHighlightLayers as $, type PartPick as A, type BuildPickInput as B, CAD_CAMERA_UP as C, DEFAULT_FIT_MARGIN as D, EnginePart as E, type FeatureTag as F, type PickModifiers as G, HANDLE_PIXELS as H, REGION_ATTRIBUTE as I, type RegionHighlight as J, type KnownFeatureType as K, type RegionPaint as L, MIN_KERNEL_VERSION as M, NO_MODIFIERS as N, type SceneBounds as O, type PartModel as P, type SectionAnchor as Q, type RegionIndex as R, SECTION_RENDER_ORDER as S, type TriangleRange as T, type SectionBounds as U, type Vec3 as V, type SectionOptions as W, type SectionPlacement as X, type SectionState as Y, SectionView as Z, type ViewportSize as _, type PartMeshRefs as a, applyProjection as a0, aspectRatio as a1, boundsFromBox as a2, buildPick as a3, buildRegionAttribute as a4, buildRegionTexels as a5, cadViewDirections as a6, contentBounds as a7, createPart as a8, currentViewDirection as a9, defaultBounds as aa, directionColor as ab, dragPlane as ac, fitDistance as ad, focusForPick as ae, orthographicHalfHeight as af, perspectiveFitDistance as ag, pickedStartDepth as ah, resolveSectionPlane as ai, resolveTheme as aj, screenLength as ak, sectionBounds as al, sectionConstant as am, sectionDepth as an, sectionDepthConstant as ao, sectionDepthRange as ap, sectionFromPick as aq, sectionOffset as ar, sectionPlane as as, startPosition as at, themesEqual as au, viewDirection as av, type EnginePartProps as b, assertSupportedKernelVersion as c, type ViewerTheme as d, type PartModelRegion as e, type ViewerCamera as f, type ViewerView as g, type Projection as h, type PartModelFeature as i, type FeatureType as j, CANDIDATE_WEIGHT as k, DEFAULT_THEME as l, DIRECTION_COLORS as m, normalizePartReport as n, EXCLUDE_FROM_FRAME as o, type FeatureHighlight as p, HIGHLIGHT_COLORS as q, HIGHLIGHT_WEIGHT as r, smoothRegionNormals as s, HOVER_WEIGHT as t, type HighlightLayers as u, PERSPECTIVE_FOV as v, PICKED_SURFACE_LABEL as w, PartMesh as x, type PartMeshProps as y, type PartObject as z };