Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

fix(assembly): a build turned while playback is paused no longer swings back

aashu32a2ef554939
diff --git a/packages/viewer/AGENTS.md b/packages/viewer/AGENTS.md
index d181c0ea31..769557384a 100644
--- a/packages/viewer/AGENTS.md
+++ b/packages/viewer/AGENTS.md
@@ -7,7 +7,7 @@
- **graph.json** (`AssemblyGraph`) — assembly tree written by the geometry service `/convert`; leaf nodes carry a stable `nodeId` (also baked into GLB node extras as `userData.nodeId`). All joins between steps, plans, and scene objects are by `nodeId`.
- **plan.json** (`AssemblyPlan`) — per-component insertion `Motion`, sequence, subassembly `groups`, and body-level `contacts`, written by the geometry service `/plan`. `CURRENT_PLAN_VERSION` (currently `3`) — stored plans below it are STALE and must be treated as absent so the pipeline re-plans.
- **Step** (`AssemblyStep`) — one build instruction: `componentNodeIds`, a `Motion`, optional `camera`, `fastener`, per-step `hiddenComponentNodeIds`, an optional `orientation`, and the sub-assembly fields `isSubAssembly` / `parentStepId` / `usedInStepId`. Built from a plan by `buildAssemblyStepGroups`.
-- **Build orientation** (`orientation.ts`) — a step's `orientation` is a unit quaternion turning the model frame into the bench frame (both Z-up); it holds from that step on within its own build (`resolveOrientations`, keyed by `stepWorlds`: the main build and each sub-assembly keep separate chains, a sub-assembly starts upright). The player shows it as a CAMERA FRAME, never by turning the model — turning a root node would break everything that works in world space (`buildStepClip`, the path editor, box select). `useBuildFrame` owns the frame: `camera.up` = `upForOrientation(q)`, and a new orientation turns the camera, its target and up about the build's center (the framed bounds' center) by `next⁻¹ · applied` over `TURN_MS`, so on screen the build turns over in place (turning about the target swung an off-center build round in an arc). Playback and framing wait for the turn (`isTurning`), and grabbing the controls finishes it. When the center moves (entering or leaving a sub-assembly) the new frame SNAPS instead of turning about the other build's center, and unmounting hands the camera back upright, because the camera outlives a remounted scene. A turned step with no saved view keeps the camera's bench direction (`keptDirection`) rather than re-aiming — any geometry-scored framer undoes a spin, since a spin is just an orbit — and the editor's turn buttons save the current view with the orientation, so playback lands on what the author saw. `keptDirection` (where the camera looks from once the pending turn lands) is the current direction for every step's framing, so stepping back from a turned step to an upright one scores its candidates from the post-turn view, not the pre-turn one. A saved view (`captureCameraPose`; `isSavedView` tells it from a plan hint) is stored in the BENCH frame (`toBench` / `fromBench`, about the same center), so turning a step keeps its view and turns the build; a plan hint is used only on an upright build (it turns with the model); a turn on the active step never re-frames (orientation is not in `framingKey`); drei `GizmoHelper` writes `camera.up` on every frame of a viewcube tween and resets it when the tween ends, so the hook restores the build's up whenever no turn is playing; the framing effect takes the STEP's up, not the mid-turn `camera.up`. `turnOrientation` applies one editor turn (`flip` 180°, `tipForward`/`tipBack`/`spinLeft`/`spinRight` 90°) about a SQUARE bench axis picked from the view and snaps the result to the 24 right-angle orientations (axis by axis, never entry rounding); `describeOrientation` names the pose (upright / upside down / on its side) for the editor.
+- **Build orientation** (`orientation.ts`) — a step's `orientation` is a unit quaternion turning the model frame into the bench frame (both Z-up); it holds from that step on within its own build (`resolveOrientations`, keyed by `stepWorlds`: the main build and each sub-assembly keep separate chains, a sub-assembly starts upright). The player shows it as a CAMERA FRAME, never by turning the model — turning a root node would break everything that works in world space (`buildStepClip`, the path editor, box select). `useBuildFrame` owns the frame: `camera.up` = `upForOrientation(q)`, and a new orientation turns the camera, its target and up about the build's center (the framed bounds' center) by `next⁻¹ · applied` over `TURN_MS`, so on screen the build turns over in place (turning about the target swung an off-center build round in an arc). Playback and framing wait for the turn (`isTurning`), and grabbing the controls finishes it. When the center moves (entering or leaving a sub-assembly) the new frame SNAPS instead of turning about the other build's center, and unmounting hands the camera back upright, because the camera outlives a remounted scene. A turned step with no saved view keeps the camera's bench direction (`keptDirection`) rather than re-aiming — any geometry-scored framer undoes a spin, since a spin is just an orbit — and the editor's turn buttons save the current view with the orientation, so playback lands on what the author saw. `keptDirection` (where the camera looks from once the pending turn lands) is the current direction for every step's framing, so stepping back from a turned step to an upright one scores its candidates from the post-turn view, not the pre-turn one. A saved view (`captureCameraPose`; `isSavedView` tells it from a plan hint) is stored in the BENCH frame (`toBench` / `fromBench`, about the same center), so turning a step keeps its view and turns the build; a plan hint is used only on an upright build (it turns with the model); a turn on the active step never re-frames (orientation is not in `framingKey`), and the camera's pending glide target (`desiredPoseRef`) is held in the bench frame too — held in the model frame, a target set by playback and not yet reached dragged the camera back after a turn made while paused; drei `GizmoHelper` writes `camera.up` on every frame of a viewcube tween and resets it when the tween ends, so the hook restores the build's up whenever no turn is playing; the framing effect takes the STEP's up, not the mid-turn `camera.up`. `turnOrientation` applies one editor turn (`flip` 180°, `tipForward`/`tipBack`/`spinLeft`/`spinRight` 90°) about a SQUARE bench axis picked from the view and snaps the result to the 24 right-angle orientations (axis by axis, never entry rounding); `describeOrientation` names the pose (upright / upside down / on its side) for the editor.
- **Sub-assemblies** (`subassembly.ts`) — a header step (`isSubAssembly`) groups the steps whose `parentStepId` points at it; those steps sit directly before it in play order and are BUILT ON THEIR OWN: while one is active the player isolates its sub-assembly's parts (focus-style, ancestors kept, not cleared by playback, framed on their own bounds). A header's `usedInStepId` names the later step that carries the finished unit in. A header whose `motion` is not `none` has a path of its own: the unit plays it (`buildStepClip`'s `units`, one after another in sub-assembly order) before the step's own parts move — a step with no animation of its own fades its parts in only after those units seat (`fadeProgress`). One `stepClipTiming` per step feeds the timeline segment, the clip and the fade delay; while picking components it gives the units and the glide no time. `buildCarryPlans` is THE per-step answer to which units fly (`pathUnits`), which glide, what the step's own insertion moves (`ownMovingPartIds`) and whether the step is an unused header joining on its own path (`joinsOnOwnPath`: that path is the header's motion, so it has no insertion of its own); `carriesUnits` says whether a step brings any unit in. The clip, the fade, the path editor and the framing all read it. Each header's unit parts come from `buildSubAssemblyPlan` (`unitPartIds`). A unit whose header has no path of its own (`motion` `none`) glides from beside the build (`CARRY_IN_GLIDE_SECONDS` / `buildStepClip`'s `glide.nodeIds`), then rides the using step's insertion. A header nothing uses is where its unit joins the main build; a USED header plays nothing (0-length segment, skipped by prev/next). A step whose own insertion moves nothing (`stepClipTiming`'s `ownParts: false`, e.g. a header joining on its own path) gets a slot of just its units and the hold — the fixed `none` slot is for process-only steps and own parts that fade in. No nesting — a step USES a finished sub-assembly instead, so chains of any length work. `arrivalIndexByNode(steps, world)` is THE answer to "when does this part appear in the build on screen" and drives visibility; `validateSubAssemblies` is THE structural rule the ERP service and editor share. `scopeStepIds` limits the timeline to an opened sub-assembly.
- **Motion** — discriminated union `linear | L | helix | path | waypoints | none`. `waypoints` is editor-authored: poses relative to the seated pose, turning about the moving set's seated bounds center, then shifting (`waypointMatrix`), so one motion fits a part, a rigid group or a sub-assembly. The player takes that center from graph.json's seated bounds for the clip (`buildStepClip`'s required `pivot`), the path editor and the framed start pose alike — the live nodes are mid-animation when framing runs. `resampleEased` keeps every input keyframe (at its eased time) besides its evenly spaced samples, so easing never cuts a turning leg's 15° samples short. The path editor saves `linear`/`L` until a waypoint is turned (`editorWaypointsToMotion`); it has a Move / Rotate tool (`pathToolLabels` on the player, host-translated — no labels, no switch): Rotate shows drei `TransformControls` rings on the selected waypoint and stops the spheres dragging, because the rings' invisible free-rotation grip sits over the sphere. Insertion motion; the player derives removal (reverse) and start poses. `flagged`/`blockedBy` steps use `none` and fade in (no collision-free path exists — a synthesized path would clip through geometry).
- **Artifact tiers** — a model renders from best-available: LOD GLB → optimised GLB → lossless GLB → raw WASM (in-browser occt-import-js) fallback.
diff --git a/packages/viewer/src/AssemblyPlayer.tsx b/packages/viewer/src/AssemblyPlayer.tsx
index 06fceaa221..0e435d10a4 100644
--- a/packages/viewer/src/AssemblyPlayer.tsx
+++ b/packages/viewer/src/AssemblyPlayer.tsx
@@ -992,6 +992,8 @@ type MaterialOverrides = {
// the transition allocates nothing.
const SCRATCH_CURRENT_OFFSET = new Vector3();
const SCRATCH_DESIRED_OFFSET = new Vector3();
+const SCRATCH_DESIRED_POSITION = new Vector3();
+const SCRATCH_DESIRED_TARGET = new Vector3();
const HIGHLIGHT_COLOR = 0x3b82f6;
// Selection is always red — both an in-scene click selection ("selected") and a
@@ -1983,7 +1985,9 @@ function AssemblyScene({
}, [scene, controls, frameBox, assemblyBox]);
// Smoothly approached camera pose (per-step rotation); cleared when the
- // user grabs the controls so they can take over mid-transition
+ // user grabs the controls so they can take over mid-transition. Held in the
+ // bench frame, like the camera: a model-frame target went stale when the
+ // build turned before the camera reached it, and dragged the turn back.
const desiredPoseRef = useRef<{ position: Vector3; target: Vector3 } | null>(
null
);
@@ -2030,8 +2034,16 @@ function AssemblyScene({
useFrame((_, delta) => {
// A turn to a new orientation plays first; framing waits for it.
if (buildFrame.isTurning()) return;
- const desired = desiredPoseRef.current;
- if (!desired || !controls) return;
+ const desiredBench = desiredPoseRef.current;
+ if (!desiredBench || !controls) return;
+ const desired = {
+ position: buildFrame.fromBench(
+ SCRATCH_DESIRED_POSITION.copy(desiredBench.position)
+ ),
+ target: buildFrame.fromBench(
+ SCRATCH_DESIRED_TARGET.copy(desiredBench.target)
+ )
+ };
const alpha = 1 - Math.exp(-delta * 4);
controls.target.lerp(desired.target, alpha);
@@ -2108,14 +2120,8 @@ function AssemblyScene({
const savedView = step.camera;
if (isSavedView(savedView)) {
desiredPoseRef.current = {
- position: buildFrame.fromBench(
- new Vector3(...savedView.position),
- orientation
- ),
- target: buildFrame.fromBench(
- new Vector3(...savedView.target),
- orientation
- )
+ position: new Vector3(...savedView.position),
+ target: new Vector3(...savedView.target)
};
if (camera instanceof PerspectiveCamera) {
camera.fov = savedView.fov;
@@ -2176,7 +2182,12 @@ function AssemblyScene({
? camera.aspect
: 16 / 9
});
- if (pose) desiredPoseRef.current = pose;
+ if (pose) {
+ desiredPoseRef.current = {
+ position: buildFrame.toBench(pose.position, orientation),
+ target: buildFrame.toBench(pose.target, orientation)
+ };
+ }
}, [
steps,
activeStepIndex,
diff --git a/packages/viewer/src/useBuildFrame.ts b/packages/viewer/src/useBuildFrame.ts
index 3c3a4e5759..72077e4cfd 100644
--- a/packages/viewer/src/useBuildFrame.ts
+++ b/packages/viewer/src/useBuildFrame.ts
@@ -17,14 +17,18 @@ const IDENTITY = new Quaternion();
// Reused every frame so the turn allocates nothing.
const SCRATCH_DELTA = new Quaternion();
const SCRATCH_STEP = new Quaternion();
+const SCRATCH_INVERSE = new Quaternion();
export type BuildFrame = {
/** A turn to a new orientation is playing: playback and framing wait for it. */
isTurning: () => boolean;
- /** A model-frame point as seen on the bench (where the viewer stands), in place. */
- toBench: (point: Vector3) => Vector3;
- /** A bench-frame point in the model frame of a build turned by `orientation`, in place. */
- fromBench: (point: Vector3, orientation: Quat) => Vector3;
+ /**
+ * A model-frame point as seen on the bench (where the viewer stands), in
+ * place. `orientation` defaults to the one on screen now.
+ */
+ toBench: (point: Vector3, orientation?: Quat) => Vector3;
+ /** The inverse of `toBench`, in place. */
+ fromBench: (point: Vector3, orientation?: Quat) => Vector3;
/**
* The camera's current bench direction (target → eye, unit), in the model
* frame of `orientation`: where it looks from once a turn to it lands.
@@ -169,13 +173,27 @@ export function useBuildFrame({
return frame !== null && !frame.applied.equals(frame.to);
}, []);
const toBench = useCallback(
- (point: Vector3) =>
- turnAbout(point, frameRef.current?.applied ?? IDENTITY, pivotRef.current),
+ (point: Vector3, orientation?: Quat) =>
+ turnAbout(
+ point,
+ orientation
+ ? toQuaternion(orientation)
+ : (frameRef.current?.applied ?? IDENTITY),
+ pivotRef.current
+ ),
[]
);
const fromBench = useCallback(
- (point: Vector3, target: Quat) =>
- turnAbout(point, toQuaternion(target).invert(), pivotRef.current),
+ (point: Vector3, orientation?: Quat) =>
+ turnAbout(
+ point,
+ SCRATCH_INVERSE.copy(
+ orientation
+ ? toQuaternion(orientation)
+ : (frameRef.current?.applied ?? IDENTITY)
+ ).invert(),
+ pivotRef.current
+ ),
[]
);
const keptDirection = useCallback(