@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/runtime/EmitterRegistry.js

@@ -1,286 +1,438 @@
-import { assert } from "../../../../core/assert.js";
-import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
-import {
-    PARTICLE_DATABASE_INITIAL_SIZE,
-    PARTICLE_DATABASE_SPEC,
-    PARTICLE_EMITTER_STATE_TABLE,
-    PARTICLE_EMITTER_TABLE
-} from "../data/PARTICLE_DATABASE_SPEC.js";
-import { PARTICLE_EMITTER_STATE_EMPTY } from "../data/PARTICLE_EMITTER_STATE.js";
-import { PARTICLE_GENERATION_FIRST, particle_generation_next } from "../data/particle_header.js";
-import { create_emitter_record, ParticleEmitter } from "./ParticleEmitter.js";
-import { ProgramArena } from "./ProgramArena.js";
-
-/**
- * Staging for one emitter row. Reused across every write — the table serializes it into its page
- * shadow synchronously, so nothing outlives the call. This is what keeps a frame's flush free of
- * allocation whatever the number of rows it restages.
- */
-const RECORD = create_emitter_record();
-
-/**
- * The emitter set: {@link ParticleEmitter} instances on the CPU, one GPU table row each.
- *
- * Rows live in a {@link GPUDatabase} table ({@link ../data/PARTICLE_DATABASE_SPEC.js}), which is
- * what makes the set editable at runtime. Adding an emitter stages one record; removing one frees
- * its slot for the next add; changing one restages that record and nothing else. Rows are handed
- * out by the table and are stable for an emitter's lifetime — they have to be, because every live
- * particle's record header stores the row of the emitter that spawned it.
- *
- * Reuse of a freed row is made safe by the **generation**: every add takes the next value of one
- * running counter, so no two emitters this registry has ever registered share one, and the
- * particles of a removed emitter — which carry its generation — cannot be mistaken for the new
- * tenant's. The simulate pass kills them on sight; see {@link ../data/particle_header.js}.
- *
- * The GPU-owned per-emitter state is the database's second table, claimed and released here at the
- * emitter's row and never written by the CPU otherwise.
- *
- * Programs are the one thing NOT in the database: they are variable-length and shared, so they go
- * into a packed {@link ProgramArena} buffer and the emitter record carries offsets into it. The arena is
- * append-only and content-deduplicated — two emitters compiled from the same graph land on one
- * program id, which is what the simulation-order bucketing buckets on. Removing an emitter does not
- * reclaim its program: the dense `program_id`s are baked into every other emitter's record, so
- * compacting them would mean rewriting the whole table to save a few hundred words.
- */
-export class EmitterRegistry {
-
-    /**
-     * @type {GPUDatabase}
-     */
-    database;
-
-    /**
-     * Packed instruction + constant buffers for every distinct program in the set.
-     * @type {ProgramArena}
-     */
-    arena = new ProgramArena();
-
-    /**
-     * The live emitters, in no particular order — {@link ParticleEmitter#row} is the identity.
-     * @type {ParticleEmitter[]}
-     */
-    emitters = [];
-
-    /**
-     * The live emitters by table row. Sparse: a freed row reads `undefined` until it is reused.
-     * Rows are small dense integers handed out lowest-free-first, so an array is the right index.
-     *
-     * @type {ParticleEmitter[]}
-     */
-    by_row = [];
-
-    /**
-     * Whether {@link arena} has grown since the instruction/constant buffers were last built. Those
-     * two are monolithic (a program is variable-length, so there is no table to page them into), so
-     * a new program means re-uploading them whole — which is why the arena dedupes by content and
-     * why this is a separate flag from the per-row dirtiness the table tracks.
-     *
-     * @type {boolean}
-     */
-    programs_dirty = true;
-
-    /**
-     * The generation the next add will take.
-     * @type {number}
-     */
-    #generation = PARTICLE_GENERATION_FIRST;
-
-    /**
-     * @param {GPUDevice} device
-     */
-    constructor(device) {
-        assert.defined(device, 'device');
-
-        this.database = new GPUDatabase({
-            device,
-            definition: PARTICLE_DATABASE_SPEC,
-            label: 'Particles / Emitters',
-            initial_data_size_bytes: PARTICLE_DATABASE_INITIAL_SIZE,
-        });
-    }
-
-    /**
-     * The emitter table.
-     * @returns {GPUTypedTable}
-     */
-    get table() {
-        return this.database.get(PARTICLE_EMITTER_TABLE);
-    }
-
-    /**
-     * The GPU-owned state table: one row per emitter, at the emitter's row, claimed and released
-     * here and otherwise the GPU's.
-     * @returns {GPUTypedTable}
-     */
-    get state_table() {
-        return this.database.get(PARTICLE_EMITTER_STATE_TABLE);
-    }
-
-    /**
-     * @returns {number} number of live emitters
-     */
-    get count() {
-        return this.emitters.length;
-    }
-
-    /**
-     * Number of distinct compiled programs — the number of buckets the simulation-order coherence
-     * pass histograms into.
-     *
-     * @returns {number}
-     */
-    get program_count() {
-        return this.arena.program_count;
-    }
-
-    /**
-     * Register an emitter and give it a table row.
-     *
-     * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or a description
-     *        {@link ParticleEmitter.from} accepts
-     * @param {number} [transform_row] the emitter node's row in the scene's `transforms` table, if
-     *        already known; {@link set_transform_row} sets it later otherwise
-     * @returns {ParticleEmitter}
-     */
-    add(config, transform_row = 0) {
-        const emitter = config.isParticleEmitter === true ? config : ParticleEmitter.from(config);
-
-        assert.equal(emitter.row, -1, 'emitter.row — this emitter is already registered');
-
-        const program_count_before = this.arena.program_count;
-
-        emitter.placement = this.arena.add(emitter.effect.program);
-
-        if (this.arena.program_count !== program_count_before) {
-            this.programs_dirty = true;
-        }
-
-        emitter.generation = this.#generation;
-        this.#generation = particle_generation_next(this.#generation);
-
-        emitter.transform_row = transform_row;
-
-        // An emitter given no seed gets one that tells it apart from every other emitter this
-        // registry has seen. Two emitters of one effect are the common case, and an identical seed
-        // makes them the same particles in the same places.
-        if (emitter.seed === 0) {
-            emitter.seed = emitter.generation;
-        }
-
-        // The table picks the slot — the lowest free one, so a removed emitter's row is reused
-        // rather than the id space growing without bound.
-        emitter.row = this.table.add(emitter.write_record(RECORD));
-        emitter.dirty = false;
-
-        // Claim the state row alongside: zeroed, so the first tick starts it over. The CPU never
-        // writes it again — see PARTICLE_EMITTER_STATE.
-        this.state_table.set(emitter.row, PARTICLE_EMITTER_STATE_EMPTY);
-
-        this.emitters.push(emitter);
-        this.by_row[emitter.row] = emitter;
-
-        return emitter;
-    }
-
-    /**
-     * Unregister an emitter and free its table row.
-     *
-     * Its particles are not touched here; they carry its generation, the row they will read is
-     * zero-filled (or a later tenant's, with a different generation), and the simulate pass frees
-     * them the next time it sees them. Retiring an emitter gently — spawn rate to zero, remove once
-     * its particles have died — remains available to an author who wants the tail to play out.
-     *
-     * @param {ParticleEmitter} emitter
-     */
-    remove(emitter) {
-        assert.defined(emitter, 'emitter');
-        assert.equal(emitter.isParticleEmitter, true, 'emitter.isParticleEmitter !== true');
-
-        const position = this.emitters.indexOf(emitter);
-
-        assert.notEqual(position, -1, 'emitter is not registered here');
-
-        // Swap-remove: order carries no meaning, and a splice would allocate.
-        const last = this.emitters.pop();
-
-        if (last !== emitter) {
-            this.emitters[position] = last;
-        }
-
-        this.by_row[emitter.row] = undefined;
-        this.table.remove(emitter.row);
-        this.state_table.remove(emitter.row);
-
-        emitter.row = -1;
-        emitter.generation = 0;
-        emitter.placement = undefined;
-    }
-
-    /**
-     * Look up a live emitter by its table row.
-     *
-     * @param {number} row
-     * @returns {ParticleEmitter|undefined}
-     */
-    get(row) {
-        return this.by_row[row];
-    }
-
-    /**
-     * Point an emitter's record at its node's row in the scene's `transforms` table. The row is
-     * restaged on the next flush.
-     *
-     * @param {ParticleEmitter} emitter
-     * @param {number} transform_row
-     */
-    set_transform_row(emitter, transform_row) {
-        assert.isNonNegativeInteger(transform_row, 'transform_row');
-
-        if (emitter.transform_row === transform_row) {
-            return;
-        }
-
-        emitter.transform_row = transform_row;
-        emitter.dirty = true;
-    }
-
-    /**
-     * Restage the table rows of every emitter whose fields have moved since the last flush.
-     *
-     * Cheap to call every frame: an emitter that has not changed costs one boolean test, and the
-     * table coalesces repeated writes to one row within a frame anyway. Allocates nothing — every
-     * row goes through the one module-static staging record.
-     */
-    flush() {
-        const table = this.table;
-        const emitters = this.emitters;
-        const count = emitters.length;
-
-        for (let i = 0; i < count; i++) {
-            const emitter = emitters[i];
-
-            if (!emitter.dirty) {
-                continue;
-            }
-
-            table.set(emitter.row, emitter.write_record(RECORD));
-            emitter.dirty = false;
-        }
-    }
-
-    /**
-     * The packed program buffer — header, constant pools, code — rebuilt whole.
-     *
-     * Call when {@link programs_dirty}; it clears the flag. The buffer is monolithic (a program is
-     * variable-length, so there is no table to page it into), so this is a full rebuild — the
-     * arena's content deduplication is what keeps it rare (it only grows when an effect the set has
-     * never seen is registered).
-     *
-     * @returns {Uint32Array}
-     */
-    build_program() {
-        this.programs_dirty = false;
-
-        return this.arena.build_program_buffer();
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
+import {
+    PARTICLE_DATABASE_INITIAL_SIZE,
+    PARTICLE_DATABASE_SPEC,
+    PARTICLE_EMITTER_STATE_TABLE,
+    PARTICLE_EMITTER_TABLE
+} from "../data/PARTICLE_DATABASE_SPEC.js";
+import { PARTICLE_EMITTER_STATE_EMPTY } from "../data/PARTICLE_EMITTER_STATE.js";
+import { create_emitter_record, write_emitter_record } from "../data/particle_emitter_record.js";
+import { PARTICLE_GENERATION_FIRST, particle_generation_next } from "../data/particle_header.js";
+import { GPUParticleEmitterContext } from "./GPUParticleEmitterContext.js";
+import { ParticleEmitter } from "./ParticleEmitter.js";
+import { ProgramHeap } from "./ProgramHeap.js";
+
+/**
+ * Staging for one emitter row. Reused across every write — the table serializes it into its page
+ * shadow synchronously, so nothing outlives the call. This is what keeps a frame's flush free of
+ * allocation whatever the number of rows it restages.
+ */
+const RECORD = create_emitter_record();
+
+/**
+ * The emitter set: {@link ParticleEmitter} instances on the CPU, one GPU table row each.
+ *
+ * Rows live in a {@link GPUDatabase} table ({@link ../data/PARTICLE_DATABASE_SPEC.js}), which is
+ * what makes the set editable at runtime. Adding an emitter stages one record; removing one frees
+ * its slot for the next add; changing one restages that record and nothing else. Rows are handed
+ * out by the table and are stable for an emitter's lifetime — they have to be, because every live
+ * particle's record header stores the row of the emitter that spawned it.
+ *
+ * Reuse of a freed row is made safe by the **generation**: every add takes the next value of one
+ * running counter, so no two emitters this registry has ever registered share one, and the
+ * particles of a removed emitter — which carry its generation — cannot be mistaken for the new
+ * tenant's. The simulate pass kills them on sight; see {@link ../data/particle_header.js}.
+ *
+ * **None of that bookkeeping is on the emitter.** An emitter is a scene node and a description of
+ * an effect, with nothing in it that depends on a device; the row, the generation, the program
+ * placement, the node's `transforms` row and the atlas patch are a
+ * {@link ./GPUParticleEmitterContext.js} this registry holds against the emitter and hands out
+ * through {@link EmitterRegistry#context}. Registering an emitter creates one, removing it destroys
+ * one, and an emitter with no context here is an emitter this registry does not have.
+ *
+ * The GPU-owned per-emitter state is the database's second table, claimed and released here at the
+ * emitter's row and never written by the CPU otherwise.
+ *
+ * Programs are the one thing NOT in the database: they are variable-length and shared, so they go
+ * into a packed {@link ProgramHeap} buffer and the emitter record carries offsets into it. The heap
+ * is content-deduplicated and reference-counted — two emitters compiled from the same graph land on
+ * one program id, which is what the simulation-order bucketing buckets on, and the last emitter of
+ * an effect is what releases it.
+ */
+export class EmitterRegistry {
+
+    /**
+     * @type {GPUDatabase}
+     */
+    database;
+
+    /**
+     * Packed instruction + constant buffers for every distinct program in the set.
+     * @type {ProgramHeap}
+     */
+    programs = new ProgramHeap();
+
+    /**
+     * The live emitters, in no particular order — the row in {@link context} is the identity.
+     * @type {ParticleEmitter[]}
+     */
+    emitters = [];
+
+    /**
+     * The live emitters by table row. Sparse: a freed row reads `undefined` until it is reused.
+     * Rows are small dense integers handed out lowest-free-first, so an array is the right index.
+     *
+     * @type {ParticleEmitter[]}
+     */
+    by_row = [];
+
+    /**
+     * Whether {@link programs} has changed since {@link build_program} last packed it. The buffer is
+     * monolithic (a program is variable-length, so there is no table to page it into), so any change
+     * means re-uploading it whole — which is why the heap dedupes by content, and why this is
+     * separate from the per-row dirtiness the table tracks.
+     *
+     * Read off the heap's own version rather than kept as a flag: there is then no path that changes
+     * the programs and forgets to say so.
+     *
+     * @returns {boolean}
+     */
+    get programs_dirty() {
+        return this.programs.version !== this.#built_programs_version;
+    }
+
+    /**
+     * {@link ProgramHeap#version} the last {@link build_program} packed. `-1` for "nothing has been
+     * built yet", which no version reaches.
+     *
+     * @type {number}
+     */
+    #built_programs_version = -1;
+
+    /**
+     * {@link ProgramHeap#placement_version} the rows were last staged against. When the heap repacks,
+     * every program that was already placed moves, so every row built from the old offsets has to be
+     * written again — see {@link flush}.
+     *
+     * @type {number}
+     */
+    #staged_placement_version = 0;
+
+    /**
+     * What this registry knows about each emitter it holds, and the only place any of it exists.
+     *
+     * @type {Map<ParticleEmitter, GPUParticleEmitterContext>}
+     */
+    #contexts = new Map();
+
+    /**
+     * The generation the next add will take.
+     * @type {number}
+     */
+    #generation = PARTICLE_GENERATION_FIRST;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.database = new GPUDatabase({
+            device,
+            definition: PARTICLE_DATABASE_SPEC,
+            label: 'Particles / Emitters',
+            initial_data_size_bytes: PARTICLE_DATABASE_INITIAL_SIZE,
+        });
+    }
+
+    /**
+     * The emitter table.
+     * @returns {GPUTypedTable}
+     */
+    get table() {
+        return this.database.get(PARTICLE_EMITTER_TABLE);
+    }
+
+    /**
+     * The GPU-owned state table: one row per emitter, at the emitter's row, claimed and released
+     * here and otherwise the GPU's.
+     * @returns {GPUTypedTable}
+     */
+    get state_table() {
+        return this.database.get(PARTICLE_EMITTER_STATE_TABLE);
+    }
+
+    /**
+     * @returns {number} number of live emitters
+     */
+    get count() {
+        return this.emitters.length;
+    }
+
+    /**
+     * Number of distinct compiled programs registered.
+     * @returns {number}
+     */
+    get program_count() {
+        return this.programs.program_count;
+    }
+
+    /**
+     * Number of buckets the simulation-order coherence pass histograms into: every live program id
+     * is below it. See {@link ProgramHeap#program_id_capacity}.
+     *
+     * @returns {number}
+     */
+    get program_id_capacity() {
+        return this.programs.program_id_capacity;
+    }
+
+    /**
+     * Register slots the hungriest registered effect needs — a property of the whole set, since
+     * there is one simulate pipeline and it is chosen once. What a caller does with the number (pick
+     * a register backing, refuse the effect, warn an author) is the caller's; see
+     * {@link ProgramHeap#max_register_count}.
+     *
+     * @returns {number}
+     */
+    get max_register_count() {
+        return this.programs.max_register_count;
+    }
+
+    /**
+     * What this registry assigned an emitter: its table row, generation, program placement, the
+     * `transforms` row of its node and its atlas patch.
+     *
+     * `undefined` for an emitter this registry does not hold — which is the way to ask whether one
+     * is live, there being no `-1` on the emitter to read instead.
+     *
+     * @param {ParticleEmitter} emitter
+     * @returns {GPUParticleEmitterContext|undefined}
+     */
+    context(emitter) {
+        return this.#contexts.get(emitter);
+    }
+
+    /**
+     * Register an emitter and give it a table row.
+     *
+     * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or a description
+     *        {@link ParticleEmitter.from} accepts
+     * @param {number} [transform_row] the emitter node's row in the scene's `transforms` table, if
+     *        already known; {@link set_transform_row} sets it later otherwise
+     * @returns {ParticleEmitter}
+     */
+    add(config, transform_row = 0) {
+        const emitter = config.isParticleEmitter === true ? config : ParticleEmitter.from(config);
+
+        assert.equal(this.#contexts.has(emitter), false, 'this emitter is already registered');
+
+        const context = new GPUParticleEmitterContext();
+
+        context.placement = this.programs.acquire(emitter.program);
+
+        context.generation = this.#generation;
+        this.#generation = particle_generation_next(this.#generation);
+
+        context.transform_row = transform_row;
+
+        // The table picks the slot — the lowest free one, so a removed emitter's row is reused
+        // rather than the id space growing without bound.
+        context.row = this.table.add(write_emitter_record(RECORD, emitter, context));
+        context.staged(emitter);
+
+        // Claim the state row alongside: zeroed, so the first tick starts it over. The CPU never
+        // writes it again — see PARTICLE_EMITTER_STATE.
+        this.state_table.set(context.row, PARTICLE_EMITTER_STATE_EMPTY);
+
+        this.#contexts.set(emitter, context);
+        this.emitters.push(emitter);
+        this.by_row[context.row] = emitter;
+
+        return emitter;
+    }
+
+    /**
+     * Unregister an emitter and free its table row.
+     *
+     * Its particles are not touched here; they carry its generation, the row they will read is
+     * zero-filled (or a later tenant's, with a different generation), and the simulate pass frees
+     * them the next time it sees them. Retiring an emitter gently — spawn rate to zero, remove once
+     * its particles have died — remains available to an author who wants the tail to play out.
+     *
+     * The emitter itself comes out of this unchanged: what it loses is its context, which is
+     * everything being registered gave it. Its program goes with the context — the heap counts
+     * references, so an effect is only unpacked when its last emitter leaves.
+     *
+     * @param {ParticleEmitter} emitter
+     */
+    remove(emitter) {
+        assert.defined(emitter, 'emitter');
+        assert.equal(emitter.isParticleEmitter, true, 'emitter.isParticleEmitter !== true');
+
+        const context = this.#contexts.get(emitter);
+
+        assert.defined(context, 'emitter is not registered here');
+
+        const position = this.emitters.indexOf(emitter);
+
+        // Swap-remove: order carries no meaning, and a splice would allocate.
+        const last = this.emitters.pop();
+
+        if (last !== emitter) {
+            this.emitters[position] = last;
+        }
+
+        this.by_row[context.row] = undefined;
+        this.table.remove(context.row);
+        this.state_table.remove(context.row);
+
+        this.programs.release(context.placement);
+
+        context.placement = null;
+
+        this.#contexts.delete(emitter);
+    }
+
+    /**
+     * Give a registered emitter different bytecode to run: its old program loses a reference, the new
+     * one gains one, and its row is restaged with the new placement.
+     *
+     * This is the runtime edit the emitter table has always allowed and the program buffer used not
+     * to — an author reworking an effect in the editor changes the program of an emitter that is
+     * already live, and the effect it used to run goes away with the last emitter that ran it.
+     *
+     * The attribute {@link ../layout/ParticleLayout.js layout} is NOT part of this and must not
+     * change with it: particles already in flight are laid out the old way, and new bytecode reading
+     * them at new offsets would read somebody else's field. Re-laying-out an effect means new
+     * emitters.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
+     */
+    set_program(emitter, program) {
+        assert.defined(program, 'program');
+
+        const context = this.#contexts.get(emitter);
+
+        assert.defined(context, 'emitter is not registered here');
+
+        const previous = context.placement;
+
+        // acquired before the old one is let go, so that re-setting the program an emitter already
+        // runs — which is what an editor does on every keystroke that changes nothing — neither
+        // unpacks it nor gives it a new id
+        context.placement = this.programs.acquire(program);
+
+        emitter.program = program;
+
+        this.programs.release(previous);
+
+        context.invalidate();
+    }
+
+    /**
+     * Look up a live emitter by its table row.
+     *
+     * @param {number} row
+     * @returns {ParticleEmitter|undefined}
+     */
+    get(row) {
+        return this.by_row[row];
+    }
+
+    /**
+     * Point an emitter's record at its node's row in the scene's `transforms` table. The row is
+     * restaged on the next flush.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {number} transform_row
+     */
+    set_transform_row(emitter, transform_row) {
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
+
+        const context = this.#contexts.get(emitter);
+
+        assert.defined(context, 'emitter is not registered here');
+
+        if (context.transform_row === transform_row) {
+            return;
+        }
+
+        context.transform_row = transform_row;
+        context.invalidate();
+    }
+
+    /**
+     * Point an emitter's record at the patch its texture was packed into: uv offset `.xy`, uv scale
+     * `.zw`. The row is restaged on the next flush.
+     *
+     * For whoever owns the atlas to call, on registration and again after every repack — a repack
+     * moves every patch, and an emitter left holding the old one draws the wrong image.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {ArrayLike<number>} region [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
+     */
+    set_atlas_region(emitter, region) {
+        assert.equal(region.length, 4, 'region.length');
+
+        const context = this.#contexts.get(emitter);
+
+        assert.defined(context, 'emitter is not registered here');
+
+        const atlas_region = context.atlas_region;
+
+        if (
+            atlas_region[0] === region[0] && atlas_region[1] === region[1]
+            && atlas_region[2] === region[2] && atlas_region[3] === region[3]
+        ) {
+            return;
+        }
+
+        atlas_region.set(region);
+        context.invalidate();
+    }
+
+    /**
+     * Restage the table rows of every emitter whose fields have moved since the last flush.
+     *
+     * "Moved" is the node's own change counter: an emitter is restaged when its
+     * {@link ../../scene/Node3D.js Node3D#version} is not the one its row was staged from, or when
+     * something in its context changed. So an author marks an edited emitter the way they mark any
+     * edited node, with `needsUpdate = true`, and there is no second flag to forget.
+     *
+     * Cheap to call every frame: an emitter that has not changed costs one integer comparison, and
+     * the table coalesces repeated writes to one row within a frame anyway. Walks the context map
+     * rather than the emitter list so that a pass over the set is not also a lookup per emitter.
+     * Stages through the one module-static record, so a frame's restaging allocates nothing however
+     * many rows it touches.
+     */
+    flush() {
+        const table = this.table;
+
+        const placement_version = this.programs.placement_version;
+
+        // A repack moved every program that was already placed, so every row holds offsets into
+        // where its code used to be. That is the one change no emitter announces — it is not an edit
+        // to any of them — so it is asked of the heap once here rather than pushed onto each context.
+        const relocated = placement_version !== this.#staged_placement_version;
+
+        this.#staged_placement_version = placement_version;
+
+        for (const [emitter, context] of this.#contexts) {
+            if (!relocated && !context.is_stale(emitter)) {
+                continue;
+            }
+
+            table.set(context.row, write_emitter_record(RECORD, emitter, context));
+            context.staged(emitter);
+        }
+    }
+
+    /**
+     * The packed program buffer — header, constant pools, code — rebuilt whole.
+     *
+     * Call when {@link programs_dirty}; it answers the flag. The buffer is monolithic (a program is
+     * variable-length, so there is no table to page it into), so this is a full rebuild — the heap's
+     * content deduplication is what keeps it rare (it changes only when an effect the set has never
+     * seen is registered, or when the sections are repacked to make room for one).
+     *
+     * @returns {Uint32Array}
+     */
+    build_program() {
+        this.#built_programs_version = this.programs.version;
+
+        return this.programs.build_buffer();
+    }
+}