perf(editor): stop repeating work the editor already did

[pythonlearner1025]

What part this touches

Two editor hot paths. They sit in different packages and are independent of each other. Both are the same shape of bug: work the editor already did, done again.

ViewerInstanceManager in packages/editor owns the editor's viewer. It listens to sceneUpdate on the scene. That event fires once per object that changed. Its handler calls changed(), which dispatches stateChange. useManagerVersion turns every stateChange into a setVersion(v => v + 1) for 13 components, including the root App.

scene-diff.ts in packages/kite3d compares the old and new main scene file so the dev server can write a line to the scene journal. The dev server awaits that diff inside the PUT /files/<scene>.gltf handler, so it sits between the editor pressing Save and the response coming back.

The problem

One, the dispatch per object

private onEditSceneUpdate = (event: {object?: IObject3D}) => {
    if (!this.loadingScene && !this.savingScene && event.object) {
        this.loadedNeedsSave = true
    }
    this.changed()
}

Twenty objects changing in one frame produced twenty stateChange dispatches, and twenty rounds of 13 setState calls.

The audit that opened this said the cost was 3.3 ms of React per moved object per frame. That was wrong, and measuring the fix is what caught it. React 18 batches updates that arrive in the same task, so a synchronous burst was already collapsing into one render. Measured on a 2,405 node project, 20 objects moved per synchronous frame: React self time 161.2 ms before against 142.0 ms after, over 40 frames. That is 0.48 ms per frame. With one object moved there is no difference at all.

The real cost is where React cannot batch: updates arriving in separate tasks. Asset loads, watcher reloads and nested asset instantiation all arrive that way. Forty updates in forty separate tasks cost 135.7 ms of React work and 511 ms of total JavaScript.

Two, the material flattened once per property

const properties = new Set([...flattenMaterial(oldMaterial).keys(), ...flattenMaterial(newMaterial).keys()])
const nodes = materialNodes(after, match.after)
for (const property of [...properties].sort()) {
    const oldValue = flattenMaterial(oldMaterial).get(property)
    const newValue = flattenMaterial(newMaterial).get(property)

flattenMaterial recurses the whole material and builds a fresh Map. Calling it inside the loop walks the material once per property compared. A material with P properties is walked 2P times instead of twice.

The audit called this real but cheap. That was also wrong. The audit's synthetic materials put their properties under extras, and flattenMaterial skips extras at the top level:

if (!path && (key === 'name' || key === 'extras')) continue

So the audit benchmarked a loop that never ran. With properties where a real material carries them, 20 materials with 64 properties took 143.94 ms, and with 256 properties 2198.89 ms. That is over two seconds blocking a save.

The fix

Coalesce scene updates to one stateChange per animation frame, keyed on a single pending frame handle.

Cancel that pending frame in dispose(), so a torn down manager cannot dispatch.

Leave every other caller of changed() immediate. Status text, save completion and play transitions are one off, not per object.

Hoist the two flattenMaterial calls out of the property loop into oldFlat and newFlat.

The risk trade

The coalescing costs one frame of latency on the editor's reaction to a scene change. The change itself is applied immediately; only the React re-render waits. A drag already renders at frame rate, so nothing visible moves later than it did.

The failure mode worth naming is coalescing that drops rather than delays. A test covers exactly that: after a single coalesced update, Save Scene must become enabled.

The alternative considered and rejected: move the coalescing inside changed() so every caller benefits. Rejected because status and lifecycle transitions are already one per event, so it would add a frame of latency to messages like "Scene saved" for no gain.

The flattenMaterial hoist has no behaviour to trade. The output is identical, which two of the four new tests assert directly.

On why these ship together: the owner asked for fewer PRs, and this is one two line change plus one seven line change, both removing repeated work on an editor path, both with no behaviour change. If a reviewer prefers them split, the two commits are separable by file with no conflict.

Tests

packages/editor/test/editor/scene-update-coalescing.spec.ts, 2 playwright cases.

• a burst of scene updates in one frame dispatches one stateChange. Without the fix it gets 20, expected 1.
• a coalesced scene update still enables Save Scene. Passes both before and after, by design. It is the guard against coalescing that drops the update.

packages/kite3d/test/scene-diff.test.ts, 4 vitest cases. They pass a material wrapped in a Proxy that counts key enumerations, so the assertion is a call count and not a timing.

• flattens each material once, whatever the property count. Fails without the fix.
• flattens each material once even as the property count grows. Fails without the fix, and takes 129 ms against 1 ms.
• still reports the property that changed, and reports no material change when the two are identical. Both pass before and after. They hold the output fixed across the refactor.

One honest note on method. The first run of the editor tests passed against the unfixed source, because runDev serves the built packages/editor/dist and the revert had not been rebuilt. Rebuilding after the revert produced the real failure, 20 against 1. Every before number below comes from a rebuilt bundle.

Measured, same build on both sides, profiling project of 2,405 nodes, headless Chromium with swiftshader:

measure	before	after
40 updates in separate tasks, React self time	135.7 ms	0 ms
40 updates in separate tasks, total JS	511 ms	76 ms
40 updates in separate tasks, wall	820 ms	546 ms
10 updates in separate tasks, React self time	37.1 ms	3.6 ms
20 objects moved per synchronous frame, React over 40 frames	161.2 ms	142.0 ms
1 object moved per frame	no difference	no difference
diff, 20 materials x 16 properties	10.23 ms	0.98 ms
diff, 20 materials x 64 properties	143.94 ms	2.85 ms
diff, 20 materials x 256 properties	2198.89 ms	12.11 ms
diff, real 88 KB scene with 0 materials	0.91 ms	0.88 ms

Full CI mirrored locally on this branch: build, typecheck, lint, test:kite3d 13 passed, test:editor 10 passed, test:runtime 1 passed.

Deploy

The coalescing ships in @kite3d/editor, which the dev server serves. The hoist ships in kite3d, the CLI and dev server package. Neither touches @kite3d/engine, so published games are unaffected.

npm run build
npm run typecheck
npm run lint
npm run test:kite3d
npm run test:editor
npm run test:runtime

Then the owner's usual release. Users pick it up when they bump kite3d.

Rollback: revert this commit and release again. No data change, no format change, no migration. The scene journal keeps writing the same lines it wrote before.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T623SnndzSVwCSmuQrVRj2