@appinternalleads/ui 0.4.0 → 0.4.1

package/src/motion/replication2/rive-contract.ts

@@ -0,0 +1,165 @@
+import type { FrameState, Glow, Rgba } from './engine';
+
+/**
+ * **The Rive contract** — the `Replication2` view model, property by property, and the one function
+ * that fills it from the engine's frame state. This is the only place the file's property names
+ * appear on the host side; the authoring script (`rive/replication-2/authoring/generate-rml.ts`)
+ * builds the file from the same list, so the two cannot drift apart.
+ *
+ * Every property corresponds to a schema value (directly or through the engine); the file has no
+ * inputs of its own. Pure: no React, no Rive runtime.
+ */
+export const RIVE_ARTBOARD = 'Replication2';
+export const RIVE_STATE_MACHINE = 'Replication2Machine';
+export const RIVE_VIEW_MODEL = 'Replication2';
+
+export type RiveProp = { name: string; type: 'Number' | 'String' | 'Color'; value: number | string; toSource?: boolean };
+const N = (name: string, value = 0): RiveProp => ({ name, type: 'Number', value });
+const S = (name: string, value = ''): RiveProp => ({ name, type: 'String', value });
+const C = (name: string, value = 0xff000000): RiveProp => ({ name, type: 'Color', value });
+
+export const STREAK_SLOTS = 12;
+
+export const RIVE_PROPS: readonly RiveProp[] = [
+  N('sceneIndex'), S('status', 'idle'),
+  N('artW', 1920), N('artH', 1080),
+  // background
+  C('bgDark'), C('bgLight'), N('bgLightOpacity'),
+  N('gradOpacity'), C('gradFrom'), C('gradTo'), N('gradX1'), N('gradY1'), N('gradX2'), N('gradY2'),
+  ...(['top', 'bottom'] as const).flatMap((k) => [N(`${k}X`), N(`${k}Y`), N(`${k}R`), N(`${k}ScaleY`, 1), C(`${k}Color`), C(`${k}Mid`), N(`${k}Falloff`, 0.5), N(`${k}Opacity`)]),
+  N('vigOpacity'), C('vigColor'), N('vigX'), N('vigY'), N('vigR', 1),
+  C('streakColor'), N('streakWidth', 10), N('streakHeight', 1080),
+  ...Array.from({ length: STREAK_SLOTS }, (_, i) => [N(`streak${i}X`), N(`streak${i}Opacity`)]).flat(),
+  // the text group
+  N('stageX', 960), N('stageY', 540), N('stageScale', 1), N('stageRotation'), N('stageOpacity', 1),
+  // the sentence
+  S('lineSettled'), S('lineHead'), C('lineColor'), C('lineHeadColor'), N('lineSize', 100), N('lineWeight', 400), N('lineTracking'), N('lineOpacity', 1),
+  { ...N('lineWidth'), toSource: true },
+  // per-glyph entry (the newest glyph of the sentence or the final words) and distortion (sentence or display line)
+  N('enterFrom', -10), N('enterTo', -9), N('enterX'), N('enterY'), N('enterScale', 1), N('enterRotation'), N('enterOpacity', 1), N('enterStrength'),
+  N('distFrom'), N('distTo'), N('distFalloffFrom'), N('distFalloffTo'), N('distX'), N('distY'), N('distRotation'), N('distScaleX', 1), N('distScaleY', 1), N('distOpacity', 1), N('distStrength'),
+  // the display line
+  S('displayText'), N('displaySize', 100), N('displayWeight', 400), N('displayTracking'), N('displayOpacity', 1),
+  C('displayTop'), C('displayBottom'), N('displayGradStartY'), N('displayGradEndY'),
+  N('hideLeftTo', -1), N('hideLeftFalloff', -1), N('hideRightFrom', 2), N('hideRightFalloff', 2),
+  // the final words
+  S('finalSettled'), S('finalHead'), S('finalEntering'), C('finalColor'), C('finalHeadColor'), C('finalEnteringColor'),
+  N('finalSize', 60), N('finalWeight', 400), N('finalTracking'), N('finalOpacity', 1),
+  { ...N('finalWidth'), toSource: true },
+  // cursor
+  N('cursorW'), N('cursorH'), N('cursorStroke'), N('cursorRadius'), C('cursorStrokeColor'), C('cursorFillColor'), N('cursorOffset'), N('cursorScale', 1),
+  N('cursorLineOpacity'), N('cursorFinalOpacity'), N('cursorGlowOpacity'), C('cursorGlowColor'), N('cursorGlowR'),
+  // head glow
+  C('glowColor'), C('glowMid'), N('glowFalloff', 0.5), N('glowR'), N('glowScaleY', 1), N('glowX'), N('glowY'),
+  N('glowNormal'), N('glowScreen'), N('glowAdditive'),
+  // brackets
+  N('brOpacity'), C('brColor'), N('brThick', 1), N('brHalfH'), N('brSerif'), N('brLeftX'), N('brRightX'),
+  N('brLeftTrim', 1), N('brRightTrim', 1), N('brLeftOpacity'), N('brRightOpacity'), N('brGlowOpacity'), C('brGlowColor'), N('brGlowR'),
+  // braces
+  N('braceOpacity'), C('braceColor'), N('braceSize', 60), N('braceWeight', 600), N('braceLeftX'), N('braceRightX'), N('braceY'),
+  N('braceClosing'), N('braceGlowOpacity'), C('braceGlowColor'), N('braceGlowR'),
+];
+
+/** `#rrggbb` (+ alpha 0‥1) as the ARGB integer the Rive runtime takes. */
+export function argb(hex: string, alpha = 1): number {
+  const a = Math.round(Math.min(1, Math.max(0, alpha)) * 255);
+  return ((a << 24) | parseInt(hex.slice(1, 7), 16)) >>> 0;
+}
+const rgba = (c: Rgba) => argb(c.hex, c.alpha);
+const deg = (d: number) => (d * Math.PI) / 180;
+
+export type RiveValues = Record<string, number | string>;
+
+/** Every view-model value for one frame. The driver writes these, skipping unchanged ones. */
+export function riveValues(s: FrameState): RiveValues {
+  const v: RiveValues = {
+    sceneIndex: s.sceneIndex,
+    artW: s.design.width, artH: s.design.height,
+    bgDark: argb(s.background.dark), bgLight: argb(s.background.light), bgLightOpacity: s.background.lightOpacity,
+    gradOpacity: s.background.gradient.opacity, gradFrom: argb(s.background.gradient.from), gradTo: argb(s.background.gradient.to),
+    gradX1: s.background.gradient.x1, gradY1: s.background.gradient.y1, gradX2: s.background.gradient.x2, gradY2: s.background.gradient.y2,
+    vigOpacity: s.background.vignette.opacity, vigColor: argb(s.background.vignette.color),
+    vigX: s.design.width / 2, vigY: s.design.height / 2, vigR: s.background.vignette.radius,
+    streakColor: argb(s.background.streaks.color), streakWidth: s.background.streaks.width, streakHeight: s.design.height,
+  };
+  const glow = (k: string, g: Glow) => {
+    v[`${k}X`] = g.x; v[`${k}Y`] = g.y; v[`${k}R`] = g.rx; v[`${k}ScaleY`] = g.rx > 0 ? g.ry / g.rx : 1;
+    v[`${k}Color`] = argb(g.color); v[`${k}Mid`] = argb(g.color, 0.5); v[`${k}Falloff`] = g.falloff; v[`${k}Opacity`] = g.visible ? g.opacity : 0;
+  };
+  glow('top', s.background.top);
+  glow('bottom', s.background.bottom);
+  for (let i = 0; i < STREAK_SLOTS; i++) {
+    const it = s.background.streaks.items[i];
+    v[`streak${i}X`] = it?.x ?? 0;
+    v[`streak${i}Opacity`] = it?.opacity ?? 0;
+  }
+
+  Object.assign(v, { stageX: s.stage.x, stageY: s.stage.y, stageScale: s.stage.scale, stageRotation: deg(s.stage.rotation), stageOpacity: s.stage.opacity });
+
+  const L = s.line;
+  Object.assign(v, {
+    lineSettled: L.settled, lineHead: L.head, lineColor: argb(L.color), lineHeadColor: rgba(L.headColor),
+    lineSize: L.fontSize, lineWeight: L.weight, lineTracking: L.letterSpacing, lineOpacity: L.visible ? L.opacity : 0,
+  });
+
+  // The per-glyph entry follows whichever text is being typed.
+  const enter = s.final.visible ? s.final.enter : L.enter;
+  const em = s.final.visible ? s.final.fontSize : L.fontSize;
+  Object.assign(v, {
+    enterFrom: enter.index, enterTo: enter.index + 1, enterX: enter.x * em, enterY: enter.y * em, enterScale: enter.scale,
+    enterRotation: deg(enter.rotation), enterOpacity: enter.opacity, enterStrength: enter.strength,
+  });
+  const d = s.display.visible ? s.display.distortion : L.distortion;
+  const dem = s.display.visible ? s.display.fontSize : L.fontSize;
+  Object.assign(v, {
+    distFrom: d.from, distTo: d.to, distFalloffFrom: d.falloffFrom, distFalloffTo: d.falloffTo, distX: d.x * dem, distY: d.y * dem,
+    distRotation: deg(d.rotation), distScaleX: d.scaleX, distScaleY: d.scaleY, distOpacity: d.opacity, distStrength: d.strength,
+  });
+
+  const D = s.display;
+  Object.assign(v, {
+    displayText: D.text, displaySize: D.fontSize, displayWeight: D.weight, displayTracking: D.letterSpacing, displayOpacity: D.visible ? D.opacity : 0,
+    displayTop: argb(D.gradientTop), displayBottom: argb(D.gradientBottom), // Text-local y runs down from the top of the line box: cap top ≈ 0.25 em, descender bottom ≈ 1.21 em (Inter).
+    displayGradStartY: 0.25 * D.fontSize, displayGradEndY: 1.21 * D.fontSize,
+    hideLeftTo: D.hideLeftTo, hideLeftFalloff: D.hideLeftTo - D.softness, hideRightFrom: D.hideRightFrom, hideRightFalloff: D.hideRightFrom + D.softness,
+  });
+
+  const F = s.final;
+  Object.assign(v, {
+    finalSettled: F.settled, finalHead: F.head, finalEntering: F.entering, finalColor: argb(F.color), finalHeadColor: rgba(F.headColor),
+    finalEnteringColor: rgba(F.enteringColor), finalSize: F.fontSize, finalWeight: F.weight, finalTracking: F.letterSpacing,
+    finalOpacity: F.visible ? F.opacity : 0,
+  });
+
+  const K = s.cursor;
+  const text = K.attach === 'final' ? F.settled + F.head + F.entering : L.settled + L.head;
+  Object.assign(v, {
+    cursorW: K.width, cursorH: K.height, cursorStroke: K.stroke, cursorRadius: K.radius,
+    cursorStrokeColor: argb(K.color, K.solid ? 0 : 1), cursorFillColor: argb(K.color, K.solid ? 1 : 0),
+    cursorOffset: text === '' ? 0 : K.gap + K.width / 2, cursorScale: K.scale,
+    cursorLineOpacity: K.visible && K.attach === 'line' ? K.opacity : 0, cursorFinalOpacity: K.visible && K.attach === 'final' ? K.opacity : 0,
+    cursorGlowOpacity: K.visible ? K.glow.opacity : 0, cursorGlowColor: argb(K.glow.color), cursorGlowR: K.glow.radius,
+  });
+
+  const G = s.headGlow;
+  Object.assign(v, {
+    glowColor: argb(G.color), glowMid: argb(G.color, 0.7), glowFalloff: G.falloff, glowR: G.rx, glowScaleY: G.rx > 0 ? G.ry / G.rx : 1,
+    glowX: G.offsetX, glowY: G.offsetY,
+    glowNormal: G.blend === 'normal' ? G.opacity : 0, glowScreen: G.blend === 'screen' ? G.opacity : 0, glowAdditive: G.blend === 'additive' ? G.opacity : 0,
+  });
+
+  const B = s.brackets;
+  Object.assign(v, {
+    brOpacity: B.visible ? B.opacity : 0, brColor: argb(B.color), brThick: B.thickness, brHalfH: B.height / 2, brSerif: B.serif,
+    brLeftX: -B.padding + B.leftOffset, brRightX: B.padding + B.rightOffset, brLeftTrim: B.leftTrim, brRightTrim: B.rightTrim,
+    brLeftOpacity: B.leftOpacity, brRightOpacity: B.rightOpacity, brGlowOpacity: B.visible ? B.glow.opacity : 0, brGlowColor: argb(B.glow.color), brGlowR: B.glow.radius,
+  });
+
+  const R = s.brace;
+  Object.assign(v, {
+    braceOpacity: R.visible ? R.opacity : 0, braceColor: argb(R.color), braceSize: R.size * F.fontSize, braceWeight: R.weight,
+    braceLeftX: -R.padding, braceRightX: R.padding + R.closingSlack, braceY: R.offsetY, braceClosing: R.closingVisible,
+    braceGlowOpacity: R.visible ? R.glow.opacity : 0, braceGlowColor: argb(R.glow.color), braceGlowR: R.glow.radius,
+  });
+  return v;
+}

package/src/motion/replication2/template.ts

@@ -0,0 +1,33 @@
+import type { ConfigurableMotionTemplate } from '../types';
+import { configJsonSchema, defaultConfig } from './config';
+import { CONTROLS, GROUPS } from './controls';
+import { outputDuration } from './engine';
+import { PRESET_PATCHES } from './presets';
+import { RIVE_ARTBOARD, RIVE_STATE_MACHINE, RIVE_VIEW_MODEL } from './rive-contract';
+
+/**
+ * **replication-2 in the motion registry.** A configurable-motion template rendered by Rive: unlike
+ * the DOM templates, its timing and motion are part of the schema (DECISIONS §25), and people and
+ * agents edit the same canonical config. Plain data — safe to JSON-serialise.
+ */
+export const replication2: ConfigurableMotionTemplate = {
+  id: 'replication-2',
+  version: '1.0.0',
+  kind: 'configurableMotion',
+  renderer: 'rive',
+  title: 'Replication 2 — typed question to brace mark',
+  description: 'A cursor settles, a question types itself in with placeholder glyphs and a head glow, brackets frame it, it collapses, a display line tracks in, and a hard cut to white reveals words added inside blue braces. Every timing, easing, colour, size and word is configurable.',
+  fps: 60,
+  formats: [
+    { id: 'landscape', aspectRatio: '16:9', width: 3840, height: 2160 },
+    { id: 'portrait', aspectRatio: '9:16', width: 2160, height: 3840 },
+    { id: 'square', aspectRatio: '1:1', width: 2160, height: 2160 },
+  ],
+  durationInFrames: outputDuration(defaultConfig()),
+  groups: [...GROUPS],
+  controls: CONTROLS,
+  schema: configJsonSchema(),
+  presets: PRESET_PATCHES,
+  rive: { file: 'rive/replication-2/replication-2.riv', artboard: RIVE_ARTBOARD, stateMachine: RIVE_STATE_MACHINE, viewModel: RIVE_VIEW_MODEL },
+  exampleContent: defaultConfig(),
+};

package/src/motion/sample.ts

@@ -0,0 +1,173 @@
+import type { AnimatedProperty, Keyframe, MotionContract, MotionFormat, Track } from './types';
+import { ease } from './easing';
+
+/**
+ * **Frame → style, from the motion contract.** Pure and deterministic: the same (target, frame) gives
+ * the same style in Remotion, in the HTML runtime and in a test.
+ *
+ * Colours are `#rrggbb` or a theme token name. A token becomes `var(--cp-<token>)`, and a blend
+ * between two tokens becomes `color-mix()`, so a theme changes colours without touching motion.
+ */
+export type TargetStyle = {
+  transform?: string;
+  left?: string;
+  top?: string;
+  opacity?: string;
+  filter?: string;
+  clipPath?: string;
+  color?: string;
+};
+
+const round = (n: number) => Number(n.toFixed(3));
+const isHex = (v: string) => v.startsWith('#');
+const colorRef = (v: string) => (isHex(v) ? v : `var(--cp-${v})`);
+
+function mixColor(a: string, b: string, t: number): string {
+  if (isHex(a) && isHex(b)) {
+    const pa = parseInt(a.slice(1), 16), pb = parseInt(b.slice(1), 16);
+    const ch = (p: number, s: number) => (p >> s) & 255;
+    const mix = (s: number) => Math.round(ch(pa, s) + (ch(pb, s) - ch(pa, s)) * t);
+    // Interpolating between two author-set motion colours; this is arithmetic, not a design colour.
+    // eslint-disable-next-line comppack/no-raw-colour
+    return `rgb(${mix(16)}, ${mix(8)}, ${mix(0)})`;
+  }
+  return `color-mix(in srgb, ${colorRef(b)} ${round(t * 100)}%, ${colorRef(a)})`;
+}
+
+/** The value of one track at a scene-relative frame. Clamped outside the first/last keyframe. */
+export function valueAt(keyframes: Keyframe[], frame: number): number | string {
+  const first = keyframes[0]!;
+  if (frame <= first.f) return first.v;
+  for (let i = 1; i < keyframes.length; i++) {
+    const b = keyframes[i]!;
+    if (frame < b.f) {
+      const a = keyframes[i - 1]!;
+      const t = ease(b.e, (frame - a.f) / (b.f - a.f));
+      if (typeof a.v === 'string' || typeof b.v === 'string') {
+        return t >= 1 ? b.v : t <= 0 ? a.v : mixColor(String(a.v), String(b.v), t);
+      }
+      return a.v + (b.v - a.v) * t;
+    }
+  }
+  return keyframes[keyframes.length - 1]!.v;
+}
+
+/**
+ * `scene` scopes the lookup to one timeline. A sequence template's timelines share target names
+ * (every item has a `word`), so its callers always pass it; fixed templates may leave it out.
+ */
+export type Sampler = (target: string, sceneFrame: number, scene?: string) => TargetStyle;
+
+const FILTER_ID = /^[a-z][a-z0-9-]*$/;
+
+/** Index a motion contract once; the returned sampler answers per (target, frame). */
+export function createSampler(motion: MotionContract): Sampler {
+  const all = new Map<string, Track[]>();
+  const byScene = new Map<string, Map<string, Track[]>>();
+  for (const s of motion.scenes) {
+    const own = new Map<string, Track[]>();
+    byScene.set(s.id, own);
+    for (const t of s.tracks) {
+      all.set(t.target, [...(all.get(t.target) ?? []), t]);
+      own.set(t.target, [...(own.get(t.target) ?? []), t]);
+    }
+  }
+
+  return (target, frame, scene) => {
+    const tracks = (scene === undefined ? all : byScene.get(scene))?.get(target);
+    if (!tracks) return {};
+    const v: Partial<Record<AnimatedProperty, number | string>> = {};
+    for (const t of tracks) v[t.property] = valueAt(t.keyframes, frame);
+    const num = (p: AnimatedProperty, d: number) => (typeof v[p] === 'number' ? round(v[p] as number) : d);
+
+    const style: TargetStyle = {};
+    if (['x', 'y', 'rotate', 'scale', 'scaleX', 'scaleY'].some((p) => p in v)) {
+      const s = num('scale', 1);
+      style.transform = `translate(${num('x', 0)}px, ${num('y', 0)}px) rotate(${num('rotate', 0)}deg) scale(${round(s * num('scaleX', 1))}, ${round(s * num('scaleY', 1))})`;
+    }
+    if ('left' in v) style.left = `${num('left', 0)}%`;
+    if ('top' in v) style.top = `${num('top', 0)}px`;
+    if ('opacity' in v) style.opacity = String(num('opacity', 1));
+    /* An fx is one of the template's own SVG filters, by id; ids are checked so a value can only
+       ever be a local reference. It runs before the blur. */
+    const fx = typeof v.fx === 'string' && v.fx !== 'none' && FILTER_ID.test(v.fx) ? `url(#${v.fx})` : '';
+    const blur = 'blur' in v ? `blur(${num('blur', 0)}px)` : '';
+    if (fx || blur) style.filter = [fx, blur].filter(Boolean).join(' ');
+    if ('clipRight' in v || 'clipLeft' in v) style.clipPath = `inset(0% ${num('clipRight', 0)}% 0% ${num('clipLeft', 0)}%)`;
+    if ('color' in v) {
+      const c = String(v.color);
+      style.color = c.startsWith('#') || c.startsWith('rgb') || c.startsWith('color-mix') ? c : colorRef(c);
+    }
+    return style;
+  };
+}
+
+/**
+ * One scene as it plays for some content. `scene` is the timeline that animates it. `key` is the
+ * `[data-scene]` it shows: the scene id, or `<list>.<index>` for a sequence item. `item` is that
+ * item's index.
+ */
+export type PlayedScene = { key: string; scene: string; item?: number; from: number; durationInFrames: number };
+
+const listOf = (motion: MotionContract, content: unknown): Record<string, unknown>[] => {
+  const seq = motion.sequence!;
+  const list = seq.path.split('.').reduce<unknown>((v, k) => (v && typeof v === 'object' ? (v as Record<string, unknown>)[k] : undefined), content);
+  return Array.isArray(list) ? (list as Record<string, unknown>[]) : [];
+};
+
+/** The item's timeline: its `motionField` choice, or the first option when it has none. */
+export function itemScene(motion: MotionContract, item: Record<string, unknown> | undefined): string {
+  const seq = motion.sequence!;
+  const chosen = item?.[seq.motionField];
+  return typeof chosen === 'string' && seq.options[seq.motionField]?.includes(chosen) ? chosen : seq.options[seq.motionField]![0]!;
+}
+
+/** What plays, in order, for this content. Deterministic: content → the same timeline every time. */
+export function playlist(motion: MotionContract, content: unknown): PlayedScene[] {
+  if (!motion.sequence) return activeScenes(motion, content).map((s) => ({ key: s.id, scene: s.id, from: s.from, durationInFrames: s.durationInFrames }));
+  const { rhythm, path } = motion.sequence;
+  let from = 0;
+  return listOf(motion, content).map((item, i) => {
+    const scene = itemScene(motion, item);
+    const min = motion.scenes.find((s) => s.id === scene)?.durationInFrames ?? 1;
+    const durationInFrames = Math.max(rhythm[Math.min(i, rhythm.length - 1)] ?? min, min);
+    const played = { key: `${path}.${i}`, scene, item: i, from, durationInFrames };
+    from += durationInFrames;
+    return played;
+  });
+}
+
+/** The scenes that play for this content: optional scenes whose content is absent are dropped. */
+export function activeScenes(motion: MotionContract, content: unknown) {
+  const c = (content ?? {}) as Record<string, unknown>;
+  return motion.scenes.filter((s) => !s.optional || (c[s.id] !== undefined && c[s.id] !== null));
+}
+
+/** Total length for this content. */
+export function durationFor(motion: MotionContract, content: unknown) {
+  return playlist(motion, content).reduce((end, s) => Math.max(end, s.from + s.durationInFrames), 0);
+}
+
+/**
+ * Which scene is on screen at an absolute frame, and its scene-relative frame. `id` is what the
+ * markup shows (`[data-scene]`); `scene` is the timeline that animates it.
+ */
+export function sceneAt(motion: MotionContract, frame: number, content?: unknown): { id: string; scene: string; item?: number; frame: number } | null {
+  const scenes = content === undefined && !motion.sequence ? playlist(motion, Object.fromEntries(motion.scenes.map((s) => [s.id, {}]))) : playlist(motion, content);
+  for (const s of scenes) {
+    if (frame >= s.from && frame < s.from + s.durationInFrames) return { id: s.key, scene: s.scene, ...(s.item === undefined ? {} : { item: s.item }), frame: frame - s.from };
+  }
+  return null;
+}
+
+/** The canvas for this content: the format its `aspectRatio` names, else the template's default. */
+export function formatFor(motion: MotionContract, content?: unknown): MotionFormat {
+  const wanted = (content as { aspectRatio?: unknown } | undefined)?.aspectRatio;
+  const formats = motion.formats ?? [];
+  return formats.find((f) => f.aspectRatio === wanted) ?? formats[0] ?? { id: 'default', aspectRatio: `${motion.width}:${motion.height}`, width: motion.width, height: motion.height };
+}
+
+/** Theme tokens → the CSS custom properties the template's styles read. */
+export function themeVariables(theme: Record<string, string> | undefined): Record<string, string> {
+  return Object.fromEntries(Object.entries(theme ?? {}).map(([k, v]) => [`--cp-${k}`, v]));
+}