npm - @toolpath/viewer - Versions diffs - 2.3.0 → 2.3.3 - Mend

@toolpath/viewer 2.3.0 → 2.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +781 -1171
package/dist/{chunk-N54FHMTG.js → chunk-M2B3CQPQ.js} +40 -2
package/dist/engine/index.js +1 -1
package/dist/index.js +242 -94
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,45 +1,103 @@
-# `@toolpath/viewer`
+# Toolpath Viewer
-Show a machined part in 3D in your React app. Users can spin it, zoom in, click a surface to see
-which features own it, cut it open with a section plane, and jump between standard views with a
-view cube.
-It is built on [React Three Fiber](https://r3f.docs.pmnd.rs) and draws parts analyzed by the
-Toolpath Engine. You can also give it your own geometry.
+Display CAD meshes in a React application with feature picking, camera controls,
+stock, section cuts, and measurements. Use `EnginePart` for an analyzed Toolpath
+report, or `PartMesh` for geometry and region/feature data you supply yourself.
+The viewer does not read STEP files, run analysis, or require an API key to render
+local geometry.
 - [Install](#install)
-- [Quick start](#quick-start)
-- [How it works](#how-it-works)
-- [Components](#components)
-- [Recipes](#recipes)
-- [Errors](#errors)
-- [Working with the Toolpath API](#working-with-the-toolpath-api)
-- [Using it without the Engine](#using-it-without-the-engine)
+- [Quick start: Engine report](#quick-start)
+- [Use your own geometry](#using-it-without-the-engine)
+- [Selection and hover](#selection-and-hover)
+- [Components and camera controls](#components)
+- [Toolbar, stock, section, and measurement recipes](#recipes)
+- [Engine loading, caching, and errors](#working-with-the-toolpath-api)
 - [Reference](#reference)
+- [Work on the package](#working-on-this-package)
 ## Install
-```bash
-npm install @toolpath/viewer react react-dom three @react-three/fiber @react-three/drei
+```sh
+npm install @toolpath/viewer
+```
+Your application must provide compatible peers:
+| Dependency           | Declared range |
+| -------------------- | -------------- |
+| `react`, `react-dom` | `^19.0.0`      |
+| `three`              | `>=0.159.0`    |
+| `@react-three/fiber` | `^9.7.0`       |
+| `@react-three/drei`  | `^10.7.8`      |
+For a new application, this is the combination used by the repository's example:
+```sh
+npm install @toolpath/viewer react@19.2.0 react-dom@19.2.0 three@0.185.1 @react-three/fiber@9.7.0 @react-three/drei@10.7.8
+```
+TypeScript applications also need React and three.js types, for example
+`@types/react`, `@types/react-dom`, and `@types/three`. Match the three.js types to
+your installed three.js release. Keep one compatible copy of each renderer/peer
+in your application; React Three Fiber 9 uses React 19.
+This is an ESM package with included TypeScript declarations. Its declared Node
+floor is 20; the tested three.js release needs a browser with WebGL2 support. Use your framework's
+client component boundary for interactive React code and its normal bundler setup.
+See the [React Three Fiber installation guide](https://r3f.docs.pmnd.rs/getting-started/installation)
+for framework-specific setup.
+**Current packaging limitation:** direct, unbundled Node ESM imports of both
+JavaScript entries fail with `CameraControls.install is not a function`. Use an
+application bundler; for SSR, verify the framework's server dependency bundling
+as well as its client component boundary. The declared Node floor does not make
+these entries standalone Node utilities.
+### Styles
+The canvas does not need Tailwind or `@toolpath/ui`. Give the viewer a nonzero
+height. It fills its wrapper, and its transparent canvas shows the background you
+set on the wrapper or parent.
+For the optional toolbar, import its plain CSS through your application's CSS
+entry point or client entry:
+```css
+@import '@toolpath/viewer/toolbar.css';
 ```
+Measurement labels and hover-card content need your own styling; the toolbar
+stylesheet does not style them. See [Measuring](#measuring) and [Theming](#theming).
 ## Quick start
-Pass a part report from the Toolpath API to `<EnginePart>`:
+Pass a completed analysis report to `EnginePart`. It validates the report, loads
+its mesh, and renders the result. It accepts `unknown`, so the viewer does not
+require an SDK dependency just to display a report.
+This example uses [react-error-boundary](https://github.com/bvaughn/react-error-boundary):
+```sh
+npm install react-error-boundary
+```
 ```tsx
 'use client'
 import { Suspense, useState } from 'react'
-import { Axes, Grid, ViewCube, Viewer } from '@toolpath/viewer'
+import { ErrorBoundary } from 'react-error-boundary'
+import { Axes, Grid, ViewCube, Viewer, type FeatureTag } from '@toolpath/viewer'
 import { EnginePart } from '@toolpath/viewer/engine'
-import type { PartResponse } from '@toolpath/api'
-export function PartViewer({ report }: { report: PartResponse }) {
-  const [selection, setSelection] = useState<string[]>([])
+export const PartViewer = ({ report }: { report: unknown }) => {
+  const [selection, setSelection] = useState<Array<FeatureTag>>([])
   return (
-    <ErrorBoundary fallback={<p>This part could not be displayed.</p>}>
+    <ErrorBoundary
+      fallback={<p role="alert">This part could not be displayed.</p>}
+      resetKeys={[report]}
+    >
       <Suspense fallback={<p>Loading part…</p>}>
         <Viewer style={{ height: 500 }} onPointerMissed={() => setSelection([])}>
           <EnginePart
@@ -57,930 +115,537 @@ export function PartViewer({ report }: { report: PartResponse }) {
 }
 ```
-This renders the part with a grid, axes, and a view cube. Clicking a surface selects its most
-likely feature and paints it orange. Clicking empty space clears the selection.
+Suspense supplies loading UI; the error boundary handles invalid report data.
+An accepted analysis job is not a report: finish the API workflow
+before passing its result here. When changing parts/results, key `PartViewer` by
+analysis-result identity to reset selection, the camera, and one-time overlay
+bounds. Refreshing URLs for the same artifact does not require a new key.
-What each wrapper is for:
+## How it works
-- **`<Suspense>`**: `EnginePart` downloads the part's mesh and shows the fallback until it
-  arrives.
-- **Error boundary**: an expired mesh URL or a bad report is thrown as an error, not shown as an
-  empty viewer. Use any error boundary you like, such as
-  [`react-error-boundary`](https://github.com/bvaughn/react-error-boundary). See [Errors](#errors).
-- **Height**: `<Viewer>` fills its parent, so give it or its parent a height.
+- Geometry and tool dimensions are **millimetres**, with **Z up**. Vectors and
+  stock must use the same coordinate frame; converting display units does not
+  change mesh coordinates.
+- Regions identify surfaces and cover half-open triangle ranges `[start, end)`.
+  A feature refers to one or more regions. Several direction-dependent features
+  can share one surface, so a click can have several valid owners.
+- `PartMesh` emits picks and hover information. Your application owns selection,
+  filtering, DFM rules, annotations, and persistence.
+- The viewer frames its content when it first appears and renders on demand.
+  It still renders during interaction and transitions; this is not a zero-cost
+  guarantee for an idle mounted scene. Call `fit()` after later content changes
+  when you want to reframe, or remount the viewer to start a new view.
-## How it works
+## Using it without the Engine
-```text
-<Viewer>                  canvas, camera, lights, mouse controls
- ├─ <EnginePart>          validates the report, loads the mesh, then renders <PartMesh>
- │   └─ <PartMesh>        draws the part and handles hover, click, colours, section cuts
- ├─ <DirectionArrows>     arrows for the directions the part can be machined from
- ├─ <Stock>               translucent geometry, GLB, box or cylinder stock, included in Fit
- ├─ <SectionTool>         optional: click a face or a plane to cut the part open
- ├─ <MeasureTool>         optional: click two points for a distance, three for an angle
- ├─ <Grid> <Axes>         reference geometry, sized to the part
- └─ <ViewCube>            the clickable orientation cube in the corner
-```
+Supply a `PartModel` and a **non-indexed** three.js `BufferGeometry`. Region ranges
+must cover every triangle without gaps or overlaps; `buildRegionIndex` validates
+that mapping. Preserve triangle order when preparing geometry.
-1. **`<Viewer>`** sets up the 3D scene. Put everything else inside it. It frames the camera on
-   whatever you put inside once that content appears. It only redraws when something changes, so
-   a viewer that isn't being used costs nothing.
-2. **`<EnginePart>`** checks the report, downloads the mesh (GLB first, STL if there is no GLB),
-   and makes sure the mesh matches the report. Meshes are cached, so showing the same part twice
-   downloads it once.
-3. **`<PartMesh>`** draws the part as one mesh. The Engine splits the part's surface into
-   **regions** (faces) and groups regions into **features** (holes, pockets, walls, and so on).
-   When the pointer is over the part, `PartMesh` works out which region it is on and which
-   features own that region.
-4. **You own the state.** The viewer tells you what was clicked (`onPick`), and you tell it what to
-   highlight (`selection`, `highlights`, …). It never changes your selection by itself.
-### Focus the current selection
-Pass `focus` to make selected features solid while the remainder of the part becomes translucent.
-The default outside opacity is 15%; set `opacity` for a different X-ray strength. With no selected
-features, the part stays fully opaque.
+This complete example renders a 20 mm cube and disposes the caller-owned geometry
+on unmount:
 ```tsx
-<EnginePart report={report} selection={selection} focus={{ opacity: 0.12 }} />
+import { useEffect, useMemo } from 'react'
+import { BoxGeometry } from 'three'
+import { PartMesh, Viewer, ViewCube, buildRegionIndex, type PartModel } from '@toolpath/viewer'
+export const Cube = () => {
+  const { model, geometry } = useMemo(() => {
+    const indexed = new BoxGeometry(20, 20, 20)
+    const geometry = indexed.toNonIndexed()
+    indexed.dispose()
+    const regions = Array.from({ length: 6 }, (_, idx) => ({
+      idx,
+      splitOrigin: idx,
+      shapeKind: 'Plane',
+      area: 400,
+      triangles: { start: idx * 2, end: idx * 2 + 2 },
+    }))
+    const features = [
+      {
+        tag: 'top',
+        featureType: 'face',
+        machiningDirection: { x: 0, y: 0, z: 1 },
+        axis: null,
+        regionIdxs: [4],
+      },
+    ]
+    const model: PartModel = {
+      partId: 'local-cube',
+      kernelVersion: '',
+      regions,
+      features,
+      candidateDirections: [{ x: 0, y: 0, z: 1 }],
+      mesh: { pointCount: 36, triangleCount: 12, glbUrl: null, stlUrl: null, thumbnailUrl: null },
+      regionIndex: buildRegionIndex({ regions, features, triangleCount: 12 }),
+      warnings: [],
+    }
+    return { model, geometry }
+  }, [])
+  useEffect(() => () => geometry.dispose(), [geometry])
+  return (
+    <Viewer style={{ height: 400 }}>
+      <PartMesh model={model} geometry={geometry} selection={['top']} />
+      <ViewCube />
+    </Viewer>
+  )
+}
 ```
-Parts are in **millimetres** with **Z pointing up**. The camera uses the same convention.
-### A click usually matches several features
-The same face is usually owned by **5–8 features at once**, even on a plain cube: it can be a
-`face` when cut from one direction, a `wall` when cut from another, and part of every `profile`
-around it. So a click gives you every match, and you decide which to use:
-| Field            | What it contains                                                      |
-| ---------------- | --------------------------------------------------------------------- |
-| `pick.best`      | The most likely feature, or `null`                                    |
-| `pick.ranked`    | Every matching feature, most likely first                             |
-| `pick.owners`    | Every matching feature, in report order                               |
-| `pick.region`    | The index of the face that was clicked                                |
-| `pick.point`     | Where the click hit, as `[x, y, z]`                                   |
-| `pick.normal`    | The direction the clicked surface faces, as `[x, y, z]`               |
-| `pick.pointer`   | Browser coordinates for an application-owned hover card, when present |
-| `pick.modifiers` | `{ alt, ctrl, meta, shift, secondary }`: keys held, and right-click   |
-| `pick.doubled`   | `true` if this click was the second half of a double-click            |
-The ranking puts specific features first: holes, then pockets and bosses, then chamfers and
-fillets, then walls and faces, then profiles. Among features of the same kind, the one whose
-machining direction points most toward the camera wins.
-`onHover` receives the same `PartPick` shape. Use the optional `pointer` location yourself, or
-wrap application content in `<HoverCard pick={hoverPick}>`; it follows the cursor while that
-region remains hovered. The viewer intentionally leaves card content and actions to the application.
-Hover feedback is on by default; pass `hover={false}` to disable both face feedback and `onHover`
-callbacks while preserving clicks. That makes an application toolbar's feature-hover toggle
-unambiguous.
-The normalized model contains feature identity, type, directions, face shape, and analytic area.
-An Engine DFM card can join `pick.best` to the part's detailed feature data and render its own
-depth, clearance-diameter, or L/D rows inside `HoverCard`; setup labels remain application or plan
-context rather than a fact of the part surface.
+The feature covers only the top face; surfaces without a feature remain drawable
+and pickable, but have no `pick.best`. An application-supplied model does not go
+through the Engine kernel-version gate. Keep geometry/model references stable
+between renders. `PartMesh` manages its rendering resources, but never disposes
+the input geometry; the caller owns that lifetime.
-## Components
+## Selection and hover
-### Stock and display controls
+Viewer identity is `FeatureTag` (`model.features[i].tag`, sourced from an Engine
+report's `featureTag`). Do not replace it with an array index or an API
+`featureId`. Region indices are local to their report and cannot join unrelated
+results. `FeatureType` and `ShapeKind` allow unknown strings for newer data.
+| `PartPick` field          | Meaning                                                                             |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `best`                    | Highest-ranked feature tag, or `null`.                                              |
+| `ranked`                  | Owners ranked for the camera and active direction.                                  |
+| `owners`                  | All owners in report order, before active-direction filtering.                      |
+| `region`, `triangleIndex` | Surface index and triangle hit.                                                     |
+| `point`, `normal`         | Hit position and outward normal; three-number tuples. The normal is in world space. |
+| `pointer`                 | Optional browser `clientX`/`clientY` for DOM overlays.                              |
+| `modifiers`               | `alt`, `ctrl`, `meta`, `shift`, and `secondary` (right button).                     |
+| `doubled`                 | This pick completed a double-click.                                                 |
+| `sharpCorner`             | Optional corner hit when sharp-corner visualization is enabled.                     |
+`onPick` reports primary and secondary clicks. Decide whether secondary clicks,
+double-clicks, or modifier keys should change selection. Double-click retargeting
+still works independently. `onHover` receives a pick or `null`; `hover={false}`
+disables hover feedback and callbacks while leaving click picking enabled.
-Use `<Stock>` for a box, cylinder, prepared geometry or GLB bytes. Stock and part coordinates
-must use the same millimetre, Z-up frame. Stock is included in Fit and Reset while
-keeping section tools, measurements, the grid, and direction arrows sized to the finished part.
-Stock does not intercept clicks or get clipped by the part's section plane.
+This inspector shares selection between a list and the mesh, cycles overlapping
+owners on repeated clicks, and draws application-owned hover text:
 ```tsx
-import { useMemo, useRef, useState } from 'react'
+import { useState } from 'react'
+import type { BufferGeometry } from 'three'
 import {
-  Axes,
-  Stock,
-  DirectionArrows,
+  HoverCard,
   PartMesh,
   Viewer,
-  directionHighlights,
+  focusForPick,
+  type PartModel,
+  type PartPick,
 } from '@toolpath/viewer'
-import type { PartModel, ViewerHandle } from '@toolpath/viewer'
-import type { BufferGeometry } from 'three'
-export function StockPreview({ model, geometry }: { model: PartModel; geometry: BufferGeometry }) {
-  const viewer = useRef<ViewerHandle>(null)
-  const [stock, setStock] = useState(false)
-  const [axes, setAxes] = useState(true)
-  const [directions, setDirections] = useState(false)
-  const [direction, setDirection] = useState<number | null>(null)
-  const [wireframe, setWireframe] = useState(false)
-  const colors = useMemo(
-    () => (directions ? directionHighlights(model, direction) : []),
-    [model, direction, directions],
-  )
+export const FeatureInspector = ({
+  model,
+  geometry,
+}: {
+  model: PartModel
+  geometry: BufferGeometry
+}) => {
+  const [selected, setSelected] = useState<string | null>(null)
+  const [hovered, setHovered] = useState<string | null>(null)
+  const [pick, setPick] = useState<PartPick | null>(null)
+  const [lastRegion, setLastRegion] = useState<number | null>(null)
   return (
     <>
-      <Viewer ref={viewer} style={{ height: 500 }}>
+      <ul>
+        {model.features.map((feature) => (
+          <li key={feature.tag}>
+            <button
+              type="button"
+              onClick={() => setSelected(feature.tag)}
+              onMouseEnter={() => setHovered(feature.tag)}
+              onMouseLeave={() => setHovered(null)}
+            >
+              {feature.featureType}: {feature.tag}
+            </button>
+          </li>
+        ))}
+      </ul>
+      <Viewer style={{ height: 400 }} onPointerMissed={() => setSelected(null)}>
         <PartMesh
           model={model}
           geometry={geometry}
-          display={wireframe ? 'wireframe' : 'solid'}
-          regionHighlights={colors}
-          activeDirection={directions ? direction : null}
-        />
-        {stock && <Stock box={{ partGeometry: geometry, allowance: { wall: 3, floor: 3 } }} />}
-        {axes && <Axes />}
-        <DirectionArrows
-          directions={model.candidateDirections}
-          visible={directions}
-          shownDirection={direction}
-          onPickDirection={(index) => setDirection((held) => (held === index ? null : index))}
+          selection={selected ? [selected] : []}
+          hoveredFeatureIds={hovered ? [hovered] : []}
+          focusFeature={selected}
+          onHover={setPick}
+          onPick={(next) => {
+            if (next.modifiers.secondary || next.doubled) {
+              return
+            }
+            setSelected(focusForPick(next, lastRegion, selected))
+            setLastRegion(next.region)
+          }}
         />
       </Viewer>
-      <button aria-pressed={stock} onClick={() => setStock(!stock)}>
-        Stock
-      </button>
-      <button aria-pressed={axes} onClick={() => setAxes(!axes)}>
-        Axes
-      </button>
-      <button aria-pressed={directions} onClick={() => setDirections(!directions)}>
-        By direction
-      </button>
-      <button aria-pressed={wireframe} onClick={() => setWireframe(!wireframe)}>
-        Wireframe
-      </button>
-      <button onClick={() => viewer.current?.fit()}>Fit</button>
+      <HoverCard pick={pick}>
+        {(current) => <span>{current.best ?? `Region ${current.region}`}</span>}
+      </HoverCard>
     </>
   )
 }
 ```
-For a box preview, pass `box={{ partGeometry, allowance, offset }}`. Allowance is padding
-**per side**, in millimetres. The preferred form is
-`{ wall, floor }`: wall stock expands X/Y and floor stock expands Z, matching the wall/floor
-roughing-stock distinction used by machining settings. A number or `{ x, y, z }` remains accepted
-for uniform or axis-specific padding. It defaults to zero. `offset` translates the stock from the
-part's bounding-box centre. `boxStockBounds(geometry, allowance, offset)` returns the same `Box3`
-for displaying dimensions.
-For fixed-box previews, pass `box={{ partGeometry, dimensions, position, positionOffset, offset }}`
-instead, where `dimensions` is `{ x, y, z }`. Dimensions and allowance are alternative sizing
-modes, not simultaneous options. `position` accepts
-`model_centered`, `offset_from_top`, or `offset_from_bottom`, and `positionOffset` is the distance
-from the selected top or bottom bound. All fixed-box values use millimetres and the part's Z-up
-coordinate frame.
-Negative/non-finite allowances, non-finite coordinates, and empty or non-positive stock dimensions
-throw `RangeError`. The 3 mm allowance above is an example, not an automatic stock recommendation.
-`<Stock cylinder={{ origin, axis, diameter, length }} />` draws round stock along any axis:
-`origin` is the centre of its base and `axis` points from the base toward its far end, in part
-coordinates. For a preview, pass
-`cylinder={{ partGeometry, diameter, length, position, positionOffset }}` instead. It stands along
-the part's Z, is centred on the part's bounding box, and is placed along Z by the same `position`
-rule as fixed-box stock. The kernel centres fixed round stock on the part's
-smallest enclosing circle about the first setup's cutting direction, so render the resolved stock
-once a job is planned.
-`<Stock box={{ frame, lower, upper }} />` draws a block whose corners are given in a frame
-of `location`, `axis` and `refDirection`: a point `(x, y, z)` sits at
-`location + x·refDirection + y·(axis × refDirection) + z·axis`, with `axis` normalised and
-`refDirection` projected square to it and normalised. That is the shape of an Engine plan's
-`stock.resolved` box, which is squared to the setup rather than to the part. Omit `frame` when
-`lower` and `upper` are already in part coordinates. Resolved placement and `partGeometry`
-preview options are mutually exclusive for both shapes.
-Box and cylinder sources rebuild their mesh only when their figures/options change (or the
-preview's `partGeometry` reference changes). Inline option objects do not trigger repeated part
-scans on ordinary renders. Figures that cannot make a
-solid — a zero axis, a non-positive size, a frame whose axis and reference direction are parallel —
-throw `RangeError`.
-`Stock` accepts exactly one of `geometry`, `glb`, `box` or `cylinder`:
-```tsx
-<Stock geometry={geometry} showEdges={false} />
-// Or:
-<Stock glb={glbBytes} showEdges={false} />
-<Stock box={resolvedBox} />
-<Stock cylinder={resolvedCylinder} />
-<Stock box={{ partGeometry, dimensions, position, positionOffset }} />
-<Stock cylinder={{ partGeometry, diameter, length, position, positionOffset }} />
-```
-All four inputs are mutually exclusive in `StockProps`. With `geometry`, the caller owns its
-lifetime and disposal. With `box` or `cylinder`, `Stock` owns the generated geometry. With `glb`,
-`Stock` decodes the bytes internally and disposes decoded
-geometry when the bytes change or the component unmounts. Keep the same `ArrayBuffer` reference
-while displaying the same artifact to avoid decoding it again on ordinary renders.
-It renders nothing while decoding and throws decoding failures to the nearest error boundary.
-Changing the source immediately hides the previous stock; late results from an earlier decode
-are discarded and cleaned up.
-The component does not fetch, cache or store artifacts. The caller supplies the bytes.
-GLB node transforms are applied without centering, rescaling or changing axes:
-Engine stock artifacts are already in part coordinates, millimetres and Z-up. Indexed geometry
-stays indexed; missing normals are computed without requiring a part report. The parser cleans up
-its temporary scene after preparing the returned geometry.
-Engine stock files are plain GLB served with HTTP gzip, which the browser handles automatically;
-no meshopt decoder is needed. Authentication, durable artifact copies, action selection and
-missing-artifact fallback and artifact caching belong to the application. The example's
-**Stock source → GLB fixture** option exercises synthetic blanks encoded by the services stock
-writer. **Shape preview** exposes the separate box/cylinder shape controls.
-`Stock` accepts `color`, `emissive` (default black), `flatShading` (default `false`),
-`opacity` (default `0.2`), `edgeColor`, `edgeOpacity`, and `showEdges`. Emissive shading
-and flat shading change only the material, not the source's vertices, indices or normals.
-`renderStyle="legacy-workpiece"` reproduces legacy Workpiece rendering: white with dark emissive
-shading, per-face shading, 20% opacity, two shared-geometry surface passes and black 50%-opacity
-edges drawn before surfaces (rather than over them). The default `overlay` style is unchanged.
-For action-to-action playback, `retainPrevious` keeps the current decoded GLB visible until
-the next GLB is ready, then swaps meshes without a blank frame. Key the stock's parent by
-part/calculation identity (not action) to prevent retaining geometry across unrelated runs.
-The default still hides the previous source during decoding. Geometry is disposed after a
-replacement commits; cancelled/late results are discarded.
-The outline is built the first time it is shown, so a large stock mesh with `showEdges={false}`
-costs no edge pass. All source types accept the same appearance props. Caller-provided geometry is never disposed; the
-components dispose their own materials and outlines. Conditionally mount stock to toggle it.
-Toggling stock preserves the camera; Fit/Reset then frames the visible stock together with the part.
-**Migration from 1.x:** `BoxStock` and `BoxStockProps` have been removed. Use
-`<Stock box={{ partGeometry, allowance, offset }} />` for allowance-based previews, or
-`<Stock box={{ partGeometry, dimensions, position, positionOffset, offset }} />` for fixed
-dimensions. No preview-builder helper is required. `Stock geometry={geometry}` remains supported.
-`StockProps` is now a union type alias, so `interface X extends StockProps` becomes
-`type X = StockProps & { … }`; `StockAppearanceProps` names the shared appearance props alone.
-`directionHighlights(model, activeDirection?)` returns region colors in the same palette as
-`DirectionArrows`. For a face with several owners, the most specific feature wins, followed by
-candidate-direction order and feature tag. Unmatched directions are left unpainted. Hover and
-selection still paint over this wash. Scoping by direction filters ownership; it does not hide
-the rest of the model or claim that an unpainted face cannot be manufactured.
-Wireframe keeps the existing semantic edges, including rear edges, and keeps faces available for
-picking, measuring, and section placement. Highlighted faces and section caps remain visible.
-`showEdges` controls solid-mode outlines; wireframe always shows them. The example's bottom toolbar
-makes wireframe and direction coloring mutually exclusive and includes a direction legend and
-contextual Section/Measure controls.
-### `<ViewerToolbar>`
-`ViewerToolbar` is a composable, viewer-scoped toolbar for camera, display, section, and measurement
-controls. Import its stylesheet alongside your application stylesheet:
-```tsx
-import '@toolpath/viewer/toolbar.css'
-import { ViewerToolbar, ViewerToolbarProvider } from '@toolpath/viewer'
-```
-Give `ViewerToolbarProvider` the current values and callbacks from the host app, then place the
-toolbar and viewer inside it. The toolbar owns no application state or behavior: it only reads the
-provider. Omit `children` for every configured control in the standard order, or compose the
-individual buttons to use only the controls and order your application needs.
+`HoverCard` is a DOM element; keep it outside the canvas and style its contents.
+`focusFeature` frames the feature when its value changes. The `focus` prop is
+different: `focus={{ opacity: 0.12 }}` makes regions outside `selection`
+translucent. Its default outside opacity is 0.15, and an empty selection leaves
+the part opaque. For multiselection, update your own tag array and avoid duplicates.
-```tsx
-<ViewerToolbarProvider
-  controls={{
-    stock: { pressed: showStock, onClick: () => setShowStock((shown) => !shown) },
-    measure: { pressed: measuring, onClick: toggleMeasuring },
-    fit: { onClick: () => viewer.current?.fit() },
-  }}
->
-  <ViewerToolbar>
-    <ViewerToolbar.Controls>
-      <ViewerToolbar.MeasureButton />
-      <ViewerToolbar.Divider />
-      <ViewerToolbar.StockButton />
-      <ViewerToolbar.FitButton />
-    </ViewerToolbar.Controls>
-  </ViewerToolbar>
-  <Viewer ref={viewer}>…</Viewer>
-</ViewerToolbarProvider>
-```
+## Components
-`ViewerToolbar.Controls`, `Divider`, and the sixteen `*Button` components are available on
-`ViewerToolbar`: `StockButton`, `AxesButton`, `GridButton`, `BananaButton`, `ToolsButton`, `DirectionsButton`,
-`DfmButton` (shows or hides an application's DFM flags), `SharpCornersButton`, `HoverButton`, `FocusButton`, `WireframeButton`, `SectionButton`, `MeasureButton`, `FitButton`,
-`ResetButton`, and `TopButton`. A rendered button requires its matching provider control. For an
-application-specific toolbar component, `useViewerToolbar()` reads the same controls from inside
-the provider.
-#### Styling hooks
-Every viewer, hover-card, and toolbar DOM boundary has a stable class name. Your `className` on
-`<Viewer>`, `<ViewerToolbar>`, or `<HoverCard>` is appended to the component's own class; it never
-replaces the hook. The toolbar stylesheet uses the same names, so import it for the default look or
-override any of these selectors in your application stylesheet.
-| Component         | Class                     | Element                           |
-| ----------------- | ------------------------- | --------------------------------- |
-| `<Viewer>`        | `viewer-root`             | Wrapper around the canvas         |
-| `<Viewer>`        | `viewer-canvas-container` | R3F canvas event container        |
-| `<Viewer>`        | `viewer-canvas-frame`     | R3F's canvas-sizing frame         |
-| `<Viewer>`        | `viewer-canvas`           | The `<canvas>` itself             |
-| `<HoverCard>`     | `viewer-hover-card`       | Cursor-following tooltip shell    |
-| `<ViewerToolbar>` | `viewer-toolbar-stack`    | Outer toolbar stack               |
-| `<ViewerToolbar>` | `viewer-toolbar`          | Controls group                    |
-| `<ViewerToolbar>` | `viewer-toolbar-button`   | Each standard control button      |
-| `<ViewerToolbar>` | `viewer-toolbar-icon`     | SVG within a standard control     |
-| `<ViewerToolbar>` | `viewer-toolbar-tooltip`  | Label shown on button hover/focus |
-| `<ViewerToolbar>` | `viewer-toolbar-divider`  | Separator between control groups  |
-The following `data-*` attributes identify generated elements without depending on labels, which
-can change with state or localization:
-| Attribute                             | Element and values                                                                                                                                                              |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data-viewer-root="true"`             | `<Viewer>` wrapper                                                                                                                                                              |
-| `data-viewer-canvas-container="true"` | R3F canvas event container                                                                                                                                                      |
-| `data-viewer-canvas-frame="true"`     | R3F canvas-sizing frame                                                                                                                                                         |
-| `data-viewer-canvas="true"`           | The `<canvas>` itself                                                                                                                                                           |
-| `data-viewer-hover-card="true"`       | `<HoverCard>` shell                                                                                                                                                             |
-| `data-viewer-toolbar="true"`          | Toolbar stack                                                                                                                                                                   |
-| `data-viewer-toolbar-controls="true"` | Controls group                                                                                                                                                                  |
-| `data-viewer-toolbar-action`          | Standard button: `stock`, `axes`, `grid`, `banana`, `tools`, `directions`, `dfm`, `sharpCorners`, `hover`, `focus`, `wireframe`, `section`, `measure`, `fit`, `reset`, or `top` |
-| `data-viewer-toolbar-icon="true"`     | Standard button SVG                                                                                                                                                             |
-| `data-viewer-toolbar-tooltip="true"`  | Standard button tooltip                                                                                                                                                         |
-| `data-viewer-toolbar-divider="true"`  | Toolbar separator                                                                                                                                                               |
-Toggle buttons also carry standard `aria-pressed="true"` or `"false"`; use that to style their
-current state. `Fit`, `Reset`, and `Top view` are actions rather than toggles, so they omit the
-attribute.
+| Component                    | Purpose                                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `Viewer`                     | Canvas, camera, lighting, controls, initial framing, and viewer-owned section state. |
+| `EnginePart`                 | Validated Engine report plus cached mesh loading; imports from `/engine`.            |
+| `PartMesh`                   | Your normalized model and prepared geometry; selection, paint, picking, sections.    |
+| `ViewCube`                   | 26 orientation targets: faces, edges, and corners.                                   |
+| `Grid`, `Axes`               | Reference geometry excluded from camera framing.                                     |
+| `DirectionArrows`            | Candidate and optional named/preview machining directions.                           |
+| `Stock`                      | Geometry, GLB bytes, box, or cylinder stock.                                         |
+| `SectionTool`, `SectionView` | Interactive section placement or a supplied section visualization.                   |
+| `MeasureTool`                | Distance/angle picking and labels.                                                   |
+| `ToolMarks`                  | Supplied cutter/profile geometry and labels; no datasheet inference.                 |
+| `Banana`                     | Optional bundled 154 mm scale reference; loads its GLB on mount and suspends.        |
+| `CadCameraControls`          | Lower-level camera controls for custom R3F scenes. `Viewer` already installs them.   |
+| `ViewerToolbar`              | DOM controls configured through `ViewerToolbarProvider`.                             |
+| `HoverCard`                  | Cursor-following DOM content for a pick.                                             |
 ### `<Viewer>`
-The canvas that holds everything. Import it from `@toolpath/viewer`.
-| Prop                    | Default          | What it does                                                                                                |
-| ----------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
-| `projection`            | `'orthographic'` | `'orthographic'` keeps parallel lines parallel. `'perspective'` gives depth, which helps with deep pockets. |
-| `controls`              | `'toolpath'`     | CAD navigation preset. See [CAD controls](#cad-controls).                                                   |
-| `zoomTo`                | `'cursor'`       | Zoom toward the pointer, or toward `'centre'` (often easier on a trackpad).                                 |
-| `freeOrbit`             | `true`           | Let the view keep rotating past straight-up and straight-down.                                              |
-| `retargetOnDoubleClick` | `true`           | Double-click the part to rotate around that point.                                                          |
-| `recentreOnDoubleClick` | `true`           | Double-click the middle mouse button to fit the whole part again.                                           |
-| `showOrbitTarget`       | `false`          | Show a small marker at the point the view rotates around.                                                   |
-| `theme`                 | —                | Override lighting and colours. See [Theming](#theming).                                                     |
-| `onPointerMissed`       | —                | Called when a left-click hits nothing. Clear your selection here.                                           |
-| `className`, `style`    | —                | Applied to the wrapping `<div>`. It fills its parent by default.                                            |
-| `ref`                   | —                | A `ViewerHandle` for moving the camera. See [Camera buttons](#camera-buttons).                              |
-Changing `projection` rebuilds the canvas and returns the camera to its starting view.
-The canvas is transparent. To set a background colour, style the wrapper or its parent.
+| Prop                    | Default           | Behavior                                                                              |
+| ----------------------- | ----------------- | ------------------------------------------------------------------------------------- |
+| `projection`            | `orthographic`    | `perspective` is also supported. Changing it remounts the canvas and resets the view. |
+| `controls`              | `toolpath`        | Navigation preset, independent of projection.                                         |
+| `zoomTo`                | `cursor`          | Zoom toward the pointer or `centre`.                                                  |
+| `freeOrbit`             | `true`            | Allow rotation through the poles.                                                     |
+| `retargetOnDoubleClick` | `true`            | Double-click a part to move the orbit target there.                                   |
+| `recentreOnDoubleClick` | `true`            | Double middle-click to fit content.                                                   |
+| `showOrbitTarget`       | `false`           | Show the pivot marker.                                                                |
+| `theme`                 | Default lighting  | Override lighting; part/cube/tool colors have their own theme props.                  |
+| `onPointerMissed`       | —                 | Empty-space primary click, with drag guarding; use it to clear selection.             |
+| `style`, `className`    | Full-size wrapper | Set dimensions and background on the wrapper or parent.                               |
+| `ref`                   | —                 | `ViewerHandle` for controls outside the canvas.                                       |
+`ViewerHandle` exposes `fit()`, `reset()`, `setView(name)`,
+`setViewDirection({ x, y, z })`, `frameBox(box)`, and `setSection(options | null)`.
+`fit` and `frameBox` preserve view direction; `reset` returns to the opening view.
+Named views are `top`, `bottom`, `front`, `back`, `left`, `right`, and `isometric`.
+Direction vectors point from the part toward the camera.
 #### CAD controls
-`controls` changes only the navigation gestures. It does not choose a projection: the viewer stays
-orthographic by default, and `projection="perspective"` remains an independent opt-in.
+| Preset               | Rotate                                          | Pan                             | Zoom                        |
+| -------------------- | ----------------------------------------------- | ------------------------------- | --------------------------- |
+| `toolpath`           | Left-drag                                       | Right-drag                      | Wheel                       |
+| `fusion`, `inventor` | Shift + middle-drag / Shift + two-finger scroll | Middle-drag / two-finger scroll | Trackpad pinch              |
+| `alias`              | Left-drag                                       | Middle-drag                     | Wheel                       |
+| `solidworks`         | Middle-drag                                     | Ctrl + middle-drag              | Shift + middle-drag / wheel |
+| `tinkercad`          | Right-drag                                      | Shift + right-drag              | Wheel                       |
+| `powermill`          | Middle-drag                                     | Shift + middle-drag             | Wheel                       |
+| `onshape`            | Right-drag                                      | Middle-drag                     | Wheel                       |
-| Value          | Label      | Rotate                                | Pan                                       | Zoom                                |
-| -------------- | ---------- | ------------------------------------- | ----------------------------------------- | ----------------------------------- |
-| `'toolpath'`   | Toolpath   | Left-drag                             | Right-drag                                | Scroll wheel                        |
-| `'fusion'`     | Fusion     | Shift + middle-drag or Shift + scroll | Middle-drag, scroll, or two-finger scroll | Trackpad pinch                      |
-| `'alias'`      | Alias      | Left-drag                             | Middle-drag                               | Scroll wheel                        |
-| `'inventor'`   | Inventor   | Shift + middle-drag or Shift + scroll | Middle-drag, scroll, or two-finger scroll | Trackpad pinch                      |
-| `'solidworks'` | SolidWorks | Middle-drag                           | Ctrl + middle-drag                        | Shift + middle-drag or scroll wheel |
-| `'tinkercad'`  | Tinkercad  | Right-drag                            | Shift + right-drag                        | Scroll wheel                        |
-| `'powermill'`  | PowerMill  | Middle-drag                           | Shift + middle-drag                       | Scroll wheel                        |
-| `'onshape'`    | Onshape    | Right-drag                            | Middle-drag                               | Scroll wheel                        |
-Fusion and Inventor treat a two-finger scroll as pan, Shift + two-finger scroll as orbit, and a
-pinch (a wheel event with Ctrl set by the browser) as zoom. Other schemes use one-finger rotate,
-two-finger pinch-and-pan, and three-finger pan on touch screens.
-All schemes support double-clicking the part to rotate around that point and double-clicking the
-middle mouse button to fit the whole part. Dragging never selects anything; a click only counts if
-the pointer barely moved.
-The package exports `CONTROL_SCHEME_OPTIONS`, `ControlScheme`, and `ControlSchemeOption` for a host
-application's settings UI. It deliberately stores no preferences: pass the selected `controls`,
-`freeOrbit`, and `zoomTo` values to `<Viewer>` from your own state or persistence layer.
-`'toolpath'`, `freeOrbit={true}`, and `zoomTo="cursor"` are the defaults.
+`CONTROL_SCHEME_OPTIONS` supplies labels/values for a settings UI. Preferences are
+application-owned. Default touch controls use one-finger rotation, two-finger
+pinch/pan, and three-finger pan; Fusion/Inventor use their CAD scroll behavior.
 ### `<EnginePart>`
-Draws a Toolpath Engine part report. Import it from `@toolpath/viewer/engine`.
-It takes one prop of its own, `report`: the `PartResponse` from `@toolpath/api`, unchanged. All
-other props are the same as `<PartMesh>`'s, except `model` and `geometry`, which it creates for
-you.
-Mesh URLs in a report expire **15 minutes** after the report was created. If a part may be shown
-later than that, fetch a fresh report first. Don't save the URLs.
+`report` is its only additional prop. It inherits `PartMeshProps` except `model`
+and `geometry`, which it creates. Mesh loading prefers GLB and tries STL if GLB
+fails or is absent. It does not fetch a report or start an Engine job.
 ### `<PartMesh>`
-Draws the part and handles clicks. You only use it directly when you
-[don't use the Engine](#using-it-without-the-engine). All of these props also work on
-`<EnginePart>`.
-**Colours**
-| Prop                | Type                                  | What it does                                                                                          |
-| ------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `selection`         | `string[]`                            | Feature tags to highlight as selected (orange).                                                       |
-| `highlights`        | `FeatureHighlight[]`                  | Your own colour per feature, e.g. difficulty or setup.                                                |
-| `regionHighlights`  | `RegionHighlight[]`                   | Your own colour per face.                                                                             |
-| `candidates`        | `string[]`                            | Other possible matches, faintly tinted by machining direction.                                        |
-| `pickedRegions`     | `number[]`                            | Faces to mark as just clicked.                                                                        |
-| `hoveredFeatureIds` | `string[]`                            | Features to show as hovered, e.g. when hovering a list row.                                           |
-| `showEdges`         | `boolean` (`true`)                    | Draw outlines between faces.                                                                          |
-| `sharpCorners`      | `SharpCornerOptions \| null` (`null`) | Draw the sharp corners the DFM rules flag. See [Showing sharp corners](#showing-sharp-corners).       |
-| `display`           | `'solid' \| 'wireframe'` (`'solid'`)  | Wireframe draws face boundaries without triangle diagonals. Painted and hovered faces remain visible. |
-| `theme`             | `Partial<ViewerTheme>`                | Override the part's colours.                                                                          |
-**Interaction**
-| Prop              | Type                               | What it does                                                                                    |
-| ----------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `onPick`          | `(pick: PartPick) => void`         | Left- or right-click on the part.                                                               |
-| `onHover`         | `(pick: PartPick \| null) => void` | The pointer moved onto a different face, or off the part (`null`).                              |
-| `hover`           | `boolean` (`true`)                 | Paint and report faces under the pointer. `false` leaves click picking on and clears any hover. |
-| `activeDirection` | `number \| null`                   | Only match features machined from this direction (an index into `candidateDirections`).         |
-| `focusFeature`    | `string \| null`                   | Zoom to this feature. The camera moves each time the value changes.                             |
-| `section`         | `SectionOptions`                   | Cut the part open. Omit it to follow the viewer's own cut. See [Section view](#section-view).   |
-| `onSectionChange` | `(state: SectionState) => void`    | Called when the cut moves or goes away. With `section`, passing it also shows the drag handle.  |
-| `onAdjacency`     | `(map) => void`                    | Called once per mesh with which faces touch which.                                              |
-| `children`        | `ReactNode`                        | Objects drawn on the part. They read its model and mesh with `usePartContext()`.                |
-Hovering over the part is handled for you. You only need `onHover` if you want to show the hovered
-feature elsewhere in your UI.
-### `<ViewCube>`
-The orientation cube in the corner. It has 26 clickable areas: 6 faces, 12 edges, and 8 corners,
-so you can get an isometric view with one click.
-```tsx
-<ViewCube alignment="bottom-right" margin={[60, 60]} onViewChange={(view) => track(view)} />
-```
-| Prop           | Default       |                                                                |
-| -------------- | ------------- | -------------------------------------------------------------- |
-| `alignment`    | `'top-right'` | `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'` |
-| `margin`       | `[80, 80]`    | Distance from the corner, in pixels                            |
-| `onViewChange` | —             | Called with the view name, e.g. `'top-front-right'`            |
-| `theme`        | —             | Cube colours                                                   |
-### `<DirectionArrows>`
-An arrow for each direction the part can be machined from. Each direction has its own colour, and
-features machined from that direction use the same colour. The arrows point **at** the part,
-because that is the direction the tool comes from.
-```tsx
-<DirectionArrows
-  directions={model.candidateDirections}
-  activeDirection={direction}
-  onPickDirection={(index) => setDirection(index === direction ? null : index)}
-/>
-```
-| Prop               | What it does                                                                         |
-| ------------------ | ------------------------------------------------------------------------------------ |
-| `directions`       | The report's `candidateDirections`.                                                  |
-| `activeDirection`  | Show only this arrow.                                                                |
-| `shownDirection`   | Which arrows to show: `null` for all, an index, a list of indices, or `-1` for none. |
-| `previewDirection` | An extra arrow drawn on top of the part, e.g. while the user aims a new direction.   |
-| `namedDirections`  | Extra directions that aren't candidates, each with its own colour.                   |
-| `onPickDirection`  | Called with an arrow's index when it is clicked.                                     |
-| `visible`          | Hide all arrows.                                                                     |
-Clicking an arrow does not trigger `onPointerMissed`, so it won't clear your selection.
-With the Engine, get the directions from the model:
-`const model = useMemo(() => normalizePartReport(report), [report])`.
-### `<SectionTool>`
-Cut the part open from inside the viewport. Optional: mount it next to the part when the user
-enters section mode, and unmount it when they leave.
-```tsx
-{
-  sectioning ? <SectionTool /> : null
-}
-```
-While it is up, hovering the part previews a cut through the face under the pointer and a click
-places it; three coloured planes behind the part cut along an axis instead. Once there is a cut,
-the part's own arrow drags it, an outlined sheet shows the cutting plane, and Escape clears it.
-| Prop    | What it does                                                           |
-| ------- | ---------------------------------------------------------------------- |
-| `theme` | Override its colours — `sectionOutline` for the sheet and the preview. |
-The cut it places is the viewer's own, and `<PartMesh>` follows it when given no `section` prop.
-While the tool is mounted the part reports no hovers or picks. Details and the controlled
-alternative are under [Section view](#section-view).
-### `<MeasureTool>`
-Measure the part from inside the viewport. Optional: mount it next to the part when the user
-enters measure mode, and unmount it when they leave.
-```tsx
-{
-  measuring ? <MeasureTool mode="distance" onChange={setMeasurements} /> : null
-}
-```
-The pointer snaps to what is under it — a corner first, then an edge's midpoint, then the edge,
-then the face — and a marker shows where the click will land. Two clicks measure a distance, three
-an angle (one arm's end, the vertex, the other arm's end), with a live readout between clicks.
-Finished measurements stay drawn over the part, each with a label, until Delete removes the last
-one or the tool is unmounted. Escape drops the points of one in progress, and Shift holds the next
-point to an axis through the last.
-| Prop             | What it does                                                                                  |
-| ---------------- | --------------------------------------------------------------------------------------------- |
-| `mode`           | `'distance'` (default) or `'angle'`. Changing it drops any points already placed.             |
-| `measurements`   | Own the list. Omit it and the tool keeps its own.                                             |
-| `onChange`       | The list changed: a measurement finished, or Delete removed the last one.                     |
-| `showDeltas`     | Show a distance's X, Y and Z parts as dashed legs in the axis colours. On by default.         |
-| `format`         | Write a length. Millimetres to two places by default; pass your own to show inches.           |
-| `labelClassName` | Added to every label, beside `toolpath-measure-label`.                                        |
-| `theme`          | Override its colours — `measure` for lines and markers, `measureSnap` for the snap indicator. |
-Labels are DOM elements laid over the canvas and come **unstyled**: the tool is headless, and
-what a label looks like is your stylesheet's, through the `toolpath-measure-label` class and the
-data attributes on each one — see [Measuring](#measuring) for a starting point. While the tool is
-mounted the part reports no hovers or picks, as with `<SectionTool>`.
-### `<ToolMarks>`
-Cutting tools drawn on the part, each to scale where it stands: a see-through end mill — flat,
-bull nose or ball — or any tool given by its profile, rimmed at its bottom and top, with a dimension
-across its top and a label on it. What a tool stands for is yours: the widest tool a pocket admits, the tool an operation uses.
-Nothing here reads a datasheet.
-```tsx
-<EnginePart report={report}>
-  <ToolMarks
-    marks={[
-      {
-        base: { x: 12, y: 4, z: -8 },
-        axis: { x: 0, y: 0, z: 1 },
-        diameter: 6,
-        height: 8,
-        cornerRadius: 0.5,
-        label: '⌀ 6.000 mm',
-        note: 'bull nose R 0.5',
-      },
-    ]}
-  />
-</EnginePart>
-```
-| Prop             | What it does                                                                       |
-| ---------------- | ---------------------------------------------------------------------------------- |
-| `marks`          | The tools, in the coordinates the part is drawn in. See `ToolMark` below.          |
-| `visible`        | `false` hides them without unmounting. On by default.                              |
-| `labelClassName` | Added to every label, beside `toolpath-measure-label`.                             |
-| `theme`          | `measure` colours the rims and the dimension, as it does the measure tool's lines. |
-A `ToolMark` is `base` (the centre of the tool's bottom), `axis` (up the tool), `diameter`,
-`height`, and optionally `cornerRadius` (0 flat, half the diameter a ball), `across` (which way the
-dimension runs; any direction square to the axis otherwise), `label` and `note`. Any other tool —
-a drill, a chamfer mill, a tool in its holder — takes `profile`: its side as `{ r, z }` points from
-the tip up, such as `@toolpath/tool-drawing`'s outline, turned about the axis in place of the end
-mill.
-Show and hide them with `visible`, from the toolbar's `ToolsButton` and its `tools` control.
-It draws as `<MeasureTool>` draws: the lines show through the part, and each label is an unstyled
-`<div class="toolpath-measure-label" data-measure-label="tool">` with its text in a
-`data-measure-value` span and its note in a `data-measure-note` one. The marks take no pointer
-events and are left out of framing.
-Inside `<PartMesh>` or `<EnginePart>`, `usePartContext()` gives the part's `model` and `geometry`,
-and `featureTriangles(model, geometry, tag)` a feature's triangles, for working out where a tool
-stands.
-### `<Grid>` and `<Axes>`
-Reference geometry. The camera ignores both when it frames the part.
-- **`<Grid>`** sits under the part and sizes itself to it: 5 mm squares under a 50 mm cube, 50 mm
-  squares under a 900 mm plate. Props: `step` (square size in mm), `extent`, `color`,
-  `opacity` (default `0.35`).
-- **`<Axes>`** draws X (red), Y (green), and Z (blue) from the origin. Prop: `size` (default `25`).
+| Props                                | Behavior                                                                                                              |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `model`, `geometry`                  | Required normalized data and non-indexed geometry.                                                                    |
+| `selection`, `candidates`            | Selected feature tags and secondary candidates.                                                                       |
+| `highlights`, `regionHighlights`     | Feature/region colors. Hover and selection overlay the direction wash.                                                |
+| `pickedRegions`, `hoveredFeatureIds` | Application-driven region/feature feedback.                                                                           |
+| `hover`, `onHover`, `onPick`         | Hover enablement and interaction callbacks.                                                                           |
+| `focus`, `focusFeature`              | Selection X-ray rendering versus camera framing.                                                                      |
+| `activeDirection`                    | Candidate-direction index; `null`/omitted means all directions.                                                       |
+| `display`, `showEdges`               | `solid` or `wireframe`; outlines default on. Wireframe always shows semantic face boundaries, not triangle diagonals. |
+| `sharpCorners`                       | `{ features: tags }` for externally flagged features, or `null`.                                                      |
+| `section`, `onSectionChange`         | Controlled section options and change reporting. Omit `section` to follow the viewer's section store.                 |
+| `onAdjacency`                        | Receive touching-region sets for the prepared mesh.                                                                   |
+| `theme`                              | Partial `ViewerTheme` for the part.                                                                                   |
+| `children`                           | R3F overlays that can read `usePartContext()`.                                                                        |
+With an active direction, picking ranks only reachable owners; a face with none
+has `best === null`. `owners` still carries all owners. `directionHighlights(model,
+index)` produces region paint matching `DirectionArrows`; it does not hide geometry
+or establish that an unpainted face is impossible to machine.
+### `<ViewCube>`, `<Grid>`, and `<Axes>`
+`ViewCube` defaults to `alignment="top-right"` and `margin={[80, 80]}` (pixels).
+`onViewChange` receives a `ViewName`, including diagonal names. Its theme controls
+cube colors. Grid chooses a step from part size unless you supply `step`/`extent`;
+it accepts `color` and `opacity` (default 0.35). Axes has a `size` in millimetres
+(default 25). These controls/reference objects do not enlarge normal part framing.
 ## Recipes
-### Camera buttons
+### Toolbar and camera buttons
-Use a ref to move the camera from buttons outside the viewer:
+This scene uses caller-owned geometry. The provider supplies actions; it does not
+implement toggling, persistence, measurement state, or stock creation for you.
+The containing DOM element is positioned so the toolbar sits over this viewer.
 ```tsx
-import { useRef } from 'react'
-import { Viewer, type ViewerHandle } from '@toolpath/viewer'
-const viewer = useRef<ViewerHandle>(null)
-<button onClick={() => viewer.current?.fit()}>Fit</button>
-<button onClick={() => viewer.current?.reset()}>Reset</button>
-<button onClick={() => viewer.current?.setView('top')}>Top</button>
-<button onClick={() => viewer.current?.setView('isometric')}>Iso</button>
-<Viewer ref={viewer}>…</Viewer>
-```
-| Method                      | What it does                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------ |
-| `fit()`                     | Fit the whole part, keeping the current angle.                                 |
-| `reset()`                   | Go back to the starting view.                                                  |
-| `setView(name)`             | `'top'`, `'bottom'`, `'front'`, `'back'`, `'left'`, `'right'`, `'isometric'`   |
-| `setViewDirection({x,y,z})` | Look at the part from any direction (a vector pointing toward the camera).     |
-| `frameBox(box)`             | Zoom to a `THREE.Box3`, keeping the current angle.                             |
-| `setSection(options)`       | Set or clear (`null`) the viewer's own cut. See [Section view](#section-view). |
-Components rendered **inside** `<Viewer>` can get the same methods with `useViewerControls()`.
-### Selecting from a list
+import { useRef, useState } from 'react'
+import type { BufferGeometry } from 'three'
+import {
+  Axes,
+  Grid,
+  MeasureTool,
+  PartMesh,
+  SectionTool,
+  Stock,
+  ViewCube,
+  Viewer,
+  ViewerToolbar,
+  ViewerToolbarProvider,
+  type Measurement,
+  type PartModel,
+  type ViewerHandle,
+} from '@toolpath/viewer'
+import '@toolpath/viewer/toolbar.css'
-Keep the selection in your own state and share it between a feature list and the part. Hovering a
-list row highlights the feature on the part, and clicking the row zooms to it:
+export const Workbench = ({ model, geometry }: { model: PartModel; geometry: BufferGeometry }) => {
+  const viewer = useRef<ViewerHandle>(null)
+  const [stock, setStock] = useState(false)
+  const [mode, setMode] = useState<'section' | 'measure' | null>(null)
+  const [measurements, setMeasurements] = useState<readonly Measurement[]>([])
+  const toggle = (next: 'section' | 'measure') =>
+    setMode((current) => (current === next ? null : next))
-```tsx
-const [selected, setSelected] = useState<string | null>(null)
-const [hovered, setHovered] = useState<string | null>(null)
-<ul>
-  {model.features.map((feature) => (
-    <li
-      key={feature.tag}
-      onMouseEnter={() => setHovered(feature.tag)}
-      onMouseLeave={() => setHovered(null)}
-      onClick={() => setSelected(feature.tag)}
+  return (
+    <ViewerToolbarProvider
+      controls={{
+        stock: { pressed: stock, onClick: () => setStock((shown) => !shown) },
+        section: { pressed: mode === 'section', onClick: () => toggle('section') },
+        measure: { pressed: mode === 'measure', onClick: () => toggle('measure') },
+        fit: { onClick: () => viewer.current?.fit() },
+        reset: { onClick: () => viewer.current?.reset() },
+        top: { onClick: () => viewer.current?.setView('top') },
+      }}
     >
-      {feature.featureType}
-    </li>
-  ))}
-</ul>
-<Viewer onPointerMissed={() => setSelected(null)}>
-  <EnginePart
-    report={report}
-    selection={selected ? [selected] : []}
-    hoveredFeatureIds={hovered ? [hovered] : []}
-    focusFeature={selected}
-    onPick={(pick) => setSelected(pick.best)}
-  />
-</Viewer>
-```
-`feature.tag` is the feature's ID. Always use it to refer to a feature, never the feature's
-position in the array.
-### Clicking the same face again to go through its matches
-Clicking the same face repeatedly can step through its matching features, like most CAD tools do.
-`focusForPick` handles this:
-```tsx
-const [focused, setFocused] = useState<string | null>(null)
-const [lastRegion, setLastRegion] = useState<number | null>(null)
-<EnginePart
-  report={report}
-  selection={focused ? [focused] : []}
-  onPick={(pick) => {
-    setFocused(focusForPick(pick, lastRegion, focused))
-    setLastRegion(pick.region)
-  }}
-/>
-```
-A click on a different face starts again from that face's best match. To show the other matches
-faintly, pass `pick.ranked` as `candidates`.
-### Selecting several features with a modifier key
-The viewer tells you which keys were held and leaves the behaviour to you:
-```tsx
-onPick={(pick) => {
-  const tag = pick.best
-  if (!tag) return
-  if (pick.modifiers.shift) setSelection((current) => [...current, tag])
-  else setSelection([tag])
-}}
-```
-A double-click on the part also re-centres the view. The second click still calls `onPick`, with
-`pick.doubled` set to `true`. Ignore those clicks if a double-click shouldn't change your selection.
-### Showing only one machining direction
-Pass the same index to the arrows and the part. Clicks then only match features machined from that
-direction. A face that can't be reached from that direction gives `pick.best === null`.
-```tsx
-<EnginePart report={report} activeDirection={direction} onPick={onPick} />
-<DirectionArrows
-  directions={model.candidateDirections}
-  activeDirection={direction}
-  onPickDirection={setDirection}
-/>
-```
-To list features by direction, use `groupByDirection(model)`. To label a direction, use
-`directionLabel(direction)`, which gives `+Z`, `−X`, or `0.707, 0, 0.707`. To colour a direction
-the same way as its arrow, use `directionColor(index)`.
-### Showing sharp corners
-`sharpCorners` draws a part's sharp corners as red bands painted on the two faces that meet there: strong where you can see them, faint
-where the part is in front of them. **Which corners is the DFM rules' call, not the viewer's.** Pass
-the features the rules flag with a sharp corner — those whose `featureSheet(datasheet).sharpCorners`
-is set, from `@toolpath/dfm/model` — and the viewer draws each one's inside corners that run along
-its machining direction: the vertical corners between its walls that no end mill makes. Nothing else
-is drawn — not a hole's rim, not an outside edge, not a floor meeting a wall.
-The mesh only says where those corners are. It needs the closed mesh the Engine produces (every edge
-shared by exactly two triangles) and the report's regions, which tell a real edge from tessellation.
-```tsx
-const flagged = Object.entries(sheets)
-  .filter(([, sheet]) => sheet.sharpCorners)
-  .map(([tag]) => tag)
-<ViewerToolbarProvider
-  controls={{ sharpCorners: { pressed: shown, onClick: () => setShown((on) => !on) } }}
->
-  <ViewerToolbar />
-  <Viewer>
-    <EnginePart report={report} sharpCorners={shown ? { features: flagged } : null} />
-  </Viewer>
-</ViewerToolbarProvider>
-```
-`ViewerToolbar.SharpCornersButton` turns them on and off; there is nothing else to offer users.
-Tags are matched without regard to case, so the lower-cased keys an application keeps its sheets
-under work as they are.
-With `hover` on, the pointer on a corner is on the corner: it takes the theme's `hover` colour at
-the same width, the face under it is not painted as hovered, and the pick `onHover` reports carries it as
-`pick.sharpCorner`. That is a `SharpCorner`: the flagged `feature` it belongs to, its `start` and `end`,
-its `length` (how deep a tool would have to reach, mm), and the `angle` between its faces (90 for a
-square corner). What a hover card says about it is the application's call; with the feature's sheet,
-the widest tool that fits it (`pinchDiameter`) says what milling would leave there — that tool's radius.
-```tsx
-<HoverCard pick={pick}>
-  {(pick) =>
-    pick.sharpCorner ? (
-      <SharpCornerDetails corner={pick.sharpCorner} />
-    ) : (
-      <FeatureDetails pick={pick} />
-    )
-  }
-</HoverCard>
+      <div style={{ position: 'relative', height: 500 }}>
+        <Viewer ref={viewer}>
+          <PartMesh model={model} geometry={geometry} />
+          {stock && <Stock box={{ partGeometry: geometry, allowance: { wall: 3, floor: 3 } }} />}
+          {mode === 'section' && <SectionTool />}
+          {mode === 'measure' && (
+            <MeasureTool measurements={measurements} onChange={setMeasurements} />
+          )}
+          <Grid />
+          <Axes />
+          <ViewCube />
+        </Viewer>
+        <ViewerToolbar />
+      </div>
+    </ViewerToolbarProvider>
+  )
+}
 ```
-`findSharpCorners(creases, model, options)` lists the same corners without a pointer.
-`features` is the only option. How sharp a fold must be to count, how closely it must follow the
-machining direction, and how the bands look are fixed: the rules have already decided which corners
-matter, and there is nothing left worth tuning. The colour is the `sharpCorner` theme key. To count
-or measure the corners yourself, use `surfaceCreases(geometry, model)` and
-`sharpCornerPositions(creases, model, options)`.
+Call Fit after toggling stock if you want to frame the blank. When switching from
+Section to Measure, the viewer's existing cut remains until cleared with Escape
+while the section tool is active or `viewer.current?.setSection(null)`. The example
+retains measurements in React state when the tool is unmounted.
-If your application paints the features a rule flags, leave that rule's paint off while the corners
-are shown. A corner drawn in the rule's colour disappears into paint of the same colour, and the
-corner is the rule's mark, more exactly than the paint is.
+With no children, `ViewerToolbar` renders configured controls in standard order.
+For custom composition use `ViewerToolbar.Controls`, `ViewerToolbar.Divider`, and
+its `*Button` components. A button without a matching provider control throws.
+The supported action names are `stock`, `axes`, `grid`, `banana`, `tools`,
+`directions`, `dfm`, `sharpCorners`, `hover`, `focus`, `wireframe`, `section`,
+`measure`, `fit`, `reset`, and `top`; button names capitalize the action, such as
+`ViewerToolbar.SharpCornersButton`. `useViewerToolbar()` reads those controls.
-### Custom colours
+### Stock and display controls
-Use `highlights` for colours that mean something in your app, such as difficulty, setup, or cost.
-Colours are hex numbers:
+`Stock` takes exactly one source. Stock stays in part coordinates, is included in
+Fit/Reset, and does not intercept part picks or follow its section cut.
+| Source              | Input                                                                                                                 |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `geometry`          | A caller-owned `BufferGeometry`; dispose it yourself after use.                                                       |
+| `glb`               | An `ArrayBuffer` of GLB bytes you fetched. Keep the buffer reference stable. Stock decodes/disposes its own geometry. |
+| `box` preview       | `{ partGeometry, allowance, offset? }` or `{ partGeometry, dimensions, position?, positionOffset?, offset? }`.        |
+| `box` resolved      | `{ lower, upper, frame? }`.                                                                                           |
+| `cylinder` preview  | `{ partGeometry, diameter, length, position?, positionOffset? }`.                                                     |
+| `cylinder` resolved | `{ origin, axis, diameter, length }`; origin is the base center, axis points along its length.                        |
+Allowances are **per side**: `{ wall, floor }` expands X/Y and Z respectively;
+a number or `{ x, y, z }` is also accepted. The Workbench's 3 mm allowance is an
+example, not a stock recommendation. Fixed preview `dimensions` are `{ x, y, z }`.
+Positions are `model_centered`, `offset_from_top`, and `offset_from_bottom`, with
+`positionOffset` in millimetres. Preview options and resolved figures are mutually
+exclusive. Use `boxStockBounds` / `fixedBoxStockBounds` for corresponding dimensions.
+Centered stock is centered on the part's bounds. For top positioning its upper Z
+is `part.max.z + positionOffset`; for bottom positioning its lower Z is
+`part.min.z - positionOffset`. These rules also position cylinder previews along Z.
+A box's optional frame has `location`, `axis`, and `refDirection`. Its local point
+maps to `location + x·refDirection + y·(axis × refDirection) + z·axis`; the axis is
+normalized and the reference direction projected perpendicular and normalized.
+Without a frame, corners are already in part coordinates. A cylinder preview is
+Z-aligned and centered on the part's bounding box. Treat previews as visualization;
+prefer the operation's resolved stock when the selected API contract supplies it.
+Negative/non-finite allowances, invalid coordinates, degenerate frames/axes, and
+non-positive dimensions throw `RangeError`. GLB node transforms are applied without
+centering, rescaling, or axis conversion. Stock does not fetch, cache, decompress
+HTTP responses itself, or need an analysis report; the browser handles HTTP gzip.
+Appearance props are `color`, `emissive`, `flatShading`, `opacity` (default 0.2),
+`edgeColor`, `edgeOpacity`, and `showEdges`. `renderStyle="legacy-workpiece"` selects
+the legacy two-pass material/edge appearance. With `showEdges={false}`, outlines
+are not built until needed. `retainPrevious` applies to GLB playback: keep the
+previous decode visible until the replacement is ready. Key the stock subtree by
+part/calculation identity to prevent carrying geometry into a different run.
+Without it, changing GLB bytes hides the previous geometry during decoding.
+**Migration from 1.x:** replace removed `BoxStock` with `Stock`'s `box` source.
+`StockProps` is a union; use an intersection type rather than extending it with an
+interface. `StockAppearanceProps` describes just the shared appearance options.
+### Direction coloring
+Keep the same candidate index in `PartMesh.activeDirection` and the arrows. Use
+`shownDirection={null}` for all arrows, an index/list to choose arrows, or `-1`
+for none. `activeDirection` also scopes arrows when `shownDirection` is omitted.
+`previewDirection` and `namedDirections` add non-candidate directions.
 ```tsx
-const DIFFICULTY = { easy: 0x22c55e, medium: 0xeab308, hard: 0xef4444 }
+import { useMemo, useState } from 'react'
+import type { BufferGeometry } from 'three'
+import {
+  DirectionArrows,
+  PartMesh,
+  Viewer,
+  directionHighlights,
+  type PartModel,
+} from '@toolpath/viewer'
-<EnginePart
-  report={report}
-  highlights={features.map((f) => ({ tag: f.tag, color: DIFFICULTY[f.difficulty] }))}
-  selection={selection}
-/>
+export const DirectionViewer = ({
+  model,
+  geometry,
+}: {
+  model: PartModel
+  geometry: BufferGeometry
+}) => {
+  const [direction, setDirection] = useState<number | null>(null)
+  const colors = useMemo(() => directionHighlights(model, direction), [model, direction])
+  return (
+    <Viewer style={{ height: 400 }}>
+      <PartMesh
+        model={model}
+        geometry={geometry}
+        activeDirection={direction}
+        regionHighlights={colors}
+      />
+      <DirectionArrows
+        directions={model.candidateDirections}
+        shownDirection={direction}
+        onPickDirection={(index) => setDirection((current) => (current === index ? null : index))}
+      />
+    </Viewer>
+  )
+}
 ```
-A face shows only one colour. When several layers apply, the one lower in this list wins:
-1. `highlights` (your colours, per feature)
-2. `regionHighlights` (your colours, per face)
-3. `candidates` (faint, per direction)
-4. `selection` (orange)
-5. `pickedRegions`
-6. `hoveredFeatureIds`
-7. the face under the pointer
-`weight` (`0`–`1`, default `0.7`) sets how strongly a highlight covers the part.
-Changing colours is fast, even when every feature on a large part is highlighted.
+Arrows point toward the part. Picking an arrow does not clear selection through
+`onPointerMissed`. Use `groupByDirection`, `directionLabel`, and `directionColor`
+for a matching list/legend. Wireframe and direction coloring are independent props;
+any mutual exclusion in the example app is application behavior.
 ### Section view
-The quickest way is `<SectionTool>`. Put it inside `<Viewer>` next to the part and give `PartMesh`
-no `section` prop:
+Mount `SectionTool` inside `Viewer` beside a part with no explicit `section` prop.
+It previews the surface under the pointer, places a cut on click, and offers X/Y/Z
+planes. A drag handle moves the cut; Escape clears it while the tool is mounted.
+It writes the viewer-owned section store and suppresses normal part hover/picks
+while active. Unmounting the tool restores part interactions, not the uncut solid.
-```tsx
-<Viewer ref={viewer}>
-  <EnginePart report={report} />
-  {sectioning ? <SectionTool /> : null}
-</Viewer>
-```
-Hovering the part previews a cut through the face under the pointer; clicking places it. Three
-coloured planes stand behind the part — click one to cut along that axis, in from your side. Once
-there is a cut, a framed plane and two-way normal-axis handle show exactly what will move; drag the
-handle to move it. Keep the canvas clear by presenting `sectionMeasurement(state)` beside the host
-application's section slider; it reports the depth from a picked surface, or the distance swept
-through the part bounds. Escape clears it.
-The cut belongs to the viewer: `viewer.current.setSection(null)` clears it from a button outside
-the canvas, `setSection({ enabled: true, normal, offset })` sets one, and `onSectionChange` on
-`PartMesh` still reports every move.
-While the tool is mounted, the part reports no hovers or picks — clicking a face cuts through it
-without also selecting it. Unmount the tool, as above, and they come back.
-To drive the cut yourself instead, pass `section`. `normal` points toward the half you keep.
-`offset` goes from `0` (whole part) to `1` (fully cut away).
+For application-controlled cuts, supply `section` directly. Here `normal` points
+toward the retained half; `offset` ranges from 0 (whole part) to 1 (cut away).
 ```tsx
-const [cutting, setCutting] = useState(false)
-const [offset, setOffset] = useState(0.5)
-<input type="checkbox" checked={cutting} onChange={(e) => setCutting(e.target.checked)} />
-<input type="range" min={0} max={1} step={0.01} value={offset}
-       onChange={(e) => setOffset(Number(e.target.value))} />
-<EnginePart
-  report={report}
-  section={{ enabled: cutting, normal: { x: 0, y: 0, z: 1 }, offset }}
-  onSectionChange={(state) => setOffset(state.offset)}
-/>
+import { useState } from 'react'
+import type { BufferGeometry } from 'three'
+import { PartMesh, Viewer, type PartModel } from '@toolpath/viewer'
+export const SectionViewer = ({
+  model,
+  geometry,
+}: {
+  model: PartModel
+  geometry: BufferGeometry
+}) => {
+  const [offset, setOffset] = useState(0.5)
+  return (
+    <>
+      <label>
+        Section offset
+        <input
+          type="range"
+          min="0"
+          max="1"
+          step="0.01"
+          value={offset}
+          onChange={(event) => setOffset(Number(event.target.value))}
+        />
+      </label>
+      <Viewer style={{ height: 400 }}>
+        <PartMesh
+          model={model}
+          geometry={geometry}
+          section={{ enabled: true, normal: { x: 0, y: 0, z: 1 }, offset }}
+          onSectionChange={(state) => setOffset(state.offset)}
+        />
+      </Viewer>
+    </>
+  )
+}
 ```
-The cut surface is filled in with a hatch and outlined, so the part doesn't look hollow and the cut
-reads as a cut. Passing `onSectionChange` also shows the draggable plane-frame gizmo. The handler is
-called on every drag and only when the cut actually changes, so it's safe to store the value in
-state; a cut going away is reported once, with `enabled: false`.
-**Cutting at a clicked surface.** `sectionFromPick` places the cut at the surface the user clicked.
-`depth` moves it into the part, in millimetres:
-```tsx
-const [plane, setPlane] = useState<SectionPlacement | null>(null)
-<EnginePart
-  report={report}
-  section={{ enabled: plane !== null, plane, depth: 1 }}
-  onPick={({ point: [x, y, z], normal: [nx, ny, nz] }) =>
-    setPlane(sectionFromPick({ point: { x, y, z }, normal: { x: nx, y: ny, z: nz } }))
-  }
-/>
-```
+Passing `onSectionChange` also enables the controlled cut's drag handle. The callback
+reports `SectionState`, including `enabled`, `normal`, `offset`, `plane`, `depth`,
+`constant`, and depth bounds. Use `sectionFromPick({ point, normal })` to create a
+surface placement, then `{ enabled: true, plane, depth }` to cut inward by a depth
+in millimetres. Pick tuples must be converted to `{ x, y, z }` for that helper.
+`sectionMeasurement(state)` supplies a readout for your own slider or label.
 ### Measuring
-Mount `<MeasureTool>` next to the part. It needs nothing else:
+`MeasureTool` mounts inside `Viewer`. Two clicks measure distance; three measure an
+angle, with the vertex as the middle point. Snapping prefers corners, edge
+midpoints, edges, then faces. `mode` is `distance` or `angle`; `showDeltas={false}`
+hides a distance's X/Y/Z legs. `onChange` reports `readonly Measurement[]`; pass
+`measurements` too to control and retain the list, as the Workbench does.
-```tsx
-const [measuring, setMeasuring] = useState(false)
-const [mode, setMode] = useState<MeasureMode>('distance')
-const [measurements, setMeasurements] = useState<readonly Measurement[]>([])
-<Viewer>
-  <EnginePart report={report} />
-  {measuring ? <MeasureTool mode={mode} onChange={setMeasurements} /> : null}
-</Viewer>
-```
+Shift constrains the next point to an axis. Escape cancels points in progress;
+Delete/Backspace removes the last measurement unless focus is in a form field.
+Normal part hover/picks are suppressed while measuring. Without controlled state,
+unmounting the tool drops its measurements.
+The tool measures the visible sectioned geometry, including the cap and clipped
+edges. If a mounted SectionTool has no cut yet, measuring waits so its first
+placement click is not also a measurement. Existing measurements remain visible.
-Hover the part and a marker shows where a click will land: a corner, an edge's midpoint, a point
-on an edge, or a point on the face, in that order of preference. It snaps to the edges the part
-draws — the boundaries between analytic surfaces — so a corner is a corner of the part, not of a
-mesh triangle. Click twice for a distance or three times for an angle. The line follows the pointer
-between clicks with a live readout.
-A distance is labelled with its length and, unless it already runs along an axis, broken into its
-X, Y and Z parts as dashed legs in the axis colours with a label each. `showDeltas={false}` turns
-the legs off. An angle draws its two arms and an arc, labelled in degrees.
-`onChange` reports the list whenever it changes. Each entry is a `Measurement`: `kind`, an `id`,
-and its `points` — two for a distance, three for an angle with the vertex in the middle. To own the
-list, pass `measurements` too; to clear it, unmount the tool or pass `[]`. `measurementLabel(m)`
-writes an entry the way the tool does, and `distanceBetween`, `deltaBetween` and `angleAt` are the
-arithmetic behind it.
-**Styling the labels.** Every label is a `<div class="toolpath-measure-label">` with
-`data-measure-label` set to `distance`, `angle`, `delta` (one leg of a distance's X, Y, Z breakdown,
-with `data-axis`) or `live` (the readout that follows the pointer), and `data-measurement-id` on
-anything belonging to a finished measurement. Nothing else is set: no font, no colour, no
-background. `labelClassName` adds your own class, for Tailwind or a CSS module. A stylesheet to
-start from, which is what the example uses:
+Labels are unstyled DOM overlays with class `toolpath-measure-label`; add CSS such as:
 ```css
 .toolpath-measure-label {
@@ -988,355 +653,300 @@ start from, which is what the example uses:
   font:
     600 12px/1.2 system-ui,
     sans-serif;
-  color: #fff;
-  background: rgba(20, 23, 33, 0.85);
+  color: white;
+  background: #141721dd;
   border: 1px solid #4f8ef7;
   border-radius: 4px;
   padding: 2px 6px;
-  transform: translateY(-16px);
 }
 .toolpath-measure-label[data-measure-label='delta'] {
   font-size: 11px;
-  transform: translateY(14px);
-}
-.toolpath-measure-label[data-axis='x'] {
-  border-color: #ff6b6b;
 }
 ```
-Labels take no pointer events, so one lying over the part never takes a click meant for the face
-under it. The lines, markers and arc are drawn on the canvas and themed through `measure`.
+`data-measure-label` identifies `distance`, `angle`, `delta`, `live`, or tool labels;
+axis legs also have `data-axis`, and finished labels have `data-measurement-id`.
+`labelClassName` adds a class. Labels do not take pointer events. Lengths default to
+millimetres; the `format(mm)` callback changes their displayed string, not geometry
+units or angles (which remain degrees).
-Lengths are written in millimetres by default. The part is in millimetres and the viewer does not
-convert, so pass `format` to show anything else:
+### Showing sharp corners and tool marks
-```tsx
-<MeasureTool format={(mm) => `${(mm / MM_PER_INCH).toFixed(3)} in`} />
-```
-**Measuring a cut part.** Mount the measure tool with a section cut in place, or beside
-`<SectionTool>`, and it measures what is on screen: the half a cut has removed is not there to snap
-to, the part's edges stop at the plane, the outline where the plane passes through solid material
-is an edge with corners of its own, and the capped face is a surface a point can land on. The
-sample follows the cut — drag the handle or set a depth and the next pointer move sees the new cut.
-It reads the plane off the part's own material, so a controlled `section` prop works the same way.
-Beside a `<SectionTool>` that has no cut yet, the measure tool waits: it offers no snap and places
-no point until a cut is chosen or the section tool is unmounted, so the click that picks the cut is
-not also the first point of a measurement. Measurements already made stay up meanwhile.
-Hold Shift to hold the next point to the X, Y or Z line through the last one — whichever axis the
-pointer is furthest along — so a length along an edge is measured square rather than slightly across
-it. The line wears that axis's colour while it is held, and the finished distance has no legs to
-show. Delete or Backspace removes the last measurement, unless focus is in a field. Escape drops the
-points of a measurement in progress. While the tool is mounted the part reports no hovers or picks;
-unmounting it hands the pointer back.
-### Theming
-```tsx
-<Viewer theme={{ ambientIntensity: 1.5 }}>
-  <EnginePart report={report} theme={{ part: 0xe5e7eb, highlight: 0x2563eb, hover: 0x93c5fd }} />
-  <ViewCube theme={{ cube: 0x1f2937, cubeLabel: 0xffffff }} />
-</Viewer>
-```
-Colours are hex numbers. Lighting goes on `<Viewer>`, part colours go on the part, and cube colours
-go on the cube. See `DEFAULT_THEME` for every key. The default part colours are tuned for the
-default lighting, so if you change one, check the other.
-The section cut is themed on the part too: `sectionCap` and `sectionHatch` are the cap's fill and
-hatch lines, `sectionHandle` overrides the drag arrow's colour, and `sectionOutline` the
-cutting-plane sheet and preview that `<SectionTool>` draws. Without a `sectionHandle` override, the
-drag arrow uses the cutting plane's direction colour. `measure` and `measureSnap` are
-`<MeasureTool>`'s lines and its snap indicator; a distance's X, Y, Z legs take `AXIS_COLORS`, the
-same hues as the section tool's global planes. `sharpCorner` is the colour of
-[sharp corners](#showing-sharp-corners).
-`HIGHLIGHT_COLORS` has the standard selection colours (`default`, `toolIssue`, `geometryIssue`).
-`DIRECTION_COLORS` has the 9 direction colours, which repeat for parts with more than 9 directions.
-### Drawing your own objects in the scene
-Anything React Three Fiber can draw can go inside `<Viewer>`, and the camera includes it when it
-frames the scene. To leave an object out of framing, as `<Grid>` does, set
-`userData={{ [EXCLUDE_FROM_FRAME]: true }}`.
-Use `useContentBox()` inside the viewer to get the part's bounding box, for example to size your own
-object.
-## Errors
-These are all thrown, so an error boundary catches them.
-| Error                           | Import from               | When                                                                                                             |
-| ------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `PartReportFormatError`         | `@toolpath/viewer`        | The report is malformed. `error.issues` lists every problem.                                                     |
-| `UnsupportedKernelVersionError` | `@toolpath/viewer`        | The report is from an Engine kernel older than `0.3.0`. Re-analyze the part.                                     |
-| `PartMeshError`                 | `@toolpath/viewer/engine` | The mesh download failed (usually an expired URL: fetch the report again), or the mesh doesn't match the report. |
-| `AggregateError`                | —                         | Both the GLB and the STL failed. `error.errors` has one error per file.                                          |
+DFM decisions belong to the application. Pass flagged feature tags as
+`sharpCorners={{ features: tags }}`; the viewer draws qualifying inside corners
+along those features' machining directions. It does not flag features or guess
+missing manufacturing data. Use a closed mesh with report region boundaries;
+`findSharpCorners`/`sharpCornerPositions` operate on `surfaceCreases` for custom
+inspection. A hovered corner appears as `pick.sharpCorner` with its feature,
+endpoints, length, and angle. Feature tag matching for these flags is case-insensitive.
-```tsx
-import { PartReportFormatError, UnsupportedKernelVersionError } from '@toolpath/viewer'
-function PartError({ error }: { error: Error }) {
-  if (error instanceof UnsupportedKernelVersionError) return <p>Re-analyze this part to view it.</p>
-  if (error instanceof PartReportFormatError)
-    return <p>Invalid report: {error.issues.join(', ')}</p>
-  return <p>Could not load this part. Refresh to try again.</p>
-}
-```
-The viewer does not read STEP files. The Engine analyzes STEP files and produces the mesh the
-viewer displays.
-## Working with the Toolpath API
-Use [`@toolpath/api`](https://www.npmjs.com/package/@toolpath/api) to get parts. Call it **from your
-server**, so your API key stays private, and pass the result to the browser.
-The API can give you two things to show:
-- **An analyzed part** (`getPart`): faces and features. Use it with `<EnginePart>`.
-- **A display mesh** (`getPartMesh`): faces only, but much faster, because the part isn't
-  analyzed. Use it with `<PartMesh>`.
-Both need a part whose CAD file is already uploaded. Their mesh URLs expire after 15 minutes, so
-don't cache the responses.
-### Analyzed part
+Mount `ToolMarks` under a part to illustrate supplied cutters or profiles. For
+example, this is a 6 mm bull-nose cutter standing along +Z:
 ```ts
-// server
-import { createToolpathClient } from '@toolpath/api'
-const api = createToolpathClient({ apiKey: process.env.TOOLPATH_API_KEY! })
+import type { ToolMark } from '@toolpath/viewer'
-export const getReport = (partId: string) => api.parts.getPart({ id: partId })
-```
-```tsx
-// browser
-<Viewer>
-  <EnginePart report={report} />
-</Viewer>
+export const toolMarks: Array<ToolMark> = [
+  {
+    base: { x: 12, y: 4, z: -8 },
+    axis: { x: 0, y: 0, z: 1 },
+    diameter: 6,
+    height: 8,
+    cornerRadius: 0.5,
+    label: '⌀ 6 mm',
+    note: 'Bull nose R 0.5',
+  },
+]
 ```
-### Display mesh
+Use `ToolMarks`'s `marks` prop for that array. A `ToolMark` can instead supply a
+rotational `profile` of `{ r, z }` points. `visible` toggles display;
+`labelClassName` styles labels. Marks use the measure-label CSS hook with
+`data-measure-label="tool"`, optional value/note spans, take no pointer events,
+and are excluded from camera framing. They do not read datasheets themselves.
-On the server, start a mesh job, wait for it, then get the mesh:
+### Theming
-```ts
-// server
-export async function getMesh(partId: string) {
-  const { jobId } = await api.parts.createPartMesh({ id: partId })
-  let job = await api.jobs.getJob({ id: jobId })
-  while (job.status === 'queued' || job.status === 'running') {
-    await new Promise((resolve) => setTimeout(resolve, 1000))
-    job = await api.jobs.getJob({ id: jobId })
-  }
-  if (job.status === 'failed') throw new Error(job.error ?? 'Meshing failed')
-  return api.parts.getPartMesh({ id: partId, jobId })
-}
-```
+Colors in `ViewerTheme` are numeric hex values. Set lighting on `Viewer`, part
+colors on `PartMesh`/`EnginePart`, and overlay colors on their components; passing
+part colors only to `Viewer` does not theme its children automatically.
+`DEFAULT_THEME` lists the keys. Selection palettes are `HIGHLIGHT_COLORS`; direction
+colors cycle through `DIRECTION_COLORS`.
+Part keys include `part`, `partEmissive`, `hover`, `highlight`, `picked`, `edge`,
+`edgeOpacity`, and `sharpCorner`. Section keys include `sectionCap`, `sectionHatch`,
+`sectionOutline`, `sectionHandle`, and `sectionHandleOutline`. Measurement tools
+use `measure`/`measureSnap`; cube keys are `cube`, `cubeEdge`, and `cubeLabel`.
+The canvas background comes from the wrapper/parent, independently of those colors.
+Stable DOM classes include `viewer-root`, `viewer-canvas-container`,
+`viewer-canvas-frame`, `viewer-canvas`, `viewer-hover-card`, `viewer-toolbar-stack`,
+`viewer-toolbar`, `viewer-toolbar-button`, `viewer-toolbar-icon`,
+`viewer-toolbar-tooltip`, and `viewer-toolbar-divider`. Caller `className` values
+append to the component's hook. Corresponding `data-viewer-*` attributes identify
+the DOM boundaries; `data-viewer-toolbar-action` contains the control's action name.
+Style the hover card yourself; it is a pointer-events-free fixed-position shell.
+Custom R3F objects can go inside `Viewer` and participate in framing. Set
+`userData={{ [EXCLUDE_FROM_FRAME]: true }}` to exclude an object. Use the exported
+`EXCLUDE_FROM_FRAME` constant, not a guessed string.
-If the part already has a display mesh, skip the job and call `api.parts.getPartMesh({ id })`.
+## Working with the Toolpath API
-In the browser, turn the response into a model. `faceTriangleCounts` says how many triangles each
-face has, so each count becomes one face:
+Keep analysis/job orchestration outside the viewer. A server-side
+[`@toolpath/api`](https://www.npmjs.com/package/@toolpath/api) integration can fetch a
+completed report and pass it to the browser. Deliberate browser API access needs
+an appropriately scoped, allowed-origin key; a browser-delivered key is observable
+and is not made secret by CORS. See the [authentication guide](https://developers.toolpath.com/authentication).
+The viewer's mesh loader does not attach an Engine API key to artifact requests.
+### Analyzed part versus display mesh
+A completed analysis report includes features and regions for `EnginePart`.
+A display-mesh response has geometry and face counts without analysis features;
+it is not an `EnginePart` report. Use `PartMesh` with a model whose region ranges
+come from that display mesh's `faceTriangleCounts`. Without them, a single region
+can cover all triangles. Such a model has no feature owners, so `pick.best` is
+`null`; use `pickedRegions` and `regionHighlights` for face feedback. Its face
+indices do not identify analysis-report regions, and synthetic area values do not
+establish analytic measurements or DFM results.
+### Mesh loading and ownership
+For custom fetching, backend proxies, or local files, use `/engine` loaders and
+render `PartMesh`. `EnginePart` itself has no custom-fetch prop.
+`loadPartMesh(mesh, { fetch?, signal? })` tries GLB then STL;
+`loadPartGeometry(url, counts, { format?, fetch?, signal? })` loads one artifact;
+`parsePartGeometry(bytes, counts, format?)` parses bytes without fetching.
+All produce caller-owned, non-indexed geometry, preserve triangle ordering and
+coordinates, and validate counts against the supplied expectation. Call
+`smoothRegionNormals(geometry, model.regions)` to smooth curved regions while
+preserving their boundaries.
+The counts argument is `{ pointCount, triangleCount }`, as in `model.mesh`; raw
+API fields named `meshPointCount`/`meshTriangleCount` must be mapped deliberately.
+This loader handles cancellation, failures, changed reports, and owned geometry:
 ```tsx
-// browser
 import { useEffect, useMemo, useState } from 'react'
 import type { BufferGeometry } from 'three'
-import type { PartMeshResponse } from '@toolpath/api'
-import { PartMesh, Viewer, buildRegionIndex, type PartModel } from '@toolpath/viewer'
-import { loadPartMesh } from '@toolpath/viewer/engine'
-function toModel(mesh: PartMeshResponse): PartModel {
-  let start = 0
-  const regions = (mesh.faceTriangleCounts ?? [mesh.meshTriangleCount]).map((count, idx) => {
-    const triangles = { start, end: start + count }
-    start += count
-    return { idx, splitOrigin: idx, shapeKind: 'Unknown', area: 0, triangles }
-  })
-  const triangleCount = mesh.meshTriangleCount
-  return {
-    partId: mesh.partId,
-    kernelVersion: '',
-    features: [],
-    regions,
-    candidateDirections: [],
-    mesh: {
-      pointCount: mesh.meshPointCount,
-      triangleCount,
-      glbUrl: mesh.meshGlbUrl,
-      stlUrl: null,
-      thumbnailUrl: null,
-    },
-    regionIndex: buildRegionIndex({ regions, features: [], triangleCount }),
-    warnings: [],
-  }
-}
-export function MeshViewer({ mesh }: { mesh: PartMeshResponse }) {
-  const model = useMemo(() => toModel(mesh), [mesh])
-  const [geometry, setGeometry] = useState<BufferGeometry | null>(null)
+import { PartMesh, Viewer, type PartModel } from '@toolpath/viewer'
+import {
+  loadPartMesh,
+  normalizePartReport,
+  smoothRegionNormals,
+  type FetchLike,
+} from '@toolpath/viewer/engine'
-  useEffect(() => {
-    loadPartMesh(model.mesh).then(setGeometry)
-  }, [model])
+type Loaded = { model: PartModel; request: FetchLike | undefined; geometry: BufferGeometry }
+type Failure = { model: PartModel; request: FetchLike | undefined; error: Error }
-  if (!geometry) return <p>Loading…</p>
+export const ManagedPart = ({ report, request }: { report: unknown; request?: FetchLike }) => {
+  const model = useMemo(() => normalizePartReport(report), [report])
+  const [loaded, setLoaded] = useState<Loaded | null>(null)
+  const [failure, setFailure] = useState<Failure | null>(null)
+  useEffect(() => {
+    const controller = new AbortController()
+    let active = true
+    let owned: BufferGeometry | undefined
+    const load = async () => {
+      const geometry = await loadPartMesh(model.mesh, { fetch: request, signal: controller.signal })
+      if (!active) {
+        geometry.dispose()
+        return
+      }
+      try {
+        smoothRegionNormals(geometry, model.regions)
+      } catch (error) {
+        geometry.dispose()
+        throw error
+      }
+      owned = geometry
+      setLoaded({ model, request, geometry })
+    }
+    void load().catch((error: unknown) => {
+      if (active) {
+        setFailure({
+          model,
+          request,
+          error: error instanceof Error ? error : new Error(String(error)),
+        })
+      }
+    })
+    return () => {
+      active = false
+      controller.abort()
+      owned?.dispose()
+    }
+  }, [model, request])
+  if (failure?.model === model && failure.request === request) throw failure.error
+  if (loaded?.model !== model || loaded.request !== request) return <p>Loading mesh…</p>
   return (
-    <Viewer style={{ height: 500 }}>
-      <PartMesh model={model} geometry={geometry} onPick={(pick) => console.log(pick.region)} />
+    <Viewer style={{ height: 400 }}>
+      <PartMesh model={model} geometry={loaded.geometry} />
     </Viewer>
   )
 }
 ```
-In a real app, also handle a failed download and call `geometry.dispose()` when you're done.
-A display mesh has no features, so a click gives you only the face (`pick.region`), and
-`pick.best` is always `null`. Use `pickedRegions` and `regionHighlights` to colour faces. Don't pass
-a display mesh to `<EnginePart>`: its faces are numbered differently from an analyzed part's.
-## Using it without the Engine
-`<PartMesh>` takes a `PartModel` (the part's faces and features) and a three.js `BufferGeometry`
-(the mesh). Use it to show a local file, a test fixture, or geometry you created yourself.
-```tsx
-import * as THREE from 'three'
-import { PartMesh, Viewer, buildRegionIndex, type PartModel } from '@toolpath/viewer'
+Use an error boundary around `ManagedPart`, as in the quick start. Keep an injected
+`request` function stable; changing it starts a new load. The component hides the
+previous model while the replacement loads, aborts on cleanup, and disposes a
+late result if the loader completed after cancellation. It does not use the shared
+Engine geometry cache.
-// A 20 mm cube. Each face is a region made of 2 triangles.
-const geometry = new THREE.BoxGeometry(20, 20, 20).toNonIndexed()
+### Expiring URLs and cache
-const regions = [0, 1, 2, 3, 4, 5].map((idx) => ({
-  idx,
-  splitOrigin: idx,
-  shapeKind: 'Plane',
-  area: 400,
-  triangles: { start: idx * 2, end: idx * 2 + 2 }, // [start, end)
-}))
+Artifact URLs are short-lived. Fetch promptly and obtain fresh URLs through the
+owning API when needed; do not store them as durable identifiers or log them. URL
+expiry belongs to the signed URL, not the age of the immutable analysis result.
+An error-boundary reset alone cannot renew an expired URL. Browser artifact fetches
+also need the artifact host's CORS permission, independently of API-key origins.
-const features = [
-  {
-    tag: 'top',
-    featureType: 'face',
-    machiningDirection: { x: 0, y: 0, z: 1 },
-    axis: null,
-    regionIdxs: [4],
-  },
-  {
-    tag: 'sides',
-    featureType: 'wall',
-    machiningDirection: { x: 0, y: 0, z: 1 },
-    axis: null,
-    regionIdxs: [0, 1, 2, 3],
-  },
-]
-const model: PartModel = {
-  partId: 'cube',
-  kernelVersion: '0.3.0',
-  features,
-  regions,
-  candidateDirections: [{ x: 0, y: 0, z: 1 }],
-  mesh: { pointCount: 36, triangleCount: 12, glbUrl: null, stlUrl: null, thumbnailUrl: null },
-  regionIndex: buildRegionIndex({ regions, features, triangleCount: 12 }),
-  warnings: [],
-}
+`EnginePart` uses a shared reference-aware geometry cache with a default capacity
+of eight entries. Mounted parts retain their resources; released entries are
+LRU-evicted/disposed when capacity is exceeded. The key uses GLB/STL URLs without query strings so renewed signatures reuse geometry. Proxy paths therefore
+need distinct artifact identities; putting all identities only in query parameters
+can collide. Keep the report's region mapping compatible with the cached artifact.
+Use `engineGeometryCache.clear()` only after consumers have unmounted: it disposes
+cached geometry, including retained resources.
-export const Cube = () => (
-  <Viewer style={{ height: 400 }}>
-    <PartMesh model={model} geometry={geometry} onPick={(pick) => console.log(pick.ranked)} />
-  </Viewer>
-)
-```
-Requirements:
-- **The mesh must be non-indexed** (call `.toNonIndexed()`). Each vertex can belong to only one
-  face.
-- **Regions must cover every triangle, with no gaps or overlaps.** `buildRegionIndex` throws if
-  they don't.
-- **Create the geometry once** (with `useMemo` or at module level). `PartMesh` doesn't dispose of
-  it, so you're responsible for that.
-If you have a report and want to load the mesh yourself, for example through your own backend,
-use the functions in `@toolpath/viewer/engine`:
-```ts
-import { loadPartMesh, normalizePartReport, smoothRegionNormals } from '@toolpath/viewer/engine'
+## Errors
-const model = normalizePartReport(report) // throws on a bad report
-const geometry = await loadPartMesh(model.mesh, { fetch: myFetch, signal })
-smoothRegionNormals(geometry, model.regions) // curved faces look smooth, edges stay sharp
-```
+| Error                           | Export    | Handling                                                                                             |
+| ------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `PartReportFormatError`         | Root      | Inspect `issues`; reject malformed reports or mismatched region/triangle mappings.                   |
+| `UnsupportedKernelVersionError` | Root      | `kernelVersion` is below `MIN_KERNEL_VERSION` (currently `0.3.0`); request compatible analysis data. |
+| `PartMeshError`                 | `/engine` | No artifact, HTTP failure, unreadable mesh, or count/shape mismatch.                                 |
+| `AggregateError`                | Built-in  | All available GLB/STL attempts failed; inspect `errors` for individual causes.                       |
+| `RangeError`                    | Built-in  | Invalid stock dimensions, frames, axes, or coordinates.                                              |
-[`examples/react-viewer`](https://github.com/toolpath/ui-packages/tree/main/examples/react-viewer)
-is a complete app built this way, with no API key needed.
+Wrap `EnginePart` in Suspense and an error boundary. A custom async loader must
+catch a rejected promise or rethrow it during render, as `ManagedPart` does; React
+boundaries do not catch arbitrary async callback errors. Recover by correcting
+input or fetching a fresh report/URL as appropriate, then reset the boundary.
+Do not disable validation to render an unrelated mesh against a report's regions.
 ## Reference
 ### Entry points
-| Import                    | Contents                                                                                                                                                                                             |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@toolpath/viewer`        | All components, hooks, types, and helpers. Also re-exports `EnginePart`, `normalizePartReport`, and `smoothRegionNormals`.                                                                           |
-| `@toolpath/viewer/engine` | Loading Engine reports and meshes: `EnginePart`, `loadPartMesh`, `loadPartGeometry`, `parsePartGeometry`, `PartMeshError`, `engineGeometryCache`, `createEngineGeometryCache`, `MIN_KERNEL_VERSION`. |
+| Import                         | Contents                                                                                                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@toolpath/viewer`             | Components, hooks, models, geometry/camera/selection helpers, and types. Also re-exports `EnginePart`, `normalizePartReport`, and `smoothRegionNormals`. |
+| `@toolpath/viewer/engine`      | Engine loading/normalization, geometry cache, `PartMeshError`, and adapter types.                                                                        |
+| `@toolpath/viewer/toolbar.css` | Optional toolbar stylesheet.                                                                                                                             |
+Other source/dist subpaths are not public imports. The complete signatures for an
+installed version are in its `dist/index.d.ts`, `dist/engine/index.d.ts`, and
+referenced declaration chunks. The public source export lists are
+[root](https://github.com/toolpath/ui-packages/blob/main/packages/viewer/src/index.ts)
+and [Engine adapter](https://github.com/toolpath/ui-packages/blob/main/packages/viewer/src/engine/index.ts).
 ### Hooks
-| Hook                  | Where                            | What it does                                                                     |
-| --------------------- | -------------------------------- | -------------------------------------------------------------------------------- |
-| `useViewerControls()` | Inside `<Viewer>`                | Get `fit`, `reset`, `setView`, `setViewDirection`, `frameBox`, and `setSection`. |
-| `useViewerToolbar()`  | Inside `<ViewerToolbarProvider>` | Get the actions and state supplied to the provider.                              |
-| `useSectionStore()`   | Inside `<Viewer>`                | Read, set, or subscribe to the viewer's own cut.                                 |
-| `useContentBox()`     | Inside `<Viewer>`                | Get the part's bounding box (a `THREE.Box3`, empty until loaded).                |
-| `usePartContext()`    | Inside `<PartMesh>`              | Get the part's `model` and the `geometry` it is drawn from, for an overlay.      |
-| `useTapGuard()`       | Inside `<Viewer>`                | Check whether a pointer event was a click and not a drag.                        |
-### Helpers
-| Helper                                                   | What it does                                                         |
-| -------------------------------------------------------- | -------------------------------------------------------------------- |
-| `normalizePartReport(report)`                            | Checks an API report and converts it to a `PartModel`.               |
-| `buildRegionIndex({ regions, features, triangleCount })` | Builds the lookups between triangles, faces, and features.           |
-| `model.regionIndex.featuresForRegion(i)`                 | The features that own a face.                                        |
-| `model.regionIndex.regionsForFeature(tag)`               | The faces that make up a feature.                                    |
-| `focusForPick(pick, lastRegion, lastFocus)`              | Steps through a face's matches on repeated clicks.                   |
-| `rankOwners` / `bestOwner`                               | The ranking `onPick` uses, if you want to run it yourself.           |
-| `groupByDirection(model)`                                | Features grouped by machining direction.                             |
-| `featureTriangles(model, geometry, tag)`                 | A feature's triangles and outward normals, as plain arrays.          |
-| `directionLabel(v)` / `directionColor(i)`                | A direction's label and colour.                                      |
-| `sectionFromPick({ point, normal })`                     | Turns a clicked surface into a section plane.                        |
-| `measurementLabel(measurement, format?)`                 | Writes a measurement the way `<MeasureTool>` labels it.              |
-| `snapAt(hit, edges, camera, viewport)`                   | Where a point on the part snaps to, for a tool of your own.          |
-| `surfaceCreases(geometry, model)`                        | Every edge between two faces, with its angle and which way it folds. |
-| `sharpCornerPositions(creases, model, options)`          | The ones `sharpCorners` would draw, as line segment endpoints.       |
-| `findSharpCorners(creases, model, options)`              | The same, as whole corners: feature, ends, length and angle.         |
-| `engineGeometryCache.clear()`                            | Frees every cached mesh.                                             |
-The package also exports lower-level geometry, camera, and view-cube functions that the components
-use. They're listed in `dist/index.d.ts`.
-### Types
-`ViewerProps`, `ViewerHandle`, `ViewerView`, `Projection`, `ControlScheme`, `EnginePartProps`,
-`PartMeshProps`, `PartPick`, `PickModifiers`, `PartModel`, `PartModelFeature`, `PartModelRegion`,
-`FeatureTag`, `FeatureType`, `Vec3`, `FeatureHighlight`, `RegionHighlight`, `FocusOptions`, `SectionOptions`,
-`SectionState`, `SectionPlacement`, `SectionToolProps`, `SectionStore`, `MeasureToolProps`,
-`MeasureMode`, `Measurement`, `DistanceMeasurement`, `AngleMeasurement`, `Snap`, `SnapKind`,
-`ViewerTheme`, `ViewName`, `DirectionArrowsProps`, `NamedDirection`, `GridProps`, `AxesProps`,
-`ViewCubeProps`, `ViewerToolbarProps`, `ViewerToolbarControlsProps`, `ViewerToolbarControls`,
-`ViewerToolbarControl`, `SharpCorner`, `SharpCornerOptions`, `SurfaceCreases`.
-`FeatureType` and `ShapeKind` accept any string, because newer Engine versions add new values.
-Handle values you don't recognize.
+| Hook                | Required context                 | Use                                                                                                  |
+| ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `useViewerControls` | Inside `Viewer`                  | Camera controls and `setSection`.                                                                    |
+| `useViewerToolbar`  | Inside `ViewerToolbarProvider`   | Configured host actions/state.                                                                       |
+| `useSectionStore`   | Inside `Viewer`                  | Read, set, or subscribe to viewer-owned section state.                                               |
+| `useContentBox`     | Inside the scene                 | Finished-part bounds, excluding stock/furniture; empty until found and measured once per hook mount. |
+| `usePartContext`    | Child of `PartMesh`/`EnginePart` | Part model and prepared input geometry.                                                              |
+| `useRetarget`       | Inside viewer scene              | Retarget callback, or `null` when disabled/outside context.                                          |
+| `useTapGuard`       | Inside viewer scene              | Distinguish taps from drags.                                                                         |
+### Helpers and types
+Common model/selection helpers include `buildRegionIndex`, `focusForPick`,
+`rankOwners`, `bestOwner`, `groupByDirection`, `directionLabel`, `directionColor`,
+`directionHighlights`, `regionAdjacency`, and `featureTriangles`. The region index
+provides `featuresForRegion(idx)` and `regionsForFeature(tag)`.
+For custom tools, section helpers include `sectionFromPick`, `sectionMeasurement`,
+`resolveSectionPlane`, and `createSectionStore`; measurement helpers include
+`distanceBetween`, `deltaBetween`, `angleAt`, `measurementLabel`, and `snapAt`.
+Lower-level camera, view-cube, painting, and geometry functions are also exported;
+consult their declarations rather than importing implementation files.
+Start with `ViewerProps`, `ViewerHandle`, `PartMeshProps`, `EnginePartProps`,
+`PartModel`, `PartModelRegion`, `PartModelFeature`, `FeatureTag`, `PartPick`,
+`FeatureHighlight`, `RegionHighlight`, `FocusOptions`, `ViewerTheme`, `StockProps`,
+`SectionOptions`, `SectionState`, `Measurement`, `MeasureMode`, and `ToolMark`.
+`EnginePartProps` and the loader/cache types come from `/engine`; scene/model
+types come from the root. Use the types belonging to your installed version; a newer source checkout does
+not add exports to a published package.
+## Working on this package
+The [React viewer example](https://github.com/toolpath/ui-packages/tree/main/examples/react-viewer)
+loads procedural parts without credentials. It also opens local report/mesh files;
+its [README](https://github.com/toolpath/ui-packages/blob/main/examples/react-viewer/README.md)
+describes the controls and browser tests.
+From the repository root with its pinned toolchain:
+```sh
+pnpm --filter @toolpath/viewer build
+pnpm --filter @toolpath/viewer check-types
+pnpm --filter @toolpath/viewer test
+pnpm --filter @toolpath/example-react-viewer... build
+pnpm --filter @toolpath/example-react-viewer test
+```
+The example imports built packages. `build:watch` on `@toolpath/viewer` refreshes
+that output during development. Browser tests need Chromium installed. When
+changing exports/assets, pack the viewer and test that artifact in a clean consumer;
+check both JS entries, declarations, toolbar CSS, and the bundled banana asset.
+Fixture URLs are redacted test data, not working download links. Keep retained
+fixtures unchanged and use a fixture copy when adapting URLs for a local test.
+See the [contributor guide](https://github.com/toolpath/ui-packages/blob/main/AGENTS.md)
+and [changelog](https://github.com/toolpath/ui-packages/blob/main/packages/viewer/CHANGELOG.md)
+for repo workflows and published changes.
+## License
+[MIT](https://github.com/toolpath/ui-packages/blob/main/packages/viewer/LICENSE).