@toolpath/viewer 1.4.0 → 2.0.0

package/README.md

@@ -76,6 +76,7 @@ What each wrapper is for:
  ├─ <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
@@ -95,6 +96,16 @@ What each wrapper is for:
 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.
+
+```tsx
+<EnginePart report={report} selection={selection} focus={{ opacity: 0.12 }} />
+```
+
 Parts are in **millimetres** with **Z pointing up**. The camera uses the same convention.
 
 ### A click usually matches several features
@@ -103,23 +114,298 @@ The same face is usually owned by **5–8 features at once**, even on a plain cu
 `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.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          |
+| 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.
+
 ## Components
 
+### Stock and display controls
+
+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.
+
+```tsx
+import { useMemo, useRef, useState } from 'react'
+import {
+  Axes,
+  Stock,
+  DirectionArrows,
+  PartMesh,
+  Viewer,
+  directionHighlights,
+} 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],
+  )
+
+  return (
+    <>
+      <Viewer ref={viewer} style={{ height: 500 }}>
+        <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))}
+        />
+      </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>
+    </>
+  )
+}
+```
+
+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.
+
+```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>
+```
+
+`ViewerToolbar.Controls`, `Divider`, and the thirteen `*Button` components are available on
+`ViewerToolbar`: `StockButton`, `AxesButton`, `GridButton`, `BananaButton`, `DirectionsButton`,
+`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`, `directions`, `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.
+
 ### `<Viewer>`
 
 The canvas that holds everything. Import it from `@toolpath/viewer`.
@@ -127,7 +413,7 @@ 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'`     | Mouse mapping. See [Mouse controls](#mouse-controls).                                                       |
+| `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.                                                          |
@@ -142,20 +428,35 @@ Changing `projection` rebuilds the canvas and returns the camera to its starting
 
 The canvas is transparent. To set a background colour, style the wrapper or its parent.
 
-#### Mouse controls
+#### 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.
+
+| 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.
 
-| Action                | `controls="toolpath"` (default) | `controls="fusion"` (like Fusion 360)      |
-| --------------------- | ------------------------------- | ------------------------------------------ |
-| Rotate                | Left-drag                       | Shift + middle-drag, or Shift + scroll     |
-| Pan                   | Right-drag or middle-drag       | Middle-drag, or scroll / two-finger scroll |
-| Zoom                  | Scroll wheel                    | Trackpad pinch                             |
-| Rotate around a point | Double-click the part           | Double-click the part                      |
-| Fit whole part        | Double middle-click             | Double middle-click                        |
+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.
 
-In `fusion` mode, left-drag doesn't move the camera, and the scroll wheel pans instead of zooming.
-On touch screens, one finger rotates and two fingers pinch and pan.
+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.
 
-Dragging never selects anything. A click only counts if the pointer barely moved.
+`'toolpath'`, `freeOrbit={true}`, and `zoomTo="cursor"` are the defaults.
 
 ### `<EnginePart>`
 
@@ -176,28 +477,30 @@ Draws the part and handles clicks. You only use it directly when you
 
 **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.                                   |
-| `theme`             | `Partial<ViewerTheme>` | Override the part's 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.                                                                          |
+| `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`).                             |
-| `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.                                             |
+| 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.                                              |
 
 Hovering over the part is handled for you. You only need `onHover` if you want to show the hovered
 feature elsewhere in your UI.
@@ -478,7 +781,10 @@ no `section` prop:
 
 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, an arrow drags it, an outlined sheet shows the cutting plane, and Escape clears it.
+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.
@@ -505,7 +811,7 @@ const [offset, setOffset] = useState(0.5)
 ```
 
 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 an arrow handle users can drag. The handler is
+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`.
 
@@ -625,10 +931,11 @@ go on the cube. See `DEFAULT_THEME` for every key. The default part colours are
 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` the drag arrow, and `sectionOutline` the cutting-plane sheet and
-preview that `<SectionTool>` draws. `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.
+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.
 
 `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.
@@ -872,12 +1179,13 @@ is a complete app built this way, with no API key needed.
 
 ### Hooks
 
-| Hook                  | Use inside `<Viewer>` to…                                                        |
-| --------------------- | -------------------------------------------------------------------------------- |
-| `useViewerControls()` | Get `fit`, `reset`, `setView`, `setViewDirection`, `frameBox`, and `setSection`. |
-| `useSectionStore()`   | Read, set, or subscribe to the viewer's own cut.                                 |
-| `useContentBox()`     | Get the part's bounding box (a `THREE.Box3`, empty until loaded).                |
-| `useTapGuard()`       | Check whether a pointer event was a click and not a drag.                        |
+| 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).                |
+| `useTapGuard()`       | Inside `<Viewer>`                | Check whether a pointer event was a click and not a drag.                        |
 
 ### Helpers
 
@@ -903,11 +1211,12 @@ use. They're listed in `dist/index.d.ts`.
 
 `ViewerProps`, `ViewerHandle`, `ViewerView`, `Projection`, `ControlScheme`, `EnginePartProps`,
 `PartMeshProps`, `PartPick`, `PickModifiers`, `PartModel`, `PartModelFeature`, `PartModelRegion`,
-`FeatureTag`, `FeatureType`, `Vec3`, `FeatureHighlight`, `RegionHighlight`, `SectionOptions`,
+`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`.
+`ViewCubeProps`, `ViewerToolbarProps`, `ViewerToolbarControlsProps`, `ViewerToolbarControls`,
+`ViewerToolbarControl`.
 
 `FeatureType` and `ShapeKind` accept any string, because newer Engine versions add new values.
 Handle values you don't recognize.