From 6d4a91f82cc241a3f32e767014944945d77a7d79 Mon Sep 17 00:00:00 2001
From: dementive <87823030+dementive@users.noreply.github.com>
Date: Wed, 30 Sep 2026 11:12:12 -0400
Subject: [PATCH 1/5] Cylinder stock rendering

---
 .changeset/cylinder-stock.md                |   5 +
 examples/react-viewer/src/main.tsx          | 160 +++++++++-----
 examples/react-viewer/tests/toolbar.spec.ts |  18 ++
 packages/viewer/README.md                   |  33 ++-
 packages/viewer/src/index.ts                |  18 +-
 packages/viewer/src/render/stock.ts         | 182 ++++++++++++++--
 packages/viewer/src/stock.tsx               |  45 +++-
 packages/viewer/tests/stock.test.ts         | 222 +++++++++++++++++++-
 8 files changed, 605 insertions(+), 78 deletions(-)
 create mode 100644 .changeset/cylinder-stock.md

diff --git a/.changeset/cylinder-stock.md b/.changeset/cylinder-stock.md
new file mode 100644
index 0000000..993af04
--- /dev/null
+++ b/.changeset/cylinder-stock.md
@@ -0,0 +1,5 @@
+---
+'@toolpath/viewer': minor
+---
+
+Add `CylinderStock` for round stock along any axis, `fixedCylinderStock` for a fixed-cylinder preview placed by the same position rule as fixed-box stock, and `OrientedBoxStock` for a block squared to a frame of its own, such as a plan's setup-squared stock box. Stock outlines are now built only when shown.
diff --git a/examples/react-viewer/src/main.tsx b/examples/react-viewer/src/main.tsx
index 9264763..371318f 100644
--- a/examples/react-viewer/src/main.tsx
+++ b/examples/react-viewer/src/main.tsx
@@ -6,7 +6,9 @@ import {
   Axes,
   Banana,
   BoxStock,
+  CylinderStock,
   fixedBoxStockBounds,
+  fixedCylinderStock,
   directionHighlights,
   directionLabel,
   directionColor,
@@ -215,7 +217,11 @@ const App = () => {
   const [showDirections, setShowDirections] = useState(false)
   const [focus, setFocus] = useState(false)
   const [wireframe, setWireframe] = useState(false)
+  const [stockShape, setStockShape] = useState<'box' | 'cylinder'>(
+    params.get('stockShape') === 'cylinder' ? 'cylinder' : 'box',
+  )
   const [stockDimensions, setStockDimensions] = useState({ x: 25.908, y: 25.908, z: 25.908 })
+  const [stockCylinder, setStockCylinder] = useState({ diameter: 38.1, length: 25.908 })
   const [stockPosition, setStockPosition] = useState<StockPosition>('model_centered')
   const [stockPositionOffset, setStockPositionOffset] = useState(0)
   const stockSize = useMemo(
@@ -228,6 +234,10 @@ const App = () => {
       ).getSize(new THREE.Vector3()),
     [part.geometry, stockDimensions, stockPosition, stockPositionOffset],
   )
+  const cylinderFigure = useMemo(
+    () => fixedCylinderStock(part.geometry, stockCylinder, stockPosition, stockPositionOffset),
+    [part.geometry, stockCylinder, stockPosition, stockPositionOffset],
+  )
   const highlights = useMemo(
     () => (showDirections ? directionHighlights(part.model, direction) : []),
     [direction, part.model, showDirections],
@@ -346,57 +356,106 @@ const App = () => {
         <p>{part.hint}</p>
         <p>
           <strong>Stock:</strong>{' '}
-          {stockSize
-            .toArray()
-            .map((value) => value.toFixed(2))
-            .join(' × ')}{' '}
-          mm (X × Y × Z)
+          {stockShape === 'cylinder'
+            ? `⌀${cylinderFigure.diameter.toFixed(2)} × ${cylinderFigure.length.toFixed(2)} mm (diameter × length)`
+            : `${stockSize
+                .toArray()
+                .map((value) => value.toFixed(2))
+                .join(' × ')} mm (X × Y × Z)`}
         </p>
         <label className="stock-allowance">
-          Stock X dimension (mm)
-          <input
-            type="number"
-            min="0"
-            max="100"
-            step="0.5"
-            value={stockDimensions.x}
-            onChange={(event) => {
-              const value = event.target.valueAsNumber
-              if (Number.isFinite(value) && value > 0 && value <= 1000)
-                setStockDimensions((current) => ({ ...current, x: value }))
-            }}
-          />
-        </label>
-        <label className="stock-allowance">
-          Stock Y dimension (mm)
-          <input
-            type="number"
-            min="0"
-            max="100"
-            step="0.5"
-            value={stockDimensions.y}
-            onChange={(event) => {
-              const value = event.target.valueAsNumber
-              if (Number.isFinite(value) && value > 0 && value <= 1000)
-                setStockDimensions((current) => ({ ...current, y: value }))
-            }}
-          />
-        </label>
-        <label className="stock-allowance">
-          Stock Z dimension (mm)
-          <input
-            type="number"
-            min="0.01"
-            max="1000"
-            step="0.01"
-            value={stockDimensions.z}
-            onChange={(event) => {
-              const value = event.target.valueAsNumber
-              if (Number.isFinite(value) && value > 0 && value <= 1000)
-                setStockDimensions((current) => ({ ...current, z: value }))
-            }}
-          />
+          Stock shape
+          <select
+            value={stockShape}
+            onChange={(event) => setStockShape(event.target.value as 'box' | 'cylinder')}
+          >
+            <option value="box">Box</option>
+            <option value="cylinder">Cylinder</option>
+          </select>
         </label>
+        {stockShape === 'cylinder' ? (
+          <>
+            <label className="stock-allowance">
+              Stock diameter (mm)
+              <input
+                type="number"
+                min="0.01"
+                max="1000"
+                step="0.01"
+                value={stockCylinder.diameter}
+                onChange={(event) => {
+                  const value = event.target.valueAsNumber
+                  if (Number.isFinite(value) && value > 0 && value <= 1000)
+                    setStockCylinder((current) => ({ ...current, diameter: value }))
+                }}
+              />
+            </label>
+            <label className="stock-allowance">
+              Stock length (mm)
+              <input
+                type="number"
+                min="0.01"
+                max="1000"
+                step="0.01"
+                value={stockCylinder.length}
+                onChange={(event) => {
+                  const value = event.target.valueAsNumber
+                  if (Number.isFinite(value) && value > 0 && value <= 1000)
+                    setStockCylinder((current) => ({ ...current, length: value }))
+                }}
+              />
+            </label>
+          </>
+        ) : null}
+        {stockShape === 'box' ? (
+          <>
+            <label className="stock-allowance">
+              Stock X dimension (mm)
+              <input
+                type="number"
+                min="0"
+                max="100"
+                step="0.5"
+                value={stockDimensions.x}
+                onChange={(event) => {
+                  const value = event.target.valueAsNumber
+                  if (Number.isFinite(value) && value > 0 && value <= 1000)
+                    setStockDimensions((current) => ({ ...current, x: value }))
+                }}
+              />
+            </label>
+            <label className="stock-allowance">
+              Stock Y dimension (mm)
+              <input
+                type="number"
+                min="0"
+                max="100"
+                step="0.5"
+                value={stockDimensions.y}
+                onChange={(event) => {
+                  const value = event.target.valueAsNumber
+                  if (Number.isFinite(value) && value > 0 && value <= 1000)
+                    setStockDimensions((current) => ({ ...current, y: value }))
+                }}
+              />
+            </label>
+            <label className="stock-allowance">
+              Stock Z dimension (mm)
+              <input
+                type="number"
+                min="0.01"
+                max="1000"
+                step="0.01"
+                value={stockDimensions.z}
+                onChange={(event) => {
+                  const value = event.target.valueAsNumber
+                  if (Number.isFinite(value) && value > 0 && value <= 1000)
+                    setStockDimensions((current) => ({ ...current, z: value }))
+                }}
+              />
+            </label>
+          </>
+        ) : null}
         <label className="stock-allowance">
           Stock position
           <select
@@ -426,7 +485,7 @@ const App = () => {
           </label>
         ) : null}
         <p className="small-note">
-          Fixed box stock dimensions and position. Values are millimetres.
+          Fixed stock shape, dimensions and position. Values are millimetres.
         </p>
         <button
           className="detail-button"
@@ -605,7 +664,8 @@ const App = () => {
               }}
               onPick={(pick: PartPick) => setSelected([...pick.ranked])}
             />
-            {showStock ? (
+            {showStock && stockShape === 'cylinder' ? <CylinderStock {...cylinderFigure} /> : null}
+            {showStock && stockShape === 'box' ? (
               <BoxStock
                 partGeometry={part.geometry}
                 dimensions={stockDimensions}
diff --git a/examples/react-viewer/tests/toolbar.spec.ts b/examples/react-viewer/tests/toolbar.spec.ts
index 5669fcc..3f4f02c 100644
--- a/examples/react-viewer/tests/toolbar.spec.ts
+++ b/examples/react-viewer/tests/toolbar.spec.ts
@@ -161,6 +161,24 @@ for (const projection of ['perspective', 'orthographic'] as const) {
     await expect.poll(async () => Buffer.compare(focused, await canvas.screenshot())).not.toBe(0)
   })
 
+  test(`cylinder stock mounts cleanly and fits with the part (${projection})`, async ({ page }) => {
+    const { canvas } = await openViewer(
+      page,
+      `projection=${projection}&stock=on&stockShape=cylinder`,
+    )
+    const stock = page.locator('p', { hasText: 'Stock:' })
+    await expect(stock).toContainText('⌀38.10 × 25.91')
+    const before = await readCamera(page)
+    const narrow = await canvas.screenshot()
+    await page.getByRole('spinbutton', { name: 'Stock diameter (mm)' }).fill('60')
+    await expect(stock).toContainText('⌀60.00 × 25.91')
+    await expect.poll(async () => Buffer.compare(narrow, await canvas.screenshot())).not.toBe(0)
+    await page.getByRole('button', { name: 'Fit', exact: true }).click()
+    await expect
+      .poll(async () => (await readCamera(page)).distance)
+      .toBeGreaterThan(before.distance)
+  })
+
   test(`stock present on mount does not move the section midpoint (${projection})`, async ({
     page,
   }) => {
diff --git a/packages/viewer/README.md b/packages/viewer/README.md
index 81d7690..6525bda 100644
--- a/packages/viewer/README.md
+++ b/packages/viewer/README.md
@@ -76,7 +76,8 @@ 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> <BoxStock> <CylinderStock> <OrientedBoxStock>
+ │                        translucent stock, included when fitting the camera
  ├─ <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,8 +147,10 @@ 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
+Use `<BoxStock>` for an axis-aligned blank around a part, `<CylinderStock>` for round stock,
+`<OrientedBoxStock>` for a block squared to a frame of its own, or
+`<Stock geometry={stockGeometry} />` for an actual stock mesh, such as irregular or in-process
+stock. Stock and part coordinates
 must use the same millimetre, Z-up frame. Both components include stock 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.
@@ -228,8 +231,30 @@ 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.
 
+`<CylinderStock 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. `fixedCylinderStock(geometry, { diameter, length }, position, positionOffset)` returns
+that figure for a fixed-cylinder preview, standing along the part's Z, centred on the part's
+bounding box, and placed along Z by the same `position` rule as fixed-box stock — so
+`<CylinderStock {...fixedCylinderStock(geometry, size)} />` previews it. Memoise the figure: it reads
+every vertex of the part. It is a preview; 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.
+
+`<OrientedBoxStock 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`. That is the shape of an Engine plan's
+`stock` box, which is squared to the setup rather than to the part.
+
+`CylinderStock` and `OrientedBoxStock` rebuild their mesh only when the figure's numbers change, so
+a figure read off a fresh API response does not rebuild the same stock. 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 `color`, `opacity` (default `0.2`), `edgeColor`, `edgeOpacity`, and `showEdges`.
-`BoxStock` accepts the same appearance props. Caller-provided geometry is never disposed; the
+The outline is built the first time it is shown, so a large stock mesh with `showEdges={false}`
+costs no edge pass. `BoxStock`, `CylinderStock` and `OrientedBoxStock` 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.
 
diff --git a/packages/viewer/src/index.ts b/packages/viewer/src/index.ts
index 4524fc2..fe3b224 100644
--- a/packages/viewer/src/index.ts
+++ b/packages/viewer/src/index.ts
@@ -13,11 +13,21 @@ export type {
   ViewerToolbarControlsProps,
   ViewerToolbarProps,
 } from './viewer-toolbar.js'
-export { Stock, BoxStock } from './stock.js'
-export type { StockProps, BoxStockProps } from './stock.js'
+export { Stock, BoxStock, CylinderStock, OrientedBoxStock } from './stock.js'
+export type {
+  StockProps,
+  BoxStockProps,
+  CylinderStockProps,
+  OrientedBoxStockProps,
+} from './stock.js'
 export { Banana, BANANA_MODEL_URL } from './banana.js'
-export { boxStockBounds, fixedBoxStockBounds } from './render/stock.js'
-export type { StockAllowance, StockPosition } from './render/stock.js'
+export { boxStockBounds, fixedBoxStockBounds, fixedCylinderStock } from './render/stock.js'
+export type {
+  CylinderStockFigure,
+  OrientedBoxStockFigure,
+  StockAllowance,
+  StockPosition,
+} from './render/stock.js'
 export { directionHighlights } from './render/direction-highlights.js'
 export type { PartDisplay } from './render/part.js'
 export { Axes, Grid, ViewCube } from './primitives.js'
diff --git a/packages/viewer/src/render/stock.ts b/packages/viewer/src/render/stock.ts
index 3721007..3c4db0f 100644
--- a/packages/viewer/src/render/stock.ts
+++ b/packages/viewer/src/render/stock.ts
@@ -1,12 +1,16 @@
 import {
   Box3,
+  BoxGeometry,
   type BufferGeometry,
+  CylinderGeometry,
   EdgesGeometry,
   Group,
   LineBasicMaterial,
   LineSegments,
+  Matrix4,
   Mesh,
   MeshLambertMaterial,
+  Quaternion,
   Vector3,
 } from 'three'
 import type { Vec3 } from '../model/types.js'
@@ -21,9 +25,43 @@ import { STOCK_OBJECT } from './camera.js'
  */
 export type StockAllowance = number | Vec3 | { wall: number; floor: number }
 
-/** How an explicit box is positioned relative to the part's Z bounds. */
+/** How explicit fixed stock is positioned relative to the part's Z bounds. */
 export type StockPosition = 'model_centered' | 'offset_from_top' | 'offset_from_bottom'
 
+/**
+ * Round stock in part coordinates, in millimetres: the centre of its base, the
+ * direction from the base toward its far end, and its size. The Engine's
+ * resolved `StockCylinder` carries the same four figures.
+ */
+export interface CylinderStockFigure {
+  origin: Vec3
+  axis: Vec3
+  diameter: number
+  length: number
+}
+
+/**
+ * A block squared to a frame of its own rather than to the part, in
+ * millimetres. `lower` and `upper` are corners in `frame`, whose point
+ * `(x, y, z)` sits at `location + x·refDirection + y·(axis × refDirection) + z·axis`
+ * in part coordinates. This is the shape of the Engine's plan `StockBox`, which
+ * is squared to the setup.
+ */
+export interface OrientedBoxStockFigure {
+  frame: { location: Vec3; axis: Vec3; refDirection: Vec3 }
+  lower: Vec3
+  upper: Vec3
+}
+
+/**
+ * Sides on a cylinder's rings. Adjacent sides meet at under 6°, well inside the
+ * outline's 15° crease, so the outline draws the two rims and no facet lines.
+ */
+const CYLINDER_SEGMENTS = 64
+
+/** three.js builds a cylinder about +Y, centred on the origin. */
+const CYLINDER_AXIS = new Vector3(0, 1, 0)
+
 /**
  * Bounds for an explicit fixed box. X/Y are centered on the part's bounding
  * box; Z is centered, offset from the top, or offset from the bottom. `offset`
@@ -50,19 +88,119 @@ export function fixedBoxStockBounds(
   }
   const part = partBounds(geometry)
   const center = part.getCenter(new Vector3())
-  const z =
-    position === 'offset_from_top'
-      ? part.max.z + positionOffset - dimensions.z / 2
-      : position === 'offset_from_bottom'
-        ? part.min.z - positionOffset + dimensions.z / 2
-        : center.z
-  const half = new Vector3(dimensions.x / 2, dimensions.y / 2, dimensions.z / 2)
+  const z = fixedStockLowerZ(part, dimensions.z, position, positionOffset)
   return new Box3(
-    new Vector3(center.x, center.y, z).sub(half),
-    new Vector3(center.x, center.y, z).add(half),
+    new Vector3(center.x - dimensions.x / 2, center.y - dimensions.y / 2, z),
+    new Vector3(center.x + dimensions.x / 2, center.y + dimensions.y / 2, z + dimensions.z),
   ).translate(new Vector3(offset.x, offset.y, offset.z))
 }
 
+/**
+ * A preview of fixed round stock: `diameter` across and `length` long, standing
+ * along the part's Z, centred on the part's bounding box across it, and placed
+ * along it by the same position rule as {@link fixedBoxStockBounds}.
+ *
+ * It is a preview, as the legacy app's was. The kernel stands fixed round stock
+ * along the first setup's cutting direction and centres it on the part's
+ * smallest enclosing circle, which the bounding-box centre only approximates.
+ * Once a job is planned, render the stock it resolved instead.
+ */
+export function fixedCylinderStock(
+  geometry: BufferGeometry,
+  size: { diameter: number; length: number },
+  position: StockPosition = 'model_centered',
+  positionOffset = 0,
+): CylinderStockFigure {
+  if (![size.diameter, size.length].every((value) => Number.isFinite(value) && value > 0)) {
+    throw new RangeError('Fixed stock diameter and length must be finite and positive.')
+  }
+  if (!Number.isFinite(positionOffset)) {
+    throw new RangeError('Fixed stock position offset must be finite.')
+  }
+  const part = partBounds(geometry)
+  const center = part.getCenter(new Vector3())
+  return {
+    origin: {
+      x: center.x,
+      y: center.y,
+      z: fixedStockLowerZ(part, size.length, position, positionOffset),
+    },
+    axis: { x: 0, y: 0, z: 1 },
+    diameter: size.diameter,
+    length: size.length,
+  }
+}
+
+/**
+ * Where fixed stock `length` long starts along Z. Centred splits the extra
+ * length evenly and ignores the offset; from the top puts the stock's top
+ * `positionOffset` above the part's; from the bottom puts its bottom
+ * `positionOffset` below the part's. The kernel places both fixed shapes by
+ * this one rule, so both previews share it too.
+ */
+function fixedStockLowerZ(
+  part: Box3,
+  length: number,
+  position: StockPosition,
+  positionOffset: number,
+): number {
+  if (position === 'offset_from_top') return part.max.z + positionOffset - length
+  if (position === 'offset_from_bottom') return part.min.z - positionOffset
+  return (part.min.z + part.max.z - length) / 2
+}
+
+/** A closed cylinder for `figure`, in part coordinates. */
+export function cylinderStockGeometry(figure: CylinderStockFigure): BufferGeometry {
+  const { origin, diameter, length } = figure
+  if (![origin.x, origin.y, origin.z].every(Number.isFinite)) {
+    throw new RangeError('Cylinder stock origin must be finite.')
+  }
+  if (![diameter, length].every((value) => Number.isFinite(value) && value > 0)) {
+    throw new RangeError('Cylinder stock diameter and length must be finite and positive.')
+  }
+  const axis = new Vector3(figure.axis.x, figure.axis.y, figure.axis.z)
+  const norm = axis.length()
+  if (!Number.isFinite(norm) || norm === 0) {
+    throw new RangeError('Cylinder stock axis must be finite and non-zero.')
+  }
+  axis.divideScalar(norm)
+  const center = axis
+    .clone()
+    .multiplyScalar(length / 2)
+    .add(new Vector3(origin.x, origin.y, origin.z))
+  return new CylinderGeometry(diameter / 2, diameter / 2, length, CYLINDER_SEGMENTS)
+    .applyQuaternion(new Quaternion().setFromUnitVectors(CYLINDER_AXIS, axis))
+    .translate(center.x, center.y, center.z)
+}
+
+/** A closed block for `figure`, in part coordinates. */
+export function orientedBoxStockGeometry(figure: OrientedBoxStockFigure): BufferGeometry {
+  const { frame, lower, upper } = figure
+  const { location, axis, refDirection } = frame
+  if (
+    ![location, axis, refDirection, lower, upper].every((vector) =>
+      [vector.x, vector.y, vector.z].every(Number.isFinite),
+    )
+  ) {
+    throw new RangeError('Box stock frame and corners must be finite.')
+  }
+  const size = new Vector3(upper.x - lower.x, upper.y - lower.y, upper.z - lower.z)
+  if (size.toArray().some((value) => !(value > 0))) {
+    throw new RangeError('Box stock upper corner must be above its lower corner on every axis.')
+  }
+  const x = new Vector3(refDirection.x, refDirection.y, refDirection.z)
+  const z = new Vector3(axis.x, axis.y, axis.z)
+  const y = new Vector3().crossVectors(z, x)
+  if (!(y.length() > 0)) {
+    throw new RangeError(
+      'Box stock frame axis and reference direction must be non-zero and not parallel.',
+    )
+  }
+  return new BoxGeometry(size.x, size.y, size.z)
+    .translate((lower.x + upper.x) / 2, (lower.y + upper.y) / 2, (lower.z + upper.z) / 2)
+    .applyMatrix4(new Matrix4().makeBasis(x, y, z).setPosition(location.x, location.y, location.z))
+}
+
 /** Per-side allowance and centre offset in millimetres, in the part's coordinates. */
 export function boxStockBounds(
   geometry: BufferGeometry,
@@ -111,24 +249,34 @@ export function createStock(geometry: BufferGeometry) {
   const material = new MeshLambertMaterial({ transparent: true, depthWrite: false })
   const edgeMaterial = new LineBasicMaterial({ transparent: true, depthWrite: false })
   const mesh = new Mesh(geometry, material)
-  const edgeGeometry = new EdgesGeometry(geometry, 15)
-  const edges = new LineSegments(edgeGeometry, edgeMaterial)
   const object = new Group()
   object.userData[STOCK_OBJECT] = true
   mesh.renderOrder = 5
-  edges.renderOrder = 6
   mesh.raycast = () => {}
-  edges.raycast = () => {}
-  object.add(mesh, edges)
+  object.add(mesh)
+  let edges: LineSegments<EdgesGeometry, LineBasicMaterial> | null = null
   return {
     object,
     material,
     edgeMaterial,
-    edges,
+    /**
+     * Shows or hides the outline, building it the first time it is shown: the
+     * edge pass reads every triangle, and stock cut by a toolpath has a great
+     * many of them.
+     */
+    showEdges(show: boolean) {
+      if (show && !edges) {
+        edges = new LineSegments(new EdgesGeometry(geometry, 15), edgeMaterial)
+        edges.renderOrder = 6
+        edges.raycast = () => {}
+        object.add(edges)
+      }
+      if (edges) edges.visible = show
+    },
     dispose() {
       material.dispose()
       edgeMaterial.dispose()
-      edgeGeometry.dispose()
+      edges?.geometry.dispose()
     },
   }
 }
diff --git a/packages/viewer/src/stock.tsx b/packages/viewer/src/stock.tsx
index f0fd4ab..bfbaf6c 100644
--- a/packages/viewer/src/stock.tsx
+++ b/packages/viewer/src/stock.tsx
@@ -5,7 +5,11 @@ import type { Vec3 } from './model/types.js'
 import {
   boxStockBounds,
   createStock,
+  cylinderStockGeometry,
+  type CylinderStockFigure,
   fixedBoxStockBounds,
+  orientedBoxStockGeometry,
+  type OrientedBoxStockFigure,
   type StockAllowance,
   type StockPosition,
 } from './render/stock.js'
@@ -37,7 +41,7 @@ export const Stock = ({
     stock.material.opacity = opacity
     stock.edgeMaterial.color.setHex(edgeColor)
     stock.edgeMaterial.opacity = edgeOpacity
-    stock.edges.visible = showEdges
+    stock.showEdges(showEdges)
     invalidate()
   }, [color, edgeColor, edgeOpacity, invalidate, opacity, showEdges, stock])
   return <primitive object={stock.object} dispose={null} />
@@ -89,3 +93,42 @@ export const BoxStock = ({
   useEffect(() => () => geometry.dispose(), [geometry])
   return <Stock geometry={geometry} {...props} />
 }
+
+export interface CylinderStockProps extends Omit<StockProps, 'geometry'>, CylinderStockFigure {}
+
+/**
+ * Round stock along any axis, from its base centre, axis, diameter and length
+ * in part coordinates. Pass `fixedCylinderStock`'s figure for a preview,
+ * or a planned job's resolved cylinder for the stock it was cut from.
+ */
+export const CylinderStock = ({ origin, axis, diameter, length, ...props }: CylinderStockProps) => {
+  // Keyed on the figure's numbers rather than its identity: a figure read off
+  // an API response is a new object on every fetch, and the same stock should
+  // not rebuild its mesh.
+  const figure = JSON.stringify({ origin, axis, diameter, length })
+  const geometry = useMemo(
+    () => cylinderStockGeometry(JSON.parse(figure) as CylinderStockFigure),
+    [figure],
+  )
+  useEffect(() => () => geometry.dispose(), [geometry])
+  return <Stock geometry={geometry} {...props} />
+}
+
+export interface OrientedBoxStockProps
+  extends Omit<StockProps, 'geometry'>,
+    OrientedBoxStockFigure {}
+
+/**
+ * A block squared to its own frame rather than to the part, such as a planned
+ * job's stock box, which is squared to the setup. Use BoxStock for a block
+ * squared to the part.
+ */
+export const OrientedBoxStock = ({ frame, lower, upper, ...props }: OrientedBoxStockProps) => {
+  const figure = JSON.stringify({ frame, lower, upper })
+  const geometry = useMemo(
+    () => orientedBoxStockGeometry(JSON.parse(figure) as OrientedBoxStockFigure),
+    [figure],
+  )
+  useEffect(() => () => geometry.dispose(), [geometry])
+  return <Stock geometry={geometry} {...props} />
+}
diff --git a/packages/viewer/tests/stock.test.ts b/packages/viewer/tests/stock.test.ts
index debfa9b..bce8864 100644
--- a/packages/viewer/tests/stock.test.ts
+++ b/packages/viewer/tests/stock.test.ts
@@ -2,16 +2,52 @@ import {
   Box3,
   BoxGeometry,
   BufferGeometry,
+  EdgesGeometry,
   Float32BufferAttribute,
   Group,
+  LineSegments,
   Mesh,
   Raycaster,
   Vector3,
 } from 'three'
 import { describe, expect, it, vi } from 'vitest'
+import type { Vec3 } from '../src/model/types.js'
 import { contentBounds, partBounds } from '../src/render/camera.js'
 import { hitUnderRay } from '../src/render/section.js'
-import { boxStockBounds, createStock, fixedBoxStockBounds } from '../src/render/stock.js'
+import {
+  boxStockBounds,
+  createStock,
+  cylinderStockGeometry,
+  fixedBoxStockBounds,
+  fixedCylinderStock,
+  orientedBoxStockGeometry,
+  type StockPosition,
+} from '../src/render/stock.js'
+
+const bounds = (geometry: BufferGeometry) => {
+  geometry.computeBoundingBox()
+  return geometry.boundingBox!
+}
+
+/**
+ * Where every vertex of a cylinder mesh sits relative to the figure: how far
+ * along the axis from the base, and how far out from the axis.
+ */
+function cylinderSpan(geometry: BufferGeometry, origin: Vec3, axis: Vec3) {
+  const base = new Vector3(origin.x, origin.y, origin.z)
+  const direction = new Vector3(axis.x, axis.y, axis.z).normalize()
+  const position = geometry.getAttribute('position')
+  const point = new Vector3()
+  let along = { min: Infinity, max: -Infinity }
+  let radius = 0
+  for (let index = 0; index < position.count; index += 1) {
+    point.fromBufferAttribute(position, index).sub(base)
+    const t = point.dot(direction)
+    along = { min: Math.min(along.min, t), max: Math.max(along.max, t) }
+    radius = Math.max(radius, point.addScaledVector(direction, -t).length())
+  }
+  return { along, radius }
+}
 
 describe('stock dimensions', () => {
   it('adds allowance on both sides and offsets from an off-origin part centre', () => {
@@ -76,6 +112,171 @@ describe('stock dimensions', () => {
   })
 })
 
+describe('fixed cylinder stock', () => {
+  const part = () => new BoxGeometry(20, 30, 10).translate(40, -10, 5)
+
+  it('stands on the part Z and centres on its bounding box', () => {
+    expect(fixedCylinderStock(part(), { diameter: 50, length: 20 })).toEqual({
+      origin: { x: 40, y: -10, z: -5 },
+      axis: { x: 0, y: 0, z: 1 },
+      diameter: 50,
+      length: 20,
+    })
+  })
+
+  it('places its ends by the same rule as a fixed box', () => {
+    const cases: [StockPosition, number, number][] = [
+      ['model_centered', 3, -5],
+      ['offset_from_top', 2, -8],
+      ['offset_from_bottom', 2, -2],
+      ['offset_from_top', -1, -11],
+    ]
+    for (const [position, offset, bottom] of cases) {
+      const cylinder = fixedCylinderStock(part(), { diameter: 50, length: 20 }, position, offset)
+      const box = fixedBoxStockBounds(part(), { x: 50, y: 50, z: 20 }, position, offset)
+      expect(cylinder.origin.z).toBe(bottom)
+      expect(cylinder.origin.z).toBe(box.min.z)
+      expect(cylinder.origin.z + cylinder.length).toBe(box.max.z)
+    }
+  })
+
+  it('rejects sizes and offsets that would build NaN geometry', () => {
+    for (const value of [0, -1, NaN, Infinity]) {
+      expect(() => fixedCylinderStock(part(), { diameter: value, length: 20 })).toThrow(RangeError)
+      expect(() => fixedCylinderStock(part(), { diameter: 20, length: value })).toThrow(RangeError)
+    }
+    expect(() =>
+      fixedCylinderStock(part(), { diameter: 20, length: 20 }, 'offset_from_top', NaN),
+    ).toThrow(RangeError)
+    expect(() => fixedCylinderStock(new BufferGeometry(), { diameter: 20, length: 20 })).toThrow(
+      RangeError,
+    )
+  })
+})
+
+describe('cylinder stock geometry', () => {
+  it('runs from the base centre along the axis, whichever way the axis points', () => {
+    const origin = { x: 4, y: -7, z: 2 }
+    const axes: Vec3[] = [
+      { x: 0, y: 0, z: 1 },
+      { x: 1, y: 0, z: 0 },
+      { x: 0, y: -1, z: 0 },
+      { x: 0, y: 0, z: -1 },
+      { x: 2, y: 2, z: 1 },
+    ]
+    for (const axis of axes) {
+      const geometry = cylinderStockGeometry({ origin, axis, diameter: 30, length: 80 })
+      const { along, radius } = cylinderSpan(geometry, origin, axis)
+      // Positions are float32, so a micron is as close as they can agree.
+      expect(along.min).toBeCloseTo(0, 4)
+      expect(along.max).toBeCloseTo(80, 4)
+      expect(radius).toBeCloseTo(15, 4)
+    }
+  })
+
+  it('lies along X as round stock lying down does', () => {
+    const box = bounds(
+      cylinderStockGeometry({
+        origin: { x: -5, y: 1, z: 2 },
+        axis: { x: 1, y: 0, z: 0 },
+        diameter: 20,
+        length: 60,
+      }),
+    )
+    expect(box.min.x).toBeCloseTo(-5, 9)
+    expect(box.max.x).toBeCloseTo(55, 9)
+    expect(box.min.y).toBeCloseTo(-9, 9)
+    expect(box.max.y).toBeCloseTo(11, 9)
+    expect(box.min.z).toBeCloseTo(-8, 9)
+    expect(box.max.z).toBeCloseTo(12, 9)
+  })
+
+  it('outlines only its two rims', () => {
+    const geometry = cylinderStockGeometry({
+      origin: { x: 0, y: 0, z: 0 },
+      axis: { x: 1, y: 1, z: 0 },
+      diameter: 300,
+      length: 40,
+    })
+    // Two vertices per edge, one edge per side on each of the two rims.
+    expect(new EdgesGeometry(geometry, 15).getAttribute('position').count).toBe(2 * 2 * 64)
+  })
+
+  it('rejects figures that would build NaN geometry', () => {
+    const figure = {
+      origin: { x: 0, y: 0, z: 0 },
+      axis: { x: 0, y: 0, z: 1 },
+      diameter: 10,
+      length: 10,
+    }
+    expect(() => cylinderStockGeometry({ ...figure, axis: { x: 0, y: 0, z: 0 } })).toThrow(
+      RangeError,
+    )
+    expect(() => cylinderStockGeometry({ ...figure, axis: { x: NaN, y: 0, z: 1 } })).toThrow(
+      RangeError,
+    )
+    expect(() => cylinderStockGeometry({ ...figure, origin: { x: Infinity, y: 0, z: 0 } })).toThrow(
+      RangeError,
+    )
+    expect(() => cylinderStockGeometry({ ...figure, diameter: 0 })).toThrow(RangeError)
+    expect(() => cylinderStockGeometry({ ...figure, length: -1 })).toThrow(RangeError)
+  })
+})
+
+describe('oriented box stock geometry', () => {
+  const frame = {
+    location: { x: 5, y: 5, z: 5 },
+    axis: { x: 0, y: 0, z: 1 },
+    refDirection: { x: 1, y: 0, z: 0 },
+  }
+
+  it('places the corners in an unrotated frame at its location', () => {
+    const box = bounds(
+      orientedBoxStockGeometry({
+        frame,
+        lower: { x: -1, y: -2, z: -3 },
+        upper: { x: 10, y: 20, z: 30 },
+      }),
+    )
+    expect(box.min.toArray()).toEqual([4, 3, 2])
+    expect(box.max.toArray()).toEqual([15, 25, 35])
+  })
+
+  it('reads corners along refDirection, axis × refDirection and axis', () => {
+    const box = bounds(
+      orientedBoxStockGeometry({
+        // x runs along part Y, y along part Z (axis × refDirection), z along part X.
+        frame: { ...frame, axis: { x: 1, y: 0, z: 0 }, refDirection: { x: 0, y: 1, z: 0 } },
+        lower: { x: 0, y: 0, z: 0 },
+        upper: { x: 10, y: 20, z: 30 },
+      }),
+    )
+    expect(box.min.toArray()).toEqual([5, 5, 5])
+    expect(box.max.toArray()).toEqual([35, 15, 25])
+  })
+
+  it('rejects degenerate frames and inverted corners', () => {
+    const lower = { x: 0, y: 0, z: 0 }
+    const upper = { x: 1, y: 1, z: 1 }
+    expect(() =>
+      orientedBoxStockGeometry({
+        frame: { ...frame, refDirection: { x: 0, y: 0, z: 2 } },
+        lower,
+        upper,
+      }),
+    ).toThrow(RangeError)
+    expect(() =>
+      orientedBoxStockGeometry({ frame: { ...frame, axis: { x: 0, y: 0, z: 0 } }, lower, upper }),
+    ).toThrow(RangeError)
+    expect(() =>
+      orientedBoxStockGeometry({ frame, lower: upper, upper: { x: 2, y: 1, z: 2 } }),
+    ).toThrow(RangeError)
+    expect(() => orientedBoxStockGeometry({ frame, lower, upper: { x: 1, y: NaN, z: 1 } })).toThrow(
+      RangeError,
+    )
+  })
+})
+
 describe('stock scene integration', () => {
   it('frames stock without changing part-relative bounds or intercepting tool rays', () => {
     const root = new Group()
@@ -96,11 +297,28 @@ describe('stock scene integration', () => {
     stock.dispose()
   })
 
+  it('builds its outline once, and only when it is first shown', () => {
+    const stock = createStock(new BoxGeometry(10, 10, 10))
+    stock.showEdges(false)
+    expect(stock.object.children).toHaveLength(1)
+    stock.showEdges(true)
+    const [, edges] = stock.object.children
+    expect(edges).toBeInstanceOf(LineSegments)
+    stock.showEdges(false)
+    expect(edges!.visible).toBe(false)
+    stock.showEdges(true)
+    expect(stock.object.children).toEqual([stock.object.children[0], edges])
+    expect(edges!.visible).toBe(true)
+    stock.dispose()
+  })
+
   it('disposes owned GPU resources while leaving caller geometry reusable', () => {
     const geometry = new BoxGeometry(10, 10, 10)
     const stock = createStock(geometry)
+    stock.showEdges(true)
     const inputDisposed = vi.spyOn(geometry, 'dispose')
-    const edgesDisposed = vi.spyOn(stock.edges.geometry, 'dispose')
+    const edges = stock.object.children[1] as LineSegments
+    const edgesDisposed = vi.spyOn(edges.geometry, 'dispose')
     const materialDisposed = vi.spyOn(stock.material, 'dispose')
     const edgeMaterialDisposed = vi.spyOn(stock.edgeMaterial, 'dispose')
     stock.dispose()

From 656985eefd0f6fbddfe894d349695a83b4c0e252 Mon Sep 17 00:00:00 2001
From: nathan-vandrei <87823030+dementive@users.noreply.github.com>
Date: Thu, 1 Oct 2026 17:06:44 -0400
Subject: [PATCH 2/5] Stock glbs

---
 .changeset/cylinder-stock.md                 |   2 +-
 examples/react-viewer/src/main.tsx           | 107 ++++++++++++++-----
 examples/react-viewer/tests/toolbar.spec.ts  |  44 ++++++++
 packages/viewer/README.md                    |  29 +++++
 packages/viewer/fixtures/mesh/stock-box.json |   5 +
 packages/viewer/src/index.ts                 |   2 +
 packages/viewer/src/render/stock-mesh.ts     |  39 +++++++
 packages/viewer/src/stock.tsx                |  84 +++++++++++++--
 packages/viewer/tests/stock-mesh.test.ts     |  67 ++++++++++++
 packages/viewer/tests/stock-source.test.ts   |  13 +++
 10 files changed, 351 insertions(+), 41 deletions(-)
 create mode 100644 packages/viewer/fixtures/mesh/stock-box.json
 create mode 100644 packages/viewer/src/render/stock-mesh.ts
 create mode 100644 packages/viewer/tests/stock-mesh.test.ts
 create mode 100644 packages/viewer/tests/stock-source.test.ts

diff --git a/.changeset/cylinder-stock.md b/.changeset/cylinder-stock.md
index 993af04..5179ae3 100644
--- a/.changeset/cylinder-stock.md
+++ b/.changeset/cylinder-stock.md
@@ -2,4 +2,4 @@
 '@toolpath/viewer': minor
 ---
 
-Add `CylinderStock` for round stock along any axis, `fixedCylinderStock` for a fixed-cylinder preview placed by the same position rule as fixed-box stock, and `OrientedBoxStock` for a block squared to a frame of its own, such as a plan's setup-squared stock box. Stock outlines are now built only when shown.
+Add `CylinderStock` for round stock along any axis, `fixedCylinderStock` for a fixed-cylinder preview placed by the same position rule as fixed-box stock, and `OrientedBoxStock` for a block squared to a frame of its own, such as a plan's setup-squared stock box. `Stock` now accepts either caller-owned `geometry` or initial/in-process stock GLB bytes through `glb`, without fetching or caching artifacts. Stock outlines are now built only when shown.
diff --git a/examples/react-viewer/src/main.tsx b/examples/react-viewer/src/main.tsx
index 371318f..60c252a 100644
--- a/examples/react-viewer/src/main.tsx
+++ b/examples/react-viewer/src/main.tsx
@@ -7,6 +7,7 @@ import {
   Banana,
   BoxStock,
   CylinderStock,
+  Stock,
   fixedBoxStockBounds,
   fixedCylinderStock,
   directionHighlights,
@@ -38,6 +39,7 @@ import {
 } from '@toolpath/viewer'
 import { AnalysisOptions } from './analysis-options'
 import { MODELS, modelFromQuery } from './models'
+import stockMeshFixture from '../../../packages/viewer/fixtures/mesh/stock-box.json'
 import './style.css'
 
 /**
@@ -57,6 +59,14 @@ const params = new URLSearchParams(window.location.search)
 const projection: Projection =
   params.get('projection') === 'orthographic' ? 'orthographic' : 'perspective'
 const showOrbitTarget = params.get('orbitTarget') === 'on'
+const STOCK_GLB_BYTES = Uint8Array.from(atob(stockMeshFixture.base64), (char) =>
+  char.charCodeAt(0),
+).buffer
+const LARGE_STOCK_GLB_BYTES = Uint8Array.from(atob(stockMeshFixture.largeBase64), (char) =>
+  char.charCodeAt(0),
+).buffer
+type StockShape = 'box' | 'cylinder'
+type StockSource = 'geometry' | 'glb'
 const requestedControls = params.get('controls')
 const initialControls: ControlScheme = CONTROL_SCHEME_OPTIONS.some(
   (option) => option.value === requestedControls,
@@ -217,11 +227,15 @@ const App = () => {
   const [showDirections, setShowDirections] = useState(false)
   const [focus, setFocus] = useState(false)
   const [wireframe, setWireframe] = useState(false)
-  const [stockShape, setStockShape] = useState<'box' | 'cylinder'>(
+  const [stockShape, setStockShape] = useState<StockShape>(
     params.get('stockShape') === 'cylinder' ? 'cylinder' : 'box',
   )
+  const [stockSource, setStockSource] = useState<StockSource>(
+    params.get('stockSource') === 'glb' ? 'glb' : 'geometry',
+  )
   const [stockDimensions, setStockDimensions] = useState({ x: 25.908, y: 25.908, z: 25.908 })
   const [stockCylinder, setStockCylinder] = useState({ diameter: 38.1, length: 25.908 })
+  const [stockMeshSize, setStockMeshSize] = useState('40')
   const [stockPosition, setStockPosition] = useState<StockPosition>('model_centered')
   const [stockPositionOffset, setStockPositionOffset] = useState(0)
   const stockSize = useMemo(
@@ -356,24 +370,50 @@ const App = () => {
         <p>{part.hint}</p>
         <p>
           <strong>Stock:</strong>{' '}
-          {stockShape === 'cylinder'
-            ? `⌀${cylinderFigure.diameter.toFixed(2)} × ${cylinderFigure.length.toFixed(2)} mm (diameter × length)`
-            : `${stockSize
-                .toArray()
-                .map((value) => value.toFixed(2))
-                .join(' × ')} mm (X × Y × Z)`}
+          {stockSource === 'glb'
+            ? `${stockMeshSize}.00 × ${stockMeshSize}.00 × ${stockMeshSize}.00 mm (services-encoded GLB blank)`
+            : stockShape === 'cylinder'
+              ? `⌀${cylinderFigure.diameter.toFixed(2)} × ${cylinderFigure.length.toFixed(2)} mm (diameter × length)`
+              : `${stockSize
+                  .toArray()
+                  .map((value) => value.toFixed(2))
+                  .join(' × ')} mm (X × Y × Z)`}
         </p>
         <label className="stock-allowance">
-          Stock shape
+          Stock source
           <select
-            value={stockShape}
-            onChange={(event) => setStockShape(event.target.value as 'box' | 'cylinder')}
+            value={stockSource}
+            onChange={(event) => setStockSource(event.target.value as StockSource)}
           >
-            <option value="box">Box</option>
-            <option value="cylinder">Cylinder</option>
+            <option value="geometry">Shape preview</option>
+            <option value="glb">GLB fixture</option>
           </select>
         </label>
-        {stockShape === 'cylinder' ? (
+        {stockSource === 'geometry' ? (
+          <label className="stock-allowance">
+            Stock shape
+            <select
+              value={stockShape}
+              onChange={(event) => setStockShape(event.target.value as StockShape)}
+            >
+              <option value="box">Box</option>
+              <option value="cylinder">Cylinder</option>
+            </select>
+          </label>
+        ) : null}
+        {stockSource === 'glb' ? (
+          <label className="stock-allowance">
+            GLB blank
+            <select
+              value={stockMeshSize}
+              onChange={(event) => setStockMeshSize(event.target.value)}
+            >
+              <option value="40">40 mm box</option>
+              <option value="60">60 mm box</option>
+            </select>
+          </label>
+        ) : null}
+        {stockSource === 'geometry' && stockShape === 'cylinder' ? (
           <>
             <label className="stock-allowance">
               Stock diameter (mm)
@@ -407,7 +447,7 @@ const App = () => {
             </label>
           </>
         ) : null}
-        {stockShape === 'box' ? (
+        {stockSource === 'geometry' && stockShape === 'box' ? (
           <>
             <label className="stock-allowance">
               Stock X dimension (mm)
@@ -456,18 +496,20 @@ const App = () => {
             </label>
           </>
         ) : null}
-        <label className="stock-allowance">
-          Stock position
-          <select
-            value={stockPosition}
-            onChange={(event) => setStockPosition(event.target.value as StockPosition)}
-          >
-            <option value="model_centered">Model centered</option>
-            <option value="offset_from_top">Offset from top</option>
-            <option value="offset_from_bottom">Offset from bottom</option>
-          </select>
-        </label>
-        {stockPosition !== 'model_centered' ? (
+        {stockSource === 'geometry' ? (
+          <label className="stock-allowance">
+            Stock position
+            <select
+              value={stockPosition}
+              onChange={(event) => setStockPosition(event.target.value as StockPosition)}
+            >
+              <option value="model_centered">Model centered</option>
+              <option value="offset_from_top">Offset from top</option>
+              <option value="offset_from_bottom">Offset from bottom</option>
+            </select>
+          </label>
+        ) : null}
+        {stockSource === 'geometry' && stockPosition !== 'model_centered' ? (
           <label className="stock-allowance">
             Position offset (mm)
             <input
@@ -485,7 +527,9 @@ const App = () => {
           </label>
         ) : null}
         <p className="small-note">
-          Fixed stock shape, dimensions and position. Values are millimetres.
+          {stockSource === 'glb'
+            ? 'Synthetic initial stock encoded by the services GLB writer, in part coordinates.'
+            : 'Fixed stock shape, dimensions and position. Values are millimetres.'}
         </p>
         <button
           className="detail-button"
@@ -664,8 +708,13 @@ const App = () => {
               }}
               onPick={(pick: PartPick) => setSelected([...pick.ranked])}
             />
-            {showStock && stockShape === 'cylinder' ? <CylinderStock {...cylinderFigure} /> : null}
-            {showStock && stockShape === 'box' ? (
+            {showStock && stockSource === 'geometry' && stockShape === 'cylinder' ? (
+              <CylinderStock {...cylinderFigure} />
+            ) : null}
+            {showStock && stockSource === 'glb' ? (
+              <Stock glb={stockMeshSize === '40' ? STOCK_GLB_BYTES : LARGE_STOCK_GLB_BYTES} />
+            ) : null}
+            {showStock && stockSource === 'geometry' && stockShape === 'box' ? (
               <BoxStock
                 partGeometry={part.geometry}
                 dimensions={stockDimensions}
diff --git a/examples/react-viewer/tests/toolbar.spec.ts b/examples/react-viewer/tests/toolbar.spec.ts
index 3f4f02c..83c1dca 100644
--- a/examples/react-viewer/tests/toolbar.spec.ts
+++ b/examples/react-viewer/tests/toolbar.spec.ts
@@ -179,6 +179,50 @@ for (const projection of ['perspective', 'orthographic'] as const) {
       .toBeGreaterThan(before.distance)
   })
 
+  test(`GLB stock loads, remounts and fits without intercepting picks (${projection})`, async ({
+    page,
+  }) => {
+    const errors: string[] = []
+    page.on('pageerror', (error) => errors.push(error.message))
+    page.on('console', (message) => {
+      if (message.type() === 'error') errors.push(message.text())
+    })
+    const { canvas, box } = await openViewer(page, `projection=${projection}&stockSource=glb`)
+    await expect(page.getByRole('combobox', { name: 'Stock source' })).toHaveValue('glb')
+    await expect(page.getByRole('combobox', { name: 'Stock shape' })).toHaveCount(0)
+    const before = await readCamera(page)
+    const withoutStock = await canvas.screenshot()
+    await page.getByRole('button', { name: 'Show stock', exact: true }).click()
+    await expect
+      .poll(async () => Buffer.compare(withoutStock, await canvas.screenshot()))
+      .not.toBe(0)
+    expect((await readCamera(page)).distance).toBeCloseTo(before.distance, 5)
+    await canvas.click({ position: on(box, { x: 0.5, y: 0.5 }) })
+    await expect(page.locator('p', { hasText: 'Selected:' })).toContainText(
+      projection === 'perspective' ? 'back-face' : 'front-face',
+    )
+    await page.getByRole('button', { name: 'Fit', exact: true }).click()
+    await expect
+      .poll(async () => (await readCamera(page)).distance)
+      .toBeGreaterThan(before.distance)
+
+    const smallDistance = (await readCamera(page)).distance
+    const smallStock = await canvas.screenshot()
+    await page.getByRole('combobox', { name: 'GLB blank' }).selectOption('60')
+    await expect.poll(async () => Buffer.compare(smallStock, await canvas.screenshot())).not.toBe(0)
+    await page.getByRole('button', { name: 'Fit', exact: true }).click()
+    await expect.poll(async () => (await readCamera(page)).distance).toBeGreaterThan(smallDistance)
+
+    // Stock cleans up decoded geometry; the caller's bytes remain reusable on remount.
+    await page.getByRole('button', { name: 'Hide stock', exact: true }).click()
+    await page.getByRole('button', { name: 'Reset', exact: true }).click()
+    await expect.poll(async () => (await readCamera(page)).distance).toBeCloseTo(before.distance, 5)
+    const hidden = await canvas.screenshot()
+    await page.getByRole('button', { name: 'Show stock', exact: true }).click()
+    await expect.poll(async () => Buffer.compare(hidden, await canvas.screenshot())).not.toBe(0)
+    expect(errors).toEqual([])
+  })
+
   test(`stock present on mount does not move the section midpoint (${projection})`, async ({
     page,
   }) => {
diff --git a/packages/viewer/README.md b/packages/viewer/README.md
index 6525bda..98186c8 100644
--- a/packages/viewer/README.md
+++ b/packages/viewer/README.md
@@ -251,6 +251,35 @@ a figure read off a fresh API response does not rebuild the same stock. Figures
 solid — a zero axis, a non-positive size, a frame whose axis and reference direction are parallel —
 throw `RangeError`.
 
+`Stock` accepts exactly one source: caller-owned `BufferGeometry`, or initial-stock/in-process-stock
+GLB bytes as an `ArrayBuffer`:
+
+```tsx
+<Stock geometry={geometry} showEdges={false} />
+// Or:
+<Stock glb={glbBytes} showEdges={false} />
+```
+
+`geometry` and `glb` are mutually exclusive in `StockProps`. With `geometry`, the caller owns its
+lifetime and disposal. 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`, `opacity` (default `0.2`), `edgeColor`, `edgeOpacity`, and `showEdges`.
 The outline is built the first time it is shown, so a large stock mesh with `showEdges={false}`
 costs no edge pass. `BoxStock`, `CylinderStock` and `OrientedBoxStock` accept the same appearance
diff --git a/packages/viewer/fixtures/mesh/stock-box.json b/packages/viewer/fixtures/mesh/stock-box.json
new file mode 100644
index 0000000..e3b6660
--- /dev/null
+++ b/packages/viewer/fixtures/mesh/stock-box.json
@@ -0,0 +1,5 @@
+{
+  "description": "Synthetic 40 mm and 60 mm initial-stock boxes centered on the origin. Encoded with services/apps/engine-worker/src/lib/mesh.ts meshToGlb on 2026-10-01; the same POSITION-only indexed GLB writer used by stock artifacts. Not captured kernel calculations. Base64 stores the exact GLB bytes for unit tests and the browser example.",
+  "largeBase64": "Z2xURgIAAAAkAwAAGAIAAEpTT057ImFzc2V0Ijp7InZlcnNpb24iOiIyLjAiLCJnZW5lcmF0b3IiOiJlbmdpbmUtd29ya2VyIn0sImJ1ZmZlcnMiOlt7ImJ5dGVMZW5ndGgiOjI0MH1dLCJidWZmZXJWaWV3cyI6W3siYnVmZmVyIjowLCJieXRlT2Zmc2V0IjowLCJieXRlTGVuZ3RoIjo5NiwidGFyZ2V0IjozNDk2Mn0seyJidWZmZXIiOjAsImJ5dGVPZmZzZXQiOjk2LCJieXRlTGVuZ3RoIjoxNDQsInRhcmdldCI6MzQ5NjN9XSwiYWNjZXNzb3JzIjpbeyJidWZmZXJWaWV3IjowLCJjb21wb25lbnRUeXBlIjo1MTI2LCJjb3VudCI6OCwidHlwZSI6IlZFQzMiLCJtaW4iOlstMzAsLTMwLC0zMF0sIm1heCI6WzMwLDMwLDMwXX0seyJidWZmZXJWaWV3IjoxLCJjb21wb25lbnRUeXBlIjo1MTI1LCJjb3VudCI6MzYsInR5cGUiOiJTQ0FMQVIifV0sIm1lc2hlcyI6W3sicHJpbWl0aXZlcyI6W3siYXR0cmlidXRlcyI6eyJQT1NJVElPTiI6MH0sImluZGljZXMiOjEsIm1vZGUiOjR9XX1dLCJub2RlcyI6W3sibWVzaCI6MH1dLCJzY2VuZXMiOlt7Im5vZGVzIjpbMF19XSwic2NlbmUiOjB9IPAAAABCSU4AAADwwQAA8MEAAPDBAADwQQAA8MEAAPDBAADwQQAA8EEAAPDBAADwwQAA8EEAAPDBAADwwQAA8MEAAPBBAADwQQAA8MEAAPBBAADwQQAA8EEAAPBBAADwwQAA8EEAAPBBAAAAAAIAAAABAAAAAAAAAAMAAAACAAAABAAAAAUAAAAGAAAABAAAAAYAAAAHAAAAAAAAAAEAAAAFAAAAAAAAAAUAAAAEAAAAAQAAAAIAAAAGAAAAAQAAAAYAAAAFAAAAAgAAAAMAAAAHAAAAAgAAAAcAAAAGAAAAAwAAAAAAAAAEAAAAAwAAAAQAAAAHAAAA",
+  "base64": "Z2xURgIAAAAkAwAAGAIAAEpTT057ImFzc2V0Ijp7InZlcnNpb24iOiIyLjAiLCJnZW5lcmF0b3IiOiJlbmdpbmUtd29ya2VyIn0sImJ1ZmZlcnMiOlt7ImJ5dGVMZW5ndGgiOjI0MH1dLCJidWZmZXJWaWV3cyI6W3siYnVmZmVyIjowLCJieXRlT2Zmc2V0IjowLCJieXRlTGVuZ3RoIjo5NiwidGFyZ2V0IjozNDk2Mn0seyJidWZmZXIiOjAsImJ5dGVPZmZzZXQiOjk2LCJieXRlTGVuZ3RoIjoxNDQsInRhcmdldCI6MzQ5NjN9XSwiYWNjZXNzb3JzIjpbeyJidWZmZXJWaWV3IjowLCJjb21wb25lbnRUeXBlIjo1MTI2LCJjb3VudCI6OCwidHlwZSI6IlZFQzMiLCJtaW4iOlstMjAsLTIwLC0yMF0sIm1heCI6WzIwLDIwLDIwXX0seyJidWZmZXJWaWV3IjoxLCJjb21wb25lbnRUeXBlIjo1MTI1LCJjb3VudCI6MzYsInR5cGUiOiJTQ0FMQVIifV0sIm1lc2hlcyI6W3sicHJpbWl0aXZlcyI6W3siYXR0cmlidXRlcyI6eyJQT1NJVElPTiI6MH0sImluZGljZXMiOjEsIm1vZGUiOjR9XX1dLCJub2RlcyI6W3sibWVzaCI6MH1dLCJzY2VuZXMiOlt7Im5vZGVzIjpbMF19XSwic2NlbmUiOjB9IPAAAABCSU4AAACgwQAAoMEAAKDBAACgQQAAoMEAAKDBAACgQQAAoEEAAKDBAACgwQAAoEEAAKDBAACgwQAAoMEAAKBBAACgQQAAoMEAAKBBAACgQQAAoEEAAKBBAACgwQAAoEEAAKBBAAAAAAIAAAABAAAAAAAAAAMAAAACAAAABAAAAAUAAAAGAAAABAAAAAYAAAAHAAAAAAAAAAEAAAAFAAAAAAAAAAUAAAAEAAAAAQAAAAIAAAAGAAAAAQAAAAYAAAAFAAAAAgAAAAMAAAAHAAAAAgAAAAcAAAAGAAAAAwAAAAAAAAAEAAAAAwAAAAQAAAAHAAAA"
+}
diff --git a/packages/viewer/src/index.ts b/packages/viewer/src/index.ts
index fe3b224..86bb958 100644
--- a/packages/viewer/src/index.ts
+++ b/packages/viewer/src/index.ts
@@ -16,6 +16,8 @@ export type {
 export { Stock, BoxStock, CylinderStock, OrientedBoxStock } from './stock.js'
 export type {
   StockProps,
+  StockSource,
+  StockAppearanceProps,
   BoxStockProps,
   CylinderStockProps,
   OrientedBoxStockProps,
diff --git a/packages/viewer/src/render/stock-mesh.ts b/packages/viewer/src/render/stock-mesh.ts
new file mode 100644
index 0000000..0ce3c45
--- /dev/null
+++ b/packages/viewer/src/render/stock-mesh.ts
@@ -0,0 +1,39 @@
+import { type BufferGeometry, Mesh, type Object3D } from 'three'
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
+
+/**
+ * Decode caller-provided GLB bytes into stock geometry in part coordinates.
+ * Internal to Stock: no fetching or caching. Stock owns the returned geometry
+ * and disposes it when its input changes or it unmounts.
+ */
+export async function parseStockGlb(data: ArrayBuffer): Promise<BufferGeometry[]> {
+  const { scene } = await new GLTFLoader().parseAsync(data, '')
+  try {
+    return stockMeshGeometries(scene)
+  } finally {
+    // This scene is private to the parser, not a shared loader-cache resource.
+    scene.traverse((object) => {
+      if (!(object instanceof Mesh)) return
+      object.geometry.dispose()
+      for (const material of Array.isArray(object.material) ? object.material : [object.material]) {
+        material.dispose()
+      }
+    })
+  }
+}
+
+/** Prepare owned stock geometry without changing the loader's shared scene. */
+export function stockMeshGeometries(scene: Object3D): BufferGeometry[] {
+  const geometries: BufferGeometry[] = []
+  scene.updateWorldMatrix(true, true)
+  scene.traverse((object) => {
+    if (!(object instanceof Mesh)) return
+    const geometry = object.geometry.clone().applyMatrix4(object.matrixWorld)
+    // Engine stock GLBs contain indexed positions and no normals. They need
+    // lighting, but not the part report's per-region attributes or de-indexing.
+    if (!geometry.hasAttribute('normal')) geometry.computeVertexNormals()
+    geometries.push(geometry)
+  })
+  if (geometries.length === 0) throw new Error('The stock GLB contains no mesh.')
+  return geometries
+}
diff --git a/packages/viewer/src/stock.tsx b/packages/viewer/src/stock.tsx
index bfbaf6c..2b057b2 100644
--- a/packages/viewer/src/stock.tsx
+++ b/packages/viewer/src/stock.tsx
@@ -1,7 +1,8 @@
 import { useThree } from '@react-three/fiber'
-import { useEffect, useLayoutEffect, useMemo } from 'react'
+import { useEffect, useLayoutEffect, useMemo, useState } from 'react'
 import { type BufferGeometry, BoxGeometry, Vector3 } from 'three'
 import type { Vec3 } from './model/types.js'
+import { parseStockGlb } from './render/stock-mesh.js'
 import {
   boxStockBounds,
   createStock,
@@ -14,9 +15,7 @@ import {
   type StockPosition,
 } from './render/stock.js'
 
-export interface StockProps {
-  /** Caller-owned stock mesh in the same millimetre, Z-up coordinates as the part. */
-  geometry: BufferGeometry
+export interface StockAppearanceProps {
   color?: number
   opacity?: number
   edgeColor?: number
@@ -24,15 +23,38 @@ export interface StockProps {
   showEdges?: boolean
 }
 
+/** Exactly one source, in the same millimetre, Z-up coordinates as the part. */
+export type StockSource =
+  | {
+      /** Caller-owned geometry; Stock never disposes it. */
+      geometry: BufferGeometry
+      glb?: never
+    }
+  | {
+      /** Caller-provided GLB bytes; Stock owns and cleans up the decoded geometry. */
+      glb: ArrayBuffer
+      geometry?: never
+    }
+
+export type StockProps = StockAppearanceProps & StockSource
+
 /** Translucent stock, included in Fit but ignored by picking, sections and measurements. */
-export const Stock = ({
+export const Stock = ({ geometry, glb, ...appearance }: StockProps) =>
+  geometry ? (
+    <GeometryStock geometry={geometry} {...appearance} />
+  ) : (
+    <GlbStock glb={glb!} {...appearance} />
+  )
+
+/** One renderer for caller-owned geometry and internally decoded GLB meshes. */
+const GeometryStock = ({
   geometry,
   color = 0xb9cbe2,
   opacity = 0.2,
   edgeColor = 0xa8bdd8,
   edgeOpacity = 0.75,
   showEdges = true,
-}: StockProps) => {
+}: StockAppearanceProps & { geometry: BufferGeometry }) => {
   const invalidate = useThree((state) => state.invalidate)
   const stock = useMemo(() => createStock(geometry), [geometry])
   useEffect(() => () => stock.dispose(), [stock])
@@ -47,7 +69,49 @@ export const Stock = ({
   return <primitive object={stock.object} dispose={null} />
 }
 
-export interface BoxStockProps extends Omit<StockProps, 'geometry'> {
+const GlbStock = ({ glb, ...appearance }: StockAppearanceProps & { glb: ArrayBuffer }) => {
+  const [decoded, setDecoded] = useState<{
+    source: ArrayBuffer
+    geometries?: BufferGeometry[]
+    error?: Error
+  } | null>(null)
+
+  useEffect(() => {
+    let active = true
+    let owned: BufferGeometry[] = []
+    parseStockGlb(glb).then(
+      (geometries) => {
+        if (!active) {
+          geometries.forEach((geometry) => geometry.dispose())
+          return
+        }
+        owned = geometries
+        setDecoded({ source: glb, geometries })
+      },
+      (cause: unknown) => {
+        if (active) {
+          setDecoded({
+            source: glb,
+            error: cause instanceof Error ? cause : new Error(String(cause)),
+          })
+        }
+      },
+    )
+    return () => {
+      active = false
+      owned.forEach((geometry) => geometry.dispose())
+    }
+  }, [glb])
+
+  // A changed source must not display the preceding action while it decodes.
+  if (decoded?.source !== glb) return null
+  if (decoded.error) throw decoded.error
+  return decoded.geometries?.map((geometry) => (
+    <GeometryStock key={geometry.uuid} geometry={geometry} {...appearance} />
+  ))
+}
+
+export interface BoxStockProps extends StockAppearanceProps {
   partGeometry: BufferGeometry
   /** Explicit X/Y/Z dimensions, in millimetres, for fixed-box stock. */
   dimensions?: Vec3
@@ -94,7 +158,7 @@ export const BoxStock = ({
   return <Stock geometry={geometry} {...props} />
 }
 
-export interface CylinderStockProps extends Omit<StockProps, 'geometry'>, CylinderStockFigure {}
+export interface CylinderStockProps extends StockAppearanceProps, CylinderStockFigure {}
 
 /**
  * Round stock along any axis, from its base centre, axis, diameter and length
@@ -114,9 +178,7 @@ export const CylinderStock = ({ origin, axis, diameter, length, ...props }: Cyli
   return <Stock geometry={geometry} {...props} />
 }
 
-export interface OrientedBoxStockProps
-  extends Omit<StockProps, 'geometry'>,
-    OrientedBoxStockFigure {}
+export interface OrientedBoxStockProps extends StockAppearanceProps, OrientedBoxStockFigure {}
 
 /**
  * A block squared to its own frame rather than to the part, such as a planned
diff --git a/packages/viewer/tests/stock-mesh.test.ts b/packages/viewer/tests/stock-mesh.test.ts
new file mode 100644
index 0000000..a7c29bd
--- /dev/null
+++ b/packages/viewer/tests/stock-mesh.test.ts
@@ -0,0 +1,67 @@
+import { BoxGeometry, Group, Mesh, MeshBasicMaterial, Vector3 } from 'three'
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
+import { describe, expect, it, vi } from 'vitest'
+import fixture from '../fixtures/mesh/stock-box.json'
+import { parseStockGlb, stockMeshGeometries } from '../src/render/stock-mesh.js'
+
+describe('GLB stock geometry', () => {
+  it('loads the services encoder output in millimetres without a report or decoder', async () => {
+    const bytes = Uint8Array.from(Buffer.from(fixture.base64, 'base64'))
+    const { scene } = await new GLTFLoader().parseAsync(bytes.buffer, '')
+    const source = scene.children[0] as Mesh
+    expect(source.geometry.hasAttribute('normal')).toBe(false)
+
+    const [geometry] = await parseStockGlb(bytes.buffer)
+    expect(geometry!.index?.count).toBe(36)
+    expect(geometry!.getAttribute('position').count).toBe(8)
+    expect(geometry!.hasAttribute('normal')).toBe(true)
+    geometry!.computeBoundingBox()
+    expect(geometry!.boundingBox!.min.toArray()).toEqual([-20, -20, -20])
+    expect(geometry!.boundingBox!.max.toArray()).toEqual([20, 20, 20])
+    expect(source.geometry.hasAttribute('normal')).toBe(false)
+    geometry!.dispose()
+  })
+
+  it('applies nested transforms to every mesh without changing shared source geometry', () => {
+    const source = new BoxGeometry(10, 20, 30)
+    const material = new MeshBasicMaterial()
+    const scene = new Group()
+    scene.position.set(5, 7, 9)
+    const nested = new Group()
+    nested.rotation.z = Math.PI / 2
+    const first = new Mesh(source, material)
+    first.position.x = 20
+    nested.add(first)
+    const second = new Mesh(source, material)
+    second.position.z = 50
+    scene.add(nested, second)
+    const original = source.getAttribute('position').array.slice()
+    const sourceDisposed = vi.spyOn(source, 'dispose')
+    const materialDisposed = vi.spyOn(material, 'dispose')
+
+    const geometries = stockMeshGeometries(scene)
+    const centers = geometries.map((geometry) => {
+      geometry.computeBoundingBox()
+      return geometry.boundingBox!.getCenter(new Vector3()).toArray()
+    })
+    expect(centers).toEqual([
+      [5, 27, 9],
+      [5, 7, 59],
+    ])
+    expect(geometries[0]!.boundingBox!.getSize(new Vector3()).toArray()).toEqual([20, 10, 30])
+    geometries.forEach((geometry) => geometry.dispose())
+    expect(source.getAttribute('position').array).toEqual(original)
+    expect(sourceDisposed).not.toHaveBeenCalled()
+    expect(materialDisposed).not.toHaveBeenCalled()
+    source.dispose()
+    material.dispose()
+  })
+
+  it('rejects a GLB scene without stock geometry', () => {
+    expect(() => stockMeshGeometries(new Group())).toThrow('The stock GLB contains no mesh.')
+  })
+
+  it('rejects unreadable GLB bytes', async () => {
+    await expect(parseStockGlb(new ArrayBuffer(12))).rejects.toThrow()
+  })
+})
diff --git a/packages/viewer/tests/stock-source.test.ts b/packages/viewer/tests/stock-source.test.ts
new file mode 100644
index 0000000..b7eca53
--- /dev/null
+++ b/packages/viewer/tests/stock-source.test.ts
@@ -0,0 +1,13 @@
+import { BufferGeometry } from 'three'
+import { expectTypeOf, it } from 'vitest'
+import type { BoxStockProps, StockProps } from '../src/stock.js'
+
+it('accepts one geometry or GLB source, with shared appearance props', () => {
+  expectTypeOf({ geometry: new BufferGeometry(), opacity: 0.3 }).toExtend<StockProps>()
+  expectTypeOf({ glb: new ArrayBuffer(0), showEdges: false }).toExtend<StockProps>()
+  // @ts-expect-error Exactly one source is required.
+  expectTypeOf({ geometry: new BufferGeometry(), glb: new ArrayBuffer(0) }).toExtend<StockProps>()
+  // @ts-expect-error A source cannot be omitted.
+  expectTypeOf({ opacity: 0.3 }).toExtend<StockProps>()
+  expectTypeOf<BoxStockProps>().not.toHaveProperty('glb')
+})

From ac7f9862069f31b3d448756f1148d576249c5162 Mon Sep 17 00:00:00 2001
From: nathan-vandrei <87823030+dementive@users.noreply.github.com>
Date: Thu, 1 Oct 2026 17:30:35 -0400
Subject: [PATCH 3/5] Improve stock API

---
 .changeset/cylinder-stock.md               |   6 +-
 examples/react-viewer/src/main.tsx         |  30 ++--
 packages/viewer/README.md                  |  63 ++++----
 packages/viewer/src/index.ts               |  19 +--
 packages/viewer/src/render/stock.ts        |  74 ++++++++-
 packages/viewer/src/stock.tsx              | 168 ++++++++-------------
 packages/viewer/tests/stock-source.test.ts |  51 ++++++-
 packages/viewer/tests/stock.test.ts        |  81 +++++++---
 8 files changed, 310 insertions(+), 182 deletions(-)

diff --git a/.changeset/cylinder-stock.md b/.changeset/cylinder-stock.md
index 5179ae3..78949ae 100644
--- a/.changeset/cylinder-stock.md
+++ b/.changeset/cylinder-stock.md
@@ -1,5 +1,7 @@
 ---
-'@toolpath/viewer': minor
+'@toolpath/viewer': major
 ---
 
-Add `CylinderStock` for round stock along any axis, `fixedCylinderStock` for a fixed-cylinder preview placed by the same position rule as fixed-box stock, and `OrientedBoxStock` for a block squared to a frame of its own, such as a plan's setup-squared stock box. `Stock` now accepts either caller-owned `geometry` or initial/in-process stock GLB bytes through `glb`, without fetching or caching artifacts. Stock outlines are now built only when shown.
+Consolidate stock rendering into `Stock`, accepting exactly one of `geometry`, `glb`, `box`, or `cylinder`. Box and cylinder inputs accept either resolved placement or part-relative preview options, with placement calculated internally. Resolved box figures support optional setup frames; resolved cylinder figures support arbitrary axes. Fetching, caching and artifact storage remain caller-owned. Stock outlines are built only when shown.
+
+Remove `BoxStock` and `BoxStockProps`. Replace `<BoxStock partGeometry={geometry} allowance={allowance} />` with `<Stock box={{ partGeometry: geometry, allowance }} />`; for explicit dimensions use `<Stock box={{ partGeometry: geometry, dimensions, position, positionOffset, offset }} />`. Preview builders are internal, and inline options do not cause repeated part scans on ordinary renders. Existing `<Stock geometry={geometry} />` usage is unchanged.
diff --git a/examples/react-viewer/src/main.tsx b/examples/react-viewer/src/main.tsx
index 60c252a..f87a20d 100644
--- a/examples/react-viewer/src/main.tsx
+++ b/examples/react-viewer/src/main.tsx
@@ -5,11 +5,8 @@ import * as THREE from 'three'
 import {
   Axes,
   Banana,
-  BoxStock,
-  CylinderStock,
   Stock,
   fixedBoxStockBounds,
-  fixedCylinderStock,
   directionHighlights,
   directionLabel,
   directionColor,
@@ -248,10 +245,6 @@ const App = () => {
       ).getSize(new THREE.Vector3()),
     [part.geometry, stockDimensions, stockPosition, stockPositionOffset],
   )
-  const cylinderFigure = useMemo(
-    () => fixedCylinderStock(part.geometry, stockCylinder, stockPosition, stockPositionOffset),
-    [part.geometry, stockCylinder, stockPosition, stockPositionOffset],
-  )
   const highlights = useMemo(
     () => (showDirections ? directionHighlights(part.model, direction) : []),
     [direction, part.model, showDirections],
@@ -373,7 +366,7 @@ const App = () => {
           {stockSource === 'glb'
             ? `${stockMeshSize}.00 × ${stockMeshSize}.00 × ${stockMeshSize}.00 mm (services-encoded GLB blank)`
             : stockShape === 'cylinder'
-              ? `⌀${cylinderFigure.diameter.toFixed(2)} × ${cylinderFigure.length.toFixed(2)} mm (diameter × length)`
+              ? `⌀${stockCylinder.diameter.toFixed(2)} × ${stockCylinder.length.toFixed(2)} mm (diameter × length)`
               : `${stockSize
                   .toArray()
                   .map((value) => value.toFixed(2))
@@ -709,17 +702,26 @@ const App = () => {
               onPick={(pick: PartPick) => setSelected([...pick.ranked])}
             />
             {showStock && stockSource === 'geometry' && stockShape === 'cylinder' ? (
-              <CylinderStock {...cylinderFigure} />
+              <Stock
+                cylinder={{
+                  partGeometry: part.geometry,
+                  ...stockCylinder,
+                  position: stockPosition,
+                  positionOffset: stockPositionOffset,
+                }}
+              />
             ) : null}
             {showStock && stockSource === 'glb' ? (
               <Stock glb={stockMeshSize === '40' ? STOCK_GLB_BYTES : LARGE_STOCK_GLB_BYTES} />
             ) : null}
             {showStock && stockSource === 'geometry' && stockShape === 'box' ? (
-              <BoxStock
-                partGeometry={part.geometry}
-                dimensions={stockDimensions}
-                position={stockPosition}
-                positionOffset={stockPositionOffset}
+              <Stock
+                box={{
+                  partGeometry: part.geometry,
+                  dimensions: stockDimensions,
+                  position: stockPosition,
+                  positionOffset: stockPositionOffset,
+                }}
               />
             ) : null}
             <DirectionArrows
diff --git a/packages/viewer/README.md b/packages/viewer/README.md
index 98186c8..bb14693 100644
--- a/packages/viewer/README.md
+++ b/packages/viewer/README.md
@@ -76,8 +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> <CylinderStock> <OrientedBoxStock>
- │                        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
@@ -147,11 +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, `<CylinderStock>` for round stock,
-`<OrientedBoxStock>` for a block squared to a frame of its own, or
-`<Stock geometry={stockGeometry} />` for an actual stock mesh, such as irregular or in-process
-stock. 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.
 
@@ -159,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,
@@ -190,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}
@@ -217,51 +213,60 @@ 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.
 
-`<CylinderStock origin={…} axis={…} diameter={…} length={…} />` draws round stock along any axis:
+`<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. `fixedCylinderStock(geometry, { diameter, length }, position, positionOffset)` returns
-that figure for a fixed-cylinder preview, standing along the part's Z, centred on the part's
-bounding box, and placed along Z by the same `position` rule as fixed-box stock — so
-`<CylinderStock {...fixedCylinderStock(geometry, size)} />` previews it. Memoise the figure: it reads
-every vertex of the part. It is a preview; the kernel centres fixed round stock on the part's
+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.
 
-`<OrientedBoxStock frame={…} lower={…} upper={…} />` draws a block whose corners are given in a frame
+`<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`. That is the shape of an Engine plan's
-`stock` box, which is squared to the setup rather than to the part.
+`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.
 
-`CylinderStock` and `OrientedBoxStock` rebuild their mesh only when the figure's numbers change, so
-a figure read off a fresh API response does not rebuild the same stock. Figures that cannot make a
+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 source: caller-owned `BufferGeometry`, or initial-stock/in-process-stock
-GLB bytes as an `ArrayBuffer`:
+`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 }} />
 ```
 
-`geometry` and `glb` are mutually exclusive in `StockProps`. With `geometry`, the caller owns its
-lifetime and disposal. With `glb`, `Stock` decodes the bytes internally and disposes decoded
+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.
@@ -282,11 +287,15 @@ writer. **Shape preview** exposes the separate box/cylinder shape controls.
 
 `Stock` accepts `color`, `opacity` (default `0.2`), `edgeColor`, `edgeOpacity`, and `showEdges`.
 The outline is built the first time it is shown, so a large stock mesh with `showEdges={false}`
-costs no edge pass. `BoxStock`, `CylinderStock` and `OrientedBoxStock` accept the same appearance
-props. Caller-provided geometry is never disposed; the
+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.
+
 `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
diff --git a/packages/viewer/src/index.ts b/packages/viewer/src/index.ts
index 86bb958..f6301ba 100644
--- a/packages/viewer/src/index.ts
+++ b/packages/viewer/src/index.ts
@@ -13,20 +13,17 @@ export type {
   ViewerToolbarControlsProps,
   ViewerToolbarProps,
 } from './viewer-toolbar.js'
-export { Stock, BoxStock, CylinderStock, OrientedBoxStock } from './stock.js'
-export type {
-  StockProps,
-  StockSource,
-  StockAppearanceProps,
-  BoxStockProps,
-  CylinderStockProps,
-  OrientedBoxStockProps,
-} from './stock.js'
+export { Stock } from './stock.js'
+export type { StockProps, StockSource, StockAppearanceProps } from './stock.js'
 export { Banana, BANANA_MODEL_URL } from './banana.js'
-export { boxStockBounds, fixedBoxStockBounds, fixedCylinderStock } from './render/stock.js'
+export { boxStockBounds, fixedBoxStockBounds } from './render/stock.js'
 export type {
   CylinderStockFigure,
-  OrientedBoxStockFigure,
+  BoxStockFigure,
+  BoxStockInput,
+  BoxStockPreview,
+  CylinderStockInput,
+  CylinderStockPreview,
   StockAllowance,
   StockPosition,
 } from './render/stock.js'
diff --git a/packages/viewer/src/render/stock.ts b/packages/viewer/src/render/stock.ts
index 3c4db0f..2e8d473 100644
--- a/packages/viewer/src/render/stock.ts
+++ b/packages/viewer/src/render/stock.ts
@@ -47,12 +47,48 @@ export interface CylinderStockFigure {
  * in part coordinates. This is the shape of the Engine's plan `StockBox`, which
  * is squared to the setup.
  */
-export interface OrientedBoxStockFigure {
-  frame: { location: Vec3; axis: Vec3; refDirection: Vec3 }
+export interface BoxStockFigure {
+  /** Omit for a box whose corners are already in part coordinates. */
+  frame?: { location: Vec3; axis: Vec3; refDirection: Vec3 }
   lower: Vec3
   upper: Vec3
 }
 
+/** Box preview around the part: explicit dimensions or per-side allowance. */
+export type BoxStockPreview = {
+  partGeometry: BufferGeometry
+  offset?: Vec3
+} & (
+  | { dimensions: Vec3; position?: StockPosition; positionOffset?: number; allowance?: never }
+  | { allowance?: StockAllowance; dimensions?: never; position?: never; positionOffset?: never }
+)
+
+/** Resolved corners or part-relative preview options, never both. */
+export type BoxStockInput =
+  | (BoxStockFigure & { partGeometry?: never })
+  | (BoxStockPreview & { lower?: never; upper?: never; frame?: never })
+
+/** Upright cylinder preview centered on the part's bounding box. */
+export interface CylinderStockPreview {
+  partGeometry: BufferGeometry
+  diameter: number
+  length: number
+  position?: StockPosition
+  positionOffset?: number
+}
+
+/** Resolved cylinder placement or part-relative preview options, never both. */
+export type CylinderStockInput =
+  | (CylinderStockFigure & { partGeometry?: never; position?: never; positionOffset?: never })
+  | (CylinderStockPreview & { origin?: never; axis?: never })
+
+function boxFigure(bounds: Box3): BoxStockFigure {
+  return {
+    lower: { x: bounds.min.x, y: bounds.min.y, z: bounds.min.z },
+    upper: { x: bounds.max.x, y: bounds.max.y, z: bounds.max.z },
+  }
+}
+
 /**
  * Sides on a cylinder's rings. Adjacent sides meet at under 6°, well inside the
  * outline's 15° crease, so the outline draws the two rims and no facet lines.
@@ -105,7 +141,7 @@ export function fixedBoxStockBounds(
  * smallest enclosing circle, which the bounding-box centre only approximates.
  * Once a job is planned, render the stock it resolved instead.
  */
-export function fixedCylinderStock(
+function fixedCylinderStock(
   geometry: BufferGeometry,
   size: { diameter: number; length: number },
   position: StockPosition = 'model_centered',
@@ -150,7 +186,10 @@ function fixedStockLowerZ(
 }
 
 /** A closed cylinder for `figure`, in part coordinates. */
-export function cylinderStockGeometry(figure: CylinderStockFigure): BufferGeometry {
+export function cylinderStockGeometry(input: CylinderStockInput): BufferGeometry {
+  const figure: CylinderStockFigure = input.partGeometry
+    ? fixedCylinderStock(input.partGeometry, input, input.position, input.positionOffset)
+    : input
   const { origin, diameter, length } = figure
   if (![origin.x, origin.y, origin.z].every(Number.isFinite)) {
     throw new RangeError('Cylinder stock origin must be finite.')
@@ -173,9 +212,32 @@ export function cylinderStockGeometry(figure: CylinderStockFigure): BufferGeomet
     .translate(center.x, center.y, center.z)
 }
 
+/** Resolve preview options when supplied, then build a box in part coordinates. */
+export function boxStockGeometry(input: BoxStockInput): BufferGeometry {
+  const figure: BoxStockFigure = input.partGeometry
+    ? boxFigure(
+        input.dimensions
+          ? fixedBoxStockBounds(
+              input.partGeometry,
+              input.dimensions,
+              input.position,
+              input.positionOffset,
+              input.offset,
+            )
+          : boxStockBounds(input.partGeometry, input.allowance, input.offset),
+      )
+    : input
+  return orientedBoxStockGeometry(figure)
+}
+
 /** A closed block for `figure`, in part coordinates. */
-export function orientedBoxStockGeometry(figure: OrientedBoxStockFigure): BufferGeometry {
-  const { frame, lower, upper } = figure
+export function orientedBoxStockGeometry(figure: BoxStockFigure): BufferGeometry {
+  const { lower, upper } = figure
+  const frame = figure.frame ?? {
+    location: { x: 0, y: 0, z: 0 },
+    axis: { x: 0, y: 0, z: 1 },
+    refDirection: { x: 1, y: 0, z: 0 },
+  }
   const { location, axis, refDirection } = frame
   if (
     ![location, axis, refDirection, lower, upper].every((vector) =>
diff --git a/packages/viewer/src/stock.tsx b/packages/viewer/src/stock.tsx
index 2b057b2..57b1747 100644
--- a/packages/viewer/src/stock.tsx
+++ b/packages/viewer/src/stock.tsx
@@ -1,18 +1,13 @@
 import { useThree } from '@react-three/fiber'
 import { useEffect, useLayoutEffect, useMemo, useState } from 'react'
-import { type BufferGeometry, BoxGeometry, Vector3 } from 'three'
-import type { Vec3 } from './model/types.js'
+import type { BufferGeometry } from 'three'
 import { parseStockGlb } from './render/stock-mesh.js'
 import {
-  boxStockBounds,
+  type BoxStockInput,
+  boxStockGeometry,
   createStock,
   cylinderStockGeometry,
-  type CylinderStockFigure,
-  fixedBoxStockBounds,
-  orientedBoxStockGeometry,
-  type OrientedBoxStockFigure,
-  type StockAllowance,
-  type StockPosition,
+  type CylinderStockInput,
 } from './render/stock.js'
 
 export interface StockAppearanceProps {
@@ -23,27 +18,33 @@ export interface StockAppearanceProps {
   showEdges?: boolean
 }
 
+interface StockSources {
+  /** Caller-owned geometry; Stock never disposes it. */
+  geometry: BufferGeometry
+  /** Caller-provided GLB bytes; Stock owns and cleans up the decoded geometry. */
+  glb: ArrayBuffer
+  /** Resolved box corners/frame, or part-relative box preview options. */
+  box: BoxStockInput
+  /** Resolved cylinder placement, or part-relative cylinder preview options. */
+  cylinder: CylinderStockInput
+}
+
 /** Exactly one source, in the same millimetre, Z-up coordinates as the part. */
-export type StockSource =
-  | {
-      /** Caller-owned geometry; Stock never disposes it. */
-      geometry: BufferGeometry
-      glb?: never
-    }
-  | {
-      /** Caller-provided GLB bytes; Stock owns and cleans up the decoded geometry. */
-      glb: ArrayBuffer
-      geometry?: never
-    }
+export type StockSource = {
+  [K in keyof StockSources]: Pick<StockSources, K> &
+    Partial<Record<Exclude<keyof StockSources, K>, never>>
+}[keyof StockSources]
 
 export type StockProps = StockAppearanceProps & StockSource
 
 /** Translucent stock, included in Fit but ignored by picking, sections and measurements. */
-export const Stock = ({ geometry, glb, ...appearance }: StockProps) =>
+export const Stock = ({ geometry, glb, box, cylinder, ...appearance }: StockProps) =>
   geometry ? (
     <GeometryStock geometry={geometry} {...appearance} />
+  ) : glb ? (
+    <GlbStock glb={glb} {...appearance} />
   ) : (
-    <GlbStock glb={glb!} {...appearance} />
+    <ShapeStock box={box} cylinder={cylinder} {...appearance} />
   )
 
 /** One renderer for caller-owned geometry and internally decoded GLB meshes. */
@@ -111,86 +112,49 @@ const GlbStock = ({ glb, ...appearance }: StockAppearanceProps & { glb: ArrayBuf
   ))
 }
 
-export interface BoxStockProps extends StockAppearanceProps {
-  partGeometry: BufferGeometry
-  /** Explicit X/Y/Z dimensions, in millimetres, for fixed-box stock. */
-  dimensions?: Vec3
-  /** Position mode for explicit fixed-box stock. Defaults to model-centered. */
-  position?: StockPosition
-  /** Distance from the selected top/bottom part bound, in millimetres. */
-  positionOffset?: number
-  /**
-   * Stock left around the part, in millimetres. In the `{ wall, floor }` form,
-   * wall applies to X/Y and floor applies to Z. Number and `{ x, y, z }` forms
-   * are retained for compatibility. Defaults to zero.
-   */
-  allowance?: StockAllowance
-  /** Translation from the part's bounding-box centre, in millimetres. */
-  offset?: Vec3
-}
-
-/** An axis-aligned blank around the part. Use Stock for an arbitrary stock mesh. */
-export const BoxStock = ({
-  partGeometry,
-  dimensions,
-  position = 'model_centered',
-  positionOffset = 0,
-  allowance = 0,
-  offset,
-  ...props
-}: BoxStockProps) => {
-  const ox = offset?.x ?? 0
-  const oy = offset?.y ?? 0
-  const oz = offset?.z ?? 0
-  const geometry = useMemo(() => {
-    const box = dimensions
-      ? fixedBoxStockBounds(partGeometry, dimensions, position, positionOffset, {
-          x: ox,
-          y: oy,
-          z: oz,
-        })
-      : boxStockBounds(partGeometry, allowance, { x: ox, y: oy, z: oz })
-    const size = box.getSize(new Vector3())
-    const center = box.getCenter(new Vector3())
-    return new BoxGeometry(size.x, size.y, size.z).translate(center.x, center.y, center.z)
-  }, [allowance, dimensions, ox, oy, oz, partGeometry, position, positionOffset])
-  useEffect(() => () => geometry.dispose(), [geometry])
-  return <Stock geometry={geometry} {...props} />
-}
-
-export interface CylinderStockProps extends StockAppearanceProps, CylinderStockFigure {}
-
-/**
- * Round stock along any axis, from its base centre, axis, diameter and length
- * in part coordinates. Pass `fixedCylinderStock`'s figure for a preview,
- * or a planned job's resolved cylinder for the stock it was cut from.
- */
-export const CylinderStock = ({ origin, axis, diameter, length, ...props }: CylinderStockProps) => {
-  // Keyed on the figure's numbers rather than its identity: a figure read off
-  // an API response is a new object on every fetch, and the same stock should
-  // not rebuild its mesh.
-  const figure = JSON.stringify({ origin, axis, diameter, length })
-  const geometry = useMemo(
-    () => cylinderStockGeometry(JSON.parse(figure) as CylinderStockFigure),
-    [figure],
-  )
-  useEffect(() => () => geometry.dispose(), [geometry])
-  return <Stock geometry={geometry} {...props} />
-}
-
-export interface OrientedBoxStockProps extends StockAppearanceProps, OrientedBoxStockFigure {}
-
-/**
- * A block squared to its own frame rather than to the part, such as a planned
- * job's stock box, which is squared to the setup. Use BoxStock for a block
- * squared to the part.
- */
-export const OrientedBoxStock = ({ frame, lower, upper, ...props }: OrientedBoxStockProps) => {
-  const figure = JSON.stringify({ frame, lower, upper })
-  const geometry = useMemo(
-    () => orientedBoxStockGeometry(JSON.parse(figure) as OrientedBoxStockFigure),
-    [figure],
+/** Figure geometry is owned here; equivalent figures do not rebuild it. */
+const ShapeStock = ({
+  box,
+  cylinder,
+  ...appearance
+}: StockAppearanceProps & {
+  box?: BoxStockInput
+  cylinder?: CylinderStockInput
+}) => {
+  const isBox = box !== undefined
+  const partGeometry = box?.partGeometry ?? cylinder?.partGeometry
+  const figure = JSON.stringify(
+    box
+      ? box.partGeometry
+        ? {
+            dimensions: box.dimensions,
+            allowance: box.allowance,
+            offset: box.offset,
+            position: box.position,
+            positionOffset: box.positionOffset,
+          }
+        : { frame: box.frame, lower: box.lower, upper: box.upper }
+      : cylinder!.partGeometry
+        ? {
+            diameter: cylinder!.diameter,
+            length: cylinder!.length,
+            position: cylinder!.position,
+            positionOffset: cylinder!.positionOffset,
+          }
+        : {
+            origin: cylinder!.origin,
+            axis: cylinder!.axis,
+            diameter: cylinder!.diameter,
+            length: cylinder!.length,
+          },
   )
+  const geometry = useMemo(() => {
+    const options = JSON.parse(figure)
+    const input = partGeometry ? { ...options, partGeometry } : options
+    return isBox
+      ? boxStockGeometry(input as BoxStockInput)
+      : cylinderStockGeometry(input as CylinderStockInput)
+  }, [figure, isBox, partGeometry])
   useEffect(() => () => geometry.dispose(), [geometry])
-  return <Stock geometry={geometry} {...props} />
+  return <GeometryStock geometry={geometry} {...appearance} />
 }
diff --git a/packages/viewer/tests/stock-source.test.ts b/packages/viewer/tests/stock-source.test.ts
index b7eca53..69e6f55 100644
--- a/packages/viewer/tests/stock-source.test.ts
+++ b/packages/viewer/tests/stock-source.test.ts
@@ -1,13 +1,58 @@
 import { BufferGeometry } from 'three'
 import { expectTypeOf, it } from 'vitest'
-import type { BoxStockProps, StockProps } from '../src/stock.js'
+import type { StockProps } from '../src/stock.js'
 
-it('accepts one geometry or GLB source, with shared appearance props', () => {
+it('accepts exactly one geometry, GLB, box or cylinder source, with shared appearance props', () => {
+  const box = { lower: { x: 0, y: 0, z: 0 }, upper: { x: 10, y: 20, z: 30 } }
+  const cylinder = {
+    origin: { x: 0, y: 0, z: 0 },
+    axis: { x: 0, y: 0, z: 1 },
+    diameter: 10,
+    length: 20,
+  }
   expectTypeOf({ geometry: new BufferGeometry(), opacity: 0.3 }).toExtend<StockProps>()
   expectTypeOf({ glb: new ArrayBuffer(0), showEdges: false }).toExtend<StockProps>()
+  expectTypeOf({ box, color: 0xff0000 }).toExtend<StockProps>()
+  expectTypeOf({ cylinder, edgeOpacity: 0.5 }).toExtend<StockProps>()
+  expectTypeOf({
+    box: {
+      partGeometry: new BufferGeometry(),
+      dimensions: { x: 10, y: 20, z: 30 },
+      position: 'offset_from_top' as const,
+      positionOffset: 2,
+    },
+  }).toExtend<StockProps>()
+  expectTypeOf({
+    box: { partGeometry: new BufferGeometry(), allowance: { wall: 2, floor: 3 } },
+  }).toExtend<StockProps>()
+  expectTypeOf({
+    cylinder: { partGeometry: new BufferGeometry(), diameter: 10, length: 20 },
+  }).toExtend<StockProps>()
+  // @ts-expect-error Resolved box placement and preview options cannot be mixed.
+  expectTypeOf({ box: { ...box, partGeometry: new BufferGeometry() } }).toExtend<StockProps>()
+  const mixedCylinder = { cylinder: { ...cylinder, partGeometry: new BufferGeometry() } }
+  const mixedBoxSizing = {
+    box: { partGeometry: new BufferGeometry(), dimensions: { x: 10, y: 20, z: 30 }, allowance: 2 },
+  }
+  const incompleteCylinder = { cylinder: { partGeometry: new BufferGeometry(), diameter: 10 } }
+  // @ts-expect-error Resolved cylinder placement and preview options cannot be mixed.
+  expectTypeOf(mixedCylinder).toExtend<StockProps>()
+  // @ts-expect-error Fixed box dimensions and allowance sizing are alternative preview modes.
+  expectTypeOf(mixedBoxSizing).toExtend<StockProps>()
+  // @ts-expect-error A cylinder preview requires diameter and length.
+  expectTypeOf(incompleteCylinder).toExtend<StockProps>()
   // @ts-expect-error Exactly one source is required.
   expectTypeOf({ geometry: new BufferGeometry(), glb: new ArrayBuffer(0) }).toExtend<StockProps>()
   // @ts-expect-error A source cannot be omitted.
   expectTypeOf({ opacity: 0.3 }).toExtend<StockProps>()
-  expectTypeOf<BoxStockProps>().not.toHaveProperty('glb')
+  // @ts-expect-error Shape sources are also mutually exclusive.
+  expectTypeOf({ box, cylinder }).toExtend<StockProps>()
+  // @ts-expect-error Geometry and box cannot be supplied together.
+  expectTypeOf({ geometry: new BufferGeometry(), box }).toExtend<StockProps>()
+  // @ts-expect-error Geometry and cylinder cannot be supplied together.
+  expectTypeOf({ geometry: new BufferGeometry(), cylinder }).toExtend<StockProps>()
+  // @ts-expect-error GLB and box cannot be supplied together.
+  expectTypeOf({ glb: new ArrayBuffer(0), box }).toExtend<StockProps>()
+  // @ts-expect-error GLB and cylinder cannot be supplied together.
+  expectTypeOf({ glb: new ArrayBuffer(0), cylinder }).toExtend<StockProps>()
 })
diff --git a/packages/viewer/tests/stock.test.ts b/packages/viewer/tests/stock.test.ts
index bce8864..8647a78 100644
--- a/packages/viewer/tests/stock.test.ts
+++ b/packages/viewer/tests/stock.test.ts
@@ -16,10 +16,10 @@ import { contentBounds, partBounds } from '../src/render/camera.js'
 import { hitUnderRay } from '../src/render/section.js'
 import {
   boxStockBounds,
+  boxStockGeometry,
   createStock,
   cylinderStockGeometry,
   fixedBoxStockBounds,
-  fixedCylinderStock,
   orientedBoxStockGeometry,
   type StockPosition,
 } from '../src/render/stock.js'
@@ -50,6 +50,28 @@ function cylinderSpan(geometry: BufferGeometry, origin: Vec3, axis: Vec3) {
 }
 
 describe('stock dimensions', () => {
+  it('renders allowance and fixed-dimension preview options in part coordinates', () => {
+    const part = new BoxGeometry(20, 30, 10).translate(40, -10, 5)
+    const padded = bounds(
+      boxStockGeometry({
+        partGeometry: part,
+        allowance: { wall: 2, floor: 3 },
+        offset: { x: 1, y: 2, z: 3 },
+      }),
+    )
+    expect(padded.min.toArray()).toEqual([29, -25, 0])
+    expect(padded.max.toArray()).toEqual([53, 9, 16])
+    const fixed = bounds(
+      boxStockGeometry({
+        partGeometry: part,
+        dimensions: { x: 40, y: 50, z: 20 },
+        position: 'offset_from_top',
+        positionOffset: 2,
+      }),
+    )
+    expect(fixed.min.toArray()).toEqual([20, -35, -8])
+    expect(fixed.max.toArray()).toEqual([60, 15, 12])
+  })
   it('adds allowance on both sides and offsets from an off-origin part centre', () => {
     const geometry = new BoxGeometry(20, 30, 10).translate(40, -10, 5)
     const positions = geometry.getAttribute('position').array.slice()
@@ -116,12 +138,9 @@ describe('fixed cylinder stock', () => {
   const part = () => new BoxGeometry(20, 30, 10).translate(40, -10, 5)
 
   it('stands on the part Z and centres on its bounding box', () => {
-    expect(fixedCylinderStock(part(), { diameter: 50, length: 20 })).toEqual({
-      origin: { x: 40, y: -10, z: -5 },
-      axis: { x: 0, y: 0, z: 1 },
-      diameter: 50,
-      length: 20,
-    })
+    const box = bounds(cylinderStockGeometry({ partGeometry: part(), diameter: 50, length: 20 }))
+    expect(box.min.toArray()).toEqual([15, -35, -5])
+    expect(box.max.toArray()).toEqual([65, 15, 15])
   })
 
   it('places its ends by the same rule as a fixed box', () => {
@@ -132,25 +151,43 @@ describe('fixed cylinder stock', () => {
       ['offset_from_top', -1, -11],
     ]
     for (const [position, offset, bottom] of cases) {
-      const cylinder = fixedCylinderStock(part(), { diameter: 50, length: 20 }, position, offset)
+      const cylinder = bounds(
+        cylinderStockGeometry({
+          partGeometry: part(),
+          diameter: 50,
+          length: 20,
+          position,
+          positionOffset: offset,
+        }),
+      )
       const box = fixedBoxStockBounds(part(), { x: 50, y: 50, z: 20 }, position, offset)
-      expect(cylinder.origin.z).toBe(bottom)
-      expect(cylinder.origin.z).toBe(box.min.z)
-      expect(cylinder.origin.z + cylinder.length).toBe(box.max.z)
+      expect(cylinder.min.z).toBe(bottom)
+      expect(cylinder.min.z).toBe(box.min.z)
+      expect(cylinder.max.z).toBe(box.max.z)
     }
   })
 
   it('rejects sizes and offsets that would build NaN geometry', () => {
     for (const value of [0, -1, NaN, Infinity]) {
-      expect(() => fixedCylinderStock(part(), { diameter: value, length: 20 })).toThrow(RangeError)
-      expect(() => fixedCylinderStock(part(), { diameter: 20, length: value })).toThrow(RangeError)
+      expect(() =>
+        cylinderStockGeometry({ partGeometry: part(), diameter: value, length: 20 }),
+      ).toThrow(RangeError)
+      expect(() =>
+        cylinderStockGeometry({ partGeometry: part(), diameter: 20, length: value }),
+      ).toThrow(RangeError)
     }
     expect(() =>
-      fixedCylinderStock(part(), { diameter: 20, length: 20 }, 'offset_from_top', NaN),
+      cylinderStockGeometry({
+        partGeometry: part(),
+        diameter: 20,
+        length: 20,
+        position: 'offset_from_top',
+        positionOffset: NaN,
+      }),
+    ).toThrow(RangeError)
+    expect(() =>
+      cylinderStockGeometry({ partGeometry: new BufferGeometry(), diameter: 20, length: 20 }),
     ).toThrow(RangeError)
-    expect(() => fixedCylinderStock(new BufferGeometry(), { diameter: 20, length: 20 })).toThrow(
-      RangeError,
-    )
   })
 })
 
@@ -224,6 +261,16 @@ describe('cylinder stock geometry', () => {
 })
 
 describe('oriented box stock geometry', () => {
+  it('uses part-coordinate corners when no frame is supplied', () => {
+    const box = bounds(
+      orientedBoxStockGeometry({
+        lower: { x: -5, y: 10, z: 20 },
+        upper: { x: 15, y: 40, z: 60 },
+      }),
+    )
+    expect(box.min.toArray()).toEqual([-5, 10, 20])
+    expect(box.max.toArray()).toEqual([15, 40, 60])
+  })
   const frame = {
     location: { x: 5, y: 5, z: 5 },
     axis: { x: 0, y: 0, z: 1 },

From a2fc359ff3ebeee483bb7dfc8adf5512d99ca950 Mon Sep 17 00:00:00 2001
From: nathan-vandrei <87823030+dementive@users.noreply.github.com>
Date: Fri, 2 Oct 2026 10:46:42 -0400
Subject: [PATCH 4/5] Recover legacy stock rendering and seamless IPG
 transitions

---
 .changeset/stock-mesh-transitions.md          |   5 +
 .changeset/stock-workpiece-shading.md         |   5 +
 packages/viewer/README.md                     |  13 ++-
 .../viewer/src/render/stock-mesh-buffer.ts    |  50 +++++++++
 packages/viewer/src/render/stock.ts           |  14 ++-
 packages/viewer/src/stock.tsx                 |  94 ++++++++++------
 .../viewer/tests/stock-mesh-buffer.test.ts    | 102 ++++++++++++++++++
 packages/viewer/tests/stock-source.test.ts    |  10 ++
 packages/viewer/tests/stock.test.ts           |  26 +++++
 9 files changed, 285 insertions(+), 34 deletions(-)
 create mode 100644 .changeset/stock-mesh-transitions.md
 create mode 100644 .changeset/stock-workpiece-shading.md
 create mode 100644 packages/viewer/src/render/stock-mesh-buffer.ts
 create mode 100644 packages/viewer/tests/stock-mesh-buffer.test.ts

diff --git a/.changeset/stock-mesh-transitions.md b/.changeset/stock-mesh-transitions.md
new file mode 100644
index 0000000..774c4f7
--- /dev/null
+++ b/.changeset/stock-mesh-transitions.md
@@ -0,0 +1,5 @@
+---
+'@toolpath/viewer': minor
+---
+
+Add optional `Stock` `retainPrevious` behavior to keep the current GLB visible until its replacement finishes decoding. Dispose replaced geometry after the swap, and discard cancelled decode results.
diff --git a/.changeset/stock-workpiece-shading.md b/.changeset/stock-workpiece-shading.md
new file mode 100644
index 0000000..7ae366b
--- /dev/null
+++ b/.changeset/stock-workpiece-shading.md
@@ -0,0 +1,5 @@
+---
+'@toolpath/viewer': minor
+---
+
+Add a `legacy-workpiece` render style to `Stock`, reproducing legacy white/emissive shading, 20% opacity, two surface passes and edges drawn before surfaces. Add optional `emissive` and `flatShading` appearance props. Existing overlay defaults and source geometry remain unchanged.
diff --git a/packages/viewer/README.md b/packages/viewer/README.md
index bb14693..a00f287 100644
--- a/packages/viewer/README.md
+++ b/packages/viewer/README.md
@@ -285,7 +285,18 @@ missing-artifact fallback and artifact caching belong to the application. The ex
 **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`, `opacity` (default `0.2`), `edgeColor`, `edgeOpacity`, and `showEdges`.
+`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.
diff --git a/packages/viewer/src/render/stock-mesh-buffer.ts b/packages/viewer/src/render/stock-mesh-buffer.ts
new file mode 100644
index 0000000..fa9459c
--- /dev/null
+++ b/packages/viewer/src/render/stock-mesh-buffer.ts
@@ -0,0 +1,50 @@
+import type { BufferGeometry } from 'three'
+
+/** Own decoded meshes until their replacement has committed, including cancelled/late decodes. */
+export function createStockMeshBuffer() {
+  const owned = new Set<BufferGeometry>()
+  let disposed = false
+  return {
+    request(
+      decode: () => Promise<BufferGeometry[]>,
+      ready: (geometries: BufferGeometry[]) => void,
+      failed: (cause: unknown) => void,
+    ) {
+      // React StrictMode replays setup after cleanup on the same component instance.
+      disposed = false
+      let active = true
+      void decode().then(
+        (geometries) => {
+          if (!active || disposed) {
+            geometries.forEach((geometry) => geometry.dispose())
+            return
+          }
+          geometries.forEach((geometry) => owned.add(geometry))
+          ready(geometries)
+        },
+        (cause: unknown) => {
+          if (active && !disposed) {
+            failed(cause)
+          }
+        },
+      )
+      return () => {
+        active = false
+      }
+    },
+    commit(geometries: BufferGeometry[]) {
+      const visible = new Set(geometries)
+      for (const geometry of owned) {
+        if (!visible.has(geometry)) {
+          owned.delete(geometry)
+          geometry.dispose()
+        }
+      }
+    },
+    dispose() {
+      disposed = true
+      owned.forEach((geometry) => geometry.dispose())
+      owned.clear()
+    },
+  }
+}
diff --git a/packages/viewer/src/render/stock.ts b/packages/viewer/src/render/stock.ts
index 2e8d473..d5b78d4 100644
--- a/packages/viewer/src/render/stock.ts
+++ b/packages/viewer/src/render/stock.ts
@@ -307,15 +307,23 @@ function partBounds(geometry: BufferGeometry): Box3 {
 }
 
 /** Owns the stock materials and outline, never the caller's geometry. */
-export function createStock(geometry: BufferGeometry) {
+export function createStock(geometry: BufferGeometry, legacyWorkpiece = false) {
   const material = new MeshLambertMaterial({ transparent: true, depthWrite: false })
   const edgeMaterial = new LineBasicMaterial({ transparent: true, depthWrite: false })
   const mesh = new Mesh(geometry, material)
   const object = new Group()
   object.userData[STOCK_OBJECT] = true
-  mesh.renderOrder = 5
+  mesh.renderOrder = legacyWorkpiece ? 2 : 5
   mesh.raycast = () => {}
   object.add(mesh)
+  if (legacyWorkpiece) {
+    // Legacy Workpiece draws stock and stockShadow with the same material.
+    // Share geometry/material rather than allocating a second copy of the GLB.
+    const shadow = mesh.clone()
+    shadow.raycast = () => {}
+    object.add(shadow)
+    edgeMaterial.depthWrite = true
+  }
   let edges: LineSegments<EdgesGeometry, LineBasicMaterial> | null = null
   return {
     object,
@@ -329,7 +337,7 @@ export function createStock(geometry: BufferGeometry) {
     showEdges(show: boolean) {
       if (show && !edges) {
         edges = new LineSegments(new EdgesGeometry(geometry, 15), edgeMaterial)
-        edges.renderOrder = 6
+        edges.renderOrder = legacyWorkpiece ? 1 : 6
         edges.raycast = () => {}
         object.add(edges)
       }
diff --git a/packages/viewer/src/stock.tsx b/packages/viewer/src/stock.tsx
index 57b1747..efb6f3e 100644
--- a/packages/viewer/src/stock.tsx
+++ b/packages/viewer/src/stock.tsx
@@ -2,6 +2,7 @@ import { useThree } from '@react-three/fiber'
 import { useEffect, useLayoutEffect, useMemo, useState } from 'react'
 import type { BufferGeometry } from 'three'
 import { parseStockGlb } from './render/stock-mesh.js'
+import { createStockMeshBuffer } from './render/stock-mesh-buffer.js'
 import {
   type BoxStockInput,
   boxStockGeometry,
@@ -11,7 +12,15 @@ import {
 } from './render/stock.js'
 
 export interface StockAppearanceProps {
+  /** Keep the preceding decoded GLB visible until its replacement is ready. Key by part/run to reset. */
+  retainPrevious?: boolean
+  /** Reproduce the legacy Workpiece's materials, duplicate surface pass and edge ordering. */
+  renderStyle?: 'overlay' | 'legacy-workpiece'
   color?: number
+  /** Unlit surface contribution, useful for readable workpiece shading beside the CAD model. */
+  emissive?: number
+  /** Shade each triangle independently without changing the source's vertices or normals. */
+  flatShading?: boolean
   opacity?: number
   edgeColor?: number
   edgeOpacity?: number
@@ -50,62 +59,87 @@ export const Stock = ({ geometry, glb, box, cylinder, ...appearance }: StockProp
 /** One renderer for caller-owned geometry and internally decoded GLB meshes. */
 const GeometryStock = ({
   geometry,
-  color = 0xb9cbe2,
+  renderStyle = 'overlay',
+  color = renderStyle === 'legacy-workpiece' ? 0xffffff : 0xb9cbe2,
+  emissive = renderStyle === 'legacy-workpiece' ? 0x3c4051 : 0x000000,
+  flatShading = renderStyle === 'legacy-workpiece',
   opacity = 0.2,
-  edgeColor = 0xa8bdd8,
-  edgeOpacity = 0.75,
+  edgeColor = renderStyle === 'legacy-workpiece' ? 0x000000 : 0xa8bdd8,
+  edgeOpacity = renderStyle === 'legacy-workpiece' ? 0.5 : 0.75,
   showEdges = true,
 }: StockAppearanceProps & { geometry: BufferGeometry }) => {
   const invalidate = useThree((state) => state.invalidate)
-  const stock = useMemo(() => createStock(geometry), [geometry])
+  const stock = useMemo(
+    () => createStock(geometry, renderStyle === 'legacy-workpiece'),
+    [geometry, renderStyle],
+  )
   useEffect(() => () => stock.dispose(), [stock])
   useLayoutEffect(() => {
     stock.material.color.setHex(color)
+    stock.material.emissive.setHex(emissive)
+    if (stock.material.flatShading !== flatShading) {
+      stock.material.flatShading = flatShading
+      stock.material.needsUpdate = true
+    }
     stock.material.opacity = opacity
+    stock.material.depthWrite = renderStyle === 'legacy-workpiece' && opacity === 1
+    stock.material.polygonOffset = renderStyle === 'legacy-workpiece' && opacity === 1
+    stock.material.polygonOffsetFactor = 1
+    stock.material.polygonOffsetUnits = 1
     stock.edgeMaterial.color.setHex(edgeColor)
     stock.edgeMaterial.opacity = edgeOpacity
     stock.showEdges(showEdges)
     invalidate()
-  }, [color, edgeColor, edgeOpacity, invalidate, opacity, showEdges, stock])
+  }, [
+    color,
+    emissive,
+    flatShading,
+    edgeColor,
+    edgeOpacity,
+    invalidate,
+    opacity,
+    renderStyle,
+    showEdges,
+    stock,
+  ])
   return <primitive object={stock.object} dispose={null} />
 }
 
-const GlbStock = ({ glb, ...appearance }: StockAppearanceProps & { glb: ArrayBuffer }) => {
+const GlbStock = ({
+  glb,
+  retainPrevious = false,
+  ...appearance
+}: StockAppearanceProps & { glb: ArrayBuffer }) => {
+  const buffer = useMemo(() => createStockMeshBuffer(), [])
   const [decoded, setDecoded] = useState<{
     source: ArrayBuffer
     geometries?: BufferGeometry[]
     error?: Error
   } | null>(null)
 
-  useEffect(() => {
-    let active = true
-    let owned: BufferGeometry[] = []
-    parseStockGlb(glb).then(
-      (geometries) => {
-        if (!active) {
-          geometries.forEach((geometry) => geometry.dispose())
-          return
-        }
-        owned = geometries
-        setDecoded({ source: glb, geometries })
-      },
-      (cause: unknown) => {
-        if (active) {
+  useEffect(() => () => buffer.dispose(), [buffer])
+  useLayoutEffect(() => {
+    buffer.commit(decoded?.geometries ?? [])
+  }, [buffer, decoded])
+  useEffect(
+    () =>
+      buffer.request(
+        () => parseStockGlb(glb),
+        (geometries) => {
+          setDecoded({ source: glb, geometries })
+        },
+        (cause: unknown) => {
           setDecoded({
             source: glb,
             error: cause instanceof Error ? cause : new Error(String(cause)),
           })
-        }
-      },
-    )
-    return () => {
-      active = false
-      owned.forEach((geometry) => geometry.dispose())
-    }
-  }, [glb])
+        },
+      ),
+    [buffer, glb],
+  )
 
-  // A changed source must not display the preceding action while it decodes.
-  if (decoded?.source !== glb) return null
+  // Retention is opt-in: playback can hold its current IPG through the next decode.
+  if (!decoded || (!retainPrevious && decoded.source !== glb)) return null
   if (decoded.error) throw decoded.error
   return decoded.geometries?.map((geometry) => (
     <GeometryStock key={geometry.uuid} geometry={geometry} {...appearance} />
diff --git a/packages/viewer/tests/stock-mesh-buffer.test.ts b/packages/viewer/tests/stock-mesh-buffer.test.ts
new file mode 100644
index 0000000..4ba7be3
--- /dev/null
+++ b/packages/viewer/tests/stock-mesh-buffer.test.ts
@@ -0,0 +1,102 @@
+import { BoxGeometry } from 'three'
+import type { BufferGeometry } from 'three'
+import { describe, expect, it, vi } from 'vitest'
+import { createStockMeshBuffer } from '../src/render/stock-mesh-buffer.js'
+
+const deferred = () => {
+  let resolve!: (geometries: BufferGeometry[]) => void
+  let reject!: (cause: unknown) => void
+  const promise = new Promise<BufferGeometry[]>((yes, no) => {
+    resolve = yes
+    reject = no
+  })
+  return { promise, resolve, reject }
+}
+
+describe('decoded stock transitions', () => {
+  it('keeps A alive while B decodes and disposes A only after B commits', async () => {
+    const buffer = createStockMeshBuffer()
+    const a = new BoxGeometry()
+    const b = new BoxGeometry()
+    const disposeA = vi.spyOn(a, 'dispose')
+    const disposeB = vi.spyOn(b, 'dispose')
+    const ready = vi.fn()
+    const cancelA = buffer.request(() => Promise.resolve([a]), ready, vi.fn())
+    await Promise.resolve()
+    buffer.commit([a])
+    cancelA()
+    const pending = deferred()
+    buffer.request(() => pending.promise, ready, vi.fn())
+    expect(disposeA).not.toHaveBeenCalled()
+    pending.resolve([b])
+    await Promise.resolve()
+    expect(ready).toHaveBeenLastCalledWith([b])
+    expect(disposeA).not.toHaveBeenCalled()
+    buffer.commit([b])
+    expect(disposeA).toHaveBeenCalledOnce()
+    expect(disposeB).not.toHaveBeenCalled()
+    buffer.dispose()
+    expect(disposeB).toHaveBeenCalledOnce()
+  })
+
+  it('discards late B after A → B → A and never replaces the visible answer', async () => {
+    const buffer = createStockMeshBuffer()
+    const pending = deferred()
+    const b = new BoxGeometry()
+    const disposeB = vi.spyOn(b, 'dispose')
+    const ready = vi.fn()
+    const cancel = buffer.request(() => pending.promise, ready, vi.fn())
+    cancel()
+    pending.resolve([b])
+    await Promise.resolve()
+    expect(ready).not.toHaveBeenCalled()
+    expect(disposeB).toHaveBeenCalledOnce()
+    buffer.dispose()
+  })
+
+  it('disposes a decode completing after unmount', async () => {
+    const buffer = createStockMeshBuffer()
+    const pending = deferred()
+    const geometry = new BoxGeometry()
+    const dispose = vi.spyOn(geometry, 'dispose')
+    const ready = vi.fn()
+    buffer.request(() => pending.promise, ready, vi.fn())
+    buffer.dispose()
+    pending.resolve([geometry])
+    await Promise.resolve()
+    expect(ready).not.toHaveBeenCalled()
+    expect(dispose).toHaveBeenCalledOnce()
+  })
+
+  it('reports current decode errors but ignores cancelled failures', async () => {
+    const buffer = createStockMeshBuffer()
+    const failed = vi.fn()
+    const error = new Error('bad GLB')
+    buffer.request(() => Promise.reject(error), vi.fn(), failed)
+    await Promise.resolve()
+    expect(failed).toHaveBeenCalledWith(error)
+    const pending = deferred()
+    const cancel = buffer.request(() => pending.promise, vi.fn(), failed)
+    cancel()
+    pending.reject(error)
+    await Promise.resolve()
+    expect(failed).toHaveBeenCalledOnce()
+    buffer.dispose()
+  })
+
+  it('supports cleanup/setup replay without publishing an earlier request', async () => {
+    const buffer = createStockMeshBuffer()
+    const ready = vi.fn()
+    const first = deferred()
+    const cancel = buffer.request(() => first.promise, ready, vi.fn())
+    cancel()
+    buffer.dispose()
+    const current = new BoxGeometry()
+    buffer.request(() => Promise.resolve([current]), ready, vi.fn())
+    first.resolve([new BoxGeometry()])
+    await Promise.resolve()
+    expect(ready).toHaveBeenCalledOnce()
+    expect(ready).toHaveBeenCalledWith([current])
+    buffer.dispose()
+  })
+})
diff --git a/packages/viewer/tests/stock-source.test.ts b/packages/viewer/tests/stock-source.test.ts
index 69e6f55..1e8ca60 100644
--- a/packages/viewer/tests/stock-source.test.ts
+++ b/packages/viewer/tests/stock-source.test.ts
@@ -12,6 +12,16 @@ it('accepts exactly one geometry, GLB, box or cylinder source, with shared appea
   }
   expectTypeOf({ geometry: new BufferGeometry(), opacity: 0.3 }).toExtend<StockProps>()
   expectTypeOf({ glb: new ArrayBuffer(0), showEdges: false }).toExtend<StockProps>()
+  expectTypeOf({ glb: new ArrayBuffer(0), retainPrevious: true }).toExtend<StockProps>()
+  expectTypeOf({
+    glb: new ArrayBuffer(0),
+    renderStyle: 'legacy-workpiece' as const,
+  }).toExtend<StockProps>()
+  expectTypeOf({
+    glb: new ArrayBuffer(0),
+    emissive: 0x3c4051,
+    flatShading: true,
+  }).toExtend<StockProps>()
   expectTypeOf({ box, color: 0xff0000 }).toExtend<StockProps>()
   expectTypeOf({ cylinder, edgeOpacity: 0.5 }).toExtend<StockProps>()
   expectTypeOf({
diff --git a/packages/viewer/tests/stock.test.ts b/packages/viewer/tests/stock.test.ts
index 8647a78..48cacb0 100644
--- a/packages/viewer/tests/stock.test.ts
+++ b/packages/viewer/tests/stock.test.ts
@@ -359,6 +359,32 @@ describe('stock scene integration', () => {
     stock.dispose()
   })
 
+  it('matches legacy surface passes and edge ordering without copying the source geometry', () => {
+    const geometry = new BoxGeometry(10, 20, 30)
+    const stock = createStock(geometry, true)
+    stock.showEdges(true)
+    const surfaces = stock.object.children.filter((child) => child instanceof Mesh)
+    expect(surfaces).toHaveLength(2)
+    for (const surface of surfaces) {
+      expect((surface as Mesh).geometry).toBe(geometry)
+      expect((surface as Mesh).material).toBe(stock.material)
+      expect(surface.renderOrder).toBe(2)
+    }
+    const edges = stock.object.children.find((child) => child instanceof LineSegments)!
+    expect(edges.renderOrder).toBe(1)
+    expect(stock.edgeMaterial.depthWrite).toBe(true)
+    expect(stock.material.depthTest).toBe(true)
+    const root = new Group()
+    const part = new Mesh(new BoxGeometry(1, 1, 1))
+    root.add(stock.object, part)
+    const ray = new Raycaster(new Vector3(0, 0, 100), new Vector3(0, 0, -1))
+    expect(ray.intersectObject(root, true)[0]?.object).toBe(part)
+    const dispose = vi.spyOn(geometry, 'dispose')
+    stock.dispose()
+    expect(dispose).not.toHaveBeenCalled()
+    geometry.dispose()
+  })
+
   it('disposes owned GPU resources while leaving caller geometry reusable', () => {
     const geometry = new BoxGeometry(10, 10, 10)
     const stock = createStock(geometry)

From eec5e7fdd0608f6e9e162d90405cf2a458fdf376 Mon Sep 17 00:00:00 2001
From: Justin Gray <justin.s.gray@gmail.com>
Date: Fri, 2 Oct 2026 11:08:02 -0400
Subject: [PATCH 5/5] fix(viewer): reject non-finite and ignored stock inputs

ShapeStock keys its geometry on a JSON string of the figure and builds from
the parsed copy. JSON writes NaN and Infinity as null, so a non-finite scalar
allowance reached boxStockBounds as null and threw TypeError. The key now
encodes non-finite numbers as strings and the parse restores them, so every
non-finite figure throws RangeError.

A resolved BoxStockInput declares the preview options (offset, allowance,
dimensions, position, positionOffset) as never; they were accepted and
silently ignored.

orientedBoxStockGeometry normalises the frame axis and projects refDirection
square to it before building the basis, so a non-unit or skewed frame no
longer scales or shears the block. A zero refDirection throws RangeError.

The Changeset and README note that StockProps is now a union type alias.
---
 .changeset/cylinder-stock.md                |  2 ++
 packages/viewer/README.md                   |  5 +++-
 packages/viewer/src/render/stock.ts         | 27 ++++++++++++++-----
 packages/viewer/src/stock.tsx               | 13 ++++++++-
 packages/viewer/tests/stock-render.test.tsx | 30 +++++++++++++++++++++
 packages/viewer/tests/stock-source.test.ts  |  8 ++++++
 packages/viewer/tests/stock.test.ts         | 20 ++++++++++++++
 7 files changed, 97 insertions(+), 8 deletions(-)
 create mode 100644 packages/viewer/tests/stock-render.test.tsx

diff --git a/.changeset/cylinder-stock.md b/.changeset/cylinder-stock.md
index 78949ae..676cdd4 100644
--- a/.changeset/cylinder-stock.md
+++ b/.changeset/cylinder-stock.md
@@ -5,3 +5,5 @@
 Consolidate stock rendering into `Stock`, accepting exactly one of `geometry`, `glb`, `box`, or `cylinder`. Box and cylinder inputs accept either resolved placement or part-relative preview options, with placement calculated internally. Resolved box figures support optional setup frames; resolved cylinder figures support arbitrary axes. Fetching, caching and artifact storage remain caller-owned. Stock outlines are built only when shown.
 
 Remove `BoxStock` and `BoxStockProps`. Replace `<BoxStock partGeometry={geometry} allowance={allowance} />` with `<Stock box={{ partGeometry: geometry, allowance }} />`; for explicit dimensions use `<Stock box={{ partGeometry: geometry, dimensions, position, positionOffset, offset }} />`. Preview builders are internal, and inline options do not cause repeated part scans on ordinary renders. Existing `<Stock geometry={geometry} />` usage is unchanged.
+
+`StockProps` is now a union type alias rather than an interface, so `interface X extends StockProps` no longer compiles; write `type X = StockProps & { … }` instead. Use `StockAppearanceProps` for the shared appearance props alone.
diff --git a/packages/viewer/README.md b/packages/viewer/README.md
index bb14693..0730f51 100644
--- a/packages/viewer/README.md
+++ b/packages/viewer/README.md
@@ -241,7 +241,8 @@ 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`. That is the shape of an Engine plan's
+`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.
@@ -295,6 +296,8 @@ Toggling stock preserves the camera; Fit/Reset then frames the visible stock tog
 `<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
diff --git a/packages/viewer/src/render/stock.ts b/packages/viewer/src/render/stock.ts
index 2e8d473..8150161 100644
--- a/packages/viewer/src/render/stock.ts
+++ b/packages/viewer/src/render/stock.ts
@@ -44,8 +44,9 @@ export interface CylinderStockFigure {
  * A block squared to a frame of its own rather than to the part, in
  * millimetres. `lower` and `upper` are corners in `frame`, whose point
  * `(x, y, z)` sits at `location + x·refDirection + y·(axis × refDirection) + z·axis`
- * in part coordinates. This is the shape of the Engine's plan `StockBox`, which
- * is squared to the setup.
+ * in part coordinates, with `axis` normalised and `refDirection` projected
+ * square to it and normalised. This is the shape of the Engine's plan
+ * `StockBox`, which is squared to the setup.
  */
 export interface BoxStockFigure {
   /** Omit for a box whose corners are already in part coordinates. */
@@ -65,7 +66,14 @@ export type BoxStockPreview = {
 
 /** Resolved corners or part-relative preview options, never both. */
 export type BoxStockInput =
-  | (BoxStockFigure & { partGeometry?: never })
+  | (BoxStockFigure & {
+      partGeometry?: never
+      offset?: never
+      allowance?: never
+      dimensions?: never
+      position?: never
+      positionOffset?: never
+    })
   | (BoxStockPreview & { lower?: never; upper?: never; frame?: never })
 
 /** Upright cylinder preview centered on the part's bounding box. */
@@ -250,14 +258,21 @@ export function orientedBoxStockGeometry(figure: BoxStockFigure): BufferGeometry
   if (size.toArray().some((value) => !(value > 0))) {
     throw new RangeError('Box stock upper corner must be above its lower corner on every axis.')
   }
+  // Directions, not lengths: as in a STEP placement, the axis is normalised and
+  // the reference direction is projected square to it, so a non-unit or
+  // slightly skewed frame neither scales nor shears the block.
+  const z = new Vector3(axis.x, axis.y, axis.z).normalize()
   const x = new Vector3(refDirection.x, refDirection.y, refDirection.z)
-  const z = new Vector3(axis.x, axis.y, axis.z)
-  const y = new Vector3().crossVectors(z, x)
-  if (!(y.length() > 0)) {
+  const reference = x.length()
+  x.addScaledVector(z, -x.dot(z))
+  // Projection leaves float noise, not zero, when the two are parallel.
+  if (!(z.lengthSq() > 0 && x.length() > 1e-9 * reference)) {
     throw new RangeError(
       'Box stock frame axis and reference direction must be non-zero and not parallel.',
     )
   }
+  x.normalize()
+  const y = new Vector3().crossVectors(z, x)
   return new BoxGeometry(size.x, size.y, size.z)
     .translate((lower.x + upper.x) / 2, (lower.y + upper.y) / 2, (lower.z + upper.z) / 2)
     .applyMatrix4(new Matrix4().makeBasis(x, y, z).setPosition(location.x, location.y, location.z))
diff --git a/packages/viewer/src/stock.tsx b/packages/viewer/src/stock.tsx
index 57b1747..d3e428b 100644
--- a/packages/viewer/src/stock.tsx
+++ b/packages/viewer/src/stock.tsx
@@ -112,6 +112,16 @@ const GlbStock = ({ glb, ...appearance }: StockAppearanceProps & { glb: ArrayBuf
   ))
 }
 
+/**
+ * JSON alone writes NaN and Infinity as null, which the builders would read as
+ * an absent value instead of rejecting with RangeError. No figure field is a
+ * string that could be mistaken for one of these.
+ */
+const keepNonFinite = (_key: string, value: unknown) =>
+  typeof value === 'number' && !Number.isFinite(value) ? String(value) : value
+const restoreNonFinite = (_key: string, value: unknown) =>
+  value === 'NaN' || value === 'Infinity' || value === '-Infinity' ? Number(value) : value
+
 /** Figure geometry is owned here; equivalent figures do not rebuild it. */
 const ShapeStock = ({
   box,
@@ -147,9 +157,10 @@ const ShapeStock = ({
             diameter: cylinder!.diameter,
             length: cylinder!.length,
           },
+    keepNonFinite,
   )
   const geometry = useMemo(() => {
-    const options = JSON.parse(figure)
+    const options = JSON.parse(figure, restoreNonFinite)
     const input = partGeometry ? { ...options, partGeometry } : options
     return isBox
       ? boxStockGeometry(input as BoxStockInput)
diff --git a/packages/viewer/tests/stock-render.test.tsx b/packages/viewer/tests/stock-render.test.tsx
new file mode 100644
index 0000000..10d4d8e
--- /dev/null
+++ b/packages/viewer/tests/stock-render.test.tsx
@@ -0,0 +1,30 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { BoxGeometry } from 'three'
+import { describe, expect, it } from 'vitest'
+import { Stock } from '../src/stock.js'
+
+describe('Stock shape inputs', () => {
+  // The figure is built while Stock renders, before anything needs a Canvas.
+  const part = () => new BoxGeometry(20, 30, 10)
+
+  it('rejects a non-finite allowance with RangeError, as boxStockBounds does', () => {
+    for (const allowance of [NaN, Infinity, -Infinity]) {
+      expect(() =>
+        renderToStaticMarkup(<Stock box={{ partGeometry: part(), allowance }} />),
+      ).toThrow(RangeError)
+    }
+  })
+
+  it('rejects non-finite figures with RangeError', () => {
+    expect(() =>
+      renderToStaticMarkup(
+        <Stock box={{ partGeometry: part(), dimensions: { x: NaN, y: 10, z: 10 } }} />,
+      ),
+    ).toThrow(RangeError)
+    expect(() =>
+      renderToStaticMarkup(
+        <Stock cylinder={{ partGeometry: part(), diameter: Infinity, length: 10 }} />,
+      ),
+    ).toThrow(RangeError)
+  })
+})
diff --git a/packages/viewer/tests/stock-source.test.ts b/packages/viewer/tests/stock-source.test.ts
index 69e6f55..6b39716 100644
--- a/packages/viewer/tests/stock-source.test.ts
+++ b/packages/viewer/tests/stock-source.test.ts
@@ -30,6 +30,14 @@ it('accepts exactly one geometry, GLB, box or cylinder source, with shared appea
   }).toExtend<StockProps>()
   // @ts-expect-error Resolved box placement and preview options cannot be mixed.
   expectTypeOf({ box: { ...box, partGeometry: new BufferGeometry() } }).toExtend<StockProps>()
+  // @ts-expect-error A resolved box is already placed; an offset would be ignored.
+  expectTypeOf({ box: { ...box, offset: { x: 5, y: 0, z: 0 } } }).toExtend<StockProps>()
+  // @ts-expect-error A resolved box is already sized; an allowance would be ignored.
+  expectTypeOf({ box: { ...box, allowance: 3 } }).toExtend<StockProps>()
+  // @ts-expect-error A resolved box is already sized; dimensions would be ignored.
+  expectTypeOf({ box: { ...box, dimensions: { x: 1, y: 1, z: 1 } } }).toExtend<StockProps>()
+  // @ts-expect-error A resolved box is already placed; a position would be ignored.
+  expectTypeOf({ box: { ...box, position: 'offset_from_top' as const } }).toExtend<StockProps>()
   const mixedCylinder = { cylinder: { ...cylinder, partGeometry: new BufferGeometry() } }
   const mixedBoxSizing = {
     box: { partGeometry: new BufferGeometry(), dimensions: { x: 10, y: 20, z: 30 }, allowance: 2 },
diff --git a/packages/viewer/tests/stock.test.ts b/packages/viewer/tests/stock.test.ts
index 8647a78..c94a324 100644
--- a/packages/viewer/tests/stock.test.ts
+++ b/packages/viewer/tests/stock.test.ts
@@ -302,6 +302,19 @@ describe('oriented box stock geometry', () => {
     expect(box.max.toArray()).toEqual([35, 15, 25])
   })
 
+  it('reads the frame as directions, so a non-unit or skewed frame neither scales nor shears', () => {
+    const box = bounds(
+      orientedBoxStockGeometry({
+        // A long axis, and a long reference direction tilted toward it.
+        frame: { ...frame, axis: { x: 0, y: 0, z: 3 }, refDirection: { x: 2, y: 0, z: 0.5 } },
+        lower: { x: -1, y: -2, z: -3 },
+        upper: { x: 10, y: 20, z: 30 },
+      }),
+    )
+    expect(box.min.toArray()).toEqual([4, 3, 2])
+    expect(box.max.toArray()).toEqual([15, 25, 35])
+  })
+
   it('rejects degenerate frames and inverted corners', () => {
     const lower = { x: 0, y: 0, z: 0 }
     const upper = { x: 1, y: 1, z: 1 }
@@ -315,6 +328,13 @@ describe('oriented box stock geometry', () => {
     expect(() =>
       orientedBoxStockGeometry({ frame: { ...frame, axis: { x: 0, y: 0, z: 0 } }, lower, upper }),
     ).toThrow(RangeError)
+    expect(() =>
+      orientedBoxStockGeometry({
+        frame: { ...frame, refDirection: { x: 0, y: 0, z: 0 } },
+        lower,
+        upper,
+      }),
+    ).toThrow(RangeError)
     expect(() =>
       orientedBoxStockGeometry({ frame, lower: upper, upper: { x: 2, y: 1, z: 2 } }),
     ).toThrow(RangeError)