@agent-native/core 0.80.9 → 0.80.10

package/corpus/templates/design/shared/motion-compiler.ts

@@ -0,0 +1,278 @@
+/**
+ * Pure, side-effect-free motion compiler for the Design Studio (§6.3).
+ *
+ * Converts a `MotionTimeline` (JSON tracks) into a single managed
+ * `<style data-agent-native-motion>` block and back again.
+ *
+ * Guarantees:
+ * - **Deterministic**: given the same input, output is byte-identical.
+ * - **Targets by node id**: rules use `[data-agent-native-node-id="<id>"]`
+ *   selectors — no class/id coupling.
+ * - **Reduced-motion safe**: always emits an
+ *   `@media (prefers-reduced-motion: reduce)` block that disables every
+ *   generated animation.
+ * - **No dependencies**: uses djb2 (not crypto) for hashing.
+ */
+
+import type {
+  MotionEase,
+  MotionKeyframe,
+  MotionTimeline,
+  MotionTrack,
+} from "./motion-timeline";
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/** Result of {@link compile}. */
+export interface CompileResult {
+  /**
+   * Full CSS string — the body of the managed `<style data-agent-native-motion>`
+   * block (no enclosing tag).
+   */
+  css: string;
+  /**
+   * djb2 decimal hash of `css`. Stored in `motion_timeline.compiled_hash` so
+   * `apply-motion-edit` can detect drift between the JSON tracks and the CSS.
+   */
+  hash: string;
+}
+
+/**
+ * Compile a `MotionTimeline` into the CSS body of the managed style block.
+ *
+ * Output order (deterministic):
+ * 1. `@keyframes` blocks, sorted by animation name.
+ * 2. Element animation rules, sorted by node id then property.
+ * 3. `@media (prefers-reduced-motion: reduce)` block.
+ */
+export function compile(timeline: MotionTimeline): CompileResult {
+  const { tracks, durationMs, defaultEase } = timeline;
+
+  if (!tracks || tracks.length === 0) {
+    const css = reducedMotionBlock([]);
+    return { css, hash: djb2(css) };
+  }
+
+  const animNames: string[] = [];
+  const kfBlocks: string[] = [];
+  const ruleBlocks: string[] = [];
+
+  // Sort tracks for determinism: targetNodeId ASC, property ASC.
+  const sorted = [...tracks].sort((a, b) => {
+    const cmp = a.targetNodeId.localeCompare(b.targetNodeId);
+    return cmp !== 0 ? cmp : a.property.localeCompare(b.property);
+  });
+
+  for (const track of sorted) {
+    const { targetNodeId, property, keyframes } = track;
+    if (!keyframes || keyframes.length === 0) continue;
+
+    const name = animationName(targetNodeId, property);
+    animNames.push(name);
+    kfBlocks.push(keyframesBlock(name, property, keyframes, defaultEase));
+
+    const dur = formatDuration(durationMs);
+    const ease = keyframes[0]?.ease ?? defaultEase;
+    ruleBlocks.push(
+      `[data-agent-native-node-id="${escAttr(targetNodeId)}"] {\n` +
+        `  animation-name: ${name};\n` +
+        `  animation-duration: ${dur};\n` +
+        `  animation-timing-function: ${ease};\n` +
+        `  animation-fill-mode: both;\n` +
+        `}`,
+    );
+  }
+
+  const css = [...kfBlocks, ...ruleBlocks, reducedMotionBlock(animNames)].join(
+    "\n\n",
+  );
+  return { css, hash: djb2(css) };
+}
+
+/**
+ * Parse the CSS body of a managed `<style data-agent-native-motion>` block
+ * back into `MotionTrack[]`.
+ *
+ * Best-effort round-trip. Does not recover `durationMs` or `defaultEase`
+ * (those live on the DB row). Sufficient for drift detection and basic
+ * editing recovery.
+ */
+export function parse(css: string): MotionTrack[] {
+  const tracks: MotionTrack[] = [];
+  const kfRe = /@keyframes\s+(an-motion-[^\s{]+)\s*\{/g;
+  let m: RegExpExecArray | null;
+
+  while ((m = kfRe.exec(css)) !== null) {
+    const fullName = m[1];
+    const decoded = decodeAnimationName(fullName);
+    if (!decoded) continue;
+
+    const bodyStart = m.index + m[0].length;
+    const body = extractBlock(css, bodyStart);
+    if (body === null) continue;
+
+    tracks.push({
+      targetNodeId: decoded.targetNodeId,
+      property: decoded.property,
+      keyframes: parseKeyframeBody(body),
+    });
+  }
+
+  return tracks;
+}
+
+/**
+ * Return the djb2 hash of a CSS string — useful for verifying stored
+ * `compiled_hash` values without re-compiling a full timeline.
+ */
+export function hashCss(css: string): string {
+  return djb2(css);
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Build a deterministic CSS animation name from a node id and CSS property.
+ * Non-ident characters are replaced with `_`.
+ *
+ * Format: `an-motion-<nodeId>--<property>`
+ */
+function animationName(nodeId: string, property: string): string {
+  const safe = (s: string) => s.replace(/[^a-zA-Z0-9-]/g, "_");
+  return `an-motion-${safe(nodeId)}--${safe(property)}`;
+}
+
+/** Reverse `animationName` — returns `null` when the name doesn't match. */
+function decodeAnimationName(
+  name: string,
+): { targetNodeId: string; property: string } | null {
+  const prefix = "an-motion-";
+  if (!name.startsWith(prefix)) return null;
+  const rest = name.slice(prefix.length);
+  const sep = rest.indexOf("--");
+  if (sep === -1) return null;
+  return { targetNodeId: rest.slice(0, sep), property: rest.slice(sep + 2) };
+}
+
+/**
+ * Build a `@keyframes` block for one (property, keyframes) pair.
+ * Each stop sets `animation-timing-function` to control easing to the NEXT
+ * stop (standard CSS keyframe easing semantics).
+ */
+function keyframesBlock(
+  name: string,
+  property: string,
+  keyframes: MotionKeyframe[],
+  defaultEase: MotionEase,
+): string {
+  const sorted = [...keyframes].sort((a, b) => a.t - b.t);
+  const stops = sorted.map((kf) => {
+    const pct = formatPercent(kf.t);
+    const ease = kf.ease ?? defaultEase;
+    return (
+      `  ${pct} {\n` +
+      `    ${property}: ${kf.value};\n` +
+      `    animation-timing-function: ${ease};\n` +
+      `  }`
+    );
+  });
+  return `@keyframes ${name} {\n${stops.join("\n")}\n}`;
+}
+
+/**
+ * Build the `@media (prefers-reduced-motion: reduce)` block.
+ * Always emitted so managed blocks are easily identified by parsers.
+ */
+function reducedMotionBlock(names: string[]): string {
+  if (names.length === 0) {
+    return `@media (prefers-reduced-motion: reduce) {\n  /* no animations */\n}`;
+  }
+  // Disable every named animation on any element that carries it.
+  const selector = names.map((n) => `[style*="${n}"]`).join(",\n  ");
+  return (
+    `@media (prefers-reduced-motion: reduce) {\n` +
+    `  ${selector},\n` +
+    `  [data-agent-native-node-id] {\n` +
+    `    animation: none !important;\n` +
+    `  }\n` +
+    `}`
+  );
+}
+
+/** Format a millisecond duration as a CSS `<time>` value with trailing zeros stripped. */
+function formatDuration(ms: number): string {
+  const s = (ms / 1000).toFixed(3).replace(/\.?0+$/, "");
+  return `${s}s`;
+}
+
+/** Format a normalised time `t ∈ [0, 1]` as a CSS percentage string. */
+function formatPercent(t: number): string {
+  if (t <= 0) return "0%";
+  if (t >= 1) return "100%";
+  const pct = Math.round(t * 10000) / 100;
+  return `${pct}%`;
+}
+
+/**
+ * Escape a string for safe use as a CSS attribute selector value.
+ * Escapes `\` and `"`.
+ */
+function escAttr(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * Find the content of the CSS block that starts just after position `start`
+ * (i.e., just after the opening `{`). Returns `null` on unbalanced braces.
+ */
+function extractBlock(css: string, start: number): string | null {
+  let depth = 1;
+  let i = start;
+  while (i < css.length && depth > 0) {
+    if (css[i] === "{") depth++;
+    else if (css[i] === "}") depth--;
+    i++;
+  }
+  if (depth !== 0) return null;
+  return css.slice(start, i - 1);
+}
+
+/** Parse the interior of a `@keyframes` block into `MotionKeyframe[]`. */
+function parseKeyframeBody(body: string): MotionKeyframe[] {
+  const frames: MotionKeyframe[] = [];
+  const stopRe = /([\d.]+%|from|to)\s*\{([^}]*)\}/g;
+  let m: RegExpExecArray | null;
+
+  while ((m = stopRe.exec(body)) !== null) {
+    const pctStr = m[1];
+    const content = m[2];
+    const t =
+      pctStr === "from" ? 0 : pctStr === "to" ? 1 : parseFloat(pctStr) / 100;
+
+    const easeMatch = content.match(/animation-timing-function\s*:\s*([^;]+)/);
+    const ease = easeMatch ? (easeMatch[1].trim() as MotionEase) : undefined;
+
+    // Extract the first non-timing property as the animated value.
+    const propMatch = content.match(
+      /^(?!.*animation-timing-function)[a-zA-Z-]+\s*:\s*([^;]+)/m,
+    );
+    const value = propMatch ? propMatch[1].trim() : "";
+
+    frames.push({ t, value, ...(ease !== undefined ? { ease } : {}) });
+  }
+
+  return frames;
+}
+
+/**
+ * djb2 string hash — deterministic, no crypto dependency.
+ * Returns a 32-bit unsigned integer as a decimal string.
+ */
+function djb2(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    // eslint-disable-next-line no-bitwise
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(10);
+}

package/corpus/templates/design/shared/motion-timeline.ts

@@ -0,0 +1,193 @@
+/**
+ * Motion timeline types for the Design Studio motion dock (§6.3 + §4.3).
+ *
+ * A MotionTimeline compiles into a managed `<style data-agent-native-motion>`
+ * block. The CSS is the runtime truth; the JSON `tracks` aid editing only.
+ * `compiledHash` keeps the two in lockstep — `apply-motion-edit` must update
+ * both atomically.
+ */
+
+export type MotionEase =
+  | "linear"
+  | "ease"
+  | "ease-in"
+  | "ease-out"
+  | "ease-in-out"
+  | "step-start"
+  | "step-end"
+  | string; // cubic-bezier(...) or steps(...)
+
+export interface MotionKeyframe {
+  /** Normalised time in [0, 1] where 0 = 0% and 1 = 100% of `durationMs`. */
+  t: number;
+  /** CSS property value at this keyframe (e.g. "0px", "1", "#ff0000"). */
+  value: string;
+  /** Per-keyframe easing applied between this keyframe and the next. */
+  ease?: MotionEase;
+}
+
+/**
+ * One property track for a single target node.
+ * A node may have multiple tracks (e.g. opacity + transform).
+ */
+export interface MotionTrack {
+  /** Matches `data-agent-native-node-id` stamped on the target DOM element. */
+  targetNodeId: string;
+  /** CSS property name being animated (e.g. "opacity", "transform", "color"). */
+  property: string;
+  keyframes: MotionKeyframe[];
+}
+
+/**
+ * A complete animation timeline scoped to one design + source + screen/file.
+ * A design may have many timelines (one per screen or logical animation group).
+ */
+export interface MotionTimeline {
+  id: string;
+  designId: string;
+  /**
+   * Opaque source reference identifying the screen or file this timeline
+   * belongs to (fileId for inline designs, routeId for localhost/fusion).
+   * `null` when scoped to the entire design.
+   */
+  sourceRef: string | null;
+  /**
+   * File path for real-app CSS module output.
+   * `null` for inline designs (CSS lives in the managed `<style>` block).
+   */
+  filePath: string | null;
+  tracks: MotionTrack[];
+  /** Total animation duration in milliseconds. */
+  durationMs: number;
+  /** Default easing applied to keyframe intervals that omit a per-keyframe ease. */
+  defaultEase: MotionEase;
+  /**
+   * Hash of the compiled CSS output. Used by `apply-motion-edit` to detect
+   * drift between the stored JSON tracks and the managed `<style>` block.
+   * Cleared to `null` when tracks are edited but CSS has not yet been recompiled.
+   */
+  compiledHash: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ─── Animatable-property catalog + track factory ──────────────────────────────
+//
+// Shared by the MotionDock UI (the "add a track" picker) and unit tests. These
+// are pure helpers so the first-track-creation flow can be tested without
+// mounting React. They power the "create the FIRST track" path: a freshly
+// selected element has no tracks, so the dock seeds a default track from one of
+// these presets and the keyframes below.
+
+/**
+ * One animatable-property preset offered when creating a brand-new track.
+ * `from`/`to` seed the two default keyframes so the track is immediately
+ * compilable and previewable (a track with < 1 keyframe is rejected by
+ * `apply-motion-edit`).
+ */
+export interface MotionPropertyPreset {
+  /** CSS property animated by the track (e.g. "opacity", "transform"). */
+  property: string;
+  /** Human-readable label for the picker (e.g. "Opacity", "Slide up"). */
+  label: string;
+  /** Value at t = 0. */
+  from: string;
+  /** Value at t = 1. */
+  to: string;
+}
+
+/**
+ * Built-in property presets for the "add a track" picker. Ordered most-common
+ * first. Every preset is a valid CSS identifier accepted by
+ * `assertSafeCssProperty` and yields two safe keyframe values.
+ */
+export const MOTION_PROPERTY_PRESETS: MotionPropertyPreset[] = [
+  { property: "opacity", label: "Fade (opacity)", from: "0", to: "1" },
+  {
+    property: "transform",
+    label: "Slide up (translateY)",
+    from: "translateY(16px)",
+    to: "translateY(0px)",
+  },
+  {
+    property: "transform",
+    label: "Scale (zoom in)",
+    from: "scale(0.8)",
+    to: "scale(1)",
+  },
+  {
+    property: "filter",
+    label: "Blur in",
+    from: "blur(8px)",
+    to: "blur(0px)",
+  },
+  {
+    property: "color",
+    label: "Color",
+    from: "#000000",
+    to: "#000000",
+  },
+  {
+    property: "background-color",
+    label: "Background color",
+    from: "#ffffff",
+    to: "#ffffff",
+  },
+];
+
+/**
+ * Build a brand-new {@link MotionTrack} for a target node + property, seeded
+ * with two keyframes (start/end) so it is immediately valid for both the live
+ * preview bridge and the `apply-motion-edit` "Write to CSS" commit. Used by the
+ * MotionDock "create first track" path.
+ *
+ * When `preset` is omitted, a neutral 0 → 1 opacity-style pair is used so the
+ * track still compiles; callers normally pass a {@link MotionPropertyPreset}.
+ */
+export function createMotionTrack(
+  targetNodeId: string,
+  property: string,
+  options: { from?: string; to?: string; ease?: MotionEase } = {},
+): MotionTrack {
+  const from = options.from ?? "0";
+  const to = options.to ?? "1";
+  return {
+    targetNodeId,
+    property,
+    keyframes: [
+      { t: 0, value: from, ...(options.ease ? { ease: options.ease } : {}) },
+      { t: 1, value: to, ...(options.ease ? { ease: options.ease } : {}) },
+    ],
+  };
+}
+
+/**
+ * Build a track from a {@link MotionPropertyPreset}. Thin wrapper over
+ * {@link createMotionTrack} that forwards the preset's seed values.
+ */
+export function createMotionTrackFromPreset(
+  targetNodeId: string,
+  preset: MotionPropertyPreset,
+  ease?: MotionEase,
+): MotionTrack {
+  return createMotionTrack(targetNodeId, preset.property, {
+    from: preset.from,
+    to: preset.to,
+    ease,
+  });
+}
+
+/**
+ * Return `true` when a track for the given (targetNodeId, property) pair already
+ * exists in `tracks`. The dock uses this to decide between "create a new track"
+ * and "add a keyframe to the existing track" so a property is never duplicated.
+ */
+export function hasTrackFor(
+  tracks: MotionTrack[],
+  targetNodeId: string,
+  property: string,
+): boolean {
+  return tracks.some(
+    (t) => t.targetNodeId === targetNodeId && t.property === property,
+  );
+}