rn-gamekit 0.1.0 → 0.2.0

package/src/react/assets/createGameAssetStore.ts

@@ -10,12 +10,22 @@
  * - `acquire` resolves only with a complete usable lease.
  * - Reference counts keep a shared source alive across leases; the native
  *   handle is disposed exactly once when the final lease releases it.
+ * - Each reference token releases exactly once, decrements its captured
+ *   entry (never a fresh URI lookup), and only removes the cache mapping
+ *   when the mapping still holds that exact entry (GS-ASSET-01/02).
+ * - Each acquisition stage has one cleanup owner: a reference transfers to
+ *   the attempt only after successful validation, so a failed validation
+ *   releases exactly once and never touches another owner's reference.
  * - A failed/abandoned attempt releases every handle it acquired; entries
  *   still leased elsewhere are preserved.
- * - Attempts carry an epoch token: stale completion after retry/unmount is
- *   ignored and can never double-dispose.
+ * - Stale completion after retry/unmount is rejected by the caller's abort
+ *   signal and the store's disposed flag; late decodes dispose their own
+ *   handle without touching a successor entry.
  * - `AbortSignal` detaches an imperative caller immediately; late results
  *   from the underlying work are ignored.
+ * - Abort/disposed state is checked after the final awaited step and before
+ *   the lease is published, so an abort racing completion never surfaces
+ *   a lease for a cancelled request.
  * - Progress is monotonic and counts requested logical resources (a
  *   deduplicated source still counts once per logical descriptor).
  * - The store rejects acquisitions after disposal; disposal is idempotent.
@@ -67,13 +77,12 @@ interface ResourceEntry {
   readonly uri: string;
   handle: NativeImageHandle | undefined;
   inFlight: Promise<NativeImageHandle> | undefined;
-  /** Logical descriptor keys sharing this resolved source. */
-  readonly logicalKeys: Set<string>;
   refCount: number;
 }
 
+/** References owned by one in-progress acquisition (GS-ASSET-04: no epoch
+ * token — staleness is decided by the caller's abort signal, not a counter). */
 interface Attempt {
-  readonly token: number;
   /** Idempotent release closures for every reference this attempt owns. */
   readonly acquired: ResourceRef[];
 }
@@ -138,10 +147,8 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
 } {
   const groups = new Set<string>(Object.keys(manifest));
   const logical = logicalAssetsOf(manifest);
-  const byKey = new Map<string, LogicalAsset>(logical.map((asset) => [asset.key, asset]));
   const resources = new Map<string, ResourceEntry>();
   let disposed = false;
-  let nextAttemptToken = 1;
   /** Per-attempt ownership is explicit: the attempt object is passed through
    * every resolve/decode/validate operation; no shared singleton (R4). */
 
@@ -175,67 +182,63 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
     });
   }
 
-  /** Drop one reference held by a caller that never recorded a logical key. */
-  function dropResourceRef(uri: string): void {
-    const entry = resources.get(uri);
-    if (entry === undefined) {
-      return;
-    }
+  /**
+   * Drop one reference to the captured entry (GS-ASSET-01/02). The entry
+   * object — not a fresh URI lookup — is decremented, and the cache mapping
+   * is removed only when it still holds this exact entry, so a stale token
+   * can never affect a successor generation for the same URI.
+   */
+  function dropResourceRef(entry: ResourceEntry): void {
     entry.refCount -= 1;
     if (entry.refCount <= 0) {
       if (entry.handle !== undefined) {
         entry.handle.dispose();
       }
-      resources.delete(uri);
+      if (resources.get(entry.uri) === entry) {
+        resources.delete(entry.uri);
+      }
     }
   }
 
   /**
-   * Begin one owned reference to a resource. Every waiter — cache miss,
-   * in-flight share, or completed cache hit — goes through this single
-   * accounting path and receives an idempotent release closure (RF5). The
-   * caller must either commit the ref to the attempt or call release()
-   * exactly once; the final release disposes the native handle.
+   * Begin one owned reference to a resource (GS-ASSET-01). Every waiter —
+   * cache miss, in-flight share, or completed cache hit — goes through this
+   * single accounting path and receives a token bound to the exact entry
+   * object. The token releases exactly once: a flag guards the decrement,
+   * so a validation failure (released by its stage) followed by attempt
+   * cleanup (releasing the attempt's tokens) can never double-release.
+   * The caller must either transfer the token to the attempt or let its
+   * owning stage release it exactly once; the final release disposes the
+   * native handle.
    */
-  function beginResourceRef(uri: string): ResourceRef {
+  function beginResourceRef(uri: string): { readonly ref: ResourceRef; readonly entry: ResourceEntry } {
     const existing = resources.get(uri);
-    let entry: ResourceEntry;
     if (existing !== undefined && existing.handle !== undefined) {
       // Completed cache hit.
-      entry = existing;
-      entry.refCount += 1;
-      const handle = existing.handle;
-      return {
-        release: () => dropResourceRef(uri),
-        ready: async () => handle,
-      };
+      existing.refCount += 1;
+      return { ref: idempotentRef(existing), entry: existing };
     }
     if (existing !== undefined && existing.inFlight !== undefined) {
       // Shared in-flight decode.
-      entry = existing;
-      entry.refCount += 1;
-      const shared = existing.inFlight;
-      return {
-        release: () => dropResourceRef(uri),
-        ready: async () => shared,
-      };
+      existing.refCount += 1;
+      return { ref: idempotentRef(existing), entry: existing };
     }
     // Cache miss: this waiter starts the decode.
-    entry = {
+    const entry: ResourceEntry = {
       uri,
       handle: undefined,
       inFlight: undefined,
-      logicalKeys: new Set(),
       refCount: 1,
     };
     resources.set(uri, entry);
     const promise = (async () => {
       const handle = await pipelines.decode(uri);
       // A late completion must never resurrect a disposed store or an entry
-      // whose last waiter aborted while the decode was in flight.
+      // whose last waiter aborted while the decode was in flight. Identity
+      // matters here too: the mapping may now hold a successor entry.
       if (disposed || entry.refCount <= 0) {
         handle.dispose();
-        if (entry.refCount <= 0) {
+        if (entry.refCount <= 0 && resources.get(uri) === entry) {
           resources.delete(uri);
         }
         throw new AssetStoreError('ASSET_ABORTED', [], 'asset acquisition aborted');
@@ -244,36 +247,63 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
       return handle;
     })();
     entry.inFlight = promise;
-    void promise.then(
-      () => {
-        entry.inFlight = undefined;
-      },
-      () => {
+    const cleanup = (): void => {
+      if (entry.inFlight === promise) {
         entry.inFlight = undefined;
-      },
-    );
+      }
+    };
+    promise.then(cleanup, cleanup);
+    const ref = idempotentRef(entry);
+    return { ref, entry };
+  }
+
+  /** One release closure bound to its entry; safe to call repeatedly. */
+  function idempotentRef(entry: ResourceEntry): ResourceRef {
+    let released = false;
+    const ready = async (): Promise<NativeImageHandle> => {
+      if (entry.handle !== undefined) {
+        return entry.handle;
+      }
+      const inFlight = entry.inFlight;
+      if (inFlight === undefined) {
+        throw new AssetStoreError(
+          'ASSET_DECODE_FAILED',
+          [],
+          `resource ${JSON.stringify(entry.uri)} has no decoded handle`,
+        );
+      }
+      return inFlight;
+    };
     return {
-      release: () => dropResourceRef(uri),
-      ready: async () => promise,
+      release: () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        dropResourceRef(entry);
+      },
+      ready,
     };
   }
 
+  /**
+   * Acquire one logical asset (GS-ASSET-01). This stage owns its reference
+   * until successful validation transfers it to the attempt: on any
+   * failure the stage releases exactly once and the token never enters
+   * `attempt.acquired`, so attempt cleanup can never release it again.
+   * Returns the exact entry backing this asset for the lease table.
+   */
   async function acquireOne(
     asset: LogicalAsset,
     attempt: Attempt,
     signal: AbortSignal | undefined,
-  ): Promise<void> {
+  ): Promise<ResourceEntry> {
     const uri = await raceWithAbort(pipelines.resolve(asset.descriptor.source), signal);
     // RF5: the reference token exists before any cancellable await; abort
     // can never leave a positive reference behind.
-    const ref = beginResourceRef(uri);
+    const { ref, entry } = beginResourceRef(uri);
     try {
       const handle = await raceWithAbort(ref.ready(), signal);
-      attempt.acquired.push(ref);
-      const entry = resources.get(uri);
-      if (entry !== undefined) {
-        entry.logicalKeys.add(asset.key);
-      }
       if (asset.descriptor.kind === 'sprite-sheet') {
         validateFrames(
           [asset.group, asset.name, 'frames'],
@@ -282,9 +312,11 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
           handle.height(),
         );
       }
+      // Transfer ownership to the attempt only after validation succeeds.
+      attempt.acquired.push(ref);
+      return entry;
     } catch (error) {
-      // Every failure, abort, and stale completion releases this waiter's
-      // reference exactly once; surviving owners keep theirs.
+      // The single owner releases exactly once; surviving owners keep theirs.
       ref.release();
       throw error;
     }
@@ -321,21 +353,22 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
       return createLease(new Map(), () => undefined);
     }
 
-    const token = nextAttemptToken;
-    nextAttemptToken += 1;
-    const attempt: Attempt = { token, acquired: [] };
+    const attempt: Attempt = { acquired: [] };
 
-    const loaded = new Map<string, string>();
+    const loaded = new Map<string, { readonly asset: LogicalAsset; readonly entry: ResourceEntry }>();
     try {
       let completed = 0;
       const total = requested.length;
       for (const asset of requested) {
         throwIfAborted();
-        await acquireOne(asset, attempt, signal);
-        loaded.set(asset.key, asset.key);
+        const entry = await acquireOne(asset, attempt, signal);
+        loaded.set(asset.key, { asset, entry });
         completed += 1;
         options.onProgress?.(completed / total);
       }
+      // GS-ASSET-02: an abort racing the final step must surface instead of
+      // publishing a lease for a cancelled request.
+      throwIfAborted();
       return createLease(loaded, () => {
         for (const ref of attempt.acquired) {
           ref.release();
@@ -351,17 +384,51 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
     }
   };
 
+  /**
+   * Build one validated loaded value from the exact entry that backed the
+   * acquisition (GS-ASSET-04). The handle is always present: `ready()` only
+   * resolves after the entry's handle is set.
+   */
+  function loadedValueFor(asset: LogicalAsset, entry: ResourceEntry): LoadedImage | LoadedSpriteSheet {
+    const handle = entry.handle;
+    if (handle === undefined) {
+      // Defensive: reachable only if the store's own accounting is broken.
+      // Fail clearly rather than publishing an imageless loaded value.
+      throw new AssetStoreError(
+        'ASSET_DECODE_FAILED',
+        [asset.group, asset.name],
+        `resource ${JSON.stringify(entry.uri)} resolved without a decoded handle`,
+      );
+    }
+    if (asset.descriptor.kind === 'image') {
+      return {
+        descriptor: asset.descriptor,
+        width: handle.width(),
+        height: handle.height(),
+        image: handle,
+      };
+    }
+    return {
+      descriptor: asset.descriptor,
+      frames: asset.descriptor.frames,
+      width: handle.width(),
+      height: handle.height(),
+      image: handle,
+    };
+  }
+
   function createLease(
-    loadedKeys: ReadonlyMap<string, string>,
+    loaded: ReadonlyMap<string, { readonly asset: LogicalAsset; readonly entry: ResourceEntry }>,
     onDispose: () => void,
   ): GameAssetLease<TManifest> {
     let leaseDisposed = false;
-    const loaded = new Map<string, LogicalAsset>();
-    for (const key of loadedKeys.keys()) {
-      const asset = byKey.get(key);
-      if (asset !== undefined) {
-        loaded.set(key, asset);
-      }
+    // GS-ASSET-04: the lease holds a direct descriptor→validated value
+    // table built once from the captured entries. Lookup is a single map
+    // hit: no per-get scans of loaded descriptors or resource key sets,
+    // and no wrapper allocated per call.
+    const table = new Map<ImageDescriptor | SpriteSheetDescriptor, LoadedImage | LoadedSpriteSheet>();
+    for (const { asset, entry } of loaded.values()) {
+      table.set(asset.descriptor, loadedValueFor(asset, entry));
     }
     const assets: LoadedAssets<TManifest> = {
       manifest,
@@ -372,8 +439,8 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
         if (leaseDisposed) {
           throw new AssetStoreError('ASSET_STORE_DISPOSED', [], 'lease is disposed');
         }
-        const entry = findLoadedFor(descriptor, loaded);
-        if (entry === undefined) {
+        const value = table.get(descriptor as ImageDescriptor | SpriteSheetDescriptor);
+        if (value === undefined) {
           // R9: v1 lookup is descriptor-reference membership — the exact
           // descriptor object the manifest declared — not a nominal manifest
           // identity. Identically shaped manifests share the structural type,
@@ -385,7 +452,7 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
             'descriptor is not a reference declared by this manifest and group selection',
           );
         }
-        return entry as TDescriptor extends { readonly kind: 'sprite-sheet' }
+        return value as TDescriptor extends { readonly kind: 'sprite-sheet' }
           ? LoadedSpriteSheet
           : LoadedImage;
       },
@@ -402,40 +469,6 @@ export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
     };
   }
 
-  function findLoadedFor(
-    descriptor: ImageDescriptor | SpriteSheetDescriptor,
-    loaded: ReadonlyMap<string, LogicalAsset>,
-  ): unknown {
-    for (const asset of loaded.values()) {
-      if (asset.descriptor === descriptor) {
-        const entry = entryFor(asset.key);
-        const handle = entry?.handle;
-        const width = handle?.width() ?? 0;
-        const height = handle?.height() ?? 0;
-        if (asset.descriptor.kind === 'image') {
-          return { descriptor: asset.descriptor, width, height, image: handle };
-        }
-        return {
-          descriptor: asset.descriptor,
-          frames: asset.descriptor.frames,
-          width,
-          height,
-          image: handle,
-        };
-      }
-    }
-    return undefined;
-  }
-
-  function entryFor(logicalKey: string): ResourceEntry | undefined {
-    for (const entry of resources.values()) {
-      if (entry.logicalKeys.has(logicalKey)) {
-        return entry;
-      }
-    }
-    return undefined;
-  }
-
   return {
     acquire,
     dispose: () => {

package/src/react/assets/useGameAssets.ts

@@ -13,12 +13,18 @@
  * Lifecycle:
  * - The requested group list is normalized (sorted) so a recreated
  *   equivalent array does not reload.
+ * - Every render executes all hooks unconditionally; when the rendered
+ *   request differs from the state's request, the hook exposes a fresh
+ *   loading view synchronously instead of a stale ready lease (GS-ASSET-03).
+ * - Request identity combines manifest identity, factory identity,
+ *   normalized groups, and retry attempt, so a new manifest with identical
+ *   group names can never expose the previous manifest's lease.
  * - Retry starts a new attempt; late completion from an older attempt can
  *   never replace the new state.
  * - Unmount invalidates the attempt, releases the lease, and disposes the
  *   store — hook-owned resources are released exactly once.
  */
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { GameAssetError } from '../../assets/errors';
 import type { AssetGroupMap, GameAssetLease, LoadedAssets } from '../../assets/types';
@@ -59,6 +65,23 @@ export function dedupeGroups(groups: readonly string[]): readonly string[] {
   return [...new Set(groups)].sort();
 }
 
+/** Stable numeric identities for request participants (GS-ASSET-03): object
+ * identity, so a new manifest object with identical group names is a new
+ * request even when every group string matches. */
+const manifestIdentities = new WeakMap<object, number>();
+const factoryIdentities = new WeakMap<object, number>();
+let nextParticipantId = 1;
+
+function participantId(table: WeakMap<object, number>, value: object): number {
+  let id = table.get(value);
+  if (id === undefined) {
+    id = nextParticipantId;
+    nextParticipantId += 1;
+    table.set(value, id);
+  }
+  return id;
+}
+
 /** Order-independent group key: equivalent arrays map to one key. */
 export function stableGroupsKey(groups: readonly string[]): string {
   return dedupeGroups(groups).join('\u0000');
@@ -71,11 +94,22 @@ export function useGameAssets<TManifest extends AssetGroupMap>(
 ): GameAssetsState<TManifest> {
   const groupsKey = stableGroupsKey(options.groups);
   const [attempt, setAttempt] = useState(0);
+  // A memoized normalized array: stable across equivalent recreated group
+  // arrays, so the effect below never reloads for one (R6).
+  const normalizedGroups = useMemo(() => dedupeGroups(options.groups), [groupsKey]);
+  // `??` selects a reference, never a new closure, so the default factory
+  // keeps a stable identity across renders.
+  const factory = storeFactory ?? defaultStoreFactory;
+  // GS-ASSET-03/04: the full request identity. Manifest and factory use
+  // object identity; groups are normalized; the attempt drives retries.
+  const requestKey =
+    `${participantId(manifestIdentities, manifest)}:` +
+    `${participantId(factoryIdentities, factory)}:${groupsKey}:${attempt}`;
   const [state, setState] = useState<GameAssetsState<TManifest>>({
     status: 'loading',
     progress: 0,
     retry: () => undefined,
-    requestKey: groupsKey,
+    requestKey,
   });
   const storeRef = useRef<HookStore<TManifest> | undefined>(undefined);
   const leaseRef = useRef<GameAssetLease<TManifest> | undefined>(undefined);
@@ -85,27 +119,17 @@ export function useGameAssets<TManifest extends AssetGroupMap>(
     setAttempt((current) => current + 1);
   }, []);
 
-  // Ref mirror of the attempt so stale-effect completions are rejected
-  // after a retry re-renders with a higher attempt.
-  const attemptRef = useRef(attempt);
-  attemptRef.current = attempt;
-
-  // RF7: if the rendered request differs from the state's request, expose
-  // loading synchronously instead of the previous ready lease — the old
-  // lease is disposed by the effect cleanup, so no consumer can observe it
-  // under the new request.
-  if (state.requestKey !== groupsKey && state.status === 'ready') {
-    return { status: 'loading', progress: 0, retry, requestKey: groupsKey };
-  }
-
   useEffect(() => {
-    const store = (storeFactory ?? defaultStoreFactory)(manifest);
+    const store = factory(manifest);
     storeRef.current = store;
+    // Per-effect invalidation (GS-ASSET-03): cleanup sets `disposed` before
+    // any newer effect runs, so stale completions are rejected without a
+    // render-time ref mutation standing in for ownership.
     let disposed = false;
-    const attemptAtStart = attempt;
-    const isCurrent = (): boolean => attemptRef.current === attemptAtStart;
-    const setIfCurrent = (updater: (previous: GameAssetsState<TManifest>) => GameAssetsState<TManifest>): void => {
-      if (!disposed && isCurrent()) {
+    const setIfCurrent = (
+      updater: (previous: GameAssetsState<TManifest>) => GameAssetsState<TManifest>,
+    ): void => {
+      if (!disposed) {
         setState(updater);
       }
     };
@@ -118,38 +142,40 @@ export function useGameAssets<TManifest extends AssetGroupMap>(
       status: 'loading',
       progress: 0,
       retry: retry,
-      requestKey: groupsKey,
+      requestKey,
     });
 
     store
       .acquire({
-        groups: dedupeGroups(options.groups),
+        groups: normalizedGroups,
         signal: controller.signal,
         onProgress: (progress) => {
           setIfCurrent((previous) =>
-            previous.status === 'loading' ? { ...previous, progress } : previous,
+            previous.status === 'loading' && previous.requestKey === requestKey
+              ? { ...previous, progress }
+              : previous,
           );
         },
       })
       .then((lease) => {
-        if (disposed || !isCurrent()) {
+        if (disposed) {
           // Stale completion (retry/unmount): release immediately.
           lease.dispose();
           return;
         }
         leaseRef.current?.dispose();
         leaseRef.current = lease;
-        setState({ status: 'ready', assets: lease.assets, requestKey: groupsKey });
+        setState({ status: 'ready', assets: lease.assets, requestKey });
       })
       .catch((error: unknown) => {
-        if (disposed || !isCurrent()) {
+        if (disposed) {
           return;
         }
         const structured =
           error instanceof GameAssetError
             ? error
             : new GameAssetError('ASSET_DECODE_FAILED', [], error instanceof Error ? error.message : String(error));
-        setState({ status: 'error', error: structured, retry, requestKey: groupsKey });
+        setState({ status: 'error', error: structured, retry, requestKey });
       });
 
     return () => {
@@ -162,10 +188,16 @@ export function useGameAssets<TManifest extends AssetGroupMap>(
       storeRef.current = undefined;
       store.dispose();
     };
-    // The groups key is order-independent, so a recreated equivalent array
-    // does not reload; the attempt state drives retries. The store factory
-    // is the internal test seam and must be stable across renders.
-  }, [attempt, groupsKey, manifest, storeFactory]);
+    // The effect re-runs only when the request identity (or its stable
+    // derivatives) changes; equivalent recreated group arrays do not reload.
+  }, [requestKey, manifest, factory, normalizedGroups, groupsKey, retry]);
+
+  // GS-ASSET-03: every hook above runs unconditionally. When the rendered
+  // request differs from the state's request, expose a fresh loading view
+  // synchronously — never a stale ready lease, error, or progress.
+  if (state.requestKey !== requestKey) {
+    return { status: 'loading', progress: 0, retry, requestKey };
+  }
 
   return state;
 }

package/src/react/bindAppLifecycle.ts

@@ -1,4 +1,5 @@
-import type { GameSessionStatus } from '../core/session/types';
+import type { GameSessionStatus, GameSubscription } from '../core/session/types';
+import { createCleanupList } from './cleanupList';
 
 /** Minimal AppState-like source used to keep this seam platform-neutral. */
 export interface AppLifecycleSource {
@@ -18,6 +19,12 @@ export interface AppLifecycleSession {
   pause(): void;
   /** Resume a paused session. */
   resume(): void;
+  /**
+   * Optional status observation (T10.6): when present, the binder also
+   * guards against an external `start()` while the host is inactive, so a
+   * frame loop can never escape into the background.
+   */
+  addStatusListener?(listener: (status: GameSessionStatus) => void): GameSubscription;
 }
 
 /**
@@ -36,7 +43,14 @@ export function bindAppLifecycle(
   source: AppLifecycleSource,
   session: AppLifecycleSession,
 ): () => void {
+  // GS-REACT-02: setup is transactional — every stage registers its release
+  // as it completes, so a later failure unwinds everything acquired so far.
+  const cleanups = createCleanupList();
   let pausedByLifecycle = false;
+  let currentState = source.currentState ?? 'active';
+
+  const isInactive = (state: string | null | undefined): boolean =>
+    state === 'inactive' || state === 'background';
 
   const pauseForBackground = () => {
     if (session.getStatus() === 'running') {
@@ -45,27 +59,49 @@ export function bindAppLifecycle(
     }
   };
 
-  // Synchronize the initial app state before any change event arrives.
-  if (source.currentState === 'inactive' || source.currentState === 'background') {
-    pauseForBackground();
-  }
-
-  const subscription = source.addEventListener('change', (next) => {
-    if (next === 'active') {
-      if (pausedByLifecycle) {
-        pausedByLifecycle = false;
-        // Resume only if the session is still paused; a different actor may
-        // have resumed or disposed it while the app was backgrounded.
-        if (session.getStatus() === 'paused') {
-          session.resume();
+  // T10.6: an external start() while the host is inactive is deterministically
+  // returned to paused. The binder observes status transitions and re-pauses
+  // any running transition that happens while the app is not active, so a
+  // frame loop cannot escape into the background.
+  let statusSubscription: GameSubscription | undefined;
+  try {
+    if (session.addStatusListener !== undefined) {
+      statusSubscription = session.addStatusListener((status) => {
+        if (status === 'running' && isInactive(currentState)) {
+          session.pause();
+          pausedByLifecycle = true;
         }
-      }
-      return;
+      });
+      cleanups.add(() => statusSubscription?.remove());
     }
-    if (next === 'inactive' || next === 'background') {
+
+    // Synchronize the initial app state before any change event arrives.
+    if (isInactive(source.currentState)) {
       pauseForBackground();
     }
-  });
+
+    const subscription = source.addEventListener('change', (next) => {
+      currentState = next;
+      if (next === 'active') {
+        if (pausedByLifecycle) {
+          pausedByLifecycle = false;
+          // Resume only if the session is still paused; a different actor may
+          // have resumed or disposed it while the app was backgrounded.
+          if (session.getStatus() === 'paused') {
+            session.resume();
+          }
+        }
+        return;
+      }
+      if (isInactive(next)) {
+        pauseForBackground();
+      }
+    });
+    cleanups.add(() => subscription.remove());
+  } catch (error) {
+    cleanups.releaseAll();
+    throw error;
+  }
 
   let cleanedUp = false;
   return () => {
@@ -73,7 +109,7 @@ export function bindAppLifecycle(
       return;
     }
     cleanedUp = true;
-    subscription.remove();
+    cleanups.releaseAll();
     pausedByLifecycle = false;
   };
 }