@unrulysystems/native-motion-core 0.1.0-alpha.0

package/dist/layout/types.cjs

@@ -0,0 +1,36 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// SPEC-LAYOUT §2 — the plain geometric data the projection engine operates on. Host-agnostic: a `Rect` is a
+// bounding box in its projection frame, fed in by the host measurement adapter as plain numbers; `core` never
+// imports a Fabric measure API (REQ-CORE-003). Projection sessions may operate in any caller-chosen coherent
+// frame; layout identity is stricter and accepts only branded common/window-space rects so cross-container
+// FLIP cannot accidentally compare parent-relative coordinates (REQ-LAYOUT-020). A `Transform` is the
+// transform-ONLY correction the substrate executes — translate + scale, no rotation/skew at M1 (the FLIP
+// correction never mutates layout-authoritative style, REQ-LAYOUT-001).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWindowSpaceRect = toWindowSpaceRect;
+const WINDOW_SPACE_RECT = Symbol('WindowSpaceRect');
+function requireFiniteWindowSpaceField(rect, field) {
+    const value = rect[field];
+    if (!Number.isFinite(value)) {
+        throw new Error(`layout identity: window-space rect field '${field}' is ${JSON.stringify(value)}; ` +
+            'a finite number is required before entering the projection registry.');
+    }
+    return value;
+}
+/**
+ * Brand a host-validated common-space measurement for the layoutId registry. Host bindings own the
+ * measurement primitive; core owns the unrepresentable-if-raw registry contract.
+ */
+// alloc-ok: js-thread — measure-commit conversion on the JS side (onLayout path), never per frame.
+function toWindowSpaceRect(rect) {
+    const x = requireFiniteWindowSpaceField(rect, 'x');
+    const y = requireFiniteWindowSpaceField(rect, 'y');
+    const width = requireFiniteWindowSpaceField(rect, 'width');
+    const height = requireFiniteWindowSpaceField(rect, 'height');
+    if (width <= 0 || height <= 0) {
+        throw new Error(`layout identity: window-space rect dimensions must be positive before projection ` +
+            `(width=${width}, height=${height}).`);
+    }
+    return { x, y, width, height };
+}

package/dist/layout/types.d.cts

@@ -0,0 +1,31 @@
+declare const WINDOW_SPACE_RECT: unique symbol;
+/** A host bounding rect (top-left origin) in its projection frame. All units are px. */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A rect already converted into the common layoutId projection frame. */
+export type WindowSpaceRect = Rect & {
+    readonly [WINDOW_SPACE_RECT]: true;
+};
+/**
+ * Brand a host-validated common-space measurement for the layoutId registry. Host bindings own the
+ * measurement primitive; core owns the unrepresentable-if-raw registry contract.
+ */
+export declare function toWindowSpaceRect(rect: Rect): WindowSpaceRect;
+/** A transform-only layout correction (translate + scale about the rect's top-left). No rotation/skew (M1). */
+export interface Transform {
+    readonly translateX: number;
+    readonly translateY: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+}
+/**
+ * A stable layout-identity token — the binding key for a measurement (REQ-LAYOUT-016). NOT a raw host view
+ * tag: Fabric recycles and reuses tags, so identity is carried by this token and re-validated immediately
+ * before a transform applies. Opaque string at M1.
+ */
+export type LayoutIdToken = string;
+export {};

package/dist/layout/types.d.ts

@@ -0,0 +1,31 @@
+declare const WINDOW_SPACE_RECT: unique symbol;
+/** A host bounding rect (top-left origin) in its projection frame. All units are px. */
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A rect already converted into the common layoutId projection frame. */
+export type WindowSpaceRect = Rect & {
+    readonly [WINDOW_SPACE_RECT]: true;
+};
+/**
+ * Brand a host-validated common-space measurement for the layoutId registry. Host bindings own the
+ * measurement primitive; core owns the unrepresentable-if-raw registry contract.
+ */
+export declare function toWindowSpaceRect(rect: Rect): WindowSpaceRect;
+/** A transform-only layout correction (translate + scale about the rect's top-left). No rotation/skew (M1). */
+export interface Transform {
+    readonly translateX: number;
+    readonly translateY: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+}
+/**
+ * A stable layout-identity token — the binding key for a measurement (REQ-LAYOUT-016). NOT a raw host view
+ * tag: Fabric recycles and reuses tags, so identity is carried by this token and re-validated immediately
+ * before a transform applies. Opaque string at M1.
+ */
+export type LayoutIdToken = string;
+export {};

package/dist/layout/types.js

@@ -0,0 +1,35 @@
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// SPEC-LAYOUT §2 — the plain geometric data the projection engine operates on. Host-agnostic: a `Rect` is a
+// bounding box in its projection frame, fed in by the host measurement adapter as plain numbers; `core` never
+// imports a Fabric measure API (REQ-CORE-003). Projection sessions may operate in any caller-chosen coherent
+// frame; layout identity is stricter and accepts only branded common/window-space rects so cross-container
+// FLIP cannot accidentally compare parent-relative coordinates (REQ-LAYOUT-020). A `Transform` is the
+// transform-ONLY correction the substrate executes — translate + scale, no rotation/skew at M1 (the FLIP
+// correction never mutates layout-authoritative style, REQ-LAYOUT-001).
+const WINDOW_SPACE_RECT = Symbol('WindowSpaceRect');
+function requireFiniteWindowSpaceField(rect, field) {
+  'worklet';
+    const value = rect[field];
+    if (!Number.isFinite(value)) {
+        throw new Error(`layout identity: window-space rect field '${field}' is ${JSON.stringify(value)}; ` +
+            'a finite number is required before entering the projection registry.');
+    }
+    return value;
+}
+/**
+ * Brand a host-validated common-space measurement for the layoutId registry. Host bindings own the
+ * measurement primitive; core owns the unrepresentable-if-raw registry contract.
+ */
+// alloc-ok: js-thread — measure-commit conversion on the JS side (onLayout path), never per frame.
+export function toWindowSpaceRect(rect) {
+  'worklet';
+    const x = requireFiniteWindowSpaceField(rect, 'x');
+    const y = requireFiniteWindowSpaceField(rect, 'y');
+    const width = requireFiniteWindowSpaceField(rect, 'width');
+    const height = requireFiniteWindowSpaceField(rect, 'height');
+    if (width <= 0 || height <= 0) {
+        throw new Error(`layout identity: window-space rect dimensions must be positive before projection ` +
+            `(width=${width}, height=${height}).`);
+    }
+    return { x, y, width, height };
+}

package/dist/motion-arc.cjs

@@ -0,0 +1,184 @@
+"use strict";
+// REQ-API-059 — pin-faithful parametric arc (motion-dom animation/utils/arc.ts at 12.42.2).
+// Host-agnostic: atan2 + wrap only. `sampleArcPoint` is the UI-runtime sampler (resolved
+// geometry, no sticky closure). `arc()` holds the auto-direction continuity closure JS-side.
+// `transition.layout.path` is NOT this module (packet F3).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NATIVE_ARC_BRAND = void 0;
+exports.computeArcControlPointInto = computeArcControlPointInto;
+exports.sampleArcPointInto = sampleArcPointInto;
+exports.sampleArcPoint = sampleArcPoint;
+exports.applyPathProgressInto = applyPathProgressInto;
+exports.applyPathProgress = applyPathProgress;
+exports.isNativeArcPath = isNativeArcPath;
+exports.arc = arc;
+exports.NATIVE_ARC_BRAND = '$$nativeMotionArc';
+function wrap180(v) {
+    'worklet';
+    const rangeSize = 360;
+    return ((((v + 180) % rangeSize) + rangeSize) % rangeSize) - 180;
+}
+function bezierPoint(t, origin, control, target) {
+    'worklet';
+    const inv = 1 - t;
+    return inv * inv * origin + 2 * inv * t * control + t * t * target;
+}
+function bezierTangentAngle(t, originX, controlX, targetX, originY, controlY, targetY) {
+    'worklet';
+    const dx = 2 * (1 - t) * (controlX - originX) + 2 * t * (targetX - controlX);
+    const dy = 2 * (1 - t) * (controlY - originY) + 2 * t * (targetY - controlY);
+    return Math.atan2(dy, dx) * (180 / Math.PI);
+}
+/** Frame-path control point: writes the caller-owned `out` slot, allocates nothing. */
+function computeArcControlPointInto(fromX, fromY, toX, toY, strength, peak, out) {
+    'worklet';
+    const deltaX = toX - fromX;
+    const deltaY = toY - fromY;
+    const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+    if (distance > 0) {
+        const normalPerpX = -deltaY / distance;
+        const normalPerpY = deltaX / distance;
+        const desiredHeight = strength * distance;
+        out.x = fromX + deltaX * peak + normalPerpX * desiredHeight;
+        out.y = fromY + deltaY * peak + normalPerpY * desiredHeight;
+        return;
+    }
+    out.x = fromX;
+    out.y = fromY;
+}
+function computeArcControlPoint(fromX, fromY, toX, toY, strength, peak) {
+    'worklet';
+    const out = { x: 0, y: 0 };
+    computeArcControlPointInto(fromX, fromY, toX, toY, strength, peak, out);
+    return out;
+}
+/**
+ * Frame-path sampler: `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot). Writes the
+ * caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+function sampleArcPointInto(t, geometry, out, scratch) {
+    'worklet';
+    const control = scratch.control;
+    computeArcControlPointInto(geometry.fromX, geometry.fromY, geometry.toX, geometry.toY, geometry.signedStrength, geometry.peak, control);
+    const x = bezierPoint(t, geometry.fromX, control.x, geometry.toX);
+    const y = bezierPoint(t, geometry.fromY, control.y, geometry.toY);
+    if (!geometry.rotationScale) {
+        out.x = x;
+        out.y = y;
+        out.rotate = 0;
+        return;
+    }
+    const tangent0 = bezierTangentAngle(0, geometry.fromX, control.x, geometry.toX, geometry.fromY, control.y, geometry.toY);
+    const tangent1 = bezierTangentAngle(1, geometry.fromX, control.x, geometry.toX, geometry.fromY, control.y, geometry.toY);
+    const tangentDelta = wrap180(tangent1 - tangent0);
+    const raw = bezierTangentAngle(t, geometry.fromX, control.x, geometry.toX, geometry.fromY, control.y, geometry.toY);
+    const baseline = tangent0 + tangentDelta * t;
+    out.x = x;
+    out.y = y;
+    out.rotate = wrap180(raw - baseline) * geometry.rotationScale;
+}
+/**
+ * UI-runtime sampler. `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot).
+ * Dual-use: tests + worklet frame step. Function-level worklet tag (JS callers stay valid).
+ * Allocating public twin of `sampleArcPointInto` — off-frame callers only (REQ-DRIVER-021).
+ */
+function sampleArcPoint(t, fromX, fromY, toX, toY, peak, signedStrength, rotationScale) {
+    'worklet';
+    const scratch = { control: { x: 0, y: 0 }, sample: { x: 0, y: 0, rotate: 0 } };
+    const out = { x: 0, y: 0, rotate: 0 };
+    sampleArcPointInto(t, { fromX, fromY, toX, toY, peak, signedStrength, rotationScale }, out, scratch);
+    return out;
+}
+/**
+ * Pin onComplete: snap x/y to target and zero pathRotation. Progress is 0→1000. Frame-path
+ * form: writes the caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+function applyPathProgressInto(progressValue, geometry, done, out, scratch) {
+    'worklet';
+    if (done) {
+        out.x = geometry.toX;
+        out.y = geometry.toY;
+        out.pathRotation = 0;
+        return;
+    }
+    const point = scratch.sample;
+    sampleArcPointInto(progressValue / 1000, geometry, point, scratch);
+    out.x = point.x;
+    out.y = point.y;
+    out.pathRotation = point.rotate;
+}
+/**
+ * Allocating public twin of `applyPathProgressInto` — off-frame callers only (REQ-DRIVER-021);
+ * the UI frame step uses the caller-owned-slot form above.
+ */
+function applyPathProgress(progressValue, geometry, done) {
+    'worklet';
+    const out = { x: 0, y: 0, pathRotation: 0 };
+    const scratch = { control: { x: 0, y: 0 }, sample: { x: 0, y: 0, rotate: 0 } };
+    applyPathProgressInto(progressValue, geometry, done, out, scratch);
+    return out;
+}
+function isNativeArcPath(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[exports.NATIVE_ARC_BRAND] === true &&
+        typeof value.resolve === 'function');
+}
+function rotationScaleOf(rotate) {
+    if (rotate === true)
+        return 1;
+    if (typeof rotate === 'number')
+        return rotate;
+    return 0;
+}
+/**
+ * Public `arc(options)` — reuse the returned value (useMemo / module scope) so the
+ * auto-direction sticky closure survives re-renders, matching the pin.
+ */
+function arc(options = {}) {
+    const strength = options.strength ?? 0.5;
+    const peak = options.peak ?? 0.5;
+    const direction = options.direction;
+    const rotationScale = rotationScaleOf(options.rotate);
+    let prevBulgeSign;
+    const path = {
+        [exports.NATIVE_ARC_BRAND]: true,
+        resolve(from, to) {
+            const dx = to.x - from.x;
+            const dy = to.y - from.y;
+            let signed;
+            if (direction === 'cw')
+                signed = -strength;
+            else if (direction === 'ccw')
+                signed = strength;
+            else {
+                const dom = Math.abs(dx) >= Math.abs(dy) ? dx : dy;
+                signed = dom < 0 ? -strength : strength;
+            }
+            let control = computeArcControlPoint(from.x, from.y, to.x, to.y, signed, peak);
+            if (direction === undefined) {
+                const isVertical = Math.abs(dx) < Math.abs(dy);
+                const midX = from.x + dx * peak;
+                const midY = from.y + dy * peak;
+                const bulgeSign = isVertical ? Math.sign(control.x - midX) : Math.sign(control.y - midY);
+                if (prevBulgeSign !== undefined && bulgeSign !== 0 && bulgeSign !== prevBulgeSign) {
+                    signed = -signed;
+                    control = computeArcControlPoint(from.x, from.y, to.x, to.y, signed, peak);
+                }
+                else if (bulgeSign !== 0) {
+                    prevBulgeSign = bulgeSign;
+                }
+            }
+            return {
+                fromX: from.x,
+                fromY: from.y,
+                toX: to.x,
+                toY: to.y,
+                peak,
+                signedStrength: signed,
+                rotationScale,
+            };
+        },
+    };
+    return path;
+}

package/dist/motion-arc.d.cts

@@ -0,0 +1,78 @@
+export interface ArcOptions {
+    readonly strength?: number;
+    readonly peak?: number;
+    readonly direction?: 'cw' | 'ccw';
+    readonly rotate?: boolean | number;
+}
+export interface ArcPoint {
+    x: number;
+    y: number;
+}
+export interface ArcSample {
+    x: number;
+    y: number;
+    rotate: number;
+}
+export interface PathChannelGeometry {
+    readonly fromX: number;
+    readonly fromY: number;
+    readonly toX: number;
+    readonly toY: number;
+    readonly peak: number;
+    readonly signedStrength: number;
+    readonly rotationScale: number;
+}
+export declare const NATIVE_ARC_BRAND: "$$nativeMotionArc";
+export interface NativeArcPath {
+    readonly [NATIVE_ARC_BRAND]: true;
+    resolve(from: ArcPoint, to: ArcPoint): PathChannelGeometry;
+}
+/**
+ * Caller-owned scratch for the frame-path arc samplers (REQ-DRIVER-021, packet §6
+ * arc-return-records repair): allocated once at the command edge alongside the path record,
+ * reused every frame. `control` carries the quadratic control point; `sample` carries the
+ * intermediate ArcSample between `sampleArcPointInto` and `applyPathProgressInto`.
+ */
+export interface ArcScratch {
+    control: ArcPoint;
+    sample: ArcSample;
+}
+/** The frame-path path-progress output slot — written in place, never returned fresh per frame. */
+export interface PathProgressSample {
+    x: number;
+    y: number;
+    pathRotation: number;
+}
+/** Frame-path control point: writes the caller-owned `out` slot, allocates nothing. */
+export declare function computeArcControlPointInto(fromX: number, fromY: number, toX: number, toY: number, strength: number, peak: number, out: ArcPoint): void;
+/**
+ * Frame-path sampler: `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot). Writes the
+ * caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+export declare function sampleArcPointInto(t: number, geometry: PathChannelGeometry, out: ArcSample, scratch: ArcScratch): void;
+/**
+ * UI-runtime sampler. `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot).
+ * Dual-use: tests + worklet frame step. Function-level worklet tag (JS callers stay valid).
+ * Allocating public twin of `sampleArcPointInto` — off-frame callers only (REQ-DRIVER-021).
+ */
+export declare function sampleArcPoint(t: number, fromX: number, fromY: number, toX: number, toY: number, peak: number, signedStrength: number, rotationScale: number): ArcSample;
+/**
+ * Pin onComplete: snap x/y to target and zero pathRotation. Progress is 0→1000. Frame-path
+ * form: writes the caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+export declare function applyPathProgressInto(progressValue: number, geometry: PathChannelGeometry, done: boolean, out: PathProgressSample, scratch: ArcScratch): void;
+/**
+ * Allocating public twin of `applyPathProgressInto` — off-frame callers only (REQ-DRIVER-021);
+ * the UI frame step uses the caller-owned-slot form above.
+ */
+export declare function applyPathProgress(progressValue: number, geometry: PathChannelGeometry, done: boolean): {
+    x: number;
+    y: number;
+    pathRotation: number;
+};
+export declare function isNativeArcPath(value: unknown): value is NativeArcPath;
+/**
+ * Public `arc(options)` — reuse the returned value (useMemo / module scope) so the
+ * auto-direction sticky closure survives re-renders, matching the pin.
+ */
+export declare function arc(options?: ArcOptions): NativeArcPath;

package/dist/motion-arc.d.ts

@@ -0,0 +1,78 @@
+export interface ArcOptions {
+    readonly strength?: number;
+    readonly peak?: number;
+    readonly direction?: 'cw' | 'ccw';
+    readonly rotate?: boolean | number;
+}
+export interface ArcPoint {
+    x: number;
+    y: number;
+}
+export interface ArcSample {
+    x: number;
+    y: number;
+    rotate: number;
+}
+export interface PathChannelGeometry {
+    readonly fromX: number;
+    readonly fromY: number;
+    readonly toX: number;
+    readonly toY: number;
+    readonly peak: number;
+    readonly signedStrength: number;
+    readonly rotationScale: number;
+}
+export declare const NATIVE_ARC_BRAND: "$$nativeMotionArc";
+export interface NativeArcPath {
+    readonly [NATIVE_ARC_BRAND]: true;
+    resolve(from: ArcPoint, to: ArcPoint): PathChannelGeometry;
+}
+/**
+ * Caller-owned scratch for the frame-path arc samplers (REQ-DRIVER-021, packet §6
+ * arc-return-records repair): allocated once at the command edge alongside the path record,
+ * reused every frame. `control` carries the quadratic control point; `sample` carries the
+ * intermediate ArcSample between `sampleArcPointInto` and `applyPathProgressInto`.
+ */
+export interface ArcScratch {
+    control: ArcPoint;
+    sample: ArcSample;
+}
+/** The frame-path path-progress output slot — written in place, never returned fresh per frame. */
+export interface PathProgressSample {
+    x: number;
+    y: number;
+    pathRotation: number;
+}
+/** Frame-path control point: writes the caller-owned `out` slot, allocates nothing. */
+export declare function computeArcControlPointInto(fromX: number, fromY: number, toX: number, toY: number, strength: number, peak: number, out: ArcPoint): void;
+/**
+ * Frame-path sampler: `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot). Writes the
+ * caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+export declare function sampleArcPointInto(t: number, geometry: PathChannelGeometry, out: ArcSample, scratch: ArcScratch): void;
+/**
+ * UI-runtime sampler. `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot).
+ * Dual-use: tests + worklet frame step. Function-level worklet tag (JS callers stay valid).
+ * Allocating public twin of `sampleArcPointInto` — off-frame callers only (REQ-DRIVER-021).
+ */
+export declare function sampleArcPoint(t: number, fromX: number, fromY: number, toX: number, toY: number, peak: number, signedStrength: number, rotationScale: number): ArcSample;
+/**
+ * Pin onComplete: snap x/y to target and zero pathRotation. Progress is 0→1000. Frame-path
+ * form: writes the caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+export declare function applyPathProgressInto(progressValue: number, geometry: PathChannelGeometry, done: boolean, out: PathProgressSample, scratch: ArcScratch): void;
+/**
+ * Allocating public twin of `applyPathProgressInto` — off-frame callers only (REQ-DRIVER-021);
+ * the UI frame step uses the caller-owned-slot form above.
+ */
+export declare function applyPathProgress(progressValue: number, geometry: PathChannelGeometry, done: boolean): {
+    x: number;
+    y: number;
+    pathRotation: number;
+};
+export declare function isNativeArcPath(value: unknown): value is NativeArcPath;
+/**
+ * Public `arc(options)` — reuse the returned value (useMemo / module scope) so the
+ * auto-direction sticky closure survives re-renders, matching the pin.
+ */
+export declare function arc(options?: ArcOptions): NativeArcPath;

package/dist/motion-arc.js

@@ -0,0 +1,183 @@
+// REQ-API-059 — pin-faithful parametric arc (motion-dom animation/utils/arc.ts at 12.42.2).
+// Host-agnostic: atan2 + wrap only. `sampleArcPoint` is the UI-runtime sampler (resolved
+// geometry, no sticky closure). `arc()` holds the auto-direction continuity closure JS-side.
+// `transition.layout.path` is NOT this module (packet F3).
+export const NATIVE_ARC_BRAND = '$$nativeMotionArc';
+function wrap180(v) {
+  'worklet';
+    'worklet';
+    const rangeSize = 360;
+    return ((((v + 180) % rangeSize) + rangeSize) % rangeSize) - 180;
+}
+function bezierPoint(t, origin, control, target) {
+  'worklet';
+    'worklet';
+    const inv = 1 - t;
+    return inv * inv * origin + 2 * inv * t * control + t * t * target;
+}
+function bezierTangentAngle(t, originX, controlX, targetX, originY, controlY, targetY) {
+  'worklet';
+    'worklet';
+    const dx = 2 * (1 - t) * (controlX - originX) + 2 * t * (targetX - controlX);
+    const dy = 2 * (1 - t) * (controlY - originY) + 2 * t * (targetY - controlY);
+    return Math.atan2(dy, dx) * (180 / Math.PI);
+}
+/** Frame-path control point: writes the caller-owned `out` slot, allocates nothing. */
+export function computeArcControlPointInto(fromX, fromY, toX, toY, strength, peak, out) {
+  'worklet';
+    'worklet';
+    const deltaX = toX - fromX;
+    const deltaY = toY - fromY;
+    const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+    if (distance > 0) {
+        const normalPerpX = -deltaY / distance;
+        const normalPerpY = deltaX / distance;
+        const desiredHeight = strength * distance;
+        out.x = fromX + deltaX * peak + normalPerpX * desiredHeight;
+        out.y = fromY + deltaY * peak + normalPerpY * desiredHeight;
+        return;
+    }
+    out.x = fromX;
+    out.y = fromY;
+}
+function computeArcControlPoint(fromX, fromY, toX, toY, strength, peak) {
+  'worklet';
+    'worklet';
+    const out = { x: 0, y: 0 };
+    computeArcControlPointInto(fromX, fromY, toX, toY, strength, peak, out);
+    return out;
+}
+/**
+ * Frame-path sampler: `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot). Writes the
+ * caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+export function sampleArcPointInto(t, geometry, out, scratch) {
+  'worklet';
+    'worklet';
+    const control = scratch.control;
+    computeArcControlPointInto(geometry.fromX, geometry.fromY, geometry.toX, geometry.toY, geometry.signedStrength, geometry.peak, control);
+    const x = bezierPoint(t, geometry.fromX, control.x, geometry.toX);
+    const y = bezierPoint(t, geometry.fromY, control.y, geometry.toY);
+    if (!geometry.rotationScale) {
+        out.x = x;
+        out.y = y;
+        out.rotate = 0;
+        return;
+    }
+    const tangent0 = bezierTangentAngle(0, geometry.fromX, control.x, geometry.toX, geometry.fromY, control.y, geometry.toY);
+    const tangent1 = bezierTangentAngle(1, geometry.fromX, control.x, geometry.toX, geometry.fromY, control.y, geometry.toY);
+    const tangentDelta = wrap180(tangent1 - tangent0);
+    const raw = bezierTangentAngle(t, geometry.fromX, control.x, geometry.toX, geometry.fromY, control.y, geometry.toY);
+    const baseline = tangent0 + tangentDelta * t;
+    out.x = x;
+    out.y = y;
+    out.rotate = wrap180(raw - baseline) * geometry.rotationScale;
+}
+/**
+ * UI-runtime sampler. `t` is progress/1000 and MAY exceed [0, 1] (spring overshoot).
+ * Dual-use: tests + worklet frame step. Function-level worklet tag (JS callers stay valid).
+ * Allocating public twin of `sampleArcPointInto` — off-frame callers only (REQ-DRIVER-021).
+ */
+export function sampleArcPoint(t, fromX, fromY, toX, toY, peak, signedStrength, rotationScale) {
+  'worklet';
+    'worklet';
+    const scratch = { control: { x: 0, y: 0 }, sample: { x: 0, y: 0, rotate: 0 } };
+    const out = { x: 0, y: 0, rotate: 0 };
+    sampleArcPointInto(t, { fromX, fromY, toX, toY, peak, signedStrength, rotationScale }, out, scratch);
+    return out;
+}
+/**
+ * Pin onComplete: snap x/y to target and zero pathRotation. Progress is 0→1000. Frame-path
+ * form: writes the caller-owned `out`/`scratch` slots, allocating nothing (REQ-DRIVER-021).
+ */
+export function applyPathProgressInto(progressValue, geometry, done, out, scratch) {
+  'worklet';
+    'worklet';
+    if (done) {
+        out.x = geometry.toX;
+        out.y = geometry.toY;
+        out.pathRotation = 0;
+        return;
+    }
+    const point = scratch.sample;
+    sampleArcPointInto(progressValue / 1000, geometry, point, scratch);
+    out.x = point.x;
+    out.y = point.y;
+    out.pathRotation = point.rotate;
+}
+/**
+ * Allocating public twin of `applyPathProgressInto` — off-frame callers only (REQ-DRIVER-021);
+ * the UI frame step uses the caller-owned-slot form above.
+ */
+export function applyPathProgress(progressValue, geometry, done) {
+  'worklet';
+    'worklet';
+    const out = { x: 0, y: 0, pathRotation: 0 };
+    const scratch = { control: { x: 0, y: 0 }, sample: { x: 0, y: 0, rotate: 0 } };
+    applyPathProgressInto(progressValue, geometry, done, out, scratch);
+    return out;
+}
+export function isNativeArcPath(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[NATIVE_ARC_BRAND] === true &&
+        typeof value.resolve === 'function');
+}
+function rotationScaleOf(rotate) {
+    if (rotate === true)
+        return 1;
+    if (typeof rotate === 'number')
+        return rotate;
+    return 0;
+}
+/**
+ * Public `arc(options)` — reuse the returned value (useMemo / module scope) so the
+ * auto-direction sticky closure survives re-renders, matching the pin.
+ */
+export function arc(options = {}) {
+    const strength = options.strength ?? 0.5;
+    const peak = options.peak ?? 0.5;
+    const direction = options.direction;
+    const rotationScale = rotationScaleOf(options.rotate);
+    let prevBulgeSign;
+    const path = {
+        [NATIVE_ARC_BRAND]: true,
+        resolve(from, to) {
+            const dx = to.x - from.x;
+            const dy = to.y - from.y;
+            let signed;
+            if (direction === 'cw')
+                signed = -strength;
+            else if (direction === 'ccw')
+                signed = strength;
+            else {
+                const dom = Math.abs(dx) >= Math.abs(dy) ? dx : dy;
+                signed = dom < 0 ? -strength : strength;
+            }
+            let control = computeArcControlPoint(from.x, from.y, to.x, to.y, signed, peak);
+            if (direction === undefined) {
+                const isVertical = Math.abs(dx) < Math.abs(dy);
+                const midX = from.x + dx * peak;
+                const midY = from.y + dy * peak;
+                const bulgeSign = isVertical ? Math.sign(control.x - midX) : Math.sign(control.y - midY);
+                if (prevBulgeSign !== undefined && bulgeSign !== 0 && bulgeSign !== prevBulgeSign) {
+                    signed = -signed;
+                    control = computeArcControlPoint(from.x, from.y, to.x, to.y, signed, peak);
+                }
+                else if (bulgeSign !== 0) {
+                    prevBulgeSign = bulgeSign;
+                }
+            }
+            return {
+                fromX: from.x,
+                fromY: from.y,
+                toX: to.x,
+                toY: to.y,
+                peak,
+                signedStrength: signed,
+                rotationScale,
+            };
+        },
+    };
+    return path;
+}