fix(): key models by an internal uid, dispose synchronously

[ShaMan123]

Part of a stack of six PRs that replaces #305. The branches live in a fork, so GitHub can't chain them: every PR is based on main, and the diff of each one includes the PRs below it. Each PR names the commits that are its own and links a comparison that shows only those. They are meant to merge in the order below, and PRs 2 to 6 stay drafts until the one before them is in.

The work. All model state, on both threads, is keyed by the consumer's modelId, and a modelId can be reused. Late async work of a model that was disposed or replaced (a worker reply, queued tiles, a material transfer, a progress event, an in-flight dispose) therefore lands on the next model loaded under the same ID. The stack gives each model an internal uid that is never reused and routes everything by it, adds load({ signal }) (#173), and types the messages between the threads, where most of the bugs it fixes were hidden behind any.

The stack, bottom to top, in merge order:

1. refactor(): route model calls through _invoke #325 refactor(): route model calls through _invoke: mechanical groundwork, no behavior change
2. fix(): type calls to a model's worker, rebuild what the worker copies #326 fix(): type calls to a model's worker, rebuild what the worker copies
3. feat(): load abort signal + harden the message layer #327 feat(): load abort signal + harden the message layer
4. fix(): key models by an internal uid, dispose synchronously #328 fix(): key models by an internal uid, dispose synchronously: the core fix
5. fix(edit): key editor state by the model's uid #329 fix(edit): key editor state by the model's uid
6. refactor(): type the requests workers send to the main thread #330 refactor(): type the requests workers send to the main thread

Every commit in the stack type-checks and passes the test suite on its own, and each PR builds. The top of the stack matches #305's branch merged with today's main, apart from one fix that merge needs (see PR 4) and two reworded lines.

---

This PR's own diff: its last 3 commits, shown here on their own. The commits before them belong to the PRs below.

Description

PR 4 of 6, the core fix of the stack. Each model gets a uid from a counter in FragmentsModels that is never reused, and all internal routing uses it instead of the modelId:

• messages between the threads;
• worker assignment;
• progress callbacks;
• the tile queue;
• material definitions;
• the worker's mesh cache.

modelId stays the consumer-facing name: models.list, disposeModel() and abort() are still keyed by it. Work addressed to a uid that is no longer live finds no model and is dropped.

dispose() takes effect before it returns. The model leaves models.list and the scene, its worker slot is freed, and later requests to it reject. The returned promise resolves once the worker has deleted the model. The modelId can be loaded again right away.

From the review of #305. The review set one race aside as its own issue: a load that starts before the previous model under the same modelId has finished its dispose round trip. This PR is that fix. The old model finishes its teardown under its own uid, so nothing of it can reach the new one, and messages for a disposed model are dropped before anything can throw.

Bugs fixed (all reproducible on main)

• Dispose a model, then load the same modelId again: the old model's late tiles, materials and progress events were applied to the new one, and the old dispose's threads.delete(modelId) could remove the new model's worker assignment.
• The worker's mesh cache is shared by all models on a worker and was keyed by a hash of the modelId. Two models with the same modelId on one worker read, and evicted, each other's meshes.
• Requests pending on a worker that gets terminated never settled. They reject.
• A FINISH from a disposed model was dropped before it could settle forceUpdateFinish(), and the tile batches its worker still flushed were copied back to it, buffers and all.
• editor.save() reused the old model's materials, which were never tracked for disposal, so they leaked. The new model gets its own.

Behavior changes

• dispose(), disposeModel() and FragmentsModels.dispose() apply their effects synchronously. They still return a promise.
• A load() that fails or is aborted rejects right away. It used to wait for the worker to delete the partial model first, which a synchronous dispose no longer needs.
• A call on a disposed model, for example through an Item or Element kept from before, rejects with model "<modelId>" is disposed. Before, it went to whichever model held the modelId.
• model.modelId no longer reads model.object.name, so renaming the object doesn't change it.
• Worker protocol: messages address models by uid. The worker bundle must match the library version, which FragmentsModels.getWorker() already guarantees.

Internal API changes. These are documented as "don't use directly" but are public on their classes:

• new FragmentsModel({ modelId, uid, meshManager, threads, editor, threadGroup }) takes a single object.
• new Editor(core) no longer takes the connection.
• model.threads.invoke(uid, …), RequestsManager.clean(uid) and FragmentsConnection.delete(uid) take the uid, and the last one returns a promise.
• MaterialManager.releaseModelSlot() is removed.

Aborting is not part of this PR

All of the abort work is in PR 3. In the load and abort code, on both threads, this PR only swaps the key from modelId to uid and makes the dispose call in load()'s error path synchronous.

One fix that isn't in #305

Since #305 was written, main gained a per-model fence for update(true), keyed by request.modelId (7516383). After this PR a FINISH carries uid instead, so that fence would never see its model finish and update(true) would never resolve. Git merges the two changes cleanly and tsc passes, so only a test catches it. The uid commit keys the fence by uid and clears it when the model is removed, and mesh-manager-multi-model-fence.test.ts is ported to uid along with it.

Additional context

Worth a close look:

• The synchronous dispose() contract in FragmentsModel.dispose, DataManager.dispose and FragmentsConnection.delete.
• The fence keys in MeshManager.

The first commit changes the key both threads use to address each other, so it can't be split further: it touches all 34 source files of this PR. The other two commits are small.

Tests: 186 pass, 8 of them new. They cover reloading an ID while its old model is still being deleted and the late messages of a disposed model (load-abort.test.ts), connection deletion and worker termination (fragments-connection.test.ts), and a disposed model's FINISH (mesh-manager-fence.test.ts). None of this has been exercised in a browser with real workers yet.

---

What is the purpose of this pull request?

• Bug fix
• New Feature
• Documentation update
• Other

Before submitting the PR, please make sure you do the following:

• Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
• Follow the Conventional Commits v1.0.0 standard for PR naming (e.g. feat(examples): add hello-world example).
• Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).
• Ideally, include relevant tests that fail without this PR but pass with it.

🤖 Generated with Claude Code