@pixodesk/svg-animator-rn 1.0.21 → 1.0.22

package/src/PxRnMatrix.test.ts

@@ -0,0 +1,97 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+import { describe, expect, it } from 'vitest';
+import { svgTransformToMatrix } from './PxRnMatrix';
+import { toRnPropValue } from './PxRnPropNames';
+import { sampleProps } from './PxRnTracks';
+
+/** Reference values cross-checked against react-native-svg's own `parse()`. */
+describe('svgTransformToMatrix', () => {
+    it.each([
+        ['translate(10,20)', [1, 0, 0, 1, 10, 20]],
+        ['scale(2,3)', [2, 0, 0, 3, 0, 0]],
+        ['rotate(90)', [0, 1, -1, 0, 0, 0]],
+        ['skewX(45)', [1, 0, 1, 1, 0, 0]],
+        ['skewY(45)', [1, 1, 0, 1, 0, 0]],
+        ['matrix(1,2,3,4,5,6)', [1, 2, 3, 4, 5, 6]],
+        ['translate(5,5) translate(-5,-5)', [1, 0, 0, 1, 0, 0]],
+    ] as Array<[string, Array<number>]>)('%s', (input, expected) => {
+        const m = svgTransformToMatrix(input)!;
+        expect(m).toHaveLength(6);
+        m.forEach((v, i) => expect(v).toBeCloseTo(expected[i], 9));
+    });
+
+    it('composes a list left-to-right (translate then rotate)', () => {
+        // translate(10,0) rotate(90) maps local (1,0) → (10,1)
+        const m = svgTransformToMatrix('translate(10,0)rotate(90)')!;
+        const x = m[0] * 1 + m[2] * 0 + m[4];
+        const y = m[1] * 1 + m[3] * 0 + m[5];
+        expect(x).toBeCloseTo(10, 9);
+        expect(y).toBeCloseTo(1, 9);
+    });
+
+    it('honours a rotation centre', () => {
+        // 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);
+        expect(m[1] * 0 + m[3] * 0 + m[5]).toBeCloseTo(0, 9);
+    });
+
+    it('returns undefined when nothing parses, so the caller can pass the value through', () => {
+        expect(svgTransformToMatrix('')).toBeUndefined();
+        expect(svgTransformToMatrix('none')).toBeUndefined();
+    });
+});
+
+describe('toRnPropValue transform handling', () => {
+    it('converts a transform string to a matrix when targeting native views', () => {
+        expect(toRnPropValue('transform', 'translate(3,4)', undefined, true)).toEqual([1, 0, 0, 1, 3, 4]);
+    });
+
+    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.
+        expect(toRnPropValue('transform', 'translate(3,4)')).toBe('translate(3,4)');
+    });
+
+    it('leaves the ROOT <Svg> transform as a string even on native', () => {
+        // The root view uses `extractTransformSvgView`, which wants a string /
+        // RN style — a matrix would be silently dropped there.
+        expect(toRnPropValue('transform', 'translate(3,4)', 'svg', true)).toBe('translate(3,4)');
+    });
+
+    it('passes non-transform props through untouched', () => {
+        expect(toRnPropValue('fill', 'rgba(1,2,3,1)')).toBe('rgba(1,2,3,1)');
+        expect(toRnPropValue('opacity', '0.5')).toBe(0.5);
+    });
+});
+
+describe('native prop naming (animated path)', () => {
+    const tracks = {
+        id: 'x',
+        props: {
+            transform: [[1, 0, 0, 1, 0, 0], [1, 0, 0, 1, 9, 9]] as Array<Array<number>>,
+            opacity: [1, 0],
+        },
+    } as any;
+
+    it('renames transform → matrix for the reanimated path', () => {
+        // The native view declares `matrix`; a `transform` prop is silently
+        // dropped there, which is exactly why animated transforms did nothing.
+        const out = sampleProps(tracks, 0, 1, 2, true);
+        expect(out.matrix).toEqual([1, 0, 0, 1, 0, 0]);
+        expect(out.transform).toBeUndefined();
+        expect(out.opacity).toBe(1);
+    });
+
+    it('keeps the wire name for the plain-React path', () => {
+        // Plain renders still go through react-native-svg's JS layer, which
+        // reads `transform` and derives `matrix` itself.
+        const out = sampleProps(tracks, 1, 1, 2, false);
+        expect(out.transform).toEqual([1, 0, 0, 1, 9, 9]);
+        expect(out.matrix).toBeUndefined();
+    });
+});

package/src/PxRnMatrix.ts

@@ -0,0 +1,110 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+/**
+ * SVG transform string → 2D affine matrix, in the order react-native-svg's
+ * native side expects: `[a, b, c, d, e, f]`, i.e. SVG's own `matrix(…)` order
+ *
+ * ```
+ *   | a  c  e |
+ *   | b  d  f |
+ *   | 0  0  1 |
+ * ```
+ *
+ * WHY THIS EXISTS: react-native-svg parses a `transform` STRING into this matrix
+ * in JavaScript, inside `extractTransform`, during render. Values delivered
+ * through reanimated's `animatedProps` bypass that JS step and reach the native
+ * view directly, where a raw string is meaningless — an animated transform
+ * simply does nothing. Feeding the matrix instead makes the animated and static
+ * paths agree. (On the web the DOM parses the string itself, which is why this
+ * only shows up on a device.)
+ */
+export type Mat2D = [number, number, number, number, number, number];
+
+export const IDENTITY: Mat2D = [1, 0, 0, 1, 0, 0];
+
+const DEG = Math.PI / 180;
+
+/** `m1 · m2` — apply m2 first, then m1 (same convention as SVG's left-to-right list). */
+function multiply(m1: Mat2D, m2: Mat2D): Mat2D {
+    const [a1, b1, c1, d1, e1, f1] = m1;
+    const [a2, b2, c2, d2, e2, f2] = m2;
+    return [
+        a1 * a2 + c1 * b2,
+        b1 * a2 + d1 * b2,
+        a1 * c2 + c1 * d2,
+        b1 * c2 + d1 * d2,
+        a1 * e2 + c1 * f2 + e1,
+        b1 * e2 + d1 * f2 + f1,
+    ];
+}
+
+/** Splits `translate(1,2)rotate(45)` into `[['translate',[1,2]], ['rotate',[45]]]`. */
+const FN_RE = /([a-zA-Z]+)\s*\(([^)]*)\)/g;
+
+function numbers(raw: string): Array<number> {
+    return raw
+        .split(/[\s,]+/)
+        .filter(s => s.length > 0)
+        .map(Number)
+        .filter(n => Number.isFinite(n));
+}
+
+/**
+ * Parses an SVG transform list. Returns `undefined` when the string contains no
+ * recognisable 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 {
+    let m: Mat2D | undefined;
+    FN_RE.lastIndex = 0;
+
+    let match: RegExpExecArray | null;
+    while ((match = FN_RE.exec(value)) !== null) {
+        const fn = match[1].toLowerCase();
+        const n = numbers(match[2]);
+        let step: Mat2D | undefined;
+
+        switch (fn) {
+            case 'translate':
+                step = [1, 0, 0, 1, n[0] || 0, n[1] || 0];
+                break;
+            case 'scale': {
+                const sx = n[0] ?? 1;
+                const sy = n.length > 1 ? n[1] : sx;
+                step = [sx, 0, 0, sy, 0, 0];
+                break;
+            }
+            case 'rotate': {
+                const rad = (n[0] || 0) * DEG;
+                const cos = Math.cos(rad), sin = Math.sin(rad);
+                const rot: Mat2D = [cos, sin, -sin, cos, 0, 0];
+                if (n.length >= 3) {
+                    // rotate(a, cx, cy) == translate(cx,cy) rotate(a) translate(-cx,-cy)
+                    const cx = n[1], cy = n[2];
+                    step = multiply(multiply([1, 0, 0, 1, cx, cy], rot), [1, 0, 0, 1, -cx, -cy]);
+                } else {
+                    step = rot;
+                }
+                break;
+            }
+            case 'skewx':
+                step = [1, 0, Math.tan((n[0] || 0) * DEG), 1, 0, 0];
+                break;
+            case 'skewy':
+                step = [1, Math.tan((n[0] || 0) * DEG), 0, 1, 0, 0];
+                break;
+            case 'matrix':
+                if (n.length >= 6) step = [n[0], n[1], n[2], n[3], n[4], n[5]];
+                break;
+            default:
+                step = undefined;   // unknown function — ignore it
+        }
+
+        if (step) m = m ? multiply(m, step) : step;
+    }
+
+    return m;
+}

package/src/PxRnPropNames.ts

@@ -4,6 +4,7 @@
  *---------------------------------------------------------------------------------------*/
 
 import { kebabToCamelCaseWord } from '@pixodesk/svg-animator-core';
+import { svgTransformToMatrix } from './PxRnMatrix';
 
 /** Attribute names with a react-native-svg prop equivalent under a
  *  different name (not just a casing change). */
@@ -42,7 +43,26 @@ const LENGTH_LIST_PROPS = new Set(['strokeDasharray']);
  * expects: length-list props become number arrays; numeric strings become
  * numbers; everything else passes through.
  */
-export function toRnPropValue(rnPropName: string, value: string | number): string | number | Array<number> {
+export function toRnPropValue(
+    rnPropName: string,
+    value: string | number,
+    /** The owning element's tag. The ROOT `<Svg>` handles `transform` through a
+     *  different code path (`extractTransformSvgView`, which wants a string or
+     *  an RN style) — a matrix there would be dropped, so leave it alone. */
+    tag?: string,
+    /** Opt in to the NATIVE representation of a value (see below). Defaults to
+     *  off, so web keeps the plain SVG/DOM form it has always been given. */
+    native = false,
+): string | number | Array<number> {
+    // 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
+    // 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);
+        if (m) return m;
+    }
     if (LENGTH_LIST_PROPS.has(rnPropName)) {
         const parts = String(value).trim().replace(/,/g, ' ').split(/\s+/).map(Number).filter(n => Number.isFinite(n));
         // An odd-length dasharray repeats to become even (SVG spec); rn-svg

package/src/PxRnRender.tsx

@@ -5,10 +5,12 @@
 
 import {
     getNormalizedProps,
+    resolveStyle,
     sanitiseAttributeValue,
     DISALLOWED_SVG_TAGS_LOWER,
     TEXT_ATTR,
     TEXT_CONTENT_ATTR,
+    type PxDefs,
     type PxNode,
 } from '@pixodesk/svg-animator-core';
 import { createElement, type ComponentType, type ReactElement, type ReactNode } from 'react';
@@ -18,17 +20,24 @@ import { toRnPropName, toRnPropValue } from './PxRnPropNames';
 export interface RenderRnNodeOptions {
     /** Collects non-fatal issues (unsupported tags, dropped attrs). */
     warnings?: Array<string>;
+    /** `definitions` from the document, used to resolve named `style` presets. */
+    defs?: PxDefs;
     /**
      * Wraps the created element for animated nodes: receives the resolved
      * component + static props and returns the element to mount (the animator
      * substitutes an Animated component wired to its tracks). Return undefined
      * to keep the plain static element.
+     *
+     * `key` is handed over SEPARATELY and is deliberately absent from `props`:
+     * React 19 warns when a props object containing `key` is spread into JSX,
+     * and implementations of this hook do exactly that.
      */
     decorate?: (
         node: PxNode,
         Component: ComponentType<any>,
         props: Record<string, any>,
-        children: ReactNode
+        children: ReactNode,
+        key: string | number | undefined
     ) => ReactElement | undefined;
 }
 
@@ -37,7 +46,7 @@ export interface RenderRnNodeOptions {
  * naming, sanitisation (same security rules as the web renderer), numeric
  * coercion where possible.
  */
-export function toRnProps(props: Record<string, any>, warnings?: Array<string>): Record<string, any> {
+export function toRnProps(props: Record<string, any>, warnings?: Array<string>, tag?: string): Record<string, any> {
     const normalised = getNormalizedProps(props);
     const out: Record<string, any> = {};
     for (const key of Object.keys(normalised)) {
@@ -45,7 +54,7 @@ export function toRnProps(props: Record<string, any>, warnings?: Array<string>):
         if (sanitised === undefined) continue;
         const rnKey = toRnPropName(key);
         if (!rnKey) continue;
-        out[rnKey] = toRnPropValue(rnKey, String(sanitised));
+        out[rnKey] = toRnPropValue(rnKey, String(sanitised), tag);
     }
     return out;
 }
@@ -61,6 +70,12 @@ export function renderRnNode(node: PxNode, opts: RenderRnNodeOptions = {}, key?:
     const { type, children, style, animate, meta, effects, ...props } = node as any;
     const tag = String(type || 'g');
 
+    // `feFuncR/G/B/A` carry their SVG `type` attribute (identity/table/…) under
+    // `funcType`, because the wire format reserves `type` for the node tag.
+    // Restore it as a real prop, mirroring the web renderer.
+    const feFuncType: string | undefined = props.funcType;
+    if (feFuncType !== undefined) delete props.funcType;
+
     if (DISALLOWED_SVG_TAGS_LOWER.has(tag.toLowerCase())) {
         opts.warnings?.push('tag blocked (dangerous): ' + tag);
         return null;
@@ -72,8 +87,24 @@ export function renderRnNode(node: PxNode, opts: RenderRnNodeOptions = {}, key?:
         return null;
     }
 
-    const rnProps = toRnProps(props, opts.warnings);
-    if (key !== undefined) rnProps.key = key;
+    // NB: `key` is never written into this object — see `decorate` above.
+    const rnProps = toRnProps(props, opts.warnings, tag);
+    if (feFuncType !== undefined) rnProps.type = feFuncType;
+
+    // `node.style` — a named preset from `definitions.styles`, or an inline
+    // record. react-native-svg has no CSS, so the resolved declarations are
+    // applied as ordinary props (the same names, e.g. `fill`, `strokeWidth`).
+    // Explicit attributes on the node win over the style block.
+    const resolved = resolveStyle(style, opts.defs);
+    if (resolved) {
+        for (const [k, v] of Object.entries(resolved)) {
+            const rnKey = toRnPropName(k);
+            if (!rnKey || rnKey in rnProps) continue;
+            const sanitised = sanitiseAttributeValue(rnKey, v);
+            if (sanitised === undefined) continue;
+            rnProps[rnKey] = toRnPropValue(rnKey, String(sanitised), tag);
+        }
+    }
 
     // Text content: wire nodes carry it as `text` / `textContent` attr.
     const textContent: string | undefined = props[TEXT_ATTR] || props[TEXT_CONTENT_ATTR];
@@ -81,14 +112,28 @@ export function renderRnNode(node: PxNode, opts: RenderRnNodeOptions = {}, key?:
     let childElements: ReactNode = undefined;
     if (Array.isArray(children) && children.length > 0) {
         childElements = children
-            .map((ch: PxNode, i: number) => renderRnNode(ch, opts, i))
+            .map((ch: PxNode, i: number) => {
+                // One malformed child should cost that child, not the whole tree.
+                try {
+                    return renderRnNode(ch, opts, i);
+                } catch (e) {
+                    opts.warnings?.push('child failed to render: ' + (e instanceof Error ? e.message : String(e)));
+                    return null;
+                }
+            })
             .filter(Boolean);
     } else if (textContent !== undefined) {
         childElements = String(textContent);
     }
 
-    const decorated = opts.decorate?.(node, Component, rnProps, childElements);
+    const decorated = opts.decorate?.(node, Component, rnProps, childElements, key);
     if (decorated !== undefined) return decorated;
 
-    return createElement(Component, rnProps, childElements);
+    // `createElement` takes `key` in its config object — that path does NOT
+    // trigger React's JSX-spread warning.
+    return createElement(
+        Component,
+        key !== undefined ? { ...rnProps, key } : rnProps,
+        childElements
+    );
 }

package/src/PxRnSafety.test.ts

@@ -0,0 +1,118 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+import { describe, expect, it } from 'vitest';
+import type { PxNode } from '@pixodesk/svg-animator-core';
+import { openClosedTextPathTargets } from './PxRnSafety';
+
+/** Doc with one `<textPath>` following a closed circle-ish path. */
+function docWithClosedTarget(): PxNode {
+    return {
+        type: 'svg',
+        children: [
+            { type: 'defs', children: [{ type: 'path', id: 'ring', d: 'M0,0C10,0,10,10,0,10z' }] },
+            {
+                type: 'text',
+                children: [{
+                    type: 'textPath', id: 'tp', href: '#ring', startOffset: 5,
+                    animate: { startOffset: { keyframes: [{ time: 0, value: -20 }, { time: 1000, value: 40 }] } },
+                }],
+            },
+        ],
+    } as unknown as PxNode;
+}
+
+const find = (n: any, pred: (x: any) => boolean): any => {
+    if (pred(n)) return n;
+    for (const c of (n.children ?? [])) { const hit = find(c, pred); if (hit) return hit; }
+    return undefined;
+};
+const all = (n: any, pred: (x: any) => boolean, out: Array<any> = []): Array<any> => {
+    if (pred(n)) out.push(n);
+    for (const c of (n.children ?? [])) all(c, pred, out);
+    return out;
+};
+
+describe('openClosedTextPathTargets', () => {
+    it('repoints the textPath at an OPEN copy of the closed path', () => {
+        const out: any = openClosedTextPathTargets(docWithClosedTarget());
+        const tp = find(out, (n: any) => n.type === 'textPath');
+        const newId = String(tp.href).slice(1);
+
+        expect(newId).not.toBe('ring');
+        const copy = find(out, (n: any) => n.id === newId);
+        expect(copy).toBeDefined();
+        expect(copy.d).toBe('M0,0C10,0,10,10,0,10');   // the `z` is gone
+        expect(copy.d).not.toMatch(/[zZ]/);
+    });
+
+    it('leaves the ORIGINAL path closed, for anything else that draws it', () => {
+        const out: any = openClosedTextPathTargets(docWithClosedTarget());
+        const original = find(out, (n: any) => n.id === 'ring');
+        expect(original.d).toBe('M0,0C10,0,10,10,0,10z');
+    });
+
+    it('puts the copy in <defs> so it is never drawn', () => {
+        const out: any = openClosedTextPathTargets(docWithClosedTarget());
+        const tp = find(out, (n: any) => n.type === 'textPath');
+        const newId = String(tp.href).slice(1);
+        const defs = find(out, (n: any) => n.type === 'defs');
+        expect((defs.children ?? []).some((c: any) => c.id === newId)).toBe(true);
+    });
+
+    it('strips animation from the copy so it cannot animate twice', () => {
+        const doc: any = docWithClosedTarget();
+        doc.children[0].children[0].animate = { d: { keyframes: [] } };
+        const out: any = openClosedTextPathTargets(doc);
+        const tp = find(out, (n: any) => n.type === 'textPath');
+        const copy = find(out, (n: any) => n.id === String(tp.href).slice(1));
+        expect(copy.animate).toBeUndefined();
+    });
+
+    it('makes ONE copy for several textPaths sharing a target', () => {
+        const doc: any = docWithClosedTarget();
+        doc.children[1].children.push({ type: 'textPath', id: 'tp2', href: '#ring' });
+        const out: any = openClosedTextPathTargets(doc);
+
+        const hrefs = all(out, (n: any) => n.type === 'textPath').map((n: any) => n.href);
+        expect(new Set(hrefs).size).toBe(1);
+        expect(all(out, (n: any) => n.type === 'path')).toHaveLength(2);   // original + one copy
+    });
+
+    it('does not touch a textPath already following an OPEN path', () => {
+        const doc: any = docWithClosedTarget();
+        doc.children[0].children[0].d = 'M0,0L10,10';
+        const out: any = openClosedTextPathTargets(doc);
+        expect(find(out, (n: any) => n.type === 'textPath').href).toBe('#ring');
+        expect(all(out, (n: any) => n.type === 'path')).toHaveLength(1);
+    });
+
+    it('returns the very same object when there is no textPath at all', () => {
+        const doc = { type: 'svg', children: [{ type: 'rect' }] } as unknown as PxNode;
+        expect(openClosedTextPathTargets(doc)).toBe(doc);
+    });
+
+    it('reports what it did through the warnings channel', () => {
+        const warnings: Array<string> = [];
+        openClosedTextPathTargets(docWithClosedTarget(), warnings);
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain('#ring');
+    });
+
+    it('handles xlink:href as well as href', () => {
+        const doc: any = docWithClosedTarget();
+        const tp = doc.children[1].children[0];
+        delete tp.href;
+        tp['xlink:href'] = '#ring';
+        const out: any = openClosedTextPathTargets(doc);
+        expect(find(out, (n: any) => n.type === 'textPath')['xlink:href']).not.toBe('#ring');
+    });
+
+    it('ignores a dangling reference instead of throwing', () => {
+        const doc: any = docWithClosedTarget();
+        doc.children[1].children[0].href = '#nope';
+        expect(() => openClosedTextPathTargets(doc)).not.toThrow();
+    });
+});

package/src/PxRnSafety.ts

@@ -0,0 +1,123 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+import { deepClone, generateUniqueId, type PxNode } from '@pixodesk/svg-animator-core';
+
+/**
+ * Workarounds for defects in react-native-svg's NATIVE renderer that would
+ * otherwise take the whole app down.
+ *
+ * These are applied only when the native views are in use — never on the web,
+ * where the DOM handles all of this correctly and the document must be left
+ * exactly as the core pipeline produced it.
+ */
+
+/** True when a path's `d` contains a close-subpath command. */
+function isClosedPath(d: unknown): boolean {
+    return typeof d === 'string' && /[zZ]/.test(d);
+}
+
+/** Drops close-subpath commands, turning a closed outline into an open one. */
+function openPath(d: string): string {
+    return d.replace(/[zZ]/g, '').trimEnd();
+}
+
+/** `#foo` → `foo`. Returns undefined for anything that is not a local ref. */
+function localRef(value: unknown): string | undefined {
+    if (typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    return trimmed.startsWith('#') ? trimmed.slice(1) : undefined;
+}
+
+function forEachNode(node: PxNode | undefined, visit: (n: PxNode, parent?: PxNode) => void, parent?: PxNode): void {
+    if (!node) return;
+    visit(node, parent);
+    for (const child of (node.children ?? [])) forEachNode(child, visit, node);
+}
+
+/**
+ * Gives every `<textPath>` that follows a CLOSED path its own OPEN copy of it.
+ *
+ * WHY: react-native-svg's native text-on-path layout crashes the app —
+ * an uncatchable `NSRangeException` on iOS — for this combination.
+ * `RNSVGTSpan.mm` skips glyphs outside `[startOfRendering, endOfRendering]`,
+ * but for a closed path it sets those bounds to `startOffset … startOffset +
+ * pathLength` instead of `0 … pathLength`. Any glyph past the end of the path
+ * therefore survives the bounds check and reaches `getPosAndTan`, whose
+ * `indexOfObjectPassingTest` returns `NSNotFound` — and indexing the lengths
+ * array with `NSNotFound` throws. A non-zero `startOffset` on a closed path is
+ * all it takes, and animating `startOffset` guarantees hitting it.
+ *
+ * Opening the path restores the `0 … pathLength` bounds, so out-of-range
+ * glyphs are skipped as intended. The copy is private to the `<textPath>`, so
+ * anything else drawing the same path still gets the closed original. For a
+ * shape whose ends already meet (a circle, the usual case) the removed segment
+ * has zero length and nothing changes visually at all.
+ *
+ * Returns the document unchanged — the same object — when nothing matches.
+ */
+export function openClosedTextPathTargets(doc: PxNode, warnings?: Array<string>): PxNode {
+    // Cheap pre-check: the overwhelming majority of documents have no textPath.
+    let hasTextPath = false;
+    forEachNode(doc, n => { if (String(n.type) === 'textPath') hasTextPath = true; });
+    if (!hasTextPath) return doc;
+
+    const result = deepClone(doc);
+
+    const byId = new Map<string, PxNode>();
+    forEachNode(result, n => {
+        const id = (n as any).id;
+        if (typeof id === 'string') byId.set(id, n);
+    });
+
+    /** The copy is a geometry reference, never something to draw — so it goes
+     *  in `<defs>`, alongside the paths textPath targets normally live in. */
+    let defs = (result.children ?? []).find(c => String(c.type) === 'defs');
+    const ensureDefs = (): PxNode => {
+        if (!defs) {
+            defs = { type: 'defs', children: [] } as unknown as PxNode;
+            (result.children ??= []).unshift(defs);
+        }
+        return defs;
+    };
+
+    /** Original path id → id of the open copy, so N textPaths share one copy. */
+    const openCopies = new Map<string, string>();
+
+    forEachNode(result, node => {
+        if (String(node.type) !== 'textPath') return;
+
+        const anyNode = node as any;
+        const attr = anyNode.href !== undefined ? 'href' : 'xlink:href';
+        const targetId = localRef(anyNode[attr]);
+        if (!targetId) return;
+
+        const target = byId.get(targetId);
+        if (!target || !isClosedPath((target as any).d)) return;
+
+        let copyId = openCopies.get(targetId);
+        if (!copyId) {
+            const copy = deepClone(target) as any;
+            copyId = 'px_open_' + generateUniqueId();
+            copy.id = copyId;
+            copy.d = openPath(String(copy.d));
+            // A copy that also carried animation would animate twice; the copy
+            // exists purely as a geometry reference for the text.
+            delete copy.animate;
+            delete copy.effects;
+
+            (ensureDefs().children ??= []).push(copy);
+            openCopies.set(targetId, copyId);
+            warnings?.push(
+                'textPath follows a closed path (#' + targetId + '); using an open copy to ' +
+                'avoid a react-native-svg native crash'
+            );
+        }
+
+        anyNode[attr] = '#' + copyId;
+    });
+
+    return result;
+}