Skip to content

feat(compiler,mobile): support host JS engine reuse and Boa-free native kernels - #105

Merged
jbingham merged 2 commits into
mainfrom
feat/host-js-engine-and-kernels
Nov 17, 2026
Merged

jbingham merged 2 commits into
mainfrom
feat/host-js-engine-and-kernels

Conversation

@jbingham

Copy link
Copy Markdown
Collaborator

Summary

Applications that already embed a JavaScript engine (Boa, QuickJS, JavaScriptCore, Hermes, or V8) previously had to link three-live's bundled Boa VM as well, duplicating engine binary size, per-realm memory overhead, and native symbol surfaces. In addition, maintaining separate Rust (glb.rs::write_glb) and TypeScript (three-convert.ts::sceneToGLB) GLB serializers risked subtle behavioral drift between native and web compilation paths.

This PR enables one JS engine per host application while keeping turnkey com.google.threelive:compiler and ThreeLiveCompiler integrations 100% drop-in compatible:

  1. Unified TypeScript GLB Serialization (sceneToGLB)

    • Removes compiler/src/glb.rs::write_glb (~1,150 lines) and routes ThreeEngine::compile_glb and transcode_three_to_glb through three-convert.ts::sceneToGLB with zero-copy native Uint8Array capture (__three_live_capture_output__).
    • Hardens glb::read_glb and extractMeshesFromGLB against oversized count/componentType allocations, interleaved byteStride accessors, Uint8 indices, and scene/mesh/vertex/texture quotas.
  2. Hosted Compiler Bundle & engine-requirements.json

    • Emits dist/three-live-compiler-bundle.{js,cjs,min.js} (< 260 KB gz) and dist/engine-requirements.json (contractVersion: 1).
    • Provides self-contained TextEncoder/TextDecoder UTF-8 polyfills for bare ES2020 realms, ThreeEngine.{compileToGLB, compileToUSDZ, glbToUSDZ, aiCall, installSandboxHardening}, and optional globalThis.__three_live_host__ v1 host/kernel acceleration.
    • Locks baseline intrinsics, %TypedArray.prototype%, iterator prototypes, JSON, getSharedRegistry(), and all native hook slots ({writable: false, configurable: false}), hides __three_live_host__ from user scripts, and isolates top-level lexical declarations across warm compiles.
  3. Boa-Free Native three_live_kernels Library (THREE_LIVE_KERNELS_ABI_VERSION = 1)

    • Splits compiler/Cargo.toml features into kernels (zero boa_engine in cargo tree and nm), boa, cli, wasm, and jni.
    • Adds compiler/include/three_live_kernels.h and three_live_kernels_table(&count) exposing 24 self-describing C-ABI kernels (primitives, ExtrudeGeometry, TextGeometry, CSG, ProceduralTexture PBR + height-to-normal + AO, PNG/JPEG decode, and USDZ packaging) with panic-catching boundaries and bounded slice/scalar validation.
    • Enforces disjoint exported symbol sets via exported_symbols_kernels.lds and exported_symbols_compiler.lds.
  4. Pluggable ThreeCompilerBackend & Mobile Artifact Split

    • Android: Splits :mobile:android-runtime (com.google.threelive:runtime, pure Kotlin/JVM with zero JNI), :mobile:android-kernels (com.google.threelive:kernels, libthree_live_kernels.so + ThreeLiveKernels), and :mobile:android (com.google.threelive:compiler, api(project(":mobile:android-runtime")) + NativeThreeCompilerBackend). Optional :filament, :firebase-ai, :detect-mlkit, :hands-androidxr, and :hands-mediapipe modules now depend on :mobile:android-runtime.
    • Apple SwiftPM: Splits ThreeLiveRuntime (zero C/Boa), ThreeLiveKernels (ThreeLiveKernels.xcframework), ThreeLiveCompilerNative (ThreeLiveCompiler.xcframework), and umbrella ThreeLiveCompiler (@_exported import ThreeLiveRuntime + automatic NativeThreeCompilerBackend fallback). ThreeLiveFirebaseAI now depends only on ThreeLiveRuntime.

Testing

  • Web & Hosted Bundle (node scripts/build.js && node scripts/build.js --test): all 24 bundle budgets, compiler_bundle_test (including sandbox hardening, lexical breakout rejection, warm realm reuse, aiCall parity, and host kernel dispatch), three-live, xr-live, and evals suites pass.
  • Rust (cargo test across --no-default-features --features kernels,jni and default features): kernels unit tests, C-ABI kernels_embedder_test, three_compiler_test (87/87), and zero boa_engine dependencies/symbols verified on kernels.
  • Android & Apple: ThreeCompilerBackendTest, ThreeLiveKernelsTest, ThreeLiveKernelsTests, ThreeLiveCompilerTests, iOS XCFramework build + symbol isolation verification (verify_xcframework.sh), and Android/iOS demo builds pass.

…ve kernels

Unify GLB serialization on TypeScript `sceneToGLB`, publish a self-contained hosted compiler bundle (`dist/three-live-compiler-bundle.min.js`) paired with `dist/engine-requirements.json` and a Boa-free C ABI (`three_live_kernels.h`), and split the Android and Apple SDKs into JS-engine-free runtime, Boa-free kernel, and turnkey compiler artifacts behind a pluggable `ThreeCompilerBackend` SPI.

- **Unified TypeScript GLB Serialization**: Remove the duplicate Rust `glb.rs::write_glb` serializer so both native (`ThreeEngine::compile_glb`) and web compilation paths emit identical glTF 2.0 binaries via `three-convert.ts::sceneToGLB` with zero-copy native buffer capture.
- **Hosted Compiler Bundle & Engine Manifest**: Add `three-live-compiler-bundle.{js,cjs,min.js}` (`< 260 KB gz`) exposing `ThreeEngine.{compileToGLB, compileToUSDZ, glbToUSDZ, aiCall, installSandboxHardening}`, UTF-8 polyfills for bare ES2020 realms, `globalThis.__three_live_host__` v1 shims, and `engine-requirements.json`.
- **Boa-Free `three_live_kernels` C ABI & JNI**: Split Cargo features into `kernels` (zero `boa_engine`) and `boa`, adding `compiler/include/three_live_kernels.h` (`THREE_LIVE_KERNELS_ABI_VERSION = 1`), `three_live_kernels_table(&count)` (24 self-describing geometry, CSG, procedural texture, image, and USDZ kernels), `ThreeLiveKernels` JNI/Swift wrappers, and disjoint linker version scripts (`exported_symbols_kernels.lds` / `exported_symbols_compiler.lds`).
- **Android & Apple Artifact Split (`ThreeCompilerBackend`)**:
  - Android: `:mobile:android-runtime` (`com.google.threelive:runtime`, zero JNI/Boa), `:mobile:android-kernels` (`com.google.threelive:kernels`), and `:mobile:android` (`com.google.threelive:compiler` auto-registering `NativeThreeCompilerBackend` via `Class.forName` fallback). Optional `:filament`, `:firebase-ai`, `:detect-mlkit`, `:hands-androidxr`, and `:hands-mediapipe` adapters now depend only on `:runtime`.
  - Apple SwiftPM: `ThreeLiveRuntime` (zero C/Boa), `ThreeLiveKernels` (`ThreeLiveKernels.xcframework`, zero Boa), `ThreeLiveCompilerNative` (`ThreeLiveCompiler.xcframework`), and umbrella `ThreeLiveCompiler` (`@_exported import ThreeLiveRuntime` + `NSClassFromString` auto-registration).
@jbingham
jbingham merged commit a773f55 into main Nov 17, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants