@symbiote-native/engine 0.1.0

package/build/action-sheet-ios/index.js

@@ -0,0 +1,74 @@
+// ActionSheetIOS: a JS->native imperative module, no Fabric view, no React. It
+// drives the `ActionSheetManager` native module: `showActionSheetWithOptions`
+// passes options straight through and the native `callback(buttonIndex)` reports
+// the tapped row. We mirror RN faithfully.
+//
+// The native contract is confirmed from RN's TurboModule spec at
+// .vendors/react-native/.../src/private/specs_DEPRECATED/modules/INativeActionSheetManager.js:
+//   showActionSheetWithOptions(options, callback: (buttonIndex: number) => void)
+//   showShareActionSheetWithOptions(options, failureCallback, successCallback)
+//   dismissActionSheet?()
+//
+// iOS only. Non-throwing, like StatusBar: a missing native module is a no-op,
+// never a crash (on a device the module may be absent).
+//
+// Color note: RN runs `tintColor` / `cancelButtonTintColor` / `titleTextColor`
+// through processColor before handing them to native. symbiote centralizes color
+// processing in @symbiote-native/engine, so we do NOT process colors here; options pass
+// through untouched. The canary needs no colors; revisit when wiring real colors.
+import { dlog } from '../debug';
+import { getNativeModule } from '../native-modules';
+const ACTION_SHEET_MANAGER = 'ActionSheetManager';
+// The static imperative API RN exposes, mirrored as a static-method object.
+export const ActionSheetIOS = {
+    showActionSheetWithOptions(options, callback) {
+        dlog('ActionSheetIOS.showActionSheetWithOptions');
+        const manager = getNativeModule(ACTION_SHEET_MANAGER);
+        if (manager === null) {
+            dlog(`ActionSheetIOS: "${ACTION_SHEET_MANAGER}" unresolved — no-op`);
+            return;
+        }
+        // Normalize the single-index legacy form to the array RN's native side expects
+        // (RN ActionSheetIOS.js ~95-101): a `destructiveButtonIndex: number` becomes
+        // `destructiveButtonIndices: [number]`; an existing array passes through. Without
+        // this the destructive row isn't highlighted on a real iOS host. Colors are still
+        // not processed here (see file header).
+        const { destructiveButtonIndex, ...remainingOptions } = options;
+        let destructiveButtonIndices = options.destructiveButtonIndices;
+        if (Array.isArray(destructiveButtonIndex)) {
+            destructiveButtonIndices = destructiveButtonIndex;
+        }
+        else if (typeof destructiveButtonIndex === 'number') {
+            destructiveButtonIndices = [destructiveButtonIndex];
+        }
+        const nativeOptions = { ...remainingOptions, destructiveButtonIndices };
+        manager.showActionSheetWithOptions(nativeOptions, buttonIndex => {
+            dlog(`ActionSheetIOS callback buttonIndex=${buttonIndex}`);
+            callback(buttonIndex);
+        });
+    },
+    showShareActionSheetWithOptions(options, failureCallback, successCallback) {
+        dlog('ActionSheetIOS.showShareActionSheetWithOptions');
+        const manager = getNativeModule(ACTION_SHEET_MANAGER);
+        if (manager === null) {
+            dlog(`ActionSheetIOS: "${ACTION_SHEET_MANAGER}" unresolved — no-op`);
+            return;
+        }
+        manager.showShareActionSheetWithOptions(options, error => {
+            dlog('ActionSheetIOS share failure callback');
+            failureCallback(error);
+        }, (completed, activityType) => {
+            dlog(`ActionSheetIOS share success completed=${completed}`);
+            successCallback(completed, activityType);
+        });
+    },
+    dismissActionSheet() {
+        dlog('ActionSheetIOS.dismissActionSheet');
+        const manager = getNativeModule(ACTION_SHEET_MANAGER);
+        if (manager === null) {
+            dlog(`ActionSheetIOS: "${ACTION_SHEET_MANAGER}" unresolved — no-op`);
+            return;
+        }
+        manager.dismissActionSheet?.();
+    },
+};

package/build/alert/index.android.d.ts

@@ -0,0 +1,5 @@
+import { type IAlertStatic } from './shared';
+export type { IAlertButton, IAlertButtonStyle, IAlertButtons, IAlertOptions, IAlertType, } from './shared';
+export declare const Alert: IAlertStatic & {
+    prompt: () => void;
+};

package/build/alert/index.android.js

@@ -0,0 +1,117 @@
+// Alert, Android build. The native module is `DialogManagerAndroid`
+// (RN's TurboModuleRegistry.get('DialogManagerAndroid')): `showAlert(config, onError,
+// onAction)` pops the native dialog, and `onAction(action, buttonKey)` reports the action
+// plus the tapped button's key constant. At most three buttons map onto positive/negative/
+// neutral, last-to-first as RN does. Everything platform-agnostic is the shared core.
+// Metro picks this file on an Android host.
+//
+// The native contract is confirmed from RN's TurboModule spec:
+//   .vendors/.../specs_DEPRECATED/modules/INativeDialogManagerAndroid.js
+//     getConstants(): { buttonClicked, dismissed, buttonPositive, buttonNegative,
+//                       buttonNeutral }
+//     showAlert(config, onError: (msg) => void, onAction: (action, buttonKey?) => void)
+//
+// device-verify-pending: the `DialogManagerAndroid` name and routing are confirmed from RN
+// source but not yet exercised on a real Android host; only a bridgeless resolution log
+// there can prove the name. See .docs/native-module-platform-routing.md.
+//
+// Non-throwing, like StatusBar: a missing native module is a no-op, never a crash.
+import { dlog } from '../debug';
+import { getNativeModule } from '../native-modules';
+import { DEFAULT_POSITIVE_TEXT, normalizeButtons, } from './shared';
+const DIALOG_MANAGER = 'DialogManagerAndroid';
+// RN's hardwired Android fallbacks for the button-key constants (NativeDialogManager-
+// Android documents buttonPositive=-1, buttonNegative=-2, buttonNeutral=-3, and the
+// 'buttonClicked'/'dismissed' actions). Used when getConstants() omits a key.
+const ANDROID_DIALOG_CONSTANTS = {
+    buttonClicked: 'buttonClicked',
+    dismissed: 'dismissed',
+    buttonPositive: -1,
+    buttonNegative: -2,
+    buttonNeutral: -3,
+};
+// The trust boundary for getConstants(): native sends an untyped HostObject. Read each key
+// with a typeof guard and fall back to RN's documented default when it's missing.
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function readDialogConstants(raw) {
+    if (!isRecord(raw)) {
+        dlog('Alert: DialogManagerAndroid.getConstants() returned a non-object — using defaults');
+        return ANDROID_DIALOG_CONSTANTS;
+    }
+    const action = (key) => typeof raw[key] === 'string' ? raw[key] : ANDROID_DIALOG_CONSTANTS[key];
+    const buttonKey = (key) => typeof raw[key] === 'number' ? raw[key] : ANDROID_DIALOG_CONSTANTS[key];
+    return {
+        buttonClicked: action('buttonClicked'),
+        dismissed: action('dismissed'),
+        buttonPositive: buttonKey('buttonPositive'),
+        buttonNegative: buttonKey('buttonNegative'),
+        buttonNeutral: buttonKey('buttonNeutral'),
+    };
+}
+// The static imperative API RN exposes, mirrored as a static-method object. `prompt` has
+// no Android counterpart in RN, so it is a dlog'd no-op here (documented below).
+export const Alert = {
+    // The Android dialog path. RN keeps at most three buttons and maps them, last-to-first,
+    // onto positive/negative/neutral; onAction reads the native button-key constant back and
+    // fires that button's onPress. Non-throwing: no module -> no-op.
+    alert(title, message, buttons, options) {
+        dlog('Alert.alert (android)');
+        const manager = getNativeModule(DIALOG_MANAGER);
+        if (manager === null) {
+            dlog(`Alert.alert: "${DIALOG_MANAGER}" unresolved — no-op`);
+            return;
+        }
+        const constants = readDialogConstants(manager.getConstants());
+        const config = {
+            title: title || '',
+            message: message || '',
+            cancelable: options?.cancelable ?? false,
+        };
+        // At most three buttons (neutral, negative, positive). Ignore the rest. RN pops
+        // last-to-first, so the LAST button becomes positive and the FIRST neutral.
+        const validButtons = normalizeButtons(buttons).slice(0, 3);
+        const buttonPositive = validButtons.pop();
+        const buttonNegative = validButtons.pop();
+        const buttonNeutral = validButtons.pop();
+        if (buttonNeutral) {
+            config.buttonNeutral = buttonNeutral.text || '';
+        }
+        if (buttonNegative) {
+            config.buttonNegative = buttonNegative.text || '';
+        }
+        if (buttonPositive) {
+            config.buttonPositive = buttonPositive.text || DEFAULT_POSITIVE_TEXT;
+        }
+        // onAction maps the returned button-key constant back to the matching button's onPress;
+        // the dismiss action fires options.onDismiss.
+        const onAction = (action, buttonKey) => {
+            dlog(`Alert onAction action=${action} buttonKey=${String(buttonKey)}`);
+            if (action === constants.buttonClicked) {
+                if (buttonKey === constants.buttonNeutral) {
+                    buttonNeutral?.onPress?.();
+                }
+                else if (buttonKey === constants.buttonNegative) {
+                    buttonNegative?.onPress?.();
+                }
+                else if (buttonKey === constants.buttonPositive) {
+                    buttonPositive?.onPress?.();
+                }
+            }
+            else if (action === constants.dismissed) {
+                options?.onDismiss?.();
+            }
+        };
+        const onError = (errorMessage) => {
+            dlog(`Alert onError: ${errorMessage}`);
+        };
+        manager.showAlert(config, onError, onAction);
+    },
+    // Android has no native `prompt` (RN's Alert.prompt is iOS-only; there is no
+    // DialogManagerAndroid equivalent). Keep the symbol so the surface matches, but no-op
+    // with a dlog rather than route to a single-input dialog.
+    prompt() {
+        dlog('Alert.prompt: no Android equivalent — no-op');
+    },
+};

package/build/alert/index.d.ts

@@ -0,0 +1 @@
+export * from './index.ios';

package/build/alert/index.ios.d.ts

@@ -0,0 +1,7 @@
+import type { IAlertButtons, IAlertOptions, IAlertStatic, IAlertType } from './shared';
+export type { IAlertButton, IAlertButtonStyle, IAlertButtons, IAlertOptions, IAlertType, } from './shared';
+type IPromptCallbackOrButtons = ((text: string) => void) | IAlertButtons;
+declare function prompt(title?: string, message?: string, callbackOrButtons?: IPromptCallbackOrButtons, type?: IAlertType, defaultValue?: string, keyboardType?: string, options?: IAlertOptions): void;
+export declare const Alert: IAlertStatic & {
+    prompt: typeof prompt;
+};

package/build/alert/index.ios.js

@@ -0,0 +1,83 @@
+// Alert: iOS build. The native module is `AlertManager`
+// (RN's TurboModuleRegistry.get('AlertManager')); `alertWithArgs(args, callback)` pops the
+// native alert, and the native `callback(id, value)` reports which button (by numeric id)
+// the user tapped plus any text-input value. `alert` delegates to `prompt`, the same
+// AlertManager path RN uses. Metro picks this file on an iOS host; the base alert.ts
+// re-exports it for web/headless.
+//
+// The native contract is confirmed from RN's TurboModule spec:
+//   .vendors/.../specs_DEPRECATED/modules/INativeAlertManager.js
+//     alertWithArgs(args: Args, callback: (id: number, value: string) => void)
+//
+// Non-throwing, like StatusBar: a missing native module is a no-op, never a crash (on a
+// device the module may be absent).
+import { dlog } from '../debug';
+import { getNativeModule } from '../native-modules';
+const ALERT_MANAGER = 'AlertManager';
+// prompt builds the native args, assigns each button its array index as id, and dispatches
+// the matching button's onPress when the native callback returns that id. Non-throwing: no
+// native module -> dlog + no-op.
+function prompt(title, message, callbackOrButtons, type = 'plain-text', defaultValue, keyboardType, options) {
+    dlog('Alert.prompt');
+    // callbacks[id] is the onPress for the button at that index: the id->onPress map the
+    // native callback indexes into. The native always supplies a real string value, so the
+    // element accepts `string`; a button's `onPress` (`value?: string`) is contravariantly
+    // assignable to it.
+    let callbacks = [];
+    const buttons = [];
+    let cancelButtonKey;
+    let destructiveButtonKey;
+    let preferredButtonKey;
+    if (typeof callbackOrButtons === 'function') {
+        callbacks = [callbackOrButtons];
+    }
+    else if (Array.isArray(callbackOrButtons)) {
+        callbackOrButtons.forEach((btn, index) => {
+            callbacks[index] = btn.onPress;
+            if (btn.style === 'cancel') {
+                cancelButtonKey = String(index);
+            }
+            else if (btn.style === 'destructive') {
+                destructiveButtonKey = String(index);
+            }
+            if (btn.isPreferred) {
+                preferredButtonKey = String(index);
+            }
+            if (btn.text !== undefined || index < callbackOrButtons.length - 1) {
+                buttons.push({ [index]: btn.text ?? '' });
+            }
+        });
+    }
+    const manager = getNativeModule(ALERT_MANAGER);
+    if (manager === null) {
+        dlog(`Alert.prompt: "${ALERT_MANAGER}" unresolved — no-op`);
+        return;
+    }
+    manager.alertWithArgs({
+        title: title ?? '',
+        message: message || undefined,
+        buttons,
+        type: type || undefined,
+        defaultValue,
+        cancelButtonKey,
+        destructiveButtonKey,
+        preferredButtonKey,
+        keyboardType,
+        userInterfaceStyle: options?.userInterfaceStyle || undefined,
+    }, 
+    // The native callback crossing back: `id` is the tapped button's index, `value` the
+    // text-input contents. Index into callbacks and fire onPress.
+    (id, value) => {
+        dlog(`Alert callback id=${id}`);
+        callbacks[id]?.(value);
+    });
+}
+// The static imperative API RN exposes, mirrored as a static-method object. `prompt` is
+// iOS-only, so it lives beyond IAlertStatic on this build.
+export const Alert = {
+    // alert delegates to prompt (same AlertManager path), exactly as RN does on iOS.
+    alert(title, message, buttons, options) {
+        prompt(title, message, buttons, 'default', undefined, undefined, options);
+    },
+    prompt,
+};

package/build/alert/index.js

@@ -0,0 +1,8 @@
+// Alert: base / default build (web, headless tsx, any target without a dedicated platform
+// file). Metro overrides this with alert.ios.ts / alert.android.ts on a real iOS/Android
+// host; off those, the iOS build is the fallback (its AlertManager resolves null elsewhere
+// → graceful no-op). The barrel imports './alert', which resolves here under tsc/tsx and to
+// the platform file under Metro. The `export *` re-exports the public type names
+// (AlertType, AlertButtonStyle, AlertButton, AlertButtons, AlertOptions) so the barrel's
+// `export type { ... } from '../alert'` still resolves. See ADR 0019.
+export * from './index.ios';

package/build/alert/shared.d.ts

@@ -0,0 +1,19 @@
+export type IAlertType = 'default' | 'plain-text' | 'secure-text' | 'login-password';
+export type IAlertButtonStyle = 'default' | 'cancel' | 'destructive';
+export interface IAlertButton {
+    text?: string;
+    onPress?: (value?: string) => void;
+    isPreferred?: boolean;
+    style?: IAlertButtonStyle;
+}
+export type IAlertButtons = IAlertButton[];
+export interface IAlertOptions {
+    cancelable?: boolean;
+    userInterfaceStyle?: 'unspecified' | 'light' | 'dark';
+    onDismiss?: () => void;
+}
+export interface IAlertStatic {
+    alert(title?: string, message?: string, buttons?: IAlertButtons, options?: IAlertOptions): void;
+}
+export declare const DEFAULT_POSITIVE_TEXT = "OK";
+export declare function normalizeButtons(buttons?: IAlertButtons): IAlertButtons;

package/build/alert/shared.js

@@ -0,0 +1,17 @@
+// Shared core of the Alert module, everything that does NOT differ by platform: the
+// public contract (the type union, button shapes, IAlertStatic), the Android button-key
+// constant defaults, and the button-normalization helper. The per-platform files
+// (alert.ios.ts / alert.android.ts) implement `alert()` fully against their own native
+// module (iOS keeps `prompt` too); the two native call shapes are too divergent to share
+// a factory. No native, no `Platform.OS` read here. See ADR 0019.
+// The default positive label RN uses when a button carries no text.
+export const DEFAULT_POSITIVE_TEXT = 'OK';
+// Normalize the `buttons` arg into a consistent list: undefined/empty becomes a single
+// default "OK" button, exactly as RN does before handing the list to native. Both
+// platform files start from this so the no-buttons case behaves identically.
+export function normalizeButtons(buttons) {
+    if (buttons === undefined || buttons.length === 0) {
+        return [{ text: DEFAULT_POSITIVE_TEXT }];
+    }
+    return buttons;
+}

package/build/animated/animated-component-shared.d.ts

@@ -0,0 +1,5 @@
+import { AnimatedNode } from './graph';
+export declare function isAnimatedNode(value: unknown): value is AnimatedNode;
+export declare function readPassthroughStyle(passthrough: unknown): unknown;
+export declare function reduceProps(props: Record<string, unknown>): Record<string, unknown>;
+export declare function resolveHostNode(instance: unknown): unknown;

package/build/animated/animated-component-shared.js

@@ -0,0 +1,54 @@
+// Framework-agnostic helpers for createAnimatedComponent. Both the React and Vue
+// adapters wrap a base component so it accepts AnimatedNodes in its props; the wrap
+// mechanism (capture the host node, build an AnimatedProps leaf, reduce animated
+// props to their current values, override with the passthrough style) is pure JS,
+// identical across frameworks. Only `assignRef` is framework-ref-specific and stays
+// per-adapter; everything here is shared. Extracted from the React wrapper (ADR
+// 0016/0017) so a new adapter reuses it verbatim.
+import { AnimatedNode } from './graph';
+import { AnimatedStyle } from './style';
+export function isAnimatedNode(value) {
+    return value instanceof AnimatedNode;
+}
+// RN's `passthroughAnimatedPropExplicitValues` carries explicit (already-rasterized) prop
+// values (e.g. a sticky header's debounced `{style:{transform:[{translateY}]}}`) that must
+// override the animated prop in the COMMITTED props so the Fabric ShadowTree (hit-testing)
+// stays current while the native driver animates. Read its `style` without a cast.
+export function readPassthroughStyle(passthrough) {
+    if (typeof passthrough !== 'object' || passthrough === null)
+        return undefined;
+    return Reflect.get(passthrough, 'style');
+}
+// Replace animated entries in a props map with their current rasterized values so the
+// first paint (and every re-render) carries concrete props. `style` is run through
+// AnimatedStyle so an animated style key resolves to its current number.
+export function reduceProps(props) {
+    const out = {};
+    for (const key of Object.keys(props)) {
+        const value = props[key];
+        if (key === 'style') {
+            const styleNode = AnimatedStyle.from(value);
+            out[key] = styleNode !== undefined ? styleNode.__getValue() : value;
+        }
+        else if (isAnimatedNode(value)) {
+            out[key] = value.__getValue();
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+// A ScrollView / FlatList / SectionList ref captures an imperative handle (RN's
+// getScrollableNode pattern), NOT the raw host node, so a native event or animated
+// props have nothing to bind to. Unwrap it via getScrollNode() to the underlying
+// SymbioteNode; View / Text / Image already hand back the node directly, so they fall
+// through unchanged.
+export function resolveHostNode(instance) {
+    if (instance !== null && typeof instance === 'object') {
+        const getScrollNode = Reflect.get(instance, 'getScrollNode');
+        if (typeof getScrollNode === 'function')
+            return getScrollNode.call(instance);
+    }
+    return instance;
+}

package/build/animated/animation.d.ts

@@ -0,0 +1,9 @@
+import type { AnimatedValue } from './value';
+export interface IEndResult {
+    finished: boolean;
+}
+export type IEndCallback = (result: IEndResult) => void;
+export interface IAnimation {
+    start(fromValue: number, onUpdate: (value: number) => void, onEnd: IEndCallback, previousAnimation: IAnimation | null, animatedValue: AnimatedValue): void;
+    stop(): void;
+}

package/build/animated/animation.js

@@ -0,0 +1,6 @@
+// The driver contract. A concrete animation (timing / spring / decay, all
+// Phase 2) is a number -> number machine: `start` is handed the value's current
+// number and an `onUpdate` it calls each frame with the next number; `onEnd`
+// fires exactly once. This interface is the seam between AnimatedValue and the
+// drivers, so it lives here, free of any concrete driver.
+export {};

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

@@ -0,0 +1,27 @@
+import type { IAnimation, IEndCallback, IEndResult } from '../animation';
+import type { AnimatedValue } from '../value';
+import { type INativeAnimationConfig, type IPlatformConfig } from '../native/native-animated';
+export interface IAnimationConfig {
+    isInteraction?: boolean;
+    iterations?: number;
+    useNativeDriver?: boolean;
+    platformConfig?: IPlatformConfig;
+    debugID?: string;
+}
+export declare abstract class BaseAnimation implements IAnimation {
+    protected __active: boolean;
+    protected __iterations: number;
+    protected readonly __platformConfig: IPlatformConfig | undefined;
+    private readonly __debugID;
+    private onEndCallback;
+    private readonly nativeDriverRequested;
+    private nativeId;
+    constructor(config: IAnimationConfig);
+    protected __getDebugID(): string | undefined;
+    abstract start(fromValue: number, onUpdate: (value: number) => void, onEnd: IEndCallback, previousAnimation: IAnimation | null, animatedValue: AnimatedValue): void;
+    protected begin(onEnd: IEndCallback): void;
+    protected getNativeAnimationConfig(): INativeAnimationConfig;
+    protected startNativeIfNeeded(animatedValue: AnimatedValue): boolean;
+    stop(): void;
+    protected __notifyAnimationEnd(result: IEndResult): void;
+}

package/build/animated/animations/base.js

@@ -0,0 +1,90 @@
+// Minimal driver base, ported from RN's animations/Animation.js with every
+// native path removed (ADR 0016): no NativeAnimatedHelper, no
+// __startAnimationIfNative, no shouldUseNativeDriver, no FeatureFlags. What
+// remains is the JS-only contract: hold the end callback, track whether the
+// animation is still active, and fire onEnd at most once.
+//
+// start() / stop() are abstract: each concrete driver (timing / spring / decay)
+// owns its own requestAnimationFrame loop. They are declared as methods (not
+// class fields) so a subclass override is not shadowed under
+// useDefineForClassFields.
+import { flushValue } from '../graph';
+import { dlog, isDebug } from '../../debug';
+import { generateNativeAnimationId, isNativeAnimatedAvailable, nativeAnimated, } from '../native/native-animated';
+export class BaseAnimation {
+    // `protected` so subclasses read it inside their rAF loop to decide whether to
+    // schedule the next frame; cleared by stop().
+    __active = false;
+    __iterations;
+    // RN's Animation holds `_platformConfig` / `__debugID` and folds them into the
+    // native config (Animation.js:60-62). Subclasses read them via the protected
+    // accessors below so every driver's config carries them uniformly.
+    __platformConfig;
+    __debugID;
+    onEndCallback = null;
+    nativeDriverRequested;
+    nativeId;
+    constructor(config) {
+        this.__iterations = config.iterations ?? 1;
+        this.nativeDriverRequested = config.useNativeDriver === true;
+        this.__platformConfig = config.platformConfig;
+        this.__debugID = config.debugID;
+    }
+    // Mirrors RN's Animation.__getDebugID (Animation.js:192). Returns the label only
+    // under DEBUG so production native configs stay lean, undefined otherwise.
+    __getDebugID() {
+        return isDebug() ? this.__debugID : undefined;
+    }
+    // Subclasses call super.start(...) shape via this helper to wire the end
+    // callback and arm the active flag before launching their loop.
+    begin(onEnd) {
+        this.onEndCallback = onEnd;
+        this.__active = true;
+    }
+    // A native driver overrides this with its curve config (`{type:'frames'|'spring'|'decay', …}`).
+    getNativeAnimationConfig() {
+        throw new Error('This animation type cannot be offloaded to the native driver');
+    }
+    // If useNativeDriver was requested and the module is present, mirror the value
+    // graph into native and hand the curve to native. The JS rAF loop is then
+    // skipped entirely. Returns true when native took over. Falls back to JS (false)
+    // when the module is missing (ADR 0016 path), so an app without RCTAnimation
+    // still animates.
+    startNativeIfNeeded(animatedValue) {
+        if (!this.nativeDriverRequested)
+            return false;
+        if (!isNativeAnimatedAvailable()) {
+            dlog('useNativeDriver requested but native animated module is missing; using JS driver');
+            return false;
+        }
+        const config = this.getNativeAnimationConfig();
+        // RN hands the curve's platform bag down to the value node (Animation.js:137)
+        // so the node's create config carries it too.
+        animatedValue.__makeNative(this.__platformConfig);
+        this.nativeId = generateNativeAnimationId();
+        nativeAnimated.startAnimatingNode(this.nativeId, animatedValue.__getNativeTag(), config, result => {
+            this.__notifyAnimationEnd({ finished: result.finished });
+            // Sync the JS value to native's final value, then run leaf callbacks once.
+            if (result.value !== undefined) {
+                animatedValue.__onNativeUpdate(result.value, result.offset);
+                flushValue(animatedValue);
+            }
+        });
+        return true;
+    }
+    stop() {
+        if (this.nativeId !== undefined) {
+            nativeAnimated.stopAnimation(this.nativeId);
+        }
+        this.__active = false;
+    }
+    // Fire the completion callback at most once. start() and stop() each run at
+    // most once over an animation's life, and so does this.
+    __notifyAnimationEnd(result) {
+        const callback = this.onEndCallback;
+        if (callback !== null) {
+            this.onEndCallback = null;
+            callback(result);
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { IEndCallback } from '../animation';
+import { AnimatedNode } from '../graph';
+import { AnimatedValue } from '../value';
+import { type ITimingAnimationConfig } from './timing';
+import { type ISpringAnimationConfig } from './spring';
+import { type IDecayAnimationConfig } from './decay';
+export interface ICompositeAnimation {
+    start(callback?: IEndCallback, isLooping?: boolean): void;
+    stop(): void;
+    reset(): void;
+    _nativeLoop?(iterations: number, callback?: IEndCallback): boolean;
+}
+interface IWithOnComplete {
+    onComplete?: IEndCallback;
+}
+export type ITimingConfig = Omit<ITimingAnimationConfig, 'toValue'> & {
+    toValue: number | AnimatedNode;
+} & IWithOnComplete;
+export type ISpringConfig = Omit<ISpringAnimationConfig, 'toValue'> & {
+    toValue: number | AnimatedNode;
+} & IWithOnComplete;
+export type IDecayConfig = IDecayAnimationConfig & IWithOnComplete;
+export declare function timing(value: AnimatedValue, config: ITimingConfig): ICompositeAnimation;
+export declare function spring(value: AnimatedValue, config: ISpringConfig): ICompositeAnimation;
+export declare function decay(value: AnimatedValue, config: IDecayConfig): ICompositeAnimation;
+export interface IParallelConfig {
+    stopTogether?: boolean;
+}
+export declare function parallel(animations: ICompositeAnimation[], 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;
+export interface ILoopAnimationConfig {
+    iterations?: number;
+    resetBeforeIteration?: boolean;
+}
+export declare function loop(animation: ICompositeAnimation, config?: ILoopAnimationConfig): ICompositeAnimation;
+export {};