@toolpath/viewer 1.5.0 → 2.1.0

package/README.md

@@ -76,7 +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> <BoxStock>    translucent stock, included when fitting the camera
+ ├─ <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
@@ -146,9 +146,8 @@ context rather than a fact of the part surface.
 
 ### Stock and display controls
 
-Use `<BoxStock>` for an axis-aligned blank around a part, or `<Stock geometry={stockGeometry} />`
-for an actual stock mesh, including cylindrical or irregular blanks. Stock and part coordinates
-must use the same millimetre, Z-up frame. Both components include stock in Fit and Reset while
+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.
 
@@ -156,7 +155,7 @@ Stock does not intercept clicks or get clipped by the part's section plane.
 import { useMemo, useRef, useState } from 'react'
 import {
   Axes,
-  BoxStock,
+  Stock,
   DirectionArrows,
   PartMesh,
   Viewer,
@@ -187,7 +186,7 @@ export function StockPreview({ model, geometry }: { model: PartModel; geometry:
           regionHighlights={colors}
           activeDirection={directions ? direction : null}
         />
-        {stock && <BoxStock partGeometry={geometry} allowance={{ wall: 3, floor: 3 }} />}
+        {stock && <Stock box={{ partGeometry: geometry, allowance: { wall: 3, floor: 3 } }} />}
         {axes && <Axes />}
         <DirectionArrows
           directions={model.candidateDirections}
@@ -214,25 +213,103 @@ export function StockPreview({ model, geometry }: { model: PartModel; geometry:
 }
 ```
 
-`BoxStock.allowance` is padding **per side**, in millimetres. The preferred form is
+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 stock, pass `dimensions={{ x, y, z }}` instead. `position` accepts
+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` accepts `color`, `opacity` (default `0.2`), `edgeColor`, `edgeOpacity`, and `showEdges`.
-`BoxStock` accepts the same appearance props. Caller-provided geometry is never disposed; the
+`<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
@@ -280,8 +357,8 @@ individual buttons to use only the controls and order your application needs.
 </ViewerToolbarProvider>
 ```
 
-`ViewerToolbar.Controls`, `Divider`, and the thirteen `*Button` components are available on
-`ViewerToolbar`: `StockButton`, `AxesButton`, `GridButton`, `BananaButton`, `DirectionsButton`,
+`ViewerToolbar.Controls`, `Divider`, and the fourteen `*Button` components are available on
+`ViewerToolbar`: `StockButton`, `AxesButton`, `GridButton`, `BananaButton`, `ToolsButton`, `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
@@ -311,19 +388,19 @@ override any of these selectors in your application stylesheet.
 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                                                                                                                               |
+| 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`, `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
@@ -424,6 +501,7 @@ Draws the part and handles clicks. You only use it directly when you
 | `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.
@@ -529,6 +607,56 @@ what a label looks like is your stylesheet's, through the `toolpath-measure-labe
 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.
@@ -1108,6 +1236,7 @@ is a complete app built this way, with no API key needed.
 | `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
@@ -1121,6 +1250,7 @@ is a complete app built this way, with no API key needed.
 | `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.     |

package/dist/{chunk-4TBLMR4Z.js → chunk-WTTOUG4P.js}

@@ -13,6 +13,15 @@ import {
 } from "react";
 import { Vector3 as Vector311 } from "three";
 
+// src/part-context.tsx
+import { createContext, useContext } from "react";
+var PartContext = createContext(null);
+var usePartContext = () => {
+  const part = useContext(PartContext);
+  if (!part) throw new Error("usePartContext must be used inside <PartMesh> or <EnginePart>");
+  return part;
+};
+
 // src/model/directions.ts
 var EPSILON = 1e-6;
 function sameDirection(a, b) {
@@ -781,8 +790,8 @@ function perpendicular(axis) {
 // src/tap.tsx
 import { useThree } from "@react-three/fiber";
 import {
-  createContext,
-  useContext,
+  createContext as createContext2,
+  useContext as useContext2,
   useEffect,
   useMemo,
   useRef
@@ -823,10 +832,10 @@ function trackDoubleTaps(within = DOUBLE_TAP_MS, slop = TAP_SLOP) {
 
 // src/tap.tsx
 import { jsx } from "react/jsx-runtime";
-var ViewerTapContext = createContext(null);
+var ViewerTapContext = createContext2(null);
 var ViewerTapProvider = ({ value, children }) => /* @__PURE__ */ jsx(ViewerTapContext.Provider, { value, children });
 function useTapGuard() {
-  const shared = useContext(ViewerTapContext);
+  const shared = useContext2(ViewerTapContext);
   const domElement = useThree((state) => state.gl.domElement);
   const tracker = useRef(null);
   useEffect(() => {
@@ -1319,10 +1328,10 @@ function focusForPick(pick, previousRegion, previousFocus) {
 // src/viewer.tsx
 import { Canvas, useFrame as useFrame3, useThree as useThree4 } from "@react-three/fiber";
 import {
-  createContext as createContext2,
+  createContext as createContext3,
   forwardRef,
   useCallback,
-  useContext as useContext2,
+  useContext as useContext3,
   useEffect as useEffect4,
   useImperativeHandle,
   useMemo as useMemo4,
@@ -2193,20 +2202,20 @@ function labelTexture(label, color) {
 
 // src/viewer.tsx
 import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
-var ViewerControlsContext = createContext2(null);
+var ViewerControlsContext = createContext3(null);
 var useViewerControls = () => {
-  const controls = useContext2(ViewerControlsContext);
+  const controls = useContext3(ViewerControlsContext);
   if (!controls) throw new Error("useViewerControls must be used inside <Viewer>");
   return controls;
 };
-var SectionStoreContext = createContext2(null);
+var SectionStoreContext = createContext3(null);
 var useSectionStore = () => {
-  const store = useContext2(SectionStoreContext);
+  const store = useContext3(SectionStoreContext);
   if (!store) throw new Error("useSectionStore must be used inside <Viewer>");
   return store;
 };
-var ViewerRetargetContext = createContext2(null);
-var useRetarget = () => useContext2(ViewerRetargetContext);
+var ViewerRetargetContext = createContext3(null);
+var useRetarget = () => useContext3(ViewerRetargetContext);
 var ViewerScene = ({
   children,
   setControls,
@@ -3029,9 +3038,11 @@ var PartMesh = ({
   onPick,
   theme,
   showEdges = true,
-  display = "solid"
+  display = "solid",
+  children
 }) => {
   const { camera, controls, invalidate } = useThree7();
+  const context = useMemo6(() => ({ model, geometry }), [model, geometry]);
   const viewerControls = useViewerControls();
   const resolved = useStableTheme(theme);
   const currentTheme = useRef6(resolved);
@@ -3243,7 +3254,8 @@ var PartMesh = ({
         showHandle: !controlled || onSectionChange !== void 0,
         onDrag: !controlled || onSectionChange ? dragSection : void 0
       }
-    ) : null
+    ) : null,
+    children ? /* @__PURE__ */ jsx5(PartContext.Provider, { value: context, children }) : null
   ] });
 };
 var ORIGIN = new Vector311();
@@ -3890,6 +3902,7 @@ function useGeometryResource(part) {
 }
 
 export {
+  usePartContext,
   sameDirection,
   directionIndexOf,
   groupByDirection,

package/dist/engine/index.d.ts

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

package/dist/engine/index.js

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