perf(textures): overlap decode with upload, skip resolveDefaults on cache hit

[chiefcll]

Summary

Two focused performance changes in CoreTextureManager. Both are isolated from the recent correctness fixes that landed in #11 (now on main).

1. processSome — overlap decode with GPU upload

Today the upload loop is await getTextureData(); await uploadTexture() serial. getTextureData() is IO/decode (and for ImageTexture it dispatches to a worker pool), while uploadTexture() is effectively serial because the GL calls block from JS's perspective. Serializing them means the worker pool is mostly idle while we're uploading.

After this change, processSome keeps a small sliding window of in-flight getTextureData() promises:

• Window size = max(1, numImageWorkers) — defaults to 2.
• On each iteration we top up the window before awaiting the upload, so the next decode is already underway across the worker pool while the current texture is uploading.
• State guards check failed/freed both before awaiting (cheap skip) and after (handles freed-during-decode).
• The data-fetch promise has its own .catch inside the window, so a pre-fired rejection can't surface as an unhandled-rejection while it sits queued.
• If the time budget runs out mid-window, unfinished textures go back on the queue. Their getTextureData() will still complete in the background and memoize onto texture.textureData, so the next tick skips straight to upload.

Upload itself stays serial — the goal is to keep the worker pool busy, not to parallelize GL.

2. createTexture — look up cache before resolving defaults

Before: every createTexture call (one per texture-bearing node) allocated a fully-resolved props object via resolveDefaults() even on a cache hit.

After: makeCacheKey runs against raw props first; resolveDefaults only runs on miss. To make this safe, each makeCacheKey had to produce the same key for raw and resolved inputs:

• ImageTexture.makeCacheKey — maxRetryCount default (?? 5) is now inlined alongside the existing premultiplyAlpha default. sh/sw checks tightened from !== null to != null so undefined (raw) matches null (resolved).
• ColorTexture.makeCacheKey — color default (|| 0xffffffff) inlined so { color: 0 } resolves to the same key as the post-defaults form. This was technically a latent inconsistency before — raw input would have produced ColorTexture,0 while resolved input produces ColorTexture,4294967295.

NoiseTexture.makeCacheKey already runs resolveDefaults internally, so it's unaffected. SubTexture and RenderTexture return false from makeCacheKey and are unaffected.

The one external caller of makeCacheKey — resolveParentTexture — passes already-resolved props from an ImageTexture instance. The new key formula is backwards-compatible there.

Why this matters

• (1) is the bigger of the two: on startup-heavy scenes with multiple image workers, today's serial decode-then-upload pattern leaves the worker pool idle most of the time. Overlapping them lets the workers actually do their job.
• (2) is a smaller per-frame allocation win on every node mount, but it adds up.

Test plan

• tsc --noEmit passes
• vitest run — all 96 tests pass
• Verify image loading on a representative startup-heavy scene
• Verify behavior with numImageWorkers: 0 (prefetch window falls back to size 1, sequential like before)
• Verify cache hits for ImageTexture and ColorTexture (e.g., two nodes referencing the same src) still resolve to the same instance

🤖 Generated with Claude Code