narraleaf-react 0.45.0 → 0.45.1

package/dist/game/player/gameState.d.ts

@@ -436,6 +436,34 @@ export declare class GameState {
     isStateMounted(key: Values<ExposedKeys>): boolean;
     getExposedState<T extends ExposedStateType>(key: ExposedKeys[T]): ExposedState[T] | null;
     getExposedStateForce<T extends ExposedStateType>(key: ExposedKeys[T]): ExposedState[T];
+    /**
+     * Wait for a component to expose its state, then hand it over - **never in the caller's own
+     * task**, and always the state that is on screen when the hand-over happens.
+     *
+     * The waiting branch used to call back straight out of `mountState`, which runs inside the
+     * component's mount effect, and that is what made starting a scene one unbroken synchronous
+     * chain: the action flushes the stage, React commits, the new displayable mounts, this fires,
+     * the action resolves, `next()` runs the following action, which flushes the stage again - one
+     * commit per element, all of it without ever returning to the event loop.
+     *
+     * React counts those: a commit that leaves synchronous work pending on the same root bumps
+     * `nestedUpdateCount`, and at fifty it **throws** `Maximum update depth exceeded` - in
+     * production as well as in development. So a scene was only ever allowed about twenty-five
+     * displayables before the whole player died at its error boundary, with the game silently
+     * never starting. Measured 2026-09-04: a scene of 23 images ran, one of 26 did not.
+     *
+     * Two things follow from handing over a turn later, and both are load-bearing:
+     *
+     * - The turn is taken through {@link yieldToBrowser} rather than a timer. A scene of 44 images
+     *   took **45 seconds** to start through `setTimeout(0)` when its window was not the foreground
+     *   one, because a background window's timers are throttled to about one a second; the boot
+     *   preload gave up first.
+     * - The state is **re-read at hand-over** instead of being taken from the event. React mounts an
+     *   effect, tears it down and mounts it again under `StrictMode`, so what announced itself one
+     *   turn ago can already be the throwaway mount's state, and calling `initDisplayable` on that
+     *   one leaves the action waiting for ever. A hand-over that finds nothing mounted stays
+     *   subscribed and waits for the mount that follows.
+     */
     getExposedStateAsync<T extends ExposedStateType>(key: ExposedKeys[T], onExpose: (state: ExposedState[T]) => void): LiveGameEventToken;
     /**
      * Dispose of the game state

package/dist/game/player/lib/yieldToBrowser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hand a callback to the next turn of the event loop, without a timer.
+ *
+ * Exists because two different things need to be true at once, and `setTimeout(fn, 0)` only manages
+ * one of them:
+ *
+ * - It has to be a **task**, not a microtask. React counts commits that leave synchronous work
+ *   pending on the same root, and throws `Maximum update depth exceeded` at fifty of them - so a
+ *   chain of work driven out of mount effects has to return to the event loop to reset that count.
+ *   Microtasks drain before the loop turns and would not.
+ * - It must not be a **timer**. A window that is not the foreground one has its timers throttled to
+ *   roughly one a second by the browser, so a chain of fifty `setTimeout(0)` hand-overs takes about
+ *   fifty seconds in a background window and milliseconds in a focused one. Measured 2026-09-04:
+ *   starting a scene of 44 images this way timed the boot preload out at 45s.
+ *
+ * A `MessageChannel` message is a task and is not a timer, which is the same reason React's own
+ * scheduler reaches for one. The `setTimeout` fallback is for hosts that have no `MessageChannel`
+ * (a plain Node test run, say), where throttling is not a thing either.
+ *
+ * The returned function cancels the hand-over if it has not happened yet.
+ */
+export declare function yieldToBrowser(callback: () => void): () => void;