fix(hooks): actionable messages, guarded async flip, specific native logging

Remaining small items from the second cold review:

- required-mode throws no longer leak the internal hook name
  (useViewModelInstanceAsync: → useViewModelInstance:), and a null
  source gets its own message pointing at the upstream hook's error
  instead of 'ensure the source has a valid ViewModel'
- flipping the async param between renders now logs an actionable
  console.error before React's cryptic hooks-order invariant fires
- the VM-less normalization on the new backends logs what it swallows
  (RiveLog.d) and propagates cancellation instead of eating it
- e2e: expectDefined also rejects null (its NonNullable claim was
  unsound), the resolve-to-null test pins the stable 'not found'
  message, and android-experimental skips announce themselves
- JSDoc: the required example now states that required-narrowing needs
  a non-nullable source type (nullable sources resolve to the standard
  overload; the runtime throw still applies)

Author: mfazekas

android/src/new/java/com/margelo/nitro/rive/HybridRiveFile.kt

@@ -103,10 +103,16 @@ class HybridRiveFile(
     // getDefaultViewModelInfo throws when the artboard has no default
     // ViewModel — a normal state for VM-less files (issue #189 fixture), not
     // a failure. Resolve null like the legacy backend so callers get the
-    // documented "no ViewModel" result instead of a raw error.
+    // documented "no ViewModel" result — but propagate cancellation and log
+    // what was swallowed so a genuine failure (disposed file, dead command
+    // queue) isn't a silently blank screen.
     val vmInfo = try {
       file.getDefaultViewModelInfo(artboard)
+    } catch (e: kotlinx.coroutines.CancellationException) {
+      runCatching { artboard.close() }
+      throw e
     } catch (e: Exception) {
+      RiveLog.d(TAG, "defaultArtboardViewModel: resolving null — getDefaultViewModelInfo failed: ${e.message}")
       runCatching { artboard.close() }
       return null
     }

example/__tests__/useViewModelInstance-async-e2e.harness.tsx

@@ -32,7 +32,10 @@ const NO_DEFAULT_VM = require('../assets/rive/nodefaultbouncing.riv');
 const BOUNCING_BALL = require('../assets/rive/bouncing_ball.riv');
 
 function expectDefined<T>(value: T): asserts value is NonNullable<T> {
+  // toBeDefined() alone passes for null, which would betray the NonNullable
+  // type claim this helper makes.
   expect(value).toBeDefined();
+  expect(value).not.toBeNull();
 }
 
 async function loadFile() {
@@ -348,6 +351,9 @@ describe('useViewModelInstance async: instance creation failure', () => {
     await waitFor(() => expect(ctx.isLoading).toBe(false), { timeout: 5000 });
     expect(ctx.instance).toBeNull();
     expectDefined(ctx.error);
+    // The stable message, not a leaked raw native diagnostic.
+    expect(ctx.error.message).toContain('not found');
+    expect(ctx.error.message).not.toContain('Could not create');
     cleanup();
   });
 });
@@ -415,7 +421,12 @@ describe('useViewModelInstance async: RiveViewRef source', () => {
     const isAndroidExperimental =
       Platform.OS === 'android' &&
       RiveFileFactory.getBackend() === 'experimental';
-    if (isAndroidExperimental) return;
+    if (isAndroidExperimental) {
+      console.warn(
+        'SKIP: android-experimental — getViewModelInstance() does not expose the auto-bound VMI yet'
+      );
+      return;
+    }
 
     const file = await RiveFileFactory.fromSource(BOUNCING_BALL, undefined);
     const ctx = createCtx();
@@ -430,7 +441,12 @@ describe('useViewModelInstance async: RiveViewRef source', () => {
     const isAndroidExperimental =
       Platform.OS === 'android' &&
       RiveFileFactory.getBackend() === 'experimental';
-    if (isAndroidExperimental) return;
+    if (isAndroidExperimental) {
+      console.warn(
+        'SKIP: android-experimental — getViewModelInstance() does not expose the auto-bound VMI yet'
+      );
+      return;
+    }
 
     const file = await RiveFileFactory.fromSource(BOUNCING_BALL, undefined);
     const ctx = createCtx();

ios/new/HybridRiveFile.swift

@@ -92,11 +92,18 @@ class HybridRiveFile: HybridRiveFileSpec {
     // getDefaultViewModelInfo throws when the artboard has no default
     // ViewModel — a normal state for VM-less files (issue #189 fixture), not
     // a failure. Resolve nil like the legacy backend so callers get the
-    // documented "no ViewModel" result instead of a raw error.
-    guard let vmInfo = try? await file.getDefaultViewModelInfo(for: artboard) else {
+    // documented "no ViewModel" result — but propagate cancellation and log
+    // what was swallowed so a genuine failure (disposed file, dead worker)
+    // isn't a silently blank screen.
+    do {
+      let vmInfo = try await file.getDefaultViewModelInfo(for: artboard)
+      return HybridViewModel(file: file, vmName: vmInfo.viewModelName, worker: worker)
+    } catch is CancellationError {
+      throw CancellationError()
+    } catch {
+      RiveLog.d("RiveFile", "defaultArtboardViewModel: resolving nil — getDefaultViewModelInfo failed: \(error)")
       return nil
     }
-    return HybridViewModel(file: file, vmName: vmInfo.viewModelName, worker: worker)
   }
 
   // Deprecated: Use defaultArtboardViewModelAsync instead

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

@@ -687,9 +687,79 @@ describe('useViewModelInstance async - required', () => {
     );
 
     await waitFor(() => expect(onError).toHaveBeenCalled());
-    expect((onError.mock.calls[0][0] as Error).message).toContain(
-      'NonExistent'
+    const message = (onError.mock.calls[0][0] as Error).message;
+    expect(message).toContain('NonExistent');
+    // Users called useViewModelInstance — the internal hook name must not leak.
+    expect(message).toContain('useViewModelInstance:');
+    expect(message).not.toContain('useViewModelInstanceAsync');
+    consoleError.mockRestore();
+  });
+
+  it('names the absent source (not the ViewModel) when required throws for a null source', async () => {
+    const consoleError = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+    const onError = jest.fn();
+
+    function NullSourceProbe() {
+      useViewModelInstance(null as RiveFile | null, {
+        async: true,
+        required: true,
+      });
+      return null;
+    }
+
+    render(
+      <ErrorBoundary onError={onError}>
+        <NullSourceProbe />
+      </ErrorBoundary>
     );
+
+    await waitFor(() => expect(onError).toHaveBeenCalled());
+    const message = (onError.mock.calls[0][0] as Error).message;
+    // A null source means the file/view failed upstream — pointing users at
+    // "Ensure the source has a valid ViewModel" sends them the wrong way.
+    expect(message).toContain('useViewModelInstance:');
+    expect(message).toMatch(/source is null/i);
+    expect(message).toMatch(/useRiveFile|useRive/);
+    consoleError.mockRestore();
+  });
+});
+
+describe('useViewModelInstance - async flag constancy guard', () => {
+  it('reports an actionable error when async changes between renders', async () => {
+    const consoleError = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+    const defaultInstance = createMockViewModelInstance();
+    // The initial render takes the sync path, so the mock must speak the
+    // sync API too (the shared factories only stub the *Async surface).
+    const mockRiveFile = {
+      ...createMockRiveFile({
+        defaultViewModel: createMockViewModel({ defaultInstance }),
+      }),
+      defaultArtboardViewModel: jest.fn(() => ({
+        dispose: jest.fn(),
+        createDefaultInstance: jest.fn(() => defaultInstance),
+        createInstanceByName: jest.fn(),
+        createInstance: jest.fn(),
+      })),
+    } as unknown as RiveFile;
+
+    const { rerender } = renderHook(
+      ({ isAsync }: { isAsync: boolean }) =>
+        useViewModelInstance(mockRiveFile, { async: isAsync }),
+      { initialProps: { isAsync: false } }
+    );
+
+    // Flipping the flag switches hook implementations — React will throw its
+    // generic hooks-order invariant; the hook must first explain why.
+    expect(() => rerender({ isAsync: true })).toThrow();
+    expect(
+      consoleError.mock.calls.some((c) =>
+        String(c[0]).includes('`async` param changed between renders')
+      )
+    ).toBe(true);
     consoleError.mockRestore();
   });
 });

src/hooks/useViewModelInstance.ts

@@ -292,6 +292,9 @@ export type UseViewModelInstanceRequiredResult =
  * ```tsx
  * // With required: true (throws once resolved to null, use with Error Boundary).
  * // Note: instance is still `undefined` while loading — guard on isLoading.
+ * // The required-narrowed return type applies only when the source's TYPE is
+ * // non-nullable; with a nullable source (e.g. straight from useRiveFile) the
+ * // call resolves to the standard overload — the runtime throw still applies.
  * const { instance, isLoading } = useViewModelInstance(riveFile, { async: true, required: true });
  * ```
  *
@@ -399,7 +402,18 @@ export function useViewModelInstance(
   const isAsync = params?.async ?? false;
   // The flag selects between two hook implementations (different hook
   // orders), so it must stay constant for the lifetime of the component —
-  // documented on the param.
+  // documented on the param. React's own failure for a flip is the cryptic
+  // "Rendered more hooks than during the previous render"; explain first.
+  const initialAsyncRef = useRef(isAsync);
+  if (initialAsyncRef.current !== isAsync) {
+    console.error(
+      'useViewModelInstance: the `async` param changed between renders ' +
+        `(${String(initialAsyncRef.current)} → ${String(isAsync)}). It selects ` +
+        'between two hook implementations, so it must stay constant for the ' +
+        'lifetime of the component; remount (e.g. change `key`) to switch modes.'
+    );
+    initialAsyncRef.current = isAsync;
+  }
   if (isAsync) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     return useViewModelInstanceAsync(
@@ -469,8 +483,8 @@ function useViewModelInstanceSync(
     // async path.
     if (required) {
       throw new Error(
-        'useViewModelInstance: Failed to get ViewModelInstance. ' +
-          'Ensure the source has a valid ViewModel and instance available.'
+        'useViewModelInstance: source is null — the file or view failed to ' +
+          "resolve upstream (if it comes from useRiveFile or useRive, check that hook's error)."
       );
     }
     return { instance: null, isLoading: false, error: null };

src/hooks/useViewModelInstanceAsync.ts

@@ -425,10 +425,18 @@ export function useViewModelInstanceAsync(
   }, [source, instanceName, artboardName, viewModelName, useNew]);
 
   if (required && result.instance === null && !result.isLoading) {
+    // The public entry point is useViewModelInstance — don't leak this
+    // internal hook's name into user-facing errors.
+    if (source === null) {
+      throw new Error(
+        'useViewModelInstance: source is null — the file or view failed to ' +
+          "resolve upstream (if it comes from useRiveFile or useRive, check that hook's error)."
+      );
+    }
     throw new Error(
       result.error
-        ? `useViewModelInstanceAsync: ${result.error.message}`
-        : 'useViewModelInstanceAsync: Failed to get ViewModelInstance. ' +
+        ? `useViewModelInstance: ${result.error.message}`
+        : 'useViewModelInstance: Failed to get ViewModelInstance. ' +
           'Ensure the source has a valid ViewModel and instance available.'
     );
   }