partforge 0.41.0 → 0.45.0

package/src/framework/app.css

@@ -217,6 +217,38 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   #viewbar .pf-cutaway-actions button { min-width: 44px; padding: 0 6px; }
 }
 
+/* animation transport bar (placement: chrome.css's .pf-anim-bar). APPEARANCE
+   is ungated for the same reason as #viewbar above. */
+.pf-anim-bar {
+  display: flex; align-items: center; gap: 8px;
+  padding: 6px 10px;
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control); box-shadow: var(--pf-shadow-float);
+}
+.pf-anim-bar button {
+  border: 0; background: transparent; color: var(--pf-muted);
+  cursor: pointer; font-size: 13px; padding: 2px 4px;
+}
+.pf-anim-bar button:hover { color: var(--pf-text-2); }
+.pf-anim-title, .pf-anim-pick {
+  font-family: var(--pf-mono); font-size: 11px; color: var(--pf-text-2);
+}
+.pf-anim-pick {
+  background: var(--pf-input-bg); border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control); padding: 3px 6px;
+}
+.pf-anim-step {
+  font-family: var(--pf-mono); font-size: 10px; color: var(--pf-muted-2);
+  min-width: 90px; text-align: center; white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis;
+}
+.pf-anim-scrub-wrap { position: relative; display: inline-flex; align-items: center; width: 140px; }
+.pf-anim-scrub { width: 100%; accent-color: var(--pf-accent); }
+.pf-anim-tick {
+  position: absolute; top: 50%; width: 2px; height: 8px; margin-top: -4px;
+  background: var(--pf-muted); pointer-events: none;
+}
+
 /* Legacy id-only markup only: classed markup's viewbar lives inside .pf-stage
    (bottom-right, see chrome.css's .pf-float-viewbar) so it never meets the
    top-left floating #panel card. Legacy markup still floats #viewbar top-right

package/src/framework/assembly.js

@@ -1,4 +1,4 @@
-import { viewSubParts, resolveParams, buildPosed } from "./jobs.js";
+import { viewSubParts, resolveParams, buildPosed } from "./part-model.js";
 
 // Collision check for an assembled view: build each sub-part in its display
 // (assembly) pose and return the pairs whose solid-intersection volume exceeds

package/src/framework/backend-select.js

@@ -0,0 +1,25 @@
+// Chooses which geometry backend (manifold vs occt) a part should build against.
+// This is framework-level policy, not geometry-kernel plumbing: it knows the full
+// PartDefinition shape (meta.backend, defaults, parts[name].build), unlike
+// everything in geometry/, which is part-agnostic.
+import { OCCT_ONLY_OPS } from "./geometry/kernel.js";
+import { createProbeKernel } from "./geometry/probe.js";
+import { resolveDerived } from "./derive.js";
+
+const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
+
+export function detectBackend(part, params = {}) {
+  if (part.meta?.backend) return part.meta.backend;
+  const p = { ...part.defaults, ...params };
+  let d = {};
+  // A throwing derive must not escape here — this runs on the main thread mid
+  // regen (after the busy spinner goes up). Probe with an empty `d`; the worker
+  // build hits the same throw and posts a proper error for the UI.
+  try { d = resolveDerived(part, p); } catch { /* fall through with d = {} */ }
+  const { kernel, used } = createProbeKernel();
+  for (const name of Object.keys(part.parts)) {
+    try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }
+  }
+  for (const op of used) if (OCCT_ONLY.has(op)) return "occt";
+  return "manifold";
+}

package/src/framework/camera-tween.js

@@ -0,0 +1,58 @@
+import * as THREE from "three";
+import { EASINGS } from "./animation.js";
+
+// Retargetable orbit-camera tween for animation camera cues: eased spherical
+// interpolation of {position, target} pairs about the (linearly moving) orbit
+// target, shortest-path in azimuth, clamped off the poles so OrbitControls
+// never gimbal-locks on a "top"/"bottom" cue. Pure math, no clock — the viewer
+// feeds dt seconds into update() each frame and applies the returned pose.
+const POLE_EPS = 0.01;
+
+function toSpherical(position, target) {
+  const off = new THREE.Vector3().fromArray(position).sub(new THREE.Vector3().fromArray(target));
+  const sph = new THREE.Spherical().setFromVector3(off);
+  sph.phi = Math.min(Math.PI - POLE_EPS, Math.max(POLE_EPS, sph.phi));
+  return sph;
+}
+
+export function createCameraTween() {
+  let tw = null; // { fromSph, toSph, fromTarget, toTarget, duration, elapsed, onComplete }
+
+  // `from` is always the CALLER's current pose, which is what makes a restart
+  // mid-flight retarget smoothly: the new tween begins wherever the camera is.
+  function start(from, to, { duration = 0.6, onComplete } = {}) {
+    const fromSph = toSpherical(from.position, from.target);
+    const toSph = toSpherical(to.position, to.target);
+    const d = toSph.theta - fromSph.theta;
+    if (d > Math.PI) toSph.theta -= 2 * Math.PI;
+    if (d < -Math.PI) toSph.theta += 2 * Math.PI;
+    tw = {
+      fromSph, toSph,
+      fromTarget: new THREE.Vector3().fromArray(from.target),
+      toTarget: new THREE.Vector3().fromArray(to.target),
+      duration, elapsed: 0, onComplete,
+    };
+  }
+
+  function update(dt) {
+    if (!tw) return null;
+    tw.elapsed += dt;
+    const done = tw.elapsed >= tw.duration;
+    const u = done ? 1 : EASINGS["ease-in-out"](tw.elapsed / tw.duration);
+    const lerp = (a, b) => a + (b - a) * u;
+    const sph = new THREE.Spherical(
+      lerp(tw.fromSph.radius, tw.toSph.radius),
+      lerp(tw.fromSph.phi, tw.toSph.phi),
+      lerp(tw.fromSph.theta, tw.toSph.theta),
+    );
+    const target = tw.fromTarget.clone().lerp(tw.toTarget, u);
+    const position = new THREE.Vector3().setFromSpherical(sph).add(target);
+    const onComplete = tw.onComplete;
+    if (done) tw = null;
+    const out = { position: position.toArray(), target: target.toArray(), done };
+    if (done) onComplete?.();
+    return out;
+  }
+
+  return { start, update, cancel: () => { tw = null; }, isActive: () => !!tw };
+}

package/src/framework/capture-build.js

@@ -0,0 +1,59 @@
+// Correlated one-shot geometry builds for captureView — a private channel that
+// does NOT go through the regen loop. Same shape as export-controller's pending
+// Map (export-controller.js): allocate a jobId, resolve when the matching
+// reply arrives. Pure — no DOM, no worker; `send` is injected.
+export function createCaptureBuild({ send }) {
+  let nextId = 1;
+  let disposed = false;
+  const pending = new Map(); // jobId -> resolve
+
+  function request({ subparts, view, params, backend }) {
+    // After teardown the workers are gone, so a fresh send would post to a terminated
+    // worker (a silent no-op) and its promise would hang forever. Resolve null instead
+    // — captureView's documented "disposed runtime resolves null" contract.
+    if (disposed) return Promise.resolve(null);
+    // String-namespaced ("cap-N") so a capture jobId can never collide with
+    // export-controller's numeric jobIds — both share the same worker message
+    // space, and exportCtl.handleMessage does a raw pending.get(m.jobId) before
+    // checking type, so a colliding id could otherwise settle the wrong promise.
+    const jobId = `cap-${nextId++}`;
+    return new Promise((resolve) => {
+      pending.set(jobId, resolve);
+      // cache:true so the worker reuses its per-sub-part geometry memo (the
+      // expensive CSG); only the per-view place() + meshing re-run.
+      send({ type: "capture-generate", jobId, subparts, view, params, cache: true }, backend);
+    });
+  }
+
+  // Returns true iff this message was a reply this controller owns (so the
+  // caller — mount.js's onWorkerMessage — can skip it entirely). Keyed on
+  // membership in `pending` first: the namespaced jobId guarantees another
+  // channel's message never matches, so a hit here is always ours. A failed
+  // build (the worker's shared catch posts a generic error/needs-occt, jobId
+  // intact) resolves to null rather than leaving the caller hanging forever —
+  // captureView treats null as "capture failed, skip".
+  function handleMessage(data) {
+    const jobId = data?.jobId;
+    if (jobId == null || !pending.has(jobId)) return false;
+    if (data.type === "capture-meshes") {
+      pending.get(jobId)(data.meshes);
+    } else if (data.type === "error" || data.type === "needs-occt") {
+      pending.get(jobId)(null);
+    } else {
+      return false;
+    }
+    pending.delete(jobId);
+    return true;
+  }
+
+  // Teardown / worker death: settle every in-flight request to null instead
+  // of leaving its promise permanently pending (a caller awaiting captureView
+  // across a viewer dispose must still get an answer, even a negative one).
+  function dispose() {
+    disposed = true;
+    for (const resolve of pending.values()) resolve(null);
+    pending.clear();
+  }
+
+  return { request, handleMessage, dispose };
+}

package/src/framework/chrome.css

@@ -161,6 +161,14 @@
 .pf-float-tabs { top: 12px; left: 50%; transform: translateX(-50%); }
 .pf-float-viewbar { bottom: 12px; right: 12px; }
 
+/* --- animation transport bar (generated by animation-controls.js) ----------
+   PLACEMENT ONLY, per the rule above; appearance lives in app.css next to
+   #viewbar's, so a host that re-anchors this bar still inherits its chrome. */
+.pf-anim-bar {
+  position: absolute; left: 50%; bottom: 14px; transform: translateX(-50%);
+  z-index: 15; max-width: calc(100% - 24px);
+}
+
 /* ---- the narrow-layout tab bar ------------------------------------------
    Created by mobile-tabs.js (no host markup declares it). Hidden by default:
    below the breakpoint the rail sits beside the viewer and needs no tab, so
@@ -229,6 +237,14 @@
   }
   .pf-rail-seam { display: none; }
   .pf-tabbar { display: flex; }
+  /* Lift the transport bar clear of the viewbar. On a phone the bar is nearly
+     the full stage width (max-width: 100% - 24px) while #viewbar sits at the
+     bottom-right of the same stage, at the same z-index — so at bottom: 14px
+     the transport bar paints straight over cutaway/reframe/theme and
+     makes them unclickable. The viewbar occupies 12px…56px from the bottom
+     (12px offset + 4px padding + 34px button + 4px padding + 2px border);
+     64px clears it with an 8px gap. */
+  .pf-anim-bar { bottom: 64px; }
 }
 
 

package/src/framework/controls.js

@@ -48,10 +48,20 @@ export function clampToRange(raw, min, max) {
 }
 
 // --- info glyph + per-panel popover -----------------------------------------
+// Popover top edge: below the glyph when it fits, flipped above when the
+// viewport bottom would clip it (e.g. the animation transport bar's ⓘ, which
+// sits at the bottom of the stage). Pure, for direct unit testing — happy-dom
+// reports zero layout metrics, so the flip can't be exercised via the DOM.
+export function popoverTop({ glyphTop, glyphBottom, popHeight, viewportHeight }) {
+  const below = glyphBottom + 6;
+  if (below + popHeight <= viewportHeight - 8) return below;
+  return Math.max(8, glyphTop - 6 - popHeight);
+}
+
 // One popover element per panel, shared by all its glyphs (only one open at a
 // time). Document-level dismiss listeners are registered per panel and removed
 // by panel.dispose().
-function createInfoPopover() {
+export function createInfoPopover() {
   const pop = el("div", "popover");
   pop.hidden = true;
   document.body.append(pop);
@@ -78,7 +88,7 @@ function createInfoPopover() {
       owner = glyph;
       glyph.setAttribute("aria-expanded", "true");
       const r = glyph.getBoundingClientRect();
-      pop.style.top = `${r.bottom + 6}px`;
+      pop.style.top = `${popoverTop({ glyphTop: r.top, glyphBottom: r.bottom, popHeight: pop.offsetHeight, viewportHeight: window.innerHeight })}px`;
       pop.style.left = `${Math.max(8, r.left - 8)}px`;
     },
     dispose() {
@@ -91,7 +101,7 @@ function createInfoPopover() {
 
 // Append a focusable ⓘ glyph to `container` that toggles the panel's shared
 // popover with `description` (Markdown). No-op when description is empty.
-function attachInfo(container, description, info) {
+export function attachInfo(container, description, info) {
   if (typeof description !== "string" || !description.trim()) return;
   const glyph = document.createElement("button");
   glyph.type = "button";

package/src/framework/cutaway-gizmo-scene.js

@@ -0,0 +1,244 @@
+import * as THREE from "three";
+import { CUTAWAY_OVERLAY_RENDER_ORDER } from "./cutaway-render.js";
+
+const GIZMO_RENDER_ORDER = CUTAWAY_OVERLAY_RENDER_ORDER + 1;
+const HANDLE_HOVER_THICKNESS = 1.6;
+
+/**
+ * Builds the cutaway gizmo's three.js scene graph: the ghost plane, the
+ * translate arrow, the two rotation arcs, and the invisible hit proxies that
+ * stand in for them while picking.
+ *
+ * Pure construction - the objects come back detached, so mounting them into a
+ * scene, posing them, and reacting to the pointer all stay in
+ * `createCutawayGizmo`.
+ *
+ * `theme` is one palette out of the gizmo's theme table. Colors are baked in
+ * here rather than written as literals so the very first rendered frame
+ * already agrees with the palette that later appearance updates re-derive.
+ */
+export function buildGizmoScene(theme) {
+  const geometries = new Set();
+  const materials = new Set();
+
+  const group = new THREE.Group();
+
+  const fill = new THREE.Mesh(
+    new THREE.PlaneGeometry(1, 1),
+    new THREE.MeshBasicMaterial({
+      color: theme.fill,
+      opacity: 0.18,
+      transparent: true,
+      depthTest: true,
+      depthWrite: false,
+      side: THREE.DoubleSide,
+    }),
+  );
+  geometries.add(fill.geometry);
+  materials.add(fill.material);
+
+  const borderGeometry = new THREE.BufferGeometry().setFromPoints([
+    new THREE.Vector3(-0.5, -0.5, 0),
+    new THREE.Vector3(0.5, -0.5, 0),
+    new THREE.Vector3(0.5, 0.5, 0),
+    new THREE.Vector3(-0.5, 0.5, 0),
+  ]);
+  const borderMaterial = new THREE.LineBasicMaterial({
+    color: theme.border,
+    opacity: 1,
+    transparent: true,
+    depthTest: false,
+    depthWrite: false,
+  });
+  const border = new THREE.LineLoop(borderGeometry, borderMaterial);
+  border.renderOrder = GIZMO_RENDER_ORDER;
+  geometries.add(borderGeometry);
+  materials.add(borderMaterial);
+
+  const handleRoot = new THREE.Group();
+  const translateVisualRoot = new THREE.Group();
+  const arcRoot = new THREE.Group();
+  const translateMaterial = new THREE.MeshBasicMaterial({
+    color: theme.translate,
+    transparent: true,
+    depthTest: true,
+    depthWrite: true,
+  });
+  const rotateXMaterial = new THREE.MeshBasicMaterial({
+    color: theme.rotateX,
+    transparent: true,
+    depthTest: true,
+    depthWrite: true,
+  });
+  const rotateYMaterial = new THREE.MeshBasicMaterial({
+    color: theme.rotateY,
+    transparent: true,
+    depthTest: true,
+    depthWrite: true,
+  });
+  materials.add(translateMaterial);
+  materials.add(rotateXMaterial);
+  materials.add(rotateYMaterial);
+
+  const shaftGeometry = new THREE.CylinderGeometry(0.025, 0.025, 0.58, 12);
+  const shaftHoverGeometry = new THREE.CylinderGeometry(
+    0.025 * HANDLE_HOVER_THICKNESS,
+    0.025 * HANDLE_HOVER_THICKNESS,
+    0.58,
+    12,
+  );
+  const shaft = new THREE.Mesh(shaftGeometry, translateMaterial);
+  shaft.rotation.x = Math.PI / 2;
+  shaft.position.z = 0.29;
+  const coneGeometry = new THREE.ConeGeometry(0.075, 0.2, 16);
+  const coneHoverGeometry = new THREE.ConeGeometry(
+    0.075 * HANDLE_HOVER_THICKNESS,
+    0.2,
+    16,
+  );
+  const cone = new THREE.Mesh(coneGeometry, translateMaterial);
+  cone.rotation.x = Math.PI / 2;
+  cone.position.z = 0.68;
+  geometries.add(shaftGeometry);
+  geometries.add(shaftHoverGeometry);
+  geometries.add(coneGeometry);
+  geometries.add(coneHoverGeometry);
+
+  const ringXGeometry = new THREE.TorusGeometry(
+    0.42,
+    0.015,
+    8,
+    64,
+    Math.PI,
+  );
+  const ringX = new THREE.Mesh(ringXGeometry, rotateXMaterial);
+  const ringXHoverGeometry = new THREE.TorusGeometry(
+    0.42,
+    0.015 * HANDLE_HOVER_THICKNESS,
+    8,
+    64,
+    Math.PI,
+  );
+  ringX.quaternion
+    .setFromAxisAngle(new THREE.Vector3(1, 0, 0), -Math.PI / 2)
+    .multiply(new THREE.Quaternion().setFromAxisAngle(
+      new THREE.Vector3(0, 1, 0),
+      Math.PI / 2,
+    ));
+  const ringYGeometry = new THREE.TorusGeometry(
+    0.42,
+    0.015,
+    8,
+    64,
+    Math.PI,
+  );
+  const ringY = new THREE.Mesh(ringYGeometry, rotateYMaterial);
+  const ringYHoverGeometry = new THREE.TorusGeometry(
+    0.42,
+    0.015 * HANDLE_HOVER_THICKNESS,
+    8,
+    64,
+    Math.PI,
+  );
+  ringY.rotation.x = -Math.PI / 2;
+  geometries.add(ringXGeometry);
+  geometries.add(ringXHoverGeometry);
+  geometries.add(ringYGeometry);
+  geometries.add(ringYHoverGeometry);
+
+  const hitMaterial = new THREE.MeshBasicMaterial({
+    color: 0xffffff,
+    opacity: 0,
+    transparent: true,
+    depthWrite: false,
+  });
+  materials.add(hitMaterial);
+  const translateHitGeometry = new THREE.CylinderGeometry(0.1, 0.1, 0.95, 10);
+  const translateHit = new THREE.Mesh(translateHitGeometry, hitMaterial);
+  translateHit.rotation.x = Math.PI / 2;
+  translateHit.position.z = 0.38;
+  translateHit.userData.cutawayHandle = "translate";
+  const rotateXHitGeometry = new THREE.TorusGeometry(
+    0.42,
+    0.12,
+    8,
+    48,
+    Math.PI,
+  );
+  const rotateXHit = new THREE.Mesh(rotateXHitGeometry, hitMaterial);
+  rotateXHit.quaternion.copy(ringX.quaternion);
+  rotateXHit.userData.cutawayHandle = "rotate-x";
+  const rotateYHitGeometry = new THREE.TorusGeometry(
+    0.42,
+    0.12,
+    8,
+    48,
+    Math.PI,
+  );
+  const rotateYHit = new THREE.Mesh(rotateYHitGeometry, hitMaterial);
+  rotateYHit.quaternion.copy(ringY.quaternion);
+  rotateYHit.userData.cutawayHandle = "rotate-y";
+  geometries.add(translateHitGeometry);
+  geometries.add(rotateXHitGeometry);
+  geometries.add(rotateYHitGeometry);
+
+  translateVisualRoot.add(shaft, cone);
+  arcRoot.add(ringX, ringY, rotateXHit, rotateYHit);
+  handleRoot.add(translateVisualRoot, translateHit, arcRoot);
+  group.add(fill, border);
+
+  const handles = {
+    translate: translateHit,
+    rotateX: rotateXHit,
+    rotateY: rotateYHit,
+  };
+  const handleVisuals = {
+    translate: translateVisualRoot,
+    rotateX: ringX,
+    rotateY: ringY,
+  };
+  const handleAppearance = {
+    translate: {
+      visual: translateVisualRoot,
+      material: translateMaterial,
+      geometryPairs: [
+        { mesh: shaft, normal: shaftGeometry, hovered: shaftHoverGeometry },
+        { mesh: cone, normal: coneGeometry, hovered: coneHoverGeometry },
+      ],
+    },
+    "rotate-x": {
+      visual: ringX,
+      material: rotateXMaterial,
+      geometryPairs: [
+        { mesh: ringX, normal: ringXGeometry, hovered: ringXHoverGeometry },
+      ],
+    },
+    "rotate-y": {
+      visual: ringY,
+      material: rotateYMaterial,
+      geometryPairs: [
+        { mesh: ringY, normal: ringYGeometry, hovered: ringYHoverGeometry },
+      ],
+    },
+  };
+
+  // Every geometry and material above - including the thickened hover variants
+  // that are swapped in and out of the meshes - is owned by this scene and
+  // nothing else. The caller disposes it exactly once, at teardown.
+  function dispose() {
+    for (const geometry of geometries) geometry.dispose();
+    for (const material of materials) material.dispose();
+  }
+
+  return {
+    group,
+    fill,
+    border,
+    handleRoot,
+    arcRoot,
+    handles,
+    handleVisuals,
+    handleAppearance,
+    dispose,
+  };
+}