From dfe63af3ae45a68ccc5de4d9648507f1ab9cf708 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 8 Jul 2026 09:52:48 -0700
Subject: [PATCH 1/6] fix(core,cli): parent-relative figma child geometry;
 groups stop rejecting subcommand flags
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both found running the brand-loop guide end-to-end against the Simple
Design System:

- nodeToHtml subtracted the ROOT origin from every node's absolute bounds,
  but CSS absolute positioning resolves against the nearest positioned
  ancestor — every nesting level re-added its ancestors' offsets, drifting
  nested content down-right and pushing deep children off-frame (hero
  buttons invisible, pricing grid collapsed to one card). Children now
  subtract their PARENT's box; regression test with a two-level tree.

- trackCommandFailures asserted unknown flags against the command group's
  own (flagless) arg table even when the group was delegating to a
  subcommand, so `figma component <ref> --name x` imported and THEN threw
  "Unknown flag: --name". The assertion is now skipped when the first
  positional names a subcommand; leaf and non-delegating behavior is
  unchanged and covered by tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../utils/command-failure-tracking.test.ts    | 54 +++++++++++++++++++
 .../cli/src/utils/command-failure-tracking.ts | 18 ++++++-
 packages/core/src/figma/nodeToHtml.test.ts    | 32 +++++++++++
 packages/core/src/figma/nodeToHtml.ts         | 24 ++++++---
 4 files changed, 120 insertions(+), 8 deletions(-)

diff --git a/packages/cli/src/utils/command-failure-tracking.test.ts b/packages/cli/src/utils/command-failure-tracking.test.ts
index 1798d0ef2..0f7475af1 100644
--- a/packages/cli/src/utils/command-failure-tracking.test.ts
+++ b/packages/cli/src/utils/command-failure-tracking.test.ts
@@ -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" } };
diff --git a/packages/cli/src/utils/command-failure-tracking.ts b/packages/cli/src/utils/command-failure-tracking.ts
index d5bc1d435..efe65ef5e 100644
--- a/packages/cli/src/utils/command-failure-tracking.ts
+++ b/packages/cli/src/utils/command-failure-tracking.ts
@@ -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 {
diff --git a/packages/core/src/figma/nodeToHtml.test.ts b/packages/core/src/figma/nodeToHtml.test.ts
index 8c4b1f9b2..7f70a61dc 100644
--- a/packages/core/src/figma/nodeToHtml.test.ts
+++ b/packages/core/src/figma/nodeToHtml.test.ts
@@ -52,6 +52,38 @@ 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("emits var() with literal fallback for resolved bindings", () => {
     const out = nodeToHtml(
       frame([
diff --git a/packages/core/src/figma/nodeToHtml.ts b/packages/core/src/figma/nodeToHtml.ts
index 102567833..6ce0c81d8 100644
--- a/packages/core/src/figma/nodeToHtml.ts
+++ b/packages/core/src/figma/nodeToHtml.ts
@@ -186,7 +186,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 +197,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 +247,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 +266,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 +288,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 {

From 63ff046c30ad77c8c01db3b10d0e7c7d6317af6e Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 8 Jul 2026 21:13:54 -0700
Subject: [PATCH 2/6] fix(core): figma mapper prefixes digit-leading element
 ids
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

slugify("3D Object - Headphones") produced id="3d-object-headphones" —
valid HTML, but querySelector("#3d-…") throws (CSS idents cannot start
with a digit), which kills GSAP targeting and figma-motion translation
against imported components. uniqueSlug now prefixes digit-leading slugs
("n3d-object-headphones"). Found translating a real Figma Motion timeline.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/core/src/figma/nodeToHtml.test.ts | 18 ++++++++++++++++++
 packages/core/src/figma/nodeToHtml.ts      |  7 ++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/packages/core/src/figma/nodeToHtml.test.ts b/packages/core/src/figma/nodeToHtml.test.ts
index 7f70a61dc..367311474 100644
--- a/packages/core/src/figma/nodeToHtml.test.ts
+++ b/packages/core/src/figma/nodeToHtml.test.ts
@@ -84,6 +84,24 @@ describe("nodeToHtml", () => {
     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([
diff --git a/packages/core/src/figma/nodeToHtml.ts b/packages/core/src/figma/nodeToHtml.ts
index 6ce0c81d8..393af42c4 100644
--- a/packages/core/src/figma/nodeToHtml.ts
+++ b/packages/core/src/figma/nodeToHtml.ts
@@ -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++}`;

From 44653e186abf36b95c635826245bb3468bfec04b Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 8 Jul 2026 21:26:46 -0700
Subject: [PATCH 3/6] docs(figma-skill): verbatim motion translation,
 wrap-marker decoding, export_video validation

Field lesson from translating a real Motion timeline: the two returned
encodings window durations differently, and keyframes at times ~0.9999
are loop-wrap resets, not authored motion. Hand-normalizing across
encodings and inventing visible returns produced a render that diverged
from Figma. The skill now mandates verbatim single-encoding translation,
wrap-via-repeat, and a frame-grid comparison against export_video ground
truth before completion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 skills-manifest.json  | 2 +-
 skills/figma/SKILL.md | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index 49bbd956b..ce45e5ca0 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -10,7 +10,7 @@
       "files": 18
     },
     "figma": {
-      "hash": "ee1408c58b76db8e",
+      "hash": "17dd858344329586",
       "files": 1
     },
     "general-video": {
diff --git a/skills/figma/SKILL.md b/skills/figma/SKILL.md
index 3184b2c5a..7d2a70f28 100644
--- a/skills/figma/SKILL.md
+++ b/skills/figma/SKILL.md
@@ -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 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). **Translate values VERBATIM — never paraphrase, simplify, or invent keyframes.** Decoding rules (field-tested): the response carries two encodings — the motion.dev snippet is the timeline-cohort window (all tracks share the cohort duration), the CSS snippet may stretch per-track durations; use ONE encoding consistently (prefer motion.dev, cohort-windowed). Keyframes at times ≈0.9999→1 are **loop-wrap markers** (the instant reset at the loop boundary), NOT authored motion — drop them and realize the wrap via the tween's `repeat` restart; inventing a visible return/fade-out where the source has a wrap snap is the known failure mode.
+   2b. **Validate against ground truth before calling it done**: `export_video` on the cohort's `rootNodeId` gives Figma's own render of the timeline. Extract a frame grid from both videos at the same interval (e.g. `fps=5` contact sheets) and compare — element positions, fade states, and rotation phase must match frame-for-frame. A translation that hasn't been compared to the export is unverified.
 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.

From a2243f7586e90e07eddcb99a477e467a30667526 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 8 Jul 2026 21:49:08 -0700
Subject: [PATCH 4/6] feat(core,figma-skill): mechanical motion translation +
 objective fidelity gate

Two guarantees so figma-motion imports can't drift from the design again:

- motionContextToDocs(): raw get_motion_context response -> MotionDoc[],
  in code. Parses the motion.dev snippets (the reliable encoding; the CSS
  snippets stretch durations and can disagree), strips loop-wrap tail
  keyframes (sub-ms segments at the window end are the loop reset, not
  authored motion), preserves bezier eases verbatim. Fixture test uses the
  verbatim response from a real Motion timeline whose translation was
  frame-validated against Figma's own export_video render.

- skills/figma/scripts/verify-motion.mjs: mandatory post-render gate.
  Compares motion-energy deltas between the render and the export_video
  ground truth so static import fidelity cancels out and the score
  isolates choreography. Calibrated on a faithful translation (min 20.3dB)
  vs a diverging one (min 5.0dB); threshold 15dB.

The skill's Motion step now routes through both: no hand transcription,
no unverified completion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/core/src/figma/index.ts              |   6 +
 .../src/figma/motionContextToDocs.test.ts     | 144 ++++++++++++
 .../core/src/figma/motionContextToDocs.ts     | 221 ++++++++++++++++++
 skills-manifest.json                          |   4 +-
 skills/figma/SKILL.md                         |   4 +-
 skills/figma/scripts/verify-motion.mjs        | 105 +++++++++
 6 files changed, 480 insertions(+), 4 deletions(-)
 create mode 100644 packages/core/src/figma/motionContextToDocs.test.ts
 create mode 100644 packages/core/src/figma/motionContextToDocs.ts
 create mode 100644 skills/figma/scripts/verify-motion.mjs

diff --git a/packages/core/src/figma/index.ts b/packages/core/src/figma/index.ts
index 9e9a0b552..1d8e00e17 100644
--- a/packages/core/src/figma/index.ts
+++ b/packages/core/src/figma/index.ts
@@ -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";
diff --git a/packages/core/src/figma/motionContextToDocs.test.ts b/packages/core/src/figma/motionContextToDocs.test.ts
new file mode 100644
index 000000000..859a32fad
--- /dev/null
+++ b/packages/core/src/figma/motionContextToDocs.test.ts
@@ -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([]);
+  });
+});
diff --git a/packages/core/src/figma/motionContextToDocs.ts b/packages/core/src/figma/motionContextToDocs.ts
new file mode 100644
index 000000000..ba6a11a55
--- /dev/null
+++ b/packages/core/src/figma/motionContextToDocs.ts
@@ -0,0 +1,221 @@
+/**
+ * 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" };
+
+/** Extract the balanced `{...}` body following `marker` in `src`. */
+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(`${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(`${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;
+}
diff --git a/skills-manifest.json b/skills-manifest.json
index ce45e5ca0..1b48b1bf0 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -10,8 +10,8 @@
       "files": 18
     },
     "figma": {
-      "hash": "17dd858344329586",
-      "files": 1
+      "hash": "e84abcb652194f57",
+      "files": 2
     },
     "general-video": {
       "hash": "e26710c3537b3a07",
diff --git a/skills/figma/SKILL.md b/skills/figma/SKILL.md
index 7d2a70f28..d75e766b6 100644
--- a/skills/figma/SKILL.md
+++ b/skills/figma/SKILL.md
@@ -88,8 +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). **Translate values VERBATIM — never paraphrase, simplify, or invent keyframes.** Decoding rules (field-tested): the response carries two encodings — the motion.dev snippet is the timeline-cohort window (all tracks share the cohort duration), the CSS snippet may stretch per-track durations; use ONE encoding consistently (prefer motion.dev, cohort-windowed). Keyframes at times ≈0.9999→1 are **loop-wrap markers** (the instant reset at the loop boundary), NOT authored motion — drop them and realize the wrap via the tween's `repeat` restart; inventing a visible return/fade-out where the source has a wrap snap is the known failure mode.
-   2b. **Validate against ground truth before calling it done**: `export_video` on the cohort's `rootNodeId` gives Figma's own render of the timeline. Extract a frame grid from both videos at the same interval (e.g. `fps=5` contact sheets) and compare — element positions, fade states, and rotation phase must match frame-for-frame. A translation that hasn't been compared to the export is unverified.
+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.
diff --git a/skills/figma/scripts/verify-motion.mjs b/skills/figma/scripts/verify-motion.mjs
new file mode 100644
index 000000000..0531a626b
--- /dev/null
+++ b/skills/figma/scripts/verify-motion.mjs
@@ -0,0 +1,105 @@
+#!/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, execSync } 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) => {
+  const err = execSync(`ffmpeg -i ${JSON.stringify(a)} -i ${JSON.stringify(b)} -lavfi psnr -f null - 2>&1`).toString();
+  const m = err.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");

From 3d59dcc694bd4fe6ea49e5f8c429df6bf9f85d45 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Thu, 9 Jul 2026 00:51:35 -0700
Subject: [PATCH 5/6] =?UTF-8?q?fix(core,figma-skill):=20address=20PR=20fee?=
 =?UTF-8?q?dback=20=E2=80=94=20regex=20key=20escaping,=20no-shell=20psnr?=
 =?UTF-8?q?=20probe?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- motionContextToDocs: escape regex metacharacters in arrayAfterKey /
  scalarAfterKey key interpolation (safe today for \\w+ keys; now safe for
  any future caller), and document balancedBlock's no-strings invariant.
- verify-motion.mjs: execSync shell string -> spawnSync with array args
  (JSON.stringify is not shell escaping); verifier re-calibrated unchanged
  (faithful render still PASS at min 20.30dB).
- command-failure-tracking: rebase folded the group-delegation skip into
  upstream's recursive wrapCommand (HF#2033) — leaf commands now assert
  their own flag tables, so `figma component --namee` is rejected at the
  leaf while `--name` passes the group; heuristic invariant documented.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/core/src/figma/motionContextToDocs.ts | 14 +++++++++++---
 skills-manifest.json                           |  2 +-
 skills/figma/scripts/verify-motion.mjs         |  7 ++++---
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/packages/core/src/figma/motionContextToDocs.ts b/packages/core/src/figma/motionContextToDocs.ts
index ba6a11a55..7b07db9b4 100644
--- a/packages/core/src/figma/motionContextToDocs.ts
+++ b/packages/core/src/figma/motionContextToDocs.ts
@@ -58,7 +58,15 @@ export interface MotionContextToDocsOptions {
 /** motion.dev property → GSAP property. */
 const PROPERTY_MAP: Record<string, string> = { rotate: "rotation" };
 
-/** Extract the balanced `{...}` body following `marker` in `src`. */
+/** 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;
@@ -77,7 +85,7 @@ function balancedBlock(src: string, marker: string): string | null {
 
 /** Extract a balanced `[...]` immediately after `key:` inside `src`. */
 function arrayAfterKey(src: string, key: string): string | null {
-  const re = new RegExp(`${key}\\s*:\\s*\\[`);
+  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;
@@ -93,7 +101,7 @@ function arrayAfterKey(src: string, key: string): string | null {
 }
 
 function scalarAfterKey(src: string, key: string): string | null {
-  const m = new RegExp(`${key}\\s*:\\s*("[^"]*"|[\\w.]+)`).exec(src);
+  const m = new RegExp(`${escapeRegExp(key)}\\s*:\\s*("[^"]*"|[\\w.]+)`).exec(src);
   return m?.[1] ?? null;
 }
 
diff --git a/skills-manifest.json b/skills-manifest.json
index 1b48b1bf0..c2a86bf30 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -10,7 +10,7 @@
       "files": 18
     },
     "figma": {
-      "hash": "e84abcb652194f57",
+      "hash": "3172ad95070aaecc",
       "files": 2
     },
     "general-video": {
diff --git a/skills/figma/scripts/verify-motion.mjs b/skills/figma/scripts/verify-motion.mjs
index 0531a626b..07d79be9c 100644
--- a/skills/figma/scripts/verify-motion.mjs
+++ b/skills/figma/scripts/verify-motion.mjs
@@ -21,7 +21,7 @@
  * 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, execSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -72,8 +72,9 @@ const frame = (src, t, vf, 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) => {
-  const err = execSync(`ffmpeg -i ${JSON.stringify(a)} -i ${JSON.stringify(b)} -lavfi psnr -f null - 2>&1`).toString();
-  const m = err.match(/average:([\d.]+|inf)/);
+  // 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;
 };
 

From 666b84d7bb8cd12da71b3166c03f81a1380fbf21 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Thu, 9 Jul 2026 00:59:11 -0700
Subject: [PATCH 6/6] style(figma-skill): format verify-motion.mjs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 skills-manifest.json                   |  2 +-
 skills/figma/scripts/verify-motion.mjs | 63 ++++++++++++++++++++++----
 2 files changed, 55 insertions(+), 10 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index c2a86bf30..95f09abfe 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -10,7 +10,7 @@
       "files": 18
     },
     "figma": {
-      "hash": "3172ad95070aaecc",
+      "hash": "431580ce359639f5",
       "files": 2
     },
     "general-video": {
diff --git a/skills/figma/scripts/verify-motion.mjs b/skills/figma/scripts/verify-motion.mjs
index 07d79be9c..ae5376e0c 100644
--- a/skills/figma/scripts/verify-motion.mjs
+++ b/skills/figma/scripts/verify-motion.mjs
@@ -44,7 +44,15 @@ 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])
+    execFileSync("ffprobe", [
+      "-v",
+      "error",
+      "-show_entries",
+      "format=duration",
+      "-of",
+      "csv=p=0",
+      file,
+    ])
       .toString()
       .trim(),
   );
@@ -52,14 +60,30 @@ 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 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); }
+  if (!m) {
+    console.error("bad --crop, expected WxH+X+Y");
+    process.exit(2);
+  }
   cropFilter = `crop=${m[1]}:${m[2]}:${m[3]}:${m[4]},`;
 }
 
@@ -70,10 +94,23 @@ const frame = (src, t, vf, dst) => {
   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]);
+  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 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;
 };
@@ -88,7 +125,11 @@ for (let t = 0; t <= end; t = Math.round((t + interval) * 1000) / 1000) {
   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")) });
+  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 });
 
@@ -98,9 +139,13 @@ 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`);
+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)");
+  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");