fix(docs): the documented 'metal' delegate throws unconditionally

[giaBaoJS]

The contradiction

The v2 → v3 migration guide instructs users to migrate to the 'metal' delegate:

https://github.com/mrousavy/react-native-fast-tflite/blob/691f4b8/MIGRATION_V2_TO_V3.md#L38-L41

- const model = useTensorflowModel(source, 'metal')
+ const model = useTensorflowModel(source, ['metal'])

That exact "after" snippet fails 100% of the time, on every platform. cpp/TfliteHelpers.cpp#L149-L151:

TfLiteDelegate* getMetalDelegate() {
  throw std::runtime_error("Metal Delegate is not yet supported!");
}

There is no #ifdef and no build flag around it — unlike getCoreMLDelegate() (#ifdef __APPLE__ / #if FAST_TFLITE_ENABLE_CORE_ML, TfliteHelpers.cpp#L133-L147), getNNAPIDelegate() (#ifdef ANDROID) and getAndroidGPUDelegate() (#ifdef ANDROID). getMetalDelegate() is the only one whose body is a bare, unconditional throw.

The reachable path is unconditional too: createModel loops over every requested delegate and calls getDelegate(), which routes METAL straight there — HybridTfliteModule.cpp#L18-L31 and #L46-L49. So the throw happens during model creation, before the interpreter is built.

Three more places repeat the claim:

• README.md#L15 — "Supports GPU-accelerated delegates (CoreML/Metal/OpenGL)". The ### Using GPU Delegates section below it only documents CoreML and Android GPU/NNAPI, so the feature bullet is the only place Metal is promised.
• example/ios/Podfile#L18 — $EnableMetalDelegate=true. The podspec never reads that global; it reads only $EnableCoreMLDelegate and only defines FAST_TFLITE_ENABLE_CORE_ML (react-native-fast-tflite.podspec#L5-L9, #L29-L31). Setting it does nothing — it reads as "this is the switch that turns Metal on", which is the most misleading part of the whole story.
• src/specs/Tflite.nitro.ts#L4 — 'metal' is an undocumented member of the public TensorflowModelDelegate union, so autocomplete offers it as an equal peer of 'core-ml'.

What this PR changes

Documentation and one error message. No behaviour change, no type-level breaking change.

File	Change
README.md	Feature bullet now names the delegates that have an implementation
MIGRATION_V2_TO_V3.md	Array-migration example uses 'core-ml'; new short section documents that 'metal' is not implemented
src/specs/Tflite.nitro.ts	JSDoc on TensorflowModelDelegate documenting each member, and that 'metal' is deprecated / not implemented
cpp/TfliteHelpers.cpp	Error message names the delegates that actually work
example/ios/Podfile	Removes the no-op $EnableMetalDelegate=true

Three stale doc comments fixed in passing

delegates became a required positional parameter, but both doc comments still described it as optional with a default:

• src/loadTensorflowModel.ts#L25 and src/useTensorflowModel.ts#L27: "Uses the standard CPU delegate per default" — there is no default; you must pass []. (docs: add required delegates array to README examples #182 fixed the README examples but not these.) They also pointed users at metal as a GPU-accelerated option.
• src/useTensorflowModel.ts#L53: the comment example ['core-ml', 'default'] references 'default', which the same migration guide documents as removed and which no longer typechecks.

Deprecate vs. remove 'metal'

I deprecated it in place rather than removing it from the union. Happy to switch if you'd rather — the reasoning:

1. Removing it is a breaking type change. Anyone with ['metal'] in their source compiles today (it only throws at runtime). Removing the member turns that into a build error. Deciding whether that break is worth taking, and in which release, is your call — it doesn't belong in a docs-correctness PR.
2. Removing it means regenerating nitrogen output and renumbering the enum. 'metal' is member 0 of the generated TensorflowModelDelegate enum (nitrogen/generated/shared/c++/TensorflowModelDelegate.hpp#L32-L35). Dropping it shifts CORE_ML 1→0, NNAPI 2→1, ANDROID_GPU 3→2 across the generated JSI converters, and requires deleting getMetalDelegate() from cpp/TfliteHelpers.cpp + cpp/TfliteHelpers.hpp and the METAL case from cpp/HybridTfliteModule.cpp.
3. That larger diff would land on top of in-flight C++ work. fix(ios): zero-initialize TfLiteCoreMlDelegateOptions #196 edits cpp/TfliteHelpers.cpp; fix: skip unavailable delegates and free delegates on model destruction #197 and feat: implement dispose() for deterministic native resource release #198 edit cpp/HybridTfliteModule.cpp. As it stands this PR merges cleanly with all three (verified locally with a trial merge of fix(ios): zero-initialize TfLiteCoreMlDelegateOptions #196, the only one sharing a file with this PR — clean).
4. The runtime already stops anyone who tries; this PR just makes the throw explain what to use instead.

Honest caveat about the deprecation: I first tried a per-member /** @deprecated */ JSDoc directly on | 'metal'. I checked whether TypeScript actually surfaces it, and it does not — querying the TS 5.3.3 language service for completions at a TensorflowModelDelegate position returns kindModifiers: "" for every member, so there is no strikethrough on string-literal union members. (Prettier also collapses the union onto one line when a comment is inserted mid-union, which made the diff noisier for no gain.) So I moved the documentation to the type alias, where getQuickInfoAtPosition does return it — hovering TensorflowModelDelegate now shows the per-delegate list including the Metal warning. I'd rather say that plainly than imply a strikethrough that doesn't exist.

I have not claimed anywhere that Metal could or should be implemented — I only checked what the code does today, not what it would take to add.

Verification

• yarn typecheck — passes
• yarn lint — passes
• npx clang-format --dry-run -Werror cpp/TfliteHelpers.cpp — clean (CI uses clang-format 16; checked with 17)
• npx nitrogen — regenerates nitrogen/generated/** byte-identically, confirming the JSDoc-only spec change does not affect generated native code
• Type-compat proof: compiled a file containing const d: TensorflowModelDelegate = 'metal', loadTensorflowModel(src, ['metal']) and useTensorflowModel(src, [d]) against this branch — 0 errors, so no existing user code breaks
• Trial-merged fix(ios): zero-initialize TfLiteCoreMlDelegateOptions #196 (the only open PR touching a file this PR touches) — no conflict

yarn test currently fails on main for unrelated reasons (Babel/jest config), untouched here.