@pixodesk/svg-animator-rn 1.0.34 → 1.0.39

package/src/PixodeskSvgAnimator.tsx

@@ -3,19 +3,8 @@
  * Licensed under the MIT License. See the LICENSE file in the project root for details.
  *---------------------------------------------------------------------------------------*/
 
-import {
-    generateNewIds,
-    getAnimatorConfig,
-    getDefs,
-    materialiseAllInTree,
-    validateNodeEffects,
-    PxAnimatorEngine,
-    type FillMode,
-    type OutAction,
-    type PlaybackDirection,
-    type PxAnimatedSvgDocument,
-    type PxNode,
-} from '@pixodesk/svg-animator-core';
+import { clampSeekMs, createDiagnostics, createRunClock, isValidPlaybackRate, progressSpanMs, progressToTimeMs, PX_RATE_REJECTED, PxDiagnosticKind, seekCeilingMs, timeToProgress, type PxAnimatorHandle, type PxComponentCallbacks, type PxControlProps, type PxPlaybackOverrideProps, type PxDiagnostic, type PxDiagnostics,
+    reportDocumentDiagnostics, generateNewIds, getAnimatorConfig, getDefs, materializeAllInTree, resolveTrigger, validateNodeEffects, PxTimelineEngine, PxControlMode, resolveControlMode, type PxFillMode, type PxOutAction, type PxPlaybackDirection, type PxAnimatedSvgDocument, type PxTimelinePatch, type PxNode, applyAnimatorConfig, foldTimelineOverride } from '@pixodesk/svg-animator-core';
 import React, { createElement, useEffect, useImperativeHandle, useMemo, useRef, useState, type ComponentType, type ReactElement, type ReactNode } from 'react';
 import { Dimensions, Platform, Pressable, View } from 'react-native';
 import Animated, {
@@ -38,99 +27,45 @@ import { openClosedTextPathTargets } from './PxRnSafety';
 
 // -- Public types -----------------------------------------------------------
 
-/** Imperative playback API — mirrors ReactAnimatorApi from svg-animator-react. */
-export interface RnAnimatorApi {
-    /** Returns true if the animation is currently running. */
-    isPlaying(): boolean;
-
-    /** Starts or resumes the animation. */
-    play(): void;
-
-    /** Pauses the animation at its current state. */
-    pause(): void;
-
-    /** Stops the animation and resets it to its initial state. */
-    cancel(): void;
-
-    /** Jumps to the end of the animation and holds the final state. */
-    finish(): void;
-
-    /** Changes the speed of the animation. 1 is normal, 2 is double. */
-    setPlaybackRate(rate: number): void;
-
-    /** Returns the current playback time in milliseconds. */
-    getCurrentTime(): number | null;
-
-    /** Jumps to a specific time (in milliseconds) in the animation. */
-    setCurrentTime(time: number): void;
-}
+/**
+ * The imperative handle `apiRef` is filled with — core's `PxAnimatorHandle` under this package's
+ * name (review §9). It no longer "mirrors" the React one by hand: the local copy had already
+ * drifted (its `setPlaybackRate` comment lost "negative plays backwards"). One definition.
+ */
+export type RnAnimatorApi = PxAnimatorHandle;
 
-export interface PixodeskSvgAnimatorProps {
+/**
+ * The component's props. The playback override, the control props and the callbacks are core's
+ * shared shapes (review §9) — `PxPlaybackOverrideProps`, `PxControlProps` and
+ * `PxComponentCallbacks` — so React, Vue and React Native cannot drift apart. Only what differs
+ * on this platform is declared here: `onError` keeps its richer signature (the error boundary
+ * hands it a component stack), and `fallback` has no web counterpart.
+ */
+export interface PixodeskSvgAnimatorProps
+    extends PxPlaybackOverrideProps, PxControlProps, Omit<PxComponentCallbacks, 'onError'> {
 
     // -- Source ---------------------------------------------------------------
 
     /** The animation document to render. */
     doc: PxAnimatedSvgDocument;
 
-    // -- Timing overrides -----------------------------------------------------
-
-    /** Duration of a single iteration in milliseconds. */
-    duration?: number;
-
-    /** Delay before the animation starts, in milliseconds. */
-    delay?: number;
-
-    /** Number of iterations, or 'infinite' for endless looping. */
-    iterations?: number | 'infinite';
-
-    /** Defines the element's state when the animation is not active. */
-    fill?: FillMode;
-
-    /** Playback direction. */
-    direction?: PlaybackDirection;
-
-    /** Snap back to the start state after a natural finish. */
-    resetOnFinish?: boolean;
-
     /**
-     * What a second tap does when `startOn: 'click'` is active.
-     * Defaults to the document's `trigger.outAction`, else `'pause'`.
+     * Per-instance override of the document's `timeline` — see `PxPlaybackOverrideProps`.
+     *
+     * `engine` is accepted but ignored here: React Native always uses the `native` (fully
+     * flattened) materialization, because react-native-svg has no `<use>` shadow-tree
+     * propagation.
      */
-    outAction?: OutAction;
-
-    // -- Declarative control --------------------------------------------------
-
-    /** When true, honours the document trigger (`startOn: 'load'` plays on mount). */
-    autoplay?: boolean;
-
-    /** Starts playback unconditionally. */
-    play?: boolean;
-
-    /** Pauses current playback. */
-    pause?: boolean;
+    timeline?: PxTimelinePatch | string;
 
     // -- Imperative control ---------------------------------------------------
 
-    /** Ref populated with the imperative playback API. */
+    /**
+     * Ref populated with the imperative playback API. Filled in EVERY mode and never picks one
+     * (review §1): `autoplay` next to it still autoplays.
+     */
     apiRef?: React.RefObject<RnAnimatorApi | null>;
 
-    // -- Controlled (external) time -------------------------------------------
-
-    /** Seek to a fraction (0–1) of the whole timeline (duration × iterations). */
-    progress?: number;
-
-    /** Seek to a specific time in milliseconds. */
-    time?: number;
-
-    // -- Callbacks ------------------------------------------------------------
-
-    onPlay?: () => void;
-    onStop?: () => void;
-    onPause?: () => void;
-    onCancel?: () => void;
-    onFinish?: () => void;
-
-
     // -- Failure handling -----------------------------------------------------
 
     /**
@@ -139,7 +74,9 @@ export interface PixodeskSvgAnimatorProps {
      * animation never takes down the screen around it.
      *
      * Only JavaScript failures reach this — a crash inside react-native-svg's
-     * native renderer bypasses JavaScript entirely.
+     * native renderer bypasses JavaScript entirely. Richer than the web's
+     * `onError(diagnostic)` because the error boundary hands it a component stack; it is
+     * adapted into the shared diagnostics channel rather than narrowed to match it.
      */
     onError?: (error: Error, componentStack?: string) => void;
 
@@ -284,17 +221,11 @@ function SampledSubtree({
 
 
 /** Overrides that shadow the document's own `animator` config. */
-interface ConfigOverrides {
-    duration?: number;
-    delay?: number;
-    iterations?: number | 'infinite';
-    fill?: FillMode;
-    direction?: PlaybackDirection;
-    resetOnFinish?: boolean;
-}
+/** The override subset of the props — core's shared shape, not a local copy (review §9). */
+type ConfigOverrides = PxPlaybackOverrideProps;
 
 interface Compiled {
-    /** Materialised document, or null when compilation failed. */
+    /** Materialized document, or null when compilation failed. */
     doc: PxAnimatedSvgDocument | null;
     tracks: PxCompiledTracks;
     error: Error | null;
@@ -308,22 +239,34 @@ const EMPTY_TRACKS: PxCompiledTracks = {
 };
 
 /**
- * Materialises + compiles a document. Extracted from the component so the
+ * Materializes + compiles a document. Extracted from the component so the
  * whole thing sits behind one try/catch, and so it can be tested directly.
  */
-function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides): Compiled {
-    const { duration, delay, iterations, fill, direction, resetOnFinish } = overrides;
+function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides, diag: PxDiagnostics): Compiled {
+    const { timeline, resetTimeline, duration, delay, iterations, startOn } = overrides;
     const warnings = validateNodeEffects(doc as PxNode);
-    for (const w of warnings) console.warn('[PixodeskSvgAnimator] effects shape warning:', w);
+    for (const w of warnings) diag.warn(PxDiagnosticKind.document, 'effects shape: ' + w);
+    // The whole-document boundary diagnostic — see the note in the web player's entry.
+    reportDocumentDiagnostics(doc, '[PixodeskSvgAnimator]');
+
+    // The per-instance override, applied to the WIRE document BEFORE anything reads the
+    // config — `materializeAllInTree` samples motion paths against `duration`, so a later
+    // patch would be read by none of the pipeline. Same call, same rules, on every surface.
+    const patch = foldTimelineOverride(timeline, { duration, delay, iterations, startOn });
+    if (patch !== undefined || resetTimeline) {
+        const applied = applyAnimatorConfig(doc, patch ?? {}, { resetDefaults: !!resetTimeline });
+        for (const w of applied.warnings) diag.warn(PxDiagnosticKind.usage, 'timeline override: ' + w);
+        doc = applied.doc;
+    }
 
-    // `waapi` = the FULLY-FLATTENED materialisation: effects + loops +
+    // `native` = the FULLY-FLATTENED materialization: effects + loops +
     // sampled motion paths + animated `<use>` inlined into real `<g>`
     // clones + orphaned defs pruned. That last part is why RN must not use
-    // the `frames` flavour: frames keeps `<use href="#animatedTarget">`
+    // the `js` flavor: the frame loop keeps `<use href="#animatedTarget">`
     // live references, which only work because the DOM propagates
     // attribute writes through `<use>` shadow trees. react-native-svg has
     // no such live propagation, so an animated `<use>` would render frozen.
-    let prepared = materialiseAllInTree(doc, PxAnimatorEngine.waapi);
+    let prepared = materializeAllInTree(doc, PxTimelineEngine.native);
 
     // Sidestep a react-native-svg NATIVE crash (see PxRnSafety). Guarded on
     // the platform because the DOM renders this case correctly and the web
@@ -332,21 +275,6 @@ function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides)
         prepared = openClosedTextPathTargets(prepared as PxNode) as PxAnimatedSvgDocument;
     }
 
-    // Apply prop overrides onto the animator config (mirrors the react wrapper).
-    const animator = getAnimatorConfig(prepared) || {};
-    prepared = {
-        ...prepared,
-        animator: {
-            ...animator,
-            duration: duration !== undefined ? duration : animator.duration,
-            delay: delay !== undefined ? delay : animator.delay,
-            iterations: iterations !== undefined ? iterations : animator.iterations,
-            fill: fill !== undefined ? fill : animator.fill,
-            direction: direction !== undefined ? direction : animator.direction,
-            resetOnFinish: resetOnFinish !== undefined ? resetOnFinish : animator.resetOnFinish,
-        },
-    };
-
     prepared = generateNewIds(prepared);
     const tracks = compileTracks(prepared, { native: NATIVE_SVG_VIEWS });
     return { doc: prepared, tracks, error: null };
@@ -358,38 +286,71 @@ function compileDocument(doc: PxAnimatedSvgDocument, overrides: ConfigOverrides)
 /**
  * React Native component for rendering and controlling Pixodesk SVG animations.
  *
- * The document is materialised once through the shared core pipeline (effects,
+ * The document is materialized once through the shared core pipeline (effects,
  * loops, motion-path sampling, animated-`<use>` inlining — identical to the
- * web frames engine), compiled into densely sampled per-element tracks, and
+ * web's `native` engine, NOT the frame loop, which keeps `<use>` live), compiled
+ * into densely sampled per-element tracks, and
  * played back natively: a single reanimated progress value driven by
  * `withTiming`/`withRepeat` on the UI thread, with per-element worklets
  * indexing the precompiled tracks. No JS-thread frame loop.
  */
 export function PixodeskSvgAnimator({
-    doc, duration, delay, iterations, fill, direction, resetOnFinish, outAction: outActionProp,
+    doc, timeline, resetTimeline, duration, delay, iterations, startOn,
     // (`progress` prop aliased — the name is taken by the internal reanimated SharedValue)
     autoplay, play, pause, apiRef, progress: progressProp, time,
-    onPlay, onStop, onPause, onCancel, onFinish, onError, fallback,
+    onPlay, onStop, onPause, onCancel, onFinish, onRemove, onError, fallback, onWarn, silent,
 }: PixodeskSvgAnimatorProps): ReactElement | null {
 
     // -- Compile the document (once per doc/override change) ------------------
 
+    // `timeline` is an object prop: a fresh literal every render would otherwise recompile the
+    // whole document (materialize + compile tracks), which is the expensive path. Key on its
+    // CONTENT instead — the override is small, the document is not.
+    const timelineKey = typeof timeline === 'string' ? timeline : JSON.stringify(timeline ?? null);
+
+
+    /**
+     * The diagnostics channel, built from the CURRENT props each time (API review §5).
+     * Deliberately not hoisted into a wrapper closure: `(m, d) => onWarn?.(m, d)` would always
+     * be a function, so the channel would believe a handler exists and the console fallback
+     * would never fire for anyone who passed nothing.
+     */
+    const makeDiag = (): PxDiagnostics => createDiagnostics({
+        onWarn,
+        // This component's public `onError` is richer — `(error, componentStack?)` — and the
+        // error boundary hands it a component stack. Adapt rather than narrow it; the ternary
+        // keeps "not given" as undefined, so the console fallback still fires.
+        onError: onError ? (d: PxDiagnostic) => onError(d.error ?? new Error(d.message)) : undefined,
+        silent,
+    }, '[PixodeskSvgAnimator]');
+
     const compiled = useMemo((): Compiled => {
         try {
             return compileDocument(
                 doc,
-                { duration, delay, iterations, fill, direction, resetOnFinish }
+                { timeline, resetTimeline, duration, delay, iterations, startOn },
+                makeDiag(),
             );
         } catch (e) {
             // A malformed document must not take the host screen down with it.
             const error = e instanceof Error ? e : new Error(String(e));
-            console.warn('[PixodeskSvgAnimator] could not compile the document:', error.message);
+            makeDiag().warn(PxDiagnosticKind.internal, 'could not compile the document: ' + error.message);
             return { doc: null, tracks: EMPTY_TRACKS, error };
         }
-    }, [doc, duration, delay, iterations, fill, direction, resetOnFinish]);
+        // `timeline` is an object prop, so a fresh literal each render would recompile the whole
+        // document. Key on its CONTENT — the override is small, unlike the document.
+    }, [doc, timelineKey, resetTimeline, duration, delay, iterations, startOn]);
 
     const tracks: PxCompiledTracks = compiled.tracks;
-    const totalDuration = tracks.duration * (tracks.iterations === Infinity ? 1 : tracks.iterations);
+    // The span `progress` 0–1 covers (ONE iteration when endless) — NOT the seek ceiling.
+    const totalDuration = progressSpanMs(tracks.duration, tracks.iterations);
+    // How far a seek may go: unbounded when endless (review §3).
+    const seekCeiling = seekCeilingMs(tracks.duration, tracks.iterations);
+
+    // Whole-run time lives on its own clock: `progress` below is deliberately within ONE
+    // iteration, and `withRepeat` never reports how many have elapsed, so the run time cannot
+    // be read back off it. See `createRunClock`.
+    const runClock = useMemo(() => createRunClock(seekCeiling), [seekCeiling]);
 
     // -- Playback state -------------------------------------------------------
 
@@ -412,6 +373,8 @@ export function PixodeskSvgAnimator({
 
     const notifyFinish = () => {
         playingRef.current = false;
+        runClock.seek(Number.isFinite(seekCeiling) ? seekCeiling : tracks.duration);
+        runClock.stop();
         progress.value = restingPosition();
         onFinish?.();
         onStop?.();
@@ -462,13 +425,17 @@ export function PixodeskSvgAnimator({
         play: () => {
             // `startFrom` rewinds to the opposite end when the playhead is
             // already resting at a boundary (mirrors WAAPI, where play() on a
-            // finished animation auto-rewinds).
+            // finished animation auto-rewinds) — the run clock rewinds with it,
+            // or the time would keep counting on from the old end.
+            if (Number.isFinite(seekCeiling) && runClock.now() >= seekCeiling) runClock.seek(0);
+            runClock.start(rateRef.current);
             startFrom(progress.value);
             onPlay?.();
         },
         pause: () => {
             cancelAnimation(progress);
             playingRef.current = false;
+            runClock.stop();
             onPause?.();
             onStop?.();
         },
@@ -476,30 +443,45 @@ export function PixodeskSvgAnimator({
             cancelAnimation(progress);
             progress.value = 0;
             playingRef.current = false;
+            runClock.seek(0);
+            runClock.stop();
             onCancel?.();
             onStop?.();
         },
         finish: () => {
             cancelAnimation(progress);
             playingRef.current = false;
+            runClock.seek(Number.isFinite(seekCeiling) ? seekCeiling : tracks.duration);
+            runClock.stop();
             progress.value = restingPosition();
             onFinish?.();
             onStop?.();
         },
         setPlaybackRate: (rate: number) => {
-            if (!isFinite(rate) || rate === 0) {
-                console.warn('setPlaybackRate: rate must be finite and non-zero');
+            if (!isValidPlaybackRate(rate)) {
+                makeDiag().warn(PxDiagnosticKind.usage, PX_RATE_REJECTED);
                 return;
             }
             rateRef.current = rate;
-            if (playingRef.current) startFrom(progress.value);
+            if (playingRef.current) {
+                runClock.start(rate);   // resume from the current time at the new rate
+                startFrom(progress.value);
+            }
         },
-        getCurrentTime: () => progress.value,
+
+        // Ms from the start of the WHOLE run, like every other engine (review §3). This used
+        // to return `progress.value`, which is ms within the current iteration — so a slider
+        // built on it jumped back to 0 every time the animation repeated.
+        getCurrentTime: () => runClock.now(),
+
         setCurrentTime: (t: number) => {
             const wasPlaying = playingRef.current;
             cancelAnimation(progress);
             playingRef.current = false;
-            const clamped = Math.max(0, Math.min(t, totalDuration));
+            // Clamp against the SEEK ceiling, not the progress span — the old clamp capped an
+            // endless timeline at one iteration.
+            const clamped = clampSeekMs(t, seekCeiling);
+            runClock.seek(clamped);
             const withinIteration = tracks.duration > 0
                 ? (clamped % tracks.duration) || (clamped === 0 ? 0 : tracks.duration)
                 : 0;
@@ -507,6 +489,13 @@ export function PixodeskSvgAnimator({
             // Seeking mid-playback continues from the new position rather than
             // silently pausing.
             if (wasPlaying) startFrom(withinIteration);
+            else runClock.stop();
+        },
+
+        getCurrentProgress: () => timeToProgress(runClock.now(), tracks.duration, tracks.iterations),
+
+        setCurrentProgress: (p: number) => {
+            api.setCurrentTime(progressToTimeMs(p, tracks.duration, tracks.iterations));
         },
     };
 
@@ -514,29 +503,47 @@ export function PixodeskSvgAnimator({
 
     // -- Declarative control --------------------------------------------------
 
-    const trigger = compiled.doc ? getAnimatorConfig(compiled.doc)?.trigger : undefined;
-    const startOn = trigger?.startOn ?? 'load';
-    const outAction = outActionProp ?? trigger?.outAction ?? 'pause';
+    // The EFFECTIVE trigger, read back off the COMPILED document — so it already reflects the
+    // `timeline` override and the `startOn` shortcut, both merged in before compilation.
+    // Resolved through core's one table, so a document means the same here as on the web:
+    // no `startOn` = 'load', no `outAction` = 'continue'.
+    const trigger = resolveTrigger(compiled.doc ? getAnimatorConfig(compiled.doc)?.trigger : undefined);
+    const effectiveStartOn = trigger.startOn;
+    const effectiveOutAction = trigger.outAction;
+
+    // ONE control-mode rule, decided in core and shared with React and Vue (API review §1/§7).
+    // This component always had the right ORDER but no name for it, and never told anyone when
+    // two tiers of props were passed together.
+    const { mode: compMode, warnings: modeWarnings } =
+        resolveControlMode({ progress: progressProp, time, play, pause, autoplay });
 
     useEffect(() => {
-        if (progressProp !== undefined || time !== undefined) {
-            const seekMs = time !== undefined ? time : (progressProp ?? 0) * totalDuration;
+        const diag = makeDiag();
+        for (const w of modeWarnings) diag.warn(PxDiagnosticKind.usage, w);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [modeWarnings.join('|')]);
+
+    useEffect(() => {
+        if (compMode === PxControlMode.fixedTime) {
+            const seekMs = time !== undefined
+                ? time
+                : progressToTimeMs(progressProp ?? 0, tracks.duration, tracks.iterations);
             api.setCurrentTime(seekMs);
             return;
         }
-        if (play !== undefined || pause !== undefined) {
+        if (compMode === PxControlMode.play) {
             if (play && !pause) api.play();
             else if (pause) api.pause();
-            else if (play === false) api.finish();
+            else if (play === false) api.pause();   // hold, not finish() — review §8, same as web
             else api.play();
             return;
         }
         // 'click' and 'scrollIntoView' start from their own handlers below.
-        if (autoplay && startOn === 'load') {
+        if (compMode === PxControlMode.autoplay && effectiveStartOn === 'load') {
             api.play();
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [compiled, autoplay, play, pause, progressProp, time]);
+    }, [compiled, compMode, autoplay, play, pause, progressProp, time]);
 
     // `startOn: 'scrollIntoView'` — react-native has no IntersectionObserver, so
     // visibility is sampled by measuring the view against the window box. The
@@ -545,8 +552,8 @@ export function PixodeskSvgAnimator({
     const scrollRef = useRef<View | null>(null);
     const inViewRef = useRef(false);
     useEffect(() => {
-        if (!autoplay || startOn !== 'scrollIntoView') return;
-        const threshold = trigger?.scrollIntoViewThreshold ?? 0;
+        if (!autoplay || effectiveStartOn !== 'scrollIntoView') return;
+        const threshold = trigger.scrollIntoViewThreshold;
         inViewRef.current = false;
 
         const check = () => {
@@ -563,9 +570,9 @@ export function PixodeskSvgAnimator({
                 if (isIn) {
                     if (rateRef.current < 0) api.setPlaybackRate(Math.abs(rateRef.current));
                     api.play();
-                } else if (outAction === 'reset') api.cancel();
-                else if (outAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
-                else if (outAction !== 'continue') api.pause();
+                } else if (effectiveOutAction === 'reset') api.cancel();
+                else if (effectiveOutAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
+                else if (effectiveOutAction !== 'continue') api.pause();
             });
         };
 
@@ -573,13 +580,16 @@ export function PixodeskSvgAnimator({
         const id = setInterval(check, 200);
         return () => clearInterval(id);
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [compiled, autoplay, startOn, outAction]);
+    }, [compiled, autoplay, effectiveStartOn, effectiveOutAction]);
 
-    // Stop cleanly on unmount / doc swap.
+    // Stop cleanly on unmount / doc swap — and say so, the way the web's destroy() does (§18):
+    // both are "the animator was thrown away", so `onRemove` fires, and `onStop` with it.
     useEffect(() => {
         return () => {
             cancelAnimation(progress);
             playingRef.current = false;
+            onRemove?.();
+            onStop?.();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [compiled]);
@@ -647,14 +657,18 @@ export function PixodeskSvgAnimator({
             // rather than propagating and unmounting the host screen.
             const error = e instanceof Error ? e : new Error(String(e));
             renderErrorRef.current = error;
-            console.warn('[PixodeskSvgAnimator] could not render the document:', error.message);
+            makeDiag().warn(PxDiagnosticKind.internal, 'could not render the document: ' + error.message);
             return null;
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [compiled, trackById]);
 
     useEffect(() => {
-        for (const w of warningsRef.current) console.warn('[PixodeskSvgAnimator]', w);
+        const diag = makeDiag();
+        // `platform`: these come from the react-native-svg prop mapper — shapes this renderer
+        // cannot express, rather than anything wrong with the file.
+        for (const w of warningsRef.current) diag.warn(PxDiagnosticKind.platform, w);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [root]);
 
     // Surface compile/render failures to the host exactly once per occurrence.
@@ -672,17 +686,17 @@ export function PixodeskSvgAnimator({
     // so both are left to the host app.
     let content: ReactElement | null = root;
 
-    if (autoplay && startOn === 'scrollIntoView' && root) {
+    if (autoplay && effectiveStartOn === 'scrollIntoView' && root) {
         // `collapsable={false}` keeps the view in the native tree so it can be measured.
         content = <View ref={scrollRef} collapsable={false}>{root}</View>;
-    } else if (autoplay && startOn === 'click' && root) {
+    } else if (autoplay && effectiveStartOn === 'click' && root) {
         content = (
             <Pressable
                 onPress={() => {
                     if (playingRef.current) {
-                        if (outAction === 'reset') api.cancel();
-                        else if (outAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
-                        else if (outAction !== 'continue') api.pause();
+                        if (effectiveOutAction === 'reset') api.cancel();
+                        else if (effectiveOutAction === 'reverse') { api.setPlaybackRate(-Math.abs(rateRef.current || 1)); api.play(); }
+                        else if (effectiveOutAction !== 'continue') api.pause();
                     } else {
                         if (rateRef.current < 0) api.setPlaybackRate(Math.abs(rateRef.current));
                         api.play();
@@ -698,7 +712,7 @@ export function PixodeskSvgAnimator({
     // and commit of the tree — react-native-svg internals, reanimated failing
     // to attach to a component that turns out not to be a host view, and so on.
     return (
-        <PxRnErrorBoundary onError={onError} fallback={fallback}>
+        <PxRnErrorBoundary onError={onError} fallback={fallback} diag={makeDiag()}>
             {content}
         </PxRnErrorBoundary>
     );

package/src/PxRnErrorBoundary.tsx

@@ -4,12 +4,15 @@
  *---------------------------------------------------------------------------------------*/
 
 import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { createDiagnostics, PxDiagnosticKind, type PxDiagnostics } from '@pixodesk/svg-animator-core';
 
 export interface PxRnErrorBoundaryProps {
     children: ReactNode;
     /** Rendered instead of the children once something has thrown. */
     fallback?: (error: Error) => ReactNode;
     onError?: (error: Error, info?: string) => void;
+    /** Where to report the failure (API review §5). Defaults to the console. */
+    diag?: PxDiagnostics;
 }
 
 interface State {
@@ -38,7 +41,8 @@ export class PxRnErrorBoundary extends Component<PxRnErrorBoundaryProps, State>
 
     override componentDidCatch(error: Error, info: ErrorInfo): void {
         this.props.onError?.(error, info?.componentStack ?? undefined);
-        console.warn('[PixodeskSvgAnimator] render failed:', error?.message ?? error);
+        (this.props.diag ?? createDiagnostics(undefined, '[PixodeskSvgAnimator]'))
+            .warn(PxDiagnosticKind.internal, 'render failed: ' + (error?.message ?? String(error)));
     }
 
     override componentDidUpdate(prev: PxRnErrorBoundaryProps): void {

package/src/PxRnMatrix.test.ts

@@ -33,7 +33,7 @@ describe('svgTransformToMatrix', () => {
         expect(y).toBeCloseTo(1, 9);
     });
 
-    it('honours a rotation centre', () => {
+    it('honors a rotation center', () => {
         // rotate(180, 5, 0) maps (0,0) → (10,0)
         const m = svgTransformToMatrix('rotate(180,5,0)')!;
         expect(m[0] * 0 + m[2] * 0 + m[4]).toBeCloseTo(10, 9);
@@ -53,7 +53,7 @@ describe('toRnPropValue transform handling', () => {
 
     it('leaves the transform ALONE by default, for the DOM', () => {
         // react-native-web hands the value straight to the DOM, where an array
-        // serialises to `transform="1,0,0,1,3,4"` and the element stops moving.
+        // serializes to `transform="1,0,0,1,3,4"` and the element stops moving.
         expect(toRnPropValue('transform', 'translate(3,4)')).toBe('translate(3,4)');
     });
 

package/src/PxRnMatrix.ts

@@ -54,7 +54,7 @@ function numbers(raw: string): Array<number> {
 
 /**
  * Parses an SVG transform list. Returns `undefined` when the string contains no
- * recognisable function, so callers can leave the original value untouched
+ * recognizable function, so callers can leave the original value untouched
  * rather than silently replacing it with an identity matrix.
  */
 export function svgTransformToMatrix(value: string): Mat2D | undefined {

package/src/PxRnPropNames.ts

@@ -16,7 +16,7 @@ const ATTR_NAME_OVERRIDES: Record<string, string> = {
 const DROPPED_ATTRS = new Set(['class', 'className', 'style', 'xmlns', 'xmlns:xlink', 'data-px-meta']);
 
 /**
- * Converts one normalised wire attribute name (camelCase after core's
+ * Converts one normalized wire attribute name (camelCase after core's
  * `getNormalizedProps`, or kebab-case raw) to a react-native-svg prop name.
  * Returns undefined for props that must be dropped.
  *
@@ -57,7 +57,7 @@ export function toRnPropValue(
     // On a device `transform` must arrive as a matrix, not a string: the
     // string→matrix parse happens in JS during render, which reanimated's
     // animated-props path skips entirely. See PxRnMatrix for the full why.
-    // On the web the DOM parses the string itself and an array would serialise
+    // On the web the DOM parses the string itself and an array would serialize
     // to a meaningless `transform="1,0,0,1,3,4"`, so it must stay a string.
     if (native && rnPropName === 'transform' && typeof value === 'string' && tag !== 'svg') {
         const m = svgTransformToMatrix(value);