Merge pull request #2063 from heygen-com/vi/figma-mapper-fixes

fix(core,cli): parent-relative figma child geometry; groups stop rejecting subcommand flags
This commit is contained in:
Vance Ingalls
2026-07-09 01:18:04 -07:00
committed by GitHub
10 changed files with 678 additions and 12 deletions
@@ -39,6 +39,60 @@ describe("trackCommandFailures", () => {
expect(onFailure).not.toHaveBeenCalled();
});
it("rejects an unknown flag on a leaf command", async () => {
const wrapped = trackCommandFailures(
() =>
Promise.resolve({
meta: { name: "leaf" },
args: { out: { type: "string" } },
run: () => Promise.resolve(),
} as CommandDef),
vi.fn(),
);
const cmd = await wrapped();
await expect(
(cmd.run as (ctx: unknown) => Promise<unknown>)({ rawArgs: ["--bogus", "x"] }),
).rejects.toThrow(/--bogus/);
});
it("skips the unknown-flag check when a command group delegates to a subcommand", async () => {
// `figma component <ref> --name x`: --name belongs to the subcommand's
// table; the group (subCommands + fallback-help run) must not reject it.
const run = vi.fn(() => Promise.resolve());
const wrapped = trackCommandFailures(
() =>
Promise.resolve({
meta: { name: "figma" },
subCommands: { component: () => Promise.resolve({ meta: { name: "component" } }) },
run,
} as unknown as CommandDef),
vi.fn(),
);
const cmd = await wrapped();
await expect(
(cmd.run as (ctx: unknown) => Promise<unknown>)({
rawArgs: ["component", "KEY:1-2", "--name", "hero"],
}),
).resolves.toBeUndefined();
expect(run).toHaveBeenCalled();
});
it("still rejects an unknown flag when the group is NOT delegating", async () => {
const wrapped = trackCommandFailures(
() =>
Promise.resolve({
meta: { name: "figma" },
subCommands: { component: () => Promise.resolve({ meta: { name: "component" } }) },
run: () => Promise.resolve(),
} as unknown as CommandDef),
vi.fn(),
);
const cmd = await wrapped();
await expect(
(cmd.run as (ctx: unknown) => Promise<unknown>)({ rawArgs: ["--bogus"] }),
).rejects.toThrow(/--bogus/);
});
it("passes through a command with no run() untouched", async () => {
const onFailure = vi.fn();
const parent: CommandDef = { meta: { name: "parent" } };
@@ -54,7 +54,23 @@ function wrapCommand(
// Reject unknown flags before the command body: citty silently ignores
// them otherwise, dropping the value (e.g. `render --out x` fell back to
// the default output path). Inside the try so the rejection is reported.
assertKnownFlags(cmd, ctx?.rawArgs ?? []);
//
// A command group (subCommands + fallback-help run) delegating to a
// subcommand must NOT assert here: the flags belong to the subcommand's
// table, not the group's, and would be falsely rejected (e.g.
// `figma component <ref> --name x`). The wrapped subcommand loaders
// below assert the leaf's own table, so typo protection is preserved.
// Heuristic caveat: "first non-dash token names a subcommand" is sound
// only while command groups declare no flags of their own — if a group
// grows a flag whose value could match a subcommand name, replace this
// with a real argv parse.
const rawArgs = ctx?.rawArgs ?? [];
const firstPositional = rawArgs.find((tok) => tok && !tok.startsWith("-"));
const delegatesToSub =
cmd.subCommands != null &&
firstPositional != null &&
Object.prototype.hasOwnProperty.call(cmd.subCommands, firstPositional);
if (!delegatesToSub) assertKnownFlags(cmd, rawArgs);
return await run(ctx);
} catch (err) {
try {
+6
View File
@@ -59,5 +59,11 @@ export type {
TokensToVariablesResult,
} from "./tokensToVariables";
export { mapEase } from "./motionEase";
export {
motionContextToDocs,
type MotionContextResponse,
type MotionContextNode,
type MotionContextToDocsOptions,
} from "./motionContextToDocs";
export { motionToGsap } from "./motionToGsap";
export { emitTimelineScript } from "./emitTimelineScript";
@@ -0,0 +1,144 @@
// @vitest-environment node
import { describe, expect, it } from "vitest";
import { motionContextToDocs } from "./motionContextToDocs";
import type { MotionContextResponse } from "./motionContextToDocs";
/**
* Fixture: verbatim `get_motion_context` response for the SDS "Unlocked"
* Motion card (fileKey Hl5L3gkQ3Tz3Y2KTQJbAkT, node 3021:6485, 2026-07-08).
* The expected outputs were validated frame-by-frame against Figma's own
* `export_video` render of the same timeline (verify-motion.mjs PASS).
*/
const FIXTURE: MotionContextResponse = {
nodes: [
{
nodeId: "3021:6487",
nodeName: "Shape w offset",
nodeType: "FRAME",
codeSnippets: {
motionDev:
'<motion.div initial={{ rotate: 0, }} animate={{ rotate: [0, 223.149, 360], }} transition={{ rotate: { duration: 2, times: [0, 0.9999, 1], ease: "linear", repeat: Infinity }, }} />',
},
},
{
nodeId: "3021:6491",
nodeName: "3D Object - Headphones",
nodeType: "ROUNDED_RECTANGLE",
codeSnippets: {
motionDev:
'<motion.div initial={{ y: 0, }} animate={{ y: [0, -71.246, -64.253, -19.227, -1.212, 0], }} transition={{ y: { duration: 2, times: [0, 0.8066, 0.9997, 0.9998, 0.9999, 1], ease: [[0.539, 0, 0.312, 0.995], "linear", "linear", "linear", "linear"], repeat: Infinity }, }} />',
},
},
{
nodeId: "3021:6492",
nodeName: "Shape",
nodeType: "ROUNDED_RECTANGLE",
codeSnippets: {
motionDev:
'<motion.div initial={{ width: 160.5, }} animate={{ width: [160.5, 500, 500, 160.5], }} transition={{ width: { duration: 2, times: [0, 0.1956, 0.9999, 1], ease: [[0.539, 0, 0.312, 0.995], "linear", [0.539, 0, 0.312, 0.995]], repeat: Infinity }, }} />',
},
},
{
nodeId: "3021:6493",
nodeName: "Headline",
nodeType: "TEXT",
codeSnippets: {
motionDev:
'<motion.div initial={{ opacity: 0, x: 98.914, }} animate={{ opacity: [0, 0, 1, 1, 0], x: [98.914, 98.914, 0, 0, 98.914], }} transition={{ opacity: { duration: 2, times: [0, 0.0686, 0.2273, 0.9999, 1], ease: ["linear", [0.539, 0, 0.312, 0.995], "linear", [0.539, 0, 0.312, 0.995]], repeat: Infinity }, x: { duration: 2, times: [0, 0.0686, 0.2273, 0.9999, 1], ease: ["linear", [0.539, 0, 0.312, 0.995], "linear", [0.539, 0, 0.312, 0.995]], repeat: Infinity }, }} />',
},
},
{
nodeId: "3021:6494",
nodeName: "Knob",
nodeType: "FRAME",
codeSnippets: {
motionDev:
'<motion.div initial={{ x: -339.087, }} animate={{ x: [-339.087, 0, 0, -339.087], }} transition={{ x: { duration: 2, times: [0, 0.1956, 0.9999, 1], ease: [[0.539, 0, 0.312, 0.995], "linear", [0.539, 0, 0.312, 0.995]], repeat: Infinity }, }} />',
},
},
],
timelineCohorts: [
{
rootNodeId: "3021:6485",
durationMs: 2000,
loopMode: "loop",
memberNodeIds: ["3021:6487", "3021:6491", "3021:6492", "3021:6493", "3021:6494"],
},
],
};
const SELECTORS: Record<string, string> = {
"3021:6487": "#shape-w-offset",
"3021:6491": "#headphones-3d",
"3021:6492": "#shape-2",
"3021:6493": "#headline",
"3021:6494": "#knob",
};
function docs(repeat = 1) {
return motionContextToDocs(FIXTURE, {
selectorFor: (n) => SELECTORS[n.nodeId] ?? `#${n.nodeId}`,
repeat,
});
}
describe("motionContextToDocs", () => {
it("produces one doc per animated node with caller-supplied selectors", () => {
const out = docs();
expect(out.map((d) => d.selector)).toEqual([
"#shape-w-offset",
"#headphones-3d",
"#shape-2",
"#headline",
"#knob",
]);
});
it("strips the loop-wrap tail and extends the last keyframe to the window end", () => {
const rotation = docs()[0]?.tracks[0];
// [0, 223.149, 360] @ [0, .9999, 1]: the 360 is the wrap marker.
// 223.149° over the 2s window is the true angular speed (the CSS
// snippet's "360° in 2s" disagrees and is wrong — verified against
// export_video ground truth).
expect(rotation?.property).toBe("rotation");
expect(rotation?.values).toEqual([0, 223.149]);
expect(rotation?.times).toEqual([0, 1]);
});
it("strips multi-keyframe wrap clusters but keeps real sub-second motion", () => {
const y = docs()[1]?.tracks[0];
// tail cluster (-19.227, -1.212, 0) spans <1ms each — wrap markers.
// -64.253 @ 0.9997 ends a 0.386s segment — real, kept, extended to 1.
expect(y?.values).toEqual([0, -71.246, -64.253]);
expect(y?.times).toEqual([0, 0.8066, 1]);
});
it("keeps hold segments and drops only the wrap snap", () => {
const width = docs()[2]?.tracks[0];
expect(width?.values).toEqual([160.5, 500, 500]);
expect(width?.times).toEqual([0, 0.1956, 1]);
});
it("parses multiple properties per node", () => {
const headline = docs()[3];
expect(headline?.tracks.map((t) => t.property).sort()).toEqual(["opacity", "x"]);
const opacity = headline?.tracks.find((t) => t.property === "opacity");
expect(opacity?.values).toEqual([0, 0, 1, 1]);
expect(opacity?.times).toEqual([0, 0.0686, 0.2273, 1]);
});
it("preserves bezier easing arrays and applies the requested repeat", () => {
const knob = docs(2)[4]?.tracks[0];
expect(knob?.ease[0]).toEqual([0.539, 0, 0.312, 0.995]);
expect(knob?.repeat).toBe(2);
expect(knob?.duration).toBe(2);
});
it("skips nodes without motion.dev snippets", () => {
const out = motionContextToDocs(
{ nodes: [{ nodeId: "1:1", nodeName: "Static", codeSnippets: { css: "..." } }] },
{ selectorFor: () => "#static" },
);
expect(out).toEqual([]);
});
});
@@ -0,0 +1,229 @@
/**
* Mechanical translation of a raw Figma MCP `get_motion_context` response
* into MotionDocs — no hand transcription (design spec §6 motion notes).
*
* Field-tested decoding rules (2026-07, SDS "Unlocked" card):
*
* - The response carries two encodings per node. The motion.dev snippet is
* the reliable one: every track is sampled inside the timeline-cohort
* window, so values are correct AT their normalized times. The CSS
* snippet stretches per-track durations and can disagree — it is ignored.
* - Keyframes clustered at the tail of the window (segments spanning less
* than WRAP_EPSILON_S of real time) are LOOP-WRAP MARKERS — the instant
* reset at the loop boundary — not authored motion. They are stripped and
* the wrap is realized by the tween's `repeat` restart. Inventing visible
* returns from wrap markers is the known failure mode this module exists
* to prevent.
* - After stripping, the last kept keyframe's time extends to 1 so the
* track fills its window (the dropped tail spanned sub-millisecond time).
*
* Verification is still mandatory: render and compare against
* `export_video` ground truth with skills/figma/scripts/verify-motion.mjs.
*/
import type { MotionDoc, MotionEase, MotionTrack } from "./types";
/** Tail segments shorter than this (seconds) are loop-wrap markers. */
const WRAP_EPSILON_S = 0.005;
export interface MotionContextNode {
nodeId: string;
nodeName: string;
nodeType?: string;
codeSnippets?: { css?: string; motionDev?: string };
}
export interface MotionContextResponse {
nodes: MotionContextNode[];
timelineCohorts?: Array<{
rootNodeId: string;
durationMs: number;
loopMode?: string;
memberNodeIds?: string[];
}>;
}
export interface MotionContextToDocsOptions {
/**
* Maps a node to the CSS selector of its imported element. REQUIRED in
* practice: pass the ids from the Phase-3 component import (the mapper's
* slugs, e.g. `#headphones-3d`) — deriving selectors from node names here
* would silently drift from the imported HTML.
*/
selectorFor: (node: MotionContextNode) => string;
/** Extra plays per track (GSAP semantics: 0 = play once). Default 0. */
repeat?: number;
}
/** motion.dev property → GSAP property. */
const PROPERTY_MAP: Record<string, string> = { rotate: "rotation" };
/** Escape regex metacharacters — keys are `\w+` property names today, but a
* future caller passing anything else must not silently misparse. */
function escapeRegExp(text: string): string {
return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
/** Extract the balanced `{...}` body following `marker` in `src`. Brace
* counting does not skip string literals — sound for motion.dev output
* (numeric arrays + named eases, never arbitrary strings containing `}`). */
function balancedBlock(src: string, marker: string): string | null {
const at = src.indexOf(marker);
if (at === -1) return null;
const start = src.indexOf("{", at + marker.length - 1);
if (start === -1) return null;
let depth = 0;
for (let i = start; i < src.length; i += 1) {
if (src[i] === "{") depth += 1;
if (src[i] === "}") {
depth -= 1;
if (depth === 0) return src.slice(start + 1, i);
}
}
return null;
}
/** Extract a balanced `[...]` immediately after `key:` inside `src`. */
function arrayAfterKey(src: string, key: string): string | null {
const re = new RegExp(`${escapeRegExp(key)}\\s*:\\s*\\[`);
const m = re.exec(src);
if (!m) return null;
const start = m.index + m[0].length - 1;
let depth = 0;
for (let i = start; i < src.length; i += 1) {
if (src[i] === "[") depth += 1;
if (src[i] === "]") {
depth -= 1;
if (depth === 0) return src.slice(start, i + 1);
}
}
return null;
}
function scalarAfterKey(src: string, key: string): string | null {
const m = new RegExp(`${escapeRegExp(key)}\\s*:\\s*("[^"]*"|[\\w.]+)`).exec(src);
return m?.[1] ?? null;
}
function parseEase(transitionBlock: string): MotionEase[] | null {
const arr = arrayAfterKey(transitionBlock, "ease");
if (arr) return JSON.parse(arr) as MotionEase[];
const scalar = scalarAfterKey(transitionBlock, "ease");
if (scalar?.startsWith('"')) return [JSON.parse(scalar) as string];
return null;
}
/**
* Strip loop-wrap tail keyframes: walking from the end, drop keyframes whose
* incoming segment spans < WRAP_EPSILON_S of real time; stop at the first
* substantial segment. Extend the last kept time to 1.
*/
function stripWrapTail(
values: Array<number | string>,
times: number[],
ease: MotionEase[],
duration: number,
): { values: Array<number | string>; times: number[]; ease: MotionEase[] } {
let end = values.length;
while (end > 2) {
const tPrev = times[end - 2];
const tCur = times[end - 1];
if (tPrev === undefined || tCur === undefined) break;
if ((tCur - tPrev) * duration >= WRAP_EPSILON_S) break;
end -= 1;
}
const v = values.slice(0, end);
const t = times.slice(0, end);
const e = ease.slice(0, Math.max(1, end - 1));
const last = t.length - 1;
if (t[last] !== undefined && t[last] < 1) t[last] = 1;
return { values: v, times: t, ease: e };
}
interface RawTrackData {
values: Array<number | string>;
times: number[];
ease: MotionEase[];
duration: number;
}
/** Extract and validate one property's raw arrays from the snippet blocks. */
function extractTrackData(animate: string, transition: string, prop: string): RawTrackData | null {
const valuesSrc = arrayAfterKey(animate, prop);
const propTransition = balancedBlock(transition, `${prop}: {`);
if (!valuesSrc || !propTransition) return null;
const timesSrc = arrayAfterKey(propTransition, "times");
const durationSrc = scalarAfterKey(propTransition, "duration");
const ease = parseEase(propTransition);
if (!timesSrc || !durationSrc || !ease) return null;
const values = JSON.parse(valuesSrc) as Array<number | string>;
const times = JSON.parse(timesSrc) as number[];
const duration = Number(durationSrc);
if (values.length !== times.length || !Number.isFinite(duration)) return null;
return { values, times, ease, duration };
}
/** Parse one property's track out of the animate/transition blocks. */
function parsePropertyTrack(
animate: string,
transition: string,
prop: string,
repeat: number,
): MotionTrack | null {
const raw = extractTrackData(animate, transition, prop);
if (!raw) return null;
// segment eases: a single named ease applies to every segment
const segCount = raw.values.length - 1;
const segEase =
raw.ease.length === segCount
? raw.ease
: Array.from({ length: segCount }, (_, i) => raw.ease[i % raw.ease.length] ?? "linear");
const stripped = stripWrapTail(raw.values, raw.times, segEase, raw.duration);
return {
property: PROPERTY_MAP[prop] ?? prop,
values: stripped.values,
times: stripped.times,
ease: stripped.ease,
duration: raw.duration,
repeat,
};
}
/** Parse one node's motion.dev snippet into MotionTracks. */
function parseNodeTracks(node: MotionContextNode, repeat: number): MotionTrack[] {
const snippet = node.codeSnippets?.motionDev;
if (!snippet) return [];
const animate = balancedBlock(snippet, "animate={");
const transition = balancedBlock(snippet, "transition={");
if (!animate || !transition) return [];
const tracks: MotionTrack[] = [];
const propRe = /(\w+)\s*:\s*\[/g;
let m: RegExpExecArray | null;
while ((m = propRe.exec(animate)) !== null) {
const prop = m[1];
if (prop === undefined) continue;
const track = parsePropertyTrack(animate, transition, prop, repeat);
if (track) tracks.push(track);
}
return tracks;
}
/**
* Raw `get_motion_context` response → MotionDoc[], mechanically. Feed the
* result to motionToGsap/emitTimelineScript; then verify against
* export_video ground truth before calling the import done.
*/
export function motionContextToDocs(
response: MotionContextResponse,
options: MotionContextToDocsOptions,
): MotionDoc[] {
const repeat = options.repeat ?? 0;
const docs: MotionDoc[] = [];
for (const node of response.nodes ?? []) {
const tracks = parseNodeTracks(node, repeat);
if (tracks.length === 0) continue;
docs.push({ selector: options.selectorFor(node), tracks });
}
return docs;
}
@@ -52,6 +52,56 @@ describe("nodeToHtml", () => {
expect(out.html).toContain("background-color: #0066FF");
});
it("positions nested children relative to their PARENT, not the root", () => {
const out = nodeToHtml(
frame([
{
id: "1:2",
name: "Group",
type: "FRAME",
absoluteBoundingBox: BOX(600, 400, 300, 200),
children: [
{
id: "1:3",
name: "Inner",
type: "RECTANGLE",
absoluteBoundingBox: BOX(620, 440, 100, 40),
fills: [SOLID_BLUE],
},
],
},
]),
{ resolved: [], unresolved: [] },
);
// Group at canvas (600,400) inside root (100,200) → left 500, top 200.
expect(out.html).toContain("left: 500px");
expect(out.html).toContain("top: 200px");
// Inner at canvas (620,440) inside Group (600,400) → left 20, top 40 —
// NOT root-relative 520/240, which double-offsets when CSS resolves
// absolute position against the positioned parent.
expect(out.html).toContain("left: 20px");
expect(out.html).toContain("top: 40px");
expect(out.html).not.toContain("left: 520px");
});
it("prefixes digit-leading slugs so ids stay CSS-selector-safe", () => {
const out = nodeToHtml(
frame([
{
id: "1:2",
name: "3D Object - Headphones",
type: "RECTANGLE",
absoluteBoundingBox: BOX(120, 220, 100, 40),
fills: [SOLID_BLUE],
},
]),
{ resolved: [], unresolved: [] },
);
// "#3d-object-headphones" would throw in querySelector/GSAP targeting
expect(out.html).toContain('id="n3d-object-headphones"');
expect(out.html).not.toContain('id="3d-object-headphones"');
});
it("emits var() with literal fallback for resolved bindings", () => {
const out = nodeToHtml(
frame([
+23 -8
View File
@@ -162,7 +162,12 @@ interface RenderContext {
}
function uniqueSlug(ctx: RenderContext, name: string): string {
const base = slugify(name);
const raw = slugify(name);
// A digit-leading id ("3D Object" → "3d-object") is valid HTML but not a
// valid CSS selector — querySelector("#3d-object") throws, which breaks
// GSAP targeting and figma-motion translation. Prefix so ids stay
// selector-safe.
const base = /^[0-9]/.test(raw) ? `n${raw}` : raw;
let slug = base;
let n = 2;
while (ctx.usedSlugs.has(slug)) slug = `${base}-${n++}`;
@@ -186,7 +191,7 @@ function unresolvedAttr(node: FigmaNodeDocument, ctx: RenderContext): string {
return ` data-figma-unresolved="${escapeHtml(props.join(" "))}"`;
}
function geometryCss(node: FigmaNodeDocument, ctx: RenderContext, isRoot: boolean): string[] {
function geometryCss(node: FigmaNodeDocument, parentBox: Box, isRoot: boolean): string[] {
const box = boxOf(node);
const styles: string[] = [];
if (!box) return styles;
@@ -197,10 +202,14 @@ function geometryCss(node: FigmaNodeDocument, ctx: RenderContext, isRoot: boolea
`height: ${round(box.height)}px`,
);
} else {
// CSS absolute positioning is relative to the nearest positioned
// ancestor — the PARENT's box, not the root origin. Subtracting the root
// for every depth double-offsets nested children (each level re-adds its
// ancestors' offsets), drifting content down-right and off-frame.
styles.push(
"position: absolute",
`left: ${round(box.x - ctx.origin.x)}px`,
`top: ${round(box.y - ctx.origin.y)}px`,
`left: ${round(box.x - parentBox.x)}px`,
`top: ${round(box.y - parentBox.y)}px`,
`width: ${round(box.width)}px`,
`height: ${round(box.height)}px`,
);
@@ -243,10 +252,15 @@ function decorationCss(node: FigmaNodeDocument, ctx: RenderContext): string[] {
// instead of a RangeError; real figma frames are nowhere near this deep.
const MAX_DEPTH = 500;
function renderChildren(node: FigmaNodeDocument, ctx: RenderContext, depth: number): string {
function renderChildren(
node: FigmaNodeDocument,
ctx: RenderContext,
depth: number,
parentBox: Box,
): string {
const childHtml: string[] = [];
for (const child of childDocuments(node)) {
const rendered = renderNodeHtml(child, ctx, false, depth + 1);
const rendered = renderNodeHtml(child, ctx, false, depth + 1, parentBox);
if (rendered.length > 0) childHtml.push(rendered);
}
return childHtml.length > 0 ? `\n${childHtml.join("\n")}\n` : "";
@@ -257,11 +271,12 @@ function renderNodeHtml(
ctx: RenderContext,
isRoot: boolean,
depth = 0,
parentBox: Box = ctx.origin,
): string {
if (node.visible === false || depth > MAX_DEPTH) return "";
const slug = uniqueSlug(ctx, node.name);
const style = escapeHtml(
[...geometryCss(node, ctx, isRoot), ...decorationCss(node, ctx)].join("; "),
[...geometryCss(node, parentBox, isRoot), ...decorationCss(node, ctx)].join("; "),
);
// data-hf-snippet marks the file as a mountable fragment, not a standalone
// composition — the project linter skips composition-root rules for it.
@@ -278,7 +293,7 @@ function renderNodeHtml(
return `<div ${idAttrs} style="${style}">${text}</div>`;
}
return `<div ${idAttrs} style="${style}">${renderChildren(node, ctx, depth)}</div>`;
return `<div ${idAttrs} style="${style}">${renderChildren(node, ctx, depth, boxOf(node) ?? parentBox)}</div>`;
}
export interface NodeToHtmlOptions {
+2 -2
View File
@@ -10,8 +10,8 @@
"files": 18
},
"figma": {
"hash": "ee1408c58b76db8e",
"files": 1
"hash": "431580ce359639f5",
"files": 2
},
"general-video": {
"hash": "e26710c3537b3a07",
+2 -1
View File
@@ -88,7 +88,8 @@ Node tree → editable HTML at exact figma geometry, packaged as a registry item
No REST equivalent exists. You drive the MCP tools, then hand output to the pure helpers in `@hyperframes/core/figma`:
1. `get_motion_context(fileKey, nodeId)` — use `recursive:true` on the parent frame (one call for the whole scene, not one per element). Save the raw JSON next to the project (`.media/figma-cache/`) so retranslation is free.
2. Normalize into a `MotionDoc`: per animated property a `MotionTrack` { property (motion.dev name), values, times (0..1), ease[] (named or `[x1,y1,x2,y2]` bezier), duration, repeat }. Selector = the element's stable id (`#<id>` from Phase-3 output or the authored scene).
2. Normalize into `MotionDoc`s with `motionContextToDocs(rawResponse, { selectorFor, repeat })` from `@hyperframes/core/figma` — **never transcribe keyframe numbers by hand**. The helper encodes the field-tested decoding rules mechanically: it parses the motion.dev snippets (the reliable encoding — the CSS snippets stretch durations and can disagree; they are ignored), strips loop-wrap tail keyframes (sub-millisecond segments at times ≈0.9999→1 are the loop's instant reset, not authored motion — the wrap is realized by `repeat` restart), and preserves bezier eases verbatim. `selectorFor` must return the ids from the Phase-3 component import — don't derive selectors from node names.
2b. **Validate against ground truth before calling it done — mandatory**: `export_video` on the cohort's `rootNodeId` gives Figma's own render of the timeline. Run `node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y` — it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR (calibrated: faithful ≈ 20+, diverging ≈ 5). Measure `--crop` from the render's actual card edges, don't guess. FAIL means re-check the translation, not the threshold.
3. `motionToGsap(doc)` → `emitTimelineScript(spec)` → inject as a `<script>` after the GSAP + CustomEase CDN tags. Paused, finite, registered on `window.__timelines` with a literal key.
4. Untranslatable track (shader-driven, unsupported prop, complex masks) → bake: `export_video` → freeze MP4 → embed as `<video class="clip">`. Exception: shader-driven tracks — figma's export path flattens shaders to the base color (see Shaders below), so a bake there silently loses the shader; ask the user for a native figma export instead. Always say which path you used and why. Named eases outside the mapped set fall back to linear — the mapping table lives in `motionEase.ts`; flag the fallback to the user when it fires.
5. Run `npx hyperframes lint && npx hyperframes validate` before calling it done.
+151
View File
@@ -0,0 +1,151 @@
#!/usr/bin/env node
/**
* Objective fidelity gate for figma-motion imports (skill step 2b).
*
* Compares the HyperFrames render against Figma's own `export_video` output
* using MOTION-ENERGY deltas: for each sample window [t, t+interval], the
* frame difference ref(t+i)-ref(t) is compared (PSNR) against
* render(t+i)-render(t). Static import divergence (fonts, rasterized edges,
* subpixel geometry — the hybrid-fidelity ceiling) cancels out of both
* deltas, so the score isolates choreography: trajectories, timing, easing.
*
* Calibration (SDS "Unlocked" card, 2026-07): a faithful translation scored
* min 20.3dB / mean 27.7dB; a diverging one (invented retract keyframes,
* wrong durations) scored min 5.0dB / mean 23.1dB. Default threshold 15dB
* sits between with margin on both sides.
*
* node verify-motion.mjs --reference figma-export.mp4 --render out.mp4 \
* [--crop WxH+X+Y] [--interval 0.2] [--min-motion-psnr 15]
*
* --crop selects the card region inside the (usually larger) composition
* frame. Measure it from the render (the card's left/top edge + scaled
* size), don't guess: a wrong crop reads as motion divergence.
*/
import { execFileSync, spawnSync } from "node:child_process";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
function arg(name, fallback) {
const i = process.argv.indexOf(`--${name}`);
return i > -1 ? process.argv[i + 1] : fallback;
}
const reference = arg("reference");
const render = arg("render");
if (!reference || !render) {
console.error(
"usage: verify-motion.mjs --reference ref.mp4 --render out.mp4 [--crop WxH+X+Y] [--interval 0.2] [--min-motion-psnr 15]",
);
process.exit(2);
}
const crop = arg("crop", null);
const interval = Number(arg("interval", "0.2"));
const minMotion = Number(arg("min-motion-psnr", "15"));
const ffprobe = (file) =>
Number(
execFileSync("ffprobe", [
"-v",
"error",
"-show_entries",
"format=duration",
"-of",
"csv=p=0",
file,
])
.toString()
.trim(),
);
const refDur = ffprobe(reference);
const renderDur = ffprobe(render);
const end = Math.min(refDur, renderDur) - interval - 0.01;
const dims = execFileSync("ffprobe", [
"-v",
"error",
"-select_streams",
"v",
"-show_entries",
"stream=width,height",
"-of",
"csv=p=0",
reference,
])
.toString()
.trim()
.split(",")
.map(Number);
const [rw, rh] = dims;
let cropFilter = "";
if (crop) {
const m = crop.match(/^(\d+)x(\d+)\+(\d+)\+(\d+)$/);
if (!m) {
console.error("bad --crop, expected WxH+X+Y");
process.exit(2);
}
cropFilter = `crop=${m[1]}:${m[2]}:${m[3]}:${m[4]},`;
}
const dir = mkdtempSync(join(tmpdir(), "verify-motion-"));
const frame = (src, t, vf, dst) => {
const args = ["-y", "-v", "error", "-ss", String(t), "-i", src, "-frames:v", "1"];
if (vf) args.push("-vf", vf);
execFileSync("ffmpeg", args.concat(dst));
};
const diff = (a, b, dst) =>
execFileSync("ffmpeg", [
"-y",
"-v",
"error",
"-i",
a,
"-i",
b,
"-filter_complex",
"blend=all_mode=difference",
dst,
]);
const psnr = (a, b) => {
// spawnSync with array args (no shell): psnr stats land on stderr
const r = spawnSync("ffmpeg", ["-i", a, "-i", b, "-lavfi", "psnr", "-f", "null", "-"], {
encoding: "utf8",
});
const m = (r.stderr || "").match(/average:([\d.]+|inf)/);
return m ? (m[1] === "inf" ? 99 : Number(m[1])) : NaN;
};
const renderVf = `${cropFilter}scale=${rw}:${rh}`;
const results = [];
for (let t = 0; t <= end; t = Math.round((t + interval) * 1000) / 1000) {
const t1 = Math.round((t + interval) * 1000) / 1000;
frame(reference, t, null, join(dir, "ra.png"));
frame(reference, t1, null, join(dir, "rb.png"));
frame(render, t, renderVf, join(dir, "oa.png"));
frame(render, t1, renderVf, join(dir, "ob.png"));
diff(join(dir, "ra.png"), join(dir, "rb.png"), join(dir, "rd.png"));
diff(join(dir, "oa.png"), join(dir, "ob.png"), join(dir, "od.png"));
results.push({
t,
motion: psnr(join(dir, "rd.png"), join(dir, "od.png")),
abs: psnr(join(dir, "rb.png"), join(dir, "ob.png")),
});
}
rmSync(dir, { recursive: true, force: true });
const min = Math.min(...results.map((r) => r.motion));
const mean = results.reduce((s, r) => s + r.motion, 0) / results.length;
for (const r of results)
console.log(
`window ${r.t.toFixed(2)}s→${(r.t + interval).toFixed(2)}s motion-psnr=${r.motion.toFixed(2)}dB (abs=${r.abs.toFixed(1)}dB)${r.motion < minMotion ? " <-- BELOW THRESHOLD" : ""}`,
);
console.log(
`\nwindows=${results.length} min-motion=${min.toFixed(2)}dB mean-motion=${mean.toFixed(2)}dB threshold=${minMotion}dB`,
);
if (min < minMotion) {
console.log(
"VERDICT: FAIL — choreography diverges from the Figma export (check timings, invented keyframes, durations)",
);
process.exit(1);
}
console.log("VERDICT: PASS — motion matches the Figma export within the static-fidelity ceiling");