PrivateshadowsPrivatecontrollerAbort controller for the in-flight prefetch batch (null when idle).
PrivateinNumber of shadow passes still running in the current batch. A new
prefetch() call is a no-op while this is > 0: a cold LOD level outlives
one playback frame, so letting the in-flight batch finish (each pass
deepens its node's ladder by ~1 level per pass and stores it) — instead of
aborting + restarting every tick — is what lets cached quality climb
across loops. The next free tick re-targets at the current predicted view.
A stall guard (MAX_BATCH_STALL_MS) supersedes a batch that never
settles, so a hung task can't pin this > 0 for the whole session.
Privatebatchperformance.now() when the in-flight batch started (for the stall guard).
PrivatedisposedPrivate ReadonlypinnedEvery S-cache key a shadow pass may have pinned, with the cache it was pinned in (see "Pins" in the module doc). Unpinned + cleared by releaseShadows; an over-approximation is harmless because an unpin of an unpinned or absent key is a no-op.
Private ReadonlyrunningNode paths whose shadow pass is running (see queueVisible).
Private ReadonlyctxFire one background prefetch batch for viewState (the PREDICTED next
view) — one shadow pass per registered node. Fire-and-forget; never await
this from a foreground path.
Persistent across ticks: if the previous batch is still running this is a
no-op (see inFlight). Each shadow pass deepens its node's cached
ladder by ~1 cold level per pass (the budgetMs deadline stops it after
the level it was on, which is stored incrementally) and returns; the next
free tick re-targets at the then-current predicted view. Over successive
playback loops this fills the SliceCache toward full ladders so revisits
hit the fast single-concat path — while the foreground stays responsive.
Full predicted view state (t+1 slice position).
Per-pass LOD time budget. Bounds how far a single pass deepens (≈1 cold level). Progressive loaders store the deepened ladder once, when the pass finishes; an aborted pass (playback end / dataset switch) stores nothing, and the next pass resumes from the last stored depth.
OptionalladderDepth: number | "auto"Shadow-warm the loaders at or under targets for viewState, joining the
in-flight batch rather than waiting for it to finish. For loaders
registered after that batch enumerated its nodes — a partition part
activated for the predicted slice (B4) — which the running batch cannot
reach and the next one would warm a whole tick late, i.e. after the
foreground already loaded the slice cold.
PrivatestartA fresh batch controller (the in-flight gate counts its tasks).
PrivaterunQueue one shadow pass per registered, view-eligible node (restricted to
targets when given) under controller's batch, and count them into the
in-flight gate until they settle.
Optionaltargets: ReadonlySet<string>Abort the in-flight shadow batch. Called by the stall guard, and via releaseShadows on playback end / dispose (NOT on every foreground tick — the batch is meant to persist so background deepening completes). Deliberately keeps the pins: a stall-guard abort happens mid-playback, when the pinned t+1 entries are still about to be consumed.
Abort + dispose all shadow loaders (frees their accumulators) and release every pin their passes placed. Called when playback ends; shadows are rebuilt lazily on the next play.
PrivatereleaseUnpin every key a shadow pass may have pinned (see pinnedKeys).
PrivatetrackRecord the key a shadow pass on path will store (and pin) under, and
announce its in-flight store so a foreground pass for that key can adopt
the result. Returns the release for the in-flight registration.
PrivatequeuePrivateprefetchDerive the per-node state and run one shadow load. Returns a promise that settles when the pass finishes (or is skipped/aborted) so the batch can reopen the inFlight gate; it never rejects (errors are logged).
OptionalladderDepth?: number | "auto"Pinned playback ladder depth, forwarded so the t+1 entry carries the pinned prefix.
PrivategetGet or lazily build the shadow loader for a node.
PrivatedropForget and dispose one shadow whose path is no longer load-eligible.
Lazily-built shadow loaders, keyed by node path (async: progressive factories open zarr subgroups). A failed build is dropped so the next prefetch retries instead of caching the rejection forever.