@pixodesk/svg-animator-rn 1.0.34 → 1.0.39

package/README.md

@@ -51,7 +51,7 @@ document says so.
 
 ```tsx
 // Play once when a screen opens, then hold the last frame
-<PixodeskSvgAnimator doc={doc} autoplay iterations={1} fill="forwards" />
+<PixodeskSvgAnimator doc={doc} autoplay iterations={1} timeline={{ fillMode: 'forwards' }} />
 
 // Loop forever regardless of what the document says
 <PixodeskSvgAnimator doc={doc} autoplay iterations="infinite" />
@@ -166,6 +166,7 @@ const [time, setTime] = useState(0);
 
 ## Props
 
+<!-- px-check props PixodeskSvgAnimatorProps pkg=rn -->
 | Prop | Type | Description |
 |---|---|---|
 | `doc` | `PxAnimatedSvgDocument` | The animation document to render (required) |
@@ -175,19 +176,21 @@ const [time, setTime] = useState(0);
 | `apiRef` | `RefObject<RnAnimatorApi>` | Ref for imperative control |
 | `progress` | `number` | show the frame at this position in the whole timeline (duration × iterations): `0` is the first frame, `0.5` the middle, `1` the last |
 | `time` | `number` | show the frame at that time, in milliseconds from the start |
-| `duration` | `number` | Duration override (ms) |
-| `delay` | `number` | Delay before start (ms) |
-| `iterations` | `number \| 'infinite'` | Loop count |
-| `fill` | `FillMode` | Fill behaviour |
-| `direction` | `PlaybackDirection` | Playback direction |
-| `resetOnFinish` | `boolean` | Snap back to the start after a natural finish |
-| `outAction` | `OutAction` | What a second tap does with the `click` trigger (default: the document's, else `pause`) |
+| `timeline` | `object \| string` | per-instance override of the document's `timeline` block, deep-merged over it — same shape as the file; `null` at any slot deletes that key. A JSON string is accepted too. See [Playback overrides](#playback-overrides) |
+| `resetTimeline` | `boolean` | ignore the document's own timeline and start from the player's default timeline, with `timeline` on top |
+| `duration` | `number` | Shortcut for `timeline.duration` (ms) |
+| `delay` | `number` | Shortcut for `timeline.delay` (ms) |
+| `iterations` | `number \| 'infinite'` | Shortcut for `timeline.iterations` |
+| `startOn` | `PxStartOn` | Shortcut for `timeline.trigger.startOn`. `mouseOver` has no touch equivalent and is ignored |
 | `onPlay` | `() => void` | Called on play/resume |
 | `onPause` | `() => void` | Called on pause |
-| `onFinish` | `() => void` | Called on natural finish |
+| `onFinish` | `() => void` | Called when the animation reaches its end — every iteration played, or `finish()` was called |
 | `onCancel` | `() => void` | Called on cancel |
-| `onStop` | `() => void` | Called whenever playback halts (pause / cancel / finish) |
+| `onRemove` | `() => void` | Called when the animator is thrown away — the component unmounted, or a new `doc` replaced it |
+| `onStop` | `() => void` | Called whenever playback halts (pause / cancel / finish / remove) |
 | `onError` | `(error, componentStack?) => void` | Called when a document cannot be compiled or rendered |
+| `onWarn` | `(diagnostic) => void` | something is off but the animation still plays; without it → `console.warn` |
+| `silent` | `boolean \| PxDiagnosticKind[]` | silences the console fallback — everything, or just the kinds listed |
 | `fallback` | `(error) => ReactElement \| null` | Rendered in place of a failed animation (default: nothing) |
 
 With none of `autoplay` / `play` / `pause` / `progress` / `time` set, the component
@@ -215,11 +218,12 @@ renderer never reaches JavaScript and cannot be caught — see
 
 ### Differences from the React package
 
+<!-- px-check off differences from React, prose -->
 | Prop | Why it differs |
 |---|---|
-| `mode` | Not accepted. There is no Web Animations API on React Native; playback is always native-driven. |
-| `frameRate` | Not accepted. The screen's own refresh rate is used. The player does not compute values frame by frame: when the document loads it works out the animated values in advance, as a list of snapshots (60 per second of animation), and each screen refresh shows the nearest one. The closest thing to a frame rate is how many snapshots per second are prepared — `compileTracks({ sampleRate })`, only available when you use the lower-level API instead of the component. |
-| `startOn` | Not accepted as a prop — the document's trigger is honoured via `autoplay` (`load`, `click`, `scrollIntoView`, `programmatic`). `mouseOver` has no touch equivalent. |
+| `timeline.engine` | Accepted inside `timeline` but ignored. There is no Web Animations API on React Native; playback is always native-driven. |
+| `timeline.frameRate` | Ignored. The screen's own refresh rate is used. The player does not compute values frame by frame: when the document loads it works out the animated values in advance, as a list of snapshots (60 per second of animation), and each screen refresh shows the nearest one. The closest thing to a frame rate is how many snapshots per second are prepared — `compileTracks({ sampleRate })`, only available when you use the lower-level API instead of the component. |
+| `startOn: 'mouseOver'` | Has no touch equivalent, so it is not honored. The other four values (`load`, `click`, `scrollIntoView`, `programmatic`) work as they do on the web, from the file or from the `startOn` prop. |
 | `className` / `style` | Not accepted — you cannot style the component itself. It fills whatever `View` you put it in, so to set its size, give that `View` a `width` and `height`. Styling *inside* the document (`style` on an element in the JSON) is supported. |
 | `onRemove` | Never called. On the web it tells you the animator was thrown away; here there is nothing to tell — when the component leaves the screen, React removes it and everything it created. To run code at that moment, use a `useEffect` cleanup function in your own component. |
 
@@ -229,9 +233,9 @@ There is **no JavaScript frame loop** — the JS thread is idle while an
 animation runs.
 
 1. **Once per document:** the shared core flattens it
-   (`materialiseAllInTree` → effects, loops, motion-path sampling, animated
+   (`materializeAllInTree` → effects, loops, motion-path sampling, animated
    `<use>` inlining), then a track compiler densely samples every animated
-   property with `calcAnimationValues` — the same function the web frames engine
+   property with `calcAnimationValues` — the same function the web frame-loop engine
    renders with, so values match the web player exactly.
 2. **Per frame:** one reanimated progress value, driven by
    `withTiming`/`withRepeat` on the UI thread, and a tiny worklet per animated
@@ -244,29 +248,31 @@ converts it into plain values ahead of time instead of fighting the platform.
 ## Feature support
 
 Every row below was verified by running the document through the real
-pipeline (`materialiseAllInTree` → track compilation) and checking that the
+pipeline (`materializeAllInTree` → track compilation) and checking that the
 element maps to a `react-native-svg` component and that its animated
 properties actually change over time.
 
 ### Elements
 
+<!-- px-check off support matrix, prose -->
 | Element | Renders | Notes |
 |---|---|---|
 | `svg`, `g`, `defs` | ✅ | |
 | `rect`, `circle`, `ellipse`, `line`, `path`, `polygon`, `polyline` | ✅ | |
 | `text`, `tspan` | ✅ | content via the `text` attribute |
 | `textPath` | ✅ | see *Text along a path* below |
-| `image` | ✅ | `href` accepts `data:` URIs; remote URLs are blocked by the sanitiser |
+| `image` | ✅ | `href` accepts `data:` URIs; remote URLs are blocked by the sanitizer |
 | `use`, `symbol` | ✅ | animated targets are **inlined into real clones** before render — `<use>` does not propagate animation natively in React Native |
 | `linearGradient`, `radialGradient`, `stop` | ✅ | |
 | `pattern`, `marker` | ✅ | static geometry verified; complex cases unverified on device |
 | `mask`, `clipPath` | ✅ | |
 | `filter` + all 22 `fe*` primitives | ✅ | `feGaussianBlur`, `feDropShadow`, `feColorMatrix`, `feMerge`, `feComponentTransfer` + `feFunc*`, … **The visual result has not yet been checked on a real device** |
-| `foreignObject` | ❌ | blocked by the shared sanitiser (embeds arbitrary host content) |
-| `script` | ❌ | blocked by the shared sanitiser |
+| `foreignObject` | ❌ | blocked by the shared sanitizer (embeds arbitrary host content) |
+| `script` | ❌ | blocked by the shared sanitizer |
 
 ### Animatable attributes
 
+<!-- px-check off support matrix, prose -->
 | Attribute | Animates | Notes |
 |---|---|---|
 | `opacity`, `fill-opacity`, `stroke-opacity` | ✅ | |
@@ -283,50 +289,52 @@ properties actually change over time.
 
 ### Effects (`node.effects`)
 
-All effects are materialised by the shared core before rendering, so the React Native
+All effects are materialized by the shared core before rendering, so the React Native
 player sees plain nodes. **All are supported:**
 
+<!-- px-check schema PxEffectsSchema -->
 | Effect | Status | Notes |
 |---|---|---|
 | `transformBy` | ✅ | all parts animatable, including `skew` |
-| `repeater` | ✅ | copies materialised as real elements; per-copy params animatable |
+| `repeater` | ✅ | copies materialized as real elements; per-copy params animatable |
 | `maskedBy` | ✅ | including an animated mask source |
 | `clipPath` | ✅ | including animated clip geometry |
 | `strokeTrim` | ✅ | incl. `offset` and `subPaths: 'combined'` |
 | `clone` + `retime` | ✅ | each clone keeps its own time shift, incl. `retime.timeCrop` (a visibility window on the document timeline) |
-| `fillGradient` / `strokeGradient` | ✅ | animated stops **and animated geometry** (`animate.gradientX1`/`Cx`/`R`, …); `gradientTransform` is static (core-wide) |
+| `fillGradient` / `strokeGradient` | ✅ | animated stops **and animated geometry** (`animate.gradientX1`/`Cx`/`R`, …); `gradientTransform` is static (core-wide) | <!-- px names=fillGradient,strokeGradient -->
 | `textPath` | ✅ | incl. animated `startOffset` |
-| `text.useGlyphs` | ✅ | text becomes `<path>` outlines from `definitions.glyphs` — no font needed |
-| `isCombinedShape` | ✅ | |
+| `text.useGlyphs` | ✅ | text becomes `<path>` outlines from `definitions.fonts` — no font needed |
 
 ### Motion, timing and references
 
+<!-- px-check off support matrix, prose -->
 | Feature | Status | Notes |
 |---|---|---|
 | **Motion along a path** + `autoOrient` | ✅ | **sampled** by the core into plain transform keyframes — `react-native-svg` has no native path motion |
 | **Text along a path** | ✅ two ways | native `textPath` (incl. animated `startOffset`), or **per-letter motion paths** for smooth results — the example app uses the latter, since animating native `startOffset` is janky in `react-native-svg` |
 | Per-property `loop` (incl. `alternate` pingpong) | ✅ | expanded before playback |
 | Easing (cubic-bezier and named refs) | ✅ | baked into the sampled tracks |
-| `definitions.animations` / `easings` / `styles` / `glyphs` | ✅ | named refs resolved; `style` presets applied as props |
+| `definitions.animations` / `easings` / `styles` / `fonts` | ✅ | named refs resolved; `style` presets applied as props |
 | `node.style` (inline or named) | ✅ | resolved to props — React Native has no CSS, so explicit attributes win |
 
 ### Playback and triggers
 
+<!-- px-check off support matrix, prose -->
 | Feature | Status | Notes |
 |---|---|---|
 | `duration`, `delay`, `iterations` (incl. `'infinite'`) | ✅ | |
 | `direction` — all four values | ✅ | |
-| `fill` — `forwards` / `backwards` / `both` / `none` | ✅ | |
-| `resetOnFinish` | ✅ | |
+| `fillMode` — `forwards` / `backwards` / `both` / `none` | ✅ | |
+| `trigger.finishAction: 'reset'` | ✅ | |
 | `play` / `pause` / `cancel` / `finish` | ✅ | |
 | `setCurrentTime` — jump to a time, including **while playing** | ✅ | playback continues from the new point |
 | `setPlaybackRate` — faster, slower and **reverse** (negative) | ✅ | composes with `direction` |
 | Trigger `load` / `programmatic` | ✅ | |
 | Trigger `click` | ✅ | wrapped in a `Pressable`; a second tap applies `outAction` |
-| Trigger `scrollIntoView` | ✅ | visibility sampled by measuring against the window (React Native has no `IntersectionObserver`); honours `scrollIntoViewThreshold` and `outAction` |
+| Trigger `scrollIntoView` | ✅ | visibility sampled by measuring against the window (React Native has no `IntersectionObserver`); honors `scrollIntoViewThreshold` and `outAction` |
 | Trigger `mouseOver` | ❌ | no touch equivalent — use `click`, or drive `play` yourself |
-| `frameRate` | n/a | reanimated runs at the display refresh rate; use `compileTracks({sampleRate})` to trade memory for temporal precision |
-| `mode` (`waapi` / `frames`) | n/a | there is no Web Animations API on React Native — playback is always native-driven |
+| `timeline.frameRate` | n/a | reanimated runs at the display refresh rate; use `compileTracks({sampleRate})` to trade memory for temporal precision |
+| `timeline.engine` (`auto` / `native` / `js`) | n/a | there is no Web Animations API on React Native — playback is always native-driven |
 
 ### Known limitations
 

package/dist/index.cjs

@@ -73,7 +73,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/PixodeskSvgAnimator.tsx
-var import_svg_animator_core5 = require("@pixodesk/svg-animator-core");
+var import_svg_animator_core6 = require("@pixodesk/svg-animator-core");
 var import_react3 = require("react");
 var import_react_native = require("react-native");
 var import_react_native_reanimated = __toESM(require("react-native-reanimated"), 1);
@@ -199,7 +199,7 @@ function compileTracks(doc, opts) {
     ((_a2 = n == null ? void 0 : n.children) != null ? _a2 : []).forEach(indexTags);
   };
   indexTags(doc);
-  const bindings = (0, import_svg_animator_core2.getNormalisedBindings)(doc, import_svg_animator_core2.PxAnimatorEngine.frames) || [];
+  const bindings = (0, import_svg_animator_core2.getNormalizedBindings)(doc, import_svg_animator_core2.PxTimelineEngine.js) || [];
   const elements = [];
   for (const binding of bindings) {
     const animDef = binding.animate;
@@ -326,14 +326,14 @@ var RN_SVG_COMPONENTS = {
 
 // src/PxRnRender.tsx
 function toRnProps(props, warnings, tag) {
-  const normalised = (0, import_svg_animator_core3.getNormalizedProps)(props);
+  const normalized = (0, import_svg_animator_core3.getNormalizedProps)(props);
   const out = {};
-  for (const key of Object.keys(normalised)) {
-    const sanitised = (0, import_svg_animator_core3.sanitiseAttributeValue)(key, normalised[key]);
-    if (sanitised === void 0) continue;
+  for (const key of Object.keys(normalized)) {
+    const sanitized = (0, import_svg_animator_core3.sanitizeAttributeValue)(key, normalized[key]);
+    if (sanitized === void 0) continue;
     const rnKey = toRnPropName(key);
     if (!rnKey) continue;
-    out[rnKey] = toRnPropValue(rnKey, String(sanitised), tag);
+    out[rnKey] = toRnPropValue(rnKey, String(sanitized), tag);
   }
   return out;
 }
@@ -360,12 +360,12 @@ function renderRnNode(node, opts = {}, key) {
     for (const [k, v] of Object.entries(resolved)) {
       const rnKey = toRnPropName(k);
       if (!rnKey || rnKey in rnProps) continue;
-      const sanitised = (0, import_svg_animator_core3.sanitiseAttributeValue)(rnKey, v);
-      if (sanitised === void 0) continue;
-      rnProps[rnKey] = toRnPropValue(rnKey, String(sanitised), tag);
+      const sanitized = (0, import_svg_animator_core3.sanitizeAttributeValue)(rnKey, v);
+      if (sanitized === void 0) continue;
+      rnProps[rnKey] = toRnPropValue(rnKey, String(sanitized), tag);
     }
   }
-  const textContent = props[import_svg_animator_core3.TEXT_ATTR] || props[import_svg_animator_core3.TEXT_CONTENT_ATTR];
+  const textContent = props[import_svg_animator_core3.TEXT_CONTENT_ATTR];
   let childElements = void 0;
   if (Array.isArray(children) && children.length > 0) {
     childElements = children.map((ch, i) => {
@@ -391,6 +391,7 @@ function renderRnNode(node, opts = {}, key) {
 
 // src/PxRnErrorBoundary.tsx
 var import_react2 = require("react");
+var import_svg_animator_core4 = require("@pixodesk/svg-animator-core");
 var PxRnErrorBoundary = class extends import_react2.Component {
   constructor() {
     super(...arguments);
@@ -400,9 +401,9 @@ var PxRnErrorBoundary = class extends import_react2.Component {
     return { error };
   }
   componentDidCatch(error, info) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     (_c = (_b = this.props).onError) == null ? void 0 : _c.call(_b, error, (_a = info == null ? void 0 : info.componentStack) != null ? _a : void 0);
-    console.warn("[PixodeskSvgAnimator] render failed:", (_d = error == null ? void 0 : error.message) != null ? _d : error);
+    ((_d = this.props.diag) != null ? _d : (0, import_svg_animator_core4.createDiagnostics)(void 0, "[PixodeskSvgAnimator]")).warn(import_svg_animator_core4.PxDiagnosticKind.internal, "render failed: " + ((_e = error == null ? void 0 : error.message) != null ? _e : String(error)));
   }
   componentDidUpdate(prev) {
     if (this.state.error && prev.children !== this.props.children) {
@@ -417,7 +418,7 @@ var PxRnErrorBoundary = class extends import_react2.Component {
 };
 
 // src/PxRnSafety.ts
-var import_svg_animator_core4 = require("@pixodesk/svg-animator-core");
+var import_svg_animator_core5 = require("@pixodesk/svg-animator-core");
 function isClosedPath(d) {
   return typeof d === "string" && /[zZ]/.test(d);
 }
@@ -442,7 +443,7 @@ function openClosedTextPathTargets(doc, warnings) {
     if (String(n.type) === "textPath") hasTextPath = true;
   });
   if (!hasTextPath) return doc;
-  const result = (0, import_svg_animator_core4.deepClone)(doc);
+  const result = (0, import_svg_animator_core5.deepClone)(doc);
   const byId = /* @__PURE__ */ new Map();
   forEachNode(result, (n) => {
     const id = n.id;
@@ -469,8 +470,8 @@ function openClosedTextPathTargets(doc, warnings) {
     if (!target || !isClosedPath(target.d)) return;
     let copyId = openCopies.get(targetId);
     if (!copyId) {
-      const copy = (0, import_svg_animator_core4.deepClone)(target);
-      copyId = "px_open_" + (0, import_svg_animator_core4.generateUniqueId)();
+      const copy = (0, import_svg_animator_core5.deepClone)(target);
+      copyId = "px_open_" + (0, import_svg_animator_core5.generateUniqueId)();
       copy.id = copyId;
       copy.d = openPath(String(copy.d));
       delete copy.animate;
@@ -561,38 +562,33 @@ var EMPTY_TRACKS = {
   sampleCount: 2,
   elements: []
 };
-function compileDocument(doc, overrides) {
-  const { duration, delay, iterations, fill, direction, resetOnFinish } = overrides;
-  const warnings = (0, import_svg_animator_core5.validateNodeEffects)(doc);
-  for (const w of warnings) console.warn("[PixodeskSvgAnimator] effects shape warning:", w);
-  let prepared = (0, import_svg_animator_core5.materialiseAllInTree)(doc, import_svg_animator_core5.PxAnimatorEngine.waapi);
+function compileDocument(doc, overrides, diag) {
+  const { timeline, resetTimeline, duration, delay, iterations, startOn } = overrides;
+  const warnings = (0, import_svg_animator_core6.validateNodeEffects)(doc);
+  for (const w of warnings) diag.warn(import_svg_animator_core6.PxDiagnosticKind.document, "effects shape: " + w);
+  (0, import_svg_animator_core6.reportDocumentDiagnostics)(doc, "[PixodeskSvgAnimator]");
+  const patch = (0, import_svg_animator_core6.foldTimelineOverride)(timeline, { duration, delay, iterations, startOn });
+  if (patch !== void 0 || resetTimeline) {
+    const applied = (0, import_svg_animator_core6.applyAnimatorConfig)(doc, patch != null ? patch : {}, { resetDefaults: !!resetTimeline });
+    for (const w of applied.warnings) diag.warn(import_svg_animator_core6.PxDiagnosticKind.usage, "timeline override: " + w);
+    doc = applied.doc;
+  }
+  let prepared = (0, import_svg_animator_core6.materializeAllInTree)(doc, import_svg_animator_core6.PxTimelineEngine.native);
   if (NATIVE_SVG_VIEWS) {
     prepared = openClosedTextPathTargets(prepared);
   }
-  const animator = (0, import_svg_animator_core5.getAnimatorConfig)(prepared) || {};
-  prepared = __spreadProps(__spreadValues({}, prepared), {
-    animator: __spreadProps(__spreadValues({}, animator), {
-      duration: duration !== void 0 ? duration : animator.duration,
-      delay: delay !== void 0 ? delay : animator.delay,
-      iterations: iterations !== void 0 ? iterations : animator.iterations,
-      fill: fill !== void 0 ? fill : animator.fill,
-      direction: direction !== void 0 ? direction : animator.direction,
-      resetOnFinish: resetOnFinish !== void 0 ? resetOnFinish : animator.resetOnFinish
-    })
-  });
-  prepared = (0, import_svg_animator_core5.generateNewIds)(prepared);
+  prepared = (0, import_svg_animator_core6.generateNewIds)(prepared);
   const tracks = compileTracks(prepared, { native: NATIVE_SVG_VIEWS });
   return { doc: prepared, tracks, error: null };
 }
 function PixodeskSvgAnimator({
   doc,
+  timeline,
+  resetTimeline,
   duration,
   delay,
   iterations,
-  fill,
-  direction,
-  resetOnFinish,
-  outAction: outActionProp,
+  startOn,
   // (`progress` prop aliased — the name is taken by the internal reanimated SharedValue)
   autoplay,
   play,
@@ -605,24 +601,42 @@ function PixodeskSvgAnimator({
   onPause,
   onCancel,
   onFinish,
+  onRemove,
   onError,
-  fallback
+  fallback,
+  onWarn,
+  silent
 }) {
-  var _a, _b, _c, _d;
+  var _a, _b;
+  const timelineKey = typeof timeline === "string" ? timeline : JSON.stringify(timeline != null ? timeline : null);
+  const makeDiag = () => (0, import_svg_animator_core6.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) => {
+      var _a2;
+      return onError((_a2 = d.error) != null ? _a2 : new Error(d.message));
+    } : void 0,
+    silent
+  }, "[PixodeskSvgAnimator]");
   const compiled = (0, import_react3.useMemo)(() => {
     try {
       return compileDocument(
         doc,
-        { duration, delay, iterations, fill, direction, resetOnFinish }
+        { timeline, resetTimeline, duration, delay, iterations, startOn },
+        makeDiag()
       );
     } catch (e) {
       const error = e instanceof Error ? e : new Error(String(e));
-      console.warn("[PixodeskSvgAnimator] could not compile the document:", error.message);
+      makeDiag().warn(import_svg_animator_core6.PxDiagnosticKind.internal, "could not compile the document: " + error.message);
       return { doc: null, tracks: EMPTY_TRACKS, error };
     }
-  }, [doc, duration, delay, iterations, fill, direction, resetOnFinish]);
+  }, [doc, timelineKey, resetTimeline, duration, delay, iterations, startOn]);
   const tracks = compiled.tracks;
-  const totalDuration = tracks.duration * (tracks.iterations === Infinity ? 1 : tracks.iterations);
+  const totalDuration = (0, import_svg_animator_core6.progressSpanMs)(tracks.duration, tracks.iterations);
+  const seekCeiling = (0, import_svg_animator_core6.seekCeilingMs)(tracks.duration, tracks.iterations);
+  const runClock = (0, import_react3.useMemo)(() => (0, import_svg_animator_core6.createRunClock)(seekCeiling), [seekCeiling]);
   const progress = (0, import_react_native_reanimated.useSharedValue)(0);
   const playingRef = (0, import_react3.useRef)(false);
   const rateRef = (0, import_react3.useRef)(1);
@@ -634,6 +648,8 @@ function PixodeskSvgAnimator({
   };
   const notifyFinish = () => {
     playingRef.current = false;
+    runClock.seek(Number.isFinite(seekCeiling) ? seekCeiling : tracks.duration);
+    runClock.stop();
     progress.value = restingPosition();
     onFinish == null ? void 0 : onFinish();
     onStop == null ? void 0 : onStop();
@@ -670,12 +686,15 @@ function PixodeskSvgAnimator({
   const api = {
     isPlaying: () => playingRef.current,
     play: () => {
+      if (Number.isFinite(seekCeiling) && runClock.now() >= seekCeiling) runClock.seek(0);
+      runClock.start(rateRef.current);
       startFrom(progress.value);
       onPlay == null ? void 0 : onPlay();
     },
     pause: () => {
       (0, import_react_native_reanimated.cancelAnimation)(progress);
       playingRef.current = false;
+      runClock.stop();
       onPause == null ? void 0 : onPause();
       onStop == null ? void 0 : onStop();
     },
@@ -683,62 +702,82 @@ function PixodeskSvgAnimator({
       (0, import_react_native_reanimated.cancelAnimation)(progress);
       progress.value = 0;
       playingRef.current = false;
+      runClock.seek(0);
+      runClock.stop();
       onCancel == null ? void 0 : onCancel();
       onStop == null ? void 0 : onStop();
     },
     finish: () => {
       (0, import_react_native_reanimated.cancelAnimation)(progress);
       playingRef.current = false;
+      runClock.seek(Number.isFinite(seekCeiling) ? seekCeiling : tracks.duration);
+      runClock.stop();
       progress.value = restingPosition();
       onFinish == null ? void 0 : onFinish();
       onStop == null ? void 0 : onStop();
     },
     setPlaybackRate: (rate) => {
-      if (!isFinite(rate) || rate === 0) {
-        console.warn("setPlaybackRate: rate must be finite and non-zero");
+      if (!(0, import_svg_animator_core6.isValidPlaybackRate)(rate)) {
+        makeDiag().warn(import_svg_animator_core6.PxDiagnosticKind.usage, import_svg_animator_core6.PX_RATE_REJECTED);
         return;
       }
       rateRef.current = rate;
-      if (playingRef.current) startFrom(progress.value);
+      if (playingRef.current) {
+        runClock.start(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) => {
       const wasPlaying = playingRef.current;
       (0, import_react_native_reanimated.cancelAnimation)(progress);
       playingRef.current = false;
-      const clamped = Math.max(0, Math.min(t, totalDuration));
+      const clamped = (0, import_svg_animator_core6.clampSeekMs)(t, seekCeiling);
+      runClock.seek(clamped);
       const withinIteration = tracks.duration > 0 ? clamped % tracks.duration || (clamped === 0 ? 0 : tracks.duration) : 0;
       progress.value = withinIteration;
       if (wasPlaying) startFrom(withinIteration);
+      else runClock.stop();
+    },
+    getCurrentProgress: () => (0, import_svg_animator_core6.timeToProgress)(runClock.now(), tracks.duration, tracks.iterations),
+    setCurrentProgress: (p) => {
+      api.setCurrentTime((0, import_svg_animator_core6.progressToTimeMs)(p, tracks.duration, tracks.iterations));
     }
   };
   (0, import_react3.useImperativeHandle)(apiRef, () => api, [compiled]);
-  const trigger = compiled.doc ? (_a = (0, import_svg_animator_core5.getAnimatorConfig)(compiled.doc)) == null ? void 0 : _a.trigger : void 0;
-  const startOn = (_b = trigger == null ? void 0 : trigger.startOn) != null ? _b : "load";
-  const outAction = (_c = outActionProp != null ? outActionProp : trigger == null ? void 0 : trigger.outAction) != null ? _c : "pause";
+  const trigger = (0, import_svg_animator_core6.resolveTrigger)(compiled.doc ? (_a = (0, import_svg_animator_core6.getAnimatorConfig)(compiled.doc)) == null ? void 0 : _a.trigger : void 0);
+  const effectiveStartOn = trigger.startOn;
+  const effectiveOutAction = trigger.outAction;
+  const { mode: compMode, warnings: modeWarnings } = (0, import_svg_animator_core6.resolveControlMode)({ progress: progressProp, time, play, pause, autoplay });
   (0, import_react3.useEffect)(() => {
-    if (progressProp !== void 0 || time !== void 0) {
-      const seekMs = time !== void 0 ? time : (progressProp != null ? progressProp : 0) * totalDuration;
+    const diag = makeDiag();
+    for (const w of modeWarnings) diag.warn(import_svg_animator_core6.PxDiagnosticKind.usage, w);
+  }, [modeWarnings.join("|")]);
+  (0, import_react3.useEffect)(() => {
+    if (compMode === import_svg_animator_core6.PxControlMode.fixedTime) {
+      const seekMs = time !== void 0 ? time : (0, import_svg_animator_core6.progressToTimeMs)(progressProp != null ? progressProp : 0, tracks.duration, tracks.iterations);
       api.setCurrentTime(seekMs);
       return;
     }
-    if (play !== void 0 || pause !== void 0) {
+    if (compMode === import_svg_animator_core6.PxControlMode.play) {
       if (play && !pause) api.play();
       else if (pause) api.pause();
-      else if (play === false) api.finish();
+      else if (play === false) api.pause();
       else api.play();
       return;
     }
-    if (autoplay && startOn === "load") {
+    if (compMode === import_svg_animator_core6.PxControlMode.autoplay && effectiveStartOn === "load") {
       api.play();
     }
-  }, [compiled, autoplay, play, pause, progressProp, time]);
+  }, [compiled, compMode, autoplay, play, pause, progressProp, time]);
   const scrollRef = (0, import_react3.useRef)(null);
   const inViewRef = (0, import_react3.useRef)(false);
   (0, import_react3.useEffect)(() => {
-    var _a2;
-    if (!autoplay || startOn !== "scrollIntoView") return;
-    const threshold = (_a2 = trigger == null ? void 0 : trigger.scrollIntoViewThreshold) != null ? _a2 : 0;
+    if (!autoplay || effectiveStartOn !== "scrollIntoView") return;
+    const threshold = trigger.scrollIntoViewThreshold;
     inViewRef.current = false;
     const check = () => {
       const node = scrollRef.current;
@@ -754,21 +793,23 @@ 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") {
+        } else if (effectiveOutAction === "reset") api.cancel();
+        else if (effectiveOutAction === "reverse") {
           api.setPlaybackRate(-Math.abs(rateRef.current || 1));
           api.play();
-        } else if (outAction !== "continue") api.pause();
+        } else if (effectiveOutAction !== "continue") api.pause();
       });
     };
     check();
     const id = setInterval(check, 200);
     return () => clearInterval(id);
-  }, [compiled, autoplay, startOn, outAction]);
+  }, [compiled, autoplay, effectiveStartOn, effectiveOutAction]);
   (0, import_react3.useEffect)(() => {
     return () => {
       (0, import_react_native_reanimated.cancelAnimation)(progress);
       playingRef.current = false;
+      onRemove == null ? void 0 : onRemove();
+      onStop == null ? void 0 : onStop();
     };
   }, [compiled]);
   const trackById = (0, import_react3.useMemo)(() => {
@@ -784,7 +825,7 @@ function PixodeskSvgAnimator({
     if (!compiled.doc) return null;
     const renderOpts = {
       warnings: warningsRef.current,
-      defs: (0, import_svg_animator_core5.getDefs)(compiled.doc)
+      defs: (0, import_svg_animator_core6.getDefs)(compiled.doc)
     };
     try {
       return renderRnNode(compiled.doc, __spreadProps(__spreadValues({}, renderOpts), {
@@ -824,32 +865,33 @@ function PixodeskSvgAnimator({
     } catch (e) {
       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(import_svg_animator_core6.PxDiagnosticKind.internal, "could not render the document: " + error.message);
       return null;
     }
   }, [compiled, trackById]);
   (0, import_react3.useEffect)(() => {
-    for (const w of warningsRef.current) console.warn("[PixodeskSvgAnimator]", w);
+    const diag = makeDiag();
+    for (const w of warningsRef.current) diag.warn(import_svg_animator_core6.PxDiagnosticKind.platform, w);
   }, [root]);
-  const failure = (_d = compiled.error) != null ? _d : renderErrorRef.current;
+  const failure = (_b = compiled.error) != null ? _b : renderErrorRef.current;
   (0, import_react3.useEffect)(() => {
     if (failure) onError == null ? void 0 : onError(failure);
   }, [failure]);
   if (failure) return fallback ? fallback(failure) : null;
   let content = root;
-  if (autoplay && startOn === "scrollIntoView" && root) {
+  if (autoplay && effectiveStartOn === "scrollIntoView" && root) {
     content = /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.View, { ref: scrollRef, collapsable: false, children: root });
-  } else if (autoplay && startOn === "click" && root) {
+  } else if (autoplay && effectiveStartOn === "click" && root) {
     content = /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       import_react_native.Pressable,
       {
         onPress: () => {
           if (playingRef.current) {
-            if (outAction === "reset") api.cancel();
-            else if (outAction === "reverse") {
+            if (effectiveOutAction === "reset") api.cancel();
+            else if (effectiveOutAction === "reverse") {
               api.setPlaybackRate(-Math.abs(rateRef.current || 1));
               api.play();
-            } else if (outAction !== "continue") api.pause();
+            } else if (effectiveOutAction !== "continue") api.pause();
           } else {
             if (rateRef.current < 0) api.setPlaybackRate(Math.abs(rateRef.current));
             api.play();
@@ -859,7 +901,7 @@ function PixodeskSvgAnimator({
       }
     );
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PxRnErrorBoundary, { onError, fallback, children: content });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PxRnErrorBoundary, { onError, fallback, diag: makeDiag(), children: content });
 }
 var PixodeskSvgAnimator_default = PixodeskSvgAnimator;
 // Annotate the CommonJS export names for ESM import in node: