partforge 0.90.0 → 0.91.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.90.0",
+  "version": "0.91.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/cutaway.js

@@ -387,6 +387,14 @@ export function createCutaway({
     return !enabled || pointSurvivesPlane(plane, point);
   }
 
+  // The live clip plane, for a caller that has to reason about the CUT itself
+  // rather than test a point against it — clicking the cut face is the only one
+  // today. Null while disabled, and a copy either way, so no caller can hold a
+  // stale plane or move ours.
+  function getPlane(target = new THREE.Plane()) {
+    return enabled ? target.copy(plane) : null;
+  }
+
   function registerClippableMaterial(material) {
     if (disposed || !material) return () => {};
     let entry = auxiliaryMaterials.get(material);
@@ -521,6 +529,7 @@ export function createCutaway({
     setTheme,
     setViewportSize,
     isPointVisible,
+    getPlane,
     registerClippableMaterial,
     updateForCamera,
     renderOverlay,

package/src/framework/pick-flash.js

@@ -0,0 +1,44 @@
+// Sizing for the transient pick marker (viewer.flashPoint).
+//
+// The marker used to be a fixed 1.2 mm sphere — a constant WORLD size, so it
+// swelled to cover the very feature it was pointing at as soon as you zoomed
+// in, and shrank to nothing on a large part. Sizing it from the camera each
+// frame keeps it a constant handful of CSS pixels under both projections.
+import * as THREE from "three";
+
+export const FLASH_PIXEL_RADIUS = 5; // CSS px — a ~10px dot, the size it read as at default framing
+
+const MIN_RADIUS = 1e-6; // never a zero-scale matrix
+
+const _offset = new THREE.Vector3();
+const _forward = new THREE.Vector3();
+
+// World units spanned by one CSS pixel at `worldPoint`, for `camera`.
+//
+// Perspective: the frustum widens with view depth, so the answer is measured
+// along the view direction rather than as a straight distance to the camera —
+// an off-axis point is farther from the eye than it is deep, and would size a
+// fraction too large. Orthographic: depth does not enter into it at all; the
+// frustum height (as zoom leaves it) is the whole story.
+export function worldPerPixel(camera, worldPoint, viewportHeightPx) {
+  const height = viewportHeightPx > 0 ? viewportHeightPx : 1;
+  if (camera.isOrthographicCamera) {
+    const extent = Math.abs(camera.top - camera.bottom) / (camera.zoom || 1);
+    return extent / height;
+  }
+  camera.getWorldDirection(_forward);
+  const depth = Math.abs(_offset.copy(worldPoint).sub(camera.position).dot(_forward));
+  const fov = ((camera.fov ?? 50) * Math.PI) / 180;
+  return (2 * Math.tan(fov / 2) * depth) / height;
+}
+
+// Radius, in world units, for a marker that should read as `pixelRadius` CSS px.
+export function flashWorldRadius(
+  camera,
+  worldPoint,
+  viewportHeightPx,
+  pixelRadius = FLASH_PIXEL_RADIUS,
+) {
+  const radius = worldPerPixel(camera, worldPoint, viewportHeightPx) * pixelRadius;
+  return Number.isFinite(radius) && radius > MIN_RADIUS ? radius : MIN_RADIUS;
+}

package/src/framework/selection/format.js

@@ -10,13 +10,18 @@ const fmtParams = (p) => Object.entries(p).map(([k, v]) => `${k}:${v}`).join(","
 function tokenStyle(s) {
   const head = `@${s.subPart}`;
   const feat = s.feature ? ` · ${s.feature.label}` : "";
-  return `${head}${feat} · pt(${s.point.join(",")}) n(${fmtNormal(s.normal)}) · {${fmtParams(s.params)}}`;
+  const cut = s.onCutPlane ? " · section" : "";
+  return `${head}${feat}${cut} · pt(${s.point.join(",")}) n(${fmtNormal(s.normal)}) · {${fmtParams(s.params)}}`;
 }
 
 function promptStyle(s) {
   const params = Object.entries(s.params).map(([k, v]) => `${k}: ${v}`).join(", ");
   const feat = s.feature ? ` **${s.feature.label}**,` : "";
-  return `On sub-part **${s.subPart}**, the user pointed at${feat} local point (${s.point.join(", ")}), `
+  // The section wording is load-bearing: without it the point reads as a spot
+  // on the part's surface, when it is a spot inside the material that the
+  // cutaway happens to have opened up.
+  const cut = s.onCutPlane ? " the cutaway section face at" : "";
+  return `On sub-part **${s.subPart}**, the user pointed at${feat}${cut} local point (${s.point.join(", ")}), `
     + `normal ${fmtNormal(s.normal)}, with params {${params}}.`;
 }
 

package/src/framework/selection/pick.js

@@ -19,7 +19,9 @@ export function attachPicker(viewer, { part, getContext, onPick, suppressed }) {
     // a suppressed click must still clear its just-dragged flag.
     const wasDragged = drag.consumeClick();
     if (!active || wasDragged || suppressed?.()) return;
-    const hit = raycastViewer(viewer, ev.clientX, ev.clientY);
+    // includeSection: in a cutaway the flat cut face is the biggest thing on
+    // screen, and it is the one surface with no geometry behind it to hit.
+    const hit = raycastViewer(viewer, ev.clientX, ev.clientY, { includeSection: true });
     if (!hit) return;
     const selection = resolveSelection(part, getContext(), hit);
     viewer.flashPoint([hit.pointWorld.x, hit.pointWorld.y, hit.pointWorld.z]);

package/src/framework/selection/raycast.js

@@ -26,6 +26,18 @@ function normalInSubPartFrame(mesh, normal) {
   return [_normal.x, _normal.y, _normal.z];
 }
 
+const _inverseWorld = new THREE.Matrix4();
+
+// The same trip for a WORLD direction: back through the mesh's world transform
+// into the geometry frame, then forward by its local matrix like any other
+// geometry-frame direction. The cut plane's normal is the only one that arrives
+// this way — it belongs to the scene, not to a triangle.
+function worldNormalInSubPartFrame(mesh, worldNormal) {
+  _inverseWorld.copy(mesh.matrixWorld).invert();
+  _normal.copy(worldNormal).transformDirection(_inverseWorld).transformDirection(mesh.matrix);
+  return [_normal.x, _normal.y, _normal.z];
+}
+
 // The feature carried by a mesh triangle, or null (unlabeled / no attribution data).
 export function featureAt(mesh, triIndex) {
   const { featureIds, features } = mesh.geometry.userData;
@@ -33,7 +45,84 @@ export function featureAt(mesh, triIndex) {
   return id > 0 ? { id, label: features[id - 1] } : null;
 }
 
-export function raycastViewer(viewer, clientX, clientY) {
+const SECTION_EPSILON = 1e-6;
+const _sectionPoint = new THREE.Vector3();
+const _sectionNormal = new THREE.Vector3();
+const _reverseDirection = new THREE.Vector3();
+const _cutPlane = new THREE.Plane();
+
+// The cut FACE under the pointer, when a cutaway is showing one.
+//
+// Nothing real is there to hit: a section view removes the near half by
+// clipping, which the raycaster knows nothing about, so every triangle along
+// that ray is either on the discarded side (rejected by isWorldPointVisible) or
+// a back face three does not report at all. Clicking the largest surface in the
+// view therefore selected nothing.
+//
+// What IS there is solid material, sliced open at the plane. So: find where the
+// ray crosses into the retained half, and ask whether the sub-part is solid at
+// that crossing. It is solid when the ray has entered it more often than it has
+// left it — and the exits of a ray are the entries of the same ray reversed,
+// which is how this stays inside three's front-face raycasting rather than
+// flipping every material to DoubleSide behind the renderer's back.
+function sectionHit(viewer, meshes, forwardHits, surfaceHit) {
+  const plane = viewer.getCutawayPlane?.(_cutPlane);
+  if (!plane) return null;
+  const ray = raycaster.ray;
+  // Only a ray crossing INTO the retained half can reveal a cut face; if the
+  // camera is already on that side, nothing in front of it was removed.
+  if (plane.normal.dot(ray.direction) <= SECTION_EPSILON) return null;
+  const distance = ray.distanceToPlane(plane);
+  if (distance == null || distance <= 0) return null;
+  // A retained surface nearer than the crossing is simply in front of the cut.
+  if (surfaceHit && surfaceHit.distance <= distance) return null;
+  // Nothing entered before the plane can be solid at it, so the reverse
+  // raycast below is pure cost on the common miss — a click on the backdrop.
+  if (!forwardHits.some((hit) => hit.distance < distance)) return null;
+  ray.at(distance, _sectionPoint);
+
+  raycaster.set(_sectionPoint, _reverseDirection.copy(ray.direction).negate());
+  const exitHits = raycaster.intersectObjects(meshes, false);
+
+  let best = null;
+  for (const mesh of meshes) {
+    let net = 0;
+    let entry = null;
+    for (const hit of forwardHits) {
+      if (hit.object !== mesh || hit.distance >= distance) continue;
+      net += 1;
+      entry ??= hit; // hits arrive sorted, so this is the nearest entry
+    }
+    for (const hit of exitHits) {
+      if (hit.object === mesh && hit.distance < distance) net -= 1;
+    }
+    if (net > 0 && (best == null || entry.distance < best.entry.distance)) best = { mesh, entry };
+  }
+  if (!best) return null;
+
+  const { mesh, entry } = best;
+  return {
+    mesh,
+    subPart: mesh.name,
+    // The triangle the ray entered through. It is not the one under the
+    // pointer — a cut face has no triangles — but it is the material the cut
+    // opened, and callers that index by triangle need something real.
+    triIndex: entry.faceIndex,
+    pointWorld: _sectionPoint.clone(),
+    pointLocal: worldToSubPartLocal(mesh, _sectionPoint),
+    // The cut face looks back at the discarded half, opposite the plane normal.
+    normalLocal: worldNormalInSubPartFrame(mesh, _sectionNormal.copy(plane.normal).negate()),
+    // Deliberately unattributed: a cut face is an artefact of the section, not
+    // a surface the part's build ever labelled.
+    feature: null,
+    onCutPlane: true,
+  };
+}
+
+// `includeSection` opts into the cut-face pick above. It is off by default so
+// hover labels and measurement mode keep hitting real geometry only — a
+// dimension pinned to a plane the user can move is not a dimension.
+export function raycastViewer(viewer, clientX, clientY, { includeSection = false } = {}) {
   const rect = viewer.domElement.getBoundingClientRect();
   ndc.x = ((clientX - rect.left) / rect.width) * 2 - 1;
   ndc.y = -((clientY - rect.top) / rect.height) * 2 + 1;
@@ -43,6 +132,13 @@ export function raycastViewer(viewer, clientX, clientY) {
   const hit = hits.find((candidate) =>
     viewer.isWorldPointVisible?.(candidate.point) ?? true
   );
+  // Ordered before the surface answer, not after: the crossing into the
+  // retained half is nearer than anything retained, so when a cut face is
+  // there it is what the pointer is over.
+  if (includeSection) {
+    const section = sectionHit(viewer, meshes, hits, hit);
+    if (section) return section;
+  }
   if (!hit) return null;
   return {
     mesh: hit.object,

package/src/framework/selection/resolve.js

@@ -45,5 +45,9 @@ export function resolveSelection(part, ctx, hit) {
   // Feature attribution from the mesh payload (Solid.label() in the part's build) —
   // the same name the hover tooltip shows, so user, agent, and viewer share vocabulary.
   if (hit.feature) selection.feature = { label: hit.feature.label };
+  // A cutaway section pick: the point is inside the material, on the cut face,
+  // not on a surface the part was built with. Callers that describe the click
+  // in words need to say so — the coordinates alone read as a normal surface.
+  if (hit.onCutPlane) selection.onCutPlane = true;
   return selection;
 }

package/src/framework/viewer.js

@@ -5,6 +5,8 @@ import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { createCutaway } from "./cutaway.js";
+import { CUTAWAY_OVERLAY_RENDER_ORDER } from "./cutaway-render.js";
+import { flashWorldRadius } from "./pick-flash.js";
 import { createCameraTween } from "./camera-tween.js";
 import { orbitPose } from "./camera-orbit.js";
 import { orthoFrustum, perspectiveDistance } from "./projection.js";
@@ -1049,6 +1051,10 @@ export function createViewer(container, part) {
       try { cb(dt); } catch (e) { console.warn("partforge: frame listener failed", e); }
     }
     if (cutaway.isEnabled) cutaway.updateForCamera();
+    // Re-size the pick markers against the pose this frame will actually draw:
+    // a dot is only alive for about a second, but orbiting or zooming inside
+    // that second must not resize it.
+    for (const dot of flashDots) scaleFlashDot(dot);
     renderer.render(scene, activeCamera);
     cutaway.renderOverlay(renderer, activeCamera);
   }
@@ -1139,18 +1145,44 @@ export function createViewer(container, part) {
   function onCameraEnd(cb) { controls.addEventListener("end", cb); }
 
   // Transient marker at a world-space point — visual confirmation of a pick.
+  //
+  // Two things keep it visible where it used to disappear. It is ordered above
+  // every band the cutaway raises its surfaces, edges and outlines into (a
+  // section view moves them past 1,000,000, so the old fixed 999 was painted
+  // over by the very geometry the marker sat on — and `depthTest: false` means
+  // no depth is written either, so nothing behind it survives the overdraw).
+  // And it is `transparent`, which puts it in the pass three draws LAST: a
+  // translucent part puts the cutaway's caps in the transparent list, where an
+  // opaque marker is already behind whatever its render order.
+  //
+  // The sphere is a UNIT sphere scaled per frame (see below) so it reads as a
+  // constant handful of CSS pixels instead of a fixed millimetre size.
+  const FLASH_RENDER_ORDER = CUTAWAY_OVERLAY_RENDER_ORDER + 1;
   const flashTimers = new Set();
+  const flashDots = new Set();
+  const flashGeometry = new THREE.SphereGeometry(1, 16, 12);
+  const flashViewport = new THREE.Vector2();
+  function scaleFlashDot(dot) {
+    renderer.getSize(flashViewport); // CSS px, which is what a pixel radius means
+    dot.scale.setScalar(flashWorldRadius(activeCamera, dot.position, flashViewport.y));
+  }
   function flashPoint(world) {
     const dot = new THREE.Mesh(
-      new THREE.SphereGeometry(1.2, 16, 12),
-      new THREE.MeshBasicMaterial({ color: 0xffcc33, depthTest: false })
+      flashGeometry,
+      new THREE.MeshBasicMaterial({
+        color: 0xffcc33, depthTest: false, depthWrite: false, transparent: true,
+      })
     );
-    dot.renderOrder = 999;
+    dot.renderOrder = FLASH_RENDER_ORDER;
     dot.position.set(world[0], world[1], world[2]);
+    scaleFlashDot(dot); // sized before its first frame, not one frame late
     scene.add(dot);
+    flashDots.add(dot);
     const t = setTimeout(() => {
       flashTimers.delete(t);
-      scene.remove(dot); dot.geometry.dispose(); dot.material.dispose();
+      flashDots.delete(dot);
+      // The geometry is shared by every dot and freed in dispose(), not here.
+      scene.remove(dot); dot.material.dispose();
     }, 1200);
     flashTimers.add(t);
   }
@@ -1179,6 +1211,11 @@ export function createViewer(container, part) {
     controls.dispose();
     for (const t of flashTimers) clearTimeout(t);
     flashTimers.clear();
+    // A dot whose timer was just cancelled still holds its own material; the
+    // sphere geometry is shared across all of them and freed once.
+    for (const dot of flashDots) { scene.remove(dot); dot.material.dispose(); }
+    flashDots.clear();
+    flashGeometry.dispose();
     cutaway.dispose();
     for (const n of names) {
       const g = subCache[n];
@@ -1253,6 +1290,7 @@ export function createViewer(container, part) {
     flipCutaway: cutaway.flip,
     resetCutaway: cutaway.reset,
     isWorldPointVisible: cutaway.isPointVisible,
+    getCutawayPlane: cutaway.getPlane,
     registerCutawayMaterial: cutaway.registerClippableMaterial,
     registerCanonicalCaptureHidden,
     onCutawayHandleHover: cutaway.onHandleHoverChange,

package/types/index.d.ts

@@ -28,6 +28,12 @@ export interface Selection {
   params: Record<string, ParamValue>;
   /** Present when the hit surface carries a `Solid.label()` name. */
   feature?: { label: string };
+  /**
+   * Present when the click landed on a cutaway's cut face. The point is inside
+   * the material rather than on a surface the part was built with, and the
+   * normal faces the half the section removed.
+   */
+  onCutPlane?: true;
 }
 
 export interface PickEvent {