perf(parser): share exact prepass source fingerprints (#4014)

* perf(parser): share exact prepass source fingerprints (#3985)

* docs(wasm): use canonical source fingerprint MPL header

* docs(perf): preserve combined local landing validation

Author: louistrue

.changeset/cold-load-prepass-fingerprint.md

@@ -0,0 +1,7 @@
+---
+"@ifc-lite/wasm": minor
+"@ifc-lite/geometry": minor
+"@ifc-lite/parser": minor
+---
+
+Share an exact full-source fingerprint from the existing prepass through a fresh optional per-load cell. Preserve previous Rust and JavaScript methods, worker scheduling, parser fallback and partial/final source identity.

apps/viewer/src/hooks/entityIndexHandoff.ts

@@ -78,3 +78,12 @@ export function forwardEntityIndexTo(
   if (deferUntilWorkerFinishes) timer = setTimeout(release, maximumWaitMs);
   return Object.assign(forward, { release });
 }
+
+/** One immutable-source fingerprint slot per load; never cache or reuse it. */
+export function createSourceFingerprintCell(source: SharedArrayBuffer | null | undefined, enabled: boolean): SharedArrayBuffer | undefined {
+  if (!enabled || !source) return undefined;
+  const cell = new SharedArrayBuffer(16), words = new Uint32Array(cell);
+  words[0] = source.byteLength >>> 0;
+  words[1] = Math.floor(source.byteLength / 0x100000000);
+  return cell;
+}

apps/viewer/src/hooks/useIfcLoader.ts

@@ -39,7 +39,7 @@ import { resolveResourceRetryTier } from '../lib/resource-retry.js';
 import { acquireFileBuffer, type AcquiredBuffer } from '../utils/acquireFileBuffer.js';
 import { buildSpatialIndexGuarded, buildSpatialIndexForModel } from '../utils/loadingUtils.js';
 import { buildGeometryCacheKey } from './geometryCacheKey.js';
-import { forwardEntityIndexTo, type EntityIndexSink } from './entityIndexHandoff.js';
+import { forwardEntityIndexTo, createSourceFingerprintCell, type EntityIndexSink } from './entityIndexHandoff.js';
 import { type GeometryData } from '@ifc-lite/cache';
 
 import { SERVER_URL, USE_SERVER, CACHE_SIZE_THRESHOLD, CACHE_MAX_SOURCE_SIZE, CACHE_MESH_ONLY_MAX_SIZE, getDynamicBatchConfig } from '../utils/ifcConfig.js';
@@ -1450,6 +1450,7 @@ export function useIfcLoader() {
       // sync threshold (2 MB) and the desktop-stable path don't fire it
       // — gate `waitForEntityIndex` so the parser doesn't hang.
       const ADAPTIVE_SYNC_THRESHOLD_MB = 2;
+      const sourceFingerprint = createSourceFingerprintCell(sharedSource, useParserWorker);
       const geometryWillEmitEntityIndex =
         useParserWorker
         && fileSizeMB >= ADAPTIVE_SYNC_THRESHOLD_MB;
@@ -1468,6 +1469,7 @@ export function useIfcLoader() {
           const worker = new WorkerParser();
           workerParserInstance = worker;
           return worker.parseColumnar(sharedSource, {
+            sourceFingerprint,
             onSpatialReady: onPartialDataStore,
             // Hold the parser's WASM scan until the pre-pass hands over
             // the entity index — but only when we know the geometry
@@ -1607,6 +1609,7 @@ export function useIfcLoader() {
               // reference arrays. Small loads still receive immediately.
               // Refusal counts and malformed-stop diagnostics remain attached.
               onEntityIndex: parserEntityIndexHandoff,
+              sourceFingerprint,
               // `?geomWorkers=N` A/B knob — overrides the cores/memory worker-
               // count heuristic so the host's thermal sweet spot can be measured.
               // Still clamped to the memory budget by the engine. Geometry output

docs/api/wasm.md

@@ -524,3 +524,16 @@ bash scripts/build-wasm.sh
 | `bundler` | CommonJS | Webpack/Rollup |
 | `nodejs` | Node.js | Server-side |
 | `no-modules` | Global | Script tag |
+
+
+### Streaming prepass source fingerprints
+
+`IfcAPI.buildPrePassStreamingWithSourceFingerprint` and
+`IfcAPI.buildPrePassStreamingShardedWithSourceFingerprint` accept the same arguments
+as `buildPrePassStreaming` and `buildPrePassStreamingSharded`, respectively. They
+run the same prepass and add `sourceContentKey` to the final `complete` event. The
+key is the existing full-byte FNV-1a source identity, including comments and any
+unparsed tail. Existing methods and their Rust signatures remain unchanged and do
+not compute this extra key. Feature-detect the new methods when supporting older
+WASM builds. The viewer uses these methods only when a matching parser has a fresh
+fingerprint cell; no additional file-sized buffer is created.

docs/guide/geometry.md

@@ -615,3 +615,13 @@ console.log(`  Total vertices: ${result.totalVertices}`);
 - [Rendering Guide](rendering.md) - Display geometry with WebGPU
 - [Parsing Guide](parsing.md) - Parse options and streaming
 - [API Reference](../api/typescript.md) - Complete API docs
+
+### Sharing the source fingerprint with a parser worker
+
+`GeometryProcessor.processAdaptive` accepts an optional `sourceFingerprint` shared
+cell, also accepted as the last optional argument of `processParallel`. Pass the
+same fresh per-load cell to `WorkerParser.parseColumnar`; its layout and lifetime
+are documented in [Browser Worker Mode](./parsing.md#browser-worker-mode). Only the
+parallel prepass produces this key. Other geometry paths and older WASM builds
+leave the cell unavailable, and the parser computes its ordinary source key without
+waiting. Geometry streaming and parser index-handoff deadlines remain unchanged.

docs/guide/parsing.md

@@ -115,6 +115,17 @@ if (WorkerParser.isSupported()) {
 }
 ```
 
+For an integrated geometry/parser load, both `WorkerParser.parseColumnar` and
+`GeometryProcessor.processAdaptive` accept an optional `sourceFingerprint` cell.
+Use a fresh 16-byte `SharedArrayBuffer` for each immutable source and pass that
+same cell to both calls. Its four unsigned 32-bit words hold source length low
+and high halves, hash, and readiness; initialize only the two length words before
+starting either call. Never reuse a cell for another source or load. The existing
+prepass worker computes the full-source key when its WASM supports that operation;
+the parser uses it only if ready, otherwise it computes the same key itself without
+waiting. Omitting the cell retains ordinary parsing behavior. This optimization
+does not change partial/final source accessor identity or cache keys.
+
 ### Streaming Geometry
 
 For large files, stream geometry progressively using `GeometryProcessor.processStreaming()`:

packages/geometry/src/byte-streaming-prepass-result.ts

@@ -0,0 +1,23 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+export interface ByteStreamingPrePassResult {
+  jobs: Uint32Array;
+  totalJobs: number;
+  unitScale: number;
+  rtcOffset?: Float64Array;
+  needsShift: boolean;
+  buildingRotation?: number | null;
+  voidKeys: Uint32Array;
+  voidCounts: Uint32Array;
+  voidValues: Uint32Array;
+  styleIds: Uint32Array;
+  styleColors: Uint8Array;
+  /** Prepass-resolved plane-angle→radians scale (additive wire field). */
+  planeAngleToRadians?: number;
+  /** #407/#913 §2.3 per-element material colour lists (flat encoding). */
+  materialElementIds?: Uint32Array;
+  materialColorCounts?: Uint32Array;
+  materialColors?: Uint8Array;
+}

packages/geometry/src/geometry-parallel-options.ts

@@ -6,6 +6,8 @@ import type { TessellationQuality } from './types.js';
 import type { BatchSizingConfig } from './batch-sizing.js';
 
 export interface ProcessParallelOptions {
+  /** Fresh per-load fingerprint cell shared only with the matching parser. */
+  sourceFingerprint?: SharedArrayBuffer;
   /**
    * Fires when the streaming pre-pass finishes building the entity index
    * (after styles), with SAB-backed Uint32Array views over the shared

packages/geometry/src/geometry-parallel.ts

@@ -1450,6 +1450,7 @@ export async function* processParallel(
       }
       prepassWorker.postMessage({
         type: 'prepass-streaming-sharded',
+        sourceFingerprint: options?.sourceFingerprint,
         sharedBuffer,
         chunkSize: 50_000,
         ...(visibilityFilter?.disabledTypes ? { disabledTypes: visibilityFilter.disabledTypes } : {}),
@@ -1462,6 +1463,7 @@ export async function* processParallel(
     } else {
       prepassWorker.postMessage({
         type: 'prepass-streaming',
+        sourceFingerprint: options?.sourceFingerprint,
         sharedBuffer,
         chunkSize: 50_000,
         ...(visibilityFilter?.disabledTypes ? { disabledTypes: visibilityFilter.disabledTypes } : {}),

packages/geometry/src/geometry.worker.ts

@@ -3,6 +3,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
 import { ownedWasmBuffer } from './wasm-owned-buffer.js';
+import { publishPrepassFingerprint, runPrepassWithFingerprint } from './prepass-source-fingerprint.js';
 import { canReuseWorkerSource, type SourcePrepassApi, type FinalizeStyleArgs } from './worker-prepass-source.js';
 import init, { initSync, IfcAPI } from '@ifc-lite/wasm';
 import { initWasmWithRetry } from './wasm-init-retry.js';
@@ -174,6 +175,7 @@ export interface GeometryWorkerScanShardMessage {
 
 export interface GeometryWorkerPrePassMessage {
   type: 'prepass-streaming';
+  sourceFingerprint?: SharedArrayBuffer;
   sharedBuffer: SharedArrayBuffer;
   /** Jobs per chunk (defaults to 50_000). */
   chunkSize?: number;
@@ -319,6 +321,7 @@ export interface GeometryWorkerStylesShardResultMessage {
  */
 export interface GeometryWorkerPrePassShardedMessage {
   type: 'prepass-streaming-sharded';
+  sourceFingerprint?: SharedArrayBuffer;
   sharedBuffer: SharedArrayBuffer;
   chunkSize?: number;
   disabledTypes?: string[];
@@ -1384,26 +1387,20 @@ async function handleMessage(e: MessageEvent<GeometryWorkerRequest>): Promise<vo
       const ifcApi = await ensureInit();
       (self as unknown as Worker).postMessage({ type: 'prepass-progress', phase: 'parsing' });
       const { sharedBuffer, indexIds, indexStarts, indexLengths, indexClasses } = e.data;
+      const sourceFingerprint = e.data.sourceFingerprint;
       const chunkSize = e.data.chunkSize ?? 50_000;
       const disabledTypes = e.data.disabledTypes ?? undefined;
       const skipTypeGeometry = e.data.skipTypeGeometry === true;
       const onEvent = (event: unknown) => {
+        publishPrepassFingerprint(sourceFingerprint, sharedBuffer.byteLength, event);
         (self as unknown as Worker).postMessage({ type: 'prepass-stream', event });
       };
       const run = (
         bytes: Uint8Array,
         ids: Uint32Array, starts: Uint32Array, lengths: Uint32Array, classes: Uint8Array,
       ) =>
-        (ifcApi as unknown as {
-          buildPrePassStreamingSharded: (
-            data: Uint8Array, onEvent: (e: unknown) => void, chunkSize: number,
-            disabledTypes: string[] | undefined, skipTypeGeometry: boolean,
-            ids: Uint32Array, starts: Uint32Array, lengths: Uint32Array, classes: Uint8Array,
-          ) => unknown;
-        }).buildPrePassStreamingSharded(
-          bytes, onEvent, chunkSize, disabledTypes, skipTypeGeometry,
-          ids, starts, lengths, classes,
-        );
+        runPrepassWithFingerprint(ifcApi, [bytes, onEvent, chunkSize, disabledTypes, skipTypeGeometry],
+          sourceFingerprint, [ids, starts, lengths, classes]);
       try {
         run(viewSharedBytes(sharedBuffer), indexIds, indexStarts, indexLengths, indexClasses);
       } catch (err) {
@@ -1469,6 +1466,7 @@ async function handleMessage(e: MessageEvent<GeometryWorkerRequest>): Promise<vo
       // before the first chunk lands.
       (self as unknown as Worker).postMessage({ type: 'prepass-progress', phase: 'parsing' });
       const sharedBuffer = e.data.sharedBuffer;
+      const sourceFingerprint = e.data.sourceFingerprint;
       const chunkSize = e.data.chunkSize ?? 50_000;
       // #1097 load-time visibility filter (skip disabled types at job gen).
       const disabledTypes = e.data.disabledTypes ?? undefined;
@@ -1479,10 +1477,11 @@ async function handleMessage(e: MessageEvent<GeometryWorkerRequest>): Promise<vo
       // zero-copy view first, fall back to a materialised copy only if
       // wasm-bindgen rejects the view.
       const onEvent = (event: unknown) => {
+        publishPrepassFingerprint(sourceFingerprint, sharedBuffer.byteLength, event);
         (self as unknown as Worker).postMessage({ type: 'prepass-stream', event });
       };
       const runPrepass = (bytes: Uint8Array) =>
-        ifcApi.buildPrePassStreaming(bytes, onEvent, chunkSize, disabledTypes, skipTypeGeometry);
+        runPrepassWithFingerprint(ifcApi, [bytes, onEvent, chunkSize, disabledTypes, skipTypeGeometry], sourceFingerprint);
       try {
         // Zero-copy SAB view first; wasm-bindgen copies it into linear memory.
         runPrepass(viewSharedBytes(sharedBuffer));
@@ -1593,7 +1592,8 @@ async function handleMessage(e: MessageEvent<GeometryWorkerRequest>): Promise<vo
       // size from a previous dense model).
       batchSizing = resolveBatchSizing(e.data.batchSizing);
       adaptiveBatchJobs = batchSizing.maxJobs;
-      // Reuse this load's shard source; reset non-sharded/reused loads before geometry (#3989).
+      // Shard scanning has already installed this load's source (#3989).
+      // Non-sharded/reused loads still reset before their first geometry batch.
       if (!sourcePreparedForStream || !canReuseWorkerSource(installedSourceSessionId, e.data.sourceSessionId)) {
         sourceBytesApplied = false;
         cachedSourceBytes = null;