@agent-native/core 0.85.6 → 0.86.0

package/corpus/templates/design/shared/full-app.ts

@@ -0,0 +1,126 @@
+/**
+ * full-app — feature flag, types, and `designs.data` helpers for fusion-backed
+ * "full app" designs.
+ *
+ * A full-app design is backed by a real running app in a Builder Fusion
+ * container (one branch per design in the configured Builder project). Its
+ * screens are URL-backed iframes of the container's dev server — the same
+ * model as visual-edit/localhost screens, but remote — and edits queue in
+ * `design_fusion_edits` until they are applied by the in-container app agent.
+ *
+ * The `fusionApp` linkage lives in the design's `data` JSON blob (additive,
+ * like `screenMetadata`/`canvasFrames`), so no schema change is needed to mark
+ * a design as app-backed.
+ */
+
+/**
+ * Master switch for full app building in the Design app.
+ *
+ * Deliberately a plain code boolean for now: flip to `true` to expose the
+ * "Full app" creation option and enable the fusion app actions. Builder
+ * credentials plus a branch project id (DISPATCH_BUILDER_PROJECT_ID /
+ * BUILDER_BRANCH_PROJECT_ID / BUILDER_PROJECT_ID) are still required at
+ * runtime — without them the actions return the standard connect CTA.
+ */
+export const FULL_APP_BUILDING_ENABLED = false;
+
+export type DesignFusionAppStatus = "building" | "ready" | "error";
+
+export interface DesignFusionApp {
+  /** Builder project id the app branch lives in. */
+  projectId: string;
+  /** Branch backing this design (one branch per design). */
+  branchName: string;
+  /** Builder visual-editor URL for the branch (progress/debugging). */
+  editorUrl?: string;
+  /** Container dev-server URL once the container is ready; iframe-able. */
+  previewUrl?: string;
+  status: DesignFusionAppStatus;
+  /** Last provisioning/progress/error message. */
+  statusMessage?: string;
+  /** Reserved hosting slug — the app publishes to https://<slug>.builder.cloud */
+  hostingSlug?: string;
+  /** Public URL of the last successful deploy. */
+  deployedUrl?: string;
+  lastDeployId?: string;
+  lastDeployStatus?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** JSON target context attached to a queued fusion edit. */
+export interface FusionEditTarget {
+  /** CSS selector or data-node id of the element the user pointed at. */
+  selector?: string;
+  /** Route path of the screen the edit applies to (e.g. "/settings"). */
+  path?: string;
+  /** Full screen URL at edit time. */
+  url?: string;
+  /** Human-readable element description ("primary button", "nav logo"). */
+  nodeName?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Parse a design's raw `data` JSON string into an object (never throws). */
+export function parseDesignDataBlob(raw: unknown): Record<string, unknown> {
+  if (isRecord(raw)) return raw;
+  if (typeof raw !== "string" || !raw.trim()) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Read the fusion app linkage from a design's `data` (raw JSON string or
+ * already-parsed object). Returns null when the design is not app-backed.
+ */
+export function readFusionApp(data: unknown): DesignFusionApp | null {
+  const blob = parseDesignDataBlob(data);
+  const app = blob.fusionApp;
+  if (!isRecord(app)) return null;
+  const projectId = typeof app.projectId === "string" ? app.projectId : "";
+  const branchName = typeof app.branchName === "string" ? app.branchName : "";
+  if (!projectId || !branchName) return null;
+  const status: DesignFusionAppStatus =
+    app.status === "ready" || app.status === "error" ? app.status : "building";
+  const str = (value: unknown): string | undefined =>
+    typeof value === "string" && value ? value : undefined;
+  return {
+    projectId,
+    branchName,
+    status,
+    editorUrl: str(app.editorUrl),
+    previewUrl: str(app.previewUrl),
+    statusMessage: str(app.statusMessage),
+    hostingSlug: str(app.hostingSlug),
+    deployedUrl: str(app.deployedUrl),
+    lastDeployId: str(app.lastDeployId),
+    lastDeployStatus: str(app.lastDeployStatus),
+    createdAt: str(app.createdAt) ?? "",
+    updatedAt: str(app.updatedAt) ?? "",
+  };
+}
+
+/**
+ * Return a new `data` object with the fusion app linkage written. Also stamps
+ * `sourceType/sourceMode: "fusion"` so capability resolution treats the design
+ * as fusion-backed. Additive — all other keys are preserved.
+ */
+export function writeFusionApp(
+  data: unknown,
+  app: DesignFusionApp,
+): Record<string, unknown> {
+  const blob = parseDesignDataBlob(data);
+  return {
+    ...blob,
+    sourceType: "fusion",
+    sourceMode: "fusion",
+    fusionApp: { ...app },
+  };
+}

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

@@ -54,7 +54,6 @@ export function compile(timeline: MotionTimeline): CompileResult {
     return { css, hash: djb2(css) };
   }
 
-  const animNames: string[] = [];
   const kfBlocks: string[] = [];
   const rulesByTarget = new Map<
     string,
@@ -77,12 +76,15 @@ export function compile(timeline: MotionTimeline): CompileResult {
     if (!keyframes || keyframes.length === 0) continue;
     assertSafeMotionCssProperty(property, "track.property");
 
+    // Sort ONCE per track: the editor may hand us keyframes in drag order, and
+    // both the stop list and the element-rule ease must read time order.
+    const sortedKeyframes = [...keyframes].sort((a, b) => a.t - b.t);
+
     const name = animationName(targetNodeId, property);
-    animNames.push(name);
-    kfBlocks.push(keyframesBlock(name, property, keyframes, defaultEase));
+    kfBlocks.push(keyframesBlock(name, property, sortedKeyframes, defaultEase));
 
     const dur = formatDuration(durationMs);
-    const ease = keyframes[0]?.ease ?? defaultEase;
+    const ease = sortedKeyframes[0]?.ease ?? defaultEase;
     assertSafeMotionCssToken(ease, "track ease");
     const targetRule = rulesByTarget.get(targetNodeId) ?? {
       names: [],
@@ -97,21 +99,24 @@ export function compile(timeline: MotionTimeline): CompileResult {
     rulesByTarget.set(targetNodeId, targetRule);
   }
 
-  const ruleBlocks = [...rulesByTarget.entries()]
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(
-      ([targetNodeId, rule]) =>
-        `[data-agent-native-node-id="${escAttr(targetNodeId)}"] {\n` +
-        `  animation-name: ${rule.names.join(", ")};\n` +
-        `  animation-duration: ${rule.durations.join(", ")};\n` +
-        `  animation-timing-function: ${rule.timings.join(", ")};\n` +
-        `  animation-fill-mode: ${rule.fillModes.join(", ")};\n` +
-        `}`,
-    );
-
-  const css = [...kfBlocks, ...ruleBlocks, reducedMotionBlock(animNames)].join(
-    "\n\n",
+  const sortedTargets = [...rulesByTarget.entries()].sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+  const ruleBlocks = sortedTargets.map(
+    ([targetNodeId, rule]) =>
+      `[data-agent-native-node-id="${escAttr(targetNodeId)}"] {\n` +
+      `  animation-name: ${rule.names.join(", ")};\n` +
+      `  animation-duration: ${rule.durations.join(", ")};\n` +
+      `  animation-timing-function: ${rule.timings.join(", ")};\n` +
+      `  animation-fill-mode: ${rule.fillModes.join(", ")};\n` +
+      `}`,
   );
+
+  const css = [
+    ...kfBlocks,
+    ...ruleBlocks,
+    reducedMotionBlock(sortedTargets.map(([targetNodeId]) => targetNodeId)),
+  ].join("\n\n");
   return { css, hash: djb2(css) };
 }
 
@@ -201,6 +206,24 @@ export function hashCss(css: string): string {
   return djb2(css);
 }
 
+/**
+ * Parse the first `animation-duration` declaration in a managed motion CSS
+ * body and return it in milliseconds, or `null` when absent/unparsable. Used
+ * by CSS-recovery so a recovered timeline keeps the compiled duration instead
+ * of inventing a default that the next save would then persist.
+ */
+export function parseFirstAnimationDurationMs(css: string): number | null {
+  const m = /animation-duration\s*:\s*([^;]+)/.exec(css);
+  if (!m) return null;
+  const first = m[1].split(",")[0].trim();
+  const value = /^([\d.]+)(ms|s)$/.exec(first);
+  if (!value) return null;
+  const n = parseFloat(value[1]);
+  if (!Number.isFinite(n)) return null;
+  const ms = value[2] === "ms" ? n : n * 1000;
+  return ms > 0 ? Math.round(ms) : null;
+}
+
 /**
  * Reject caller-supplied CSS declaration values before interpolation into the
  * managed motion stylesheet. Motion values still allow useful CSS functions
@@ -248,13 +271,18 @@ const CSS_TOKEN_CONTROL_RE = /[\u0000-\u001f\u007f]/;
 
 /**
  * Build a deterministic CSS animation name from a node id and CSS property.
- * Non-ident characters are replaced with `_`.
+ * Non-ident characters are replaced with `_`; when sanitisation changed the
+ * node id, a short hash of the RAW id is appended so distinct ids that
+ * sanitise identically (e.g. "a:b" vs "a_b") never collide.
  *
- * Format: `an-motion-<nodeId>--<property>`
+ * Format: `an-motion-<nodeId>[_<hash>]--<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)}`;
+  const safeNode = safe(nodeId);
+  const suffix =
+    safeNode === nodeId ? "" : `_${djb2Num(nodeId).toString(36).slice(-4)}`;
+  return `an-motion-${safeNode}${suffix}--${safe(property)}`;
 }
 
 /** Reverse `animationName` — returns `null` when the name doesn't match. */
@@ -299,17 +327,21 @@ function keyframesBlock(
 /**
  * Build the `@media (prefers-reduced-motion: reduce)` block.
  * Always emitted so managed blocks are easily identified by parsers.
+ *
+ * Selects ONLY the node ids that carry compiled motion rules — a blanket
+ * `[data-agent-native-node-id]` selector would disable every animation on
+ * every stamped node, including ones this compiler does not manage.
  */
-function reducedMotionBlock(names: string[]): string {
-  if (names.length === 0) {
+function reducedMotionBlock(targetNodeIds: string[]): string {
+  if (targetNodeIds.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  ");
+  const selector = targetNodeIds
+    .map((id) => `[data-agent-native-node-id="${escAttr(id)}"]`)
+    .join(",\n  ");
   return (
     `@media (prefers-reduced-motion: reduce) {\n` +
-    `  ${selector},\n` +
-    `  [data-agent-native-node-id] {\n` +
+    `  ${selector} {\n` +
     `    animation: none !important;\n` +
     `  }\n` +
     `}`
@@ -322,11 +354,18 @@ function formatDuration(ms: number): string {
   return `${s}s`;
 }
 
-/** Format a normalised time `t ∈ [0, 1]` as a CSS percentage string. */
+/**
+ * Format a normalised time `t ∈ [0, 1]` as a CSS percentage string.
+ * Interior stops are clamped away from 0% / 100% so a stop at e.g.
+ * t = 0.99997 never rounds onto a real t = 1 stop (duplicate keyframe
+ * selectors silently drop one of the two values).
+ */
 function formatPercent(t: number): string {
   if (t <= 0) return "0%";
   if (t >= 1) return "100%";
   const pct = Math.round(t * 10000) / 100;
+  if (pct >= 100) return "99.99%";
+  if (pct <= 0) return "0.01%";
   return `${pct}%`;
 }
 
@@ -415,13 +454,18 @@ function escapeRegExp(value: string): string {
 
 /**
  * djb2 string hash — deterministic, no crypto dependency.
- * Returns a 32-bit unsigned integer as a decimal string.
+ * Returns a 32-bit unsigned integer.
  */
-function djb2(str: string): string {
+function djb2Num(str: string): number {
   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);
+  return hash;
+}
+
+/** {@link djb2Num} as a decimal string (stored `compiled_hash` format). */
+function djb2(str: string): string {
+  return djb2Num(str).toString(10);
 }

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

@@ -191,3 +191,338 @@ export function hasTrackFor(
     (t) => t.targetNodeId === targetNodeId && t.property === property,
   );
 }
+
+// ─── Keyframe helpers (pure; shared by MotionDock + tests) ────────────────────
+
+/**
+ * Two keyframes closer together than this (normalised time) are treated as the
+ * same stop: upserts replace instead of accumulating invisible duplicates.
+ */
+export const MOTION_KEYFRAME_TIME_EPSILON = 0.002;
+
+/** Return a copy of `keyframes` sorted ascending by `t` (stable). */
+export function sortMotionKeyframes(
+  keyframes: MotionKeyframe[],
+): MotionKeyframe[] {
+  return [...keyframes].sort((a, b) => a.t - b.t);
+}
+
+/**
+ * Insert `keyframe` into `keyframes`, replacing any existing keyframe whose
+ * `t` is within `epsilon` of the new keyframe's time (so repeated adds at the
+ * same playhead position never accumulate invisible duplicates). Returns a new
+ * sorted array; the input is not mutated.
+ */
+export function upsertMotionKeyframeAtTime(
+  keyframes: MotionKeyframe[],
+  keyframe: MotionKeyframe,
+  epsilon: number = MOTION_KEYFRAME_TIME_EPSILON,
+): MotionKeyframe[] {
+  const withoutCurrentTime = keyframes.filter(
+    (existing) => Math.abs(existing.t - keyframe.t) > epsilon,
+  );
+  return sortMotionKeyframes([...withoutCurrentTime, keyframe]);
+}
+
+// ─── Easing evaluation ────────────────────────────────────────────────────────
+//
+// Mirrors CSS timing-function semantics closely enough for scrub preview and
+// value sampling. The canvas preview bridge carries its own dependency-free
+// copy of this algorithm (it cannot import modules); keep the two in sync.
+
+const EASE_KEYWORD_BEZIERS: Record<string, [number, number, number, number]> = {
+  ease: [0.25, 0.1, 0.25, 1],
+  "ease-in": [0.42, 0, 1, 1],
+  "ease-out": [0, 0, 0.58, 1],
+  "ease-in-out": [0.42, 0, 0.58, 1],
+};
+
+/** Evaluate y for a CSS cubic-bezier timing function at progress x ∈ [0, 1]. */
+function cubicBezierY(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  x: number,
+): number {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const cx = 3 * x1;
+  const bx = 3 * (x2 - x1) - cx;
+  const ax = 1 - cx - bx;
+  const cy = 3 * y1;
+  const by = 3 * (y2 - y1) - cy;
+  const ay = 1 - cy - by;
+  const sampleX = (u: number) => ((ax * u + bx) * u + cx) * u;
+  const sampleY = (u: number) => ((ay * u + by) * u + cy) * u;
+  const sampleDX = (u: number) => (3 * ax * u + 2 * bx) * u + cx;
+
+  // Newton-Raphson, falling back to bisection when the derivative flattens.
+  let u = x;
+  for (let i = 0; i < 8; i++) {
+    const err = sampleX(u) - x;
+    if (Math.abs(err) < 1e-6) return sampleY(u);
+    const d = sampleDX(u);
+    if (Math.abs(d) < 1e-6) break;
+    u = Math.min(1, Math.max(0, u - err / d));
+  }
+  let lo = 0;
+  let hi = 1;
+  u = x;
+  while (hi - lo > 1e-6) {
+    u = (lo + hi) / 2;
+    if (sampleX(u) < x) lo = u;
+    else hi = u;
+  }
+  return sampleY(u);
+}
+
+/**
+ * Evaluate a {@link MotionEase} timing function at linear progress `x ∈ [0, 1]`.
+ *
+ * Supports the CSS keywords (`linear`, `ease*`, `step-start`, `step-end`),
+ * `cubic-bezier(...)` (including overshoot control points, which is how the
+ * dock's "Spring" preset is expressed), `steps(n, position)`, and a `spring`
+ * keyword approximated by an overshoot bezier. Unknown values fall back to
+ * linear. The result may leave [0, 1] for overshoot beziers by design.
+ */
+export function evaluateMotionEase(
+  ease: MotionEase | undefined,
+  x: number,
+): number {
+  const clamped = x <= 0 ? 0 : x >= 1 ? 1 : x;
+  const raw = String(ease ?? "ease")
+    .trim()
+    .toLowerCase();
+  if (raw === "linear") return clamped;
+  if (raw === "step-start") return clamped > 0 ? 1 : 0;
+  if (raw === "step-end") return clamped >= 1 ? 1 : 0;
+
+  const keyword = EASE_KEYWORD_BEZIERS[raw];
+  if (keyword) {
+    return cubicBezierY(
+      keyword[0],
+      keyword[1],
+      keyword[2],
+      keyword[3],
+      clamped,
+    );
+  }
+
+  const bezier = /^cubic-bezier\(([^)]+)\)$/.exec(raw);
+  if (bezier) {
+    const parts = bezier[1].split(",").map((part) => parseFloat(part));
+    if (parts.length === 4 && parts.every((n) => Number.isFinite(n))) {
+      // x control points must stay in [0, 1] (CSS requirement); y may overshoot.
+      const x1 = Math.min(1, Math.max(0, parts[0]));
+      const x2 = Math.min(1, Math.max(0, parts[2]));
+      return cubicBezierY(x1, parts[1], x2, parts[3], clamped);
+    }
+  }
+
+  const steps = /^steps\(([^)]+)\)$/.exec(raw);
+  if (steps) {
+    const args = steps[1].split(",").map((part) => part.trim());
+    const count = parseInt(args[0], 10);
+    if (Number.isFinite(count) && count > 0) {
+      if (clamped >= 1) return 1;
+      const jumpStart = args[1] === "start" || args[1] === "jump-start";
+      return Math.min(
+        1,
+        (Math.floor(clamped * count) + (jumpStart ? 1 : 0)) / count,
+      );
+    }
+  }
+
+  // Spring approximation: a gentle overshoot bezier.
+  if (raw.startsWith("spring")) {
+    return cubicBezierY(0.34, 1.56, 0.64, 1, clamped);
+  }
+
+  return clamped;
+}
+
+// ─── Value sampling ───────────────────────────────────────────────────────────
+
+type MotionValueSegment =
+  | { kind: "lit"; text: string }
+  | { kind: "num"; value: number; unit: string };
+
+function formatSampledNumber(n: number): string {
+  if (!Number.isFinite(n)) return "0";
+  return (Math.round(n * 10000) / 10000).toString();
+}
+
+/** Parse a hex / rgb(a) CSS color into [r, g, b, a], or null. */
+function parseSimpleColor(
+  value: string,
+): [number, number, number, number] | null {
+  const s = value.trim();
+  const hex = /^#([0-9a-fA-F]{3,8})$/.exec(s);
+  if (hex) {
+    const h = hex[1];
+    if (h.length === 3 || h.length === 4) {
+      return [
+        parseInt(h[0] + h[0], 16),
+        parseInt(h[1] + h[1], 16),
+        parseInt(h[2] + h[2], 16),
+        h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
+      ];
+    }
+    if (h.length === 6 || h.length === 8) {
+      return [
+        parseInt(h.slice(0, 2), 16),
+        parseInt(h.slice(2, 4), 16),
+        parseInt(h.slice(4, 6), 16),
+        h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
+      ];
+    }
+    return null;
+  }
+  const rgb = /^rgba?\(([^)]+)\)$/i.exec(s);
+  if (rgb) {
+    const parts = rgb[1].split(/[\s,/]+/).filter((p) => p.length > 0);
+    if (parts.length >= 3) {
+      const alpha = parts[3];
+      return [
+        parseFloat(parts[0]),
+        parseFloat(parts[1]),
+        parseFloat(parts[2]),
+        alpha === undefined
+          ? 1
+          : alpha.endsWith("%")
+            ? parseFloat(alpha) / 100
+            : parseFloat(alpha),
+      ];
+    }
+  }
+  return null;
+}
+
+function formatSampledColor(c: [number, number, number, number]): string {
+  const clamp255 = (x: number) => Math.round(Math.min(255, Math.max(0, x)));
+  const a = Math.min(1, Math.max(0, c[3]));
+  if (a >= 1) {
+    return `rgb(${clamp255(c[0])}, ${clamp255(c[1])}, ${clamp255(c[2])})`;
+  }
+  return `rgba(${clamp255(c[0])}, ${clamp255(c[1])}, ${clamp255(c[2])}, ${Math.round(a * 1000) / 1000})`;
+}
+
+function tokenizeMotionValue(value: string): MotionValueSegment[] {
+  const segs: MotionValueSegment[] = [];
+  const numRe = /^[+-]?(?:\d+\.?\d*|\.\d+)/;
+  let i = 0;
+  let litStart = 0;
+  while (i < value.length) {
+    // Skip numbers glued to an identifier (translate3d, matrix3d, …) or a hex
+    // color literal — those belong to the literal chunk, not a numeric arg.
+    const prev = i > 0 ? value[i - 1] : "";
+    if (!/[a-zA-Z#]/.test(prev)) {
+      const nm = numRe.exec(value.slice(i));
+      if (nm) {
+        const um = /^[a-z%]+/i.exec(value.slice(i + nm[0].length));
+        const unit = um ? um[0] : "";
+        if (i > litStart) {
+          segs.push({ kind: "lit", text: value.slice(litStart, i) });
+        }
+        segs.push({ kind: "num", value: parseFloat(nm[0]), unit });
+        i += nm[0].length + unit.length;
+        litStart = i;
+        continue;
+      }
+    }
+    i++;
+  }
+  if (value.length > litStart) {
+    segs.push({ kind: "lit", text: value.slice(litStart) });
+  }
+  return segs;
+}
+
+function segmentShape(segs: MotionValueSegment[]): string {
+  return segs
+    .map((seg) =>
+      seg.kind === "lit" ? `L${seg.text}` : `N${seg.unit || "<none>"}`,
+    )
+    .join(" ");
+}
+
+/**
+ * Linearly interpolate two CSS values at `ratio`. Handles matching numeric
+ * skeletons (`translateY(16px)` → `translateY(0px)`) and simple colors
+ * (hex / rgb(a)); anything non-interpolable holds the `from` value.
+ * `ratio` may leave [0, 1] for overshoot easing.
+ */
+export function lerpMotionValues(
+  from: string,
+  to: string,
+  ratio: number,
+): string {
+  if (from === to) return from;
+  const colorFrom = parseSimpleColor(from);
+  const colorTo = parseSimpleColor(to);
+  if (colorFrom && colorTo) {
+    return formatSampledColor([
+      colorFrom[0] + (colorTo[0] - colorFrom[0]) * ratio,
+      colorFrom[1] + (colorTo[1] - colorFrom[1]) * ratio,
+      colorFrom[2] + (colorTo[2] - colorFrom[2]) * ratio,
+      colorFrom[3] + (colorTo[3] - colorFrom[3]) * ratio,
+    ]);
+  }
+  const fromSegs = tokenizeMotionValue(from);
+  const toSegs = tokenizeMotionValue(to);
+  if (
+    fromSegs.length === toSegs.length &&
+    segmentShape(fromSegs) === segmentShape(toSegs)
+  ) {
+    let out = "";
+    let interpolated = false;
+    for (let i = 0; i < fromSegs.length; i++) {
+      const a = fromSegs[i];
+      const b = toSegs[i];
+      if (a.kind === "lit") {
+        out += a.text;
+        continue;
+      }
+      if (b.kind !== "num") return from;
+      interpolated = true;
+      out +=
+        formatSampledNumber(a.value + (b.value - a.value) * ratio) +
+        (a.unit || b.unit);
+    }
+    if (interpolated) return out;
+  }
+  return from;
+}
+
+/**
+ * Sample the value of a keyframe list at normalised time `t ∈ [0, 1]`,
+ * honouring per-keyframe easing (each keyframe's `ease` shapes the interval to
+ * the NEXT keyframe, standard CSS semantics). Used by the dock's
+ * "add keyframe at playhead" so new keyframes seed with the value currently
+ * shown by the preview instead of a hardcoded placeholder.
+ */
+export function sampleMotionKeyframesAt(
+  keyframes: MotionKeyframe[],
+  t: number,
+  defaultEase?: MotionEase,
+): string {
+  if (keyframes.length === 0) return "";
+  const sorted = sortMotionKeyframes(keyframes);
+  if (sorted.length === 1) return sorted[0].value;
+  const clamped = Math.min(1, Math.max(0, t));
+  if (clamped <= sorted[0].t) return sorted[0].value;
+  const last = sorted[sorted.length - 1];
+  if (clamped >= last.t) return last.value;
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const prev = sorted[i];
+    const next = sorted[i + 1];
+    if (clamped < prev.t || clamped > next.t) continue;
+    const span = next.t - prev.t;
+    if (span <= 0) return prev.value;
+    const ratio = (clamped - prev.t) / span;
+    const eased = evaluateMotionEase(prev.ease ?? defaultEase, ratio);
+    return lerpMotionValues(prev.value, next.value, eased);
+  }
+  return last.value;
+}