partforge 0.166.0 → 0.167.0

package/docs/KERNEL-CONTRACT.md

@@ -895,6 +895,17 @@ built. So **a `meshes` post is current as of the moment it is posted**: it is ne
 previous part's geometry surfacing after a rebind, and a host may take it as the build
 outcome for the part it currently has mounted.
 
+**Progressive generates.** A generate carrying `progressive: true` (mount's
+`progressiveBuild` option) also posts `{type:"meshes-partial", meshes}` while it runs:
+the sub-parts built so far, batched at most every 300 ms, each posted right after a
+sub-part boundary's staleness check. A batch that is stale by the time it is posted is
+dropped by the worker, never downgraded to `superseded` — the job's own final post still
+settles it. The final `{type:"meshes"}` then carries only the sub-parts no batch did, so
+every sub-part arrives exactly once, its buffers transferred with it. A batch settles
+nothing: `ready`, `onBuild` and a host's own "build finished" wait for `meshes`. A host
+that reads worker replies itself and turns `progressive` on must add the batches up; one
+that never sends it sees the protocol exactly as before.
+
 **Host-side rule for `superseded`.** partforge's own `mount()` does not handle a
 `superseded` message, and does not need to: in its single-mount flow the regen loop
 serializes generates, so no generate is ever in flight when the next one is sent and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.166.0",
+  "version": "0.167.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/jobs.js

@@ -65,7 +65,9 @@ const loadBedLayout = () => import("./export/bed-layout.js");
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
-//   { type:"generate", subparts, view, params, cacheBudget? } → { type:"meshes", meshes, ms }
+//   { type:"generate", subparts, view, params, cacheBudget?, progressive? } → { type:"meshes", meshes, ms }
+//       progressive: true also posts { type:"meshes-partial", meshes } batches while it
+//       builds; the final `meshes` then carries only the sub-parts no batch did
 //   { type:"export-stl", view, params }         → { type:"download-parts", ext, mime, parts }
 //   { type:"export-step", view, params }        → { type:"download", data, filename, mime }
 //   { type:"export-bundle", view, params, parts, options }
@@ -163,6 +165,11 @@ async function scoreMatchTargets(built, targets, onProgress) {
   }
 }
 
+// A progressive generate hands over its built sub-parts at most this often (ms).
+const PROGRESSIVE_BATCH_MS = 300;
+const transferOf = (meshes) => meshes.flatMap((m) =>
+  [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
+
 // The WASM traps that mean the kernel ran out of heap (or was corrupted by doing so).
 const HEAP_TRAP_RE = /out of bounds memory access|memory access out of bounds|Cannot enlarge memory|out of memory/i;
 
@@ -465,6 +472,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // The host's bound on the solid cache (mount's cacheBudgetMB), in bytes; null
       // means unbounded. Kept by the kernel, so the oracle's builds share it.
       if (Object.hasOwn(msg, "cacheBudget")) kernel.setCacheBudget?.(msg.cacheBudget ?? Infinity);
+      let lastBatchAt = t0; // progressive delivery's clock (below)
       for (const [i, name] of msg.subparts.entries()) {
         if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
         try {
@@ -485,12 +493,22 @@ export async function handle(kernel, part, msg, post, opts = {}) {
         if (i < msg.subparts.length - 1) {
           await new Promise((r) => setTimeout(r, 0));
           if (isStale()) return void post({ type: "superseded" });
+          // Progressive delivery (msg.progressive): hand over what is built so far,
+          // so a host shows a many-sub-part view filling in instead of waiting for
+          // the last sub-part (feedback #212: a 105-plate park showed nothing for
+          // ~45 s). Batched by time, never per sub-part, so a view of many cheap
+          // pieces is not a flood of messages. Posted only after the stale check
+          // above, so a batch is current as of the moment it is posted; the final
+          // `meshes` carries whatever is left, and the job's warnings and timing.
+          if (msg.progressive && meshes.length > 0 && Date.now() - lastBatchAt >= PROGRESSIVE_BATCH_MS) {
+            const batch = meshes.splice(0);
+            post({ type: "meshes-partial", meshes: batch }, transferOf(batch));
+            lastBatchAt = Date.now();
+          }
         }
       }
-      const transfer = meshes.flatMap((m) =>
-        [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
       post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.(),
-             ...(warnings.length ? { warnings } : {}) }, transfer);
+             ...(warnings.length ? { warnings } : {}) }, transferOf(meshes));
     } else if (msg.type === "capture-generate") {
       // A private, job-correlated one-shot channel for captureView — builds a
       // (possibly non-active) view's meshes off the regen loop, so it can never

package/src/framework/mount.js

@@ -286,7 +286,10 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.166.0: `cacheBudgetMB` bounds the worker's solid cache —
+// Embedding contract (0.167.0: `progressiveBuild: true` shows a many-sub-part view
+// filling in as its sub-parts finish — the worker then also posts `meshes-partial`
+// batches, and the final `meshes` carries only what no batch did, so a host reading
+// worker replies itself must add them up; 0.166.0: `cacheBudgetMB` bounds the worker's solid cache —
 // pass a small one on phones; 0.158.0: a preview GLB may carry its view's autoplay
 // animation — mount({ preview }) draws its opening pose and does not play it,
 // mountPreview plays it unless `animate: false`, and exportPreview bakes it only
@@ -517,6 +520,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
                               annotateSend = "viewbar",
                               selectionPopover,
                               cacheBudgetMB,
+                              progressiveBuild = false,
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -1016,6 +1020,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
 
     let framedView = null; // the view the camera was last framed to (null until first show)
     let cameraRestored = false; // saved camera applied once, on the first frame after load
+    let partialView = null;        // the view whose first build is shown in batches (showPartial)
+    let partialCameraKept = false; // that build must not reframe on completion
     let cutawayRestored = false; // a carried cutaway, applied once — after any preview, never on one
     let selectionRestored = false; // a carried selection, tried once, after the camera
     function restoreCarriedSelection() {
@@ -1075,7 +1081,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         for (const backend of ["manifold", "occt"]) {
           const subparts = missing.filter((n) => (backends[n] ?? "manifold") === backend);
           if (subparts.length === 0) continue;
-          service.send({ type: "generate", subparts, view: view(), params, cache: cachingOn, cacheBudget: cacheBudgetBytes }, backend);
+          service.send({ type: "generate", subparts, view: view(), params, cache: cachingOn, cacheBudget: cacheBudgetBytes, ...(progressiveBuild ? { progressive: true } : {}) }, backend);
           jobs++;
         }
         return jobs;
@@ -1137,7 +1143,13 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     }
 
     function showView(needed) {
-      const frame = view() !== framedView;
+      let frame = view() !== framedView;
+      // A first build shown in batches (showPartial) completes: frame the whole view now,
+      // unless the user moved the camera meanwhile or a restored camera stands.
+      if (partialView === view()) {
+        partialView = null;
+        if (frame && partialCameraKept) { frame = false; framedView = view(); cameraRestored = true; }
+      }
       viewer.showAssembly(needed, { frame });
       if (frame) {
         framedView = view();
@@ -1289,6 +1301,63 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       }
     }
 
+    // Apply a delivery built at the LIVE params — a final `meshes` whose build is still
+    // fresh, or a progressive batch (meshes-partial) of a build that still is.
+    function applyFreshMeshes(meshes) {
+      liveDelivered = true; // only a delivery that is applied beats a preview still decoding
+      for (const m of meshes) {
+        viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
+        // The view its job was SENT for, and the frame the worker delivered
+        // in: "canonical" (place() not applied — mount poses it below) or
+        // "posed". An older worker sends no frame; its meshes are posed.
+        cache.record(m.name, m.reads, dispatched.get(m.name)?.view ?? view(), m.frame ?? "posed");
+        // A sub-part that built into NOTHING. Manifold booleans return an
+        // empty solid rather than throwing (a bore wider than its body),
+        // and typed values may sit outside the authored range, so a
+        // "successful" build can deliver zero triangles — recorded here,
+        // reported below once the view is whole. Undefined counts (a
+        // host's synthetic reply) are not empty.
+        if (m.triangles === 0) emptySubParts.add(m.name); else emptySubParts.delete(m.name);
+        // Stamp the fast path's pose baseline. Only here, inside the
+        // non-stale branch: the stamp must describe the geometry actually
+        // delivered, which buildDone() true guarantees is at the live params.
+        fastPath.recordDelivered(m.name);
+      }
+      // setSubGeometry reset every delivered mesh's matrix, so each one gets
+      // its display pose now, after its geometry landed: a canonical mesh
+      // place() at the live params, a posed one a cleared matrix. `fresh`:
+      // an untrusted live place() here clears the pose but keeps the stamp
+      // (host and worker probes agree by construction at these params;
+      // forgetting on a disagreement would rebuild at the same params forever).
+      fastPath.apply(meshes.map((m) => m.name), undefined, { fresh: true });
+      recordFrames(meshes);
+    }
+
+    // Progressive delivery (feedback #212). A view with many sub-parts posts what it has
+    // built in batches while the job runs, and the view fills in as they land. Framing is
+    // the one hazard: showView frames once per view, and framing to the first batch
+    // would leave a park's camera zoomed in on five plates. So a first build with nothing
+    // on screen frames to the first batch, and showView frames the whole view when the
+    // build completes — unless the user has moved the camera since, or a carried or
+    // persisted camera was restored, which win as they always have.
+    cleanup.defer(viewer.onCameraStart(() => { if (partialView === view()) partialCameraKept = true; }));
+    function showPartial() {
+      const needed = viewSubParts(part, view(), params);
+      // Everything already on screen (an edit), or a cached preview filling the
+      // gaps: the ordinary path shows it.
+      if (previewGate.isActive() || needed.every((n) => viewer.hasSubMesh(n))) return refreshView();
+      const present = needed.filter((n) => viewer.hasSubMesh(n));
+      let frame = false;
+      if (view() !== framedView && partialView !== view()) {
+        partialView = view();
+        partialCameraKept = false;
+        const cam = !cameraRestored ? viewerState?.camera ?? loadCamera() : null;
+        if (cam) { viewer.setCameraState(cam); cameraRestored = true; partialCameraKept = true; }
+        else frame = true;
+      }
+      viewer.showAssembly(present, { frame });
+    }
+
     ui.showBusy("booting kernel"); // visible from first paint until the kernel is ready
 
     // Bundle filename for a multi-part export (single parts download under their own name).
@@ -1311,36 +1380,18 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
           ui.showBusy(data.phase);
           ui.setStatus(`${data.phase}…`);
           break;
+        case "meshes-partial":
+          // A batch of a progressive build: shown only while that build is still
+          // current. It settles nothing — the job's final `meshes` does.
+          if (!loop.isFresh()) break;
+          applyFreshMeshes(data.meshes);
+          showPartial();
+          updateRelevance();
+          break;
         case "meshes": {
           const fresh = loop.buildDone();
           if (fresh) { // stale results (params changed mid-build) are discarded
-            liveDelivered = true; // only a delivery that is applied beats a preview still decoding
-            for (const m of data.meshes) {
-              viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
-              // The view its job was SENT for, and the frame the worker delivered
-              // in: "canonical" (place() not applied — mount poses it below) or
-              // "posed". An older worker sends no frame; its meshes are posed.
-              cache.record(m.name, m.reads, dispatched.get(m.name)?.view ?? view(), m.frame ?? "posed");
-              // A sub-part that built into NOTHING. Manifold booleans return an
-              // empty solid rather than throwing (a bore wider than its body),
-              // and typed values may sit outside the authored range, so a
-              // "successful" build can deliver zero triangles — recorded here,
-              // reported below once the view is whole. Undefined counts (a
-              // host's synthetic reply) are not empty.
-              if (m.triangles === 0) emptySubParts.add(m.name); else emptySubParts.delete(m.name);
-              // Stamp the fast path's pose baseline. Only here, inside the
-              // non-stale branch: the stamp must describe the geometry actually
-              // delivered, which buildDone() true guarantees is at the live params.
-              fastPath.recordDelivered(m.name);
-            }
-            // setSubGeometry reset every delivered mesh's matrix, so each one gets
-            // its display pose now, after its geometry landed: a canonical mesh
-            // place() at the live params, a posed one a cleared matrix. `fresh`:
-            // an untrusted live place() here clears the pose but keeps the stamp
-            // (host and worker probes agree by construction at these params;
-            // forgetting on a disagreement would rebuild at the same params forever).
-            fastPath.apply(data.meshes.map((m) => m.name), undefined, { fresh: true });
-            recordFrames(data.meshes);
+            applyFreshMeshes(data.meshes);
             // The whole view is live: every sub-part the preview drew has just been
             // replaced in place, so the tools it held back come back. Before
             // refreshView, so showView restores a carried cutaway on this build.

package/src/framework/regen-loop.js

@@ -53,6 +53,9 @@ export function createRegenLoop({ missingParts, send, debounceMs = 180 }) {
       return genVersion === paramsVersion;
     },
     version: () => paramsVersion,
+    // A build is in flight and nothing has edited the params since it was sent —
+    // the test a progressive batch (meshes-partial) must pass to be shown.
+    isFresh: () => pending > 0 && genVersion === paramsVersion,
     // Terminal: cancel the pending debounce and refuse all future sends.
     dispose() { disposed = true; clearTimeout(timer); },
   };

package/src/framework/worker.js

@@ -138,8 +138,13 @@ export function runWorker(part, opts = {}) {
           // generate that goes stale once dequeued. Both would otherwise post the OLD
           // part's meshes after a rebind. Downgrading them to `superseded` keeps the
           // contract simple: a `meshes` post is current as of the moment it is posted.
-          const gated = (m, transfer = []) =>
-            (m.type === "meshes" && isStale() ? post({ type: "superseded" }) : post(m, transfer));
+          // A progressive batch that went stale is simply dropped: the job's own
+          // final reply (or its superseded) still settles the cycle.
+          const gated = (m, transfer = []) => {
+            if (m.type === "meshes-partial" && isStale()) return;
+            if (m.type === "meshes" && isStale()) return post({ type: "superseded" });
+            post(m, transfer);
+          };
           await handle(kernel, job.part, job.data, gated, { isStale, importMeshes, jobs: opts.jobs });
         } catch (thrown) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.

package/types/index.d.ts

@@ -226,6 +226,15 @@ export interface MountOptions {
    * gigabytes, more than a mobile browser tab is allowed.
    */
   cacheBudgetMB?: number;
+  /**
+   * Show a view filling in as its sub-parts finish, instead of all at once when the
+   * last one does — the difference on a forge of dozens of heavy pieces is the whole
+   * build time. Off by default. When on, the geometry worker also posts
+   * `{ type: "meshes-partial", meshes }` batches during a build and the final
+   * `{ type: "meshes" }` carries only the sub-parts no batch did: a host that reads
+   * worker replies itself must add the batches up.
+   */
+  progressiveBuild?: boolean;
   /** Receive exported bytes instead of partforge's own DOM download. */
   onDownload?: (file: DownloadPayload) => void;
   /** The active view (tab) name — emitted once on mount, then on every change. */