Request a render when a SplatMesh finishes loading

[asundqui]

This PR builds on top of #456 , #452 , #451, and #449 and fixes the issue labeled D2 from the earlier draft PR #428. The last commit in this PR is stacked on top. Once the previous PRs are merged I'll rebase this onto main before merging. The delta can be seen here: asundqui/spark@fix-lod-dirty-stall...fix-on-demand-mesh-init

In on-demand rendering, a SplatMesh that finishes loading after the app's last render is never shown. Uninitialized meshes are already part of visibleGenerators (contributing 0 splats), but since we don't observe mesh.initialized, when the file lands the scene stays blank until something else triggers a render. This behavior matches the on-demand docs that lists "SplatMesh finished loading" as an onDirty trigger.

One new browser test was added, which fails before the fix and succeeds with it:

• basic.test.ts: "shows a mesh that finished loading after the last render": holds back the .spz request, renders once while it is held, releases it, then settles without requesting a render. With the fix it drives the render loop and renders the splats, otherwise renders blank.

Normally Harness.settle() will await all SplatMeshes loading, so we add a new option:

• waitForLoads (default true): Wait for all meshes' initialized promises before settling (disabled for this test)

The fix is in SparkRenderer.updateInternal(): the first time a visible SplatMesh is seen uninitialized, request a render when it finishes:

for (const generator of visibleGenerators) {
  if (
    generator instanceof SplatMesh &&
    !generator.isInitialized &&
    !this.initWatched.has(generator)
  ) {
    this.initWatched.add(generator);
    generator.initialized.then(
      () => this.setDirty(),
      () => {}, // load errors are reported by the mesh itself
    );
  }
}

initWatched is a WeakSet so disposed meshes are not retained, and setDirty() is a no-op when a render is already pending, so apps with a render loop see no extra frames. The fix is currently behind a temporary FIX_MESH_INIT_RENDER flag so reviewers can flip it to false to reproduce; it will be removed before merge, as with FIX_LATE_CHUNKS in #452 .

CI browser test result: https://github.com/asundqui/spark/actions/runs/35953568067

Note: @mrxz pointed out in #428 that perhaps it should be the user's responsibility to request a re-render when their splats finish loading using the splatMesh.initialized.then(() => requestRender()); pattern. However, I feel that not doing this automatically is an easy footgun to fix, with a very low cost of potentially rendering extra frames, one per loaded SplatMesh.

[oscarlorentzon]

SplatMesh does not report load errors itself. Could the comment say what the handler prevents instead?

Suggested change

	() => {}, // load errors are reported by the mesh itself
	() => {}, // avoid an unhandled rejection when loading fails

[asundqui]

That's a good point, and the fact that it will suppress the "unhandled rejection" message is perhaps not good. They'd see the fetch error in the console, but they won't see the fact that they didn't handle it... Maybe not a deal breaker but let me explore other ways we could do this maybe with an event...

[asundqui]

@oscarlorentzon I updated the PR to use an "initialized" event instead, so it no longer uses the promise chain and potentially alter what the user sees. Looks clean and tests successfully.

[asundqui]

Rebased after #452 merge. All tests including browser tests still successful.

[mrxz]

Nitpick: can be made readonly

[asundqui]

Okay will add.

[mrxz]

The generator can be removed from the initWatched at this point:

this.initWatched.delete(generator);

[asundqui]

Okay!

[asundqui]

@dmarcos addressed @mrxz 's comments and pushed here.