@toolpath/viewer 2.3.1 → 2.3.3

package/README.md

@@ -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).