test(hooks): migrate deprecation pins to tsd, matching PR #294's wiring

Replace the session-invented eslint typetest convention with the tsd
infrastructure PR #294 introduces, copied as closely as possible so
whichever PR merges second reconciles trivially: tsd ^0.33.0, the
'typetest' script (tsd --typings src/index.tsx), the package.json tsd
block (directory src/__tests__, paths/moduleResolution/jsx options),
jest testPathIgnorePatterns for *.test-d.ts, eslint + root-tsconfig
excludes for *.test-d.ts.

The pins live in src/__tests__/useViewModelInstance.test-d.ts as
explicit assertions: expectDeprecated for every call that must resolve
to a deprecated overload (bare, async: false, widened boolean async,
exported param types), expectNotDeprecated for the literal async: true
forms including the { ...params, async: true } re-pin, expectType for
the required-narrowing behavior, and expectError for invalid param
combinations. Verified that tsd resolves deprecation per-overload for
call expressions (failure messages name the resolved signature).

One deliberate divergence from #294: CI gates 'yarn typetest' in the
lint job (theirs wires the script without a CI step) — keep the step
when the branches meet.

Author: mfazekas

.github/workflows/ci.yml

@@ -57,6 +57,11 @@ jobs:
       - name: Typecheck files
         run: yarn typecheck
 
+      # Overload/deprecation pins (src/__tests__/*.test-d.ts). PR #294 adds
+      # the same tsd wiring without gating it; keep this step when merging.
+      - name: Type tests
+        run: yarn typetest
+
   test:
     runs-on: ubuntu-latest
     steps:

eslint.config.mjs

@@ -49,21 +49,15 @@ export default defineConfig([
       '@typescript-eslint/no-deprecated': 'error',
     },
   },
-  {
-    // Type-test files pin overload/deprecation resolution: a
-    // no-deprecated disable there asserts "this call IS deprecated", so an
-    // unused directive means the resolution regressed and must fail lint.
-    files: ['**/*.typetest.{ts,tsx}'],
-    linterOptions: {
-      reportUnusedDisableDirectives: 'error',
-    },
-  },
   {
     ignores: [
       'node_modules/',
       'lib/',
       '**/.expo/',
       '**/.harness/',
+      // tsd owns *.test-d.ts (yarn typetest) — deprecated calls there are
+      // intentional expectDeprecated() pins, not violations.
+      '**/*.test-d.ts',
       // Agent worktrees (.claude/worktrees/*) are gitignored full-repo copies;
       // linting them duplicates every finding and slows the run.
       '**/.claude/',

package.json

@@ -47,7 +47,8 @@
     "lint:swift": "./scripts/lint-swift.sh",
     "lint:kotlin": "./scripts/lint-kotlin.sh",
     "lint:fix:kotlin": "./scripts/lint-fix-kotlin.sh",
-    "lint:native": "yarn lint:swift && yarn lint:kotlin"
+    "lint:native": "yarn lint:swift && yarn lint:kotlin",
+    "typetest": "tsd --typings src/index.tsx"
   },
   "keywords": [
     "react-native",
@@ -101,6 +102,7 @@
     "react-native-nitro-modules": "0.35.10",
     "react-test-renderer": "19.0.0",
     "release-it": "^17.10.0",
+    "tsd": "^0.33.0",
     "turbo": "^1.10.7",
     "typescript": "^5.2.2"
   },
@@ -126,6 +128,10 @@
       "<rootDir>/src/**/__tests__/**/*.{js,jsx,ts,tsx}",
       "<rootDir>/src/**/*.{spec,test}.{js,jsx,ts,tsx}"
     ],
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "\\.test-d\\.ts$"
+    ],
     "modulePathIgnorePatterns": [
       "<rootDir>/example/node_modules",
       "<rootDir>/lib/"
@@ -191,6 +197,20 @@
       ]
     ]
   },
+  "tsd": {
+    "typings": "src/index.tsx",
+    "directory": "src/__tests__",
+    "compilerOptions": {
+      "paths": {
+        "@rive-app/react-native": ["./src/index"]
+      },
+      "moduleResolution": "bundler",
+      "jsx": "react-jsx",
+      "lib": ["ESNext"],
+      "strict": true,
+      "allowArbitraryExtensions": true
+    }
+  },
   "create-react-native-library": {
     "languages": "kotlin-swift",
     "type": "nitro-module",

src/__tests__/useViewModelInstance.test-d.ts

@@ -0,0 +1,93 @@
+/**
+ * tsd pins for useViewModelInstance's overload resolution (`yarn typetest`).
+ *
+ * - expectDeprecated: the call must resolve to a @deprecated overload
+ *   (any call not provably `async: true` — bare, async: false, widened
+ *   params, exported param types).
+ * - expectNotDeprecated: literal `async: true` calls must stay clean.
+ * - expectError pins invalid param combinations.
+ * - expectType pins the `required` narrowing behavior.
+ */
+import {
+  expectDeprecated,
+  expectNotDeprecated,
+  expectError,
+  expectType,
+  expectAssignable,
+} from 'tsd';
+import { useViewModelInstance } from '../index';
+import type {
+  UseViewModelInstanceRequiredResult,
+  UseViewModelInstanceResult,
+} from '../index';
+import type { UseViewModelInstanceFileParams } from '../hooks/useViewModelInstance';
+import type { RiveFile } from '../specs/RiveFile.nitro';
+import type { ViewModel } from '../specs/ViewModel.nitro';
+import type { RiveViewRef } from '../index';
+
+declare const file: RiveFile;
+declare const nullableFile: RiveFile | null | undefined;
+declare const vm: ViewModel;
+declare const ref: RiveViewRef;
+
+// ── must resolve to a @deprecated overload ───────────────────────────
+expectDeprecated(useViewModelInstance(file));
+expectDeprecated(useViewModelInstance(nullableFile));
+expectDeprecated(useViewModelInstance(file, { instanceName: 'X' }));
+expectDeprecated(useViewModelInstance(file, { async: false }));
+expectDeprecated(useViewModelInstance(vm, { name: 'X' }));
+expectDeprecated(useViewModelInstance(ref));
+
+// widened `async: boolean` params resolve to the deprecated overload by
+// design — the deprecation message tells callers to re-pin with
+// `{ ...params, async: true }`
+declare const widened: { async: boolean };
+expectDeprecated(useViewModelInstance(file, widened));
+
+// values of the exported param types (async?: boolean) do too
+declare const viaExportedType: UseViewModelInstanceFileParams;
+expectDeprecated(useViewModelInstance(file, viaExportedType));
+
+// ── must stay non-deprecated ─────────────────────────────────────────
+expectNotDeprecated(useViewModelInstance(file, { async: true }));
+expectNotDeprecated(useViewModelInstance(nullableFile, { async: true }));
+expectNotDeprecated(
+  useViewModelInstance(file, { async: true, artboardName: 'Main' })
+);
+expectNotDeprecated(
+  useViewModelInstance(file, { async: true, viewModelName: 'Settings' })
+);
+expectNotDeprecated(useViewModelInstance(vm, { async: true, useNew: true }));
+expectNotDeprecated(useViewModelInstance(ref, { async: true }));
+// the documented fix for widened params re-pins the literal at the call:
+expectNotDeprecated(
+  useViewModelInstance(file, { ...viaExportedType, async: true })
+);
+
+// ── result types ─────────────────────────────────────────────────────
+// required narrowing needs a literal async AND a non-nullable source
+expectType<UseViewModelInstanceRequiredResult>(
+  useViewModelInstance(file, { async: true, required: true })
+);
+// nullable source falls back to the standard result (runtime still throws)
+expectType<UseViewModelInstanceResult>(
+  useViewModelInstance(nullableFile, { async: true, required: true })
+);
+// widened params keep the standard result shape
+expectType<UseViewModelInstanceResult>(useViewModelInstance(file, widened));
+// the required result is a subset of the standard result
+expectAssignable<UseViewModelInstanceResult>(
+  useViewModelInstance(file, { async: true, required: true })
+);
+
+// ── invalid combinations must not compile ────────────────────────────
+// artboardName and viewModelName are mutually exclusive
+expectError(
+  useViewModelInstance(file, {
+    async: true,
+    artboardName: 'A',
+    viewModelName: 'B',
+  })
+);
+// file-source params on a ViewModel source
+expectError(useViewModelInstance(vm, { async: true, artboardName: 'A' }));

src/hooks/__tests__/useViewModelInstance.deprecation.typetest.tsx

@@ -26,5 +26,5 @@
     "target": "ESNext",
     "verbatimModuleSyntax": true
   },
-  "exclude": ["expo-example", "expo55-example", "expo57-example"]
+  "exclude": ["expo-example", "expo55-example", "expo57-example", "**/*.test-d.ts"]
 }