Add synchronous CreateForJavaScript and deprecate AddToContextAsync in ExternalTexture

[bghgary]

[Updated by Copilot on behalf of @bghgary]

Changes

CreateForJavaScript(env, layerIndex = {}) replaces the async AddToContextAsync (kept as a [[deprecated]] shim that wraps it), returning a Napi::Value directly instead of a Promise. Existing ExternalTexture render/MSAA/DeviceLoss tests are migrated to the sync API.

Recursive-mutex deadlock fix. CreateForJavaScript previously held the impl mutex across a JS property lookup that could run a sibling Texture finalizer on the same thread, re-entering the same std::mutex and aborting under MSVC. Graphics::DeviceContext is now resolved before the lock is taken, and the impl mutex is encapsulated so it is never held across a JS callout — making the bug shape structurally impossible.

Single-slice layer selection. CreateForJavaScript/Update take an optional layerIndex to view one array layer of a multi-layer (e.g. NV12 decoder frame-pool) texture, selected at bind time via the bgfx setTexture view API (#3728). Graphics::Texture carries the view sub-range (ViewFirstLayer/ViewNumLayers) and NativeEngine::SetTexture binds the single-slice view. Requires the bgfx.cmake bump to 940054e1.

[bghgary]

[Responded by Copilot on behalf of @bghgary]

Follow-up on the recursive-lock issue and audit, after the fix in 415f193.

Refactor: encapsulate the Impl mutex (04bfb6b)

The original fix resolved DeviceContext before locking, which closes the immediate hole. But the underlying shape — ExternalTexture reaching through m_impl->Mutex() to lock around bodies that mix cached-field reads, bgfx calls, and napi allocation — is structurally fragile. Any future addition to a locked region that allocates a JS object (or triggers a finalizer chain) reopens the same recursive-lock failure mode.

Moved the lock inside Impl so its scope matches the actual cross-thread boundary, no more, no less:

• ImplBase exposes two JS-thread entry points: CreateTexture (constructs a Graphics::Texture*) and DestroyTexture (called from the napi finalizer). Each takes the mutex internally and contains no JS callouts, so the lock can never be held across user-visible JS execution at this site.
• Impl::Update self-locks around the m_info / m_ptr / UpdateTextures publish, with explicit braces around the critical section.
• Mutex(), AddTexture, and RemoveTexture are removed from ImplBase's public surface; m_mutex is no longer reachable from outside the impl.
• ExternalTexture::Width/Height/Get/Update no longer lock. Per the contract in ExternalTexture.h, every operation except CreateForJavaScript is graphics-thread-only and therefore already serialized against Update() by single-threaded execution. The internal locks on these getters did not actually make them safe to call from other threads (no happens-before vs prior Update writes) and only obscured the real boundary.
• ExternalTexture::CreateForJavaScript becomes a thin wrapper: resolve DeviceContext (must run unlocked, per the original fix), call Impl::CreateTexture, then Napi::Pointer::Create with a finalizer that delegates to Impl::DestroyTexture via weak_ptr.

Platform-specific Impl files (D3D11/D3D12/Metal/OpenGL) need no changes — none touch the mutex or texture set.

Test removal: lock-probe regression test (148df39)

The CreateForJavaScriptDoesNotHoldImplMutexAcrossJsCallout test installed a JS getter on _native._Graphics to deterministically reproduce the recursive-lock condition. It worked, but on review it bought too little:

• It validated this specific shape of fix (lock not held across the GetFromJavaScript callout) rather than the absence of the bug. If anyone later switched the impl to std::recursive_mutex, the test would silently pass even with the buggy "lock-held-across-callout" pattern, since recursive_mutex does not throw on re-entrant lock.
• It was tightly coupled to MSVC's std::mutex deadlock-detection throwing std::system_error on recursive lock; the probe is silent on libc++/libstdc++ where re-entrant lock is undefined behavior rather than an exception.
• The wild-case crash involves a Chakra finalizer firing during a JS property lookup, which we cannot deterministically arrange. The test had to fabricate the recursive-lock shape via a JS getter, making it a fault-injection test rather than a true regression for the original failure path.

The encapsulation refactor above provides the structural guarantee the test was approximating. The fix itself is small and well-reviewed; the cost/value trade-off didn't justify keeping the test complexity.

Audit: any other affected sites?

Scanned plugin-side lock sites that bridge graphics-thread state to JS (grep -nE 'scoped_lock|unique_lock|lock_guard' Plugins/**/*.{h,cpp}). The pattern that produced #1646 — long-lived mutex held around Napi::* allocation or JS property lookup — is unique to the original ExternalTexture::CreateForJavaScript site. Other lock sites either (a) cover C++-only critical sections with no JS callouts, or (b) explicitly unlock before invoking JS (e.g., NativeXr::Impl::NotifySessionStateChanged releases its mutex before calling the session-state callback).

The encapsulation pattern from this PR — JS-thread entry points self-lock, never expose Mutex(), never call into JS while locked — is the right model for any future plugin that bridges graphics-thread state to JS.