@woosh/meep-engine 3.46.0 → 3.49.0

package/src/shade/device/ShadeDeviceFailure.d.ts

@@ -2,12 +2,18 @@
  * Why there is no usable device, in a form a host can act on.
  *
  * It is an `Error` because that is what the failure paths already throw and callers already
- * `catch`, and it carries a {@link ShadeDeviceFailureReason} because a host showing this to a player
+ * `catch`, and it carries a {@link ShadeDeviceFailureReason} because a host showing this to a person
  * needs to distinguish "your browser cannot do this at all" from "your GPU is below what this needs"
  * from "the GPU went away" — three different things to tell somebody, and none of them a stack
  * trace.
  *
- * `detail` holds the specific thing that was missing, for the log rather than the player.
+ * The `message` is written to be shown as it is. Where the specifics are something a person can act
+ * on — which features and limits the hardware lacks, what the browser refused — it names them, so
+ * that what reaches a support thread is the answer rather than a request for logs. `detail` holds
+ * the specifics alone, for a host that phrases its own message.
+ *
+ * Nothing here assumes what the application is: the same engine runs games, CAD tools and product
+ * visualizers, and they all show these messages.
  */
 export class ShadeDeviceFailure extends Error {
     /**
@@ -19,12 +25,13 @@ export class ShadeDeviceFailure extends Error {
      */
     static adapter_unavailable(): ShadeDeviceFailure;
     /**
-     * @param {string} detail what was missing
+     * @param {string[]} unmet every requirement the adapter falls short of, as
+     * {@link shade_device_floor_unmet} phrases them
      * @returns {ShadeDeviceFailure}
      */
-    static below_floor(detail: string): ShadeDeviceFailure;
+    static below_floor(unmet: string[]): ShadeDeviceFailure;
     /**
-     * @param {string} detail
+     * @param {string} detail what the browser said when it refused
      * @returns {ShadeDeviceFailure}
      */
     static device_request_failed(detail: string): ShadeDeviceFailure;

package/src/shade/device/ShadeDeviceFailure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeDeviceFailure.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeDeviceFailure.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IA2BI;;OAEG;IACH,6BAFa,kBAAkB,CAQ9B;IAED;;OAEG;IACH,8BAFa,kBAAkB,CAQ9B;IAED;;;OAGG;IACH,2BAHW,MAAM,GACJ,kBAAkB,CAQ9B;IAED;;;OAGG;IACH,qCAHW,MAAM,GACJ,kBAAkB,CAQ9B;IAED;;;OAGG;IACH,2BAHW,MAAM,GACJ,kBAAkB,CAQ9B;IArED;;;;OAIG;IACH,oBAJW,wBAAwB,WACxB,MAAM,WACN,MAAM,EAQhB;IAxBD;;OAEG;IACH,QAFU,wBAAwB,CAEkB;IAEpD;;;;;OAKG;IACH,QAFU,MAAM,CAEJ;IA0EhB;;;OAGG;IACH,+BAFU,OAAO,CAEgC;CANhD;yCAjGwC,+BAA+B"}
+{"version":3,"file":"ShadeDeviceFailure.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeDeviceFailure.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH;IA2BI;;OAEG;IACH,6BAFa,kBAAkB,CAQ9B;IAED;;OAEG;IACH,8BAFa,kBAAkB,CAQ9B;IAED;;;;OAIG;IACH,0BAJW,MAAM,EAAE,GAEN,kBAAkB,CAU9B;IAED;;;OAGG;IACH,qCAHW,MAAM,GACJ,kBAAkB,CAQ9B;IAED;;;OAGG;IACH,2BAHW,MAAM,GACJ,kBAAkB,CAQ9B;IAxED;;;;OAIG;IACH,oBAJW,wBAAwB,WACxB,MAAM,WACN,MAAM,EAQhB;IAxBD;;OAEG;IACH,QAFU,wBAAwB,CAEkB;IAEpD;;;;;OAKG;IACH,QAFU,MAAM,CAEJ;IA6EhB;;;OAGG;IACH,+BAFU,OAAO,CAEgC;CANhD;yCA1GwC,+BAA+B"}

package/src/shade/device/ShadeDeviceFailure.js

@@ -4,12 +4,18 @@ import { ShadeDeviceFailureReason } from "./ShadeDeviceFailureReason.js";
  * Why there is no usable device, in a form a host can act on.
  *
  * It is an `Error` because that is what the failure paths already throw and callers already
- * `catch`, and it carries a {@link ShadeDeviceFailureReason} because a host showing this to a player
+ * `catch`, and it carries a {@link ShadeDeviceFailureReason} because a host showing this to a person
  * needs to distinguish "your browser cannot do this at all" from "your GPU is below what this needs"
  * from "the GPU went away" — three different things to tell somebody, and none of them a stack
  * trace.
  *
- * `detail` holds the specific thing that was missing, for the log rather than the player.
+ * The `message` is written to be shown as it is. Where the specifics are something a person can act
+ * on — which features and limits the hardware lacks, what the browser refused — it names them, so
+ * that what reaches a support thread is the answer rather than a request for logs. `detail` holds
+ * the specifics alone, for a host that phrases its own message.
+ *
+ * Nothing here assumes what the application is: the same engine runs games, CAD tools and product
+ * visualizers, and they all show these messages.
  */
 export class ShadeDeviceFailure extends Error {
     /**
@@ -44,7 +50,7 @@ export class ShadeDeviceFailure extends Error {
     static webgpu_unavailable() {
         return new ShadeDeviceFailure(
             ShadeDeviceFailureReason.WebGPUUnavailable,
-            "This browser does not support WebGPU, which this game requires.",
+            "This browser does not support WebGPU, which this application requires.",
             "navigator.gpu is undefined"
         );
     }
@@ -61,25 +67,28 @@ export class ShadeDeviceFailure extends Error {
     }
 
     /**
-     * @param {string} detail what was missing
+     * @param {string[]} unmet every requirement the adapter falls short of, as
+     * {@link shade_device_floor_unmet} phrases them
      * @returns {ShadeDeviceFailure}
      */
-    static below_floor(detail) {
+    static below_floor(unmet) {
+        const detail = unmet.join('; ');
+
         return new ShadeDeviceFailure(
             ShadeDeviceFailureReason.BelowFloor,
-            "This graphics hardware is below the minimum this game requires.",
+            `This graphics hardware does not meet this application's minimum requirements: ${detail}.`,
             detail
         );
     }
 
     /**
-     * @param {string} detail
+     * @param {string} detail what the browser said when it refused
      * @returns {ShadeDeviceFailure}
      */
     static device_request_failed(detail) {
         return new ShadeDeviceFailure(
             ShadeDeviceFailureReason.DeviceRequestFailed,
-            "The graphics device could not be created.",
+            `The graphics device could not be created: ${detail}`,
             detail
         );
     }

package/src/shade/device/ShadeDeviceFailureReason.d.ts

@@ -4,7 +4,7 @@
  * The device floor is deliberate and fixed (D6/I-8): there are no degradation tiers, no WebGL
  * fallback and no feature-detection branches. Hardware below the floor is not accommodated — it is
  * told, clearly, that it cannot run this. That makes the *message* the entire below-floor
- * behaviour the engine owes, and a reason code is what lets a host phrase it for a player rather
+ * behaviour the engine owes, and a reason code is what lets a host phrase it for a person rather
  * than showing them a stack trace.
  */
 export type ShadeDeviceFailureReason = number;

package/src/shade/device/ShadeDeviceFailureReason.js

@@ -4,7 +4,7 @@
  * The device floor is deliberate and fixed (D6/I-8): there are no degradation tiers, no WebGL
  * fallback and no feature-detection branches. Hardware below the floor is not accommodated — it is
  * told, clearly, that it cannot run this. That makes the *message* the entire below-floor
- * behaviour the engine owes, and a reason code is what lets a host phrase it for a player rather
+ * behaviour the engine owes, and a reason code is what lets a host phrase it for a person rather
  * than showing them a stack trace.
  *
  * @enum {number}
@@ -23,7 +23,7 @@ export const ShadeDeviceFailureReason = {
 
     /**
      * An adapter exists and is below the floor — a required feature or limit is missing. The
-     * failure names which one.
+     * failure names every one.
      */
     BelowFloor: 2,
 

package/src/shade/device/mock/SoftwareGPUDevice.d.ts

@@ -230,6 +230,21 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase implements GPUDevic
      * @returns {GPUComputePipeline}
      */
     createComputePipeline(descriptor: GPUComputePipelineDescriptor): GPUComputePipeline;
+    /**
+     * The asynchronous form of {@link createRenderPipeline}. There is nothing to compile here, so the
+     * handle is already made when the promise is returned, and the promise is already resolved.
+     *
+     * @param {GPURenderPipelineDescriptor} descriptor
+     * @returns {Promise<GPURenderPipeline>}
+     */
+    createRenderPipelineAsync(descriptor: GPURenderPipelineDescriptor): Promise<GPURenderPipeline>;
+    /**
+     * The asynchronous form of {@link createComputePipeline} — see {@link createRenderPipelineAsync}.
+     *
+     * @param {GPUComputePipelineDescriptor} descriptor
+     * @returns {Promise<GPUComputePipeline>}
+     */
+    createComputePipelineAsync(descriptor: GPUComputePipelineDescriptor): Promise<GPUComputePipeline>;
     /**
      * The next tick. Shared by every query set this device made, so two of them still order against
      * each other.

package/src/shade/device/mock/SoftwareGPUDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA+QA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;OAQG;IACH;QAP+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAuBrC;IAvDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAiCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmJD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;;;;;OAOG;IACH,kEAUC;IAkCD;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WA7sBa,mBAAiB,IAAI;;sCA9QG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}
+{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA+QA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;OAQG;IACH;QAP+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAuBrC;IAvDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAiCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmJD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;;;;;OAOG;IACH,kEAUC;IAkCD;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAED;;;;;;OAMG;IACH,oEAFa,0BAA0B,CAItC;IAED;;;;;OAKG;IACH,sEAFa,2BAA2B,CAIvC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAluBa,mBAAiB,IAAI;;sCA9QG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}

package/src/shade/device/mock/SoftwareGPUDevice.js

@@ -924,6 +924,27 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase {
         return new SoftwareGPUComputePipeline(descriptor);
     }
 
+    /**
+     * The asynchronous form of {@link createRenderPipeline}. There is nothing to compile here, so the
+     * handle is already made when the promise is returned, and the promise is already resolved.
+     *
+     * @param {GPURenderPipelineDescriptor} descriptor
+     * @returns {Promise<GPURenderPipeline>}
+     */
+    createRenderPipelineAsync(descriptor) {
+        return Promise.resolve(new SoftwareGPURenderPipeline(descriptor));
+    }
+
+    /**
+     * The asynchronous form of {@link createComputePipeline} — see {@link createRenderPipelineAsync}.
+     *
+     * @param {GPUComputePipelineDescriptor} descriptor
+     * @returns {Promise<GPUComputePipeline>}
+     */
+    createComputePipelineAsync(descriptor) {
+        return Promise.resolve(new SoftwareGPUComputePipeline(descriptor));
+    }
+
     /**
      * The device's monotonic counter, which is what a timestamp query records here. See
      * {@link SoftwareGPUQuerySet} for why these are not measurements.

package/src/shade/device/pipeline/ComputePipelineManager.d.ts

@@ -2,6 +2,7 @@
  * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
  * @typedef {import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler} ShaderModuleCompiler
  * @typedef {import("./PipelineLayoutManager.js").PipelineLayoutManager} PipelineLayoutManager
+ * @typedef {import("./PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 export class ComputePipelineManager {
     /**
@@ -16,15 +17,34 @@ export class ComputePipelineManager {
      * @returns {PipelineLayoutManager}
      */
     get layouts(): import("./PipelineLayoutManager.js").PipelineLayoutManager;
+    /**
+     * How many pipelines {@link prepare} is still compiling.
+     *
+     * @returns {number}
+     */
+    get pending_count(): number;
     /**
      *
      * @param {ComputePipelineDescriptor} descriptor
      * @returns {GPUComputePipeline}
      */
     obtain(descriptor: ComputePipelineDescriptor): GPUComputePipeline;
+    /**
+     * Compile the pipeline for `descriptor` off the thread that presents frames, into the cache
+     * {@link obtain} reads — see {@link PipelineEnquiry} for why.
+     *
+     * Nothing new starts for a descriptor that is cached or already compiling. A pipeline that fails
+     * is reported and left out of the cache, so `obtain` makes it again the old way. If `obtain`
+     * makes it while it is still compiling here, the one `obtain` made is kept.
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {Promise<void>} settles once the pipeline is cached or has failed; never rejects
+     */
+    prepare(descriptor: ComputePipelineDescriptor): Promise<void>;
     #private;
 }
 export type ComputePipelineDescriptor = import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor;
 export type ShaderModuleCompiler = import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler;
 export type PipelineLayoutManager = import("./PipelineLayoutManager.js").PipelineLayoutManager;
+export type PipelineEnquiry = import("./PipelineEnquiry.js").PipelineEnquiry;
 //# sourceMappingURL=ComputePipelineManager.d.ts.map

package/src/shade/device/pipeline/ComputePipelineManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComputePipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/ComputePipelineManager.js"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH;IA+BI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IAtCD;;;OAGG;IACH,0EAEC;IA8DD;;;;OAIG;IACH,mBAHW,yBAAyB,sBAQnC;;CAEJ;wCAhGY,OAAO,gEAAgE,EAAE,yBAAyB;mCAClG,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB"}
+{"version":3,"file":"ComputePipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/ComputePipelineManager.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;IA+CI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IAtDD;;;OAGG;IACH,0EAEC;IAoBD;;;;OAIG;IACH,4BAEC;IAyDD;;;;OAIG;IACH,mBAHW,yBAAyB,sBAQnC;IAED;;;;;;;;;;OAUG;IACH,oBAHW,yBAAyB,GACvB,QAAQ,IAAI,CAAC,CAwCzB;;CAEJ;wCA1KY,OAAO,gEAAgE,EAAE,yBAAyB;mCAClG,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB;8BAC1D,OAAO,sBAAsB,EAAE,eAAe"}

package/src/shade/device/pipeline/ComputePipelineManager.js

@@ -5,6 +5,7 @@ import { HashMap } from "../../../core/collection/map/HashMap.js";
  * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
  * @typedef {import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler} ShaderModuleCompiler
  * @typedef {import("./PipelineLayoutManager.js").PipelineLayoutManager} PipelineLayoutManager
+ * @typedef {import("./PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 
 export class ComputePipelineManager {
@@ -37,6 +38,22 @@ export class ComputePipelineManager {
      */
     #cache = new HashMap();
 
+    /**
+     * Compilations {@link prepare} started that have not finished.
+     *
+     * @type {HashMap<ComputePipelineDescriptor, Promise<void>>}
+     */
+    #pending = new HashMap();
+
+    /**
+     * How many pipelines {@link prepare} is still compiling.
+     *
+     * @returns {number}
+     */
+    get pending_count() {
+        return this.#pending.size;
+    }
+
 
     /**
      *
@@ -62,18 +79,17 @@ export class ComputePipelineManager {
     /**
      *
      * @param {ComputePipelineDescriptor} descriptor
-     * @returns {GPUComputePipeline}
+     * @returns {GPUComputePipelineDescriptor}
      */
-    #create(descriptor) {
+    #gpu_descriptor(descriptor) {
 
         const shaders = this.#shaders;
 
         const layouts = this.#layouts;
-        const device = this.#device;
 
         const stage = descriptor.compute;
 
-        const gpu_descriptor = {
+        return {
             label: descriptor.label,
             layout: layouts.obtainPipelineLayout(descriptor.layout),
             compute: {
@@ -82,8 +98,15 @@ export class ComputePipelineManager {
                 constants: stage.constants
             },
         };
+    }
 
-        return device.createComputePipeline(gpu_descriptor);
+    /**
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {GPUComputePipeline}
+     */
+    #create(descriptor) {
+        return this.#device.createComputePipeline(this.#gpu_descriptor(descriptor));
     }
 
     /**
@@ -98,4 +121,55 @@ export class ComputePipelineManager {
         return this.#cache.getOrCompute(descriptor, this.#create, this);
     }
 
-}
+    /**
+     * Compile the pipeline for `descriptor` off the thread that presents frames, into the cache
+     * {@link obtain} reads — see {@link PipelineEnquiry} for why.
+     *
+     * Nothing new starts for a descriptor that is cached or already compiling. A pipeline that fails
+     * is reported and left out of the cache, so `obtain` makes it again the old way. If `obtain`
+     * makes it while it is still compiling here, the one `obtain` made is kept.
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {Promise<void>} settles once the pipeline is cached or has failed; never rejects
+     */
+    prepare(descriptor) {
+        assert.defined(descriptor, 'descriptor');
+        assert.equal(descriptor.isComputePipelineDescriptor, true, 'descriptor.isComputePipelineDescriptor !== true');
+
+        const cache = this.#cache;
+
+        if (cache.has(descriptor)) {
+            return Promise.resolve();
+        }
+
+        const pending = this.#pending;
+
+        const existing = pending.get(descriptor);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const gpu_descriptor = this.#gpu_descriptor(descriptor);
+
+        const compilation = this.#device.createComputePipelineAsync(gpu_descriptor).then(
+            (pipeline) => {
+                pending.delete(descriptor);
+
+                if (!cache.has(descriptor)) {
+                    cache.set(descriptor, pipeline);
+                }
+            },
+            (error) => {
+                pending.delete(descriptor);
+
+                console.error(`Failed to create "${descriptor.label}" pipeline: `, error.message, gpu_descriptor);
+            }
+        );
+
+        pending.set(descriptor, compilation);
+
+        return compilation;
+    }
+
+}

package/src/shade/device/pipeline/PipelineEnquiry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
+ */
+/**
+ * The pipelines a renderer is about to draw with, gathered before it draws, so that they can be
+ * compiled all at once and off the thread that presents frames.
+ *
+ * Left to themselves, pipelines are made the first time a frame obtains them, and a browser compiles
+ * a pipeline made that way on the GPU process's main thread, one after another — the thread that also
+ * presents the page. A cold first frame of a single lit cube spent 3.4 s there on 54 pipelines. Made
+ * asynchronously, the same 54 compiled on the browser's worker pool in ~1.0 s, as long as the
+ * slowest of them took.
+ *
+ * Whoever owns a pass puts into this the descriptor that pass will hand to `obtain` — the same
+ * object, or one equal to it — for the configuration it is in now. An offer is speculative: one that
+ * turns out not to be drawn with costs a compile on a worker and nothing more, and a pipeline that
+ * nobody offered is still made the old way, the first time a frame obtains it. Offering the same
+ * pipeline twice is harmless; it compiles once.
+ *
+ * Who answers, and how:
+ * - a `graph_*` pass exports `enquire_<pass>_pipelines(enquiry)` beside itself, offering what it
+ *   dispatches and asking the passes it calls, so each list sits next to the code it predicts;
+ * - an object the renderer already holds when it asks answers through its own `enquirePipelines`;
+ * - a class whose instances come later — one per scene or per view — answers through a static
+ *   `enquirePipelines`, for all of them.
+ */
+export class PipelineEnquiry {
+    /**
+     * @param {GPUDevice} device
+     * @returns {PipelineEnquiry}
+     */
+    static from(device: GPUDevice): PipelineEnquiry;
+    /**
+     * The device the pipelines are for. Some descriptors are built from its limits, which is how an
+     * offer comes out equal to the descriptor the pass builds for itself.
+     *
+     * @type {GPUDevice}
+     */
+    device: GPUDevice;
+    /**
+     * @type {RenderPipelineDescriptor[]}
+     */
+    render: RenderPipelineDescriptor[];
+    /**
+     * @type {ComputePipelineDescriptor[]}
+     */
+    compute: ComputePipelineDescriptor[];
+}
+export type RenderPipelineDescriptor = import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export type ComputePipelineDescriptor = import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor;
+//# sourceMappingURL=PipelineEnquiry.d.ts.map

package/src/shade/device/pipeline/PipelineEnquiry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PipelineEnquiry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/PipelineEnquiry.js"],"names":[],"mappings":"AAEA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAmBI;;;OAGG;IACH,gCAFa,eAAe,CAU3B;IA9BD;;;;;OAKG;IACH,kBAAO;IAEP;;OAEG;IACH,QAFU,wBAAwB,EAAE,CAExB;IAEZ;;OAEG;IACH,SAFU,yBAAyB,EAAE,CAExB;CAehB;uCA3DY,OAAO,8DAA8D,EAAE,wBAAwB;wCAC/F,OAAO,gEAAgE,EAAE,yBAAyB"}

package/src/shade/device/pipeline/PipelineEnquiry.js

@@ -0,0 +1,63 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
+ */
+
+/**
+ * The pipelines a renderer is about to draw with, gathered before it draws, so that they can be
+ * compiled all at once and off the thread that presents frames.
+ *
+ * Left to themselves, pipelines are made the first time a frame obtains them, and a browser compiles
+ * a pipeline made that way on the GPU process's main thread, one after another — the thread that also
+ * presents the page. A cold first frame of a single lit cube spent 3.4 s there on 54 pipelines. Made
+ * asynchronously, the same 54 compiled on the browser's worker pool in ~1.0 s, as long as the
+ * slowest of them took.
+ *
+ * Whoever owns a pass puts into this the descriptor that pass will hand to `obtain` — the same
+ * object, or one equal to it — for the configuration it is in now. An offer is speculative: one that
+ * turns out not to be drawn with costs a compile on a worker and nothing more, and a pipeline that
+ * nobody offered is still made the old way, the first time a frame obtains it. Offering the same
+ * pipeline twice is harmless; it compiles once.
+ *
+ * Who answers, and how:
+ * - a `graph_*` pass exports `enquire_<pass>_pipelines(enquiry)` beside itself, offering what it
+ *   dispatches and asking the passes it calls, so each list sits next to the code it predicts;
+ * - an object the renderer already holds when it asks answers through its own `enquirePipelines`;
+ * - a class whose instances come later — one per scene or per view — answers through a static
+ *   `enquirePipelines`, for all of them.
+ */
+export class PipelineEnquiry {
+    /**
+     * The device the pipelines are for. Some descriptors are built from its limits, which is how an
+     * offer comes out equal to the descriptor the pass builds for itself.
+     *
+     * @type {GPUDevice}
+     */
+    device;
+
+    /**
+     * @type {RenderPipelineDescriptor[]}
+     */
+    render = [];
+
+    /**
+     * @type {ComputePipelineDescriptor[]}
+     */
+    compute = [];
+
+    /**
+     * @param {GPUDevice} device
+     * @returns {PipelineEnquiry}
+     */
+    static from(device) {
+        assert.defined(device, 'device');
+
+        const r = new PipelineEnquiry();
+
+        r.device = device;
+
+        return r;
+    }
+}

package/src/shade/device/pipeline/RenderPipelineManager.d.ts

@@ -1,6 +1,7 @@
 /**
  * @typedef {import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler} ShaderModuleCompiler
  * @typedef {import("./PipelineLayoutManager.js").PipelineLayoutManager} PipelineLayoutManager
+ * @typedef {import("./PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 export class RenderPipelineManager {
     /**
@@ -15,6 +16,12 @@ export class RenderPipelineManager {
      * @returns {PipelineLayoutManager}
      */
     get layouts(): import("./PipelineLayoutManager.js").PipelineLayoutManager;
+    /**
+     * How many pipelines {@link prepare} is still compiling.
+     *
+     * @returns {number}
+     */
+    get pending_count(): number;
     /**
      *
      * @param {RenderPipelineDescriptor} descriptor
@@ -22,9 +29,23 @@ export class RenderPipelineManager {
      * @returns {GPURenderPipeline}
      */
     obtain(descriptor: RenderPipelineDescriptor, actual_color_attachments?: GPUTextureFormat[]): GPURenderPipeline;
+    /**
+     * Compile the pipeline for `descriptor` off the thread that presents frames, into the cache
+     * {@link obtain} reads — see {@link PipelineEnquiry} for why.
+     *
+     * Nothing new starts for a descriptor that is cached or already compiling. A pipeline that fails
+     * is reported and left out of the cache, so `obtain` makes it again the old way and reports it
+     * again. If `obtain` makes it while it is still compiling here, the one `obtain` made is kept.
+     *
+     * @param {RenderPipelineDescriptor} descriptor exactly as {@link obtain} will be asked for it:
+     * after any rewrite for the attachments it is drawn into
+     * @returns {Promise<void>} settles once the pipeline is cached or has failed; never rejects
+     */
+    prepare(descriptor: RenderPipelineDescriptor): Promise<void>;
     #private;
 }
 export type ShaderModuleCompiler = import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler;
 export type PipelineLayoutManager = import("./PipelineLayoutManager.js").PipelineLayoutManager;
+export type PipelineEnquiry = import("./PipelineEnquiry.js").PipelineEnquiry;
 import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
 //# sourceMappingURL=RenderPipelineManager.d.ts.map

package/src/shade/device/pipeline/RenderPipelineManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderPipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/RenderPipelineManager.js"],"names":[],"mappings":"AAKA;;;GAGG;AAGH;IA8BI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IArCD;;;OAGG;IACH,0EAEC;IA2FD;;;;;OAKG;IACH,mBAJW,wBAAwB,6BACxB,kBAAkB,qBAgB5B;;CAEJ;mCAtIY,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB;yCAL9B,8DAA8D"}
+{"version":3,"file":"RenderPipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/RenderPipelineManager.js"],"names":[],"mappings":"AAKA;;;;GAIG;AAGH;IA8CI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IArDD;;;OAGG;IACH,0EAEC;IAoBD;;;;OAIG;IACH,4BAEC;IA4FD;;;;;OAKG;IACH,mBAJW,wBAAwB,6BACxB,kBAAkB,qBAgB5B;IAED;;;;;;;;;;;OAWG;IACH,oBAJW,wBAAwB,GAEtB,QAAQ,IAAI,CAAC,CAuCzB;;CAEJ;mCAtNY,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB;8BAC1D,OAAO,sBAAsB,EAAE,eAAe;yCANlB,8DAA8D"}