partforge 0.128.0 → 0.130.0

package/docs/AUTHORING-PARTS.md

@@ -259,10 +259,32 @@ Rules (all lint-enforced):
 - Couple motions through `derive` (animate one master param; derive the rest),
   not by tracking dependent params separately.
 - `camera` cues use the seven canonical angles (`iso front back top bottom
-  left right`). One mechanism per animation: an animation-level name (an intro
-  cue at t=0), an animation-level `[[t, angle], …]` list, or per-step names.
+  left right`) or any view-cube orientation — an edge or corner named
+  vertical, then depth, then side (`top-front-left`, `top-back-right`,
+  `front-left`, `bottom-back-right`, …; `top-front-right` is `iso`). One
+  mechanism per animation: an animation-level name (an intro cue at t=0), an
+  animation-level `[[t, angle], …]` list, or per-step names.
   Cues fire during play only — scrubbing never moves the camera — and a user
   orbit disarms the remaining cues for that run.
+- **A camera move takes as long as its cue asks**: a per-step `camera` sweeps
+  across that step's whole `duration`, and a listed cue sweeps until the next
+  cue (or the end). The move that settles the camera BEFORE playback starts —
+  the first cue, or the governing one when play resumes mid-timeline — is
+  always a short swing, because params wait for it. So a slow orbit timed to a
+  motion is a camera-only opening step (the starting angle) followed by the
+  moving step carrying the destination angle.
+- **To turn the view, move the camera — never rotate the part.** A "spin"
+  param that rotates the geometry for a turntable effect looks right in CAD
+  mode but is wrong in realistic mode: the floor, shadow and backdrop stay put
+  in the world, so the part visibly slides around on them. Use cues instead:
+
+  ```js
+  steps: [
+    { label: "Start", camera: "top-front-left", duration: 0.3 },       // establishing angle
+    { label: "Open lid", camera: "iso", duration: 1.5,                  // orbits to iso over 1.5 s
+      tracks: { lidOpen: [[0, 0], [1, 100]] } },
+  ]
+  ```
 - Playback drives params through the real param pipeline: a **pose-only**
   param (feeds only rigid placement — see "Caching & determinism" below) plays
   at frame rate; anything else rebuilds best-effort at worker cadence. `lint`
@@ -331,7 +353,10 @@ meta: { title: "…", units: "mm", environment: "studio" },
 colour, flattened so dark materials stay readable. **Realistic** mode — the
 viewer's toggle — shows the full material under environment lighting, with a
 ground and soft shadow and no feature lines. The part never moves when the
-mode changes.
+mode changes. The ground is placed under the part when a view is shown and
+after each edit; while an animation plays or is scrubbed it stays where it is
+(dropping lower only if the part would otherwise sink into it), so a motion
+that changes the part's footprint never slides the floor around under it.
 
 **3D-print layer lines** (`pla-print`, `petg-print`) run perpendicular to the
 **export** pose's +Z — the way the part will be printed, not the way it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.128.0",
+  "version": "0.130.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/animation-controls.js

@@ -504,6 +504,12 @@ export function attachAnimationControls(viewer, part, {
       // write params, or it would dirty the regen loop for a display-only fade.
       // First write for this run also remembers what the user's params were, so
       // Reset can put them back.
+      // Anything the animation moves holds the realistic floor where it is (see
+      // viewer.js placeGround): a track that rebuilds geometry re-shows the
+      // assembly every delivery, and the floor must not chase each frame's
+      // bounds. Released by a user edit, reset/stop, or a view switch — NOT by
+      // reaching the end, which would just move the jump to the last frame.
+      if (Object.keys(r.values).length || Object.keys(r.opacity ?? {}).length) viewer.holdGround?.(true);
       if (Object.keys(r.values).length) {
         if (snapshot == null) snapshot = getParamValues(current.trackedKeys);
         applyValues(r.values);
@@ -513,7 +519,10 @@ export function attachAnimationControls(viewer, part, {
       for (const [n, v] of Object.entries(r.opacity ?? {})) viewer.setSubPartOpacity?.(n, v);
       if (r.cue) {
         viewer.tweenCameraTo(r.cue.view, {
-          duration: tweenDuration,
+          // An intro gates playback, so it is always the short tween; a cue
+          // crossed mid-timeline sweeps for as long as the cue asks (its step,
+          // or until the next cue) — see normalizeAnimation.
+          duration: reducedMotion ? 0 : r.status === "intro" ? tweenDuration : (r.cue.sweep ?? tweenDuration),
           // An intro cue gates playback until the tween settles; mid-timeline
           // cues overlap playback and need no completion signal.
           onComplete: r.status === "intro" ? () => guarded(() => playback.introDone()) : undefined,
@@ -536,6 +545,9 @@ export function attachAnimationControls(viewer, part, {
   }
 
   function doReset() {
+    // Before the snapshot is re-applied: the rebuild that restores the user's
+    // params is an ordinary placement, so the floor comes back to the part.
+    viewer.holdGround?.(false);
     playback?.reset();
     viewer.cancelCameraTween();
     viewer.clearSubPartOpacities?.();
@@ -811,6 +823,7 @@ export function attachAnimationControls(viewer, part, {
     // pause playback rather than fight over them.
     notifyUserEdit() {
       disarmAutoplay();
+      viewer.holdGround?.(false); // a user edit places the floor again, as without animation
       viewer.cancelCameraTween();
       playback?.userEdited();
       syncUi();
@@ -851,6 +864,7 @@ export function attachAnimationControls(viewer, part, {
       if (status !== "playing" && status !== "intro") guarded(() => playback.play());
     },
     detach() {
+      viewer.holdGround?.(false);
       offFrame();
       offOrbit();
       viewer.clearSubPartOpacities?.();

package/src/framework/animation.js

@@ -62,10 +62,22 @@ export function normalizeAnimation(name, spec) {
   const totalDuration = steps.reduce((sum, s) => sum + s.duration, 0) || 1;
   let acc = 0;
   const stepStarts = steps.map((s) => { const t = acc / totalDuration; acc += s.duration; return t; });
+  // Each cue carries `sweep`: how many seconds its camera move takes when
+  // playback crosses it. A per-step cue sweeps across its own step, and a
+  // cue-list entry until the next cue (or the end), so a slow orbit can be timed
+  // to the motion it frames. An intro cue — the one play() settles on before
+  // params move — ignores it and uses the driver's short fixed tween, since it
+  // gates playback and a long one would read as a stall.
   let cues;
-  if (typeof spec.camera === "string") cues = [{ t: 0, view: spec.camera }];
-  else if (Array.isArray(spec.camera)) cues = spec.camera.map(([t, view]) => ({ t, view }));
-  else cues = steps.flatMap((s, i) => (s.camera ? [{ t: stepStarts[i], view: s.camera }] : []));
+  // A lone angle name is only ever an intro, so it has no sweep of its own.
+  if (typeof spec.camera === "string") cues = [{ t: 0, view: spec.camera, sweep: null }];
+  else if (Array.isArray(spec.camera)) {
+    cues = spec.camera.map(([t, view], i, all) => ({
+      t, view, sweep: ((all[i + 1]?.[0] ?? 1) - t) * totalDuration,
+    }));
+  } else {
+    cues = steps.flatMap((s, i) => (s.camera ? [{ t: stepStarts[i], view: s.camera, sweep: s.duration }] : []));
+  }
   // Keys with at least one usable keyframe list in any step, for one field
   // ("tracks" or "opacity"). Shares usableKeyframes with segmentsFor — the
   // single rule both must agree on (see the comment on usableKeyframes).
@@ -200,6 +212,7 @@ export function createPlayback(anim) {
   let firedCueT = -1;     // cues with t <= firedCueT already fired this run
   let pendingCueT = null; // cue handed to an in-flight intro tween, not yet settled
   let stopAt = null;      // stepNext/playStep pause playback on reaching this t
+  let sweepingCue = null; // the cue tick() last fired, whose camera sweep may still be moving
 
   const snapshot = (cue = null) => ({ t, status, ...evaluate(anim, t), cue });
 
@@ -227,8 +240,24 @@ export function createPlayback(anim) {
     stopAt = null;
     return begin();
   }
+  // A stop mid-sweep cancels the camera where it is. Un-fire that cue so the
+  // next play() re-honors it (as an intro) instead of resuming with the camera
+  // stranded partway; a sweep that has already landed stays fired, so an
+  // ordinary pause/resume costs no extra tween.
+  // Only a cue crossed DURING playback sweeps; an intro lands its pose fully
+  // before params move, so it is never abandoned here.
+  function abandonSweep() {
+    const c = sweepingCue;
+    sweepingCue = null;
+    if (c && t < c.t + c.sweep / anim.totalDuration) {
+      let prev = -1;
+      for (const o of anim.cues) if (o.t < c.t) prev = o.t;
+      firedCueT = prev;
+    }
+  }
+
   function pause() {
-    if (status === "playing" || status === "intro") status = "paused";
+    if (status === "playing" || status === "intro") { status = "paused"; abandonSweep(); }
     pendingCueT = null; // an unsettled intro cue is abandoned, so resume re-issues it
     return snapshot();
   }
@@ -246,6 +275,7 @@ export function createPlayback(anim) {
     stopAt = null;
     firedCueT = -1; // a later play() re-honors the cue governing the new position
     pendingCueT = null;
+    sweepingCue = null;
     return snapshot();
   }
   function playStep(i) {
@@ -254,6 +284,7 @@ export function createPlayback(anim) {
     stopAt = idx + 1 < anim.steps.length ? anim.stepStarts[idx + 1] : 1;
     firedCueT = -1;
     pendingCueT = null;
+    sweepingCue = null;
     return begin();
   }
   function stepNext() {
@@ -264,11 +295,11 @@ export function createPlayback(anim) {
     return playStep(Math.max(0, stepIndexAt(anim, t) - 1));
   }
   function reset() {
-    t = 0; status = "idle"; stopAt = null; firedCueT = -1; pendingCueT = null; armed = true;
+    t = 0; status = "idle"; stopAt = null; firedCueT = -1; pendingCueT = null; armed = true; sweepingCue = null;
     return snapshot();
   }
   function disarmCues() { armed = false; }
-  function userEdited() { if (status === "playing" || status === "intro") status = "paused"; }
+  function userEdited() { if (status === "playing" || status === "intro") { status = "paused"; abandonSweep(); } }
 
   function tick(dt) {
     if (status !== "playing" || !(dt > 0)) return null;
@@ -277,17 +308,21 @@ export function createPlayback(anim) {
     // animation, so the two rarely coexist — but when they do, an explicit
     // "play this step" must still stop where it was told to, rather than being
     // swallowed by the wrap and running forever.
+    let stoppedAtBoundary = false;
     if (stopAt != null && t >= stopAt) {
-      t = stopAt; stopAt = null; status = "paused";
+      t = stopAt; stopAt = null; status = "paused"; stoppedAtBoundary = true;
     } else if (anim.loop) {
       if (t >= 1) t -= Math.floor(t);
     } else if (t >= 1) {
       t = 1; status = "done";
     }
     let cue = null;
-    if (armed) {
+    // Stopping on a step boundary does not start the next step's camera move:
+    // that cue belongs to the step that has not played yet, and would otherwise
+    // sweep on while playback sits paused. Playing that step intros to it.
+    if (armed && !stoppedAtBoundary) {
       for (const c of anim.cues) if (c.t <= t && c.t > firedCueT) cue = c;
-      if (cue) firedCueT = cue.t;
+      if (cue) { firedCueT = cue.t; sweepingCue = cue; }
     }
     return snapshot(cue);
   }

package/src/framework/lint/rules-animations.js

@@ -12,7 +12,7 @@
 // letting the author wonder why nothing plays.
 import { err, note } from "./finding.js";
 import { EASINGS } from "../animation.js";
-import { CANONICAL_VIEWS } from "../view-angles.js";
+import { CANONICAL_VIEWS, CAMERA_CUE_VIEWS } from "../view-angles.js";
 import { probeSubPartPose } from "../pose-probe-core.js";
 import { resolveDerived } from "../derive.js";
 import { desugar } from "../panel/legacy.js";
@@ -372,7 +372,9 @@ export const ANIMATION_RULES = [
     id: "animation-camera-invalid",
     run: ({ part }) => {
       const out = [];
-      const badName = (v) => typeof v !== "string" || !CANONICAL_VIEWS.includes(v);
+      const badName = (v) => typeof v !== "string" || !CAMERA_CUE_VIEWS.includes(v);
+      // The seven canonical names plus the view cube's corners and edges.
+      const angles = `${CANONICAL_VIEWS.join(", ")}, or a view-cube orientation such as top-front-left or top-back-right`;
       for (const { name, a, base } of animEntries(part)) {
         const stepCameras = Array.isArray(a.steps)
           ? a.steps.map((s, i) => [s?.camera, i]).filter(([c]) => c !== undefined && c !== null)
@@ -386,8 +388,8 @@ export const ANIMATION_RULES = [
         for (const [cam, i] of stepCameras) {
           if (badName(cam)) {
             out.push(err("animation-camera-invalid",
-              `animation "${name}" step ${i} camera "${cam}" is not a canonical angle`,
-              `Camera cues use the canonical angles: ${CANONICAL_VIEWS.join(", ")}.`,
+              `animation "${name}" step ${i} camera "${cam}" is not a camera angle`,
+              `Camera cues use ${angles}.`,
               `${base}.steps[${i}].camera`));
           }
         }
@@ -397,8 +399,8 @@ export const ANIMATION_RULES = [
         if (typeof a.camera === "string") {
           if (badName(a.camera)) {
             out.push(err("animation-camera-invalid",
-              `animation "${name}" camera "${a.camera}" is not a canonical angle`,
-              `Camera cues use the canonical angles: ${CANONICAL_VIEWS.join(", ")}.`,
+              `animation "${name}" camera "${a.camera}" is not a camera angle`,
+              `Camera cues use ${angles}.`,
               `${base}.camera`));
           }
         } else if (Array.isArray(a.camera)) {
@@ -409,7 +411,7 @@ export const ANIMATION_RULES = [
           if (!wellFormed || !sorted) {
             out.push(err("animation-camera-invalid",
               `animation "${name}" has an invalid camera cue list`,
-              `Cues are \`[[t, angle], …]\` with t strictly ascending in 0..1 and angles from: ${CANONICAL_VIEWS.join(", ")}.`,
+              `Cues are \`[[t, angle], …]\` with t strictly ascending in 0..1 and angles from: ${angles}.`,
               `${base}.camera`));
           }
         } else {

package/src/framework/materials/environments.js

@@ -19,7 +19,7 @@ export const DEFAULT_ENVIRONMENT_ID = "studio";
 
 export const ENVIRONMENTS = {
   studio: {
-    id: "studio", label: "Studio", exposure: 0.8,
+    id: "studio", label: "Studio", exposure: 0.64,
     hdr: "env-studio.jpg",
     // Paper 001's fibre relief (normal + roughness) does the work: its colour
     // map is nearly flat, so without them the sweep read as soft blotches up
@@ -35,7 +35,7 @@ export const ENVIRONMENTS = {
     blurriness: 0.3,
   },
   workshop: {
-    id: "workshop", label: "Workshop", exposure: 0.88,
+    id: "workshop", label: "Workshop", exposure: 0.7,
     hdr: "env-workshop.jpg",
     // Unfinished maple: Poly Haven "Oak Veneer 01" lightened and desaturated
     // at bake time, with its normal map at a gentle strength and NO roughness
@@ -47,7 +47,7 @@ export const ENVIRONMENTS = {
     },
   },
   "print-bed": {
-    id: "print-bed", label: "Print bed", exposure: 0.42,
+    id: "print-bed", label: "Print bed", exposure: 0.34,
     // The studio photo re-baked with --contrast: a darker, harsher room, like
     // the inside of a printer's enclosure.
     hdr: "env-print-bed.jpg",
@@ -65,7 +65,7 @@ export const ENVIRONMENTS = {
     },
   },
   outdoor: {
-    id: "outdoor", label: "Outdoor", exposure: 0.72,
+    id: "outdoor", label: "Outdoor", exposure: 0.58,
     hdr: "env-outdoor.jpg",
     // Tinted to a warm mid-grey: the overcast sky lights an untinted concrete
     // map near-white and blue. Exposed-aggregate concrete with its own normal

package/src/framework/view-angles.js

@@ -81,6 +81,13 @@ function buildOrientations() {
 export const ORIENTATIONS = buildOrientations();
 export const ORIENTATION_IDS = Object.keys(ORIENTATIONS);
 
+// Every angle an animation camera cue may name: the seven canonical names first,
+// then the view cube's other orientations (so "top-front-left" is iso seen from
+// the other front corner). cameraPoseForView resolves all of them; this list is
+// what lint holds cues to. Kept apart from CANONICAL_VIEWS for the reason the
+// comment on ORIENTATIONS gives.
+export const CAMERA_CUE_VIEWS = [...new Set([...CANONICAL_VIEWS, ...ORIENTATION_IDS])];
+
 const norm = (v) => {
   const l = Math.hypot(v[0], v[1], v[2]) || 1;
   return [v[0] / l, v[1] / l, v[2] / l];

package/src/framework/viewer.js

@@ -794,15 +794,28 @@ export function createViewer(container, part) {
   // The ground comes to the part: it sits at the bottom of what is visible and
   // is sized from it. Only on showAssembly (and on entering the mode) — an
   // animated pose change moves the shadow, never the floor.
+  //
+  // An animation that REBUILDS geometry re-shows the assembly on every
+  // delivery, though, and re-deriving the floor from each frame's bounds slides
+  // it under the part as the bounds shift (feedback #138: a lid swinging open
+  // dragged the floor back with it). So while the animation driver holds the
+  // ground, a placement reuses the last one and may only LOWER it — never slide
+  // it sideways or resize it, and never lift it into the part. The hold is
+  // viewer-wide rather than per rig, so an environment switch mid-playback
+  // lands its floor in the same place.
+  let groundHeld = false;
+  let lastGround = null;
+  function holdGround(on) { groundHeld = !!on; }
   function placeGround({ force = false } = {}) {
     if (!realisticRig) return;
     const b = getVisibleWorldBounds(); // shared Box3: read it out before anything else runs
     if (b.isEmpty()) return;
     const center = b.getCenter(new THREE.Vector3());
     const size = b.getSize(new THREE.Vector3());
-    realisticRig.setGround({
-      y: b.min.y, centerX: center.x, centerZ: center.z, radius: size.length() / 2, footprintMm: Math.max(size.x, size.z),
-    });
+    lastGround = groundHeld && lastGround
+      ? { ...lastGround, y: Math.min(lastGround.y, b.min.y) }
+      : { y: b.min.y, centerX: center.x, centerZ: center.z, radius: size.length() / 2, footprintMm: Math.max(size.x, size.z) };
+    realisticRig.setGround(lastGround);
     shadowMovedAt = null; // this render is the full-resolution one
     renderShadow(undefined, { force });
   }
@@ -2658,6 +2671,7 @@ export function createViewer(container, part) {
     onFrame,
     onAssemblyChange: (cb) => { assemblyListeners.add(cb); return () => assemblyListeners.delete(cb); },
     tweenCameraTo,
+    holdGround,
     cancelCameraTween,
     orbitBy,
     onCameraStart,

package/src/testing/render.js

@@ -1,6 +1,7 @@
 import { writeFileSync, mkdirSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { safeName } from "../framework/safe-name.js";
+import { ORIENTATIONS } from "../framework/view-angles.js";
 import { buildView } from "../framework/oracle/build.js";
 import { bounds } from "../framework/oracle/mesh.js";
 
@@ -23,6 +24,17 @@ export const RENDER_ANGLES = {
 };
 export const RENDER_VIEWS = Object.keys(RENDER_ANGLES);
 
+// The view cube's other orientations (animation camera cues may name them, and
+// a still defaults to its cue's angle), mapped from the viewer's Y-up world
+// back into model space: world (x, y, z) -> model (x, -z, y).
+export function renderAngle(name) {
+  if (Object.hasOwn(RENDER_ANGLES, name)) return RENDER_ANGLES[name];
+  const o = Object.hasOwn(ORIENTATIONS, name) ? ORIENTATIONS[name] : null;
+  if (!o) return null;
+  const toModel = ([x, y, z]) => [x, -z, y];
+  return { dir: toModel(o.dir), up: toModel(o.up) };
+}
+
 const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
 const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
@@ -93,8 +105,8 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
   const written = [];
 
   for (const angle of views) {
-    const a = RENDER_ANGLES[angle];
-    if (!a) throw new Error(`unknown angle "${angle}" (use: ${RENDER_VIEWS.join(", ")})`);
+    const a = renderAngle(angle);
+    if (!a) throw new Error(`unknown angle "${angle}" (use: ${RENDER_VIEWS.join(", ")}, or a view-cube orientation such as top-front-left)`);
     // orthographic camera basis: zc toward camera, xc right, yc up
     const zc = norm(a.dir), xc = norm(cross(a.up, zc)), yc = cross(zc, xc);
     // Key direction (toward the light), placed over the viewer's shoulder — up and to

package/types/part.d.ts

@@ -556,11 +556,22 @@ export type Keyframes = Array<[number, number]>;
 export type CanonicalView = "iso" | "front" | "back" | "left" | "right" | "top" | "bottom";
 
 /**
- * A camera cue angle. `partforge lint` rejects anything outside the canonical
- * seven (`animation-camera-invalid`), so the type says so too. Cues fire during
- * play only; scrubbing never moves the camera.
+ * The view cube's other orientations: its edges and corners, named vertical,
+ * then depth, then side. `"top-front-right"` is the same camera as `"iso"`.
  */
-export type CameraCue = CanonicalView;
+export type ViewCubeOrientation =
+  | "top-front" | "top-back" | "top-left" | "top-right"
+  | "bottom-front" | "bottom-back" | "bottom-left" | "bottom-right"
+  | "front-left" | "front-right" | "back-left" | "back-right"
+  | "top-front-left" | "top-front-right" | "top-back-left" | "top-back-right"
+  | "bottom-front-left" | "bottom-front-right" | "bottom-back-left" | "bottom-back-right";
+
+/**
+ * A camera cue angle: one of the canonical seven or a view-cube orientation.
+ * `partforge lint` rejects anything else (`animation-camera-invalid`). Cues fire
+ * during play only; scrubbing never moves the camera.
+ */
+export type CameraCue = CanonicalView | ViewCubeOrientation;
 
 /** One step of a multi-step animation. Steps play in order; prev/next navigate them. */
 export interface AnimationStep {
@@ -586,7 +597,12 @@ export interface AnimationStep {
    * never affects params, export, measure, or verify.
    */
   opacity?: Record<string, Keyframes>;
-  /** Swing the camera to this angle when the step begins. */
+  /**
+   * Swing the camera to this angle, starting when the step begins and taking
+   * the step's whole duration — so a slow orbit can be timed to the motion it
+   * frames. (Starting playback at this step instead makes a short move there
+   * before anything else runs.)
+   */
   camera?: CameraCue;
 }
 
@@ -604,7 +620,8 @@ export interface AnimationSpecCommon {
   loop?: boolean;
   /**
    * One mechanism per animation: an angle (an intro cue at t=0), a
-   * `[[t, angle], …]` cue list, or per-step `camera` names.
+   * `[[t, angle], …]` cue list, or per-step `camera` names. A listed cue's
+   * camera move lasts until the next cue (or the end of the animation).
    */
   camera?: CameraCue | Array<[number, CameraCue]>;
   /**