"Embedding" (simple) API layer (#1701)

## Summary

Introduces a new **`Babylon::Embedding`** layer that gives host apps a
small, opinionated `Runtime` + `View` API for embedding Babylon Native,
and migrates every Playground host (Android, iOS, visionOS, macOS, UWP,
Win32, X11) onto it. The goal is to make platform integration a job that
takes tens — not hundreds — of lines of code, and to do that without
leaking `AppRuntime`, `Graphics::Device`, plugin headers, polyfill
plumbing, or threading rules into the host.

Two layers ship together:

1. **Core C++ API**
(`Embedding/Include/Shared/Babylon/Embedding/{Runtime,View,RuntimeOptions,LogLevel}.h`)
— cross-platform, single source of truth for the lifecycle, threading,
suspend/resume, input forwarding, and XR window management.
2. **Per-platform language facades** that wrap the core API in idiomatic
types for the host language:
- **Android**: JNI shared library (`BabylonNativeEmbedding.cpp`) + a
host-authored Java facade (`BabylonNative.java`)
- **Apple**: `BNRuntime` / `BNView` Obj‑C classes (Swift-friendly via
the bridging header)

## What's new

### `Embedding` core (`Embedding/Source`, `Embedding/Include/Shared`)

Two value types with explicit ownership and a documented contract:

```cpp
Babylon::Embedding::RuntimeOptions options{};
options.enableDebugger = true;
options.log = [](LogLevel level, std::string_view msg) { /* … */ };

Babylon::Embedding::Runtime runtime{options};

runtime.LoadScript("app:///Scripts/babylon.max.js");
runtime.LoadScript("app:///Scripts/scene.js");

Babylon::Embedding::View view{runtime, nativeWindowHandle};
view.Resize(width, height, CoordinateUnits::Physical);

// driven from the host's draw callback:
view.RenderFrame();
```

What the layer takes care of for you:

- **Runtime construction**: spins up `AppRuntime`, `JsRuntime`,
polyfills (Console, Window, XMLHttpRequest, WebSocket, URL, Canvas,
TextDecoder, Performance, Scheduling), and non‑GPU plugins.
- **GPU deferral**: `Graphics::Device`, `NativeEngine`, `NativeInput`,
`NativeCanvas`, `TestUtils`, and (optionally) `NativeXr` / `ShaderCache`
are constructed lazily on the **first** `View::Resize`. Subsequent View
attaches just rebind the Device.
- **Script queuing**: `LoadScript` / `Eval` / `RunOnJsThread` are safe
to call before the first `View` attach; queued and flushed when the
engine comes up.
- **Suspend / Resume**: reference-counted, closes the in-flight frame,
pauses JS timers, optionally persists the shader cache.
- **Input**: `OnPointer*` / `OnMouse*` accept either `Physical` or
`Logical` pixel units; the View handles DPR conversion.
- **XR window**: `Runtime::SetXrWindow` hands off a secondary surface
for NativeXr.
- **Logging**: single `RuntimeOptions::log` sink for
`console.{log,warn,error}`, `Babylon::DebugTrace`, and uncaught JS
exceptions.

### Android facade

`Embedding/Android/` builds the JNI shared library
`libBabylonNativeEmbedding.so` (replacing the old
`BabylonNativeJNI.cpp`). It ships the **native side only** — each host
authors its own Java declarations that match the JNI ABI. The
Playground's facade
(`Apps/Playground/Android/BabylonNative/…/com/babylonjs/embedding/BabylonNative.java`,
replacing the old `Wrapper.java`) is a thin `static`-method mirror of
the C++ API:

- **Process lifecycle**: `setContext`, `setCurrentActivity`, `pause`,
`resume`, `requestPermissionsResult`
- **Runtime**: `runtimeCreate` (optionally with a nested
`RuntimeOptions`), `runtimeDestroy`, `runtimeLoadScript`, `runtimeEval`,
`runtimeSetXrSurface`, `runtimeIsXrActive`
- **View**: `viewAttach`, `viewDetach`, `viewRenderFrame`, `viewResize`,
`viewPointerDown` / `viewPointerMove` / `viewPointerUp`

A separate `com.library.babylonnative.BabylonView` helper wires
`SurfaceHolder.Callback` and touch events to those calls.

### Apple facade

`Embedding/Apple/` — Obj‑C wrappers (`BNRuntime`, `BNView`,
`BNViewDelegate`) usable from Obj‑C and from Swift via the bridging
header. Used by Playground iOS, macOS, and visionOS. `BNRuntimeNative.h`
exposes the underlying `Babylon::Embedding::Runtime*` for callers that
need the C++ API.

## Host app migrations

Every Playground host now runs on top of the Embedding layer:

| Host | Before | After |
|---|---|---|
| Android | `BabylonNativeJNI.cpp` + `Wrapper.java` | `BabylonNative`
Java facade over the JNI layer |
| iOS | `LibNativeBridge.{h,mm}` + ad-hoc Swift glue | `BNRuntime` /
`BNView`, ~75-line `ViewController.swift` |
| macOS | `ViewController.mm` doing its own AppContext plumbing | Same
`BNRuntime` / `BNView` types as iOS |
| visionOS | `LibNativeBridge.{h,mm}` + custom App.swift threading |
`BNRuntime` / `BNView` + bridging header |
| Win32 | `AppContext` + manual `UpdateSize` / mouse plumbing |
`Runtime` + `View` with `WM_POINTER` → `View::On*` |
| UWP | C++/WinRT `AppContext` + manual swap-chain plumbing | `Runtime`
+ `View` from `IInspectable` |
| X11 | `AppContext` + X11 event handlers | `Runtime` + `View` with
`View::OnMouse*` |

The shared `AppContext.{h,cpp}` is gone — each host now constructs a
`Runtime` + `View` directly.

## Lifecycle contract

- **First View attach is the heavy step.** Hosts MUST call `Resize` at
least once with the surface's pixel dimensions before the first
`RenderFrame` — the Device is built on the first Resize.
- **One View per Runtime at a time.** `View` constructor throws
`std::runtime_error` on double-attach.
- **Destroy Views before their Runtime.** `~View` clears the
back-reference, so LIFO destruction works; `~Runtime` asserts (debug
builds) if a View is still attached.
- **Frame thread**: `RenderFrame`, `Resize`, `Suspend`, `Resume`,
`LoadScript`, `Eval`, `RunOnJsThread`, View construction/destruction.
- **Any thread**: `OnPointer*` / `OnMouse*` / `IsSuspended` /
`IsXrActive` / `SetXrWindow`.

## File scope

```
Embedding/
  Include/Shared/Babylon/Embedding/{Runtime,View,RuntimeOptions,LogLevel}.h
  Source/{Runtime,View}.cpp + RuntimeImpl.h
  Android/ — JNI shared library (Java facade lives per-host; see Playground)
  Apple/   — BNRuntime / BNView / BNViewDelegate

Apps/Playground/
  Win32/ UWP/ X11/ macOS/ iOS/ visionOS/ Android/   (all migrated)
```

## Closed open items

- [x] AI-generated comment cleanup
- [x] Naming (renamed to "Embedding")
- [x] All Playground hosts migrated (Android, iOS, visionOS, macOS, UWP,
Win32, X11)
- [x] `RunOnJsThread` now has an `afterScriptLoad` parameter
- [x] `Runtime` / `View` are regular movable value types
- [x] Removed the planning `.md` from the repo root
- [ ] Real fix for DeviceImpl.cpp issue

Author: ryantrem

.github/instructions/babylon-native-debugging.instructions.md

@@ -24,7 +24,7 @@ For pure RenderDoc CLI usage (any app, not BN-specific), see
 |---|---|
 | `Apps/Playground/Shared/CommandLine.{h,cpp}` | Argument parser. Single source of truth for supported flags. |
 | `Apps/Playground/Shared/Diagnostics.{h,cpp}` | Crash handler, `DumpFailure`, finish-line, exit-code tracking. |
-| `Apps/Playground/Shared/AppContext.cpp` | Wires `UnhandledExceptionHandler` + `console.error` into `DumpFailure`; injects `_playgroundOptions` into JS. |
+| `Apps/Playground/Win32/App.cpp` (and the other per-host `App.*`) | Wires the `RuntimeOptions::log` callback into `DumpFailure` (`JS CONSOLE ERROR` for `LogLevel::Error`, `UNCAUGHT JS ERROR` for `LogLevel::Fatal`) and injects `_playgroundOptions` into JS via `Runtime::RunOnJsThread`. |
 | `Apps/Playground/Scripts/validation_native.js` | Test runner. Reads `_playgroundOptions`, picks tests, calls `TestUtils.captureNextFrame()`. Reference-image load failures arrive via `BABYLON.Tools.LoadFile`'s `onLoadFileError` and are tagged with `MISSING_REFERENCE_IMAGE:`. |
 | `Apps/Playground/Scripts/config.json` | Test catalog. Each entry has `title`, `playgroundId`/`scriptToRun`, `referenceImage`, optional `excludeFromAutomaticTesting`/`reason`/`onlyVisual`/`renderCount`/`capture`/`threshold`/`errorRatio`. |
 | `Plugins/TestUtils/Source/TestUtils.cpp` | Native side of `TestUtils.captureNextFrame()` -- calls `m_deviceContext.RequestCaptureNextFrame()`. |
@@ -80,13 +80,15 @@ When you see `[Error] Error: Cannot load X` in stdout, **scroll up** --
 short error line. The short line is kept so legacy log scrapers still match.
 
 ### 3. JS stack on every `console.error`
-`AppContext.cpp`'s `Console::Initialize` callback calls
+The Embedding layer's `Console::Initialize` callback calls
 `Babylon::Polyfills::Console::CaptureCurrentJsStack(env)` on every
-`LogLevel::Error` message and appends the captured stack to the
-`DumpFailure` banner body. The capture is best-effort -- if the JS engine
-can't produce a stack (no JS context active, etc.) the helper returns an
-empty string and the banner just shows the message.
-Do not add per-callsite stack capture -- it's automatic.
+`LogLevel::Error` message and appends the captured stack to the message
+body that the host's `RuntimeOptions::log` callback receives (which the
+Playground hosts then route into the `DumpFailure` banner). The capture is
+best-effort — if the JS engine can't produce a stack (no JS context active,
+unsupported engine, etc.) the helper returns an empty string and the host
+just gets the bare message.
+Do not add per-callsite stack capture — it's automatic.
 
 ### 4. Colored finish line
 `Playground: Finished in <time>. (exit <code>)` is printed once at every exit

Apps/Playground/Android/BabylonNative/CMakeLists.txt

@@ -8,45 +8,30 @@ project(BabylonNative)
 get_filename_component(PLAYGROUND_DIR "${CMAKE_CURRENT_LIST_DIR}/../.." ABSOLUTE)
 get_filename_component(REPO_ROOT_DIR "${PLAYGROUND_DIR}/../.." ABSOLUTE)
 
+# Build the cross-platform Embedding facade *and* the Android JNI
+# interop layer (`libBabylonNativeEmbedding.so`). The Playground
+# Android app loads that library directly via `BabylonNative.java`
+# (in the `com.babylonjs.embedding` package).
+set(BABYLON_NATIVE_EMBEDDING ON CACHE BOOL "" FORCE)
+set(BABYLON_NATIVE_EMBEDDING_ANDROID ON CACHE BOOL "" FORCE)
+
 add_subdirectory(${REPO_ROOT_DIR} "${CMAKE_CURRENT_BINARY_DIR}/BabylonNative")
 
-add_library(BabylonNativeJNI SHARED
-    src/main/cpp/BabylonNativeJNI.cpp
-    ${PLAYGROUND_DIR}/Shared/AppContext.cpp
-    ${PLAYGROUND_DIR}/Shared/Diagnostics.cpp)
+# Append a Playground-specific JNI helper to the generic
+# BabylonNativeEmbedding target so the bootstrap script list can stay
+# in Apps/Playground/Shared/PlaygroundScripts.{h,cpp} (shared with the
+# Win32 / iOS / macOS hosts) instead of being duplicated on the Java
+# side. Compiling these into the same .so keeps the Embedding layer
+# as a single in-process instance — handles produced by one entry point
+# can be safely consumed by another.
+target_sources(BabylonNativeEmbedding
+    PRIVATE src/main/cpp/PlaygroundJNI.cpp
+            ${PLAYGROUND_DIR}/Shared/Diagnostics.cpp
+            ${PLAYGROUND_DIR}/Shared/PlaygroundScripts.cpp)
 
-target_include_directories(BabylonNativeJNI
+target_include_directories(BabylonNativeEmbedding
     PRIVATE ${PLAYGROUND_DIR})
 
-target_link_libraries(BabylonNativeJNI
-    PRIVATE GLESv3
-    PRIVATE android
+target_link_libraries(BabylonNativeEmbedding
     PRIVATE bx
-    PRIVATE EGL
-    PRIVATE log
-    PRIVATE -lz
-    PRIVATE AbortController
-    PRIVATE AndroidExtensions
-    PRIVATE AppRuntime
-    PRIVATE Blob
-    PRIVATE Canvas
-    PRIVATE Console
-    PRIVATE Fetch
-    PRIVATE File
-    PRIVATE GraphicsDevice
-    PRIVATE NativeCamera
-    PRIVATE NativeCapture
-    PRIVATE NativeEncoding
-    PRIVATE NativeEngine
-    PRIVATE NativeInput
-    PRIVATE NativeOptimizations
-    PRIVATE NativeTracing
-    PRIVATE NativeXr
-    PRIVATE Performance
-    PRIVATE ScriptLoader
-    PRIVATE ShaderCache
-    PRIVATE TestUtils
-    PRIVATE TextDecoder
-    PRIVATE TextEncoder
-    PRIVATE Window
-    PRIVATE XMLHttpRequest)
+    PRIVATE Foundation)     # for <Babylon/PerfTrace.h> in PlaygroundScripts.cpp

Apps/Playground/Android/BabylonNative/consumer-rules.pro

@@ -0,0 +1,2 @@
+-keep class com.babylonjs.embedding.BabylonNative { *; }
+-keep class com.babylonjs.embedding.BabylonNative$RuntimeOptions { *; }

Apps/Playground/Android/BabylonNative/src/main/cpp/BabylonNativeJNI.cpp

@@ -0,0 +1,39 @@
+// Playground-specific JNI helper. Built into the same .so as the generic
+// Embedding/Android JNI (added via target_sources in the Playground
+// CMakeLists), so there's a single copy of Babylon::Embedding across
+// the process — avoids cross-library handle-passing UB.
+//
+// Sole purpose: surface Apps/Playground/Shared/PlaygroundScripts.{h,cpp}
+// to Java so the bootstrap script list stays in one place, shared with
+// the other Playground hosts.
+
+#include <Babylon/Embedding/Runtime.h>
+#include <Babylon/Embedding/Android/RuntimeHandle.h>
+
+#include <Shared/PlaygroundScripts.h>
+
+#include <jni.h>
+
+extern "C"
+{
+
+JNIEXPORT void JNICALL
+Java_com_android_babylonnative_playground_PlaygroundActivity_loadBootstrapScripts(
+    JNIEnv*, jclass, jlong runtimeHandle)
+{
+    auto* runtime = Babylon::Embedding::Android::RuntimeFromHandle(runtimeHandle);
+    if (runtime == nullptr)
+    {
+        return;
+    }
+
+    // Idempotent process-wide setup (PerfTrace level, etc.).
+    Playground::Initialize();
+
+    // Queue bootstrap scripts; they run after the first View attach
+    // completes engine init on the JS thread.
+    Playground::LoadBootstrapScripts(*runtime);
+}
+
+} // extern "C"
+