@appinternalleads/ui 0.3.0 → 0.4.1

package/src/motion/cat/animation.ts

@@ -0,0 +1,206 @@
+import type { CatConfig, EasingName } from './config';
+import { EASING_NAMES } from './config';
+import { TAIL_BONE_IDS, type TailPose } from './rig';
+
+/**
+ * **The animation model** — keyframes as JSON, independent of any renderer.
+ *
+ *   manipulation model (CatConfig) → buildAnimationDocument → CatAnimationDocument (JSON)
+ *                                                         → catPose(config, timeMs, doc) → renderers
+ *
+ * A track moves ONE property of ONE rig node; `t` is a fraction of the animation's duration (0 … 1)
+ * and `value` is added on top of the config (degrees for rotate, artboard units for x/y, a scale
+ * delta for scale). Every sample is a pure function of time — no clocks, no requestAnimationFrame —
+ * so Remotion renders any frame deterministically and the editor's preview plays the same numbers.
+ */
+export const CAT_ANIMATION_SCHEMA = 'cat-rig-animation/1';
+
+/** What a track may target: the tail bones, and the groups of the rig. */
+export const ANIMATION_TARGETS = {
+  ...Object.fromEntries(TAIL_BONE_IDS.map((id) => [id, ['rotate']])),
+  'cat-tail': ['rotate', 'x', 'y', 'scale'],
+  'cat-head': ['rotate'],
+  'cat-body': ['x', 'y'],
+  cat: ['rotate', 'x', 'y', 'scale'],
+} as Record<string, readonly AnimatedProperty[]>;
+export type AnimatedProperty = 'rotate' | 'x' | 'y' | 'scale';
+
+export type CatKeyframe = { t: number; value: number };
+export type CatTrack = { id: string; property: AnimatedProperty; keyframes: CatKeyframe[] };
+export type CatAnimation = {
+  /** One cycle, in ms (speed already applied). */
+  duration: number;
+  loop: boolean;
+  easing: EasingName;
+  /** One track per rig node and property ("segments", as the tail's bones are its segments). */
+  segments: CatTrack[];
+};
+export type CatAnimationDocument = {
+  schema: typeof CAT_ANIMATION_SCHEMA;
+  asset: 'cat';
+  animations: Record<string, CatAnimation>;
+};
+
+/* ---------- easing ---------- */
+const EASE: Record<Exclude<EasingName, 'spline'>, (t: number) => number> = {
+  linear: (t) => t,
+  easeIn: (t) => t * t * t,
+  easeOut: (t) => 1 - (1 - t) ** 3,
+  easeInOut: (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
+  sineInOut: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+};
+
+/** A track's value at u ∈ [0, 1]. `spline` is a cubic Hermite (Catmull-Rom) through the keyframes: it never stops between them. */
+export function sampleTrack(keyframes: CatKeyframe[], u: number, easing: EasingName, loop: boolean): number {
+  const k = keyframes;
+  if (!k.length) return 0;
+  if (u <= k[0]!.t) return k[0]!.value;
+  const last = k[k.length - 1]!; // not .at(-1): iOS Safari before 15.4 lacks it
+  if (u >= last.t) return last.value;
+  let i = 0;
+  while (i < k.length - 2 && u > k[i + 1]!.t) i++;
+  const a = k[i]!, b = k[i + 1]!;
+  const span = b.t - a.t;
+  const f = span > 0 ? (u - a.t) / span : 1;
+  if (easing !== 'spline') return a.value + (b.value - a.value) * EASE[easing](f);
+  /* Tangents from the neighbours; a looping track wraps round (its last keyframe is its first). */
+  const at = (j: number): CatKeyframe => {
+    if (j >= 0 && j < k.length) return k[j]!;
+    if (!loop) return k[Math.max(0, Math.min(k.length - 1, j))]!;
+    return j < 0 ? { t: k[k.length - 1 + j]!.t - 1, value: k[k.length - 1 + j]!.value } : { t: k[j - k.length + 1]!.t + 1, value: k[j - k.length + 1]!.value };
+  };
+  const tangent = (j: number) => {
+    const p = at(j - 1), n = at(j + 1);
+    return n.t === p.t ? 0 : (n.value - p.value) / (n.t - p.t);
+  };
+  const m0 = tangent(i) * span, m1 = tangent(i + 1) * span;
+  const f2 = f * f, f3 = f2 * f;
+  return (2 * f3 - 3 * f2 + 1) * a.value + (f3 - 2 * f2 + f) * m0 + (-2 * f3 + 3 * f2) * b.value + (f3 - f2) * m1;
+}
+
+/** Where in its cycle an animation is at `timeMs`: loops wrap, one-shots hold their last keyframe. */
+export const progress = (anim: CatAnimation, timeMs: number): number =>
+  anim.loop ? (((timeMs % anim.duration) + anim.duration) % anim.duration) / anim.duration : Math.max(0, Math.min(1, timeMs / anim.duration));
+
+/** Every track's value at `timeMs`, keyed `${id}.${property}`, summed over the given animations. */
+export function sampleAnimations(doc: CatAnimationDocument, timeMs: number, names = Object.keys(doc.animations)): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const name of names) {
+    const anim = doc.animations[name];
+    if (!anim) continue;
+    const u = progress(anim, timeMs);
+    for (const track of anim.segments) {
+      const key = `${track.id}.${track.property}`;
+      out[key] = (out[key] ?? 0) + sampleTrack(track.keyframes, u, anim.easing, anim.loop);
+    }
+  }
+  return out;
+}
+
+/* ---------- the tail wiggle, built from the config ---------- */
+/** How much of the tip's bend each bone takes, root → tip: the base of a tail barely moves, the end moves most. */
+export const WIGGLE_PROFILE = [0.25, 0.4, 0.6, 0.8, 1] as const;
+const r3 = (v: number) => Math.round(v * 1000) / 1000;
+
+/**
+ * The tail wiggle: every bone goes rest → right → rest → left → rest over one cycle, the tip bone by
+ * `amount`, the others by less (WIGGLE_PROFILE). With follow-through each bone reaches its peaks a
+ * little after its parent — a wave travelling down the tail — while every bone still starts and ends
+ * the cycle at 0, so the cycle starts from the rest pose and loops without a seam.
+ */
+export function buildTailWiggle(tail: CatConfig['tail']): CatAnimation {
+  const n = TAIL_BONE_IDS.length;
+  return {
+    duration: Math.round(tail.duration / tail.speed),
+    loop: tail.loop,
+    easing: tail.easing,
+    segments: TAIL_BONE_IDS.map((id, i) => {
+      const lag = (tail.followThrough * i) / (n - 1);
+      const a = r3(tail.amount * WIGGLE_PROFILE[i]!);
+      return {
+        id, property: 'rotate' as const,
+        keyframes: [
+          { t: 0, value: 0 },
+          { t: r3(0.25 + lag), value: a },
+          { t: r3(0.5 + lag), value: 0 },
+          { t: r3(0.75 + lag), value: -a },
+          { t: 1, value: 0 },
+        ],
+      };
+    }),
+  };
+}
+
+/** The animation model for a config: what "Export Animation" writes and what the renderers sample. */
+export function buildAnimationDocument(config: CatConfig): CatAnimationDocument {
+  const animations: Record<string, CatAnimation> = {};
+  if (config.tail.enabled && config.tail.wiggle && config.tail.amount > 0) animations.tailWiggle = buildTailWiggle(config.tail);
+  return { schema: CAT_ANIMATION_SCHEMA, asset: 'cat', animations };
+}
+
+/** Every problem with an animation document (imported JSON, Remotion props), by path. */
+export function validateAnimationDocument(input: unknown): { path: string; message: string }[] {
+  const errors: { path: string; message: string }[] = [];
+  const doc = input as Partial<CatAnimationDocument> | null;
+  if (!doc || typeof doc !== 'object') return [{ path: '', message: 'expected an object' }];
+  if (doc.schema !== CAT_ANIMATION_SCHEMA) errors.push({ path: 'schema', message: `expected "${CAT_ANIMATION_SCHEMA}"` });
+  if (doc.asset !== 'cat') errors.push({ path: 'asset', message: 'expected "cat"' });
+  if (!doc.animations || typeof doc.animations !== 'object') return [...errors, { path: 'animations', message: 'expected an object' }];
+  for (const [name, a] of Object.entries(doc.animations)) {
+    const p = `animations.${name}`;
+    if (!(typeof a.duration === 'number' && a.duration > 0)) errors.push({ path: `${p}.duration`, message: 'expected a positive number of ms' });
+    if (typeof a.loop !== 'boolean') errors.push({ path: `${p}.loop`, message: 'expected true or false' });
+    if (!EASING_NAMES.includes(a.easing)) errors.push({ path: `${p}.easing`, message: `expected one of ${EASING_NAMES.join(', ')}` });
+    if (!Array.isArray(a.segments)) { errors.push({ path: `${p}.segments`, message: 'expected an array' }); continue; }
+    a.segments.forEach((s, i) => {
+      const sp = `${p}.segments[${i}]`;
+      const props = ANIMATION_TARGETS[s.id];
+      if (!props) errors.push({ path: `${sp}.id`, message: `unknown target; targets are ${Object.keys(ANIMATION_TARGETS).join(', ')}` });
+      else if (!props.includes(s.property)) errors.push({ path: `${sp}.property`, message: `${s.id} animates ${props.join(', ')}` });
+      if (!Array.isArray(s.keyframes) || !s.keyframes.length) errors.push({ path: `${sp}.keyframes`, message: 'expected at least one keyframe' });
+      else s.keyframes.forEach((k, j) => {
+        if (!(typeof k.t === 'number' && k.t >= 0 && k.t <= 1) || (j > 0 && k.t < s.keyframes[j - 1]!.t)) errors.push({ path: `${sp}.keyframes[${j}].t`, message: 'expected 0 … 1, in order' });
+        if (!(typeof k.value === 'number' && Number.isFinite(k.value))) errors.push({ path: `${sp}.keyframes[${j}].value`, message: 'expected a number' });
+      });
+    });
+  }
+  return errors;
+}
+
+/* ---------- config + animation → pose ---------- */
+export type CatPose = {
+  transform: CatConfig['transform'];
+  body: CatConfig['body'];
+  head: CatConfig['head'];
+  tail: { visible: boolean; x: number; y: number; rotate: number; scale: number; origin: { x: number; y: number }; bones: TailPose };
+};
+
+/**
+ * The pose at `timeMs`: the config's values plus whatever the animation document adds. `doc` defaults
+ * to the one the config builds, so `catPose(config, t)` is the whole pipeline in one call.
+ */
+export function catPose(config: CatConfig, timeMs = 0, doc: CatAnimationDocument = buildAnimationDocument(config)): CatPose {
+  const a = sampleAnimations(doc, timeMs);
+  const add = (id: string, prop: AnimatedProperty) => a[`${id}.${prop}`] ?? 0;
+  const bones: TailPose = {};
+  for (const id of TAIL_BONE_IDS) bones[id] = (config.tail.pose[id] ?? 0) + add(id, 'rotate');
+  return {
+    transform: {
+      x: config.transform.x + add('cat', 'x'), y: config.transform.y + add('cat', 'y'),
+      scale: config.transform.scale + add('cat', 'scale'), rotate: config.transform.rotate + add('cat', 'rotate'),
+    },
+    body: { x: config.body.x + add('cat-body', 'x'), y: config.body.y + add('cat-body', 'y') },
+    head: { rotate: config.head.rotate + add('cat-head', 'rotate') },
+    tail: {
+      visible: config.tail.enabled,
+      x: config.tail.x + add('cat-tail', 'x'), y: config.tail.y + add('cat-tail', 'y'),
+      rotate: config.tail.rotate + add('cat-tail', 'rotate'), scale: config.tail.scale + add('cat-tail', 'scale'),
+      origin: config.tail.origin,
+      bones,
+    },
+  };
+}
+
+/** Length of one full pass of every animation in the document (the longest), in ms — 0 when there are none. */
+export const documentDuration = (doc: CatAnimationDocument): number =>
+  Math.max(0, ...Object.values(doc.animations).map((a) => a.duration));

package/src/motion/cat/art.generated.ts

@@ -0,0 +1,44 @@
+/* eslint-disable comppack/no-raw-colour -- generated vector artwork: the measured source palette. */
+/**
+ * GENERATED by tools/cat-rig/eps-to-svg.mjs from Vecteezy asset 47078283 — do not edit by hand.
+ * Cat artwork: Vecteezy.com (asset 47078283, “silhouette cat logo design”). Free License: attribution to Vecteezy.com required.
+ * Coordinates are the EPS artboard's (4000 × 4000, y down). docs/CAT-RIG.md.
+ */
+export type PathCommand = ['M', number, number] | ['L', number, number] | ['C', number, number, number, number, number, number] | ['Z'];
+
+export const CAT_CREDIT = "Cat artwork: Vecteezy.com (asset 47078283, “silhouette cat logo design”). Free License: attribution to Vecteezy.com required.";
+export const CAT_ARTBOARD = {"width":4000,"height":4000} as const;
+/** The artwork's bounds plus 240 units of margin, in artboard units. */
+export const CAT_VIEWBOX = {"x":484,"y":6,"width":3022,"height":3991} as const;
+/** Colours measured from the source JPG (the EPS is CMYK). */
+export const CAT_SOURCE_PALETTE = {"fur":"#020202","detail":"#fafbfd","background":"#bfdbcd"} as const;
+
+/** The unsplit silhouette exactly as converted — the reference the rest pose is checked against. */
+export const SILHOUETTE_D = "M2799.52 246.98C2803.92 248 2808.56 249.71 2812.48 251.96C2839.71 267.59 2855.14 317.32 2865.41 345.21C2894.72 424.83 2921.75 500.85 2931.92 585.56C2935.19 612.79 2937.23 640.27 2938.69 667.64C2940.44 700.17 2937.47 739.92 2948.2 770.49C2955.57 791.51 2968.25 811.51 2977.16 832.09C3009.33 906.45 3039.15 977.74 3053.62 1057.88C3060.92 1098.31 3066.12 1139.08 3068.29 1180.12C3071 1231.45 3068.52 1283.04 3082.67 1332.98C3096.76 1382.66 3121 1430 3144.11 1475.96C3206.87 1600.72 3266.3 1720.9 3257.48 1865.17C3254.43 1915.11 3248.14 1969.79 3230.66 2016.73C3223.37 2036.3 3210.74 2054.24 3204.94 2074.23C3199.42 2093.23 3196.24 2113.47 3191.87 2132.81C3185.68 2160.15 3178.21 2186.78 3169.93 2213.55C3155.4 2260.58 3140.81 2307.83 3124.27 2354.2C3106.99 2402.68 3087.78 2450 3071.99 2499.11C3016.55 2671.53 2913.07 3233.13 2953.81 3400.21C2978.93 3503.21 3045.07 3451.05 3105.73 3488.85C3138.23 3509.1 3162.29 3547.66 3170.76 3584.56C3174.6 3601.25 3176.18 3620.01 3166.07 3634.88C3151.43 3656.4 3121.62 3659.23 3098.05 3663.13L3096.39 3661.12C3099.52 3638.63 3098.81 3616.19 3086.05 3596.56L3084.34 3593.97C3079.78 3586.98 3075.37 3581.5 3069.27 3575.78C3068.02 3577.79 3070.56 3579.08 3071.83 3580.73C3082.07 3593.94 3088.11 3607.69 3091.4 3624.04C3093.85 3636.17 3096.02 3650.49 3088.88 3661.32C3073 3671.58 2968.11 3671.07 2943.7 3670.86C2936.15 3641.12 2921.45 3614.84 2901.35 3591.71C2867.65 3552.96 2837.74 3537.4 2786.48 3533.78C2779.32 3515.24 2772.55 3496.73 2767.54 3477.47C2761.18 3453.01 2756.89 3426.79 2747.38 3403.32C2738.39 3381.13 2719 3366.46 2714.35 3341.57C2707.38 3304.28 2717.36 3264.7 2720.63 3227.32C2723.21 3197.89 2724.22 3168.22 2724.1 3138.68C2723.64 3022.85 2711.17 2906.9 2699.86 2791.71C2686.83 2843.15 2657.32 2903.82 2633.88 2952.01C2627.17 2812.54 2627.96 2672.99 2661.7 2536.56C2671.92 2495.21 2686.37 2455.78 2698.95 2415.19C2698.56 2415.86 2698.15 2416.52 2697.79 2417.2C2682.31 2445.82 2672.58 2482.19 2663.58 2513.47C2637.89 2602.79 2624.63 2693.84 2619.02 2786.52C2613.7 2874.42 2618.05 2964.3 2624.76 3052.03C2633.77 3169.9 2646.23 3287.35 2681.88 3400.67C2696.04 3445.71 2723.92 3530.62 2779.13 3538.85C2799.54 3541.89 2820.92 3539.97 2839.63 3550.35C2880.27 3572.9 2923.59 3619.06 2935.36 3664.98C2939.38 3680.69 2940.55 3697.79 2931.41 3712.01C2918.17 3732.59 2886.55 3736.98 2864.38 3742.43C2870.54 3720.54 2872.06 3697.91 2864.1 3676.17C2861.2 3668.25 2855.03 3655.15 2847.14 3651.31C2850.86 3656.7 2853.96 3663.17 2857 3668.99C2869.5 3692.95 2866.74 3717.79 2858.92 3742.6C2833.54 3748.7 2806.71 3749.63 2780.75 3751.53C2783.73 3738.66 2785.49 3725.41 2783.13 3712.28C2779.77 3693.67 2767.25 3672.96 2751.58 3662.03C2751.13 3663.17 2773.86 3691.75 2777.79 3704.54C2781.25 3715.76 2783.02 3735.15 2776.06 3745.49C2773.23 3749.7 2768.63 3751.44 2763.82 3752.08C2725.82 3757.1 2637.37 3741.57 2607.01 3716.13C2589.85 3701.75 2590.45 3684.55 2588.23 3663.96C2571.89 3643.85 2549.36 3629.7 2533.62 3608.74C2487.51 3547.32 2454.67 3419.16 2432.53 3344.03C2390.56 3387.86 2356.9 3436.35 2310.6 3476.58C2250.96 3467.72 2182.82 3477.44 2128.02 3503.48C2142.67 3503.56 2173.84 3490 2190.1 3485.76C2215.49 3479.16 2243.82 3475.81 2270.01 3475.7C2321.55 3475.47 2369.99 3499.11 2405.98 3535.38C2428.98 3558.57 2446.8 3585.9 2446.16 3619.86C2445.67 3646.37 2434.76 3664.89 2416.06 3682.55C2417.28 3676.39 2418.59 3670.12 2419.08 3663.85C2420.58 3645.07 2416.39 3622.9 2403.92 3608C2408.67 3620.46 2415.12 3634.35 2415.46 3647.8C2415.49 3648.86 2415.45 3649.93 2415.45 3651C2415.48 3661.35 2414.51 3671.52 2408.32 3680.22C2394.21 3700.06 2355.96 3702.77 2333.61 3707.18C2345.25 3691.29 2351.29 3673.63 2348.86 3653.76C2345.43 3625.69 2327.11 3606.14 2306.14 3589.27L2306.7 3590.31C2308.63 3590.52 2307.61 3590.18 2309.54 3591.78L2308.85 3592.9C2322.54 3607.76 2336.34 3621.76 2342.17 3641.77C2349.35 3666.41 2340.37 3685.66 2328.78 3706.77C2281.82 3712 2234.42 3711.83 2187.23 3712.03C2115.01 3712.34 2043.45 3711.1 1971.35 3706.26C1900.41 3701.49 1830.62 3692.81 1760.16 3683.83C1723.4 3679.14 1683.95 3676.99 1648.51 3666.09C1628.3 3659.87 1605.69 3649.72 1591.85 3633.25C1564.14 3600.3 1575 3564.64 1578.07 3526.27C1511.31 3529.58 1447.02 3531.45 1380.55 3522.66C1185.03 3496.81 992.6 3392.35 872.38 3234.96C771.19 3102.49 724.48 2936.65 747.35 2771.22C780.59 2530.86 942.02 2370.2 1126.85 2230.18C1180.53 2189.93 1229.3 2139.69 1263.33 2081.57C1291.87 2032.82 1311.83 1971.3 1296.47 1914.92C1281.69 1860.66 1235.41 1809.66 1187.19 1782.31C1153.2 1763.04 1114.72 1756.76 1076.76 1767.52C1043.57 1776.93 1009.94 1801.06 993.75 1831.99C988.53 1841.96 986.15 1853.22 987.01 1864.45C991.41 1921.87 1077.88 1922.52 1091.47 1967.9C1093.19 1973.65 1093 1978.42 1089.94 1983.74C1083.97 1994.11 1065.87 1999 1055.04 2001.25C1016.7 2009.19 965.49 1995.6 933.44 1974.1C911.37 1959.29 892.7 1944.97 876.18 1923.81C840.84 1878.55 825.79 1820.47 833.23 1763.69C842.38 1693.9 881.8 1633.47 937.23 1591C1017.07 1529.83 1121.14 1501.99 1220.68 1516.07C1318.45 1529.9 1408.4 1581.72 1467.38 1661.4C1523.87 1737.72 1548.85 1828.29 1542.31 1922.78C1529.03 2114.47 1399.46 2264.87 1262.18 2387.27C1232.14 2414.05 1199.4 2437.55 1169.31 2464.25C1076.48 2546.63 991.47 2654.86 973.47 2780.5C957.46 2892.28 986.13 3011.86 1054.32 3102.39C1147.78 3226.46 1319.58 3305.88 1471.24 3327.66C1423.47 3250.71 1396.32 3156.89 1385.94 3067.41C1373.26 2958.09 1378.54 2847.93 1396 2739.48C1444.98 2435.22 1580.32 2204.44 1806.07 1996.91C1852.45 1954.28 1901.97 1914.78 1952.3 1876.94C1999.26 1841.64 2048.13 1808.95 2088.86 1766.17C2133.48 1719.3 2152.66 1662.91 2179.44 1605.68C2192.66 1577.43 2208.24 1549.99 2225.94 1524.28C2242.5 1500.21 2263.26 1476.7 2285.17 1457.35C2302.36 1442.16 2323.95 1427.89 2337.72 1409.51C2355.83 1385.35 2349.86 1353.28 2345.77 1325.78C2386.6 1323.81 2423.1 1316.09 2461.73 1302.83C2481.49 1296.04 2580.47 1256.23 2587.35 1242.16C2575.08 1244.06 2543.49 1260.72 2529.16 1266.24C2451.29 1296.22 2365.1 1321.36 2280.63 1310.3C2226.07 1303.15 2207.77 1265.95 2177.79 1226.61C2196.66 1226.56 2206.6 1223.75 2221.17 1211.5C2230.23 1203.87 2264.98 1218.4 2276.97 1219.22C2293.95 1220.36 2310.17 1216.06 2325.36 1208.82C2299.29 1211.75 2268.09 1213.76 2246.32 1196.07C2230.18 1182.93 2222.12 1162.39 2219.92 1142.13C2213.09 1079.2 2250.21 1084.6 2279.46 1048.19C2280.31 1043.97 2280.44 1042.21 2277.36 1038.52C2267.56 1026.79 2237.14 1028 2222.97 1028.43C2202.97 1029.04 2163.7 1031.31 2149.15 1046.66C2148.58 1049.23 2147.49 1051.09 2148.76 1053.6C2152.71 1061.39 2174.39 1077.43 2182.08 1089.52C2201.39 1119.87 2207.5 1158.47 2221.66 1191.54C2216.7 1197.03 2211.56 1203.36 2205.46 1207.59C2195.22 1214.71 2182.02 1216.97 2169.88 1214.69C2139.46 1208.99 2109.28 1176.61 2092.53 1152.23C2033.73 1175.42 1978.53 1203.92 1929.75 1244.59C1912.96 1258.59 1898.24 1274.89 1881.31 1288.62L1882.12 1287.15L1881.77 1288.43C1881.85 1288.33 1881.97 1288.25 1882.01 1288.12C1884.23 1280.59 1896.12 1269.6 1901.73 1263.4C1934.6 1227.01 1974.09 1196.22 2017.02 1172.58C2030.4 1165.22 2078.71 1145.08 2084.79 1136.91C2086.66 1134.39 2085.87 1133.49 2085.52 1130.64C2082 1126.89 2080 1125.48 2074.73 1124.95C2061.24 1123.59 2043.1 1130.45 2030.35 1134.6C1951.63 1160.19 1881.71 1203.93 1817.13 1254.93C1857.93 1205.19 1955.04 1148.06 2015.4 1126.81C2037.31 1119.1 2059.51 1116.31 2081.55 1109.88C2083.73 1105.55 2084.06 1105.27 2083.29 1100.53C2081.41 1098.77 2081.25 1098.45 2078.74 1097.03C2070.54 1092.41 2052.58 1094.9 2043.43 1095.72C1979.08 1101.44 1920.74 1118.22 1861.14 1142.46L1859.06 1141.58C1915.82 1103.87 2014.14 1082.67 2081.74 1084.17C2083.47 1078.86 2085.33 1073.6 2087.16 1068.33C2069.88 1040.26 2055.03 1011 2044.99 979.52C2020.29 902.1 2029.31 837.95 2078.43 773.12C2095.32 750.83 2115.17 728.88 2127.9 703.92C2138.26 683.63 2143.71 659.77 2142.71 636.98C2139.76 569.53 2083.97 474.76 2051.14 415.6C2040.67 396.73 2024.78 374.64 2018.88 354.16C2017.52 349.45 2017.79 346.29 2020.05 341.89C2023.01 339.46 2024.89 338.3 2028.72 337.39C2042.9 334.05 2064.79 343.16 2078.07 348.11C2205.35 395.5 2283.12 480.09 2394.21 547.97C2455.55 538.22 2515.78 536.69 2577.69 539.97C2606.1 517.64 2630.81 488.04 2651.23 458.37C2680.14 416.36 2704.58 371.22 2730.88 327.55C2744.19 305.45 2757.03 281.25 2774.78 262.36C2782.3 254.37 2789.15 250.35 2799.52 246.98Z";
+/** White fill the silhouette is drawn over; it shows through the nose and mouth cut-outs. */
+export const MUZZLE_D = "M2155 1209.88C2155 1209.88 2184.35 1227.46 2198.29 1254.54L2324.6 1304.7C2324.6 1304.7 2361.4 1331.96 2355.39 1355.49L2606.28 1303.93L2633.22 1128.46L2385.4 1084.59L2288.43 972.99L2128.35 997.62L2133.74 1160.01L2155 1209.88Z";
+export const BODY_D = "M3082.67 1332.98C3096.76 1382.66 3121 1430 3144.11 1475.96C3206.87 1600.72 3266.3 1720.9 3257.48 1865.17C3254.43 1915.11 3248.14 1969.79 3230.66 2016.73C3223.37 2036.3 3210.74 2054.24 3204.94 2074.23C3199.42 2093.23 3196.24 2113.47 3191.87 2132.81C3185.68 2160.15 3178.21 2186.78 3169.93 2213.55C3155.4 2260.58 3140.81 2307.83 3124.27 2354.2C3106.99 2402.68 3087.78 2450 3071.99 2499.11C3016.55 2671.53 2913.07 3233.13 2953.81 3400.21C2978.93 3503.21 3045.07 3451.05 3105.73 3488.85C3138.23 3509.1 3162.29 3547.66 3170.76 3584.56C3174.6 3601.25 3176.18 3620.01 3166.07 3634.88C3151.43 3656.4 3121.62 3659.23 3098.05 3663.13L3096.39 3661.12C3099.52 3638.63 3098.81 3616.19 3086.05 3596.56L3084.34 3593.97C3079.78 3586.98 3075.37 3581.5 3069.27 3575.78C3068.02 3577.79 3070.56 3579.08 3071.83 3580.73C3082.07 3593.94 3088.11 3607.69 3091.4 3624.04C3093.85 3636.17 3096.02 3650.49 3088.88 3661.32C3073 3671.58 2968.11 3671.07 2943.7 3670.86C2936.15 3641.12 2921.45 3614.84 2901.35 3591.71C2867.65 3552.96 2837.74 3537.4 2786.48 3533.78C2779.32 3515.24 2772.55 3496.73 2767.54 3477.47C2761.18 3453.01 2756.89 3426.79 2747.38 3403.32C2738.39 3381.13 2719 3366.46 2714.35 3341.57C2707.38 3304.28 2717.36 3264.7 2720.63 3227.32C2723.21 3197.89 2724.22 3168.22 2724.1 3138.68C2723.64 3022.85 2711.17 2906.9 2699.86 2791.71C2686.83 2843.15 2657.32 2903.82 2633.88 2952.01C2627.17 2812.54 2627.96 2672.99 2661.7 2536.56C2671.92 2495.21 2686.37 2455.78 2698.95 2415.19C2698.56 2415.86 2698.15 2416.52 2697.79 2417.2C2682.31 2445.82 2672.58 2482.19 2663.58 2513.47C2637.89 2602.79 2624.63 2693.84 2619.02 2786.52C2613.7 2874.42 2618.05 2964.3 2624.76 3052.03C2633.77 3169.9 2646.23 3287.35 2681.88 3400.67C2696.04 3445.71 2723.92 3530.62 2779.13 3538.85C2799.54 3541.89 2820.92 3539.97 2839.63 3550.35C2880.27 3572.9 2923.59 3619.06 2935.36 3664.98C2939.38 3680.69 2940.55 3697.79 2931.41 3712.01C2918.17 3732.59 2886.55 3736.98 2864.38 3742.43C2870.54 3720.54 2872.06 3697.91 2864.1 3676.17C2861.2 3668.25 2855.03 3655.15 2847.14 3651.31C2850.86 3656.7 2853.96 3663.17 2857 3668.99C2869.5 3692.95 2866.74 3717.79 2858.92 3742.6C2833.54 3748.7 2806.71 3749.63 2780.75 3751.53C2783.73 3738.66 2785.49 3725.41 2783.13 3712.28C2779.77 3693.67 2767.25 3672.96 2751.58 3662.03C2751.13 3663.17 2773.86 3691.75 2777.79 3704.54C2781.25 3715.76 2783.02 3735.15 2776.06 3745.49C2773.23 3749.7 2768.63 3751.44 2763.82 3752.08C2725.82 3757.1 2637.37 3741.57 2607.01 3716.13C2589.85 3701.75 2590.45 3684.55 2588.23 3663.96C2571.89 3643.85 2549.36 3629.7 2533.62 3608.74C2487.51 3547.32 2454.67 3419.16 2432.53 3344.03C2390.56 3387.86 2356.9 3436.35 2310.6 3476.58C2250.96 3467.72 2182.82 3477.44 2128.02 3503.48C2142.67 3503.56 2173.84 3490 2190.1 3485.76C2215.49 3479.16 2243.82 3475.81 2270.01 3475.7C2321.55 3475.47 2369.99 3499.11 2405.98 3535.38C2428.98 3558.57 2446.8 3585.9 2446.16 3619.86C2445.67 3646.37 2434.76 3664.89 2416.06 3682.55C2417.28 3676.39 2418.59 3670.12 2419.08 3663.85C2420.58 3645.07 2416.39 3622.9 2403.92 3608C2408.67 3620.46 2415.12 3634.35 2415.46 3647.8C2415.49 3648.86 2415.45 3649.93 2415.45 3651C2415.48 3661.35 2414.51 3671.52 2408.32 3680.22C2394.21 3700.06 2355.96 3702.77 2333.61 3707.18C2345.25 3691.29 2351.29 3673.63 2348.86 3653.76C2345.43 3625.69 2327.11 3606.14 2306.14 3589.27L2306.7 3590.31C2308.63 3590.52 2307.61 3590.18 2309.54 3591.78L2308.85 3592.9C2322.54 3607.76 2336.34 3621.76 2342.17 3641.77C2349.35 3666.41 2340.37 3685.66 2328.78 3706.77C2281.82 3712 2234.42 3711.83 2187.23 3712.03C2115.01 3712.34 2043.45 3711.1 1971.35 3706.26C1900.41 3701.49 1830.62 3692.81 1760.16 3683.83C1723.4 3679.14 1683.95 3676.99 1648.51 3666.09C1628.3 3659.87 1605.69 3649.72 1591.85 3633.25C1564.14 3600.3 1575 3564.64 1578.07 3526.27L1471.24 3327.66C1423.47 3250.71 1396.32 3156.89 1385.94 3067.41C1373.26 2958.09 1378.54 2847.93 1396 2739.48C1444.98 2435.22 1580.32 2204.44 1806.07 1996.91C1852.45 1954.28 1901.97 1914.78 1952.3 1876.94C1999.26 1841.64 2048.13 1808.95 2088.86 1766.17C2133.48 1719.3 2152.66 1662.91 2179.44 1605.68C2192.66 1577.43 2208.24 1549.99 2225.94 1524.28C2242.5 1500.21 2263.26 1476.7 2285.17 1457.35C2302.36 1442.16 2323.95 1427.89 2337.72 1409.51Z";
+export const HEAD_D = "M2337.72 1409.51C2355.83 1385.35 2349.86 1353.28 2345.77 1325.78C2386.6 1323.81 2423.1 1316.09 2461.73 1302.83C2481.49 1296.04 2580.47 1256.23 2587.35 1242.16C2575.08 1244.06 2543.49 1260.72 2529.16 1266.24C2451.29 1296.22 2365.1 1321.36 2280.63 1310.3C2226.07 1303.15 2207.77 1265.95 2177.79 1226.61C2196.66 1226.56 2206.6 1223.75 2221.17 1211.5C2230.23 1203.87 2264.98 1218.4 2276.97 1219.22C2293.95 1220.36 2310.17 1216.06 2325.36 1208.82C2299.29 1211.75 2268.09 1213.76 2246.32 1196.07C2230.18 1182.93 2222.12 1162.39 2219.92 1142.13C2213.09 1079.2 2250.21 1084.6 2279.46 1048.19C2280.31 1043.97 2280.44 1042.21 2277.36 1038.52C2267.56 1026.79 2237.14 1028 2222.97 1028.43C2202.97 1029.04 2163.7 1031.31 2149.15 1046.66C2148.58 1049.23 2147.49 1051.09 2148.76 1053.6C2152.71 1061.39 2174.39 1077.43 2182.08 1089.52C2201.39 1119.87 2207.5 1158.47 2221.66 1191.54C2216.7 1197.03 2211.56 1203.36 2205.46 1207.59C2195.22 1214.71 2182.02 1216.97 2169.88 1214.69C2139.46 1208.99 2109.28 1176.61 2092.53 1152.23C2033.73 1175.42 1978.53 1203.92 1929.75 1244.59C1912.96 1258.59 1898.24 1274.89 1881.31 1288.62L1882.12 1287.15L1881.77 1288.43C1881.85 1288.33 1881.97 1288.25 1882.01 1288.12C1884.23 1280.59 1896.12 1269.6 1901.73 1263.4C1934.6 1227.01 1974.09 1196.22 2017.02 1172.58C2030.4 1165.22 2078.71 1145.08 2084.79 1136.91C2086.66 1134.39 2085.87 1133.49 2085.52 1130.64C2082 1126.89 2080 1125.48 2074.73 1124.95C2061.24 1123.59 2043.1 1130.45 2030.35 1134.6C1951.63 1160.19 1881.71 1203.93 1817.13 1254.93C1857.93 1205.19 1955.04 1148.06 2015.4 1126.81C2037.31 1119.1 2059.51 1116.31 2081.55 1109.88C2083.73 1105.55 2084.06 1105.27 2083.29 1100.53C2081.41 1098.77 2081.25 1098.45 2078.74 1097.03C2070.54 1092.41 2052.58 1094.9 2043.43 1095.72C1979.08 1101.44 1920.74 1118.22 1861.14 1142.46L1859.06 1141.58C1915.82 1103.87 2014.14 1082.67 2081.74 1084.17C2083.47 1078.86 2085.33 1073.6 2087.16 1068.33C2069.88 1040.26 2055.03 1011 2044.99 979.52C2020.29 902.1 2029.31 837.95 2078.43 773.12C2095.32 750.83 2115.17 728.88 2127.9 703.92C2138.26 683.63 2143.71 659.77 2142.71 636.98C2139.76 569.53 2083.97 474.76 2051.14 415.6C2040.67 396.73 2024.78 374.64 2018.88 354.16C2017.52 349.45 2017.79 346.29 2020.05 341.89C2023.01 339.46 2024.89 338.3 2028.72 337.39C2042.9 334.05 2064.79 343.16 2078.07 348.11C2205.35 395.5 2283.12 480.09 2394.21 547.97C2455.55 538.22 2515.78 536.69 2577.69 539.97C2606.1 517.64 2630.81 488.04 2651.23 458.37C2680.14 416.36 2704.58 371.22 2730.88 327.55C2744.19 305.45 2757.03 281.25 2774.78 262.36C2782.3 254.37 2789.15 250.35 2799.52 246.98C2803.92 248 2808.56 249.71 2812.48 251.96C2839.71 267.59 2855.14 317.32 2865.41 345.21C2894.72 424.83 2921.75 500.85 2931.92 585.56C2935.19 612.79 2937.23 640.27 2938.69 667.64C2940.44 700.17 2937.47 739.92 2948.2 770.49C2955.57 791.51 2968.25 811.51 2977.16 832.09C3009.33 906.45 3039.15 977.74 3053.62 1057.88C3060.92 1098.31 3066.12 1139.08 3068.29 1180.12C3071 1231.45 3068.52 1283.04 3082.67 1332.98L3040 1560L2440 1600Z";
+export const DETAIL_D = {
+  'cat-brow-right': "M2563.11 743.56C2564.59 743.32 2563.59 743.39 2566.09 744.03C2553.75 747.13 2540.15 749.13 2528.56 754.31C2468.13 781.35 2432.52 825.03 2409.53 885.99L2409.27 887.59L2408.17 886.62C2410.19 857.03 2422.47 830.63 2440.92 807.74C2470.78 770.71 2516.19 748.39 2563.11 743.56Z",
+  'cat-ear-right-inner': "M2718.64 442.28C2717.48 456.94 2681.98 500.11 2670.4 514.39C2633.5 559.89 2598.74 590.79 2539.18 596.78C2540.63 590.9 2566.85 578.87 2572.87 575.39C2628.24 543.43 2674.6 487.94 2718.64 442.28Z",
+  'cat-ear-left-inner': "M2071.33 381.44C2084.12 385.57 2228.57 493.99 2244.68 508.93C2255.08 518.59 2280.82 543.45 2281.42 558.18C2277.66 559.65 2274.11 561.25 2270.01 561.46C2266.55 561.63 2263.22 556.64 2260.87 554.26C2249.83 543.04 2239.59 530.78 2228.09 520.07C2203.13 496.84 2175.94 475.44 2150.07 453.18C2123.16 430.01 2097.24 405.71 2071.33 381.44Z",
+  'cat-ear-right-edge': "M2872.87 398.29C2878.43 408.02 2881.32 421.14 2884.27 431.9C2909.91 525.37 2886.37 665.54 2864.24 759.96C2821.57 727.03 2782.69 689.43 2738.41 658.55C2730.82 653.85 2723.84 649.72 2717.71 643.09C2739.75 649.41 2821.77 714.49 2848.72 731.55C2871.97 652.25 2890.2 554.35 2884.24 471.79C2882.47 447.23 2876.51 422.67 2872.87 398.29Z",
+  'cat-eye-left': "M2093.44 794.28C2105.05 795.6 2115.71 798.6 2126.88 801.87C2126.57 808.49 2126.13 815.54 2126.7 822.15C2127.84 835.29 2133.74 861.33 2145.39 869.07C2149.91 872.06 2151.39 871.68 2156.49 871.1C2170.23 861.78 2175.3 840.28 2178.99 824.81C2184.59 829.17 2189.9 833.85 2195.25 838.5C2197.36 847.05 2198.63 855.19 2199.54 863.94C2201.31 879.09 2201.48 894.22 2201.75 909.45C2189.72 911.22 2177.97 912.97 2165.87 910.45C2141.18 905.31 2118.94 886.94 2105.65 865.77C2091.77 843.66 2087.69 819.66 2093.44 794.28Z",
+  'cat-leg-front-line': "M3107.27 2258.3C3107.62 2263.7 3103.09 2269.75 3100.43 2274.37C3026.87 2401.88 2929.25 2514.19 2804.95 2594.15C2770.4 2616.38 2732.99 2637.63 2693.14 2648.33L2693.06 2648.11C2695.3 2641.02 2727.52 2623.52 2735.55 2618.17C2771.74 2594.04 2807.82 2568.71 2841.75 2541.48C2942.75 2460.43 3035.79 2366.63 3107.27 2258.3Z",
+  'cat-eye-right': "M2587.62 798.4C2613.76 798.5 2639.83 801.48 2664.72 809.65C2659.27 834.43 2651.39 857.1 2635.93 877.57C2616.55 903.24 2585.95 923.19 2553.66 927.04C2522.61 930.74 2495.26 918.69 2471.27 900.24C2461.42 891.25 2454.06 882.67 2448.38 870.5C2467.24 843.22 2494.06 824.19 2523.42 809.5C2523.85 816.56 2524.08 823.94 2525.49 830.87C2528.15 844.01 2533.79 855.86 2541.05 867.05C2545.64 874.12 2556.52 876.76 2564.08 878.73C2572.55 880.94 2581.74 872.85 2584.82 865.38C2588.24 857.08 2589.39 844.64 2589.65 835.83C2590.03 823.32 2588.64 810.85 2587.62 798.4Z",
+  'cat-leg-rear-line': "M2007.98 2471.99C2011.45 2472.59 2014.91 2473.28 2018.33 2474.14C2109.07 2497.19 2181.35 2578.79 2226.69 2656.6C2258.21 2710.7 2282.45 2768.46 2302.82 2827.56C2317.53 2870.23 2329.71 2913.75 2341.29 2957.36C2360.36 3029.16 2375.35 3101.62 2392.5 3173.83C2403.99 3222.19 2418.51 3270.11 2427.71 3318.99C2428.67 3324.06 2429.31 3328.42 2427.96 3333.5C2424.15 3325.19 2423.9 3316.89 2421.66 3308.19C2416.82 3289.39 2410.6 3270.7 2404.84 3252.16C2390.32 3205.39 2372.67 3159.65 2354.96 3114.02C2352.33 3146.86 2346.39 3179.07 2339.81 3211.31C2321.06 3288.31 2282.34 3370.59 2225.42 3427.27C2241.47 3401.22 2257.85 3375.29 2270.51 3347.38C2351.48 3168.94 2330.01 2981.27 2262.88 2802.79C2214.91 2675.25 2137.51 2530.87 2007.98 2471.99Z",
+} as const;
+export type DetailId = keyof typeof DETAIL_D;
+
+/** The tail outline (cut at nodes 91 → 116, closed through a hidden plug inside the body). */
+export const TAIL_COMMANDS: PathCommand[] = [["M",1578.07,3526.27],["C",1511.31,3529.58,1447.02,3531.45,1380.55,3522.66],["C",1185.03,3496.81,992.6,3392.35,872.38,3234.96],["C",771.19,3102.49,724.48,2936.65,747.35,2771.22],["C",780.59,2530.86,942.02,2370.2,1126.85,2230.18],["C",1180.53,2189.93,1229.3,2139.69,1263.33,2081.57],["C",1291.87,2032.82,1311.83,1971.3,1296.47,1914.92],["C",1281.69,1860.66,1235.41,1809.66,1187.19,1782.31],["C",1153.2,1763.04,1114.72,1756.76,1076.76,1767.52],["C",1043.57,1776.93,1009.94,1801.06,993.75,1831.99],["C",988.53,1841.96,986.15,1853.22,987.01,1864.45],["C",991.41,1921.87,1077.88,1922.52,1091.47,1967.9],["C",1093.19,1973.65,1093,1978.42,1089.94,1983.74],["C",1083.97,1994.11,1065.87,1999,1055.04,2001.25],["C",1016.7,2009.19,965.49,1995.6,933.44,1974.1],["C",911.37,1959.29,892.7,1944.97,876.18,1923.81],["C",840.84,1878.55,825.79,1820.47,833.23,1763.69],["C",842.38,1693.9,881.8,1633.47,937.23,1591],["C",1017.07,1529.83,1121.14,1501.99,1220.68,1516.07],["C",1318.45,1529.9,1408.4,1581.72,1467.38,1661.4],["C",1523.87,1737.72,1548.85,1828.29,1542.31,1922.78],["C",1529.03,2114.47,1399.46,2264.87,1262.18,2387.27],["C",1232.14,2414.05,1199.4,2437.55,1169.31,2464.25],["C",1076.48,2546.63,991.47,2654.86,973.47,2780.5],["C",957.46,2892.28,986.13,3011.86,1054.32,3102.39],["C",1147.78,3226.46,1319.58,3305.88,1471.24,3327.66],["L",1640,3330],["L",1720,3470],["Z"]];
+/** For each command of TAIL_COMMANDS, the centre-line position s ∈ [0, 1] of each of its points (0 = root, 1 = tip). */
+export const TAIL_POINT_S: number[][] = [[0],[0.0136,0.0272,0.0408],[0.0968,0.1528,0.2088],[0.2519,0.2951,0.3382],[0.4087,0.4792,0.5497],[0.5726,0.5955,0.6184],[0.6435,0.6686,0.6937],[0.7228,0.7519,0.7809],[0.804,0.8271,0.8502],[0.8711,0.8919,0.9128],[0.9197,0.9266,0.9334],[0.9542,0.9749,0.9956],[0.9963,0.9971,0.9979],[0.9971,0.9963,0.9956],[0.9834,0.9713,0.9591],[0.9536,0.9481,0.9426],[0.9327,0.9228,0.9128],[0.8985,0.8842,0.8699],[0.8485,0.8271,0.8057],[0.7833,0.7609,0.7386],[0.7178,0.697,0.6763],[0.623,0.5697,0.5164],[0.5037,0.4909,0.4781],[0.434,0.3899,0.3458],[0.2985,0.2511,0.2037],[0.1392,0.0747,0.0102],[0],[0],[]];
+/** The bone chain, root to tip. Bone i runs from TAIL_JOINTS[i] to TAIL_JOINTS[i + 1] and rotates about TAIL_JOINTS[i]. */
+export const TAIL_BONES = ["tail-root","tail-segment-1","tail-segment-2","tail-segment-3","tail-tip"] as const;
+export const TAIL_JOINTS: [number, number][] = [[1524.66,3426.97],[979.67,3182.72],[921.84,2604.43],[1336.88,2152.6],[1200.43,1653.36],[1089.94,1983.74]];
+/** The smoothed centre line, root to tip (every 10th sample), for overlays. */
+export const TAIL_CENTRE_LINE: [number, number][] = [[1524.66,3426.97],[1446.2,3423.13],[1368.69,3411.18],[1292.92,3390.66],[1219.73,3362.22],[1149.94,3326.24],[1084.59,3282.81],[1024.95,3231.95],[972.54,3173.81],[928.92,3108.9],[895.32,3038.3],[872.53,2963.52],[861.07,2886.19],[861.33,2808.04],[873.52,2730.88],[897.4,2656.48],[931.94,2586.25],[975.37,2520.96],[1025.83,2460.77],[1081.53,2405.19],[1140.26,2352.63],[1199.51,2300.6],[1256.88,2246.64],[1309.7,2188.53],[1355.08,2124.76],[1389.85,2055.05],[1410.44,1980.41],[1413.46,1903.56],[1396.63,1828.91],[1360.32,1761.51],[1307.42,1706.05],[1241.77,1666.84],[1168.05,1647.83],[1092.17,1651.43],[1021.1,1677.73],[963.26,1725.12],[929.56,1789.28],[930.43,1859.34],[967.28,1919.73],[1028.25,1962.1],[1089.94,1983.74]];
+/** Where the head turns: the middle of the neck cut, a little into the neck. */
+export const HEAD_PIVOT: [number, number] = [2710.2,1411.25];

package/src/motion/cat/config.ts

@@ -0,0 +1,186 @@
+import { CAT_SOURCE_PALETTE, TAIL_JOINTS } from './art.generated';
+import { TAIL_BONE_IDS, type TailBoneId } from './rig';
+
+/**
+ * **The cat's manipulation model** — one plain object that says everything about how the cat looks and
+ * moves. The editor, agents and the Remotion props all edit THIS; the animation model is built from it
+ * (`buildAnimationDocument`) and the renderers draw what the two resolve to. Nobody edits path data.
+ * Units: artboard units (the EPS's 4000-unit square; the cat is ~2500 wide), degrees, milliseconds.
+ */
+export const EASING_NAMES = ['linear', 'easeIn', 'easeOut', 'easeInOut', 'sineInOut', 'spline'] as const;
+export type EasingName = (typeof EASING_NAMES)[number];
+
+/** Parts that can be recoloured or hidden one by one. */
+export const PART_IDS = [
+  'cat-tail', 'cat-body-shape', 'cat-legs', 'cat-leg-front-line', 'cat-leg-rear-line', 'cat-head', 'cat-head-shape', 'cat-muzzle',
+  'cat-ears', 'cat-ear-left-inner', 'cat-ear-right-inner', 'cat-ear-right-edge', 'cat-eyes', 'cat-eye-left', 'cat-eye-right', 'cat-brow-right',
+] as const;
+export type PartId = (typeof PART_IDS)[number];
+export type PartStyle = { visible?: boolean; fill?: string };
+
+export type CatConfig = {
+  /** Fur: the tail, body and head silhouette. */
+  color: string;
+  /** The white details: eyes, ear lines, leg lines, muzzle. */
+  detailColor: string;
+  /** A colour to fill the frame with, or null for transparent. */
+  background: string | null;
+  /** The whole cat. Rotation and scale are about the middle of the artwork. */
+  transform: { x: number; y: number; scale: number; rotate: number };
+  /** The body, carrying the head and tail with it. */
+  body: { x: number; y: number };
+  head: { rotate: number };
+  tail: {
+    enabled: boolean;
+    /** The tail as one piece, on top of its rig: move, turn and scale about `origin`. */
+    x: number;
+    y: number;
+    rotate: number;
+    scale: number;
+    /** The pivot for `rotate` and `scale`; defaults to the tail root. */
+    origin: { x: number; y: number };
+    /** A held bend, per bone, in degrees — the pose the wiggle plays around. */
+    pose: Partial<Record<TailBoneId, number>>;
+    /** Play the tail wiggle. */
+    wiggle: boolean;
+    /** Peak bend of the tip bone, in degrees; the bones nearer the root bend proportionally less. */
+    amount: number;
+    /** Playback rate: 2 plays the same wiggle twice as fast. */
+    speed: number;
+    /** One full wiggle cycle (right, back, left, back), in ms, at speed 1. */
+    duration: number;
+    easing: EasingName;
+    loop: boolean;
+    /** How far (as a fraction of the cycle) the tip lags the root, spread evenly over the bones: a travelling wave, not a rigid swing. */
+    followThrough: number;
+  };
+  parts: Partial<Record<PartId, PartStyle>>;
+};
+
+export const DEFAULT_CAT_CONFIG: CatConfig = {
+  color: CAT_SOURCE_PALETTE.fur,
+  detailColor: CAT_SOURCE_PALETTE.detail,
+  background: null,
+  transform: { x: 0, y: 0, scale: 1, rotate: 0 },
+  body: { x: 0, y: 0 },
+  head: { rotate: 0 },
+  tail: {
+    enabled: true,
+    x: 0, y: 0, rotate: 0, scale: 1,
+    origin: { x: TAIL_JOINTS[0]![0], y: TAIL_JOINTS[0]![1] },
+    pose: Object.fromEntries(TAIL_BONE_IDS.map((id) => [id, 0])) as Record<TailBoneId, number>,
+    wiggle: true,
+    amount: 6,
+    speed: 1,
+    duration: 1500,
+    easing: 'easeInOut',
+    loop: true,
+    followThrough: 0.06,
+  },
+  parts: {},
+};
+
+/** The source look: the mint background of the original JPG. */
+export const SOURCE_BACKGROUND = CAT_SOURCE_PALETTE.background;
+
+export type CatControl = {
+  path: string;
+  label: string;
+  group: 'Look' | 'Cat' | 'Head' | 'Tail' | 'Tail rig' | 'Wiggle';
+  type: 'number' | 'boolean' | 'color' | 'enum';
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  options?: readonly string[];
+  description: string;
+};
+
+/**
+ * **Every editable value, with its range.** The editor draws its controls from this table and
+ * `validateCatConfig` checks against it, so a new control is one row here.
+ */
+export const CAT_CONTROLS: CatControl[] = [
+  { path: 'color', label: 'Fur colour', group: 'Look', type: 'color', description: 'Tail, body and head.' },
+  { path: 'detailColor', label: 'Detail colour', group: 'Look', type: 'color', description: 'Eyes, ear lines, leg lines and muzzle.' },
+  { path: 'transform.x', label: 'X', group: 'Cat', type: 'number', min: -1500, max: 1500, step: 1, unit: 'units', description: 'Moves the whole cat.' },
+  { path: 'transform.y', label: 'Y', group: 'Cat', type: 'number', min: -1500, max: 1500, step: 1, unit: 'units', description: 'Moves the whole cat.' },
+  { path: 'transform.scale', label: 'Scale', group: 'Cat', type: 'number', min: 0.2, max: 2, step: 0.01, description: 'About the middle of the artwork.' },
+  { path: 'transform.rotate', label: 'Rotation', group: 'Cat', type: 'number', min: -45, max: 45, step: 0.5, unit: '°', description: 'About the middle of the artwork.' },
+  { path: 'body.x', label: 'Body X', group: 'Cat', type: 'number', min: -600, max: 600, step: 1, unit: 'units', description: 'The body, carrying head and tail.' },
+  { path: 'body.y', label: 'Body Y', group: 'Cat', type: 'number', min: -600, max: 600, step: 1, unit: 'units', description: 'The body, carrying head and tail.' },
+  { path: 'head.rotate', label: 'Head rotation', group: 'Head', type: 'number', min: -12, max: 12, step: 0.5, unit: '°', description: 'Turns the head at the neck. Past ±12° the cut at the neck shows.' },
+  { path: 'tail.enabled', label: 'Show tail', group: 'Tail', type: 'boolean', description: 'Hide the tail entirely.' },
+  { path: 'tail.rotate', label: 'Rotation', group: 'Tail', type: 'number', min: -45, max: 45, step: 0.5, unit: '°', description: 'The whole tail, about its origin.' },
+  { path: 'tail.x', label: 'Position X', group: 'Tail', type: 'number', min: -600, max: 600, step: 1, unit: 'units', description: 'Moves the tail.' },
+  { path: 'tail.y', label: 'Position Y', group: 'Tail', type: 'number', min: -600, max: 600, step: 1, unit: 'units', description: 'Moves the tail.' },
+  { path: 'tail.scale', label: 'Scale', group: 'Tail', type: 'number', min: 0.5, max: 1.5, step: 0.01, description: 'About its origin.' },
+  { path: 'tail.origin.x', label: 'Origin X', group: 'Tail', type: 'number', min: 600, max: 3400, step: 1, unit: 'units', description: 'Pivot for rotation and scale. Default: the tail root.' },
+  { path: 'tail.origin.y', label: 'Origin Y', group: 'Tail', type: 'number', min: 100, max: 3900, step: 1, unit: 'units', description: 'Pivot for rotation and scale. Default: the tail root.' },
+  ...TAIL_BONE_IDS.map((id): CatControl => ({
+    path: `tail.pose.${id}`, label: id, group: 'Tail rig', type: 'number', min: -45, max: 45, step: 0.5, unit: '°',
+    description: `Held bend of ${id}; everything after it follows.`,
+  })),
+  { path: 'tail.wiggle', label: 'Wiggle', group: 'Wiggle', type: 'boolean', description: 'Play the tail wiggle.' },
+  { path: 'tail.amount', label: 'Wiggle amount', group: 'Wiggle', type: 'number', min: 0, max: 30, step: 0.5, unit: '°', description: 'Peak bend of the tip bone.' },
+  { path: 'tail.speed', label: 'Speed', group: 'Wiggle', type: 'number', min: 0.25, max: 4, step: 0.05, unit: '×', description: 'Playback rate.' },
+  { path: 'tail.duration', label: 'Duration', group: 'Wiggle', type: 'number', min: 300, max: 6000, step: 50, unit: 'ms', description: 'One full cycle at speed 1.' },
+  { path: 'tail.easing', label: 'Easing', group: 'Wiggle', type: 'enum', options: EASING_NAMES, description: 'Between keyframes. spline passes through them without stopping.' },
+  { path: 'tail.loop', label: 'Loop', group: 'Wiggle', type: 'boolean', description: 'Repeat, or play one cycle and hold the rest pose.' },
+  { path: 'tail.followThrough', label: 'Follow-through', group: 'Wiggle', type: 'number', min: 0, max: 0.2, step: 0.005, description: 'How far the tip lags the root, as a fraction of the cycle.' },
+];
+
+export function getPath(obj: unknown, path: string): unknown {
+  return path.split('.').reduce<unknown>((o, k) => (o == null ? undefined : (o as Record<string, unknown>)[k]), obj);
+}
+
+/** A copy of `obj` with `path` set; the objects on the way are copied, never mutated. */
+export function setPath<T>(obj: T, path: string, value: unknown): T {
+  const [k, ...rest] = path.split('.');
+  const o = (obj ?? {}) as Record<string, unknown>;
+  return { ...o, [k!]: rest.length ? setPath(o[k!], rest.join('.'), value) : value } as T;
+}
+
+export type DeepPartial<T> = { [K in keyof T]?: T[K] extends object | null ? DeepPartial<NonNullable<T[K]>> | Extract<T[K], null> : T[K] };
+export type CatConfigInput = DeepPartial<CatConfig>;
+
+const isPlain = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+function merge(base: unknown, patch: unknown): unknown {
+  if (!isPlain(base) || !isPlain(patch)) return patch === undefined ? base : patch;
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(patch)) out[k] = merge(base[k], v);
+  return out;
+}
+
+/** The full config: defaults under whatever was given. No validation — see `validateCatConfig`. */
+export const resolveCatConfig = (input: CatConfigInput = {}): CatConfig => merge(DEFAULT_CAT_CONFIG, input) as CatConfig;
+
+const COLOUR = /^#[0-9a-fA-F]{6}$/;
+export type CatConfigError = { path: string; message: string };
+
+/** Every problem with a config, by path — empty when it is valid. */
+export function validateCatConfig(input: unknown): CatConfigError[] {
+  if (!isPlain(input)) return [{ path: '', message: 'expected an object' }];
+  const config = resolveCatConfig(input as CatConfigInput);
+  const errors: CatConfigError[] = [];
+  for (const c of CAT_CONTROLS) {
+    const v = getPath(config, c.path);
+    if (c.type === 'number') {
+      if (typeof v !== 'number' || !Number.isFinite(v)) errors.push({ path: c.path, message: 'expected a number' });
+      else if (v < c.min! || v > c.max!) errors.push({ path: c.path, message: `expected ${c.min} … ${c.max}, got ${v}` });
+    } else if (c.type === 'boolean' && typeof v !== 'boolean') errors.push({ path: c.path, message: 'expected true or false' });
+    else if (c.type === 'color' && (typeof v !== 'string' || !COLOUR.test(v))) errors.push({ path: c.path, message: 'expected #rrggbb' });
+    else if (c.type === 'enum' && !c.options!.includes(v as string)) errors.push({ path: c.path, message: `expected one of ${c.options!.join(', ')}` });
+  }
+  if (config.background !== null && (typeof config.background !== 'string' || !COLOUR.test(config.background))) {
+    errors.push({ path: 'background', message: 'expected #rrggbb or null' });
+  }
+  for (const k of Object.keys(config.tail.pose)) {
+    if (!(TAIL_BONE_IDS as readonly string[]).includes(k)) errors.push({ path: `tail.pose.${k}`, message: `unknown bone; bones are ${TAIL_BONE_IDS.join(', ')}` });
+  }
+  for (const [k, s] of Object.entries(config.parts)) {
+    if (!(PART_IDS as readonly string[]).includes(k)) errors.push({ path: `parts.${k}`, message: 'unknown part' });
+    else if (s?.fill !== undefined && !COLOUR.test(s.fill)) errors.push({ path: `parts.${k}.fill`, message: 'expected #rrggbb' });
+  }
+  return errors;
+}

package/src/motion/cat/index.ts

@@ -0,0 +1,26 @@
+/**
+ * **The cat rig** — a stock vector cat (Vecteezy 47078283) converted from EPS, decomposed into semantic
+ * parts, with a skinned five-bone tail and a keyframe animation model. `docs/CAT-RIG.md`.
+ *
+ *   SVG parts → manipulation model (CatConfig) → animation model (JSON) → pose → SVG / React / Remotion
+ */
+export {
+  CAT_CREDIT, CAT_ARTBOARD, CAT_VIEWBOX, CAT_SOURCE_PALETTE, SILHOUETTE_D, MUZZLE_D, BODY_D, HEAD_D, DETAIL_D,
+  TAIL_COMMANDS, TAIL_POINT_S, TAIL_BONES, TAIL_JOINTS, TAIL_CENTRE_LINE, HEAD_PIVOT,
+  type PathCommand, type DetailId,
+} from './art.generated';
+export {
+  TAIL_BONE_IDS, boneMatrices, posedJoints, weightsAt, posedTailCommands, posedTailD, pathD, commandsBox, mul, rotateAbout, applyMat, IDENTITY,
+  type TailBoneId, type TailPose, type Mat,
+} from './rig';
+export {
+  DEFAULT_CAT_CONFIG, SOURCE_BACKGROUND, CAT_CONTROLS, EASING_NAMES, PART_IDS, resolveCatConfig, validateCatConfig, getPath, setPath,
+  type CatConfig, type CatConfigInput, type CatControl, type CatConfigError, type EasingName, type PartId, type PartStyle, type DeepPartial,
+} from './config';
+export {
+  CAT_ANIMATION_SCHEMA, ANIMATION_TARGETS, WIGGLE_PROFILE, buildTailWiggle, buildAnimationDocument, validateAnimationDocument, sampleTrack,
+  sampleAnimations, progress, catPose, documentDuration,
+  type CatAnimation, type CatAnimationDocument, type CatTrack, type CatKeyframe, type CatPose, type AnimatedProperty,
+} from './animation';
+export { catScene, catSvg, parseD, tailMatrix, catMatrix, bodyMatrix, headMatrix, matrixAttr, VIEW_CENTRE, type SceneNode, type CatSvgOptions } from './scene';
+export { Cat, CatPlayer, type CatProps, type CatPlayerProps } from './Cat';

package/src/motion/cat/rig.ts

@@ -0,0 +1,102 @@
+import { TAIL_BONES, TAIL_COMMANDS, TAIL_JOINTS, TAIL_POINT_S, type PathCommand } from './art.generated';
+
+/**
+ * **The tail rig** — a chain of five bones skinned to the tail outline (`docs/CAT-RIG.md`).
+ *
+ *   tail-root → tail-segment-1 → tail-segment-2 → tail-segment-3 → tail-tip
+ *
+ * Bone i rotates about its rest joint, and each bone's transform is its parent's transform followed by
+ * its own rotation, so a rotation at the root carries everything after it. The path is not cut into
+ * rigid pieces: every point of the original outline carries its position s along the tail's centre
+ * line, and is moved by the two nearest bones blended linearly (linear-blend skinning). That keeps the
+ * outline one smooth, crack-free vector path in every pose, and at rest (all angles 0) it is exactly
+ * the source geometry.
+ */
+export type TailBoneId = (typeof TAIL_BONES)[number];
+export const TAIL_BONE_IDS: readonly TailBoneId[] = TAIL_BONES;
+/** Degrees per bone; missing bones are 0. Positive turns clockwise on screen (SVG's y points down). */
+export type TailPose = Partial<Record<TailBoneId, number>>;
+
+/** A 2D affine matrix [a, b, c, d, e, f] — the same order as SVG's `matrix()`. */
+export type Mat = [number, number, number, number, number, number];
+export const IDENTITY: Mat = [1, 0, 0, 1, 0, 0];
+export const mul = (m: Mat, n: Mat): Mat => [
+  m[0] * n[0] + m[2] * n[1], m[1] * n[0] + m[3] * n[1],
+  m[0] * n[2] + m[2] * n[3], m[1] * n[2] + m[3] * n[3],
+  m[0] * n[4] + m[2] * n[5] + m[4], m[1] * n[4] + m[3] * n[5] + m[5],
+];
+export const rotateAbout = (deg: number, cx: number, cy: number): Mat => {
+  const r = (deg * Math.PI) / 180, c = Math.cos(r), s = Math.sin(r);
+  return [c, s, -s, c, cx - c * cx + s * cy, cy - s * cx - c * cy];
+};
+export const applyMat = (m: Mat, x: number, y: number): [number, number] => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]];
+
+/** World transform of every bone for a pose: parent first, then the bone's rotation about its rest joint. */
+export function boneMatrices(pose: TailPose): Mat[] {
+  const out: Mat[] = [];
+  let parent = IDENTITY;
+  TAIL_BONE_IDS.forEach((id, i) => {
+    const [jx, jy] = TAIL_JOINTS[i]!;
+    parent = mul(parent, rotateAbout(pose[id] ?? 0, jx, jy));
+    out.push(parent);
+  });
+  return out;
+}
+
+/** Posed joint positions (root … tip end): where the handles and the debug overlay draw. */
+export function posedJoints(pose: TailPose): [number, number][] {
+  const m = boneMatrices(pose);
+  return TAIL_JOINTS.map(([x, y], i) => applyMat(m[Math.min(i, m.length - 1)]!, x, y) as [number, number]);
+}
+
+const n = TAIL_BONE_IDS.length;
+/** Bone weights for a centre-line position: hat functions centred on each bone's middle, clamped at the ends. */
+export function weightsAt(s: number): { i: number; w: number }[] {
+  const f = s * n - 0.5;
+  if (f <= 0) return [{ i: 0, w: 1 }];
+  if (f >= n - 1) return [{ i: n - 1, w: 1 }];
+  const i = Math.floor(f), t = f - i;
+  return [{ i, w: 1 - t }, { i: i + 1, w: t }];
+}
+
+function skin(mats: Mat[], x: number, y: number, s: number): [number, number] {
+  let ox = 0, oy = 0;
+  for (const { i, w } of weightsAt(s)) {
+    const [px, py] = applyMat(mats[i]!, x, y);
+    ox += w * px; oy += w * py;
+  }
+  return [ox, oy];
+}
+
+/** The tail outline deformed by a pose, as path commands. At rest it returns TAIL_COMMANDS unchanged. */
+export function posedTailCommands(pose: TailPose): PathCommand[] {
+  const mats = boneMatrices(pose);
+  return TAIL_COMMANDS.map((c, k): PathCommand => {
+    const s = TAIL_POINT_S[k]!;
+    if (c[0] === 'Z') return c;
+    if (c[0] === 'C') {
+      const a = skin(mats, c[1], c[2], s[0]!), b = skin(mats, c[3], c[4], s[1]!), e = skin(mats, c[5], c[6], s[2]!);
+      return ['C', a[0], a[1], b[0], b[1], e[0], e[1]];
+    }
+    const p = skin(mats, c[1], c[2], s[0]!);
+    return [c[0], p[0], p[1]];
+  });
+}
+
+const num = (v: number) => String(Math.round(v * 100) / 100);
+export const pathD = (cmds: PathCommand[]): string =>
+  cmds.map((c) => c[0] + (c.length > 1 ? (c.slice(1) as number[]).map(num).join(' ') : '')).join('');
+
+export const posedTailD = (pose: TailPose): string => pathD(posedTailCommands(pose));
+
+/** Bounding box of path commands (control points included — a cheap, conservative box). */
+export function commandsBox(cmds: PathCommand[]) {
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  for (const c of cmds) {
+    for (let i = 1; i < c.length; i += 2) {
+      const x = c[i] as number, y = c[i + 1] as number;
+      if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y;
+    }
+  }
+  return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
+}