rn-gamekit 0.1.0

package/src/react/assets/createGameAssetStore.ts

@@ -0,0 +1,459 @@
+/**
+ * Asset store core (T7.4).
+ *
+ * The explicit owner of the decoded-image cache. Source resolution and
+ * image decoding are injected so the ownership logic is unit-testable with
+ * fakes and never imports native modules itself.
+ *
+ * Ownership rules:
+ * - An explicitly created store owns cache/native entries.
+ * - `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.
+ * - 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.
+ * - `AbortSignal` detaches an imperative caller immediately; late results
+ *   from the underlying work are ignored.
+ * - 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.
+ */
+import { GameAssetError } from '../../assets/errors';
+import type {
+  AssetGroupMap,
+  BrandedAssetDescriptor,
+  GameAssetLease,
+  ImageDescriptor,
+  LoadedImage,
+  LoadedAssets,
+  LoadedSpriteSheet,
+  SpriteFrameRect,
+  SpriteSheetDescriptor,
+} from '../../assets/types';
+import { validateFrameRect } from '../../assets/validation';
+import { GameAssetError as AssetStoreError } from '../../assets/errors';
+
+/** Opaque decoded-image handle (Skia's SkImage satisfies this structurally). */
+export interface NativeImageHandle {
+  /** Decoded width in pixels. */
+  width(): number;
+  /** Decoded height in pixels. */
+  height(): number;
+  /** Release the native handle; exactly once per resource. */
+  dispose(): void;
+}
+
+/** Injected source resolution and decode pipelines. */
+export interface AssetPipelines {
+  /** Resolve a static module handle to a canonical local URI. */
+  readonly resolve: (source: number) => Promise<string>;
+  /** Decode a canonical local URI into an image handle. */
+  readonly decode: (uri: string) => Promise<NativeImageHandle>;
+}
+
+/** Acquisition options for `acquire`. */
+export interface AcquireOptions {
+  /** Logical groups to load; an empty set resolves immediately. */
+  readonly groups: readonly string[];
+  /** Detach the caller; late results are ignored, never resurrected. */
+  readonly signal?: AbortSignal;
+  /** Monotonic progress in [0, 1], one update per completed logical asset. */
+  readonly onProgress?: (progress: number) => void;
+}
+
+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;
+}
+
+interface Attempt {
+  readonly token: number;
+  /** Idempotent release closures for every reference this attempt owns. */
+  readonly acquired: ResourceRef[];
+}
+
+/** One idempotent ownership token: release() is safe to call repeatedly and
+ * disposes the native handle when it is the final reference (RF5). */
+interface ResourceRef {
+  readonly release: () => void;
+  /** Resolve to the decoded handle (the shared in-flight promise or cache). */
+  readonly ready: () => Promise<NativeImageHandle>;
+}
+
+/** One logical (group, asset) identity inside a manifest. */
+interface LogicalAsset {
+  readonly key: string;
+  readonly group: string;
+  readonly name: string;
+  readonly descriptor: ImageDescriptor | SpriteSheetDescriptor;
+}
+
+function logicalAssetsOf(manifest: AssetGroupMap): LogicalAsset[] {
+  const result: LogicalAsset[] = [];
+  for (const [group, assets] of Object.entries(manifest)) {
+    for (const [name, descriptor] of Object.entries(assets)) {
+      result.push({
+        key: `${group}/${name}`,
+        group,
+        name,
+        descriptor: descriptor as ImageDescriptor | SpriteSheetDescriptor,
+      });
+    }
+  }
+  return result;
+}
+
+/** Validate a sprite sheet's frames against decoded dimensions. */
+function validateFrames(
+  path: readonly string[],
+  frames: Readonly<Record<string, SpriteFrameRect>>,
+  width: number,
+  height: number,
+): void {
+  for (const [name, rect] of Object.entries(frames)) {
+    validateFrameRect(path, name, rect);
+    if (rect.x + rect.width > width || rect.y + rect.height > height) {
+      throw new GameAssetError(
+        'ASSET_FRAME_OUT_OF_BOUNDS',
+        [...path, name],
+        `frame ${JSON.stringify(name)} (${rect.x},${rect.y} ${rect.width}x${rect.height}) exceeds the decoded image ${width}x${height}`,
+      );
+    }
+  }
+}
+
+export function createGameAssetStoreCore<TManifest extends AssetGroupMap>(
+  manifest: TManifest,
+  pipelines: AssetPipelines,
+): {
+  readonly acquire: (options: AcquireOptions) => Promise<GameAssetLease<TManifest>>;
+  readonly dispose: () => void;
+  readonly isDisposed: () => boolean;
+} {
+  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). */
+
+  function assertLive(): void {
+    if (disposed) {
+      throw new AssetStoreError('ASSET_STORE_DISPOSED', [], 'asset store is disposed');
+    }
+  }
+
+  /** Race a promise with the abort signal; the listener is removed on
+   * resolve, reject, and abort (RF5). */
+  function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+    if (signal === undefined) {
+      return promise;
+    }
+    return new Promise<T>((resolve, reject) => {
+      const onAbort = (): void => {
+        reject(new AssetStoreError('ASSET_ABORTED', [], 'asset acquisition aborted'));
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+      promise.then(
+        (value) => {
+          signal.removeEventListener('abort', onAbort);
+          resolve(value);
+        },
+        (error) => {
+          signal.removeEventListener('abort', onAbort);
+          reject(error);
+        },
+      );
+    });
+  }
+
+  /** 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;
+    }
+    entry.refCount -= 1;
+    if (entry.refCount <= 0) {
+      if (entry.handle !== undefined) {
+        entry.handle.dispose();
+      }
+      resources.delete(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.
+   */
+  function beginResourceRef(uri: string): ResourceRef {
+    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,
+      };
+    }
+    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,
+      };
+    }
+    // Cache miss: this waiter starts the decode.
+    entry = {
+      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.
+      if (disposed || entry.refCount <= 0) {
+        handle.dispose();
+        if (entry.refCount <= 0) {
+          resources.delete(uri);
+        }
+        throw new AssetStoreError('ASSET_ABORTED', [], 'asset acquisition aborted');
+      }
+      entry.handle = handle;
+      return handle;
+    })();
+    entry.inFlight = promise;
+    void promise.then(
+      () => {
+        entry.inFlight = undefined;
+      },
+      () => {
+        entry.inFlight = undefined;
+      },
+    );
+    return {
+      release: () => dropResourceRef(uri),
+      ready: async () => promise,
+    };
+  }
+
+  async function acquireOne(
+    asset: LogicalAsset,
+    attempt: Attempt,
+    signal: AbortSignal | undefined,
+  ): Promise<void> {
+    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);
+    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'],
+          asset.descriptor.frames,
+          handle.width(),
+          handle.height(),
+        );
+      }
+    } catch (error) {
+      // Every failure, abort, and stale completion releases this waiter's
+      // reference exactly once; surviving owners keep theirs.
+      ref.release();
+      throw error;
+    }
+  }
+
+
+  const acquire = async (options: AcquireOptions): Promise<GameAssetLease<TManifest>> => {
+    assertLive();
+    const { signal } = options;
+    const throwIfAborted = (): void => {
+      if (signal?.aborted === true) {
+        throw new AssetStoreError('ASSET_ABORTED', [], 'asset acquisition aborted');
+      }
+    };
+    throwIfAborted();
+
+    // RF5: normalize groups at the public boundary (dedupe) and use the
+    // same list for the progress total and acquisition.
+    const groupsNormalized = [...new Set(options.groups)];
+    const requested: LogicalAsset[] = [];
+    for (const group of groupsNormalized) {
+      if (!groups.has(group)) {
+        throw new GameAssetError('ASSET_UNKNOWN_GROUP', [group], `unknown asset group ${JSON.stringify(group)}`);
+      }
+      for (const asset of logical) {
+        if (asset.group === group) {
+          requested.push(asset);
+        }
+      }
+    }
+    if (requested.length === 0) {
+      // Empty group set resolves immediately with progress 1 and no resources.
+      options.onProgress?.(1);
+      return createLease(new Map(), () => undefined);
+    }
+
+    const token = nextAttemptToken;
+    nextAttemptToken += 1;
+    const attempt: Attempt = { token, acquired: [] };
+
+    const loaded = new Map<string, string>();
+    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);
+        completed += 1;
+        options.onProgress?.(completed / total);
+      }
+      return createLease(loaded, () => {
+        for (const ref of attempt.acquired) {
+          ref.release();
+        }
+      });
+    } catch (error) {
+      // Release every reference this attempt acquired exactly once; entries
+      // still leased by a previous lease keep their references.
+      for (const ref of attempt.acquired) {
+        ref.release();
+      }
+      throw error;
+    }
+  };
+
+  function createLease(
+    loadedKeys: ReadonlyMap<string, string>,
+    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);
+      }
+    }
+    const assets: LoadedAssets<TManifest> = {
+      manifest,
+      get: <TDescriptor extends ImageDescriptor | SpriteSheetDescriptor>(
+        descriptor: BrandedAssetDescriptor<TManifest, TDescriptor>,
+      ) => {
+        assertLive();
+        if (leaseDisposed) {
+          throw new AssetStoreError('ASSET_STORE_DISPOSED', [], 'lease is disposed');
+        }
+        const entry = findLoadedFor(descriptor, loaded);
+        if (entry === 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,
+          // so the type layer cannot distinguish them; the runtime reference
+          // check is the guarantee.
+          throw new GameAssetError(
+            'ASSET_UNKNOWN_ASSET',
+            [],
+            'descriptor is not a reference declared by this manifest and group selection',
+          );
+        }
+        return entry as TDescriptor extends { readonly kind: 'sprite-sheet' }
+          ? LoadedSpriteSheet
+          : LoadedImage;
+      },
+    };
+    return {
+      assets,
+      dispose: () => {
+        if (leaseDisposed) {
+          return;
+        }
+        leaseDisposed = true;
+        onDispose();
+      },
+    };
+  }
+
+  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: () => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      // Drop entries with no live lease; leased entries stay until their
+      // lease releases them (their refCount keeps them alive).
+      for (const [uri, entry] of resources) {
+        if (entry.refCount <= 0 && entry.handle !== undefined) {
+          entry.handle.dispose();
+          resources.delete(uri);
+        }
+      }
+    },
+    isDisposed: () => disposed,
+  };
+}
+
+export type GameAssetStore = ReturnType<typeof createGameAssetStoreCore>;

package/src/react/assets/decodeSkiaImage.ts

@@ -0,0 +1,64 @@
+/**
+ * Default Expo/Skia asset pipelines (T7.4).
+ *
+ * Exact primitives used (verified against the installed types, Skia 2.11.0
+ * and expo-asset SDK 57):
+ * - `Asset.fromModule(source)` -> `await asset.downloadAsync()` ->
+ *   `asset.localUri ?? asset.uri` (canonical local URI; static module
+ *   handles only);
+ * - `Skia.Data.fromURI(uri)` -> `SkData` (disposed as soon as the image is
+ *   created — `SkImage.MakeImageFromEncoded` copies the encoded bytes);
+ * - `Skia.Image.MakeImageFromEncoded(data)` -> `SkImage | null` (null is a
+ *   structured load failure, never a ready resource).
+ */
+import { Asset } from 'expo-asset';
+import { Skia } from '@shopify/react-native-skia';
+
+import { GameAssetError } from '../../assets/errors';
+import type { AssetGroupMap } from '../../assets/types';
+import {
+  createGameAssetStoreCore,
+  type NativeImageHandle,
+} from './createGameAssetStore';
+
+const resolvePipeline = async (source: number): Promise<string> => {
+  const asset = Asset.fromModule(source);
+  try {
+    await asset.downloadAsync();
+  } catch (error) {
+    throw new GameAssetError(
+      'ASSET_RESOLVE_FAILED',
+      [],
+      `failed to resolve static asset module ${source}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return asset.localUri ?? asset.uri;
+};
+
+const decodePipeline = async (uri: string): Promise<NativeImageHandle> => {
+  const data = await Skia.Data.fromURI(uri);
+  try {
+    const image = Skia.Image.MakeImageFromEncoded(data);
+    if (image === null) {
+      throw new GameAssetError('ASSET_DECODE_FAILED', [], `decoding ${uri} produced no image`);
+    }
+    return image as unknown as NativeImageHandle;
+  } finally {
+    data.dispose();
+  }
+};
+
+/**
+ * Create the explicit asset-store owner for a manifest using the default
+ * Expo/Skia pipelines. Callers dispose the lease then the store in
+ * `finally`.
+ */
+export function createGameAssetStore<TManifest extends AssetGroupMap>(
+  manifest: TManifest,
+) {
+  // The return type keeps the manifest generic so leases stay typed.
+  return createGameAssetStoreCore(manifest, {
+    resolve: resolvePipeline,
+    decode: decodePipeline,
+  });
+}

package/src/react/assets/errors.ts

@@ -0,0 +1,7 @@
+/**
+ * Asset store errors (T7.4).
+ *
+ * The store adds no error codes of its own: every failure is a structured
+ * `GameAssetError` with a stable code and field path.
+ */
+export { GameAssetError } from '../../assets/errors';

package/src/react/assets/useGameAssets.ts

@@ -0,0 +1,171 @@
+/**
+ * `useGameAssets` — the React loading adapter (T7.5).
+ *
+ * The hook creates and owns one asset store and lease for the requested
+ * groups; the caller must not dispose the returned ready value manually.
+ *
+ * Contract:
+ * - `{ status: 'loading'; progress }` — progress in [0, 1], monotonic;
+ * - `{ status: 'error'; error; retry }` — structured error + stable retry;
+ * - `{ status: 'ready'; assets }` — the complete lease, typed to the
+ *   manifest.
+ *
+ * Lifecycle:
+ * - The requested group list is normalized (sorted) so a recreated
+ *   equivalent array does not reload.
+ * - 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 { GameAssetError } from '../../assets/errors';
+import type { AssetGroupMap, GameAssetLease, LoadedAssets } from '../../assets/types';
+import type { AcquireOptions } from './createGameAssetStore';
+
+/** The store surface the hook needs, kept generic over the manifest. */
+export interface HookStore<TManifest extends AssetGroupMap> {
+  readonly acquire: (options: AcquireOptions) => Promise<GameAssetLease<TManifest>>;
+  readonly dispose: () => void;
+}
+
+/**
+ * Default store factory using the Expo/Skia pipelines. The wiring module is
+ * required lazily so the hook's import graph stays headless (tests inject
+ * their own factory and never touch the native side).
+ */
+function defaultStoreFactory<TManifest extends AssetGroupMap>(
+  manifest: TManifest,
+): HookStore<TManifest> {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { createGameAssetStore } = require('./decodeSkiaImage') as {
+    createGameAssetStore: <T extends AssetGroupMap>(value: T) => HookStore<T>;
+  };
+  return createGameAssetStore(manifest);
+}
+
+/** The discriminated loading state machine. Every state carries the
+ * normalized request key (RF7) so a rendered request that differs from the
+ * state's request can never expose a stale lease. */
+export type GameAssetsState<TManifest extends AssetGroupMap> =
+  | { readonly status: 'loading'; readonly progress: number; readonly retry: () => void; readonly requestKey: string }
+  | { readonly status: 'error'; readonly error: GameAssetError; readonly retry: () => void; readonly requestKey: string }
+  | { readonly status: 'ready'; readonly assets: LoadedAssets<TManifest>; readonly requestKey: string };
+
+/** Deduplicate and sort groups so equivalent reordered/duplicated arrays
+ * map to one key and one acquisition (R6). */
+export function dedupeGroups(groups: readonly string[]): readonly string[] {
+  return [...new Set(groups)].sort();
+}
+
+/** Order-independent group key: equivalent arrays map to one key. */
+export function stableGroupsKey(groups: readonly string[]): string {
+  return dedupeGroups(groups).join('\u0000');
+}
+
+export function useGameAssets<TManifest extends AssetGroupMap>(
+  manifest: TManifest,
+  options: { readonly groups: readonly (Extract<keyof TManifest, string>)[] },
+  storeFactory?: (manifest: TManifest) => HookStore<TManifest>,
+): GameAssetsState<TManifest> {
+  const groupsKey = stableGroupsKey(options.groups);
+  const [attempt, setAttempt] = useState(0);
+  const [state, setState] = useState<GameAssetsState<TManifest>>({
+    status: 'loading',
+    progress: 0,
+    retry: () => undefined,
+    requestKey: groupsKey,
+  });
+  const storeRef = useRef<HookStore<TManifest> | undefined>(undefined);
+  const leaseRef = useRef<GameAssetLease<TManifest> | undefined>(undefined);
+  const retry = useCallback(() => {
+    // R6: one user action starts exactly one new attempt; the same function
+    // identity is exposed in loading and error states.
+    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);
+    storeRef.current = store;
+    let disposed = false;
+    const attemptAtStart = attempt;
+    const isCurrent = (): boolean => attemptRef.current === attemptAtStart;
+    const setIfCurrent = (updater: (previous: GameAssetsState<TManifest>) => GameAssetsState<TManifest>): void => {
+      if (!disposed && isCurrent()) {
+        setState(updater);
+      }
+    };
+
+    // R6: every attempt owns an AbortController; aborting detaches the
+    // caller and rejects late progress/ready/error from older configs.
+    const controller = new AbortController();
+
+    setState({
+      status: 'loading',
+      progress: 0,
+      retry: retry,
+      requestKey: groupsKey,
+    });
+
+    store
+      .acquire({
+        groups: dedupeGroups(options.groups),
+        signal: controller.signal,
+        onProgress: (progress) => {
+          setIfCurrent((previous) =>
+            previous.status === 'loading' ? { ...previous, progress } : previous,
+          );
+        },
+      })
+      .then((lease) => {
+        if (disposed || !isCurrent()) {
+          // Stale completion (retry/unmount): release immediately.
+          lease.dispose();
+          return;
+        }
+        leaseRef.current?.dispose();
+        leaseRef.current = lease;
+        setState({ status: 'ready', assets: lease.assets, requestKey: groupsKey });
+      })
+      .catch((error: unknown) => {
+        if (disposed || !isCurrent()) {
+          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 });
+      });
+
+    return () => {
+      disposed = true;
+      // R6: abort before releasing so no late completion can touch state or
+      // resources, then release the lease and store exactly once.
+      controller.abort();
+      leaseRef.current?.dispose();
+      leaseRef.current = undefined;
+      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]);
+
+  return state;
+}