partforge 0.145.0 → 0.145.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.145.0",
+  "version": "0.145.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/core/bvh-core.js

@@ -47,8 +47,8 @@ export function buildCoreBVH(c, verts, makeJsIndex) {
     if (c.poisoned) return fallback();
     try {
       return fn();
-    } catch {
-      poisonCore(c);
+    } catch (err) {
+      poisonCore(c, err);
       return fallback();
     }
   };

package/src/framework/core/core-status.js

@@ -0,0 +1,56 @@
+// Where this realm's native core stands, and who wants to hear about it — kept
+// apart from core.js so a host can import it (partforge/worker re-exports it)
+// without pulling in the WebAssembly bytes. core.js records into it.
+//
+// Falling back to the JS is silent to the user (the answers are identical) but
+// must not be silent to the host: onCoreFallback(listener) is told — once — when
+// the core becomes unavailable or faults, with a fixed reason and nothing else,
+// so it can go straight into a host's telemetry.
+
+// Every reason a fallback can carry. A fixed vocabulary on purpose: hosts record
+// it, and an error message could carry anything.
+export const CORE_FALLBACK_REASONS = Object.freeze(["no_webassembly", "boot_failed", "out_of_memory", "trap", "error"]);
+
+let fallback = null; // { state: "unavailable" | "faulted", reason } once it happened
+let refused = 0;     // meshes the core declined (malformed MeshGL) — the JS took them
+let probe = () => "idle"; // core.js installs the live answer when it loads
+const listeners = new Set();
+
+export function setStateProbe(fn) { probe = fn; }
+
+export function recordFallback(state, reason) {
+  if (fallback) return; // the first cause is the one worth knowing
+  fallback = { state, reason };
+  for (const fn of listeners) {
+    try { fn({ ...fallback }); } catch { /* a host listener must never break a build */ }
+  }
+}
+
+// A pass sent a mesh to the JS because the core declined it (not a fault).
+export function countRefusedMesh() { refused++; }
+
+// Where this realm's core stands:
+//   state: "idle" (not needed yet) | "on" | "off" (switched off) |
+//          "unavailable" (could not start) | "faulted" (stopped after a fault)
+//   reason: one of CORE_FALLBACK_REASONS for unavailable/faulted, else null
+//   refusedMeshes: how many meshes went to the JS because the core declined them
+export function coreStatus() {
+  return { state: fallback?.state ?? probe(), reason: fallback?.reason ?? null, refusedMeshes: refused };
+}
+
+// Call `listener({ state, reason })` once when the core becomes unavailable or
+// faults — immediately if it already has. Returns an unsubscribe function.
+export function onCoreFallback(listener) {
+  if (fallback) {
+    try { listener({ ...fallback }); } catch { /* see recordFallback */ }
+  }
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+// Tests only (via core.js's setCoreForTesting): forget everything recorded.
+export function resetCoreStatus() {
+  fallback = null;
+  refused = 0;
+  listeners.clear();
+}

package/src/framework/core/core.js

@@ -25,7 +25,16 @@
 // WebAssembly memory only ever grows, an instance whose memory passed
 // RECYCLE_BYTES is dropped once nothing holds it (releaseIfIdle); the next pass
 // boots a fresh one in a few milliseconds and the old memory goes to the GC.
+//
+// Falling back is silent to the user (the answers are identical) but must not be
+// silent to the host: coreStatus() says where this realm stands, and
+// onCoreFallback(listener) is told — once — when the core becomes unavailable or
+// faults, with a fixed reason (CORE_FALLBACK_REASONS) and nothing else, so a host
+// can count fallbacks in its own telemetry.
 import { CORE_WASM_BASE64 } from "./core-wasm.js";
+import { recordFallback, resetCoreStatus, setStateProbe } from "./core-status.js";
+
+export { CORE_FALLBACK_REASONS, coreStatus, countRefusedMesh, onCoreFallback } from "./core-status.js";
 
 // What the core may keep holding between passes. Ordinary forges never grow it
 // past its 16 MB start; a preview mesh needs ~145 bytes/triangle at the peak
@@ -35,6 +44,16 @@ export const RECYCLE_BYTES = 64 * 1024 * 1024;
 
 let enabled = true;
 let booted; // undefined: not tried yet (or recycled); null: unavailable or poisoned
+const OUT_OF_MEMORY = "partforge core: out of WebAssembly memory";
+
+function reasonOf(err) {
+  if (err?.message === OUT_OF_MEMORY) return "out_of_memory";
+  if (typeof WebAssembly === "object" && err instanceof WebAssembly.RuntimeError) return "trap";
+  return "error";
+}
+
+// The live answer for coreStatus() (core-status.js) while nothing has failed.
+setStateProbe(() => (!enabled || flagOff() ? "off" : booted ? "on" : "idle"));
 
 export function setCoreEnabled(on) { enabled = !!on; }
 
@@ -49,9 +68,11 @@ export function core() {
 
 // The instance `c` faulted (a trap, or an allocation that failed): never use it
 // again in this realm. Objects still holding it check `c.poisoned` and fall back.
-export function poisonCore(c) {
+// `err` is what was thrown; only its category is kept (reasonOf).
+export function poisonCore(c, err) {
   if (c) c.poisoned = true;
   if (booted === c || c == null) booted = null;
+  recordFallback("faulted", reasonOf(err));
 }
 
 // Drop `c` if its memory grew past RECYCLE_BYTES and nothing holds it (no live
@@ -60,8 +81,12 @@ export function releaseIfIdle(c) {
   if (booted === c && c.live === 0 && c.x.memory.buffer.byteLength > RECYCLE_BYTES) booted = undefined;
 }
 
-// Tests only: install a stand-in instance (or undefined to re-boot).
-export function setCoreForTesting(c) { booted = c; }
+// Tests only: install a stand-in instance (or undefined to re-boot), and forget
+// any recorded fallback, refusal count and listeners.
+export function setCoreForTesting(c) {
+  booted = c;
+  resetCoreStatus();
+}
 
 const B64 = (() => {
   const t = new Uint8Array(128);
@@ -86,7 +111,10 @@ function decodeBase64(s) {
 }
 
 function boot() {
-  if (typeof WebAssembly !== "object") return null;
+  if (typeof WebAssembly !== "object") {
+    recordFallback("unavailable", "no_webassembly");
+    return null;
+  }
   try {
     const stub = () => 0;
     // Synchronous on purpose: a pass asks mid-build and must get an answer now.
@@ -108,7 +136,7 @@ function boot() {
       // nothing is ever written over the module's low memory.
       alloc(bytes) {
         const ptr = x.malloc(bytes || 1);
-        if (!ptr) throw new Error("partforge core: out of WebAssembly memory");
+        if (!ptr) throw new Error(OUT_OF_MEMORY);
         return ptr;
       },
       // Views are rebuilt per use: any call that grows memory detaches the old buffer.
@@ -122,6 +150,7 @@ function boot() {
       copyOut: (Ctor, ptr, len) => (ptr && len ? new Ctor(x.memory.buffer, ptr, len).slice() : new Ctor(0)),
     };
   } catch {
+    recordFallback("unavailable", "boot_failed");
     return null;
   }
 }

package/src/framework/geometry/creased-normals.js

@@ -19,7 +19,7 @@
 import { SMOOTH, COPLANAR_ANGLE, MIN_EDGE, MIN_FACE, cosDeg } from "./shading-policy.js";
 import { affineAt, IDENTITY, runEvaluator } from "./blend-surfaces.js";
 import { hypot3 } from "./js-math.js";
-import { core, poisonCore } from "../core/core.js";
+import { core, countRefusedMesh, poisonCore } from "../core/core.js";
 import { coreAccepts, creasedNormalsCore } from "../core/creased-normals-core.js";
 
 const COPLANAR_COS = cosDeg(COPLANAR_ANGLE);
@@ -43,12 +43,16 @@ const SHADE_SLIVER = 1e-3;
 // poisons that instance and this mesh, and every one after, runs the JS.
 export function creasedNormals(g, opts) {
   const c = core();
-  if (c && coreAccepts(g)) {
-    try {
-      const out = creasedNormalsCore(c, g, opts);
-      if (out) return out;
-    } catch {
-      poisonCore(c);
+  if (c) {
+    if (!coreAccepts(g)) countRefusedMesh();
+    else {
+      try {
+        const out = creasedNormalsCore(c, g, opts);
+        if (out) return out;
+        countRefusedMesh();
+      } catch (err) {
+        poisonCore(c, err);
+      }
     }
   }
   return creasedNormalsJS(g, opts);

package/src/framework/oracle/bvh.js

@@ -316,8 +316,8 @@ function indexFor(mesh, allowCore) {
   if (c) {
     try {
       return buildCoreBVH(c, triangleVertices(mesh), () => buildBVH(mesh));
-    } catch {
-      poisonCore(c); // a fault while building: this realm's core is done; JS from here
+    } catch (err) {
+      poisonCore(c, err); // a fault while building: this realm's core is done; JS from here
     }
   }
   return buildBVH(mesh);

package/src/framework/worker.js

@@ -9,6 +9,10 @@
 // guarantees about epochs, cache sweeps, and the re-posted ready) is normative
 // in docs/KERNEL-CONTRACT.md.
 import { handle } from "./jobs.js";
+// The native core's status (core/core-status.js): a host's worker entry
+// subscribes here to count fallbacks. That module carries no WebAssembly, so
+// re-exporting it costs a worker nothing at boot.
+export { coreStatus, onCoreFallback, CORE_FALLBACK_REASONS } from "./core/core-status.js";
 import { lintPart } from "../lint.js";
 import { cachedVectorDocs } from "./vectors.js";
 

package/src/oracle.js

@@ -27,7 +27,7 @@ export { buildBVH, meshTriangles } from "./framework/oracle/bvh.js";
 export { minWall } from "./framework/oracle/min-wall.js";
 // The native core's switch (framework/core/core.js): bit-identical either way, so
 // this is a performance and kill switch, never a behaviour choice.
-export { setCoreEnabled } from "./framework/core/core.js";
+export { setCoreEnabled, coreStatus, onCoreFallback, CORE_FALLBACK_REASONS } from "./framework/core/core.js";
 export { overhang } from "./framework/oracle/overhang.js";
 // Mesh file parsers — the import pipeline's own readers, browser-safe pure
 // functions; the oracle package's corpus tests read real files through them.

package/types/oracle.d.ts

@@ -17,7 +17,8 @@ export {
   // mesh facts, gaps, BVH, min wall
   meshVolume, bboxSize, bounds, meshArea, assemblyGaps, meshGaps, buildBVH, meshTriangles, minWall, overhang,
   // the native core's switch
-  setCoreEnabled,
+  setCoreEnabled, coreStatus, onCoreFallback, CORE_FALLBACK_REASONS,
+  type CoreStatus, type CoreFallback, type CoreFallbackReason,
   type Gap, type BVH,
   // mesh file parsers (the import pipeline's own readers)
   parseStl, parse3MF,

package/types/testing.d.ts

@@ -274,6 +274,28 @@ export function minWall(
  */
 export function setCoreEnabled(on: boolean): void;
 
+/** Why the core stopped answering in this realm — a fixed vocabulary, safe to record. */
+export type CoreFallbackReason = "no_webassembly" | "boot_failed" | "out_of_memory" | "trap" | "error";
+export const CORE_FALLBACK_REASONS: readonly CoreFallbackReason[];
+export interface CoreFallback {
+  state: "unavailable" | "faulted";
+  reason: CoreFallbackReason;
+}
+export interface CoreStatus {
+  /** idle: not needed yet · on · off: switched off · unavailable: could not start · faulted: stopped after a fault */
+  state: "idle" | "on" | "off" | "unavailable" | "faulted";
+  reason: CoreFallbackReason | null;
+  /** Meshes sent to the JS pass because the core declined them (malformed MeshGL) — not a fault. */
+  refusedMeshes: number;
+}
+/** Where this realm's native core stands. Output is identical either way; this is for telemetry. */
+export function coreStatus(): CoreStatus;
+/**
+ * Called once when the core becomes unavailable or faults (immediately if it
+ * already has), so a host can count fallbacks. Returns an unsubscribe function.
+ */
+export function onCoreFallback(listener: (fallback: CoreFallback) => void): () => void;
+
 /**
  * Unsupported downward-facing surface (oracle/overhang.js): the mm² of faces
  * steeper than `maxAngle` from vertical, excluding the footprint on the bed

package/types/worker.d.ts

@@ -5,6 +5,8 @@
 // its own backend.
 
 import type { PartDefinition } from "./part.js";
+export type { CoreStatus, CoreFallback, CoreFallbackReason } from "./testing.js";
+export { coreStatus, onCoreFallback, CORE_FALLBACK_REASONS } from "./testing.js";
 
 /** The rebind handle `runWorker` returns. */
 export interface WorkerHandle {