fix(): type calls to a model's worker, rebuild what the worker copies

[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 (merged)
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: all of it. #325, the PR below, is merged and this branch is rebased on main, so nothing in the diff belongs to another PR.

Description

PR 2 of 6. _invoke() took any string and any arguments and resolved to any, so every call site cast the result to what it hoped the worker returned. This PR types the call end to end, fixes the bugs the types exposed, and tests the result through a worker.

Typing

• _invoke() only takes names of the worker model's methods, with arguments that match their parameters.
• It is limited to an explicit list, RemoteMethods: the methods the main thread calls. dispose(), which deleted the worker-side model behind the main thread's back, and getItemsByConfig(), which takes a function that can't be copied to a worker, are no longer callable through it.
• The result is typed as Cloned<T>, the structured-clone copy that actually arrives. Methods are dropped from it, so a THREE.Matrix4 is { elements, isMatrix4 } and no longer passes for the real thing.
• With that in place the casts at the call sites go. Where a result is handed out under a named type (ItemData, SpatialTreeItem, the raw data maps), a return annotation keeps the name and is checked against the worker's result. The casts that stay are the index methods' and getMetadata()'s, whose type parameters are the caller's own claim.

Bugs the types exposed (all reproducible on main)

• getItemsGeometry() and getGeometries() returned a transform typed as a THREE.Matrix4 that was a plain object, so calling a Matrix4 method on it threw.
• getHighlight() and getItemsMaterialDefinition() did the same with color and THREE.Color. resetColors() was meant to rebuild it but tested isColor, which the copy keeps, so it never did.
• getSequenced() handed out mergedBoxes (THREE.Box3), geometry transforms and highlight colors as copies too. Each kind of result is now rebuilt through a map keyed by kind, so a new kind can't be left out.
• getBuffer() was cast to ArrayBuffer but resolves to a Uint8Array when compressed, which is the default: new DataView(buffer) type-checked and threw.
• Attribute types were typed as numbers. They are the names the importer writes, such as "IFCLABEL", so a numeric comparison never matched.
• getMetadata() answered null for a model saved without metadata, against its declared type.

Bug the worker tests exposed (also reproducible on main)

• getSequenced("mergedBoxes", …) always resolved to an empty box. The worker passed the selected items' local ids to getBBoxes(), which takes item ids. The types could not catch it, both being numbers.

Public API changes

• AttributeData.type and ItemAttributes.setType() take a string.
• getBuffer() resolves to ArrayBuffer | Uint8Array.
• getSequenced() can resolve to null, for a result kind the worker doesn't know, as its docs say.
• getMetadata() resolves to {} instead of null for a model without metadata. getCRS() still resolves to null without a CRS.
• VirtualFragmentsModel signatures declare what the methods already handle: the highlight and visibility methods accept no ids, meaning every item, and getItemsData() accepts GUIDs.
• MaterialManager.resetColors() is replaced by restoreColor().
• getGlobalTranformsIdsOfItems() is renamed getGlobalTransformsIdsOfItems(). The misspelled name stays on FragmentsModel, SingleThreadedFragmentsModel, IFragmentsModel and EditUtils, marked @deprecated, and calls the renamed one.

Tests

The fixes are tested end to end in fragments-model.worker.test.ts: small_test.frag is loaded and queried through a worker, using the Worker of @vitest/web-worker that vitest.setup.ts already installs. Every message crosses a real MessagePort, so results arrive as structured-clone copies, and the first test asserts exactly that. These replace this PR's earlier tests, which stubbed _invoke() with structuredClone() and so never asked the worker anything.

• 33 queries are asked of the model behind the worker and of a SingleThreadedFragmentsModel on the same file, and must be strictly equal, classes included.
• What the copy flattens comes back rebuilt: Matrix4 from getItemsGeometry(), getGeometries() and an item's geometry, Color from getHighlight() and getItemsMaterialDefinition(), Vector3 and Box3 from positions and boxes.
• Seven result kinds of getSequenced() are compared with the method that returns the same thing.
• After a real edit, with the delta model on a second worker, the moved item's transforms are Matrix4 and moved.

Two limits. The stub runs the worker in the test's own thread, so this tests what copying does, not isolation between threads. The index methods (the fixture has no indexes) and getItemDrawChunks() (it depends on which tiles are loaded) are not covered.

Additional context

Worth a close look:

• Cloned<T> in multithreading/cloned.ts.
• Whether the RemoteMethods list is complete.
• restoreColor() keeps the color components as they are. The worker already converted them from sRGB, and the old fallback would have converted them a second time.
• vitest.worker.ts, the worker the tests give to FragmentsModels. Under the stub a worker runs where window exists, so fragments-thread.ts takes itself for the main thread and doesn't listen; this file listens for it, in one line, and fragments-thread.ts is untouched. The alternative is to have fragments-thread.ts recognize the stub.

14 commits. The first 12 are one change each, and if that is too much for one review they split in two after refactor(): limit _invoke to the worker methods the main thread calls. The last two were added later: fixes moves the tests onto a worker and fixes mergedBoxes, and the last one is the rename.

Tests: 268 pass, 58 of them new (fragments-model.worker.test.ts, cloned.test.ts, get-metadata.test.ts).

---

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

[ShaMan123]

reviewed

[ShaMan123]

ready