partforge 0.153.0 → 0.154.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.153.0",
+  "version": "0.154.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/gltf/decode-preview.js

@@ -11,6 +11,16 @@
 // rotation; parenting the glTF root under the pivot would turn the part twice.
 // Undoing the root here hands the viewer geometry in the frame it already owns.
 //
+// Feature edges (encoder version 2): a sub-part's mesh may carry a second
+// primitive, mode LINES, holding the kernel's edge segments. GLTFLoader then
+// makes the node a Group of a Mesh and a LineSegments (the node's extras and
+// name on the Group, not the Mesh), so each surface and its lines are matched
+// through the glTF NODE they belong to. Lines go back to model frame through
+// the same matrix as the positions; a node with no line primitive — version 1,
+// or a sub-part whose edges were empty — decodes to an EMPTY Float32Array,
+// which the viewer reads as "no feature edges" (never undefined, which would
+// make it derive lines by angle).
+//
 // Rejects on anything that is not a decodable GLB; the callers (mount's
 // `preview`, mountPreview) decide what a failure means for them.
 import { Matrix3, Matrix4, Vector3 } from "three";
@@ -50,15 +60,50 @@ function metaOf(extras) {
   return Object.keys(out).length ? out : null;
 }
 
+// The object standing for a glTF node: the object itself when its node had one
+// primitive, else the Group GLTFLoader made for a multi-primitive mesh — the
+// one carrying the node's extras / name (a primitive's own Mesh has neither).
+function nodeObjectOf(obj) {
+  const own = obj.userData ?? {};
+  if ("partforgeSubPart" in own || "name" in own) return obj;
+  const parent = obj.parent;
+  return parent?.isGroup && parent.userData && ("partforgeSubPart" in parent.userData || "name" in parent.userData) ? parent : obj;
+}
+
+// Line segments as endpoint pairs in model frame (an indexed LINES primitive —
+// weld() indexes it — expanded back to pairs).
+function readSegments(geometry, matrix) {
+  const position = geometry.getAttribute("position");
+  if (!position || position.count === 0) return null;
+  const points = readVec3(position, matrix, false);
+  if (!geometry.index) return points;
+  const index = geometry.index.array;
+  const out = new Float32Array(index.length * 3);
+  for (let i = 0; i < index.length; i++) out.set(points.subarray(index[i] * 3, index[i] * 3 + 3), i * 3);
+  return out;
+}
+
 export async function decodePreviewGlb(bytes) {
   const data = toArrayBuffer(bytes);
   const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
   const gltf = await loader.parseAsync(data, "");
   gltf.scene.updateMatrixWorld(true);
   const meshes = [];
+  const edgesByNode = new Map(); // node object → model-frame segment arrays
+  const meshByNode = new Map(); // node object → its surface payload
   const toModel = new Matrix4();
   const normalMatrix = new Matrix3();
   gltf.scene.traverse((obj) => {
+    if (obj.isLineSegments) {
+      toModel.multiplyMatrices(Y_UP_TO_Z_UP, obj.matrixWorld);
+      const segments = readSegments(obj.geometry, toModel);
+      if (segments) {
+        const node = nodeObjectOf(obj);
+        edgesByNode.set(node, [...(edgesByNode.get(node) ?? []), segments]);
+      }
+      obj.geometry.dispose();
+      return;
+    }
     if (!obj.isMesh) return;
     const geometry = obj.geometry;
     const position = geometry.getAttribute("position");
@@ -67,19 +112,31 @@ export async function decodePreviewGlb(bytes) {
     normalMatrix.getNormalMatrix(toModel);
     const normal = geometry.getAttribute("normal");
     const indices = geometry.index ? Uint32Array.from(geometry.index.array) : null;
-    const { partforgeSubPart, partforgeDisplay, name: originalName } = obj.userData;
-    meshes.push({
+    const node = nodeObjectOf(obj);
+    const { partforgeSubPart, partforgeDisplay, name: originalName } = node.userData;
+    const payload = {
       // The writer's own record of the key, then the unsanitized glTF node name.
-      name: typeof partforgeSubPart === "string" ? partforgeSubPart : (originalName ?? obj.name),
+      name: typeof partforgeSubPart === "string" ? partforgeSubPart : (originalName ?? node.name),
       positions: readVec3(position, toModel, false),
       normals: normal ? readVec3(normal, normalMatrix, true) : null,
       indices,
       triangles: (indices ? indices.length : position.count) / 3,
-      edges: new Float32Array(0), // previews carry no feature edges (v1)
+      edges: new Float32Array(0), // filled below from the node's LINES primitive, if any
       display: partforgeDisplay && typeof partforgeDisplay === "object" ? partforgeDisplay : null,
-    });
+    };
+    meshes.push(payload);
+    if (!meshByNode.has(node)) meshByNode.set(node, payload);
     geometry.dispose();
   });
+  for (const [node, parts] of edgesByNode) {
+    const payload = meshByNode.get(node);
+    if (!payload) continue; // lines with no surface: nothing to draw them on
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const edges = new Float32Array(total);
+    let at = 0;
+    for (const p of parts) { edges.set(p, at); at += p.length; }
+    payload.edges = edges;
+  }
   const extras = gltf.userData ?? {};
   return {
     view: typeof extras.partforgeView === "string" ? extras.partforgeView : null,

package/src/framework/gltf/encode-preview.js

@@ -3,8 +3,15 @@
 // buildView all hold) as a small GLB a viewer can show before the kernel boots.
 //
 // The file, which a reader may rely on:
-//  - one node + mesh + primitive per sub-part, all three named by the sub-part
-//    key; POSITION + NORMAL (+ indices when the kernel sent them)
+//  - one node + mesh per sub-part, both named by the sub-part key; the mesh's
+//    FIRST primitive is the surface (TRIANGLES: POSITION + NORMAL, + indices
+//    when the kernel sent them); a sub-part with feature edges adds a SECOND
+//    primitive, mode LINES, POSITION only and no material — the kernel's edge
+//    segments in the same posed frame. A sub-part whose `edges` is empty or
+//    absent has no line primitive; a reader takes that as "no feature edges"
+//    (never "derive them"). Version-1 files have no line primitives at all.
+//    Both primitives share the mesh, so quantize() gives them ONE quantization
+//    volume and one node transform: the lines dequantize onto the faces.
 //  - every sub-part node under ONE root node, "partforge", rotated −90° about X:
 //    partforge models Z-up in millimetres and glTF is Y-up. Units stay mm — the
 //    file is for partforge's own viewer; metres would only matter for AR.
@@ -14,20 +21,20 @@
 //  - top-level extras { partforgeView, partforgeEncoder, partforgeMeta? }
 //  - weld() → quantize() → meshopt({ level: "medium" }): 5–8 bytes a triangle,
 //    the recipe measured in partforge-cloud's local_glb_benchmark.md
-// Not encoded (v1): feature edges, textures, patterns.
+// Not encoded: textures, patterns. (Feature edges since version 2.)
 //
 // Runs in Node, a page and a Web Worker: no three.js, no DOM, no Blob
 // (test/gltf-layering.test.js). Deterministic: the same input writes the same
 // bytes, and nothing here mutates the input (exportPreview passes the viewer's
 // live buffers). Bump PREVIEW_ENCODER_VERSION whenever the bytes for the same
 // input change — downstream caches key on it.
-import { Document, Logger, WebIO } from "@gltf-transform/core";
+import { Document, Logger, Primitive, WebIO } from "@gltf-transform/core";
 import { EXTMeshoptCompression, KHRMeshQuantization } from "@gltf-transform/extensions";
 import { meshopt, quantize, weld } from "@gltf-transform/functions";
 import { MeshoptEncoder } from "meshoptimizer/encoder";
 import { cadAppearance, DISPLAY_KEYS } from "../materials/resolve.js";
 
-export const PREVIEW_ENCODER_VERSION = 1;
+export const PREVIEW_ENCODER_VERSION = 2; // 2: feature edges as a LINES primitive
 
 // −90° about X as [x, y, z, w]: model (x, y, z) → glTF (x, z, −y), the viewer's pivot.
 const Z_UP_TO_Y_UP = [-Math.SQRT1_2, 0, 0, Math.SQRT1_2];
@@ -72,6 +79,13 @@ function checkMesh(m, seen) {
   if (m.normals != null && m.normals.length > 0 && m.normals.length !== m.positions.length) {
     throw new Error(`encodePreviewGlb: "${m.name}" normals do not match its positions`);
   }
+  // Any zero-length edges (typed or plain) mean "no feature edges": nothing to check.
+  if (m.edges != null && m.edges.length !== 0) {
+    if (!ArrayBuffer.isView(m.edges) && !Array.isArray(m.edges)) {
+      throw new TypeError(`encodePreviewGlb: "${m.name}" edges must be a typed array or an array of numbers`);
+    }
+    if (m.edges.length % 6 !== 0) throw new Error(`encodePreviewGlb: "${m.name}" edges are not whole segments`);
+  }
   if (indexed) {
     const vertexCount = m.positions.length / 3;
     for (let i = 0; i < m.indices.length; i++) {
@@ -126,9 +140,14 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
       .setMetallicFactor(look.metalness)
       .setRoughnessFactor(look.roughness)
       .setAlphaMode(look.opacity < 1 ? "BLEND" : "OPAQUE"));
+    const mesh = doc.createMesh(m.name).addPrimitive(prim);
+    if (m.edges?.length) {
+      mesh.addPrimitive(doc.createPrimitive().setMode(Primitive.Mode.LINES).setAttribute(
+        "POSITION", doc.createAccessor().setType("VEC3").setArray(Float32Array.from(m.edges)).setBuffer(buffer)));
+    }
     const extras = displayExtras(display);
     root.addChild(doc.createNode(m.name)
-      .setMesh(doc.createMesh(m.name).addPrimitive(prim))
+      .setMesh(mesh)
       .setExtras(extras ? { partforgeSubPart: m.name, partforgeDisplay: extras } : { partforgeSubPart: m.name }));
   }
   if (root.listChildren().length === 0) throw new Error("encodePreviewGlb: every mesh was empty");

package/src/framework/mount-preview.js

@@ -8,8 +8,9 @@
 // built once the GLB has decoded, from a synthetic part: one sub-part per glTF
 // mesh, carrying the `display` block the writer stored beside it, and the file's
 // background/environment meta. The CAD look is exact; realistic mode uses each
-// sub-part's display only — no sheet stock, no layer-line print frames (a v1
-// residual alongside "no edges"). The decoder loads on demand (it carries the
+// sub-part's display only — no sheet stock, no layer-line print frames (a
+// residual of the format). CAD feature edges come from the file (encoder
+// version 2); a version-1 file decodes with none. The decoder loads on demand (it carries the
 // GLTFLoader and meshopt), so a bundle that never mounts a preview never ships it.
 // Hence `ready`. Every handle method is safe before it resolves.
 import "./app.css";

package/src/framework/viewer.js

@@ -1741,9 +1741,12 @@ export function createViewer(container, part) {
     // draw none rather than falling back. Only a payload with NO edge data at
     // all (edges === undefined; no current backend does this) derives by angle.
     const lg = new LineSegmentsGeometry();
-    if (edges) lg.setPositions(edges); // edges is already a well-formed (possibly zero-length) Float32Array
-    else lg.fromEdgesGeometry(new THREE.EdgesGeometry(out, EDGE_ANGLE));
+    // The raw segment pairs drawn, kept for getSubMeshPayload (reading them back
+    // out of LineSegmentsGeometry's interleaved instance buffer is awkward).
+    const segments = edges ?? new THREE.EdgesGeometry(out, EDGE_ANGLE).getAttribute("position").array;
+    lg.setPositions(segments); // a well-formed (possibly zero-length) Float32Array
     out.userData.edges = lg;
+    out.userData.edgePositions = segments;
     return out;
   }
 
@@ -1790,7 +1793,9 @@ export function createViewer(container, part) {
   // The geometry drawn for one sub-part, as a fresh worker-style payload with its
   // fast-path pose (setSubPose) baked in — the posed mesh a headless buildView
   // would return. Copies: the caller (exportPreview → partforge/gltf) may keep or
-  // transfer them. null when nothing has been delivered under that name.
+  // transfer them. null when nothing has been delivered under that name. Its
+  // `edges` are the lines shown on screen: the kernel's segments, or — when the
+  // delivery carried no edge data at all — the angle-derived fallback lines.
   const _payloadV = new THREE.Vector3();
   const _payloadNormal = new THREE.Matrix3();
   function getSubMeshPayload(name) {
@@ -1811,10 +1816,17 @@ export function createViewer(container, part) {
         _payloadV.fromBufferAttribute(nor, i).applyMatrix3(_payloadNormal).normalize().toArray(normals, i * 3);
       }
     }
+    // Feature edges, posed by the same matrix (an empty array stays empty: "none").
+    const rawEdges = geo.userData.edgePositions ?? new Float32Array(0);
+    const edges = new Float32Array(rawEdges.length);
+    for (let i = 0; i < rawEdges.length; i += 3) {
+      _payloadV.fromArray(rawEdges, i).applyMatrix4(pose).toArray(edges, i);
+    }
     return {
       name,
       positions,
       normals,
+      edges,
       indices: geo.index ? Uint32Array.from(geo.index.array) : null,
       triangles: geo.userData.triangles ?? (geo.index ? geo.index.count : pos.count) / 3,
     };

package/types/gltf.d.ts

@@ -20,7 +20,11 @@ export interface PreviewMesh {
   /** Absent for a non-indexed soup (Manifold); OCCT sends indices. */
   indices?: Uint32Array | null;
   triangles?: number;
-  /** Ignored: feature edges are not encoded in this version. */
+  /**
+   * Feature-edge segments, endpoint pairs `[x0,y0,z0, x1,y1,z1, …]` in the same posed
+   * frame as `positions` (encoder version 2+). Written as a LINES primitive on the
+   * sub-part's mesh. Empty or absent writes none, and decodes as "no feature edges".
+   */
   edges?: Float32Array | null;
 }
 
@@ -33,7 +37,7 @@ export interface EncodePreviewInput {
   view?: string | null;
 }
 
-/** Bumped whenever the encoder writes different bytes for the same input. */
+/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges). */
 export const PREVIEW_ENCODER_VERSION: number;
 
 /** Encode one view's posed meshes as a welded, quantized, meshopt-compressed GLB (Y-up, millimetres). Deterministic. */