fix(hooks): accept widened async params; terminal null source on the sync path

Two more items from the second cold review:

- Params objects built separately widen async to boolean (and the
  exported *Params types declare async?: boolean), matching no literal
  overload — the compiler rejected the call blaming the *source*
  argument, and values of the hook's own exported param types stopped
  being accepted. New catch-all overloads (per source type) restore
  compatibility; literal async values still resolve to the specific
  overloads first, keeping deprecation warnings and required narrowing.
  Type-level regression tests gate via yarn tsc.

- The sync (non-async) path labeled a null source isLoading: true
  forever — the exact spinner-hang the async docs warn about. It now
  settles to a terminal { instance: null, isLoading: false } and, with
  required: true, throws — mirroring the async path. Behavior change
  on the deprecated path, in the direction of the documented contract.

Author: mfazekas

src/hooks/__tests__/useViewModelInstance.async.test.tsx

@@ -5,7 +5,10 @@ import {
   waitFor,
   act,
 } from '@testing-library/react-native';
-import { useViewModelInstance } from '../useViewModelInstance';
+import {
+  useViewModelInstance,
+  type UseViewModelInstanceFileParams,
+} from '../useViewModelInstance';
 import type { RiveFile } from '../../specs/RiveFile.nitro';
 import type { ViewModel, ViewModelInstance } from '../../specs/ViewModel.nitro';
 import type { ArtboardBy } from '../../specs/ArtboardBy';
@@ -361,6 +364,40 @@ function createMockRiveViewRef(
   return { getViewModelInstance: jest.fn(getViewModelInstance) } as any;
 }
 
+describe('useViewModelInstance - param type compatibility', () => {
+  // These pin overload resolution as much as runtime behavior: a params
+  // object built separately widens `async` to boolean, and the exported
+  // params types declare `async?: boolean` — both must remain accepted
+  // (`yarn tsc` is the gate that fails when the overloads regress).
+  it('accepts a params object with a widened boolean async', async () => {
+    const defaultInstance = createMockViewModelInstance();
+    const defaultViewModel = createMockViewModel({ defaultInstance });
+    const mockRiveFile = createMockRiveFile({ defaultViewModel });
+
+    const params = { async: true }; // widens to { async: boolean }
+    const { result } = renderHook(() =>
+      useViewModelInstance(mockRiveFile, params)
+    );
+
+    await waitFor(() => expect(result.current.instance).toBe(defaultInstance));
+  });
+
+  it('accepts a value of the exported file-params type with a nullable source', async () => {
+    const defaultInstance = createMockViewModelInstance();
+    const defaultViewModel = createMockViewModel({ defaultInstance });
+    const mockRiveFile: RiveFile | null | undefined = createMockRiveFile({
+      defaultViewModel,
+    });
+
+    const params: UseViewModelInstanceFileParams = { async: true };
+    const { result } = renderHook(() =>
+      useViewModelInstance(mockRiveFile, params)
+    );
+
+    await waitFor(() => expect(result.current.instance).toBe(defaultInstance));
+  });
+});
+
 describe('useViewModelInstance async - RiveViewRef source', () => {
   it('resolves the view-bound instance', async () => {
     const vmi = createMockViewModelInstance();

src/hooks/__tests__/useViewModelInstance.test.ts

@@ -363,11 +363,22 @@ describe('useViewModelInstance - ViewModel source', () => {
   });
 });
 
-describe('useViewModelInstance - null source', () => {
-  it('should return undefined instance when source is null', () => {
+describe('useViewModelInstance - null vs undefined source', () => {
+  it('settles to a terminal null when the source is null (e.g. file load failed)', () => {
+    // Mirrors the async path: `useRiveFile` returns null on error and
+    // undefined while loading — a null source must not read as isLoading.
     const { result } = renderHook(() => useViewModelInstance(null));
 
+    expect(result.current.instance).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('reports isLoading while the source is undefined (still resolving)', () => {
+    const { result } = renderHook(() => useViewModelInstance(undefined));
+
     expect(result.current.instance).toBeUndefined();
+    expect(result.current.isLoading).toBe(true);
     expect(result.current.error).toBeNull();
   });
 });

src/hooks/useViewModelInstance.ts

@@ -238,7 +238,7 @@ export type UseViewModelInstanceRequiredResult =
  * during render via deprecated runtime APIs that block the JS thread. The
  * async path will become the default in the next major.
  *
- * With `async: true`, a `null` source settles to a terminal
+ * In both modes, a `null` source settles to a terminal
  * `{ instance: null, isLoading: false }` while an `undefined` source keeps
  * the hook loading. This mirrors {@link useRiveFile} (`riveFile: undefined`
  * while loading, `null` on error) and `useRive` (`riveViewRef: undefined`
@@ -369,6 +369,25 @@ export function useViewModelInstance(
   params?: UseViewModelInstanceRefParams & { async?: false }
 ): UseViewModelInstanceResult;
 
+// Widened-`async` catch-alls: a params object built separately (or typed
+// with the exported *Params types) carries `async?: boolean` and matches no
+// literal overload above — without these the compiler rejects the call and
+// blames the *source* argument. The flag still must stay constant for the
+// component's lifetime. Literal `async` values resolve to the more specific
+// overloads first, keeping the deprecation warnings and `required` narrowing.
+export function useViewModelInstance(
+  source: RiveFile | null | undefined,
+  params?: UseViewModelInstanceFileParams
+): UseViewModelInstanceResult;
+export function useViewModelInstance(
+  source: ViewModel | null | undefined,
+  params?: UseViewModelInstanceViewModelParams
+): UseViewModelInstanceResult;
+export function useViewModelInstance(
+  source: RiveViewRef | null | undefined,
+  params?: UseViewModelInstanceRefParams
+): UseViewModelInstanceResult;
+
 // Implementation
 export function useViewModelInstance(
   source: ViewModelSource | null | undefined,
@@ -443,6 +462,20 @@ function useViewModelInstanceSync(
     [result.error]
   );
 
+  if (result.instance === undefined && source === null) {
+    // Source resolved to absent/failed rather than pending (`useRiveFile`
+    // returns null on load error, undefined while loading) — settle to a
+    // terminal null instead of reporting isLoading forever, mirroring the
+    // async path.
+    if (required) {
+      throw new Error(
+        'useViewModelInstance: Failed to get ViewModelInstance. ' +
+          'Ensure the source has a valid ViewModel and instance available.'
+      );
+    }
+    return { instance: null, isLoading: false, error: null };
+  }
+
   if (required && result.instance === null) {
     throw new Error(
       result.error