partforge 0.126.0 → 0.128.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.126.0",
+  "version": "0.128.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

@@ -495,6 +495,9 @@ export function attachAnimationControls(viewer, part, {
   }
   function apply(r) {
     if (!r || !current) return;
+    // A playing frame always draws, whatever it changed: the viewer renders on
+    // demand, and playback must never stall waiting for something to ask.
+    viewer.requestRender?.();
     try {
       // Params go through applyValues (the slider path) only when the animation
       // actually drives some: an opacity-only frame must neither snapshot nor

package/src/framework/cutaway.js

@@ -40,6 +40,9 @@ export function createCutaway({
   edgeColor,
   schedule = defaultSchedule,
   now,
+  // The viewer draws on demand; the idle fade lands on a timer, with nothing
+  // else to ask for the frame that shows it.
+  requestRender = () => {},
 }) {
   // Reassignable: a projection swap (perspective <-> ortho) hands the cutaway
   // a new camera after construction, and the gizmo must follow it too.
@@ -191,7 +194,7 @@ export function createCutaway({
     gizmo.setActiveAppearance(true);
     const scheduled = schedule(() => {
       cancelIdle = null;
-      if (enabled && !disposed) gizmo.setActiveAppearance(false);
+      if (enabled && !disposed) { gizmo.setActiveAppearance(false); requestRender(); }
     }, IDLE_DELAY_MS);
     cancelIdle = typeof scheduled === "function"
       ? scheduled

package/src/framework/materials/patterns.js

@@ -85,23 +85,79 @@ vec3 pfTriplanarNormal(vec3 p, vec3 n, float scale) {
 }
 `;
 
+// Layer lines are 0.2 mm, so at an ordinary viewing distance a layer spans a
+// few pixels or less, and point-sampling the bead profile per pixel aliased
+// into moiré (worst in the specular, through the bead normals). So one layer's
+// profile is baked into a small repeating texture sampled by layer height, and
+// the GPU's mipmaps band-limit it. Channels: R = groove shade, G = bead slope
+// (encoded slope/6 + 0.5), B = slope^2 / 9. A mip level averages G and B
+// separately, so B - G^2 is the slope VARIANCE inside the pixel — the ridges it
+// can no longer show — which widens the specular lobe instead (Toksvig / LEAN
+// mapping), so a far wall keeps its satin sheen rather than turning glossy.
+export const LAYER_PROFILE_WIDTH = 256;
+// Gradient scale on the profile lookup (+0.58 mip). A box-filtered mip chain at
+// 1x still carries the full fundamental at 2 px per layer (its 2-texel level),
+// right at Nyquist, which banded across a whole-part view; 1.5 clears that and
+// keeps the lines crisp close up (2 visibly softened them).
+const LAYER_BLUR = "1.5";
+
+// One layer's bead, t running -1 (a seam) through 0 (the crest) to 1 (the next
+// seam): the groove shade darkens the 35% of each half-bead nearest a seam, and
+// the slope is a round bead's (t / sqrt(1 - t^2)), clamped to ±3 where it goes
+// vertical. (The procedural version darkened the CREST instead — its ridge was
+// |t|, not 1 - |t| — half a layer off the valleys its own normals drew.)
+export function layerProfileData(width = LAYER_PROFILE_WIDTH) {
+  const data = new Uint8Array(width * 4);
+  for (let i = 0; i < width; i++) {
+    const t = ((i + 0.5) / width) * 2 - 1;
+    const g = Math.min(1, (1 - Math.abs(t)) / 0.35);
+    const groove = g * g * (3 - 2 * g);
+    const slope = Math.min(3, Math.max(-3, t / Math.sqrt(Math.max(1 - t * t, 0.04))));
+    data[i * 4] = Math.round(groove * 255);
+    data[i * 4 + 1] = Math.round((slope / 6 + 0.5) * 255);
+    data[i * 4 + 2] = Math.round((slope * slope / 9) * 255);
+    data[i * 4 + 3] = 255;
+  }
+  return data;
+}
+
+// One texture shared by every layer-lines material, built on first use.
+let layerProfileTex = null;
+function layerProfileTexture() {
+  if (layerProfileTex) return layerProfileTex;
+  const t = new THREE.DataTexture(layerProfileData(), LAYER_PROFILE_WIDTH, 1, THREE.RGBAFormat, THREE.UnsignedByteType);
+  t.wrapS = THREE.RepeatWrapping;
+  t.wrapT = THREE.ClampToEdgeWrapping;
+  t.magFilter = THREE.LinearFilter;
+  t.minFilter = THREE.LinearMipmapLinearFilter;
+  t.generateMipmaps = true;
+  t.colorSpace = THREE.NoColorSpace;
+  t.needsUpdate = true;
+  return (layerProfileTex = t);
+}
+
+const FRAG_DECL_LAYERS = "uniform sampler2D pfLayerMap;\n";
+
 // Per-kind fragment code, injected after <roughnessmap_fragment> so it can
 // modulate both diffuseColor (already written by <map_fragment>) and roughnessFactor.
 const FRAG_BODY = {
+  // Declared at main() scope, not in a block: FRAG_NORMAL reads the same
+  // profile sample (pfLayer) rather than looking it up again.
   "layer-lines": `
+  float pfH = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;   // in layers
+  // fract() keeps the texel coordinate small (hundreds of layers x 256 texels
+  // loses sub-texel precision in the sampler); the explicit gradients are the
+  // unwrapped height's, so the wrap at each seam doesn't drop to the 1x1 mip.
+  vec4 pfLayer = textureGrad(pfLayerMap, vec2(fract(pfH), 0.5),
+    vec2(dFdx(pfH) * ${LAYER_BLUR}, 0.0), vec2(dFdy(pfH) * ${LAYER_BLUR}, 0.0));
   {
-    float h = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;
-    float ridge = abs(fract(h) - 0.5) * 2.0;            // 0 at a layer seam, 1 mid-layer
-    float groove = smoothstep(0.0, 0.35, ridge);
-    // Anti-alias: fwidth(h) is layers per pixel. Where a layer spans fewer
-    // than ~6 px the band fades to its mean over a period (0.825: the groove
-    // ramps over 35% of it, the rest is flat), and past ~2.5 px it is gone —
-    // point-sampling finer layers than that is what aliased into moiré.
-    groove = mix(0.825, groove, 1.0 - smoothstep(0.16, 0.4, fwidth(h)));
+    float groove = pfLayer.r;
     diffuseColor.rgb *= mix(0.9, 1.0, groove); // the normal map (FRAG_NORMAL) carries most of the relief
     roughnessFactor = clamp(roughnessFactor + (1.0 - groove) * 0.18, 0.0, 1.0);
     // Filament mottling: a fine grain (~0.17 mm) over slow blotches (~2 mm),
     // fixed to the part, so a print doesn't read as flat injection-moulded plastic.
+    // Hash noise, not a noise volume: a mipmapped 64^3 texture measured ~10%
+    // slower per frame on an M1 Max (a filtered 3D fetch reads 16 texels).
     float mottle = pfNoise(vPfObjPos * 6.0) * 0.6 + pfNoise(vPfObjPos * 0.51) * 0.4;
     diffuseColor.rgb *= mix(0.893, 1.047, mottle);
     roughnessFactor = clamp(roughnessFactor + (mottle - 0.5) * 0.084, 0.0, 1.0);
@@ -149,15 +205,14 @@ const FRAG_BODY = {
 // layer is a round bead, so across one layer the surface normal swings from
 // facing down (bottom of the bead) through straight out to facing up, along
 // the print direction projected onto the surface. Faces parallel to the layers
-// (tops and bottoms) get no ridges, as on a real print. Same fwidth fade as the
-// colour bands, so far-away layers don't alias.
+// (tops and bottoms) get no ridges, as on a real print. The slope comes from the
+// same mip-filtered profile sample as the colour bands, and the slope variance
+// the filter averaged away goes into roughness: alpha^2 += var(tilt).
 const FRAG_NORMAL = {
   "layer-lines": `
   {
-    float h = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;
-    float aa = 1.0 - smoothstep(0.16, 0.4, fwidth(h));
-    float t = fract(h) * 2.0 - 1.0;                       // -1 at a seam, 0 bead crest, 1 next seam
-    float slope = clamp(t / sqrt(max(1.0 - t * t, 0.04)), -3.0, 3.0);
+    float slope = pfLayer.g * 6.0 - 3.0;
+    float slopeVar = max(pfLayer.b * 9.0 - slope * slope, 0.0);
     vec3 up = normalize(vPfPrintUpView);
     // NOT normalised: its length is how steeply the surface cuts across the
     // layers (1 on a vertical wall, 0 on a face parallel to them), so ridges fade
@@ -165,7 +220,10 @@ const FRAG_NORMAL = {
     // full-strength tilt in a direction set by rounding noise, flipping sign
     // wherever the face sat on a layer boundary — a visible patch.
     vec3 along = up - normal * dot(normal, up);
-    normal = normalize(normal + along * slope * 0.35 * aa);
+    normal = normalize(normal + along * slope * 0.35);
+    // tilt = slope * 0.35 * |along|, so var(tilt) = slopeVar * 0.35^2 * |along|^2
+    float a = roughnessFactor * roughnessFactor;
+    roughnessFactor = min(sqrt(sqrt(a * a + slopeVar * 0.1225 * dot(along, along))), 1.0);
   }`,
   // Wood replaces the view-space normal with its triplanar normal map, built in
   // object space and carried to view space through the normal matrix. A
@@ -216,7 +274,11 @@ export function setGrainAxis(material, axis) {
 export function applyPattern(material, { kind, scale = 1, printFrame, texture, normalMap, roughnessMap, roughnessMean = 0.5, normalScale = 1, grain = "u" } = {}) {
   if (!kind || !FRAG_BODY[kind]) return material;
   const wood = kind === "wood";
+  const layers = kind === "layer-lines";
   const uniforms = {
+    ...(layers ? {
+      pfLayerMap: { value: layerProfileTexture() },
+    } : {}),
     pfPatternScale: { value: scale },
     pfPrintFrame: { value: new THREE.Matrix4().fromArray(printFrame ?? new THREE.Matrix4().toArray()) },
     pfPatternMap: { value: texture ?? null },
@@ -236,7 +298,7 @@ export function applyPattern(material, { kind, scale = 1, printFrame, texture, n
       .replace("#include <common>", `#include <common>\n${VERT_DECL}${wood ? VERT_DECL_NM : ""}`)
       .replace("#include <begin_vertex>", `#include <begin_vertex>\n${VERT_BODY}${wood ? VERT_BODY_NM : ""}`);
     shader.fragmentShader = shader.fragmentShader
-      .replace("#include <common>", `#include <common>\n${FRAG_DECL}${wood ? FRAG_DECL_WOOD : ""}`)
+      .replace("#include <common>", `#include <common>\n${FRAG_DECL}${wood ? FRAG_DECL_WOOD : ""}${layers ? FRAG_DECL_LAYERS : ""}`)
       .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>\n${FRAG_BODY[kind]}`)
       .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>\n${FRAG_NORMAL[kind] ?? ""}`);
   };

package/src/framework/measure/dim3-scene.js

@@ -99,6 +99,10 @@ export function defaultPaintLabel({ text, palette }) {
 }
 
 export function createDimScene(viewer, { paintLabel = defaultPaintLabel } = {}) {
+  // Dims are scene objects edited in place, not through a viewer call, so they
+  // ask for the frame themselves (the viewer draws on demand). tick() needs no
+  // request: it only follows the camera, and a camera move is already a frame.
+  const redraw = () => viewer.requestRender?.();
   const group = new THREE.Group();
   group.name = "pf-dims";
   let attached = false;
@@ -238,6 +242,7 @@ export function createDimScene(viewer, { paintLabel = defaultPaintLabel } = {})
 
   function update(drawings) {
     if (!ensureAttached()) return;
+    redraw();
     disposeChildren();
     for (const d of drawings) {
       const key = matFor(d.tier);
@@ -423,6 +428,7 @@ export function createDimScene(viewer, { paintLabel = defaultPaintLabel } = {})
   function setTheme(mode) {
     if (!DIM_THEME[mode] || mode === theme) return;
     theme = mode;
+    redraw();
     lineMats.static.color.set(DIM_THEME[theme].static);
     lineMats.strong.color.set(DIM_THEME[theme].strong);
     fillMats.static.color.set(DIM_THEME[theme].static);
@@ -434,9 +440,10 @@ export function createDimScene(viewer, { paintLabel = defaultPaintLabel } = {})
     }
   }
 
-  function clear() { disposeChildren(); }
+  function clear() { disposeChildren(); redraw(); }
 
   function dispose() {
+    redraw();
     disposeChildren();
     unregisterCapture();
     if (attached) group.parent?.remove(group);

package/src/framework/selection/feature-highlight.js

@@ -61,8 +61,13 @@ export function createFeatureHighlight(viewer) {
     overlay.visible = true;
   }
 
+  // The overlay is edited in place, not through a viewer call, so it asks for
+  // the frame itself (the viewer draws on demand).
+  const redraw = () => viewer.requestRender?.();
+
   return {
     show(hit) {
+      redraw();
       if (!hit.feature) { mount(hit.mesh.geometry, hit.mesh); return; }
       const cached = subsets.get(hit.subPart);
       let byId = cached?.geo === hit.mesh.geometry ? cached.byId : null;
@@ -75,7 +80,7 @@ export function createFeatureHighlight(viewer) {
       if (!g) { g = featureSubset(hit.mesh.geometry, hit.feature.id); byId.set(hit.feature.id, g); }
       mount(g, hit.mesh);
     },
-    clear() { overlay.visible = false; },
+    clear() { overlay.visible = false; redraw(); },
     dispose() {
       // Every step isolated: a throw disposing one cached subset (or
       // unregistering from cutaway) must not skip the rest — same discipline

package/src/framework/viewer.js

@@ -232,6 +232,31 @@ export function createViewer(container, part) {
   const controls = new OrbitControls(activeCamera, renderer.domElement);
   controls.enableDamping = true;
 
+  // --- render on demand -------------------------------------------------------
+  // The loop ticks every animation frame (controls, tweens, frame listeners —
+  // playback, measure, the view cube all run there), but only DRAWS when
+  // something asked for it: a still view costs no GPU work. A frame is asked
+  // for by: any call through the returned viewer API (wrapped at the bottom of
+  // this function — a regen, a pose, a mode switch, a capture), the controls
+  // moving the camera (their damping included), a camera tween, input on the
+  // stage, and the internal async landings (a texture, a contact shadow, a
+  // resize, a marker timing out). Modules that edit the scene graph directly
+  // rather than through the API (measure's dims, the hover highlight, the
+  // animation driver) call viewer.requestRender() themselves.
+  //
+  // `graceMs` keeps drawing for a while after the request: input and API calls
+  // have follow-ups that land a frame or two later (hover.js picks in its own
+  // requestAnimationFrame; a regen's measure dims rebuild on the next tick).
+  const INPUT_GRACE_MS = 400;
+  const API_GRACE_MS = 150;
+  let renderRequested = true; // the first frame
+  let renderUntil = 0;
+  function requestRender(graceMs = 0) {
+    renderRequested = true;
+    if (graceMs > 0) renderUntil = Math.max(renderUntil, performance.now() + graceMs);
+  }
+  controls.addEventListener("change", () => requestRender());
+
   // --- lights + grid --------------------------------------------------------
   const liveLights = addViewerLights(scene);
   // 1 cm grid (mm units): 300 mm wide, 30 divisions -> 10 mm (1 cm) squares.
@@ -523,6 +548,7 @@ export function createViewer(container, part) {
     domElement: renderer.domElement,
     getBounds: getVisibleWorldBounds,
     edgeColor: THEME.dark.line,
+    requestRender: () => requestRender(),
   });
   for (const name of names) {
     cutaway.setSubpart(name, subMesh[name], subLines[name]);
@@ -589,7 +615,7 @@ export function createViewer(container, part) {
       const settled = new Promise((resolve) => { settle = resolve; });
       pendingTextures.add(settled);
       settled.then(() => pendingTextures.delete(settled));
-      t = textureLoader.load(assetUrl(file), () => settle(), undefined, () => settle());
+      t = textureLoader.load(assetUrl(file), () => { settle(); requestRender(); }, undefined, () => settle());
       t.anisotropy = Math.min(8, renderer.capabilities?.getMaxAnisotropy?.() ?? 1);
       textureCache.set(file, t);
     }
@@ -760,6 +786,7 @@ export function createViewer(container, part) {
     try {
       const plane = cutaway.getPlane?.(_shadowClipPlane) ?? null;
       realisticRig.shadow.render(scene, castersNow(), { ...opts, clippingPlanes: plane ? [plane] : null });
+      requestRender();
     } catch (e) {
       console.warn("partforge: contact shadow failed", e);
     }
@@ -796,6 +823,7 @@ export function createViewer(container, part) {
   // contact shadow: low-res while the plane is dragged, full once it settles —
   // the same schedule as a moving sub-part.
   cutaway.onChange?.(() => { if (realisticRig) shadowMovedAt = performance.now(); });
+  cutaway.onChange?.(() => requestRender());
 
   const livePixelRatio = (mode) =>
     Math.min(devicePixelRatio, mode === "realistic" && isCoarsePointer() ? 1.5 : 2);
@@ -1725,6 +1753,7 @@ export function createViewer(container, part) {
     lineMaterial.resolution.set(w, h); // fat lines need the viewport size for px width
     for (const m of fadeLineMats.values()) m.resolution.set(w, h); // clones need it too
     cutaway.setViewportSize(w, h, renderer.getPixelRatio());
+    requestRender(); // a resize clears the drawing buffer
   }
   const ro = new ResizeObserver(resize);
   ro.observe(container);
@@ -2254,11 +2283,12 @@ export function createViewer(container, part) {
   function renderFrame(time) {
     const dt = lastFrameTime == null ? 0 : Math.min(0.1, (time - lastFrameTime) / 1000);
     lastFrameTime = time;
-    controls.update();
+    controls.update(); // fires "change" (→ requestRender) while the camera moves, damping included
     const tw = camTween.update(dt);
     if (tw) {
       activeCamera.position.fromArray(tw.position);
       controls.target.fromArray(tw.target);
+      requestRender();
     }
     checkAutoProjection();
     // Per-listener guard, because three re-arms requestAnimationFrame only AFTER
@@ -2269,6 +2299,9 @@ export function createViewer(container, part) {
       try { cb(dt); } catch (e) { console.warn("partforge: frame listener failed", e); }
     }
     updateMovingShadow(); // after the listeners, so it sees this frame's poses
+    // Nothing asked for a frame: the canvas keeps showing the last one.
+    if (!renderRequested && performance.now() >= renderUntil) return;
+    renderRequested = false;
     // After the frame listeners, before anything reads the camera to draw with:
     // a playback frame may have moved sub-parts or the camera itself, and both
     // change where the planes belong.
@@ -2336,6 +2369,20 @@ export function createViewer(container, part) {
   // recoverable (three's own listener re-uploads on restore); the subscribers
   // let an embedder surface it instead of showing a dead rectangle.
   const contextLostListeners = new Set();
+  // Input on the stage: hover highlights, measure dims, cutaway gizmo hover and
+  // drag all react to it, some a frame or two later — draw through the grace.
+  const INPUT_EVENTS = ["pointermove", "pointerdown", "pointerup", "pointerleave", "pointercancel", "wheel"];
+  const onStageInput = () => requestRender(INPUT_GRACE_MS);
+  for (const type of INPUT_EVENTS) container.addEventListener(type, onStageInput, { capture: true, passive: true });
+  const onKeyInput = () => requestRender(INPUT_GRACE_MS);
+  window.addEventListener("keydown", onKeyInput, { capture: true, passive: true });
+  window.addEventListener("keyup", onKeyInput, { capture: true, passive: true });
+  // A restored context has re-uploaded everything but drawn nothing, and a
+  // returning tab may have had its drawing buffer discarded.
+  const onRedrawNeeded = () => requestRender();
+  renderer.domElement.addEventListener("webglcontextrestored", onRedrawNeeded);
+  document.addEventListener("visibilitychange", onRedrawNeeded);
+
   const onContextLostEvent = (event) => {
     event.preventDefault();
     for (const listener of [...contextLostListeners]) listener();
@@ -2453,6 +2500,7 @@ export function createViewer(container, part) {
   }
 
   function dropFlashDot(dot) {
+    requestRender();
     scene.remove(dot);
     dot.material.dispose(); // the geometry is shared and freed in dispose()
     flashDots.delete(dot);
@@ -2532,6 +2580,11 @@ export function createViewer(container, part) {
     // context left to lose, and a surviving listener would keep the embedder's
     // closure (and whatever it captured) alive.
     renderer.domElement.removeEventListener("webglcontextlost", onContextLostEvent);
+    for (const type of INPUT_EVENTS) container.removeEventListener(type, onStageInput, { capture: true });
+    window.removeEventListener("keydown", onKeyInput, { capture: true });
+    window.removeEventListener("keyup", onKeyInput, { capture: true });
+    renderer.domElement.removeEventListener("webglcontextrestored", onRedrawNeeded);
+    document.removeEventListener("visibilitychange", onRedrawNeeded);
     contextLostListeners.clear();
     controls.removeEventListener("start", onControlsStart);
     cameraStartListeners.clear();
@@ -2586,7 +2639,8 @@ export function createViewer(container, part) {
     renderer.domElement.remove();
   }
 
-  return {
+  return withRenderRequests({
+    requestRender,
     showAssembly,
     hideAssembly,
     setSubGeometry,
@@ -2666,5 +2720,25 @@ export function createViewer(container, part) {
     invalidatePrintFrames,
     whenRealisticReady,
     dispose,
-  };
+  }, () => requestRender(API_GRACE_MS));
+}
+
+// Every API method that can change what is drawn asks for a frame when called,
+// and again when a returned promise settles (a mode switch lands async). Pure
+// reads, subscriptions and hot per-frame queries are left unwrapped — a frame
+// listener polling getCutawayPlane() must not keep the loop drawing forever.
+// Getters (viewer.camera) and non-functions pass through untouched.
+const NO_RENDER_REQUEST = /^(get|is|has|on|__)|^(requestRender|projectPoint|subTriangles|cutawaySupported|cutawayEnabled|whenRealisticReady|dispose)$/;
+export function withRenderRequests(api, request) {
+  for (const [key, desc] of Object.entries(Object.getOwnPropertyDescriptors(api))) {
+    if (typeof desc.value !== "function" || NO_RENDER_REQUEST.test(key)) continue;
+    const fn = desc.value;
+    api[key] = function (...args) {
+      request();
+      const out = fn.apply(this, args);
+      if (out && typeof out.then === "function") out.then(request, request);
+      return out;
+    };
+  }
+  return api;
 }