partforge 0.163.0 → 0.163.1

package/docs/ERROR-PATTERNS.md

@@ -877,6 +877,12 @@ between the Manifold preview and the OCCT STEP export.
 - **Cause:** Peak WASM memory during the preview build exceeded what the phone allows a page (roughly 1–1.5 GB on iOS; a desktop tolerates several GB). The usual shape is hundreds of repeated small features unioned into one body: before partforge 0.116 every sphere was 6,728 triangles regardless of radius (the flat 116-segment preview count, squared), so a body with ~250 rivet spheres carried 1.7 M triangles of rivets into its booleans — measured 10 s and a 2.7 GB peak on a desktop for a 400k-triangle sub-part, against 4 s and 500 MB with the rivets as 12-triangle boxes. A boolean chain whose intermediates dwarf the result (a full-body skin intersected per groove) is the other shape.
 - **Fix:** Update partforge (0.116 sizes spheres by chord tolerance: that body builds in ~550 MB and 120k triangles unchanged; 0.117 extends the rule to lathe profile arcs — `torus`, `roundedCylinder`, revolved rounded profiles — and `roundedBox` corners, the other two shapes that spend the count squared). Then keep the preview build's peak down the same ways the export needs: build repeated detail as one union of instances rather than a chain of per-feature booleans, cut grooves from a thin local skin rather than the whole envelope, and drop feature counts the print cannot show ([Preview vs print quality](AUTHORING-PARTS.md#conventions--gotchas)). `partforge measure` reports triangle counts per sub-part; a single preview sub-part past ~200k triangles, or a whole view past ~400k, is the range where phones start to fail.
 
+## kernel-internal-error
+
+- **Symptom:** `the geometry kernel raised an internal error it could not describe` — from a build or a STEP import, naming the operation when known (`during STEP import of "frame" (17.1 MB)`) and, when the kernel's own heap could say, the C++ exception type (`C++ exception StdFail_NotDone`, `Standard_ConstructionError`, `std::bad_alloc`, …) and the heap size. Before partforge 0.163.1 the same failure was a bare number (`{"ok":false,"error":"154591824"}`), different on every attempt.
+- **Cause:** The OCCT kernel is a WASM build compiled without C++ exception catching, so an exception nothing inside it catches — the STEP reader's transfer refusing an entity, a construction with a zero-length direction, an allocation the heap could not grow for — reaches JavaScript as the exception's ADDRESS. The number is not a code and means nothing across runs. partforge now names the operation and reads the exception's type off the heap, but it cannot read OCCT's own message for it.
+- **Fix:** Act on the type. `std::bad_alloc` or `Standard_OutOfMemory` (the message then says "probably too large for the in-browser kernel") is memory: a STEP import needs roughly six times its file size of kernel heap (measured on OCCT-written files: 17 MB → 100 MiB, 42 MB → 248 MiB), so a file that exhausts the 2 GB wasm32 ceiling is hundreds of megabytes, or the browser refused to grow the heap — simplify the imported model or split it. Any other type on an import is the file itself: re-export it from the CAD tool as AP214/AP242 solids (no assembly-only or surface-only exports) and try the smaller file; the same type from a build is that operation refusing its input (a `Standard_ConstructionError` is usually a zero-length direction or a degenerate profile). Retrying the identical build fails the same way — it is not transient.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.163.0",
+  "version": "0.163.1",
   "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/geometry/occt-backend.js

@@ -27,6 +27,7 @@ import { makeProfileWarner } from "./profile-warnings.js";
 import { createOcctRepair } from "./occt-repair.js";
 import { occtRoundAll } from "./occt-roundall.js";
 import { classifyFaceGroups } from "./feature-attribution.js";
+import { emscriptenThrowEvidence, labelImportFailure } from "../kernel-error.js";
 import { resolveLoftRings, loftRingsKey } from "./loft-rings.js";
 import { resolveSweepStations } from "./sweep.js";
 import { normalizeProfile } from "./profile.js";
@@ -199,6 +200,7 @@ export function createOcctKernel(replicad) {
   // registers pre-build via `_registerImport` (kernel-lifetime, untracked by the
   // solid cache: imports are the framework's own memo, keyed by name+digest).
   const imports = new Map();
+  const throwEvidence = (value) => emscriptenThrowEvidence(replicad.getOC?.(), value);
   // name -> { digest, width, height, data } — depth-map grids the framework
   // registers pre-build via `_registerImage` (ensureImages). Kernel-lifetime like
   // `imports` above, and plain data rather than OCCT objects, so there is nothing
@@ -815,11 +817,22 @@ export function createOcctKernel(replicad) {
       const prev = imports.get(name);
       if (!prev?.error && prev?.digest === digest) return; // error entries are always upgradable
       if (error) { imports.set(name, { error, digest }); return; }
-      imports.set(name, { shape: await importSTEP(new Blob([step])), digest });
+      // A STEP the reader refuses, or an OCCT exception out of its transfer,
+      // leaves here labelled with the import's name and size. The latter
+      // reaches JavaScript as a bare number from this exception-less build
+      // (kernel-error.js), and the heap is read for its C++ type BEFORE
+      // anything else runs on the kernel.
+      let shape;
+      try { shape = await importSTEP(new Blob([step])); }
+      catch (e) { throw labelImportFailure({ name, bytes: step?.byteLength, error: e, evidence: throwEvidence(e) }); }
+      imports.set(name, { shape, digest });
     },
     // Registration memo: undefined for an error entry, so a later registration with
     // the same digest can upgrade it rather than being treated as a no-op repeat.
     _importDigest: (name) => { const e = imports.get(name); return e?.error ? undefined : e?.digest; },
+    // What the kernel's heap can say about a value OCCT threw (kernel-error.js):
+    // the job loop asks this when a build throws something that is not an Error.
+    _throwEvidence: throwEvidence,
     // Depth-map grids, registered pre-build by the framework via `_registerImage`
     // (ensureImages). Unlike imports there is no per-format error entry: every
     // backend can consume a normalized grid, so registration never fails.

package/src/framework/jobs.js

@@ -10,6 +10,7 @@ import { fontsFor, resolveFonts, forgetFontSource } from "./fonts.js";
 import { normalizeOpentype, parseFont } from "./geometry/opentype-interop.js";
 import { imageControlAllows, imageSourceAllowed, isNoImageSource } from "./image-source.js";
 import { imagesFor, ensureImages } from "./images.js";
+import { describeKernelThrow } from "./kernel-error.js";
 import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
 import { vectorControlAllows, vectorSourceAllowed, isNoVectorSource } from "./vector-source.js";
@@ -651,7 +652,12 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     } else if (opts.jobs && Object.hasOwn(opts.jobs, msg.type)) {
       await opts.jobs[msg.type](kernel, part, msg, post, { isStale: opts.isStale });
     }
-  } catch (err) {
+  } catch (thrown) {
+    // A kernel compiled without exception catching throws a bare NUMBER for an
+    // uncaught C++ exception; describeKernelThrow turns that into a readable
+    // Error (with the C++ type when the kernel's heap can say) and returns a
+    // real Error untouched, `code` included.
+    const err = describeKernelThrow(thrown, { evidence: kernel._throwEvidence?.(thrown) });
     // `subparts` (generate jobs only) tells the reroute policy which sub-parts the
     // failed job covered, so only those latch to OCCT — not the whole part.
     if (err?.code === "NEEDS_IMPORT_MESH") post({ type: "needs-import-mesh", jobId: msg.jobId, subparts: msg.subparts });

package/src/framework/kernel-error.js

@@ -0,0 +1,161 @@
+// What to say when the geometry kernel throws something that is not an Error.
+//
+// replicad-opencascadejs's `replicad_single` build (the OCCT kernel worker.js
+// loads) is compiled WITHOUT C++ exception catching. An exception OCCT throws
+// that nothing inside the WASM catches — a Standard_Failure out of the STEP
+// reader, a std::bad_alloc when the heap cannot grow — leaves the module through
+// Emscripten's `___cxa_throw`, whose last line is `throw ptr`: JavaScript
+// receives the exception's ADDRESS, a bare number such as 154591824, different
+// on every run. Stringified as-is, that number was the whole error message a
+// part author (and partforge-cloud's agent, which read it as the part's fault
+// and retried blindly — cloud feedback #208) got for a failed build.
+//
+// This module is the ONE place such a value becomes a readable Error, used by
+// both the job loop's error post (jobs.js, worker.js) and the STEP import path
+// (occt-backend.js). It never invents a cause: the message says the kernel
+// raised an internal error it could not describe, names the operation when the
+// caller knows it, and adds only what the kernel's own heap can prove —
+// `emscriptenThrowEvidence` reads the thrown exception's C++ type name off the
+// heap through the Itanium ABI layout Emscripten's `ExceptionInfo` uses, and
+// says "too large for the in-browser kernel" only when that type IS an
+// out-of-memory type, or the heap has reached the wasm32 ceiling. Anything the
+// read cannot validate is dropped rather than guessed.
+
+// A thrown value the caller cannot read: a number (the Emscripten case above), or
+// an object with no non-empty string message (a bare WebAssembly.Exception, a
+// plain object). A real Error — anything with a message — is never opaque.
+export function isOpaqueThrow(err) {
+  if (typeof err === "number") return true;
+  if (err == null) return true;
+  if (typeof err === "string") return err.trim() === "";
+  return !(typeof err.message === "string" && err.message.trim() !== "");
+}
+
+// Emscripten's ExceptionInfo (replicad-opencascadejs 0.23): the thrown pointer
+// is the exception OBJECT; a 24-byte header sits before it, with the
+// std::type_info pointer at header + 4. A std::type_info (libc++abi, wasm32)
+// is { vtable*, const char* __type_name }, so the mangled class name is the
+// C string at *(typeInfo + 4). test/kernel-error-occt.test.js holds this
+// layout against the installed glue: a replicad-opencascadejs bump that moves
+// it fails there, and until it is re-pinned the read simply yields no type
+// name (a wrong read almost never parses as a mangled name — see below).
+const EXCEPTION_HEADER_BYTES = 24;
+const TYPE_OFFSET_IN_HEADER = 4;
+const NAME_OFFSET_IN_TYPE_INFO = 4;
+const MAX_MANGLED_NAME = 128;
+
+// getHeapMax() in the replicad_single glue: the wasm32 build's memory ceiling.
+export const WASM32_HEAP_CEILING_BYTES = 2 ** 31;
+// At or past this share of the ceiling, a throw with no readable type is still
+// called out of memory: nothing else grows a heap to the top of its range.
+const HEAP_CEILING_SHARE = 0.9;
+
+// C++ exception types that mean the kernel could not get memory.
+const OUT_OF_MEMORY_TYPES = new Set(["std::bad_alloc", "std::bad_array_new_length", "Standard_OutOfMemory"]);
+
+// Itanium-mangled class name → readable, for the shapes exception types take:
+// `St9bad_alloc` (std::bad_alloc), `16Standard_Failure`, `N3foo3BarE`
+// (foo::Bar). Every length prefix must match its identifier exactly and the
+// string must be consumed whole, which is what makes a misread (a pointer that
+// landed on arbitrary heap bytes) come back null instead of as a "type".
+export function demangleClassName(mangled) {
+  if (typeof mangled !== "string" || !/^[A-Za-z0-9_]{1,128}$/.test(mangled)) return null;
+  let i = 0;
+  const nested = mangled[0] === "N";
+  if (nested) i++;
+  const parts = [];
+  if (mangled.startsWith("St", i)) { parts.push("std"); i += 2; }
+  while (i < mangled.length && /[0-9]/.test(mangled[i])) {
+    let j = i;
+    while (j < mangled.length && /[0-9]/.test(mangled[j])) j++;
+    const len = Number(mangled.slice(i, j));
+    if (len < 1 || j + len > mangled.length) return null;
+    const ident = mangled.slice(j, j + len);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) return null;
+    parts.push(ident);
+    i = j + len;
+  }
+  if (nested ? mangled.slice(i) !== "E" : i !== mangled.length) return null;
+  if (parts.length === 0 || (parts.length === 1 && parts[0] === "std")) return null;
+  return parts.join("::");
+}
+
+function readCString(u8, ptr, cap) {
+  if (!Number.isInteger(ptr) || ptr <= 0 || ptr >= u8.length) return null;
+  let s = "";
+  for (let i = 0; i < cap && ptr + i < u8.length; i++) {
+    const c = u8[ptr + i];
+    if (c === 0) return s;
+    s += String.fromCharCode(c);
+  }
+  return null; // ran past the cap or the heap without a terminator
+}
+
+// What the kernel's heap can say about a thrown value: `{ heapBytes, typeName? }`.
+// `module` is the Emscripten module object (what `opencascade()` resolved to,
+// `replicad.getOC()`); the HEAP views are re-read from it on every call because
+// the glue replaces them whenever the memory grows. Returns `{}` for a module
+// without heap views, and never throws.
+export function emscriptenThrowEvidence(module, value) {
+  const evidence = {};
+  const u8 = module?.HEAPU8;
+  const u32 = module?.HEAPU32;
+  if (!(u8 instanceof Uint8Array) || !(u32 instanceof Uint32Array)) return evidence;
+  evidence.heapBytes = u8.length;
+  if (!Number.isInteger(value) || value <= EXCEPTION_HEADER_BYTES || value >= u8.length) return evidence;
+  const typeInfo = u32[(value - EXCEPTION_HEADER_BYTES + TYPE_OFFSET_IN_HEADER) >> 2];
+  if (!(typeInfo > 0 && typeInfo + NAME_OFFSET_IN_TYPE_INFO + 4 <= u8.length)) return evidence;
+  const namePtr = u32[(typeInfo + NAME_OFFSET_IN_TYPE_INFO) >> 2];
+  const typeName = demangleClassName(readCString(u8, namePtr, MAX_MANGLED_NAME));
+  if (typeName) evidence.typeName = typeName;
+  return evidence;
+}
+
+export function formatBytes(n) {
+  if (!Number.isFinite(n) || n < 0) return "unknown size";
+  if (n < 1e6) return `${Math.max(1, Math.round(n / 1e3))} KB`;
+  return `${(n / 1e6).toFixed(1)} MB`;
+}
+
+const describeRaw = (err) => {
+  if (typeof err === "number") return `the kernel reported only an exception address, ${err}`;
+  const ctor = err?.constructor?.name;
+  return `the kernel reported only an opaque ${ctor && ctor !== "Object" ? ctor : "value"}`;
+};
+
+// Turn a thrown value into an Error. A real Error (anything with a message) is
+// returned AS IS — same object, nothing rewritten — so a caller can branch on
+// its `code` exactly as before. `operation` names what was running ("STEP
+// import of "frame" (17.1 MB)"); `subject` is what the memory clause blames
+// ("the file" for an import, "the part" otherwise); `evidence` is
+// `emscriptenThrowEvidence`'s answer, or nothing.
+export function describeKernelThrow(err, { operation, subject = "the part", evidence = {} } = {}) {
+  if (!isOpaqueThrow(err)) return err;
+  const { typeName, heapBytes } = evidence ?? {};
+  let message = "the geometry kernel raised an internal error it could not describe";
+  if (operation) message += ` during ${operation}`;
+  const detail = [];
+  if (typeName) detail.push(`C++ exception ${typeName}`);
+  if (Number.isFinite(heapBytes)) detail.push(`kernel heap ${formatBytes(heapBytes)}`);
+  message += detail.length ? ` (${detail.join(", ")})` : ` (${describeRaw(err)})`;
+  const outOfMemory = typeName
+    ? OUT_OF_MEMORY_TYPES.has(typeName)
+    : Number.isFinite(heapBytes) && heapBytes >= WASM32_HEAP_CEILING_BYTES * HEAP_CEILING_SHARE;
+  if (outOfMemory) {
+    message += ` — the kernel ran out of memory, so ${subject} is probably too large for the in-browser kernel; retrying without reducing it will fail the same way`;
+  }
+  const out = new Error(message, { cause: err });
+  if (typeName) out.kernelExceptionType = typeName;
+  return out;
+}
+
+// The STEP import path's wrapper: whatever `importSTEP` threw, labelled with the
+// import's name and size. An opaque throw takes `describeKernelThrow` with the
+// import as its operation; a real Error (replicad's "Failed to load STEP file",
+// its "This shape has not type, it is null" for a file the reader parsed but
+// could not transfer) keeps its text behind the same label, `cause` attached.
+export function labelImportFailure({ name, bytes, error, evidence }) {
+  const operation = `STEP import of "${name}" (${formatBytes(bytes)})`;
+  if (isOpaqueThrow(error)) return describeKernelThrow(error, { operation, subject: "the file", evidence });
+  return new Error(`${operation} failed: ${error.message}`, { cause: error });
+}

package/src/framework/worker.js

@@ -15,6 +15,7 @@ import { handle } from "./jobs.js";
 export { coreStatus, onCoreFallback, CORE_FALLBACK_REASONS } from "./core/core-status.js";
 import { lintPart } from "../lint.js";
 import { cachedVectorDocs } from "./vectors.js";
+import { describeKernelThrow } from "./kernel-error.js";
 
 async function manifoldKernels() {
   const [{ default: Module }, { createManifoldKernel }] = await Promise.all([
@@ -109,10 +110,11 @@ export function runWorker(part, opts = {}) {
         // escaping rejection would kill the pump: this job AND everything queued behind
         // it would be dropped with no reply at all, leaving the host waiting on a message
         // that never comes until its own timeout fires.
+        let kernel = null;
         try {
           // A generate superseded while it sat in the queue never builds at all.
           if (job.epoch !== null && job.epoch !== epoch) continue;
-          const kernel = await kernelFor(job.data);
+          kernel = await kernelFor(job.data);
           // handle() declares each message's transferables (the big binary buffers).
           const post = (m, transfer = []) => postMessage(m, transfer);
           if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes, jobs: opts.jobs }); continue; }
@@ -125,11 +127,14 @@ export function runWorker(part, opts = {}) {
           const gated = (m, transfer = []) =>
             (m.type === "meshes" && isStale() ? post({ type: "superseded" }) : post(m, transfer));
           await handle(kernel, job.part, job.data, gated, { isStale, importMeshes, jobs: opts.jobs });
-        } catch (err) {
+        } catch (thrown) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.
           // Carry the job's jobId when it has one (capture/export are correlated by it):
           // a boot failure hitting kernelFor here must reach the right controller, or a
           // correlated caller (captureView, exportParts) would hang instead of settling.
+          // A bare number (an uncaught C++ exception out of the kernel) is given
+          // words here too, exactly as jobs.js does for a build.
+          const err = describeKernelThrow(thrown, { evidence: kernel?._throwEvidence?.(thrown) });
           const jobId = job.data?.jobId;
           postMessage({ type: "error", message: String(err?.message || err), ...(jobId != null ? { jobId } : {}) });
         }