@woosh/meep-engine 3.22.0 → 3.23.0

package/src/core/process/ConcurrencyGate.js

@@ -0,0 +1,207 @@
+import { assert } from "../assert.js";
+import BinaryHeap from "../collection/heap/BinaryHeap.js";
+
+/**
+ * Runs at most {@link max_concurrent} tasks at a time, highest priority first across everything
+ * submitted to it.
+ *
+ * The point of putting one of these between a caller and its work is almost never the cap on its
+ * own — a caller can count its own in-flight requests. It is that **one** gate shared by several
+ * callers orders their work against each other. Per-caller caps do not compose: the number a
+ * browser, a CDN or a disk cares about is the total, and a caller that knows about one file cannot
+ * see it. Neither can a per-caller queue say that the second caller's request matters more than the
+ * first caller's, however truthfully their priorities compare.
+ *
+ * Ties are broken arbitrarily. Two tasks submitted at the same priority are, by the only measure the
+ * gate has, equally worth running.
+ *
+ * Nothing here is a new idea in this engine, which is why it ended up here rather than inside any
+ * one of its callers. `AssetManager` has capped concurrent top-level loads on `load_concurrency` for the
+ * same stated reason — keeping network slots free for higher-priority requests — and orders its
+ * pending queue through `get_pending_asset_priority_score`, which negates the priority for exactly
+ * the reason this heap does: `BinaryHeap` pops the lowest score first. `VirtualTextureManager` caps
+ * `max_concurrent_loads` against `#loads_in_flight`. When the virtual-geometry residency layer
+ * wanted the cap a third time and wrote that same negation a second time, it stopped being a detail
+ * of any one caller. The other two keep their own queues anyway, deliberately, and each says why
+ * where its cap is declared; the three paragraphs below are those reasons.
+ *
+ * **Priority is read once, at {@link submit}.** A gate keyed on a number captured at submission is
+ * the wrong shape for work whose importance moves while it waits, or whose priorities were never on
+ * a common scale: `AssetRequestScope.final_priority` is a richer model than a bare number, but it
+ * propagates hierarchically from an asset's requesting scopes and so compares only inside one
+ * hierarchy. For either, keep a queue over live records and re-score it (see below).
+ *
+ * **A task must not wait on another submission to the same gate.** The parent holds a slot while the
+ * child waits for one, so at a full gate that is a deadlock, and the gate cannot detect it: it sees
+ * a task that has not settled. Work that nests needs the parent's slot to cover the child, which
+ * means dispatching the child over the cap — `AssetManager` does exactly that for the requests its
+ * loaders make while servicing a load, and keeps its own queue for it.
+ *
+ * **What it deliberately is not.** There is no cancellation, and no way to drop or re-order a
+ * submission once it is made: a queued entry holds a closure and the gate will eventually run it.
+ * A caller that wants to *discard* pending work — because the page stopped being on screen, or a
+ * coarser mip arrived instead — wants a queue of live records it can filter, drained on its own
+ * clock, not a gate that owns closures. `VirtualTextureManager` drops queued requests untouched for
+ * `queue_stale_window` frames; it is that second thing, and no worse for it.
+ *
+ * Nothing bounds how long a low-priority submission waits. A caller that keeps feeding the gate
+ * higher-priority work will starve it indefinitely, which is what a priority queue means and is
+ * fine for the admission gates named above — where a dropped want is re-derived next frame — and not
+ * fine for work that has to finish eventually.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ConcurrencyGate {
+    /**
+     * @type {number}
+     */
+    #max_concurrent;
+
+    /**
+     * @type {number}
+     */
+    #in_flight = 0;
+
+    /**
+     * Waiting tasks, highest priority first — a min-heap on the negated priority.
+     * @type {BinaryHeap<{priority: number, task: function(): Promise<*>, resolve: function(*): void, reject: function(*): void}>}
+     */
+    #queue = new BinaryHeap((entry) => -entry.priority);
+
+    /**
+     * @type {number}
+     */
+    #admitted = 0;
+
+    /**
+     * @type {number}
+     */
+    #peak_in_flight = 0;
+
+    /**
+     * @param {number} max_concurrent how many tasks may be running at once
+     */
+    constructor(max_concurrent) {
+        assert.isPositiveInteger(max_concurrent, 'max_concurrent');
+
+        this.#max_concurrent = max_concurrent;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get max_concurrent() {
+        return this.#max_concurrent;
+    }
+
+    /**
+     * Raising this starts whatever was already waiting. Lowering it starts nothing and stops
+     * nothing — tasks already running are left to finish, and the gate admits again once they have
+     * drained below the new value.
+     *
+     * @param {number} value
+     */
+    set max_concurrent(value) {
+        assert.isPositiveInteger(value, 'max_concurrent');
+
+        this.#max_concurrent = value;
+
+        this.#pump();
+    }
+
+    /**
+     * @returns {number}
+     */
+    get in_flight() {
+        return this.#in_flight;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get queued() {
+        return this.#queue.size();
+    }
+
+    /**
+     * How many tasks this gate has started. Telemetry.
+     * @returns {number}
+     */
+    get admitted() {
+        return this.#admitted;
+    }
+
+    /**
+     * The most that were ever in flight at once — which should never exceed the cap that was in
+     * force when they started, and is here so that a test can say so rather than assume it.
+     * @returns {number}
+     */
+    get peak_in_flight() {
+        return this.#peak_in_flight;
+    }
+
+    /**
+     * Run a task when there is room, highest priority first.
+     *
+     * The task is never invoked synchronously, even when the gate is empty: it runs from a
+     * microtask, so a task that throws on its first line is a rejected promise here rather than an
+     * exception thrown back at whoever called {@link submit}.
+     *
+     * @template T
+     * @param {number} priority higher runs sooner
+     * @param {function(): Promise<T>} task
+     * @returns {Promise<T>} whatever the task settled to, once it ran
+     */
+    submit(priority, task) {
+        assert.isNumber(priority, 'priority');
+        assert.isFunction(task, 'task');
+
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ priority, task, resolve, reject });
+
+            this.#pump();
+        });
+    }
+
+    /**
+     * Start whatever fits.
+     */
+    #pump() {
+        while (this.#in_flight < this.#max_concurrent && !this.#queue.isEmpty()) {
+            const entry = this.#queue.pop();
+
+            this.#in_flight++;
+            this.#admitted++;
+
+            if (this.#in_flight > this.#peak_in_flight) {
+                this.#peak_in_flight = this.#in_flight;
+            }
+
+            /*
+             Settled through two explicit branches rather than `.finally`, because `.finally` returns
+             a promise of its own and a rejection travelling through it with nothing attached is an
+             unhandled rejection — which at the scale a gate is reached for is not a warning in a
+             log, it is a process that stops.
+            */
+            const settle = () => {
+                this.#in_flight--;
+
+                this.#pump();
+            };
+
+            Promise.resolve().then(() => entry.task()).then(
+                (value) => {
+                    settle();
+
+                    entry.resolve(value);
+                },
+                (error) => {
+                    settle();
+
+                    entry.reject(error);
+                }
+            );
+        }
+    }
+}

package/src/engine/asset/AssetManager.d.ts

@@ -32,6 +32,16 @@ export class AssetManager<CTX> {
      * this can be useful to keep some network slots available for high-priority requests such as UI related ones.
      * Nested requests (made by a loader while servicing another load) are dispatched immediately and never wait
      * on this limit: their parent occupies a slot until they resolve, so queueing them would deadlock.
+     *
+     * Not a `core/process/ConcurrencyGate`, and the three reasons are each on their own decisive.
+     * That gate admits closures it owns and resolves one promise per task; a load here is dispatched
+     * by callback and settles exactly once, reached from several places. Its ordering key is read
+     * once, at submission; the key here is re-read live on every heap sift, because
+     * {@link AssetRequestScope#final_priority} walks the scope chain and a later request joining an
+     * already-queued asset re-scores it in place. And the nested-request bypass dispatches *over*
+     * this limit on purpose, which is the one thing a gate whose whole contract is "never more than
+     * N in flight" cannot express.
+     *
      * @type {number}
      */
     load_concurrency: number;

package/src/engine/asset/AssetManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AssetManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/AssetManager.js"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH;IA4MI;;;;;;OAMG;IACH;QAJwB,OAAO,EAApB,GAAG;QACyB,QAAQ,EAApC,kBAAkB;OAW5B;IA1ND;;;;OAIG;IACH,eAEG;IAEH;;;OAGG;IACH,aAFU,YAAY,gBAAgB,EAAE,YAAY,CAAC,CAER;IAuB7C;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEY;IA4B5B;;;;;;OAMG;IACH,iBAAc;IAEd;;;OAGG;IACH,mBAFU,iBAAiB,CAEiB;IAuI5C,gBAWC;IAED;;;;;;OAMG;IACH,qBALW,OAAO,GAGN,QAAQ,IAAI,CAAC,CAgBxB;IA4ED;;;;;;;OAOG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oCAFa,OAAO,CAOnB;IAED;;OAEG;IACH,cAEC;IAED,8BAEC;IAED;;;;;;;;OAQG;IACH;QALuC,KAAK,GAAjC,iBAAiB;QACC,UAAU,GAA5B,OAAO;QAC2C,QAAQ,GAA1D,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;QACrC,wCAAc,CAc1B;IAED;;;;;;;;;;OAUG;IACH;;;mCANgC,IAAI;kBACzB,CAAC,MAAM,KAAG,KAAK,IAAI;mBACnB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;qBACvC,OAAO;gBACP,iBAAiB;aA8D3B;IAED;;;;;;;OAOG;IACH,gBAJW,MAAM,QACN,MAAM,GACL,OAAO,CAKlB;IAGD;;;;;;;OAOG;IACH,eALW,MAAM,QACN,MAAM,GACJ,OAAO,CAOnB;IAED;;;;;;;OAOG;IACH,eAJW,MAAM,QACN,MAAM,GACL,OAAO,CAMlB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,uBAZW,MAAM,QACN,MAAM,sBACM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,iCAwE9D;IAED;;;;;;;;;;;OAWG;IACH,kBAJW,MAAM,QACN,MAAM,oBAoChB;IAgbD;;;;;;OAMG;IACH,sBAkCC;IAGD;;;;OAIG;IACH,uBAHW,MAAM,GACL,OAAO,CAIlB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,wBAAY,SAAS,CAMjC;IAaD;;;;;;;;;;OAUG;IACH,+BALW,MAAM,qBAEJ,IAAI,CAqBhB;IAED;;;;;;OAMG;IACH,iCALW,MAAM,qBAEJ,OAAO,CAyBnB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,kCAEJ,QAAQ,OAAO,CAAC,CAU5B;IAED;;;;;OAKG;IACH,0BAJW,MAAM,iEAwChB;IAED;;;OAGG;IACH,uBAFW,MAAM,iBAkBhB;IAED;;;;;;;OAOG;IACH,6CAUC;IAED;;;;OAIG;IACH,2BAHW,MAAM,gBAchB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACL,gBAAgB,GAAC,SAAS,CAQrC;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,QACN,MAAM,QAUhB;IAGL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;;CANpC;;;4BA/3C2B,0CAA0C;iCAOrC,uBAAuB;6BAM3B,mBAAmB;kCAFd,6BAA6B;kCAD7B,wBAAwB;4BAE9B,0BAA0B;+BARvB,mDAAmD"}
+{"version":3,"file":"AssetManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/AssetManager.js"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH;IAsNI;;;;;;OAMG;IACH;QAJwB,OAAO,EAApB,GAAG;QACyB,QAAQ,EAApC,kBAAkB;OAW5B;IApOD;;;;OAIG;IACH,eAEG;IAEH;;;OAGG;IACH,aAFU,YAAY,gBAAgB,EAAE,YAAY,CAAC,CAER;IAuB7C;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAFU,MAAM,CAEY;IA4B5B;;;;;;OAMG;IACH,iBAAc;IAEd;;;OAGG;IACH,mBAFU,iBAAiB,CAEiB;IAuI5C,gBAWC;IAED;;;;;;OAMG;IACH,qBALW,OAAO,GAGN,QAAQ,IAAI,CAAC,CAgBxB;IA4ED;;;;;;;OAOG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oCAFa,OAAO,CAOnB;IAED;;OAEG;IACH,cAEC;IAED,8BAEC;IAED;;;;;;;;OAQG;IACH;QALuC,KAAK,GAAjC,iBAAiB;QACC,UAAU,GAA5B,OAAO;QAC2C,QAAQ,GAA1D,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;QACrC,wCAAc,CAc1B;IAED;;;;;;;;;;OAUG;IACH;;;mCANgC,IAAI;kBACzB,CAAC,MAAM,KAAG,KAAK,IAAI;mBACnB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;qBACvC,OAAO;gBACP,iBAAiB;aA8D3B;IAED;;;;;;;OAOG;IACH,gBAJW,MAAM,QACN,MAAM,GACL,OAAO,CAKlB;IAGD;;;;;;;OAOG;IACH,eALW,MAAM,QACN,MAAM,GACJ,OAAO,CAOnB;IAED;;;;;;;OAOG;IACH,eAJW,MAAM,QACN,MAAM,GACL,OAAO,CAMlB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,uBAZW,MAAM,QACN,MAAM,sBACM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,iCAwE9D;IAED;;;;;;;;;;;OAWG;IACH,kBAJW,MAAM,QACN,MAAM,oBAoChB;IAgbD;;;;;;OAMG;IACH,sBAkCC;IAGD;;;;OAIG;IACH,uBAHW,MAAM,GACL,OAAO,CAIlB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,wBAAY,SAAS,CAMjC;IAaD;;;;;;;;;;OAUG;IACH,+BALW,MAAM,qBAEJ,IAAI,CAqBhB;IAED;;;;;;OAMG;IACH,iCALW,MAAM,qBAEJ,OAAO,CAyBnB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,kCAEJ,QAAQ,OAAO,CAAC,CAU5B;IAED;;;;;OAKG;IACH,0BAJW,MAAM,iEAwChB;IAED;;;OAGG;IACH,uBAFW,MAAM,iBAkBhB;IAED;;;;;;;OAOG;IACH,6CAUC;IAED;;;;OAIG;IACH,2BAHW,MAAM,gBAchB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACL,gBAAgB,GAAC,SAAS,CAQrC;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,QACN,MAAM,QAUhB;IAGL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;;CANpC;;;4BAz4C2B,0CAA0C;iCAOrC,uBAAuB;6BAM3B,mBAAmB;kCAFd,6BAA6B;kCAD7B,wBAAwB;4BAE9B,0BAA0B;+BARvB,mDAAmD"}

package/src/engine/asset/AssetManager.js

@@ -101,6 +101,16 @@ export class AssetManager {
      * this can be useful to keep some network slots available for high-priority requests such as UI related ones.
      * Nested requests (made by a loader while servicing another load) are dispatched immediately and never wait
      * on this limit: their parent occupies a slot until they resolve, so queueing them would deadlock.
+     *
+     * Not a `core/process/ConcurrencyGate`, and the three reasons are each on their own decisive.
+     * That gate admits closures it owns and resolves one promise per task; a load here is dispatched
+     * by callback and settles exactly once, reached from several places. Its ordering key is read
+     * once, at submission; the key here is re-read live on every heap sift, because
+     * {@link AssetRequestScope#final_priority} walks the scope chain and a later request joining an
+     * already-queued asset re-scores it in place. And the nested-request bypass dispatches *over*
+     * this limit on purpose, which is the one thing a gate whose whole contract is "never more than
+     * N in flight" cannot express.
+     *
      * @type {number}
      */
     load_concurrency = Infinity;

package/src/engine/graphics/CONTEXT_LOSS_RECOVERY_PLAN.md

@@ -6,8 +6,14 @@ Date: 2026-07-30. Scope: `meep` graphics stack (three.js r136, WebGL2) as consum
 Goal: when the browser drops the WebGL context, detect it, recover in place, and let the player continue —
 no application restart, no reload, no lost session state.
 
-**Status: phases 0–3 implemented and verified.** Phases 4–6 remain (§11). Claims below are tagged
-**[src]** (read from three.js / meep source) or **[measured]** (observed in the browser harness, §10).
+**Status: superseded, kept as the record.** Phases 0–3 were implemented and verified against the
+renderer described here; that renderer — three.js r136 on WebGL2 — has since been removed from the
+repo, and Shade (WebGPU) replaced it. Phases 4–6 (§11) will not be done as written: Shade does not
+recover a lost device at all — `Renderer.on.contextRestored` is documented as never firing, and the
+response to a loss is a message and a reload (`ShadeDeviceFailure.device_lost`) — so the in-place
+recovery this document is about has no successor to port it to. Most links below point into a tree
+that no longer holds these files. Claims are tagged **[src]** (read from three.js / meep source) or
+**[measured]** (observed in the browser harness, §10).
 
 ---
 
@@ -110,18 +116,27 @@ produces the prefiltered radiance; `set_environment_texture` adds the skybox on
 re-bakes and disposes the previous target. `load_and_set_cubemap_v0` now loads the source and hands it
 over instead of baking behind the engine's back.
 
-### 4.3 Raw GL handles and residency bookkeeping — library tier, not in the shipped game
+### 4.3 Raw GL handles and residency bookkeeping — library tier, since deleted
 
-These are `meep` public surface but are not reachable from `makeMirEngineConfig`, so they are correctness
-debt rather than shipping blockers (Phase 6):
+These were `meep` public surface but were not reachable from `makeMirEngineConfig`, so they were
+correctness debt rather than shipping blockers (Phase 6). Every one of them went with the WebGL
+renderer, so the paths are recorded as they stood rather than linked:
 
-| Subsystem | What breaks | File |
+| Subsystem | What breaks | File, as of 2026-07-30 |
 | --- | --- | --- |
-| Virtual texture | page atlas written with `copyTextureToTexture`; CPU residency map still claims pages are valid → garbage tiles forever | [VirtualTexturePage.js:389](src/engine/graphics/texture/virtual/VirtualTexturePage.js:389) |
-| `WebGLTextureAtlas` | same pattern | [WebGLTextureAtlas.js:178](src/engine/graphics/texture/atlas/gpu/WebGLTextureAtlas.js:178) |
-| Node-based particles | raw `gl.createBuffer()` handles + cached `gl`, no invalidation | [GLDataBuffer.js:48](src/engine/graphics/particles/node-based/simulation/GLDataBuffer.js:48), [TransformFeedback.js:414](src/engine/graphics/particles/node-based/simulation/TransformFeedback.js:414) |
-| Hi-Z occlusion | readback of a lost target yields zeroes → whole-frame visibility misclassification | [BatchOcclusionQuery.js:149](src/engine/graphics/render/visibility/hiz/query/BatchOcclusionQuery.js:149) |
-| Impostors | baked atlases are GPU-only | [ImpostorBaker.js](src/engine/graphics/impostors/octahedral/ImpostorBaker.js) |
+| Virtual texture | page atlas written with `copyTextureToTexture`; CPU residency map still claims pages are valid → garbage tiles forever | `src/engine/graphics/texture/virtual/VirtualTexturePage.js:389` |
+| `WebGLTextureAtlas` | same pattern | `src/engine/graphics/texture/atlas/gpu/WebGLTextureAtlas.js:178` |
+| Node-based particles | raw `gl.createBuffer()` handles + cached `gl`, no invalidation | `src/engine/graphics/particles/node-based/simulation/GLDataBuffer.js:48`, `TransformFeedback.js:414` |
+| Hi-Z occlusion | readback of a lost target yields zeroes → whole-frame visibility misclassification | `src/engine/graphics/render/visibility/hiz/query/BatchOcclusionQuery.js:149` |
+| Impostors | baked atlases are GPU-only | `src/engine/graphics/impostors/octahedral/ImpostorBaker.js` |
+
+Virtual texturing is the one row with a live successor — `shade/renderer/texture/virtual/`
+(`VirtualTextureManager` / `VTPageTable` / `VTPhysicalCache`), which keeps a CPU mirror of residency
+just as the old stack did. The concern still does not carry over, because it is a *restore* hazard:
+it needs a frame drawn after the device comes back, reading a residency map that outlived the loss.
+Shade never draws that frame — `Renderer.on.contextRestored` is documented as never firing — and the
+VT stack accordingly has no loss, restore or generation hook anywhere in it. There is nothing to
+re-point this row at.
 
 ### 4.4 Secondary contexts — Phase 4
 
@@ -442,5 +457,7 @@ re-attach `viewport.el` / `graphics.domElement` / styles / size, and re-run fram
 disposal of the old targets. The monitor already supports it — `attach()` resets the loss budget and returns
 to `Live` while keeping the generation counter monotonic. Only worth building on evidence.
 
-**Phase 6 (deferred) — library tier.** VT and GPU-atlas residency invalidation, node-based particle GL
-buffers, Hi-Z, impostor atlases (§4.3). Each is self-contained; do them when the subsystem is next touched.
+**Phase 6 (closed) — library tier.** Not done, and will not be: every subsystem in §4.3 was deleted
+along with the WebGL renderer. The only one with a successor is virtual texturing, and residency
+invalidation does not carry over to it — Shade does not restore a lost device, so there is no frame in
+which a stale residency map could be read (§4.3).

package/src/engine/graphics3/pose/collect_entity_playbacks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Collect what every animation driver is playing on an entity, in the form the
+ * CPU pose evaluator takes.
+ *
+ * Both drivers are asked because either may be the one driving it — a combat
+ * unit runs a state machine, a building runs a clip list — and an entity has
+ * one of them, so the two sets do not overlap in practice. What they hand back
+ * is one entry per clip of the model, silent clips included, because that is
+ * what the GPU's accumulator is summing.
+ *
+ * A free function rather than a private helper of
+ * {@link query_entity_node_world_pose} because M3 gave it a second caller:
+ * cloth's rig path needs the anchor joint's world pose on the CPU for exactly
+ * the reason gameplay needs a socket's, and computing it from a different set
+ * of playbacks would put the garment somewhere the socket is not.
+ *
+ * @param {PosePlayback[]} target appended to; the caller owns its length
+ * @param {EntityManager} entity_manager
+ * @param {number} entity
+ * @returns {void}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function collect_entity_playbacks(target: PosePlayback[], entity_manager: EntityManager, entity: number): void;
+//# sourceMappingURL=collect_entity_playbacks.d.ts.map

package/src/engine/graphics3/pose/collect_entity_playbacks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect_entity_playbacks.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/pose/collect_entity_playbacks.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iDARW,cAAc,yCAEd,MAAM,GACJ,IAAI,CAiBhB"}

package/src/engine/graphics3/pose/collect_entity_playbacks.js

@@ -0,0 +1,40 @@
+import { AnimationGraphSystem } from "../AnimationGraphSystem.js";
+import { AnimationSystem } from "../AnimationSystem.js";
+
+/**
+ * Collect what every animation driver is playing on an entity, in the form the
+ * CPU pose evaluator takes.
+ *
+ * Both drivers are asked because either may be the one driving it — a combat
+ * unit runs a state machine, a building runs a clip list — and an entity has
+ * one of them, so the two sets do not overlap in practice. What they hand back
+ * is one entry per clip of the model, silent clips included, because that is
+ * what the GPU's accumulator is summing.
+ *
+ * A free function rather than a private helper of
+ * {@link query_entity_node_world_pose} because M3 gave it a second caller:
+ * cloth's rig path needs the anchor joint's world pose on the CPU for exactly
+ * the reason gameplay needs a socket's, and computing it from a different set
+ * of playbacks would put the garment somewhere the socket is not.
+ *
+ * @param {PosePlayback[]} target appended to; the caller owns its length
+ * @param {EntityManager} entity_manager
+ * @param {number} entity
+ * @returns {void}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function collect_entity_playbacks(target, entity_manager, entity) {
+    const graphs = entity_manager.getSystem(AnimationGraphSystem);
+
+    if (graphs !== null) {
+        graphs.write_pose_playbacks(target, entity);
+    }
+
+    const clips = entity_manager.getSystem(AnimationSystem);
+
+    if (clips !== null) {
+        clips.write_pose_playbacks(target, entity);
+    }
+}

package/src/engine/graphics3/pose/query_entity_node_world_pose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query_entity_node_world_pose.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/pose/query_entity_node_world_pose.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yGANW,MAAM,aACN,MAAM,GACJ,OAAO,CAwCnB"}
+{"version":3,"file":"query_entity_node_world_pose.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/pose/query_entity_node_world_pose.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yGANW,MAAM,aACN,MAAM,GACJ,OAAO,CAwCnB"}

package/src/engine/graphics3/pose/query_entity_node_world_pose.js

@@ -1,101 +1,74 @@
-import { assert } from "../../../core/assert.js";
-import { PosePlayback } from "../../../shade/renderer/animation/pose/PosePlayback.js";
-import { pose_evaluate_world } from "../../../shade/renderer/animation/pose/pose_evaluate_world.js";
-import { AnimationGraphSystem } from "../AnimationGraphSystem.js";
-import { AnimationSystem } from "../AnimationSystem.js";
-import { MeshSystem } from "../MeshSystem.js";
-
-/**
- * The clip set handed to the evaluator, rebuilt per call from the systems' own entries. Nothing in
- * here outlives the call — the query is on a per-frame path and allocates nothing.
- *
- * @type {PosePlayback[]}
- */
-const PLAYBACKS = [];
-
-/**
- * Where a named part of an entity's model is, in world space.
- *
- * This is the question gameplay asks of an animated model and the only sanctioned way to ask it:
- * where does this projectile leave from, where does that effect anchor, where does the floating UI
- * hang. **The answer is computed, never read back** — GPU readback is a frame late and asynchronous,
- * so an outcome that depended on it would depend on frame pacing, and determinism and replay would
- * go with it: no GPU readback on a gameplay-affecting path.
- *
- * The pose is {@link pose_evaluate_world} over the clips the animation systems are driving: a pure
- * function of (clip set, time, weights), off the same clock the renderer is written from, which is
- * what keeps a socket on the mesh that is drawn.
- *
- * The result carries both its matrix and its components.
- *
- * @param {Transform64} result
- * @param {EntityManager} entity_manager
- * @param {number} entity
- * @param {string} node_name name the asset gave the node — a bone, a socket's bone, an effector
- * @returns {boolean} `false` when there is no such node to answer about: no mesh system is
- * registered, the model has not loaded yet, the entity has none, or the name is not in it. None of
- * the four is an error
- */
-export function query_entity_node_world_pose(result, entity_manager, entity, node_name) {
-    assert.defined(result, 'result');
-    assert.defined(entity_manager, 'entity_manager');
-    assert.isNonNegativeInteger(entity, 'entity');
-    assert.isString(node_name, 'node_name');
-
-    const meshes = entity_manager.getSystem(MeshSystem);
-
-    if (meshes === null) {
-        // nothing draws models here, so nothing holds one to answer about
-        return false;
-    }
-
-    const instance = meshes.instance_of(entity);
-
-    if (instance === null) {
-        return false;
-    }
-
-    const node = instance.nodes.get(node_name);
-
-    if (node === undefined) {
-        return false;
-    }
-
-    const playbacks = PLAYBACKS;
-
-    playbacks.length = 0;
-
-    write_playbacks(playbacks, entity_manager, entity);
-
-    pose_evaluate_world(result, node, playbacks);
-
-    playbacks.length = 0;
-
-    return true;
-}
-
-/**
- * Collect what every animation driver is playing on the entity.
- *
- * Both are asked because either may be the one driving it — a combat unit runs a state machine, a
- * building runs a clip list — and an entity has one of them, so the two sets do not overlap in
- * practice. What they hand back is one entry per clip of the model, silent clips included, because
- * that is what the GPU's accumulator is summing.
- *
- * @param {PosePlayback[]} target
- * @param {EntityManager} entity_manager
- * @param {number} entity
- */
-function write_playbacks(target, entity_manager, entity) {
-    const graphs = entity_manager.getSystem(AnimationGraphSystem);
-
-    if (graphs !== null) {
-        graphs.write_pose_playbacks(target, entity);
-    }
-
-    const clips = entity_manager.getSystem(AnimationSystem);
-
-    if (clips !== null) {
-        clips.write_pose_playbacks(target, entity);
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { PosePlayback } from "../../../shade/renderer/animation/pose/PosePlayback.js";
+import { pose_evaluate_world } from "../../../shade/renderer/animation/pose/pose_evaluate_world.js";
+import { MeshSystem } from "../MeshSystem.js";
+import { collect_entity_playbacks } from "./collect_entity_playbacks.js";
+
+/**
+ * The clip set handed to the evaluator, rebuilt per call from the systems' own entries. Nothing in
+ * here outlives the call — the query is on a per-frame path and allocates nothing.
+ *
+ * @type {PosePlayback[]}
+ */
+const PLAYBACKS = [];
+
+/**
+ * Where a named part of an entity's model is, in world space.
+ *
+ * This is the question gameplay asks of an animated model and the only sanctioned way to ask it:
+ * where does this projectile leave from, where does that effect anchor, where does the floating UI
+ * hang. **The answer is computed, never read back** — GPU readback is a frame late and asynchronous,
+ * so an outcome that depended on it would depend on frame pacing, and determinism and replay would
+ * go with it: no GPU readback on a gameplay-affecting path.
+ *
+ * The pose is {@link pose_evaluate_world} over the clips the animation systems are driving: a pure
+ * function of (clip set, time, weights), off the same clock the renderer is written from, which is
+ * what keeps a socket on the mesh that is drawn.
+ *
+ * The result carries both its matrix and its components.
+ *
+ * @param {Transform64} result
+ * @param {EntityManager} entity_manager
+ * @param {number} entity
+ * @param {string} node_name name the asset gave the node — a bone, a socket's bone, an effector
+ * @returns {boolean} `false` when there is no such node to answer about: no mesh system is
+ * registered, the model has not loaded yet, the entity has none, or the name is not in it. None of
+ * the four is an error
+ */
+export function query_entity_node_world_pose(result, entity_manager, entity, node_name) {
+    assert.defined(result, 'result');
+    assert.defined(entity_manager, 'entity_manager');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.isString(node_name, 'node_name');
+
+    const meshes = entity_manager.getSystem(MeshSystem);
+
+    if (meshes === null) {
+        // nothing draws models here, so nothing holds one to answer about
+        return false;
+    }
+
+    const instance = meshes.instance_of(entity);
+
+    if (instance === null) {
+        return false;
+    }
+
+    const node = instance.nodes.get(node_name);
+
+    if (node === undefined) {
+        return false;
+    }
+
+    const playbacks = PLAYBACKS;
+
+    playbacks.length = 0;
+
+    collect_entity_playbacks(playbacks, entity_manager, entity);
+
+    pose_evaluate_world(result, node, playbacks);
+
+    playbacks.length = 0;
+
+    return true;
+}