@es3d/es3d 1.1.2 → 1.2.1

package/docs/STAGE.md

@@ -0,0 +1,95 @@
+# Stage API
+
+The stage puts an ES3D document on a canvas in a web page. It compiles the document, draws it with WebGPU or WebGL2, and handles what a page needs around that: resizing, the document's `<controls>`, scroll-driven animation, picking, and keeping meshes between visits.
+
+```js
+import { createStage } from '@es3d/es3d/stage';
+
+const stage = await createStage(document.querySelector('canvas'));
+stage.show(source);
+```
+
+`@es3d/es3d/stage` is one minified file, `browser/es3d-stage.min.js`, so a page loads it in one request, also from a CDN. `@es3d/es3d/browser` has the same stage plus the rest of the library (file conversion included), and `createStage` is also in `@es3d/es3d`. The canvas takes the size of its parent element.
+
+## Options
+
+`createStage(canvas, options)`. Every option can be left out.
+
+| Option | Default | What it does |
+|---|---|---|
+| `playing` | `true` | Play clock animations. |
+| `autoOrbit` | `true` | Turn slowly around the target until someone drags. |
+| `orbitSpeed` | `0.22` | Radians per second. |
+| `interactive` | `true` | `false`: no dragging, whatever the document says. |
+| `background` | `false` | A still camera and a running clock, for a page that moves shapes itself. |
+| `clock` | `'document'` | `'always'` runs the clock in a document with no `<animate>`. |
+| `scroll` | the page | The section whose scroll position drives `timeline="scroll"` animations. |
+| `backend` | `'auto'` | `'webgpu'` or `'webgl2'` to choose. |
+| `geometryStore` | IndexedDB | Where generated meshes are kept between visits. `false` keeps nothing. |
+| `changeBudget` | `4` | Milliseconds per frame for compiling and placing fragments. |
+| `workers` | `1` | `0` compiles `prepare()` on the main thread. |
+| `onFrame(dt, stage)` | | Called every animation frame. |
+| `onPick(hit)` | | A click on the scene. `hit.names` lists name and id up the tree; `hit.fragment` names the fragment hit. |
+| `onInteract()` | | The visitor moved the camera. |
+| `onError(message, result)` | | A document or fragment did not compile, or a fragment has elements only the stage's document can set. |
+
+With `prefers-reduced-motion`, the clock and the automatic orbit stand still and a scroll-driven camera jumps from stop to stop. `stage.reducedMotion` says whether that is on.
+
+## Showing a document
+
+`stage.show(source, { keepCamera, time, keepFragments })` compiles and shows a document in any of the three syntaxes, and returns the compile result. On errors the previous document stays on screen and `onError` is called. A new document reuses the geometry of the last one, so a colour change re-tessellates nothing.
+
+`stage.result` is the compile result on screen. `stage.camera`, `stage.controls` and `stage.renderer` are the parts the stage drives. `stage.time`, `stage.progress` (the scroll timeline, 0 to 1) and `stage.playing` can be read and set. `stage.invalidate()` draws the next frame even if nothing changed. `stage.dispose()` releases everything.
+
+## Moving shapes
+
+`stage.setTransform(id, matrix)` replaces the local matrix of the element with that id. The matrix is column-major, 16 numbers, the layout of `matrix()`. `stage.setTransforms([[id, matrix], ...])` does the same for many elements, walks each affected part of the scene once, and returns a boolean for each entry.
+
+An entry is `false` when the id is missing or the element is drawn in more than one place: a shared definition, or a copy made by `<repeat>` or `<scatter>`. Give each shape you move its own id.
+
+## Fragments
+
+A fragment is another complete document shown inside the stage's document: a map tile, a room, a route. Only that document is compiled when it is added, replaced or removed.
+
+```js
+const tile = stage.add(source, { id: '16/32748/21789' });   // returns at once
+const { ok, diagnostics } = await tile.ready;               // placed
+tile.visible = false;                                       // kept, draws nothing
+tile.replace(newSource);                                    // only this fragment is rebuilt
+tile.setTransforms([['pier', matrix]]);                     // ids of this fragment's document
+tile.remove();
+```
+
+| Call | What it does |
+|---|---|
+| `stage.add(source, { id, immediate })` | Adds a fragment and returns it. It is compiled and placed in the frame loop, within `changeBudget`; `immediate: true` does it now. Until then it draws nothing. |
+| `fragment.ready` | Resolves with `{ ok, diagnostics, fragment }` once placed, or once it failed. |
+| `fragment.visible` | `false` hides it without recompiling: it adds no rows to the frame. |
+| `fragment.replace(source)` | New content in the same place. Bad input keeps what is on screen. Returns a promise like `ready`. |
+| `fragment.setTransforms(entries)`, `setTransform(id, matrix)` | As on the stage, with the fragment's own ids. |
+| `fragment.remove()` | Takes it out at once and frees what only it used. |
+| `fragment.placed`, `fragment.diagnostics`, `fragment.id` | Its state. |
+| `stage.fragment(id)`, `stage.fragments` | One fragment, or all of them in the order added. |
+
+Each fragment is a complete, valid document, and any version-1 reader can open it on its own. Its shapes, groups, `<use>` with its own `<defs>`, `<repeat>`, `<scatter>`, `<lod>`, lights and `<animate>` are drawn as `show()` draws them. `<environment>`, `<camera>` and `<controls>` belong to the stage's document: in a fragment they are ignored, with a warning (code `STAGE_HOST_ONLY`). Two fragments may use the same ids. Materials with identical parameters are one material across all documents, and a shape repeated across fragments is generated and uploaded once.
+
+The stage's document and its fragments draw the same picture as one document that holds the document's children and then each fragment's, in the order added. `show(source)` keeps the fragments; `show(source, { keepFragments: false })` removes them.
+
+## Compiling off the main thread
+
+```js
+const prepared = await stage.prepare(source);           // { as: 'document' } for show()
+const tile = stage.add(prepared, { id });
+```
+
+`stage.prepare(source, { as })` compiles in a worker the stage starts from its own file, and generates the meshes there too. Adding the result costs the main thread about a millisecond for a tile of a thousand buildings. A stage loaded from another origin starts its worker through a small module made in the page. Where no worker can start (a content security policy, `workers: 0`), `prepare()` compiles on the main thread, so a page needs no special case. The diagnostics are the same either way. A prepared document is added or shown once.
+
+## Knowing what is on screen
+
+`stage.drawn()` resolves after the first frame that shows every change queued before the call, fully refined. It resolves with `stage.stats`.
+
+`stage.stats` describes the last drawn frame, in main-thread milliseconds: `frameMs` (the whole frame), `changeMs` (fragment changes since the frame before), `compileMs` (the compiling part of that), `tessellateMs` (mesh generation while drawing) and `renderMs` (drawing without it). Also `instances`, `drawCalls`, `uploadBytes`, `refining` (levels still being refined) and `queued` (changes waiting).
+
+## Placement functions
+
+`mulberry32`, `es3dSin` and `es3dCos` are exported too: the random generator and the sine and cosine the reader uses for `<scatter>`, so a script can place things exactly where a document would.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@es3d/es3d",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "ES3D (Extensible Scalable 3D): a declarative, SVG-inspired 3D scene format with a WebGPU/WebGL2 reference renderer, editor and converter.",
   "type": "module",
   "license": "Apache-2.0",
@@ -29,7 +29,8 @@
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
-    "./stage": "./browser/es3d-stage.min.js"
+    "./stage": "./browser/es3d-stage.min.js",
+    "./browser": "./browser/es3d.min.js"
   },
   "bin": {
     "es3d": "scripts/es3d-cli.mjs"
@@ -42,8 +43,10 @@
     "!src/main.js",
     "scripts/es3d-cli.mjs",
     "browser/es3d-stage.min.js",
+    "browser/es3d.min.js",
     "docs/SPEC.md",
-    "docs/REFERENCE.md"
+    "docs/REFERENCE.md",
+    "docs/STAGE.md"
   ],
   "engines": {
     "node": ">=22"

package/src/browser.js

@@ -0,0 +1,16 @@
+// The browser entry: the whole browser-safe API in one file
+// (browser/es3d.min.js, `npm run build:browser`, published as
+// @es3d/es3d/browser), so a page loads ES3D in a single request: parse,
+// validate and compile documents, draw them (createRenderer, createStage),
+// and convert files on the visitor's own computer.
+//
+//   import { importFiles, exportFormat } from '@es3d/es3d/browser';
+//
+//   const doc = await importFiles(input.files);            // SVG, OBJ (+.mtl), STL, STEP, glTF, X3D, USDA, OpenSCAD
+//   const { files } = exportFormat(doc.text, 'glb');       // nothing is uploaded
+//
+// It is the package entry (src/index.js) as it is: everything there runs in a
+// browser. Node-only code (the glTF packer behind scripts/, zlib in
+// io/compression.js) is not part of it; the build checks that.
+
+export * from './index.js';

package/src/cache/geometry-store.js

@@ -22,6 +22,10 @@
 //
 // Authored <mesh> data is not cached: hashing it costs about what computing
 // its normals does.
+//
+// A stage that shows fragments keeps one record per owner (the host document
+// and each fragment, GeometryCache.owned), named by that owner's entries
+// alone, so a tile's meshes are found again whatever else is on screen.
 
 import { sha256 } from './sha256.js';
 import { encodeBundle, decodeBundle } from './mesh-bundle.js';
@@ -84,11 +88,12 @@ async function digest(bytes, native) {
  * which a long-lived cache first saw them does not matter), and the name of
  * their record.
  * @param {import('../geometry/geometry-cache.js').GeometryCache} cache
- * @param {{native?: boolean}} [opts] native: false always uses sha256.js
+ * @param {{native?: boolean, entries?: Iterable<object>}} [opts] native: false always uses
+ *   sha256.js. entries: only these entries of the cache (one owner's), not all of them
  */
 export async function geometryKey(cache, opts = {}) {
   const entries = [];
-  for (const e of cache.entries.values()) if (e.identity) entries.push(e);
+  for (const e of opts.entries || cache.entries.values()) if (e.identity) entries.push(e);
   if (!entries.length) return { key: null, entries };
   entries.sort((a, b) => (a.identity < b.identity ? -1 : a.identity > b.identity ? 1 : 0));
   // identities are length-prefixed (registry.js), so their concatenation is unambiguous
@@ -118,7 +123,8 @@ const withTimeout = (promise, ms) =>
  * compile() and before the first frame; levels that exist already are kept.
  * @param {import('../geometry/geometry-cache.js').GeometryCache} cache
  * @param {object|Promise<object>} store from openGeometryStore() (null: nothing to do)
- * @param {{timeout?: number}} [opts] give up on a store slower than this (ms, default 250)
+ * @param {{timeout?: number, entries?: Iterable<object>}} [opts] timeout: give up on a store slower
+ *   than this (ms, default 250). entries: restore only these (one owner's, see geometryKey)
  * @returns {Promise<{hit: boolean, key: string|null, levels: number, bytes: number, ms: number, reason?: string}>}
  */
 export async function restoreGeometry(cache, store, opts = {}) {
@@ -126,7 +132,7 @@ export async function restoreGeometry(cache, store, opts = {}) {
   const done = (r) => ({ hit: false, key: null, levels: 0, bytes: 0, ...r, ms: now() - t0 });
   const s = await withTimeout(Promise.resolve(store), opts.timeout ?? 250);
   if (!s) return done({ reason: s === undefined ? 'store timed out' : 'no store' });
-  const { key, entries } = await geometryKey(cache);
+  const { key, entries } = await geometryKey(cache, { entries: opts.entries });
   if (!key) return done({ reason: 'nothing cacheable' });
   let buffer;
   try {
@@ -153,7 +159,7 @@ export async function restoreGeometry(cache, store, opts = {}) {
     for (const { lod, mesh, reports } of stored) if (cache.adopt(entries[i], lod, mesh, reports)) levels++;
   }
   // what the store holds: saving is worth it once the cache holds more
-  cache.persisted = `${key}:${held}`;
+  markPersisted(cache, `${key}:${held}`);
   return { hit: true, key, levels, bytes: buffer.byteLength, ms: now() - t0 };
 }
 
@@ -163,20 +169,30 @@ function countLevels(entries) {
   return n;
 }
 
+// cache.persisted is the record the cache last read or wrote (one document);
+// persistedSet remembers every one, for a cache that several owners share
+function markPersisted(cache, signature) {
+  cache.persisted = signature;
+  if (!cache.persistedSet) cache.persistedSet = new Set();
+  if (cache.persistedSet.size > 4096) cache.persistedSet.clear();
+  cache.persistedSet.add(signature);
+}
+
 /**
  * Store the meshes a cache holds for its current shapes, if it holds any the
  * store does not have yet. Call when the page is idle after drawing.
  * @param {import('../geometry/geometry-cache.js').GeometryCache} cache
  * @param {object|Promise<object>} store
+ * @param {{entries?: Iterable<object>}} [opts] entries: store only these (one owner's, see geometryKey)
  * @returns {Promise<{saved: boolean, key: string|null, bytes: number, reason?: string}>}
  */
-export async function saveGeometry(cache, store) {
+export async function saveGeometry(cache, store, opts = {}) {
   const s = await store;
   if (!s) return { saved: false, key: null, bytes: 0, reason: 'no store' };
-  const { key, entries } = await geometryKey(cache);
+  const { key, entries } = await geometryKey(cache, { entries: opts.entries });
   if (!key) return { saved: false, key: null, bytes: 0, reason: 'nothing cacheable' };
   const signature = `${key}:${countLevels(entries)}`;
-  if (cache.persisted === signature) return { saved: false, key, bytes: 0, reason: 'up to date' };
+  if (cache.persisted === signature || (cache.persistedSet && cache.persistedSet.has(signature))) return { saved: false, key, bytes: 0, reason: 'up to date' };
   const records = entries.map(storedLevels);
   if (!records.some((levels) => levels.length)) return { saved: false, key, bytes: 0, reason: 'nothing generated' };
   const buffer = encodeBundle(key, records);
@@ -186,7 +202,7 @@ export async function saveGeometry(cache, store) {
   } catch (e) {
     return { saved: false, key, bytes: buffer.byteLength, reason: `store failed: ${e && e.message ? e.message : e}` };
   }
-  cache.persisted = signature;
+  markPersisted(cache, signature);
   return { saved: true, key, bytes: buffer.byteLength };
 }
 
@@ -195,6 +211,10 @@ export async function saveGeometry(cache, store) {
  * compile() and changed() after drawing; meshes generated since the last save
  * are saved once nothing new has been generated for `delay` ms and the page
  * is idle.
+ *
+ * changed(cache, {owner, entries}) keeps one record per owner of a shared
+ * cache (the stage's host document and each fragment); every owner changed
+ * since the last save is saved then.
  * @param {object|Promise<object>|null} store null: both calls do nothing
  * @param {{delay?: number}} [opts]
  */
@@ -204,21 +224,39 @@ export function persistGeometry(store, opts = {}) {
   let timer = 0;
   let pending = null;
   let seen = -1;
+  const owners = new Map(); // owner -> {cache, entries}
+  const flush = () => {
+    const c = pending;
+    pending = null;
+    const list = [...owners.values()];
+    owners.clear();
+    if (c) saveGeometry(c, store).catch(() => {});
+    // one owner after the other: each save hashes and encodes that owner's meshes
+    list.reduce((p, o) => p.then(() => saveGeometry(o.cache, store, { entries: o.entries() }).catch(() => {})), Promise.resolve());
+  };
   return {
     store,
     restore(cache, restoreOpts) {
       return store ? restoreGeometry(cache, store, restoreOpts) : Promise.resolve(null);
     },
-    changed(cache) {
-      if (!store || (cache === pending && cache.stats.generated === seen)) return;
-      pending = cache;
-      seen = cache.stats.generated;
+    /**
+     * @param {object} cache
+     * @param {{owner: *, entries: () => Iterable<object>}} [part] one owner of a shared cache
+     */
+    changed(cache, part) {
+      if (!store) return;
+      if (part) owners.set(part.owner, { cache, entries: part.entries });
+      else {
+        if (cache === pending && cache.stats.generated === seen) return;
+        pending = cache;
+        seen = cache.stats.generated;
+      }
       clearTimeout(timer);
-      timer = setTimeout(() => idle(() => {
-        const c = pending;
-        pending = null;
-        if (c) saveGeometry(c, store).catch(() => {});
-      }), delay);
+      timer = setTimeout(() => idle(flush), delay);
+    },
+    /** Stop saving an owner that is gone. */
+    forget(owner) {
+      owners.delete(owner);
     },
   };
 }

package/src/geometry/geometry-cache.js

@@ -3,8 +3,13 @@
 // Geometry is identified by its descriptor key, so identical shapes anywhere
 // in a document (and across live edits of the document) share one entry.
 // Meshes are generated on first use and per level of detail; an entry that is
-// never drawn is never tessellated. Entries unused by the latest scene build
-// are evicted.
+// never drawn is never tessellated.
+//
+// Each build belongs to an owner. A page showing one document has one owner
+// (DOCUMENT), and an entry its latest build did not use is evicted, as before.
+// A stage that shows fragments next to its document builds each of them under
+// an owner of its own (any object), so building one tile does not evict the
+// meshes of the host or of other tiles: an entry goes once no owner holds it.
 
 import { Mesh } from './mesh.js';
 
@@ -27,6 +32,7 @@ export class GeometryEntry {
     // restored from the persistent cache reports them again
     this.reports = new Array(desc.lods).fill(null);
     this.owner = owner; // first element using this geometry (diagnostics)
+    this.owners = new Set(); // build owners holding this entry (GeometryCache.held)
     this.epoch = 0;
     this.useCount = 0;
     this.failed = false;
@@ -34,9 +40,17 @@ export class GeometryEntry {
   }
 }
 
+/** The owner of builds that name none: the one document a page shows. */
+export const DOCUMENT = 'document';
+
 export class GeometryCache {
   constructor() {
     this.entries = new Map();
+    this.held = new Map(); // owner -> Set of the entries its latest build used
+    this.building = null; // owner of the build in progress
+    this.buildSet = null;
+    // called with each entry a level was generated for (the stage stores them per owner)
+    this.onGenerate = null;
     this.quality = 1;
     this.epoch = 0;
     this.version = 0; // bumps when meshes are invalidated
@@ -45,9 +59,15 @@ export class GeometryCache {
     this.onDiagnostic = null;
   }
 
-  beginBuild() {
+  /**
+   * Start a build. Entries acquired until endBuild() belong to `owner`.
+   * @param {*} [owner] DOCUMENT, or any object for a fragment's build
+   */
+  beginBuild(owner = DOCUMENT) {
     this.epoch++;
-    for (const e of this.entries.values()) e.useCount = 0;
+    this.building = owner;
+    this.buildSet = new Set();
+    if (owner === DOCUMENT) for (const e of this.entries.values()) e.useCount = 0;
   }
 
   /** Get or create the entry for a descriptor. */
@@ -56,8 +76,10 @@ export class GeometryCache {
     if (!e) {
       e = new GeometryEntry(desc, owner);
       this.entries.set(desc.key, e);
-    } else if (e.epoch !== this.epoch) {
-      // the descriptor closure may reference a newer AST; keep it current
+    } else if (e.epoch !== this.epoch && !this.heldByOthers(e)) {
+      // the descriptor closure may reference a newer AST; keep it current.
+      // An entry another owner holds keeps its descriptor and owner element,
+      // so its diagnostics stay in that owner's document.
       e.desc = desc;
       e.identity = desc.identity || null;
       e.owner = owner;
@@ -66,14 +88,76 @@ export class GeometryCache {
     }
     e.epoch = this.epoch;
     e.useCount++;
+    if (this.buildSet) this.buildSet.add(e);
     return e;
   }
 
-  /** Drop entries that the latest build did not use. Returns the evicted entries. */
+  heldByOthers(e) {
+    for (const o of e.owners) if (o !== this.building) return true;
+    return false;
+  }
+
+  /**
+   * End a build: its owner now holds exactly the entries it acquired. Entries
+   * no owner holds are dropped. Returns the evicted entries.
+   */
   endBuild() {
+    const owner = this.building === null ? DOCUMENT : this.building;
+    const used = this.buildSet || new Set();
+    const before = this.held.get(owner);
+    this.held.set(owner, used);
+    for (const e of used) e.owners.add(owner);
+    const dropped = [];
+    if (before) {
+      for (const e of before) {
+        if (used.has(e)) continue;
+        e.owners.delete(owner);
+        dropped.push(e);
+      }
+    }
+    this.building = null;
+    this.buildSet = null;
+    // the document's build sweeps the whole cache, as it always has; a
+    // fragment's build only looks at what it held, so it costs what the fragment does
+    if (owner === DOCUMENT) return this.evictUnheld();
+    const evicted = [];
+    for (const e of dropped) {
+      if (e.owners.size === 0 && this.entries.get(e.key) === e) {
+        this.entries.delete(e.key);
+        evicted.push(e);
+      }
+    }
+    return evicted;
+  }
+
+  /**
+   * Forget everything an owner holds (a fragment that was removed or
+   * replaced). Returns the evicted entries.
+   */
+  release(owner) {
+    const set = this.held.get(owner);
+    if (!set) return [];
+    this.held.delete(owner);
+    for (const e of set) e.owners.delete(owner);
+    const evicted = [];
+    for (const e of set) {
+      if (e.owners.size === 0 && this.entries.get(e.key) === e) {
+        this.entries.delete(e.key);
+        evicted.push(e);
+      }
+    }
+    return evicted;
+  }
+
+  /** The entries an owner's latest build used (empty when it has none). */
+  owned(owner = DOCUMENT) {
+    return this.held.get(owner) || new Set();
+  }
+
+  evictUnheld() {
     const evicted = [];
     for (const [k, e] of this.entries) {
-      if (e.epoch !== this.epoch) {
+      if (e.owners.size === 0) {
         this.entries.delete(k);
         evicted.push(e);
       }
@@ -119,6 +203,7 @@ export class GeometryCache {
     this.stats.generateMs += t1 - t0;
     entry.meshes[l] = m;
     entry.reports[l] = reports.length ? reports : null;
+    if (this.onGenerate) this.onGenerate(entry);
     return m;
   }
 

package/src/io/compression.js

@@ -2,7 +2,10 @@
 // (zlib, which also provides brotli). Used for file-size statistics and the
 // benchmark, and for loading .gz files.
 
-const isNode = typeof process !== 'undefined' && !!(process.versions && process.versions.node) && typeof window === 'undefined';
+// The browser bundles (scripts/build-browser.mjs) define __ES3D_BROWSER__ as
+// true, so the Node branch and its zlib import are left out of them.
+const browserBuild = typeof __ES3D_BROWSER__ !== 'undefined' && __ES3D_BROWSER__;
+const isNode = !browserBuild && typeof process !== 'undefined' && !!(process.versions && process.versions.node) && typeof window === 'undefined';
 
 let zlibPromise = null;
 function zlib() {

package/src/io/convert.js

@@ -87,6 +87,16 @@ export function detectKind(name, bytes) {
 }
 
 /** Options of the importers, with their defaults. */
+/** {name, bytes} for each file: a File or Blob is read, a {name, bytes} object passes through. */
+async function readFiles(files) {
+  return Promise.all(Array.from(files || [], async (f) => {
+    // a File has a bytes() method of its own (Blob.bytes), so test for data, not the name
+    if (f && f.bytes && typeof f.bytes === 'object') return f;
+    if (f && typeof f.arrayBuffer === 'function') return { name: f.name || 'file', bytes: new Uint8Array(await f.arrayBuffer()) };
+    throw new TypeError('importFiles takes {name, bytes} objects or File objects.');
+  }));
+}
+
 export const IMPORT_DEFAULTS = {
   svg: { size: 10, depth: 0.04, bevel: 0, strokes: true, base: false },
   mesh: { precision: 'auto', normals: 'auto', uvs: true, smooth: 30 },
@@ -95,11 +105,14 @@ export const IMPORT_DEFAULTS = {
 
 /**
  * Convert input files into an ES3D document.
- * @param {{name: string, bytes: Uint8Array}[]} files the main file plus companions (.mtl, .bin)
+ * @param {Iterable<{name: string, bytes: Uint8Array}|Blob>} files the main file plus companions
+ *   (.mtl, .bin): {name, bytes} objects, or the File objects of an <input type="file">
+ *   or a drop (a FileList works too), which are read here
  * @param {{svg?: object, mesh?: object, stl?: object}} [opts] see IMPORT_DEFAULTS
  * @returns {Promise<{kind: string, name: string, title: string, text: string, warnings: string[], notes: string[]}>}
  */
 export async function importFiles(files, opts = {}) {
+  files = await readFiles(files);
   if (!files.length) throw new Error('No file was given.');
   const list = [];
   for (const f of files) {

package/src/pipeline.js

@@ -34,7 +34,8 @@ export function elementDiagnostic(doc, d) {
 /**
  * Parse, validate, build and flatten a document.
  * @param {string|ArrayBuffer|Uint8Array} input
- * @param {{cache?: GeometryCache, time?: number, progress?: number, maxInstances?: number}} [opts]
+ * @param {{cache?: GeometryCache, owner?: *, time?: number, progress?: number, maxInstances?: number}} [opts]
+ *   owner: whose build this is in a shared cache (GeometryCache.beginBuild); default the document
  */
 export function compile(input, opts = {}) {
   const t0 = now();

package/src/render/compile-worker.js

@@ -0,0 +1,143 @@
+// The stage's compiler thread.
+//
+// The stage is one file. A page that calls stage.prepare() starts a worker
+// from that same file; there it finds itself in a worker and serves compile
+// requests instead of drawing (render/stage.js calls serveCompiler). The
+// worker runs preparePayload (scene/prepared.js): parsing, validation,
+// building, flattening and mesh generation, and sends the result back as
+// transferred buffers.
+//
+// A worker script must come from the page's origin. A stage loaded from a CDN
+// is started through a small module made in the page (a blob URL) that
+// imports the stage by its URL, which the CDN's CORS headers allow. Where
+// neither works (a content security policy without worker-src blob:, an old
+// browser, Node), every request is compiled on the main thread instead, and
+// the page does not need to know.
+
+import { preparePayload } from '../scene/prepared.js';
+import { early, inWorker } from './worker-boot.js';
+
+/** True inside a dedicated worker. */
+export function isWorkerScope() {
+  return inWorker;
+}
+
+// a worker that has not answered its first request by then is given up on
+const FIRST_ANSWER_MS = 10000;
+
+// keys whose meshes this worker sent; capped, so a long session does not grow it forever
+const SENT_LIMIT = 200000;
+
+/**
+ * Answer compile requests posted to this worker.
+ * @param {object} scope the worker's global scope
+ */
+export function serveCompiler(scope) {
+  const sent = new Set();
+  const answer = (e) => {
+    const { id, input, time, progress, quality } = e.data || {};
+    if (sent.size > SENT_LIMIT) sent.clear();
+    let reply;
+    try {
+      reply = preparePayload(input, { time, progress, quality, sent });
+    } catch (err) {
+      scope.postMessage({ id, error: String(err && err.message ? err.message : err) });
+      return;
+    }
+    try {
+      scope.postMessage({ id, ...reply.message }, reply.transfer);
+    } catch (err) {
+      // something in the scene could not be cloned: the main thread compiles it
+      scope.postMessage({ id, ok: reply.message.ok, diagnostics: reply.message.diagnostics, hostOnly: reply.message.hostOnly, timings: reply.message.timings, lineText: reply.message.lineText, lineIndex: reply.message.lineIndex, main: true });
+    }
+  };
+  scope.onmessage = answer;
+  // requests that came while the module was still loading (worker-boot.js)
+  for (const e of early.splice(0)) answer(e);
+}
+
+/** Start a module worker running this file, or null where none can start. */
+function startWorker(url) {
+  if (typeof Worker !== 'function' || !url) return null;
+  const sameOrigin = typeof location === 'undefined' || new URL(url).origin === location.origin;
+  try {
+    if (sameOrigin) return new Worker(url, { type: 'module' });
+  } catch {
+    // fall through to the blob module
+  }
+  try {
+    const blob = new Blob([`import ${JSON.stringify(url)};`], { type: 'text/javascript' });
+    return new Worker(URL.createObjectURL(blob), { type: 'module' });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The page's side: posts documents to the worker and resolves each request
+ * with its payload. A failed worker (it did not load, or it crashed) answers
+ * every waiting and later request with null, which means: compile here.
+ */
+export class CompilerClient {
+  /** @param {string} url this module's file (the stage bundle's import.meta.url) */
+  constructor(url) {
+    this.worker = startWorker(url);
+    this.failed = !this.worker;
+    this.pending = new Map();
+    this.next = 1;
+    if (!this.worker) return;
+    this.answered = false;
+    this.watchdog = 0;
+    this.worker.onmessage = (e) => {
+      const msg = e.data;
+      this.answered = true;
+      clearTimeout(this.watchdog);
+      const done = this.pending.get(msg.id);
+      if (!done) return;
+      this.pending.delete(msg.id);
+      done(msg.error ? null : msg);
+    };
+    const fail = () => {
+      clearTimeout(this.watchdog);
+      this.failed = true;
+      for (const done of this.pending.values()) done(null);
+      this.pending.clear();
+      try { this.worker.terminate(); } catch {}
+    };
+    this.worker.onerror = (e) => {
+      if (e && e.preventDefault) e.preventDefault();
+      fail();
+    };
+    this.worker.onmessageerror = fail;
+    this.fail = fail;
+  }
+
+  /**
+   * @param {string|ArrayBuffer|Uint8Array} input copied to the worker, not transferred
+   * @param {{time?: number, progress?: number, quality?: number}} opts
+   * @returns {Promise<object|null>} the payload, or null: compile on this thread
+   */
+  compile(input, opts) {
+    if (this.failed) return Promise.resolve(null);
+    const id = this.next++;
+    return new Promise((resolve) => {
+      this.pending.set(id, resolve);
+      // a worker that never starts (blocked, or its module failed silently)
+      // must not hold the page's documents: compile them here instead
+      if (!this.answered && !this.watchdog) this.watchdog = setTimeout(() => this.fail(), FIRST_ANSWER_MS);
+      try {
+        this.worker.postMessage({ id, input, time: opts.time, progress: opts.progress, quality: opts.quality });
+      } catch {
+        this.pending.delete(id);
+        resolve(null);
+      }
+    });
+  }
+
+  dispose() {
+    if (this.worker) this.worker.terminate();
+    for (const done of this.pending.values()) done(null);
+    this.pending.clear();
+    this.failed = true;
+  }
+}