@pixodesk/svg-animator-rn 1.0.35 → 1.0.40

package/src/PixodeskSvgAnimator.tsx

@@ -3,7 +3,8 @@
  * Licensed under the MIT License. See the LICENSE file in the project root for details.
  *---------------------------------------------------------------------------------------*/
 
-import { reportDocumentDiagnostics, generateNewIds, getAnimatorConfig, getDefs, materialiseAllInTree, validateNodeEffects, PxTimelineEngine, type FillMode, type OutAction, type PlaybackDirection, type PxAnimatedSvgDocument, type PxAnimatorConfigPatch, type PxNode, type StartOn, applyAnimatorConfig, foldAnimatorConfigShortcuts } from '@pixodesk/svg-animator-core';
+import { clampSeekMs, createRunClock, isValidPlaybackRate, progressSpanMs, progressToTimeMs, PX_RATE_REJECTED, PxDiagnosticKind, seekCeilingMs, timeToProgress, type PxAnimatorHandle, type PxAnimatorCallbacks, type PxControlProps, type PxPlaybackOverrideProps, type PxDiagnostics, 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 { createDiagnostics, reportDocumentDiagnostics } from '@pixodesk/svg-animator-core/internal';
 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, {
@@ -26,112 +27,53 @@ 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.
+ * @public
+ */
+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
+ * `PxAnimatorCallbacks` — so React, Vue and React Native cannot drift apart. Only what differs
+ * on this platform is declared here: `fallback`, which has no web counterpart.
+ * @public
+ */
+export interface PixodeskSvgAnimatorProps
+    extends PxPlaybackOverrideProps, PxControlProps, PxAnimatorCallbacks {
 
     // -- 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';
-
-    /** Shortcut for `config.timeline.trigger.startOn`. */
-    startOn?: StartOn;
-
     /**
-     * Per-instance override of the document's `animator` config — the same shape as `animator`
-     * in SCHEMA.md, deep-merged over what the document says; `null` at a slot deletes it.
-     * Replaces the former flat `fill` / `direction` / `resetOnFinish` / `outAction` props, so
-     * every surface takes one vocabulary. Also accepts a JSON string.
+     * Per-instance override of the document's `timeline` — see `PxPlaybackOverrideProps`.
      *
-     * `timeline.engine` is accepted but ignored here: React Native always materialises the
-     * WAAPI-style flattening, because react-native-svg has no `<use>` shadow-tree propagation.
+     * `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.
      */
-    config?: PxAnimatorConfigPatch | string;
-
-    /** Start from the player's defaults instead of the document's playback settings. */
-    resetDocDefaults?: boolean;
-
-    // -- 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 -----------------------------------------------------
-
-    /**
-     * Called when a document cannot be compiled or rendered. The component
-     * renders {@link fallback} instead of throwing, so a single broken
-     * 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.
-     */
-    onError?: (error: Error, componentStack?: string) => void;
+    // A document that cannot be compiled or rendered is reported through `onError` — the same
+    // `(diagnostic) => void` as every other player (review §25.1), with `diagnostic.error` the
+    // thrown Error and, when the error boundary caught it, `diagnostic.detail.componentStack`.
+    // The component renders `fallback` instead of throwing, so one broken 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.
 
     /** Rendered in place of the animation after a failure. Default: nothing. */
     fallback?: (error: Error) => ReactElement | null;
@@ -274,17 +216,11 @@ function SampledSubtree({
 
 
 /** Overrides that shadow the document's own `animator` config. */
-interface ConfigOverrides {
-    config?: PxAnimatorConfigPatch | string;
-    resetDocDefaults?: boolean;
-    duration?: number;
-    delay?: number;
-    iterations?: number | 'infinite';
-    startOn?: StartOn;
-}
+/** 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;
@@ -298,34 +234,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 { config, resetDocDefaults, duration, delay, iterations, startOn } = 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 — `materialiseAllInTree` samples motion paths against `duration`, so a later
+    // 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 = foldAnimatorConfigShortcuts(config, { duration, delay, iterations, startOn });
-    if (patch !== undefined || resetDocDefaults) {
-        const applied = applyAnimatorConfig(doc, patch ?? {}, { resetDefaults: !!resetDocDefaults });
-        for (const w of applied.warnings) console.warn('[PixodeskSvgAnimator] config override:', w);
+    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, PxTimelineEngine.native);
+    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
@@ -345,46 +281,67 @@ 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.
+ * @public
  */
 export function PixodeskSvgAnimator({
-    doc, config, resetDocDefaults, duration, delay, iterations, startOn,
+    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, muteWarn, muteError,
 }: PixodeskSvgAnimatorProps): ReactElement | null {
 
     // -- Compile the document (once per doc/override change) ------------------
 
-    // `config` is an object prop: a fresh literal every render would otherwise recompile the
-    // whole document (materialise + compile tracks), which is the expensive path. Key on its
+    // `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 configKey = typeof config === 'string' ? config : JSON.stringify(config ?? null);
+    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, onError, muteWarn, muteError }, '[PixodeskSvgAnimator]');
+
     const compiled = useMemo((): Compiled => {
         try {
             return compileDocument(
                 doc,
-                { config, resetDocDefaults, duration, delay, iterations, startOn }
+                { timeline, resetTimeline, duration, delay, iterations, startOn },
+                makeDiag(),
             );
         } catch (e) {
-            // A malformed document must not take the host screen down with it.
+            // A malformed document must not take the host screen down with it. This instance
+            // will not play — an ERROR, reported once, here (review §25.1).
             const error = e instanceof Error ? e : new Error(String(e));
-            console.warn('[PixodeskSvgAnimator] could not compile the document:', error.message);
+            makeDiag().error(PxDiagnosticKind.internal, error, { phase: 'compile' });
             return { doc: null, tracks: EMPTY_TRACKS, error };
         }
-        // `config` is an object prop, so a fresh literal each render would recompile the whole
+        // `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, configKey, resetDocDefaults, duration, delay, iterations, startOn]);
+    }, [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 -------------------------------------------------------
 
@@ -407,6 +364,8 @@ export function PixodeskSvgAnimator({
 
     const notifyFinish = () => {
         playingRef.current = false;
+        runClock.seek(Number.isFinite(seekCeiling) ? seekCeiling : tracks.duration);
+        runClock.stop();
         progress.value = restingPosition();
         onFinish?.();
         onStop?.();
@@ -457,13 +416,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?.();
         },
@@ -471,30 +434,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;
@@ -502,6 +480,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));
         },
     };
 
@@ -510,30 +495,46 @@ export function PixodeskSvgAnimator({
     // -- Declarative control --------------------------------------------------
 
     // The EFFECTIVE trigger, read back off the COMPILED document — so it already reflects the
-    // `config` override and the `startOn` shortcut, both merged in before compilation.
-    const trigger = compiled.doc ? getAnimatorConfig(compiled.doc)?.trigger : undefined;
-    const effectiveStartOn = trigger?.startOn ?? 'load';
-    const effectiveOutAction = trigger?.outAction ?? 'pause';
+    // `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 && effectiveStartOn === '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
@@ -543,7 +544,7 @@ export function PixodeskSvgAnimator({
     const inViewRef = useRef(false);
     useEffect(() => {
         if (!autoplay || effectiveStartOn !== 'scrollIntoView') return;
-        const threshold = trigger?.scrollIntoViewThreshold ?? 0;
+        const threshold = trigger.scrollIntoViewThreshold;
         inViewRef.current = false;
 
         const check = () => {
@@ -572,11 +573,14 @@ export function PixodeskSvgAnimator({
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [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]);
@@ -640,27 +644,27 @@ export function PixodeskSvgAnimator({
                 },
             });
         } catch (e) {
-            // Building the element tree threw — report it and render nothing
-            // rather than propagating and unmounting the host screen.
+            // Building the element tree threw — this instance will not play: report it once
+            // (an ERROR, review §25.1) and render nothing rather than unmount 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().error(PxDiagnosticKind.internal, error, { phase: 'render' });
             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.
+    // A compile/render failure was reported where it was caught (once, as an error); here it
+    // only decides what to show.
     const failure = compiled.error ?? renderErrorRef.current;
-    useEffect(() => {
-        if (failure) onError?.(failure);
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [failure]);
-
     if (failure) return fallback ? fallback(failure) : null;
 
     // `startOn: 'click'` — the touch analogue of the web player's click trigger:
@@ -695,7 +699,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 fallback={fallback} diag={makeDiag()}>
             {content}
         </PxRnErrorBoundary>
     );

package/src/PxRnErrorBoundary.tsx

@@ -4,12 +4,20 @@
  *---------------------------------------------------------------------------------------*/
 
 import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { PxDiagnosticKind, type PxDiagnostics } from '@pixodesk/svg-animator-core';
+import { createDiagnostics } from '@pixodesk/svg-animator-core/internal';
 
+/** @public @advanced */
 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 the failure is reported (API review §5, §25.1): `error(internal, …)` with
+     * `{ componentStack }` as the detail — so it reaches `onError` like every other failure.
+     * Defaults to the console.
+     */
+    diag?: PxDiagnostics;
 }
 
 interface State {
@@ -22,12 +30,13 @@ interface State {
  * A throw anywhere in the rendered SVG tree — an unsupported prop shape, a
  * react-native-svg internal, a reanimated attachment failure — otherwise
  * unmounts the whole React tree above it. Here it is contained to this one
- * animation, reported through `onError`, and replaced by `fallback`.
+ * animation, reported through the diagnostics channel, and replaced by `fallback`.
  *
  * NOTE the limit: this catches JavaScript errors only. A crash INSIDE the
  * native renderer (see `openClosedTextPathTargets` for a real example) never
  * reaches JavaScript and cannot be caught here — those have to be avoided
  * rather than handled.
+ * @public @advanced
  */
 export class PxRnErrorBoundary extends Component<PxRnErrorBoundaryProps, State> {
     override state: State = { error: null };
@@ -37,8 +46,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]'))
+            .error(PxDiagnosticKind.internal, error, { componentStack: info?.componentStack ?? undefined });
     }
 
     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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License. See the LICENSE file in the project root for details.
  *---------------------------------------------------------------------------------------*/
 
-import { kebabToCamelCaseWord } from '@pixodesk/svg-animator-core';
+import { kebabToCamelCaseWord } from '@pixodesk/svg-animator-core/internal';
 import { svgTransformToMatrix } from './PxRnMatrix';
 
 /** Attribute names with a react-native-svg prop equivalent under a
@@ -16,12 +16,13 @@ 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.
  *
  * Pure (no react-native-svg import) so the track compiler and its tests
  * don't need a React Native environment.
+ * @internal
  */
 export function toRnPropName(attrName: string): string | undefined {
     if (DROPPED_ATTRS.has(attrName)) return undefined;
@@ -57,7 +58,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);