refactor(hooks): route widened async params to the deprecated overloads

Replace the non-deprecated catch-all overloads with plain deprecated
overloads (no async?: false pin): a params object whose async widened
to boolean — or a value of the exported *Params types — now resolves
to the deprecated overload instead of a warning-free catch-all. Since
async is a member of the params types, such calls compile (no
weak-type failure) and behave per the runtime value; the deprecation
message tells the caller the fix: re-pin with { ...params, async:
true }. This makes deprecation coverage total — any call not provably
async: true is flagged — at the cost of a nudge for already-migrated
callers who kept a widened object, which the message resolves.

The type-compat tests keep pinning that these calls compile and run
async at runtime, now with intentional no-deprecated disables.

Author: mfazekas

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

@@ -367,15 +367,18 @@ function createMockRiveViewRef(
 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).
+  // params types declare `async?: boolean` — both must keep COMPILING and
+  // behave per the runtime value (`yarn tsc` is the gate). By design they
+  // resolve to the deprecated overloads: the warning's message tells such
+  // callers to re-pin with `{ ...params, async: true }`.
   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(() =>
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- widened async resolves to the deprecated overload by design; runtime still honors the value
       useViewModelInstance(mockRiveFile, params)
     );
 
@@ -391,6 +394,7 @@ describe('useViewModelInstance - param type compatibility', () => {
 
     const params: UseViewModelInstanceFileParams = { async: true };
     const { result } = renderHook(() =>
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- exported param types carry async?: boolean and resolve to the deprecated overload by design
       useViewModelInstance(mockRiveFile, params)
     );
 
@@ -748,6 +752,7 @@ describe('useViewModelInstance - async flag constancy guard', () => {
 
     const { rerender } = renderHook(
       ({ isAsync }: { isAsync: boolean }) =>
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- dynamic async is the misuse under test
         useViewModelInstance(mockRiveFile, { async: isAsync }),
       { initialProps: { isAsync: false } }
     );

src/hooks/useViewModelInstance.ts

@@ -318,15 +318,15 @@ export function useViewModelInstance(
   source: RiveFile | null | undefined,
   params: UseViewModelInstanceFileParams & { async: true }
 ): UseViewModelInstanceResult;
-/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. */
+/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. If your params object's `async` widened to `boolean`, re-pin it at the call site: `{ ...params, async: true }`. */
 export function useViewModelInstance(
   source: RiveFile,
-  params: UseViewModelInstanceFileParams & { async?: false; required: true }
+  params: UseViewModelInstanceFileParams & { required: true }
 ): UseViewModelInstanceRequiredResult;
-/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. */
+/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. If your params object's `async` widened to `boolean`, re-pin it at the call site: `{ ...params, async: true }`. */
 export function useViewModelInstance(
   source: RiveFile | null | undefined,
-  params?: UseViewModelInstanceFileParams & { async?: false }
+  params?: UseViewModelInstanceFileParams
 ): UseViewModelInstanceResult;
 
 // ViewModel overloads
@@ -338,18 +338,15 @@ export function useViewModelInstance(
   source: ViewModel | null | undefined,
   params: UseViewModelInstanceViewModelParams & { async: true }
 ): UseViewModelInstanceResult;
-/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. */
+/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. If your params object's `async` widened to `boolean`, re-pin it at the call site: `{ ...params, async: true }`. */
 export function useViewModelInstance(
   source: ViewModel,
-  params: UseViewModelInstanceViewModelParams & {
-    async?: false;
-    required: true;
-  }
+  params: UseViewModelInstanceViewModelParams & { required: true }
 ): UseViewModelInstanceRequiredResult;
-/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. */
+/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. If your params object's `async` widened to `boolean`, re-pin it at the call site: `{ ...params, async: true }`. */
 export function useViewModelInstance(
   source: ViewModel | null | undefined,
-  params?: UseViewModelInstanceViewModelParams & { async?: false }
+  params?: UseViewModelInstanceViewModelParams
 ): UseViewModelInstanceResult;
 
 // RiveViewRef overloads
@@ -361,31 +358,12 @@ export function useViewModelInstance(
   source: RiveViewRef | null | undefined,
   params: UseViewModelInstanceRefParams & { async: true }
 ): UseViewModelInstanceResult;
-/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. */
+/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. If your params object's `async` widened to `boolean`, re-pin it at the call site: `{ ...params, async: true }`. */
 export function useViewModelInstance(
   source: RiveViewRef,
-  params: UseViewModelInstanceRefParams & { async?: false; required: true }
+  params: UseViewModelInstanceRefParams & { required: true }
 ): UseViewModelInstanceRequiredResult;
-/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. */
-export function useViewModelInstance(
-  source: RiveViewRef | null | undefined,
-  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;
+/** @deprecated Pass `async: true` — without it the instance is created synchronously via deprecated runtime APIs that block the JS thread. `async: true` becomes the default in the next major. If your params object's `async` widened to `boolean`, re-pin it at the call site: `{ ...params, async: true }`. */
 export function useViewModelInstance(
   source: RiveViewRef | null | undefined,
   params?: UseViewModelInstanceRefParams