@getrheo/contracts 1.0.0

package/dist/animations.d.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod';
+
+/**
+ * Animation IR — strict-parity, normalized keyframes shared by every
+ * runtime (web sim, native SDK, future exporters).
+ *
+ * Design notes:
+ * - `tracks` are the source of truth: each `KeyframeTrack` is a sorted
+ *   list of `{ t, value }` samples for ONE animatable property. Renderers
+ *   interpolate between samples using the segment's `easing` token.
+ * - All times are normalized 0..1; the clip's authored duration lives in
+ *   `durationMs`. This keeps schema purely numeric and renderer math
+ *   identical (CSS keyframes, Reanimated `withTiming` chains, etc.).
+ * - `triggers`: `mount` (layer appears), `unmount` (layer hides — timed on
+ *   the screen timeline), and legacy `stagger` (migrated to `mount` + delay
+ *   in the builder). Transitions between screens remain `ScreenTransition`.
+ * - Property surface is intentionally narrow ("style tokens only") so
+ *   strict parity holds across web + RN. Adding a property here means
+ *   adding interpreter support in BOTH renderers.
+ */
+declare const ANIMATABLE_PROPERTIES: readonly ["opacity", "translateX", "translateY", "scale"];
+type AnimatableProperty = (typeof ANIMATABLE_PROPERTIES)[number];
+declare const AnimatablePropertySchema: z.ZodEnum<["opacity", "translateX", "translateY", "scale"]>;
+declare const EASING_TOKENS: readonly ["linear", "ease-in", "ease-out", "ease-in-out", "standard", "emphasized"];
+type EasingToken = (typeof EASING_TOKENS)[number];
+declare const EasingTokenSchema: z.ZodEnum<["linear", "ease-in", "ease-out", "ease-in-out", "standard", "emphasized"]>;
+/** A single sample on a property track. */
+declare const KeyframeSchema: z.ZodObject<{
+    t: z.ZodNumber;
+    value: z.ZodNumber;
+    /** Easing applied from this keyframe to the next; defaults to linear. */
+    easing: z.ZodOptional<z.ZodEnum<["linear", "ease-in", "ease-out", "ease-in-out", "standard", "emphasized"]>>;
+}, "strict", z.ZodTypeAny, {
+    value: number;
+    t: number;
+    easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+}, {
+    value: number;
+    t: number;
+    easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+}>;
+type Keyframe = z.infer<typeof KeyframeSchema>;
+declare const KeyframeTrackSchema: z.ZodEffects<z.ZodObject<{
+    property: z.ZodEnum<["opacity", "translateX", "translateY", "scale"]>;
+    keyframes: z.ZodArray<z.ZodObject<{
+        t: z.ZodNumber;
+        value: z.ZodNumber;
+        /** Easing applied from this keyframe to the next; defaults to linear. */
+        easing: z.ZodOptional<z.ZodEnum<["linear", "ease-in", "ease-out", "ease-in-out", "standard", "emphasized"]>>;
+    }, "strict", z.ZodTypeAny, {
+        value: number;
+        t: number;
+        easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+    }, {
+        value: number;
+        t: number;
+        easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    property: "opacity" | "scale" | "translateX" | "translateY";
+    keyframes: {
+        value: number;
+        t: number;
+        easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+    }[];
+}, {
+    property: "opacity" | "scale" | "translateX" | "translateY";
+    keyframes: {
+        value: number;
+        t: number;
+        easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+    }[];
+}>, {
+    property: "opacity" | "scale" | "translateX" | "translateY";
+    keyframes: {
+        value: number;
+        t: number;
+        easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+    }[];
+}, {
+    property: "opacity" | "scale" | "translateX" | "translateY";
+    keyframes: {
+        value: number;
+        t: number;
+        easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+    }[];
+}>;
+type KeyframeTrack = z.infer<typeof KeyframeTrackSchema>;
+declare const ANIMATION_TRIGGERS: readonly ["mount", "stagger", "unmount"];
+type AnimationTrigger = (typeof ANIMATION_TRIGGERS)[number];
+declare const AnimationTriggerSchema: z.ZodEnum<["mount", "stagger", "unmount"]>;
+declare const AnimationClipSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    targetLayerId: z.ZodString;
+    trigger: z.ZodEnum<["mount", "stagger", "unmount"]>;
+    /** Position in the screen's stagger order. Required when trigger is `stagger`. */
+    staggerIndex: z.ZodOptional<z.ZodNumber>;
+    /** Total clip duration in milliseconds (renderer scales 0..1 keyframes by this). */
+    durationMs: z.ZodNumber;
+    /** Pre-roll delay before the clip begins, in ms. Stagger adds on top of this. */
+    delayMs: z.ZodOptional<z.ZodNumber>;
+    tracks: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        property: z.ZodEnum<["opacity", "translateX", "translateY", "scale"]>;
+        keyframes: z.ZodArray<z.ZodObject<{
+            t: z.ZodNumber;
+            value: z.ZodNumber;
+            /** Easing applied from this keyframe to the next; defaults to linear. */
+            easing: z.ZodOptional<z.ZodEnum<["linear", "ease-in", "ease-out", "ease-in-out", "standard", "emphasized"]>>;
+        }, "strict", z.ZodTypeAny, {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }, {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }, {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }>, {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }, {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    durationMs: number;
+    targetLayerId: string;
+    trigger: "mount" | "stagger" | "unmount";
+    tracks: {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }[];
+    delayMs?: number | undefined;
+    staggerIndex?: number | undefined;
+}, {
+    id: string;
+    durationMs: number;
+    targetLayerId: string;
+    trigger: "mount" | "stagger" | "unmount";
+    tracks: {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }[];
+    delayMs?: number | undefined;
+    staggerIndex?: number | undefined;
+}>, {
+    id: string;
+    durationMs: number;
+    targetLayerId: string;
+    trigger: "mount" | "stagger" | "unmount";
+    tracks: {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }[];
+    delayMs?: number | undefined;
+    staggerIndex?: number | undefined;
+}, {
+    id: string;
+    durationMs: number;
+    targetLayerId: string;
+    trigger: "mount" | "stagger" | "unmount";
+    tracks: {
+        property: "opacity" | "scale" | "translateX" | "translateY";
+        keyframes: {
+            value: number;
+            t: number;
+            easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "standard" | "emphasized" | undefined;
+        }[];
+    }[];
+    delayMs?: number | undefined;
+    staggerIndex?: number | undefined;
+}>;
+type AnimationClip = z.infer<typeof AnimationClipSchema>;
+/** Default clip duration when the builder adds mount/unmount animations. */
+declare const DEFAULT_ANIMATION_CLIP_DURATION_MS: 500;
+/**
+ * Default gap between siblings when a screen uses `stagger`. The
+ * renderer multiplies this by `staggerIndex` and adds it to the clip's
+ * `delayMs`. Lives on the screen so authors can dial overall pacing.
+ */
+declare const ScreenStaggerSchema: z.ZodObject<{
+    /** Per-index delay multiplier in ms. */
+    stepMs: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    stepMs: number;
+}, {
+    stepMs: number;
+}>;
+type ScreenStagger = z.infer<typeof ScreenStaggerSchema>;
+
+export { ANIMATABLE_PROPERTIES, ANIMATION_TRIGGERS, type AnimatableProperty, AnimatablePropertySchema, type AnimationClip, AnimationClipSchema, type AnimationTrigger, AnimationTriggerSchema, DEFAULT_ANIMATION_CLIP_DURATION_MS, EASING_TOKENS, type EasingToken, EasingTokenSchema, type Keyframe, KeyframeSchema, type KeyframeTrack, KeyframeTrackSchema, type ScreenStagger, ScreenStaggerSchema };