partforge 0.95.0 → 0.96.0

package/docs/AUTHORING-PARTS.md

@@ -1925,6 +1925,15 @@ returns instead:
   `onDownload` sink, or downloaded directly if you don't supply one); rejects on
   build/export failure or an empty selection. Placement uses the current
   view. STEP is routed to OCCT automatically.
+- `runtime.warmExportKernel() → Promise<boolean>` — pay OCCT's cold boot *before* an
+  export needs it. Because STEP is pinned to OCCT and OCCT's ~11 MB WASM loads on its
+  first job, a part whose preview ran on Manifold pays that whole boot inside its first
+  STEP export — the user waits having just asked for a file, and a host with an export
+  timeout can trip it. Call this when an export becomes likely (your download dialog
+  opening) and the wait lands somewhere harmless instead. Best-effort: resolves `true`
+  once the kernel is up, `false` on any failure or teardown, never rejects, and is a
+  cheap no-op once warm. It costs a speculative ~11 MB download, so fire it on a real
+  signal of intent rather than on mount.
 
 Pass `onDownload({ data, filename, mime })` to `mount()` to receive the exported bytes
 yourself (e.g. to download from a different origin) instead of partforge's own DOM download.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.95.0",
+  "version": "0.96.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/export-controller.js

@@ -18,6 +18,11 @@ export function backendForFormat(format, defaultBackend) {
 export function createExportController({ send, currentView, title, defaultBackend = () => "manifold", currentParams = () => ({}) }) {
   const pending = new Map(); // jobId -> { resolve, reject, onProgress }
   let nextId = 1;
+  // Warm jobs are STRING-namespaced ("warm-N") for the reason mount.js spells
+  // out for tessellate-imports: this map is keyed by jobId alone and read before
+  // any type check, so a bare numeric id here could be claimed by a pending
+  // export (both counters start at 1) and settle the wrong Promise.
+  let nextWarmId = 1;
 
   function exportParts({ parts, format, quality = "print", onProgress } = {}) {
     const jobId = nextId++;
@@ -29,12 +34,31 @@ export function createExportController({ send, currentView, title, defaultBacken
     });
   }
 
+  // Pay a backend's cold boot on purpose, before anything needs it. STEP is
+  // pinned to OCCT (backendForFormat), whose ~11 MB WASM loads lazily on its
+  // first job — so for a Manifold-previewed part the STEP export IS that boot,
+  // and the user waits for it having just asked for a file. A host that knows an
+  // export is likely (its download dialog just opened) can spend that time
+  // earlier instead.
+  //
+  // Best-effort by contract: resolves true once the kernel is up, false on any
+  // failure or teardown, and NEVER rejects — a speculative warm must not become
+  // an unhandled rejection in a host that fired it and moved on.
+  function warmKernel() {
+    const jobId = `warm-${nextWarmId++}`;
+    return new Promise((resolve) => {
+      pending.set(jobId, { resolve: () => resolve(true), reject: () => resolve(false) });
+      send({ type: "warm-kernel", jobId }, backendForFormat("step", defaultBackend));
+    });
+  }
+
   // Returns true iff this message belonged to a pending export (so the caller
   // can skip legacy handling). `sink` is partforge's onDownload.
   function handleMessage(m, sink) {
     const entry = m && m.jobId != null ? pending.get(m.jobId) : undefined;
     if (!entry) return false;
     if (m.type === "progress") { entry.onProgress?.(m.phase); return true; }
+    if (m.type === "kernel-warm") { pending.delete(m.jobId); entry.resolve(); return true; }
     if (m.type === "download") {
       pending.delete(m.jobId);
       triggerDownload(m.data, m.filename, m.mime, sink);
@@ -73,5 +97,5 @@ export function createExportController({ send, currentView, title, defaultBacken
     pending.clear();
   }
 
-  return { exportParts, handleMessage, dispose };
+  return { exportParts, warmKernel, handleMessage, dispose };
 }

package/src/framework/jobs.js

@@ -338,6 +338,13 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       onProgress("writing 3MF file");
       const data = meshTo3MF(meshes);
       post({ type: "download", data, filename: `${fileBase}.3mf`, mime: "model/3mf", jobId: msg.jobId }, [bufferOf(data)]);
+    } else if (msg.type === "warm-kernel") {
+      // Deliberately empty. worker.js awaits kernelFor() before calling handle(),
+      // so REACHING this branch is the whole result: the backend this job was
+      // routed to now has a live kernel. It exists so a host can pay OCCT's cold
+      // ~11 MB boot at a moment of its own choosing — when the export dialog
+      // opens, say — instead of inside the STEP export the user just asked for.
+      post({ type: "kernel-warm", jobId: msg.jobId });
     } else if (msg.type === "tessellate-imports") {
       // OCCT-worker service job for the STEP-on-Manifold crossover: answer with
       // print-quality triangle meshes for every STEP import, transferable.

package/src/framework/mount.js

@@ -61,7 +61,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -110,6 +110,13 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     onContextLost: (listener) => viewer.onContextLost(listener),
     listExportableParts,
     exportParts,
+    // Pay the exact kernel's cold boot ahead of an export. STEP is pinned to
+    // OCCT, whose ~11 MB WASM loads on its first job, so a Manifold-previewed
+    // part's STEP export otherwise pays that boot inside the export itself.
+    // Call this when an export becomes likely (a download dialog opening) to
+    // move the wait off the moment the user asked for a file. Best-effort:
+    // resolves true/false, never rejects, and is a cheap no-op once warm.
+    warmExportKernel: warmExportKernel ?? (() => Promise.resolve(false)),
     // Narrow-layout pane selection, for a host that draws its own tab bar
     // (partforge-cloud does, at the window level). Defaulted to a no-op so the
     // handle's shape never depends on whether this mount resolved a rail.
@@ -1135,6 +1142,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       listExportableParts: () =>
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),
+      warmExportKernel: () => exportCtl.warmKernel(),
       animation: animCtl?.runtime ?? null,
       measure: {
         isEnabled: measureMode.isEnabled,

package/src/framework/worker.js

@@ -76,7 +76,15 @@ export function runWorker(part, opts = {}) {
       return data.quality === "print" ? manifold.print : manifold.preview;
     }
     if (!occt) {
-      postMessage({ type: "progress", phase: "loading exact kernel" }); // feedback during cold boot
+      // Feedback during cold boot — and CORRELATED, because for a Manifold-previewed
+      // part this boot IS the STEP export: backendForFormat pins STEP to OCCT, so the
+      // export is the session's first OCCT job and pays the whole ~11 MB WASM load.
+      // export-controller claims replies by jobId, so an unstamped message here is
+      // dropped and a headless exportParts() caller shows no progress at all for the
+      // one phase that can outlast its timeout. Jobs with no jobId (the in-page export
+      // buttons) stay unstamped, so their progress still reaches mount's own busy
+      // indicator instead of an export controller that has nothing pending.
+      postMessage({ type: "progress", phase: "loading exact kernel", ...(data.jobId != null ? { jobId: data.jobId } : {}) });
       booting = booting ?? occtKernel().then((k) => (occt = k));
       await booting;
     }

package/types/index.d.ts

@@ -412,6 +412,17 @@ export interface PartRuntime {
    * build/export failure or an empty selection.
    */
   exportParts(opts: ExportPartsOptions): Promise<void>;
+  /**
+   * Pay the exact kernel's cold boot ahead of an export. STEP is pinned to
+   * OCCT, whose ~11 MB WASM loads on its first job, so a Manifold-previewed
+   * part's STEP export otherwise pays that boot inside the export itself.
+   * Call this when an export becomes likely — a download dialog opening — to
+   * move the wait off the moment the user asked for a file.
+   *
+   * Best-effort: resolves `true` once the kernel is up, `false` on any failure
+   * or teardown, and never rejects. A no-op once the kernel is warm.
+   */
+  warmExportKernel(): Promise<boolean>;
   /**
    * Narrow-layout pane selection, for a host that draws its own tab bar.
    * `null` hands selection back to partforge's built-in bar.