@symbiote-native/engine 0.5.0 → 1.0.0

package/README.md

@@ -1,12 +1,21 @@
 # @symbiote-native/engine
 
-The **retained shadow-tree engine** at the bottom of [SymbioteNative](../../README.md) — the one
-package every framework adapter (`@symbiote-native/react`, `@symbiote-native/vue`, `@symbiote-native/angular`, …)
-drives, and the only place the mutation→clone-on-write translation into React Native's Fabric
-exists. It holds a retained, mutable tree of nodes that an adapter mutates cheaply
-(`appendChild` / `setProp` / `removeChild` …), then on commit diffs that tree against Fabric's
-current one, clones only what changed, and calls `completeRoot` — the persistent, clone-on-write
-dance Fabric requires, done **once**, for every framework.
+The package at the bottom of [SymbioteNative](../../README.md) that every framework adapter
+(`@symbiote-native/react`, `@symbiote-native/vue`, `@symbiote-native/angular`, …) drives, and the
+only place the mutation→clone-on-write translation into React Native's Fabric exists. **The
+retained tree itself lives in C++ now**, in `cpp/SymbioteTree.cpp`, reached through this package's
+`src/` — a node handle returned to JS is a thin reference into that native tree, not a JS object
+holding the tree's state.
+
+An adapter still mutates a node cheaply (`appendChild` / `setProp` / `removeChild` …), but each
+call now appends an op to the current commit's buffer instead of touching a tree directly. On
+commit, the whole buffer crosses into C++ in **one** JSI call; `SymbioteTree` applies the ops
+against the retained tree, clones only what changed, resolves the platform-parity rules keyed on
+each node's Fabric tag (`cpp/SymbioteFabricProps.cpp` — RN's own component-level behavior, like
+`Pressable`'s `disabled` fold or a `<Text>`'s default `ellipsizeMode`, ported once instead of per
+adapter), and calls into Fabric's C++ `UIManager` directly to commit — the persistent,
+clone-on-write dance Fabric requires, done **once**, for every framework, with one crossing per
+commit instead of one per mutation.
 
 > New to SymbioteNative? The [root README](../../README.md) has the architecture and the one fact it
 > rests on — React is just _one client_ of `nativeFabricUIManager`. This package is what sits
@@ -101,10 +110,10 @@ before a tag is guaranteed to exist.
   `ActionSheetIOS`, `Linking`, `Vibration`, `ToastAndroid`, `Settings`, `I18nManager`.
 - **Host behaviors** (`registerHostBehavior` / `IHostBehavior` / `hasHostBehaviors` /
   `clearHostBehaviors` / `appListenerFor` / `setBehaviorListener` / `requestCommitFor`) — the
-  registry that lets a primitive's state machine live directly on the engine node instead of
-  inside a framework component, so a `Pressable`/`Switch`/`TextInput`/`Image` can compile to a
-  bare intrinsic tag ("host-primitive lowering"). `@symbiote-native/components` registers its
-  behaviors against this seam; the engine never imports them back.
+  registry that lets a primitive's state machine live directly on the engine node instead of inside
+  a framework component, so `pressable`/`switch`/`text-input`/`image` are bare intrinsic tags.
+  `@symbiote-native/components` registers its behaviors against this seam; the engine never imports
+  them back.
 - **`Animated`** — both the JS and native driver (`timing` / `spring` / `decay` / `loop` /
   `ValueXY` / tracking / `diffClamp` / `Easing`), including the native-event attachment path
   (`attachNativeEvent`, `AnimatedEvent`).
@@ -123,9 +132,11 @@ before a tag is guaranteed to exist.
 
 - It does not know about React, Vue, Angular, JSX, templates, or reactivity — an adapter maps its
   own framework idioms onto this API, never the other way around.
-- It does not touch Fabric C++, JSI, or Yoga directly — it calls `nativeFabricUIManager`
-  (`createNode` / `cloneNodeWithNewProps` / `appendChildToSet` / `completeRoot`), the same
-  framework-agnostic seam React's own renderer uses.
+- The JS side (`src/`) does not touch Fabric, JSI, or Yoga directly — it only builds the
+  command buffer and hands it to `SymbioteTree` in one crossing. That C++ tree is the layer
+  that actually calls Fabric's `UIManager` (`createNode` / `cloneNodeWithNewProps` /
+  `appendChildToSet` / `completeRoot`), the same framework-agnostic seam React's own renderer
+  uses further up, from JS, through `nativeFabricUIManager`.
 - It is not a component library — visual components (Switch, Modal, the lists, …) live in
   [`@symbiote-native/components`](../components), built on top of this package's `Descriptor`-free
   mutation API.
@@ -145,3 +156,17 @@ before a tag is guaranteed to exist.
 pnpm test              # vitest, from the workspace root — headless, against a fake Fabric slot
 DEBUG=1 pnpm test       # same, with diagnostic logs on
 ```
+
+That covers the JS side (`src/`) against a fake `nativeFabricUIManager`. `SymbioteTree` itself
+(`cpp/`) has its own test tiers, run from the workspace root:
+
+```bash
+pnpm test:cpp           # gtest unit tests over SymbioteTree, asserts on — the build every PR runs
+pnpm test:itest         # the JS-driven correctness suite (core/engine/cpp/tests/js/*.itest.ts*),
+                         # a real six-adapter integration harness against the C++ tree, asserts on
+pnpm bench:itest        # the same itest harness, Release build (NDEBUG + -O) — for timings, never asserts
+pnpm test:android       # test:itest built with -DSYMBIOTE_PLATFORM_ANDROID=ON, for the #ifdef ANDROID rules
+```
+
+Never read `test:itest`'s timings — that build has asserts on and is measurably slower than what
+ships; use `bench:itest` for anything you intend to quote a millisecond from.

package/android/CMakeLists.txt

@@ -0,0 +1,51 @@
+# The Android half of the engine's native module. It compiles `../cpp` — the SAME sources the
+# podspec globs — plus the JNI registration shim beside this file. Nothing under `cpp/` is copied
+# or forked; the whole point of the split is that only the registration is per-platform.
+#
+# Shaped after the one third-party precedent that is already in this repo's own app trees and
+# already builds against RN 0.86: `react-native-screens/android/CMakeLists.txt`.
+
+cmake_minimum_required(VERSION 3.13)
+
+project(symbiote_engine)
+
+set(CMAKE_VERBOSE_MAKEFILE ON)
+
+# Globbed, not listed, and that is deliberate: the iOS podspec globs `cpp/**/*.{h,cpp}`, so a listed
+# set here would mean a new shared source compiles on one platform and not the other — a link error
+# on Android for a symbol iOS resolves fine, arriving whenever somebody adds a file and forgets this
+# line. RN's own fantom tester globs its sources for the same reason.
+file(GLOB SYMBIOTE_SHARED_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/../cpp/*.cpp)
+
+add_library(symbiote_engine
+        SHARED
+        ${SYMBIOTE_SHARED_SOURCES}
+        src/main/cpp/SymbioteEngineJni.cpp
+)
+
+# So the JNI shim can say `#include "SymbioteEngineBindings.h"` rather than walk four levels up.
+target_include_directories(symbiote_engine PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../cpp)
+
+set_target_properties(symbiote_engine PROPERTIES
+        CXX_STANDARD 20
+        CXX_STANDARD_REQUIRED ON
+        CXX_EXTENSIONS OFF
+        POSITION_INDEPENDENT_CODE ON
+)
+
+target_compile_definitions(symbiote_engine PRIVATE -DFOLLY_NO_CONFIG=1)
+
+# `jsi` and `reactnative` are the only two prefab modules ReactAndroid publishes
+# (ReactAndroid/build.gradle.kts, the `prefab { }` block — the third is `hermestooling`).
+# `reactnative` is the merged library that carries react/renderer/uimanager, react/renderer/mounting
+# and the turbomodule JNI headers our C++ includes; there is no separate
+# `react_renderer_uimanager` prefab target to link.
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+
+target_link_libraries(symbiote_engine
+        ReactAndroid::reactnative
+        ReactAndroid::jsi
+        fbjni::fbjni
+        android
+)

package/android/build.gradle

@@ -0,0 +1,90 @@
+// @symbiote-native/engine's Android native half — the twin of `symbiote-engine.podspec`.
+//
+// `@symbiote-native/engine` is a DIRECT dependency of every example app, so RN's autolinking finds
+// this project with no entry in anybody's `settings.gradle` — the same reason the podspec needs no
+// Podfile line. Built as a subproject of the consuming app, so it reads the app's pinned SDK/NDK
+// versions from `rootProject.ext` (see `examples/*/android/build.gradle`), falling back to the same
+// defaults `packages/android` uses when built in isolation.
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+// Runs codegen over `../codegen-specs`, producing `NativeSymbioteEngineSpec` (Java) and the JNI spec
+// the app's autolinking links. Needed for the module to be a real TURBO module: the legacy-interop
+// path (`TurboModuleManager::getLegacyModule`) never consults `TurboModuleWithJSIBindings`, so a
+// plain `ReactContextBaseJavaModule` — the shape `packages/android` uses — would install nothing.
+// The plugin supplies `root`/`reactNativeDir`/`jsRootDir` for a library itself and adds the generated
+// java dir to `sourceSets.main` (ReactPlugin.kt, `configureCodegen(isLibrary = true)`), so no
+// `react { }` block and no `sourceSets` line are needed here.
+apply plugin: "com.facebook.react"
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "dev.symbiotenative.engine"
+  compileSdk safeExtGet("compileSdkVersion", 36)
+
+  if (rootProject.hasProperty("ndkPath")) {
+    ndkPath rootProject.ext.ndkPath
+  }
+  if (rootProject.hasProperty("ndkVersion")) {
+    ndkVersion rootProject.ext.ndkVersion
+  }
+
+  defaultConfig {
+    minSdk safeExtGet("minSdkVersion", 24)
+
+    externalNativeBuild {
+      cmake {
+        arguments "-DANDROID_STL=c++_shared"
+      }
+    }
+  }
+
+  buildFeatures {
+    // Consumes ReactAndroid's published `jsi` / `reactnative` prefab modules.
+    prefab true
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  packagingOptions {
+    // RN's own .so files get copied into this library's intermediates by prefab and would collide
+    // when the app merges native libs. Only `libsymbiote_engine.so` should ship from here. Since
+    // RN 0.76 the renderer/jni libraries are merged into `libreactnative.so`, so that one name
+    // covers all of them (same list as `react-native-screens`).
+    excludes = [
+        "META-INF",
+        "META-INF/**",
+        "**/libjsi.so",
+        "**/libc++_shared.so",
+        "**/libfbjni.so",
+        "**/libreactnative.so",
+    ]
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  // Version-less: the consuming app's React Native Gradle plugin pins react-android, and it brings
+  // fbjni's prefab in transitively (which is what `find_package(fbjni)` resolves).
+  implementation "com.facebook.react:react-android"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/cpp/SymbioteEngineJni.cpp

@@ -0,0 +1,72 @@
+// Android's registration shim — the twin of `core/engine/ios/SymbioteEngineModule.mm`, and the only
+// file in this folder that is not build configuration. Everything it does is hand the platform-shared
+// `symbiote::installBindings` to whatever runtime React Native offers it.
+//
+// The seam is `TurboModuleWithJSIBindings`
+// (ReactAndroid/src/main/java/com/facebook/react/turbomodule/core/interfaces/TurboModuleWithJSIBindings.kt).
+// `TurboModuleManager::getTurboModule` checks `isInstanceOf(JTurboModuleWithJSIBindings)` right after
+// it creates the Java module and immediately calls `installer->cthis()->installBindings(runtime, ...)`
+// (ReactAndroid/src/main/jni/react/turbomodule/ReactCommon/TurboModuleManager.cpp:205-216). That is
+// exactly what `installJSIBindingsWithRuntime:callInvoker:` is on iOS: a hook nobody can skip who
+// reaches the module at all, so JS resolves the module for its SIDE EFFECT and then reads the global.
+//
+// RN's own sample of this shape is
+// ReactCommon/react/nativemodule/samples/platform/android/{SampleTurboModule.kt,ReactCommon/SampleTurboModuleJSIBindings.cpp}
+// — a `jni::JavaClass` whose descriptor names the Kotlin module, `registerNatives` binding
+// `getBindingsInstaller`, and a `BindingsInstallerHolder::newObjectCxxArgs` lambda. This file is that,
+// with our installer inside the lambda.
+
+#include <ReactCommon/BindingsInstallerHolder.h>
+#include <ReactCommon/CallInvoker.h>
+#include <fbjni/fbjni.h>
+#include <jsi/jsi.h>
+
+#include "SymbioteEngineBindings.h"
+
+namespace symbiote {
+
+using namespace facebook;
+
+namespace {
+
+/**
+ * The C++ side of `dev.symbiotenative.engine.SymbioteEngineModule`.
+ *
+ * Both of the Kotlin class's `external` members are bound here. `getVersion` is native rather than a
+ * Kotlin constant on purpose: `kNativeVersion` is the ABI gate `native-engine.ts` reads, and a second
+ * spelling of it in Kotlin is the kind of pair that drifts without anything going red.
+ */
+class SymbioteEngineJni : public jni::JavaClass<SymbioteEngineJni> {
+ public:
+  static constexpr const char *kJavaDescriptor = "Ldev/symbiotenative/engine/SymbioteEngineModule;";
+
+  static void registerNatives() {
+    javaClassLocal()->registerNatives({
+        makeNativeMethod("getBindingsInstaller", SymbioteEngineJni::getBindingsInstaller),
+        makeNativeMethod("getVersion", SymbioteEngineJni::getVersion),
+    });
+  }
+
+ private:
+  static jni::local_ref<react::BindingsInstallerHolder::javaobject> getBindingsInstaller(
+      jni::alias_ref<SymbioteEngineJni> /*self*/) {
+    return react::BindingsInstallerHolder::newObjectCxxArgs(
+        [](jsi::Runtime &runtime, const std::shared_ptr<react::CallInvoker> & /*callInvoker*/) {
+          installBindings(runtime);
+        });
+  }
+
+  static jdouble getVersion(jni::alias_ref<SymbioteEngineJni> /*self*/) {
+    return static_cast<jdouble>(kNativeVersion);
+  }
+};
+
+} // namespace
+
+} // namespace symbiote
+
+// `System.loadLibrary("symbiote_engine")` from the module's own initializer is what gets here, so the
+// natives are bound before anything can call them.
+extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void * /*reserved*/) {
+  return facebook::jni::initialize(vm, [] { symbiote::SymbioteEngineJni::registerNatives(); });
+}

package/android/src/main/java/dev/symbiotenative/engine/SymbioteEngineModule.kt

@@ -0,0 +1,43 @@
+package dev.symbiotenative.engine
+
+import com.facebook.proguard.annotations.DoNotStrip
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.turbomodule.core.interfaces.BindingsInstallerHolder
+import com.facebook.react.turbomodule.core.interfaces.TurboModuleWithJSIBindings
+
+// Android's registration shim, and the twin of `core/engine/ios/SymbioteEngineModule.mm`. It carries
+// no behaviour: creating it is what installs `global.__symbioteEngineNative`, and the payload lives
+// in `core/engine/cpp/`, compiled unchanged by `../CMakeLists.txt`.
+//
+// `TurboModuleWithJSIBindings` is the Android analogue of iOS's `RCTTurboModuleWithJSIBindings` —
+// `TurboModuleManager::getTurboModule` calls `getBindingsInstaller()` the moment it creates the Java
+// module and applies the returned installer to the runtime. So there is no `install()` for JS to
+// call, deliberately: an explicit install has an ordering requirement nothing enforces, while this
+// hook cannot be skipped by anyone who reaches the module at all.
+//
+// Both members below are `external` and bound in `src/main/cpp/SymbioteEngineJni.cpp`. `getVersion`
+// in particular: it is the ABI gate `native-engine.ts` reads, and its value is `kNativeVersion` in
+// the shared C++ — restating it as a Kotlin constant would be a second spelling that drifts silently.
+@DoNotStrip
+@ReactModule(name = SymbioteEngineModule.NAME)
+class SymbioteEngineModule(reactContext: ReactApplicationContext) :
+    NativeSymbioteEngineSpec(reactContext), TurboModuleWithJSIBindings {
+
+  // Not in a `companion object` initializer: the companion is only touched when something reads
+  // `NAME`, and `getBindingsInstaller` is called on the INSTANCE. Loading here runs before either
+  // native member can be reached, and a repeat `loadLibrary` of an already-loaded name is a no-op.
+  init {
+    System.loadLibrary("symbiote_engine")
+  }
+
+  @DoNotStrip external override fun getBindingsInstaller(): BindingsInstallerHolder
+
+  @DoNotStrip external override fun getVersion(): Double
+
+  companion object {
+    // Declared here rather than read off the generated spec's own `NAME`, so this file and the
+    // package beside it do not depend on a field of a class that exists only after codegen runs.
+    const val NAME: String = "SymbioteEngine"
+  }
+}

package/android/src/main/java/dev/symbiotenative/engine/SymbioteEnginePackage.kt

@@ -0,0 +1,35 @@
+package dev.symbiotenative.engine
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+// The one ReactPackage for `@symbiote-native/engine`'s native half. Autolinking registers it (see
+// `../../../../../../react-native.config.cjs`), so no app touches its `MainApplication`.
+//
+// `BaseReactPackage` rather than the plain `ReactPackage` that `packages/android` uses, and
+// `isTurboModule = true` rather than the legacy-interop default: those two together are what put the
+// module on `TurboModuleManager::getTurboModule`, which is the ONLY path that consults
+// `TurboModuleWithJSIBindings`. On the legacy path the module would be created, work, and install
+// nothing — with no error anywhere.
+class SymbioteEnginePackage : BaseReactPackage() {
+
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+      if (name == SymbioteEngineModule.NAME) SymbioteEngineModule(reactContext) else null
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider {
+    mapOf(
+        SymbioteEngineModule.NAME to
+            ReactModuleInfo(
+                SymbioteEngineModule.NAME,
+                SymbioteEngineModule::class.java.name,
+                /* canOverrideExistingModule = */ false,
+                /* needsEagerInit = */ false,
+                /* isCxxModule = */ false,
+                /* isTurboModule = */ true,
+            )
+    )
+  }
+}

package/build/accessibility-info/shared.js

@@ -10,7 +10,7 @@
 // files, not derived from this file's name. Mirrors
 // RN's Libraries/Components/AccessibilityInfo/AccessibilityInfo.js.
 import { isSymbioteNode } from '../node.js';
-import { sendAccessibilityEvent as dispatchAccessibilityEvent } from '../commit.js';
+import { sendAccessibilityEvent as dispatchAccessibilityEvent } from '../imperative.js';
 import { dlog } from '../debug.js';
 export { isBoolean } from '../type-guards.js';
 // The routing behind IAccessibilityInfoStatic.sendAccessibilityEvent, shared by both

package/build/accessibility-props.d.ts

@@ -1,11 +1,4 @@
-export declare const ARIA_ALIAS_KEYS: readonly string[];
-/**
- * Whether one key is an alias this fold consumes. `startsWith` rather than a Set lookup: this runs
- * on `setProp`, the hottest write path in the engine (32 001 writes on one benchmark create), and
- * it is guarded by the node's sticky flag so it is reached at most once per node per key. The
- * `role` comparison comes first because it is the one alias with no prefix.
- */
-export declare function isAriaAliasKey(key: string): boolean;
+export declare const ARIA_ALIAS_KEYS: readonly ["role", "aria-label", "aria-labelledby", "aria-live", "aria-hidden", "aria-busy", "aria-checked", "aria-disabled", "aria-expanded", "aria-selected", "aria-modal", "aria-valuemax", "aria-valuemin", "aria-valuenow", "aria-valuetext"];
 /**
  * Fold the web-alias `aria-*` / `role` props into RN's canonical `accessibility*` props.
  *

package/build/accessibility-props.js

@@ -1,12 +1,9 @@
 // RN's `aria-*` / `role` -> `accessibility*` fold, at the layer every path goes through.
 //
-// WHY IT IS HERE AND NOT IN A WRAPPER. It used to run inside each primitive's COMPONENT, which is
-// exactly the layer host-primitive lowering removes. A per-attribute element path cannot do it —
-// `aria-checked` has to be folded against a sibling `accessibilityState` — so the four lowering
-// transforms REFUSED any element carrying `role` or an `aria-*` attribute
-// (`REFUSAL_CATEGORIES.bagFold`). Accessibility props are ordinary in real code, so that refusal
-// cost lowering coverage on every primitive, including the three already lowered. Moving the fold
-// down deletes the refusal instead of teaching four transforms a bag operation they cannot express.
+// WHY IT IS HERE AND NOT IN A WRAPPER. It used to run inside each primitive's COMPONENT, and a tag
+// has none. It also cannot run per attribute — `aria-checked` has to be folded against a sibling
+// `accessibilityState` — so it belongs at the one point where the whole bag is known, which is the
+// payload build.
 //
 // IT IS A MOVE, NOT A REWRITE, AND THAT IS DELIBERATE. The function carries TWO CONTRADICTORY
 // PRECEDENCE RULES: for the scalars an explicit `accessibility*` WINS and the alias only fills a
@@ -59,6 +56,10 @@ const ROLE_TO_ACCESSIBILITY_ROLE = {
 // list. `slotDerived` (host-behavior.ts) takes prop NAMES, so a primitive whose payload derives
 // from an owner's aria props has to enumerate them — and a second hand-written copy is exactly what
 // `.claude/rules/adapter-parity-audit.md` records going stale one member at a time.
+// `as const` rather than `readonly string[]`, so the members are LITERALS. That is what lets a
+// consumer index a prop type with them — `pickAccessibilityProps` in the Svelte adapter forwards the
+// aria half by looping this list — and it makes the two sides check each other: a name here that is
+// not a key of `IAriaProps` stops compiling at the use site rather than going quietly unforwarded.
 export const ARIA_ALIAS_KEYS = [
     'role',
     'aria-label',
@@ -85,15 +86,11 @@ function hasAnyAriaKey(props) {
     }
     return false;
 }
-/**
- * Whether one key is an alias this fold consumes. `startsWith` rather than a Set lookup: this runs
- * on `setProp`, the hottest write path in the engine (32 001 writes on one benchmark create), and
- * it is guarded by the node's sticky flag so it is reached at most once per node per key. The
- * `role` comparison comes first because it is the one alias with no prefix.
- */
-export function isAriaAliasKey(key) {
-    return key === 'role' || key.startsWith('aria-');
-}
+// `isAriaAliasKey` WAS HERE AND IS GONE (2026-09-18). Its whole reason was to maintain
+// `node.hasAriaAlias` from `setProp` — the hottest write path in the engine, 32 001 writes on one
+// benchmark create — and that flag existed only to gate the aria fold inside the headless payload
+// builder. The fold left for `SymbioteFabricProps.cpp`, which recomputes presence from the bag it
+// holds, so the flag became write-only and this function became its only maintainer. Both went.
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }

package/build/animated/animations/composition.d.ts

@@ -26,7 +26,7 @@ export declare function decay(value: AnimatedValue, config: IDecayConfig): IComp
 export interface IParallelConfig {
     stopTogether?: boolean;
 }
-export declare function parallel(animations: ICompositeAnimation[], config?: IParallelConfig): ICompositeAnimation;
+export declare function parallel(animations: (ICompositeAnimation | undefined)[], config?: IParallelConfig): ICompositeAnimation;
 export declare function sequence(animations: ICompositeAnimation[]): ICompositeAnimation;
 export declare function delay(time: number): ICompositeAnimation;
 export declare function stagger(time: number, animations: ICompositeAnimation[]): ICompositeAnimation;

package/build/animated/animations/composition.js

@@ -99,7 +99,10 @@ export function decay(value, config) {
         },
     };
 }
-export function parallel(animations, config) {
+export function parallel(
+// `| undefined` entries: `AnimatedImplementation.js`'s `parallelImpl` treats a falsy array
+// entry (e.g. `cond && timing(...)`) as already-finished rather than crashing.
+animations, config) {
     let doneCount = 0;
     // Track per-animation completion so stop() calls each at most once.
     const hasEnded = {};
@@ -123,19 +126,24 @@ export function parallel(animations, config) {
                         result.stop();
                     }
                 };
-                animation.start(cb, isLooping);
+                if (animation === undefined) {
+                    cb({ finished: true });
+                }
+                else {
+                    animation.start(cb, isLooping);
+                }
             });
         },
         stop() {
             animations.forEach((animation, idx) => {
                 if (!hasEnded[idx])
-                    animation.stop();
+                    animation?.stop();
                 hasEnded[idx] = true;
             });
         },
         reset() {
             animations.forEach((animation, idx) => {
-                animation.reset();
+                animation?.reset();
                 hasEnded[idx] = false;
                 doneCount = 0;
             });
@@ -192,6 +200,12 @@ export function delay(time) {
 export function stagger(time, animations) {
     return parallel(animations.map((animation, i) => sequence([delay(time * i), animation])));
 }
+// TODO(rn-parity, low priority): vendor's `loopImpl`/`sequenceImpl`/`parallelImpl` each throw
+// ("Loops run using the native driver cannot contain Animated.X animations") from a
+// `_startNativeLoop` reachable only by nesting `loop(loop(...))` around a native-driven leaf. Ours
+// has no such throw: the nesting silently falls back to the JS restart loop instead of erroring.
+// Judged non-actionable (misuse-detection guard, no runtime-visible effect for a correct caller,
+// same class as the `numColumns` invariant) — see the audit skill for the full reasoning.
 export function loop(animation, config = {}) {
     const iterations = config.iterations ?? -1;
     const resetBeforeIteration = config.resetBeforeIteration ?? true;

package/build/animated/easing.d.ts

@@ -1,5 +1,5 @@
 export type IEasingFunction = (t: number) => number;
-export declare const Easing: {
+export interface IEasing {
     step0(n: number): number;
     step1(n: number): number;
     linear(t: number): number;
@@ -17,4 +17,5 @@ export declare const Easing: {
     in(easing: IEasingFunction): IEasingFunction;
     out(easing: IEasingFunction): IEasingFunction;
     inOut(easing: IEasingFunction): IEasingFunction;
-};
+}
+export declare const Easing: IEasing;

package/build/animated/easing.js

@@ -1,88 +1,17 @@
-// Common easing functions, ported from React Native's Libraries/Animated/Easing.js.
-// Pure math (the only dependency is the equally-pure bezier solver), so it lives
-// unchanged in shared and every adapter re-exports it.
-import { bezier } from './bezier.js';
-let cachedEase;
-export const Easing = {
-    step0(n) {
-        return n > 0 ? 1 : 0;
-    },
-    step1(n) {
-        return n >= 1 ? 1 : 0;
-    },
-    linear(t) {
-        return t;
-    },
-    // A simple inertial interaction (object slowly accelerating to speed).
-    ease(t) {
-        if (cachedEase === undefined) {
-            cachedEase = bezier(0.42, 0, 1, 1);
-        }
-        return cachedEase(t);
-    },
-    quad(t) {
-        return t * t;
-    },
-    cubic(t) {
-        return t * t * t;
-    },
-    // Nth-power: position is the Nth power of elapsed time.
-    poly(n) {
-        return t => Math.pow(t, n);
-    },
-    sin(t) {
-        return 1 - Math.cos((t * Math.PI) / 2);
-    },
-    circle(t) {
-        return 1 - Math.sqrt(1 - t * t);
-    },
-    exp(t) {
-        return Math.pow(2, 10 * (t - 1));
-    },
-    // Elastic: spring-like oscillation. bounciness 1 overshoots once; 0 not at all.
-    elastic(bounciness = 1) {
-        const p = bounciness * Math.PI;
-        return t => 1 - Math.pow(Math.cos((t * Math.PI) / 2), 3) * Math.cos(t * p);
-    },
-    // Animates back slightly before moving forward.
-    back(s = 1.70158) {
-        return t => t * t * ((s + 1) * t - s);
-    },
-    // A simple bouncing effect.
-    bounce(t) {
-        if (t < 1 / 2.75) {
-            return 7.5625 * t * t;
-        }
-        if (t < 2 / 2.75) {
-            const t2 = t - 1.5 / 2.75;
-            return 7.5625 * t2 * t2 + 0.75;
-        }
-        if (t < 2.5 / 2.75) {
-            const t2 = t - 2.25 / 2.75;
-            return 7.5625 * t2 * t2 + 0.9375;
-        }
-        const t2 = t - 2.625 / 2.75;
-        return 7.5625 * t2 * t2 + 0.984375;
-    },
-    // A cubic bezier curve, same as CSS transition-timing-function.
-    bezier(x1, y1, x2, y2) {
-        return bezier(x1, y1, x2, y2);
-    },
-    // Runs an easing function forwards.
-    in(easing) {
-        return easing;
-    },
-    // Runs an easing function backwards.
-    out(easing) {
-        return t => 1 - easing(1 - t);
-    },
-    // Makes any easing function symmetrical (forwards then backwards).
-    inOut(easing) {
-        return t => {
-            if (t < 0.5) {
-                return easing(t * 2) / 2;
-            }
-            return 1 - easing((1 - t) * 2) / 2;
-        };
-    },
-};
+// RN's own Easing, imported rather than ported.
+//
+// The port this replaces was 109 lines beside a 142-line `bezier.ts`, and it reproduced upstream
+// formula for formula. Swept at 20 001 points per function before the swap: 15 of the 17 agree to
+// the bit, and the two bezier-backed ones (`ease`, `bezier`) differ by 2.9e-10, because upstream
+// samples its spline into a Float32Array where the port used a plain (float64) array. That is
+// below a sub-pixel on any animation this drives.
+//
+// The TYPE is ours and stays ours. `Easing` is on the engine barrel and re-exported by all five
+// adapters, and the upstream module ships no types - so importing it untyped would hand every
+// consumer `any`. Twenty lines of interface in exchange for 251 lines of implementation.
+import EasingUpstream from 'react-native/Libraries/Animated/Easing';
+// tsc resolves this deep path but reads the Flow source through allowJs, so the default export
+// arrives shapeless rather than untyped - the mismatch is the only thing the suppression covers,
+// and IEasing above is what every consumer actually sees.
+// @ts-expect-error - upstream ships no usable types for this path.
+export const Easing = EasingUpstream;