mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
Merge pull request #2112 from heygen-com/vi/figma-scopes-retry
fix(figma): auth/retry/batch hardening, mapper fidelity, skill routing, setup docs
This commit is contained in:
Vance Ingalls
+29
-15
@@ -10,7 +10,7 @@ The work your designer already did in Figma — layout, color, type, motion —
|
||||
| Capability | What you get | Surface |
|
||||
| --- | --- | --- |
|
||||
| **Static assets** | A frame/layer rendered to SVG/PNG/JPG/PDF, frozen under `.media/` | `hyperframes figma asset` |
|
||||
| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` |
|
||||
| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` (Enterprise) or the `/figma` skill via MCP (any plan) |
|
||||
| **Components** | A frame as editable HTML with brand-linked colors | `hyperframes figma component` |
|
||||
| **Motion** | A Figma Motion timeline as an editable, paused GSAP timeline | `/figma` skill (agent, MCP) |
|
||||
| **Shaders** | A shader fill/effect as a frozen still or clip | `/figma` skill (agent, MCP) |
|
||||
@@ -20,22 +20,32 @@ Two transports, split by what Figma exposes: assets, tokens, and components run
|
||||
|
||||
## One-time setup
|
||||
|
||||
The CLI paths need a Figma personal access token in the `FIGMA_TOKEN` environment variable.
|
||||
There are two credentials, and most people only need to set up one to start:
|
||||
|
||||
| You want to import… | Set up |
|
||||
| --- | --- |
|
||||
| A logo, image, or a whole frame as HTML (assets, components) | A **token** — Step A below |
|
||||
| Brand colors (tokens) | Either works, but on a non-Enterprise plan the **MCP connector** (Step B) gets you there in one click — the token path needs an Enterprise plan for this specific pull |
|
||||
| Motion, shaders, or a storyboard | The **MCP connector** only — no token, no setup beyond connecting it |
|
||||
|
||||
Do both if your project needs everything; each is independent, so it doesn't matter which you set up first.
|
||||
|
||||
### Step A — Figma token (assets, tokens, components)
|
||||
|
||||
Needed for anything you run from the `hyperframes figma` CLI.
|
||||
|
||||
<Steps>
|
||||
<Step title="Mint a token">
|
||||
In Figma: **Settings → Security → Personal access tokens → Generate new token.**
|
||||
</Step>
|
||||
<Step title="Pick read-only scopes">
|
||||
The integration never writes to Figma — read-only is all it ever needs:
|
||||
<Step title="Check these scopes">
|
||||
Read-only is all it ever needs — the integration never writes to Figma. **On most accounts (not Figma Enterprise), check exactly these three:**
|
||||
|
||||
| Scope | Setting | Needed for |
|
||||
| --- | --- | --- |
|
||||
| File content | Read-only | assets, components |
|
||||
| File metadata | Read-only | version tracking, refresh |
|
||||
| Variables | Read-only | brand variables — **Figma Enterprise only** |
|
||||
- **File content** — Read-only
|
||||
- **File metadata** — Read-only
|
||||
- **Library content** — Read-only — easy to miss, and without it `tokens` 403s the moment it tries the published-styles fallback
|
||||
|
||||
No Enterprise plan? Skip the Variables scope — `tokens` automatically falls back to your published styles. That's expected behavior, not an error.
|
||||
On a **Figma Enterprise** plan, also check **Variables — Read-only** to pull brand colors directly via `tokens`. Not on Enterprise? Skip it — `tokens` falls back to published styles automatically, or use the MCP connector (Step B) instead, which reaches variables on any plan.
|
||||
</Step>
|
||||
<Step title="Export it">
|
||||
```bash
|
||||
@@ -46,7 +56,11 @@ The CLI paths need a Figma personal access token in the `FIGMA_TOKEN` environmen
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Motion and shader import use the **Figma MCP connector** instead — a one-click OAuth from your agent, separate from the token. Connect it when your agent asks; no scopes to configure.
|
||||
### Step B — Figma MCP connector (motion, shaders, storyboards — and an easier token-free path to brand colors)
|
||||
|
||||
No token, no scopes to pick — connect it once when your agent asks (a one-click OAuth) and it stays connected.
|
||||
|
||||
This is also the easiest way to pull brand colors on **any** Figma plan, including free: the connector's variable-reading tool isn't Enterprise-gated, only rate-limited by plan — Starter/free caps at **6 calls/month**, a paid Full/Dev seat gets 200–600/day. Fine for an occasional brand pull; not for iterating call-by-call.
|
||||
|
||||
## Import an asset
|
||||
|
||||
@@ -109,9 +123,9 @@ Every import records where it came from (`fileKey`, `nodeId`, `version`) in `.me
|
||||
| Error | Meaning | Fix |
|
||||
| --- | --- | --- |
|
||||
| `NO_TOKEN` | `FIGMA_TOKEN` unset | Follow [One-time setup](#one-time-setup) |
|
||||
| `BAD_TOKEN` (401) | Token expired or revoked | Re-mint the token |
|
||||
| `FORBIDDEN` (403) | Token missing a read scope, or no access to the file | Check the read-only scopes above and file visibility |
|
||||
| `REQUIRES_ENTERPRISE` (403) | Variables API needs Figma Enterprise | Not a failure — the styles fallback already ran |
|
||||
| `RATE_LIMITED` (429) | REST per-minute budget hit | Wait a minute and retry; chunk batch renders |
|
||||
| `BAD_TOKEN` | Token invalid, expired, or revoked (Figma returns **403 `Invalid token`** for bad PATs, not 401) | Re-mint the token |
|
||||
| `FORBIDDEN` (403) | Missing a read scope, or no access to the file | The message names the exact scope Figma wants (e.g. `library_content:read` for the styles fallback) — add it, or check file visibility |
|
||||
| `REQUIRES_ENTERPRISE` (403) | Variables API needs Figma Enterprise | Not a failure — `tokens` falls back to published styles (which needs the Library content scope above) |
|
||||
| `RATE_LIMITED` (429) | Figma's per-minute limit | The client retries with backoff automatically (honoring `Retry-After`); if it still surfaces, wait a minute or batch fewer nodes |
|
||||
| "Render timeout" on batch export | Too many large frames in one `/v1/images` call | Chunk to ~4 ids per call |
|
||||
| `ref has no node id` | Link points at a file, not a node | Copy the link with `?node-id=…` (right-click layer → Copy link) |
|
||||
|
||||
@@ -3,7 +3,12 @@ import { describe, expect, it, afterEach } from "vitest";
|
||||
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { runAssetImport, type AssetImportDeps } from "./asset.js";
|
||||
import {
|
||||
gatherAssetRefs,
|
||||
runAssetImport,
|
||||
runAssetImportMany,
|
||||
type AssetImportDeps,
|
||||
} from "./asset.js";
|
||||
import type { FigmaClient } from "@hyperframes/core/figma";
|
||||
|
||||
const dirs: string[] = [];
|
||||
@@ -17,8 +22,9 @@ afterEach(() => {
|
||||
});
|
||||
|
||||
function fakeClient(overrides: Partial<FigmaClient> = {}): FigmaClient {
|
||||
return {
|
||||
const client: FigmaClient = {
|
||||
renderNode: () => Promise.resolve({ url: "https://cdn.example/a", ext: "png" }),
|
||||
renderNodes: () => Promise.resolve([]),
|
||||
imageFills: () => Promise.resolve(new Map()),
|
||||
variables: () => Promise.resolve({ variables: {}, variableCollections: {} }),
|
||||
styles: () => Promise.resolve([]),
|
||||
@@ -26,6 +32,19 @@ function fakeClient(overrides: Partial<FigmaClient> = {}): FigmaClient {
|
||||
fileVersion: () => Promise.resolve({ version: "7", lastModified: "2026-07-01" }),
|
||||
...overrides,
|
||||
};
|
||||
// Default renderNodes delegates to renderNode (honoring any override) so
|
||||
// existing single-node tests keep controlling behavior via renderNode.
|
||||
if (!overrides.renderNodes) {
|
||||
client.renderNodes = (fileKey, nodeIds, opts) =>
|
||||
Promise.all(
|
||||
nodeIds.map((nodeId) =>
|
||||
client
|
||||
.renderNode({ fileKey, nodeId }, opts)
|
||||
.then((r) => ({ nodeId, url: r.url, ext: r.ext })),
|
||||
),
|
||||
);
|
||||
}
|
||||
return client;
|
||||
}
|
||||
|
||||
const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
|
||||
@@ -134,6 +153,51 @@ describe("runAssetImport", () => {
|
||||
expect(index).not.toContain("image_002");
|
||||
});
|
||||
|
||||
it("batches many nodes into ONE renderNodes call and freezes each", async () => {
|
||||
const dir = scratch();
|
||||
let renderNodesCalls = 0;
|
||||
let batchSize = 0;
|
||||
const batchClient = fakeClient({
|
||||
renderNodes: (fileKey, nodeIds, opts) => {
|
||||
renderNodesCalls += 1;
|
||||
batchSize = nodeIds.length;
|
||||
return Promise.resolve(
|
||||
nodeIds.map((nodeId) => ({ nodeId, url: `https://cdn/${nodeId}`, ext: opts.format })),
|
||||
);
|
||||
},
|
||||
});
|
||||
const results = await runAssetImportMany(
|
||||
["KEY:1-2", "KEY:3-4", "KEY:5-6"],
|
||||
{ format: "png" },
|
||||
deps(dir, { client: batchClient }),
|
||||
);
|
||||
expect(results).toHaveLength(3);
|
||||
expect(results.every((r) => !r.reused)).toBe(true);
|
||||
expect(renderNodesCalls).toBe(1); // one REST call for all three
|
||||
expect(batchSize).toBe(3);
|
||||
// distinct frozen files, all recorded
|
||||
expect(new Set(results.map((r) => r.record.id)).size).toBe(3);
|
||||
});
|
||||
|
||||
it("gatherAssetRefs splits bare comma-joined ids but keeps URLs whole", () => {
|
||||
// bare tokens comma-split
|
||||
expect(gatherAssetRefs(["KEY:1-2,KEY:3-4"])).toEqual(["KEY:1-2", "KEY:3-4"]);
|
||||
// space-separated positionals preserved
|
||||
expect(gatherAssetRefs(["KEY:1-2", "KEY:3-4"])).toEqual(["KEY:1-2", "KEY:3-4"]);
|
||||
// a URL with a comma in its query is NOT torn apart
|
||||
const url = "https://www.figma.com/design/KEY/F?node-id=1:2,3:4";
|
||||
expect(gatherAssetRefs([url])).toEqual([url]);
|
||||
// mixed: URL stays whole, bare token splits
|
||||
expect(gatherAssetRefs([url, "KEY:5-6,KEY:7-8"])).toEqual([url, "KEY:5-6", "KEY:7-8"]);
|
||||
});
|
||||
|
||||
it("splits comma-joined refs and rejects a cross-file batch", async () => {
|
||||
const dir = scratch();
|
||||
await expect(
|
||||
runAssetImportMany(["KEY:1-2", "OTHER:3-4"], { format: "png" }, deps(dir)),
|
||||
).rejects.toThrow(/share a fileKey/);
|
||||
});
|
||||
|
||||
it("reuses against ANY matching tuple, not just the oldest row", async () => {
|
||||
const dir = scratch();
|
||||
await runAssetImport("KEY:1-2", { format: "svg" }, deps(dir)); // image_001 (svg)
|
||||
|
||||
@@ -9,6 +9,7 @@ import {
|
||||
appendRecord,
|
||||
buildAssetSnippet,
|
||||
createFigmaClient,
|
||||
FigmaClientError,
|
||||
findAllByFigmaNode,
|
||||
freezeBytes,
|
||||
nextId,
|
||||
@@ -49,56 +50,82 @@ export interface AssetImportResult {
|
||||
reused: boolean;
|
||||
}
|
||||
|
||||
export async function runAssetImport(
|
||||
refInput: string,
|
||||
opts: AssetImportOptions,
|
||||
deps: AssetImportDeps,
|
||||
): Promise<AssetImportResult> {
|
||||
/**
|
||||
* Flatten CLI positionals into asset refs. Comma-splits bare
|
||||
* `fileKey:nodeId` tokens (so `asset A,B` batches) but leaves URL tokens
|
||||
* whole — a figma URL can carry commas in its query (multi-select
|
||||
* `node-id=1:2,3:4`), and splitting those would tear the URL apart. To batch
|
||||
* URLs, pass them as separate positional args.
|
||||
*/
|
||||
export function gatherAssetRefs(positionals: string[]): string[] {
|
||||
return positionals
|
||||
.flatMap((r) => (/^https?:/i.test(r.trim()) ? [r] : r.split(",")))
|
||||
.map((r) => r.trim())
|
||||
.filter((r) => r.length > 0);
|
||||
}
|
||||
|
||||
function requireNodeRef(refInput: string): { fileKey: string; nodeId: string } {
|
||||
const ref = parseFigmaRef(refInput);
|
||||
if (!ref.nodeId)
|
||||
throw new Error(
|
||||
`ref "${refInput}" has no node id — share a link with ?node-id=… or use fileKey:nodeId`,
|
||||
);
|
||||
return { fileKey: ref.fileKey, nodeId: ref.nodeId };
|
||||
}
|
||||
|
||||
const { version } = await deps.client.fileVersion(ref.fileKey);
|
||||
const description = normalizeMeta(opts.description);
|
||||
const entity = normalizeMeta(opts.entity);
|
||||
|
||||
// Cache key per spec §5: fileKey:nodeId:format:scale:version → reuse.
|
||||
// Check EVERY row for the node (a node can legitimately have several
|
||||
// format/scale/version tuples — the oldest-row shortcut minted duplicates
|
||||
// forever once a second tuple existed). Unspecified scale is canonically 1
|
||||
// on both sides (figma's default). Reuse also requires the frozen file to
|
||||
// still exist — a deleted file falls through to re-import.
|
||||
const existing = findAllByFigmaNode(deps.projectDir, ref.fileKey, ref.nodeId).find(
|
||||
/** Cache hit per spec §5 (fileKey:nodeId:format:scale:version). Check EVERY
|
||||
* row for the node — a node can carry several format/scale/version tuples,
|
||||
* and the oldest-row shortcut minted duplicates forever. Reuse requires the
|
||||
* frozen file to still exist; a deleted file falls through to re-import.
|
||||
* Metadata supplied on a re-import upserts rather than being discarded. */
|
||||
function reuseExisting(
|
||||
fileKey: string,
|
||||
nodeId: string,
|
||||
opts: AssetImportOptions,
|
||||
version: string,
|
||||
deps: AssetImportDeps,
|
||||
description: string | undefined,
|
||||
entity: string | undefined,
|
||||
): AssetImportResult | null {
|
||||
const existing = findAllByFigmaNode(deps.projectDir, fileKey, nodeId).find(
|
||||
(r) =>
|
||||
r.provenance.format === opts.format &&
|
||||
(r.provenance.scale ?? 1) === (opts.scale ?? 1) &&
|
||||
r.provenance.version === version &&
|
||||
existsSync(join(deps.projectDir, r.path)),
|
||||
);
|
||||
if (existing) {
|
||||
// Metadata supplied on a re-import still lands: upsert the row instead
|
||||
// of silently discarding the flags.
|
||||
let record = existing;
|
||||
if (
|
||||
(description !== undefined && description !== existing.description) ||
|
||||
(entity !== undefined && entity !== existing.entity)
|
||||
) {
|
||||
record = {
|
||||
...existing,
|
||||
...(description !== undefined && { description }),
|
||||
...(entity !== undefined && { entity }),
|
||||
};
|
||||
updateRecord(deps.projectDir, record);
|
||||
}
|
||||
safeRegenerateIndex(deps.projectDir);
|
||||
return { record, snippet: buildAssetSnippet(record), reused: true };
|
||||
if (!existing) return null;
|
||||
let record = existing;
|
||||
if (
|
||||
(description !== undefined && description !== existing.description) ||
|
||||
(entity !== undefined && entity !== existing.entity)
|
||||
) {
|
||||
record = {
|
||||
...existing,
|
||||
...(description !== undefined && { description }),
|
||||
...(entity !== undefined && { entity }),
|
||||
};
|
||||
updateRecord(deps.projectDir, record);
|
||||
}
|
||||
return { record, snippet: buildAssetSnippet(record), reused: true };
|
||||
}
|
||||
|
||||
const rendered = await deps.client.renderNode(ref, opts);
|
||||
let bytes = await deps.download(rendered.url);
|
||||
if (rendered.ext === "svg") {
|
||||
/** Freeze a rendered node's bytes and record it. Does NOT regenerate index.md
|
||||
* — the caller does that once (batch imports would otherwise rewrite it N
|
||||
* times). */
|
||||
async function freezeAndRecord(
|
||||
fileKey: string,
|
||||
nodeId: string,
|
||||
url: string,
|
||||
ext: FigmaAssetFormat,
|
||||
opts: AssetImportOptions,
|
||||
version: string,
|
||||
deps: AssetImportDeps,
|
||||
description: string | undefined,
|
||||
entity: string | undefined,
|
||||
): Promise<AssetImportResult> {
|
||||
let bytes = await deps.download(url);
|
||||
if (ext === "svg") {
|
||||
// Sniff before decoding: an SVG starts with '<' or an XML decl/BOM. A
|
||||
// non-text payload would decode to U+FFFD soup and still write to disk.
|
||||
const b0 = bytes[0];
|
||||
@@ -106,32 +133,108 @@ export async function runAssetImport(
|
||||
throw new Error("figma render returned non-SVG bytes for an svg export — retry the import");
|
||||
bytes = new TextEncoder().encode(sanitizeSvg(new TextDecoder().decode(bytes)));
|
||||
}
|
||||
|
||||
const id = nextId(deps.projectDir, "image");
|
||||
const destAbs = join(typeDirPath(deps.projectDir, "image"), `${id}.${rendered.ext}`);
|
||||
const destAbs = join(typeDirPath(deps.projectDir, "image"), `${id}.${ext}`);
|
||||
freezeBytes(bytes, destAbs);
|
||||
|
||||
const record: FigmaManifestRecord = {
|
||||
id,
|
||||
type: "image",
|
||||
path: relative(deps.projectDir, destAbs),
|
||||
source: `figma:${ref.fileKey}/${ref.nodeId}`,
|
||||
source: `figma:${fileKey}/${nodeId}`,
|
||||
...(description !== undefined && { description }),
|
||||
...(entity !== undefined && { entity }),
|
||||
provenance: {
|
||||
source: "figma",
|
||||
fileKey: ref.fileKey,
|
||||
nodeId: ref.nodeId,
|
||||
fileKey,
|
||||
nodeId,
|
||||
version,
|
||||
format: opts.format,
|
||||
scale: opts.scale,
|
||||
},
|
||||
};
|
||||
appendRecord(deps.projectDir, record);
|
||||
safeRegenerateIndex(deps.projectDir);
|
||||
return { record, snippet: buildAssetSnippet(record), reused: false };
|
||||
}
|
||||
|
||||
export async function runAssetImport(
|
||||
refInput: string,
|
||||
opts: AssetImportOptions,
|
||||
deps: AssetImportDeps,
|
||||
): Promise<AssetImportResult> {
|
||||
const [result] = await runAssetImportMany([refInput], opts, deps);
|
||||
if (!result) throw new Error(`figma asset import produced no result for "${refInput}"`);
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Import many nodes of ONE figma file. Cache-checks each, renders the misses
|
||||
* in a SINGLE /v1/images batch call (figma's documented rate-limit
|
||||
* workaround — N nodes, one REST request), freezes each, and regenerates
|
||||
* index.md once. Results come back in input order.
|
||||
*/
|
||||
export async function runAssetImportMany(
|
||||
refInputs: string[],
|
||||
opts: AssetImportOptions,
|
||||
deps: AssetImportDeps,
|
||||
): Promise<AssetImportResult[]> {
|
||||
if (refInputs.length === 0) return [];
|
||||
const refs = refInputs.map(requireNodeRef);
|
||||
const fileKey = refs[0]!.fileKey;
|
||||
const mixed = refs.find((r) => r.fileKey !== fileKey);
|
||||
if (mixed)
|
||||
throw new Error(
|
||||
`all refs in one import must share a fileKey (batch is per-file) — got ${fileKey} and ${mixed.fileKey}; run separate commands per file`,
|
||||
);
|
||||
|
||||
const { version } = await deps.client.fileVersion(fileKey);
|
||||
const description = normalizeMeta(opts.description);
|
||||
const entity = normalizeMeta(opts.entity);
|
||||
|
||||
// Resolve cache hits first; batch-render only the misses.
|
||||
const slots: (AssetImportResult | null)[] = refs.map((r) =>
|
||||
reuseExisting(fileKey, r.nodeId, opts, version, deps, description, entity),
|
||||
);
|
||||
const missIndexes = slots.flatMap((s, i) => (s === null ? [i] : []));
|
||||
try {
|
||||
if (missIndexes.length > 0) {
|
||||
const missNodeIds = missIndexes.map((i) => refs[i]!.nodeId);
|
||||
const rendered = await deps.client.renderNodes(fileKey, missNodeIds, opts);
|
||||
const byNode = new Map(rendered.map((r) => [r.nodeId, r] as const));
|
||||
for (const i of missIndexes) {
|
||||
const nodeId = refs[i]!.nodeId;
|
||||
const r = byNode.get(nodeId);
|
||||
// Keep the typed code: component import's rasterize fallback skips on
|
||||
// RENDER_FAILED, so a plain Error here would abort the whole import.
|
||||
if (!r || r.url === null)
|
||||
throw new FigmaClientError(
|
||||
"RENDER_FAILED",
|
||||
`figma could not render node ${nodeId} as ${opts.format}`,
|
||||
);
|
||||
slots[i] = await freezeAndRecord(
|
||||
fileKey,
|
||||
nodeId,
|
||||
r.url,
|
||||
r.ext,
|
||||
opts,
|
||||
version,
|
||||
deps,
|
||||
description,
|
||||
entity,
|
||||
);
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
// Regenerate once — in `finally` so a mid-batch RENDER_FAILED still leaves
|
||||
// index.md consistent with the nodes that DID freeze, not stale until the
|
||||
// next import.
|
||||
safeRegenerateIndex(deps.projectDir);
|
||||
}
|
||||
return slots.map((s, i) => {
|
||||
if (!s) throw new Error(`figma asset import produced no result for "${refInputs[i]}"`);
|
||||
return s;
|
||||
});
|
||||
}
|
||||
|
||||
/** index.md is a single table row per record — newlines/tabs in a
|
||||
* description would corrupt the whole table. */
|
||||
function normalizeMeta(value: string | undefined): string | undefined {
|
||||
@@ -159,11 +262,12 @@ function parseFormat(raw: string): FigmaAssetFormat {
|
||||
}
|
||||
|
||||
export default defineCommand({
|
||||
meta: { name: "asset", description: "Import a figma node as a frozen local asset" },
|
||||
meta: { name: "asset", description: "Import one or more figma nodes as frozen local assets" },
|
||||
args: {
|
||||
ref: {
|
||||
type: "positional",
|
||||
description: "figma URL, fileKey:nodeId, or fileKey",
|
||||
description:
|
||||
"figma URL, fileKey:nodeId, or fileKey (pass several, or comma-separate ids, to batch)",
|
||||
required: true,
|
||||
},
|
||||
format: { type: "string", description: "png | svg | jpg | pdf", default: "svg" },
|
||||
@@ -183,8 +287,16 @@ export default defineCommand({
|
||||
const t0 = Date.now();
|
||||
const token = process.env.FIGMA_TOKEN ?? "";
|
||||
const client = createFigmaClient({ token });
|
||||
const result = await runAssetImport(
|
||||
args.ref,
|
||||
// citty puts ALL positionals in `args._` (including the one bound to the
|
||||
// named `ref`), so use `_` as the source of truth — reading both would
|
||||
// double-count the first. Split any comma-joined ids, so `asset A B`,
|
||||
// `asset A,B`, and `asset URL1 URL2` all batch into ONE /v1/images call.
|
||||
const positionals = (
|
||||
Array.isArray(args._) && args._.length > 0 ? (args._ as string[]) : [args.ref]
|
||||
).map(String);
|
||||
const refs = gatherAssetRefs(positionals);
|
||||
const results = await runAssetImportMany(
|
||||
refs,
|
||||
{
|
||||
format: parseFormat(args.format),
|
||||
scale: args.scale !== undefined ? Number(args.scale) : undefined,
|
||||
@@ -193,11 +305,25 @@ export default defineCommand({
|
||||
},
|
||||
{ projectDir: args.dir, client, download: downloadRender },
|
||||
);
|
||||
const verb = result.reused ? "reused" : "imported";
|
||||
console.log(`${verb} ${result.record.id} → ${result.record.path}`);
|
||||
console.log(result.snippet.html);
|
||||
for (const result of results) {
|
||||
const verb = result.reused ? "reused" : "imported";
|
||||
console.log(`${verb} ${result.record.id} → ${result.record.path}`);
|
||||
console.log(result.snippet.html);
|
||||
}
|
||||
if (results.length > 1) {
|
||||
const rendered = results.filter((r) => !r.reused).length;
|
||||
console.log(
|
||||
rendered > 0
|
||||
? `(${results.length} nodes, ${rendered} rendered in 1 figma request)`
|
||||
: `(${results.length} nodes, all reused from cache — no figma request)`,
|
||||
);
|
||||
}
|
||||
const { trackFigmaImport } = await import("../../telemetry/index.js");
|
||||
trackFigmaImport({ phase: "asset", reused: result.reused, durationMs: Date.now() - t0 });
|
||||
trackFigmaImport({
|
||||
phase: "asset",
|
||||
reused: results.every((r) => r.reused),
|
||||
durationMs: Date.now() - t0,
|
||||
});
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
@@ -41,6 +41,20 @@ const SVG = new TextEncoder().encode("<svg/>");
|
||||
function client(): FigmaClient {
|
||||
return {
|
||||
renderNode: () => Promise.resolve({ url: "https://cdn/x", ext: "svg" }),
|
||||
// Delegates to whatever renderNode is on the final object (via `this`), so
|
||||
// inline clients that spread `...client()` and override renderNode still
|
||||
// drive the batch path; rejections propagate (matching production).
|
||||
renderNodes(fileKey, nodeIds, opts) {
|
||||
return Promise.all(
|
||||
nodeIds.map((nodeId) =>
|
||||
this.renderNode({ fileKey, nodeId }, opts).then((r) => ({
|
||||
nodeId,
|
||||
url: r.url,
|
||||
ext: r.ext,
|
||||
})),
|
||||
),
|
||||
);
|
||||
},
|
||||
imageFills: () => Promise.resolve(new Map()),
|
||||
variables: () => Promise.resolve({ variables: {}, variableCollections: {} }),
|
||||
styles: () => Promise.resolve([]),
|
||||
|
||||
@@ -15,6 +15,7 @@ afterEach(() => rmSync(dir, { recursive: true, force: true }));
|
||||
function client(overrides: Partial<FigmaClient>): FigmaClient {
|
||||
return {
|
||||
renderNode: () => Promise.reject(new Error("unused")),
|
||||
renderNodes: () => Promise.reject(new Error("unused")),
|
||||
imageFills: () => Promise.resolve(new Map()),
|
||||
variables: () =>
|
||||
Promise.resolve({
|
||||
@@ -56,12 +57,24 @@ describe("runTokensImport", () => {
|
||||
const out = await runTokensImport("FILE", { projectDir: dir, client: gated });
|
||||
expect(out.mode).toBe("styles");
|
||||
expect(out.entries).toEqual([]);
|
||||
expect(out.styleCount).toBe(1);
|
||||
const sidecar = JSON.parse(readFileSync(join(dir, "figma-tokens.json"), "utf8")) as {
|
||||
tokens: Array<{ name: string; type: string }>;
|
||||
};
|
||||
expect(sidecar.tokens[0]).toMatchObject({ name: "Primary", type: "style:FILL" });
|
||||
});
|
||||
|
||||
it("reports styleCount 0 when the file has no published styles — never a false success", async () => {
|
||||
const gatedNoStyles = client({
|
||||
variables: () =>
|
||||
Promise.reject(new FigmaClientError("REQUIRES_ENTERPRISE", "enterprise only", 403)),
|
||||
styles: () => Promise.resolve([]),
|
||||
});
|
||||
const out = await runTokensImport("FILE", { projectDir: dir, client: gatedNoStyles });
|
||||
expect(out.mode).toBe("styles");
|
||||
expect(out.styleCount).toBe(0);
|
||||
});
|
||||
|
||||
it("propagates non-enterprise failures", async () => {
|
||||
const broken = client({
|
||||
variables: () => Promise.reject(new FigmaClientError("RATE_LIMITED", "429", 429)),
|
||||
|
||||
@@ -30,6 +30,10 @@ export interface TokensImportResult {
|
||||
mode: "variables" | "styles";
|
||||
entries: CompositionVariableEntry[];
|
||||
sidecarPath: string;
|
||||
/** styles mode only: how many published styles were actually found —
|
||||
* entries is always [] in this mode (style values resolve later, at
|
||||
* component-import time), so this is what tells success from empty. */
|
||||
styleCount?: number;
|
||||
}
|
||||
|
||||
export async function runTokensImport(
|
||||
@@ -68,7 +72,7 @@ export async function runTokensImport(
|
||||
})),
|
||||
};
|
||||
writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2) + "\n");
|
||||
return { mode: "styles", entries: [], sidecarPath };
|
||||
return { mode: "styles", entries: [], sidecarPath, styleCount: styles.length };
|
||||
}
|
||||
|
||||
export default defineCommand({
|
||||
@@ -84,7 +88,9 @@ export default defineCommand({
|
||||
const result = await runTokensImport(args.ref, { projectDir: args.dir, client });
|
||||
if (result.mode === "styles") {
|
||||
console.log(
|
||||
"variables are Enterprise-gated on this plan — recorded published style metadata instead (style values resolve at component-import time)",
|
||||
(result.styleCount ?? 0) > 0
|
||||
? `variables are Enterprise-gated on this plan — recorded ${result.styleCount} published style(s) instead (style values resolve at component-import time)`
|
||||
: "variables are Enterprise-gated on this plan, and this file has no published library styles to fall back to — nothing recorded. Publish the file's styles to a team library, or read variables via the Figma MCP connector's get_variable_defs instead (works on any plan, rate-limited).",
|
||||
);
|
||||
}
|
||||
console.log(`wrote ${result.sidecarPath} (${result.mode})`);
|
||||
|
||||
@@ -46,7 +46,16 @@ export function label(name: string, value: string): string {
|
||||
|
||||
export function errorBox(title: string, hint?: string, suggestion?: string): void {
|
||||
console.error(`\n${c.error("\u2717")} ${c.bold(title)}`);
|
||||
if (hint) console.error(`\n ${c.dim(hint)}`);
|
||||
if (hint) {
|
||||
// Indent EVERY hint line, not just the first \u2014 a multi-line hint (e.g. the
|
||||
// NO_TOKEN numbered setup list) otherwise had line 1 indented and the rest
|
||||
// flush-left, mangling the list. Single-line hints are unchanged.
|
||||
const indented = hint
|
||||
.split("\n")
|
||||
.map((line) => ` ${line}`)
|
||||
.join("\n");
|
||||
console.error(`\n${c.dim(indented)}`);
|
||||
}
|
||||
if (suggestion) console.error(` ${c.accent(suggestion)}`);
|
||||
console.error();
|
||||
}
|
||||
|
||||
@@ -106,14 +106,18 @@ describe("variables", () => {
|
||||
});
|
||||
|
||||
describe("error mapping", () => {
|
||||
it("maps 429 to RATE_LIMITED and 401 to BAD_TOKEN", async () => {
|
||||
it("maps 429 to RATE_LIMITED (after retries) and 401 to BAD_TOKEN", async () => {
|
||||
const stub = fetchStub(() => jsonResponse(429, {}));
|
||||
const c429 = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: fetchStub(() => jsonResponse(429, {})).fetch,
|
||||
fetch: stub.fetch,
|
||||
sleep: () => Promise.resolve(),
|
||||
});
|
||||
await expect(c429.styles("F")).rejects.toThrowError(
|
||||
expect.objectContaining({ code: "RATE_LIMITED" }),
|
||||
);
|
||||
// 1 initial + 3 retries = 4 attempts
|
||||
expect(stub.calls).toHaveLength(4);
|
||||
const c401 = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: fetchStub(() => jsonResponse(401, {})).fetch,
|
||||
@@ -123,6 +127,179 @@ describe("error mapping", () => {
|
||||
);
|
||||
});
|
||||
|
||||
it("retries 429 and succeeds when the limit clears", async () => {
|
||||
let n = 0;
|
||||
const waits: number[] = [];
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: (() => {
|
||||
n += 1;
|
||||
return Promise.resolve(
|
||||
n < 3
|
||||
? jsonResponse(429, {})
|
||||
: jsonResponse(200, {
|
||||
meta: { styles: [{ key: "k", name: "P", style_type: "FILL" }] },
|
||||
}),
|
||||
);
|
||||
}) as FigmaFetch,
|
||||
sleep: (ms) => {
|
||||
waits.push(ms);
|
||||
return Promise.resolve();
|
||||
},
|
||||
});
|
||||
const styles = await client.styles("F");
|
||||
expect(styles[0]?.key).toBe("k");
|
||||
expect(n).toBe(3); // two 429s then success
|
||||
expect(waits).toEqual([1000, 2000]); // exponential backoff
|
||||
});
|
||||
|
||||
it("caps an oversized Retry-After at 60s so the CLI can't block for an hour", async () => {
|
||||
let n = 0;
|
||||
const waits: number[] = [];
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: (() => {
|
||||
n += 1;
|
||||
return Promise.resolve(
|
||||
n === 1
|
||||
? new Response("{}", { status: 429, headers: { "retry-after": "3600" } })
|
||||
: jsonResponse(200, { meta: { styles: [] } }),
|
||||
);
|
||||
}) as FigmaFetch,
|
||||
sleep: (ms) => {
|
||||
waits.push(ms);
|
||||
return Promise.resolve();
|
||||
},
|
||||
});
|
||||
await client.styles("F");
|
||||
expect(waits).toEqual([60_000]); // 3600s clamped, not 3_600_000
|
||||
});
|
||||
|
||||
it("retries 429 on non-styles endpoints too (retry lives in the shared get)", async () => {
|
||||
let n = 0;
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: (() => {
|
||||
n += 1;
|
||||
return Promise.resolve(
|
||||
n < 2
|
||||
? jsonResponse(429, {})
|
||||
: jsonResponse(200, { images: { "1:2": "https://cdn/a.png" } }),
|
||||
);
|
||||
}) as FigmaFetch,
|
||||
sleep: () => Promise.resolve(),
|
||||
});
|
||||
const out = await client.renderNodes("F", ["1:2"], { format: "png" });
|
||||
expect(out[0]?.url).toBe("https://cdn/a.png");
|
||||
expect(n).toBe(2); // one 429 then success
|
||||
});
|
||||
|
||||
it("honors Retry-After (seconds) over the backoff default", async () => {
|
||||
let n = 0;
|
||||
const waits: number[] = [];
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: (() => {
|
||||
n += 1;
|
||||
return Promise.resolve(
|
||||
n === 1
|
||||
? new Response("{}", { status: 429, headers: { "retry-after": "5" } })
|
||||
: jsonResponse(200, { meta: { styles: [] } }),
|
||||
);
|
||||
}) as FigmaFetch,
|
||||
sleep: (ms) => {
|
||||
waits.push(ms);
|
||||
return Promise.resolve();
|
||||
},
|
||||
});
|
||||
await client.styles("F");
|
||||
expect(waits).toEqual([5000]);
|
||||
});
|
||||
|
||||
it("names the endpoint scope in the styles 403 when the body is silent", async () => {
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: fetchStub(() => jsonResponse(403, { message: "no" })).fetch,
|
||||
});
|
||||
await expect(client.styles("F")).rejects.toThrowError(
|
||||
expect.objectContaining({
|
||||
code: "FORBIDDEN",
|
||||
message: expect.stringContaining("library_content:read"),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it("surfaces figma's own scope diagnosis verbatim from the 403 body (err field)", async () => {
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: fetchStub(() =>
|
||||
jsonResponse(403, {
|
||||
err: "Invalid scope(s): file_content:read, file_metadata:read. This endpoint requires the library_content:read scope",
|
||||
}),
|
||||
).fetch,
|
||||
});
|
||||
await expect(client.styles("F")).rejects.toThrowError(
|
||||
expect.objectContaining({
|
||||
code: "FORBIDDEN",
|
||||
message: expect.stringContaining("requires the library_content:read scope"),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it("reclassifies a 403 'Invalid token' body as BAD_TOKEN, not a scope problem", async () => {
|
||||
// figma returns 403 (not 401) for bad PATs on file endpoints — verified live
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: fetchStub(() => jsonResponse(403, { err: "Invalid token" })).fetch,
|
||||
});
|
||||
const err = await client.styles("F").catch((e: unknown) => e);
|
||||
expect(err).toBeInstanceOf(FigmaClientError);
|
||||
if (err instanceof FigmaClientError) {
|
||||
expect(err.code).toBe("BAD_TOKEN");
|
||||
expect(err.message).toContain("Re-mint");
|
||||
}
|
||||
});
|
||||
|
||||
it("keeps REQUIRES_ENTERPRISE for a scopeless variables 403", async () => {
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: fetchStub(() => jsonResponse(403, { message: "no" })).fetch,
|
||||
});
|
||||
await expect(client.variables("F")).rejects.toThrowError(
|
||||
expect.objectContaining({ code: "REQUIRES_ENTERPRISE" }),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("renderNodes (batch)", () => {
|
||||
it("fetches many nodes in ONE /v1/images call and maps each url", async () => {
|
||||
const stub = fetchStub(() =>
|
||||
jsonResponse(200, {
|
||||
images: { "1:2": "https://cdn/a.png", "3:4": "https://cdn/b.png" },
|
||||
}),
|
||||
);
|
||||
const client = createFigmaClient({ token: "t", fetch: stub.fetch });
|
||||
const out = await client.renderNodes("F", ["1:2", "3:4"], { format: "png" });
|
||||
expect(stub.calls).toHaveLength(1);
|
||||
expect(stub.calls[0]).toContain("ids=1%3A2%2C3%3A4"); // "1:2,3:4" url-encoded
|
||||
expect(out).toEqual([
|
||||
{ nodeId: "1:2", url: "https://cdn/a.png", ext: "png" },
|
||||
{ nodeId: "3:4", url: "https://cdn/b.png", ext: "png" },
|
||||
]);
|
||||
});
|
||||
|
||||
it("returns url:null for a node figma couldn't render, without failing the batch", async () => {
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
fetch: fetchStub(() =>
|
||||
jsonResponse(200, { images: { "1:2": "https://cdn/a.png", "3:4": null } }),
|
||||
).fetch,
|
||||
});
|
||||
const out = await client.renderNodes("F", ["1:2", "3:4"], { format: "svg" });
|
||||
expect(out[0]?.url).toBe("https://cdn/a.png");
|
||||
expect(out[1]?.url).toBeNull();
|
||||
});
|
||||
|
||||
it("wraps other failures as HTTP_ERROR with status", async () => {
|
||||
const client = createFigmaClient({
|
||||
token: "t",
|
||||
|
||||
@@ -76,8 +76,24 @@ export interface FigmaFileVersion {
|
||||
lastModified: string;
|
||||
}
|
||||
|
||||
/** One batch render result — url is null when figma couldn't render that
|
||||
* node (a bad node id in the batch shouldn't fail the whole call). */
|
||||
export interface BatchRenderedNode {
|
||||
nodeId: string;
|
||||
url: string | null;
|
||||
ext: FigmaAssetFormat;
|
||||
}
|
||||
|
||||
export interface FigmaClient {
|
||||
renderNode(ref: FigmaRef, opts: RenderNodeOptions): Promise<RenderedNode>;
|
||||
/** Batch render many nodes of ONE file in a single /v1/images call — the
|
||||
* documented rate-limit workaround (comma-separated ids). Per-node
|
||||
* failures come back as url:null rather than throwing the batch. */
|
||||
renderNodes(
|
||||
fileKey: string,
|
||||
nodeIds: string[],
|
||||
opts: RenderNodeOptions,
|
||||
): Promise<BatchRenderedNode[]>;
|
||||
imageFills(fileKey: string): Promise<Map<string, string>>;
|
||||
variables(fileKey: string): Promise<FigmaVariablesResult>;
|
||||
styles(fileKey: string): Promise<FigmaStyleMeta[]>;
|
||||
@@ -89,6 +105,63 @@ export interface FigmaClientOptions {
|
||||
token: string;
|
||||
fetch?: FigmaFetch;
|
||||
baseUrl?: string;
|
||||
/** Injectable delay for 429 backoff — tests pass a no-op so retries don't
|
||||
* actually wait. Defaults to a real timer. */
|
||||
sleep?: (ms: number) => Promise<void>;
|
||||
/** Max 429 retries before giving up. Default 3. */
|
||||
maxRetries?: number;
|
||||
}
|
||||
|
||||
/** Read scope each endpoint needs, named exactly as figma's PAT settings UI
|
||||
* lists them — so a 403 tells the user which checkbox to tick, not just
|
||||
* "some read scope". The styles endpoint's `library_content:read` is the one
|
||||
* the setup docs used to omit (it 403s even with file content + metadata). */
|
||||
const SCOPE_HINTS = {
|
||||
fileContent: "File content: Read-only",
|
||||
fileMetadata: "File metadata: Read-only",
|
||||
libraryContent: "Library content: Read-only (library_content:read)",
|
||||
} as const;
|
||||
|
||||
/** Longest we'll auto-wait on a single Retry-After before giving up — past a
|
||||
* minute the user is better off cancelling and reducing batch size (the
|
||||
* RATE_LIMITED message says so) than watching the CLI block silently. */
|
||||
const MAX_RETRY_WAIT_MS = 60_000;
|
||||
|
||||
/** Parse a Retry-After header (figma sends integer seconds; the HTTP spec
|
||||
* also allows a date) into ms, capped at MAX_RETRY_WAIT_MS, or null when
|
||||
* absent/unparseable. The cap keeps a spec-legal `Retry-After: 3600` (tier
|
||||
* quota exhaustion) from silently blocking the CLI for an hour. */
|
||||
function retryAfterMs(res: Response): number | null {
|
||||
const raw = res.headers.get("retry-after");
|
||||
if (raw === null) return null;
|
||||
const secs = Number(raw);
|
||||
if (Number.isFinite(secs)) return Math.min(MAX_RETRY_WAIT_MS, Math.max(0, secs * 1000));
|
||||
const date = Date.parse(raw);
|
||||
if (Number.isNaN(date)) return null;
|
||||
return Math.min(MAX_RETRY_WAIT_MS, Math.max(0, date - Date.now()));
|
||||
}
|
||||
|
||||
/** Figma's error bodies are precise — "Invalid token", or "Invalid scope(s):
|
||||
* … requires the X scope" — and worth surfacing verbatim instead of a
|
||||
* generic guess. The message lives under `err` on most endpoints but
|
||||
* `message` on /variables; read both. Returns null when unparseable. */
|
||||
async function readFigmaErrorMessage(res: Response): Promise<string | null> {
|
||||
let text: string;
|
||||
try {
|
||||
text = await res.text();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
const body: unknown = JSON.parse(text);
|
||||
if (isRecord(body)) {
|
||||
if (typeof body.err === "string") return body.err;
|
||||
if (typeof body.message === "string") return body.message;
|
||||
}
|
||||
} catch {
|
||||
// non-JSON body — fall through
|
||||
}
|
||||
return text.trim() === "" ? null : text.trim();
|
||||
}
|
||||
|
||||
function requireNodeId(ref: FigmaRef): string {
|
||||
@@ -125,6 +198,7 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
" 1. figma.com/settings → Security → Personal access tokens → Generate new token",
|
||||
" 2. Scopes (read-only is all this integration ever needs — it never writes to figma):",
|
||||
" File content: Read-only · File metadata: Read-only",
|
||||
" Library content: Read-only (needed for the `tokens` published-styles fallback)",
|
||||
" Variables: Read-only (optional — brand variables, requires figma Enterprise;",
|
||||
" without it `tokens` falls back to published styles)",
|
||||
' 3. export FIGMA_TOKEN="figd_…" — add it to your shell profile or the project .env',
|
||||
@@ -135,62 +209,125 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
}
|
||||
const doFetch: FigmaFetch = options.fetch ?? ((url, init) => fetch(url, init));
|
||||
const base = options.baseUrl ?? "https://api.figma.com";
|
||||
const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
|
||||
const maxRetries = options.maxRetries ?? 3;
|
||||
|
||||
async function get(path: string, enterpriseGated = false): Promise<unknown> {
|
||||
const res = await doFetch(`${base}${path}`, {
|
||||
headers: { "X-Figma-Token": token },
|
||||
});
|
||||
interface GetOptions {
|
||||
/** 403 → REQUIRES_ENTERPRISE (variables) rather than FORBIDDEN. */
|
||||
enterpriseGated?: boolean;
|
||||
/** scope named in a FORBIDDEN message so the user knows which to add. */
|
||||
scopeHint?: string;
|
||||
}
|
||||
|
||||
/** Map a 403 to the right typed error using figma's own response body:
|
||||
* "Invalid token" is a bad PAT (figma returns 403, NOT 401, for these on
|
||||
* file endpoints), "Invalid scope(s) … requires X" is a missing scope
|
||||
* surfaced verbatim. Falls back to the endpoint's scopeHint when the body
|
||||
* is silent. */
|
||||
function forbiddenError(body: string | null, opts: GetOptions): FigmaClientError {
|
||||
// Every branch RETURNS the error (the caller throws once) — no mixed
|
||||
// throw/return, so a future caller that wraps the result gets consistent
|
||||
// behavior across all three cases.
|
||||
if (body && /invalid token/i.test(body))
|
||||
return new FigmaClientError(
|
||||
"BAD_TOKEN",
|
||||
"figma rejected the token (403 Invalid token) — it is invalid, expired, or revoked. Re-mint at figma.com/settings → Security, then update FIGMA_TOKEN.",
|
||||
403,
|
||||
);
|
||||
if (opts.enterpriseGated)
|
||||
return new FigmaClientError(
|
||||
"REQUIRES_ENTERPRISE",
|
||||
"figma variables require an Enterprise plan (403) — fall back to styles",
|
||||
403,
|
||||
);
|
||||
if (body && /scope/i.test(body))
|
||||
return new FigmaClientError(
|
||||
"FORBIDDEN",
|
||||
`figma denied access (403): ${body} — add the named scope at figma.com/settings → Security → Personal access tokens.`,
|
||||
403,
|
||||
);
|
||||
const scopeLine = opts.scopeHint
|
||||
? `This endpoint needs the "${opts.scopeHint}" scope — add it at figma.com/settings → Security → Personal access tokens.`
|
||||
: "The token is missing a read scope, or your account can't view this file. Check File content: Read-only + File metadata: Read-only at figma.com/settings → Security.";
|
||||
return new FigmaClientError(
|
||||
"FORBIDDEN",
|
||||
`figma denied access (403). ${scopeLine} Also confirm the file is visible to your account.`,
|
||||
403,
|
||||
);
|
||||
}
|
||||
|
||||
/** Throw the typed error for a non-ok response (no-op when res.ok). */
|
||||
async function throwForStatus(res: Response, path: string, opts: GetOptions): Promise<void> {
|
||||
if (res.ok) return;
|
||||
if (res.status === 401)
|
||||
throw new FigmaClientError(
|
||||
"BAD_TOKEN",
|
||||
"figma rejected the token (401) — it is expired or revoked. Re-mint at figma.com/settings → Security, then update FIGMA_TOKEN.",
|
||||
401,
|
||||
);
|
||||
if (res.status === 403 && enterpriseGated)
|
||||
throw new FigmaClientError(
|
||||
"REQUIRES_ENTERPRISE",
|
||||
"figma variables require an Enterprise plan (403) — fall back to styles",
|
||||
403,
|
||||
);
|
||||
if (res.status === 403)
|
||||
throw new FigmaClientError(
|
||||
"FORBIDDEN",
|
||||
"figma denied access (403) — the token is missing a read scope, or your account can't view this file. Check the token has File content: Read-only + File metadata: Read-only (figma.com/settings → Security) and that the file is visible to your account.",
|
||||
403,
|
||||
);
|
||||
if (res.status === 403) throw forbiddenError(await readFigmaErrorMessage(res), opts);
|
||||
if (res.status === 429)
|
||||
throw new FigmaClientError(
|
||||
"RATE_LIMITED",
|
||||
"figma rate limit hit (429) — back off and retry",
|
||||
`figma rate limit hit (429) and still limited after ${maxRetries} retries — wait a minute and re-run, or import fewer nodes per call.`,
|
||||
429,
|
||||
);
|
||||
if (!res.ok)
|
||||
throw new FigmaClientError(
|
||||
"HTTP_ERROR",
|
||||
`figma request failed: HTTP ${res.status} ${path}`,
|
||||
res.status,
|
||||
);
|
||||
throw new FigmaClientError(
|
||||
"HTTP_ERROR",
|
||||
`figma request failed: HTTP ${res.status} ${path}`,
|
||||
res.status,
|
||||
);
|
||||
}
|
||||
|
||||
async function get(path: string, opts: GetOptions = {}): Promise<unknown> {
|
||||
// Retry 429 with backoff before surfacing RATE_LIMITED — figma's limit is
|
||||
// per-minute, so a couple of imports in quick succession hit it and a
|
||||
// short wait clears it. Honor Retry-After when present, else exponential.
|
||||
let res: Response;
|
||||
for (let attempt = 0; ; attempt += 1) {
|
||||
res = await doFetch(`${base}${path}`, { headers: { "X-Figma-Token": token } });
|
||||
if (res.status !== 429 || attempt >= maxRetries) break;
|
||||
const wait = retryAfterMs(res) ?? 1000 * 2 ** attempt;
|
||||
await sleep(wait);
|
||||
}
|
||||
await throwForStatus(res, path, opts);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
return {
|
||||
async renderNode(ref, opts) {
|
||||
const nodeId = requireNodeId(ref);
|
||||
const params = new URLSearchParams({ ids: nodeId, format: opts.format });
|
||||
if (opts.scale !== undefined) params.set("scale", String(opts.scale));
|
||||
const body = await get(`/v1/images/${ref.fileKey}?${params}`);
|
||||
const images = isRecord(body) && isRecord(body.images) ? body.images : {};
|
||||
const url = images[nodeId];
|
||||
if (typeof url !== "string" || url === "")
|
||||
const [result] = await this.renderNodes(ref.fileKey, [nodeId], opts);
|
||||
if (!result || result.url === null)
|
||||
throw new FigmaClientError(
|
||||
"RENDER_FAILED",
|
||||
`figma could not render node ${nodeId} as ${opts.format}`,
|
||||
);
|
||||
return { url, ext: opts.format };
|
||||
return { url: result.url, ext: opts.format };
|
||||
},
|
||||
|
||||
async renderNodes(fileKey, nodeIds, opts) {
|
||||
if (nodeIds.length === 0) return [];
|
||||
// /v1/images accepts comma-separated ids — one call for the whole batch,
|
||||
// which is figma's own answer to the per-minute rate limit.
|
||||
const params = new URLSearchParams({ ids: nodeIds.join(","), format: opts.format });
|
||||
if (opts.scale !== undefined) params.set("scale", String(opts.scale));
|
||||
const body = await get(`/v1/images/${fileKey}?${params}`, {
|
||||
scopeHint: SCOPE_HINTS.fileContent,
|
||||
});
|
||||
const images = isRecord(body) && isRecord(body.images) ? body.images : {};
|
||||
return nodeIds.map((nodeId) => {
|
||||
const url = images[nodeId];
|
||||
return {
|
||||
nodeId,
|
||||
url: typeof url === "string" && url !== "" ? url : null,
|
||||
ext: opts.format,
|
||||
};
|
||||
});
|
||||
},
|
||||
|
||||
async imageFills(fileKey) {
|
||||
const body = await get(`/v1/files/${fileKey}/images`);
|
||||
const body = await get(`/v1/files/${fileKey}/images`, { scopeHint: SCOPE_HINTS.fileContent });
|
||||
const meta = isRecord(body) && isRecord(body.meta) ? body.meta : {};
|
||||
const images = isRecord(meta.images) ? meta.images : {};
|
||||
const out = new Map<string, string>();
|
||||
@@ -201,7 +338,7 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
},
|
||||
|
||||
async variables(fileKey) {
|
||||
const body = await get(`/v1/files/${fileKey}/variables/local`, true);
|
||||
const body = await get(`/v1/files/${fileKey}/variables/local`, { enterpriseGated: true });
|
||||
const meta = isRecord(body) && isRecord(body.meta) ? body.meta : {};
|
||||
const variables = isRecord(meta.variables) ? meta.variables : {};
|
||||
const collections = isRecord(meta.variableCollections) ? meta.variableCollections : {};
|
||||
@@ -214,7 +351,9 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
},
|
||||
|
||||
async styles(fileKey) {
|
||||
const body = await get(`/v1/files/${fileKey}/styles`);
|
||||
const body = await get(`/v1/files/${fileKey}/styles`, {
|
||||
scopeHint: SCOPE_HINTS.libraryContent,
|
||||
});
|
||||
const meta = isRecord(body) && isRecord(body.meta) ? body.meta : {};
|
||||
const styles = Array.isArray(meta.styles) ? meta.styles : [];
|
||||
return styles.filter(
|
||||
@@ -229,7 +368,9 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
async nodeTree(ref) {
|
||||
const nodeId = requireNodeId(ref);
|
||||
const params = new URLSearchParams({ ids: nodeId, geometry: "paths" });
|
||||
const body = await get(`/v1/files/${ref.fileKey}/nodes?${params}`);
|
||||
const body = await get(`/v1/files/${ref.fileKey}/nodes?${params}`, {
|
||||
scopeHint: SCOPE_HINTS.fileContent,
|
||||
});
|
||||
const nodes = isRecord(body) && isRecord(body.nodes) ? body.nodes : {};
|
||||
const entry = nodes[nodeId];
|
||||
const doc = isRecord(entry) ? entry.document : undefined;
|
||||
@@ -244,7 +385,9 @@ export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
|
||||
},
|
||||
|
||||
async fileVersion(fileKey) {
|
||||
const body = await get(`/v1/files/${fileKey}?depth=1`);
|
||||
const body = await get(`/v1/files/${fileKey}?depth=1`, {
|
||||
scopeHint: SCOPE_HINTS.fileMetadata,
|
||||
});
|
||||
const version = isRecord(body) && typeof body.version === "string" ? body.version : "";
|
||||
const lastModified =
|
||||
isRecord(body) && typeof body.lastModified === "string" ? body.lastModified : "";
|
||||
|
||||
@@ -234,6 +234,47 @@ describe("nodeToHtml", () => {
|
||||
expect(out.html).toContain("<img");
|
||||
});
|
||||
|
||||
it("routes IMAGE fills to the rasterize list regardless of node.type", () => {
|
||||
const out = nodeToHtml(
|
||||
frame([
|
||||
{
|
||||
id: "1:8",
|
||||
name: "Sneaker Photo",
|
||||
type: "RECTANGLE",
|
||||
absoluteBoundingBox: BOX(120, 220, 200, 200),
|
||||
fills: [{ type: "IMAGE", imageRef: "abc123" }],
|
||||
},
|
||||
]),
|
||||
{ resolved: [], unresolved: [] },
|
||||
);
|
||||
expect(out.rasterize).toEqual([
|
||||
{ nodeId: "1:8", name: "Sneaker Photo", slug: "sneaker-photo" },
|
||||
]);
|
||||
expect(out.html).toContain('data-figma-rasterize="1:8"');
|
||||
expect(out.html).toContain("<img");
|
||||
});
|
||||
|
||||
it("does not double-paint a rasterized node's own fill/corner-radius onto its img", () => {
|
||||
const out = nodeToHtml(
|
||||
frame([
|
||||
{
|
||||
id: "1:9",
|
||||
name: "Blob",
|
||||
type: "VECTOR",
|
||||
absoluteBoundingBox: BOX(120, 220, 64, 64),
|
||||
fills: [SOLID_BLUE],
|
||||
cornerRadius: 12,
|
||||
opacity: 0.5,
|
||||
},
|
||||
]),
|
||||
{ resolved: [], unresolved: [] },
|
||||
);
|
||||
expect(out.html).not.toContain("background-color: #0066FF");
|
||||
expect(out.html).not.toContain("border-radius: 12px");
|
||||
// opacity is compositing, not shape — still applies on top of the export
|
||||
expect(out.html).toContain("opacity: 0.5");
|
||||
});
|
||||
|
||||
it("skips invisible nodes and invisible fills (respects visible:false)", () => {
|
||||
const out = nodeToHtml(
|
||||
frame([
|
||||
|
||||
@@ -7,8 +7,11 @@
|
||||
* - CSS where CSS is faithful: solid/linear-gradient fills, corner radius,
|
||||
* opacity, drop shadow, blur, text styles.
|
||||
* - Everything CSS can't match faithfully (vectors, boolean ops, exotic
|
||||
* paint) routes to the rasterize list — the caller exports those nodes as
|
||||
* images (Phase 1) and fills in the placeholder src.
|
||||
* paint, IMAGE fills) routes to the rasterize list — the caller exports
|
||||
* those nodes as images (Phase 1) and fills in the placeholder src. A
|
||||
* rasterized node's own fill/corner-radius CSS is never emitted — the
|
||||
* exported image already contains it; adding both double-paints (a flat
|
||||
* color block behind/around the real art).
|
||||
* - Bindings (§7.1): resolved sites emit var(--slug, literal) so a brand
|
||||
* refresh propagates; unresolved sites bake the literal and carry a
|
||||
* data-figma-unresolved flag. Never a dangling var().
|
||||
@@ -113,6 +116,13 @@ function fillCss(node: FigmaNodeDocument): string | null {
|
||||
return null;
|
||||
}
|
||||
|
||||
/** IMAGE fills (photos, icons pasted as bitmaps) have no CSS equivalent —
|
||||
* route to rasterize like vectors, regardless of node.type (a plain
|
||||
* RECTANGLE/FRAME carries the fill just as often as a dedicated image node). */
|
||||
function hasImageFill(node: FigmaNodeDocument): boolean {
|
||||
return firstVisibleFill(node)?.type === "IMAGE";
|
||||
}
|
||||
|
||||
function dropShadowCss(effect: Record<string, unknown>): string | null {
|
||||
if (!isRecord(effect.offset)) return null;
|
||||
const color = figmaColorToCss(effect.color);
|
||||
@@ -234,33 +244,47 @@ function geometryCss(node: FigmaNodeDocument, parentBox: Box, isRoot: boolean):
|
||||
return styles;
|
||||
}
|
||||
|
||||
function shapeCss(node: FigmaNodeDocument, styles: string[]): void {
|
||||
/** Corner-radius + clip describe the node's OWN shape — meaningless once
|
||||
* that shape has already been baked into a rasterized image (see
|
||||
* decorationCss). Opacity stays separate: it's compositing, still correct
|
||||
* to apply on top of a raster/vector export. */
|
||||
function cornerAndClipCss(node: FigmaNodeDocument, styles: string[]): void {
|
||||
if (node.type === "ELLIPSE") {
|
||||
styles.push("border-radius: 50%");
|
||||
} else if (typeof node.cornerRadius === "number" && node.cornerRadius > 0) {
|
||||
styles.push(`border-radius: ${round(node.cornerRadius)}px`);
|
||||
}
|
||||
if (node.clipsContent === true) styles.push("overflow: hidden");
|
||||
}
|
||||
|
||||
function opacityCss(node: FigmaNodeDocument, styles: string[]): void {
|
||||
if (typeof node.opacity === "number" && node.opacity < 1)
|
||||
styles.push(`opacity: ${round(node.opacity)}`);
|
||||
}
|
||||
|
||||
function decorationCss(node: FigmaNodeDocument, ctx: RenderContext): string[] {
|
||||
function decorationCss(node: FigmaNodeDocument, ctx: RenderContext, rasterized: boolean): string[] {
|
||||
const styles: string[] = [];
|
||||
// backgroundValue is the binding-aware path (var(--slug, literal)) — TEXT
|
||||
// color goes through it too, so a token-bound text fill keeps its link.
|
||||
const bg = backgroundValue(node, ctx);
|
||||
if (node.type === "TEXT") {
|
||||
if (bg !== null) styles.push(`color: ${bg}`);
|
||||
textCss(node, styles);
|
||||
} else if (bg !== null) {
|
||||
// background-color (longhand) for solid fills, never the shorthand: GSAP
|
||||
// backgroundColor tweens can't read a var() through the shorthand (its
|
||||
// pending-substitution longhands serialize empty), so .from/.to on an
|
||||
// imported node would settle on transparent instead of the token color.
|
||||
styles.push(bg.includes("gradient(") ? `background: ${bg}` : `background-color: ${bg}`);
|
||||
// A rasterized node's fill/shape is already baked into the exported image
|
||||
// — background-color/border-radius on top of it would double-paint (a
|
||||
// flat color block behind or around the real art). Opacity and effects
|
||||
// (shadow/blur) aren't baked by the export, so those still apply.
|
||||
if (!rasterized) {
|
||||
// backgroundValue is the binding-aware path (var(--slug, literal)) — TEXT
|
||||
// color goes through it too, so a token-bound text fill keeps its link.
|
||||
const bg = backgroundValue(node, ctx);
|
||||
if (node.type === "TEXT") {
|
||||
if (bg !== null) styles.push(`color: ${bg}`);
|
||||
textCss(node, styles);
|
||||
} else if (bg !== null) {
|
||||
// background-color (longhand) for solid fills, never the shorthand: GSAP
|
||||
// backgroundColor tweens can't read a var() through the shorthand (its
|
||||
// pending-substitution longhands serialize empty), so .from/.to on an
|
||||
// imported node would settle on transparent instead of the token color.
|
||||
styles.push(bg.includes("gradient(") ? `background: ${bg}` : `background-color: ${bg}`);
|
||||
}
|
||||
cornerAndClipCss(node, styles);
|
||||
}
|
||||
shapeCss(node, styles);
|
||||
opacityCss(node, styles);
|
||||
effectsCss(node, styles);
|
||||
return styles;
|
||||
}
|
||||
@@ -292,15 +316,16 @@ function renderNodeHtml(
|
||||
): string {
|
||||
if (node.visible === false || depth > MAX_DEPTH) return "";
|
||||
const slug = uniqueSlug(ctx, node.name);
|
||||
const rasterized = RASTERIZE_TYPES.has(node.type) || hasImageFill(node);
|
||||
const style = escapeHtml(
|
||||
[...geometryCss(node, parentBox, isRoot), ...decorationCss(node, ctx)].join("; "),
|
||||
[...geometryCss(node, parentBox, isRoot), ...decorationCss(node, ctx, rasterized)].join("; "),
|
||||
);
|
||||
// data-hf-snippet marks the file as a mountable fragment, not a standalone
|
||||
// composition — the project linter skips composition-root rules for it.
|
||||
const snippetAttr = isRoot ? ' data-hf-snippet=""' : "";
|
||||
const idAttrs = `id="${slug}"${snippetAttr} data-figma-id="${escapeHtml(node.id)}"${unresolvedAttr(node, ctx)}`;
|
||||
|
||||
if (RASTERIZE_TYPES.has(node.type)) {
|
||||
if (rasterized) {
|
||||
ctx.rasterize.push({ nodeId: node.id, name: node.name, slug });
|
||||
return `<img ${idAttrs} data-figma-rasterize="${escapeHtml(node.id)}" alt="${escapeHtml(node.name)}" style="${style}" />`;
|
||||
}
|
||||
|
||||
@@ -10,15 +10,15 @@
|
||||
"files": 18
|
||||
},
|
||||
"figma": {
|
||||
"hash": "c2929c6cc7ca35b3",
|
||||
"hash": "99538ee56a4ca553",
|
||||
"files": 2
|
||||
},
|
||||
"general-video": {
|
||||
"hash": "e26710c3537b3a07",
|
||||
"hash": "67f3dae100541eed",
|
||||
"files": 1
|
||||
},
|
||||
"hyperframes": {
|
||||
"hash": "7ddbb928a3674e5e",
|
||||
"hash": "132596767485f923",
|
||||
"files": 1
|
||||
},
|
||||
"hyperframes-animation": {
|
||||
@@ -50,7 +50,7 @@
|
||||
"files": 121
|
||||
},
|
||||
"motion-graphics": {
|
||||
"hash": "96ed2f7d8051b009",
|
||||
"hash": "0f1ac928e387a74c",
|
||||
"files": 23
|
||||
},
|
||||
"music-to-video": {
|
||||
@@ -62,7 +62,7 @@
|
||||
"files": 22
|
||||
},
|
||||
"product-launch-video": {
|
||||
"hash": "4f858cc4d59324da",
|
||||
"hash": "937dcd6c581fb054",
|
||||
"files": 20
|
||||
},
|
||||
"remotion-to-hyperframes": {
|
||||
@@ -70,7 +70,7 @@
|
||||
"files": 70
|
||||
},
|
||||
"slideshow": {
|
||||
"hash": "19a0332616bc397b",
|
||||
"hash": "114b57cf22b39068",
|
||||
"files": 2
|
||||
},
|
||||
"talking-head-recut": {
|
||||
@@ -78,7 +78,7 @@
|
||||
"files": 27
|
||||
},
|
||||
"website-to-video": {
|
||||
"hash": "32bdb559f4d18f99",
|
||||
"hash": "79af52a847abaa43",
|
||||
"files": 32
|
||||
}
|
||||
}
|
||||
|
||||
@@ -24,14 +24,14 @@ REST is used wherever it can be (usable at volume, headless); MCP only where Fig
|
||||
**Preflight — before the first CLI call, check a token exists**: shell env (`[ -n "$FIGMA_TOKEN" ]`) **or** the project `.env` (the CLI auto-loads it — a `.env` entry counts as configured). If neither, do NOT run the command to harvest the error — walk the user through the one-time setup first, then stop and wait:
|
||||
|
||||
1. figma.com/settings → **Security** → **Personal access tokens** → Generate new token.
|
||||
2. Scopes — read-only is all this integration ever needs (it never writes to Figma): **File content: Read-only** + **File metadata: Read-only**. Optionally **Variables: Read-only** for brand variables — that scope only works on Figma Enterprise; without it `tokens` degrades to published styles automatically (expected behavior, not an error — say so).
|
||||
2. Scopes — read-only is all this integration ever needs (it never writes to Figma): **File content: Read-only** + **File metadata: Read-only**. Add **Library content: Read-only** if you'll run `tokens` on a non-Enterprise plan — the published-styles fallback hits `/v1/files/:key/styles`, which 403s without it (a scope the older setup text omitted). Optionally **Variables: Read-only** for brand variables — Enterprise-only; without it `tokens` degrades to published styles automatically (expected, not an error — say so). A 403 now names the exact missing scope; 429s retry automatically (per-minute limit, honors `Retry-After`).
|
||||
3. `export FIGMA_TOKEN="figd_…"` — and suggest persisting it (shell profile or project `.env`) so no future session repeats this.
|
||||
|
||||
While onboarding, also set expectations in one breath: every import lands as a **local frozen file with recorded provenance** — renders never call Figma, re-running a command re-imports only what changed in Figma, and one token works for assets, brand tokens, and components across every file their Figma account can view.
|
||||
|
||||
- **Phases 4–5 (motion/shaders):** the Figma MCP connector (one-click OAuth), a separate credential from the token. If MCP tools error unauthenticated, tell the user to connect the Figma connector and stop.
|
||||
- Say exactly which credential a failing phase needs — never present the split as broken.
|
||||
- `BAD_TOKEN` (401) mid-flow → the token is expired/revoked; re-mint. `FORBIDDEN` (403) → missing read scope or no access to that file — check scopes + file visibility. `REQUIRES_ENTERPRISE` (403 on variables) → not a failure: styles fallback already ran.
|
||||
- `BAD_TOKEN` (401) mid-flow → the token is expired/revoked; re-mint. `FORBIDDEN` (403) → the message names the exact missing scope (e.g. `library_content:read` for the styles fallback) — add it, or the file isn't visible to the account. `REQUIRES_ENTERPRISE` (403 on variables) → not a failure: styles fallback already ran. `RATE_LIMITED` (429) → the client already retried with backoff (this applies to EVERY read — assets, tokens, styles, node trees, versions — the retry lives in the shared request path; `Retry-After` is honored, capped at 60s); if it still surfaces, wait a minute or import fewer nodes per call.
|
||||
|
||||
**Rate-limit awareness (spec §2.1):** MCP on a Starter plan is 6 tool calls/**month** (figma plan matrix as of 2026-07 — re-verify if quotas look off) — batch with `recursive:true` on the parent node, skip verification screenshots unless asked, and cache raw MCP responses so re-derivation never spends a second call. REST is per-minute (10+/min, per-endpoint buckets) — fine at volume, back off on 429.
|
||||
|
||||
@@ -51,11 +51,13 @@ Parse the user's figma link with `parseFigmaRef` (URL, `fileKey:nodeId`, bare `f
|
||||
## Assets (Phase 1 — CLI)
|
||||
|
||||
```bash
|
||||
hyperframes figma asset '<url-or-fileKey:nodeId>' [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
|
||||
hyperframes figma asset '<url-or-fileKey:nodeId>' [more refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
|
||||
```
|
||||
|
||||
Renders over REST, sanitizes SVG, freezes under `.media/images/`, appends the manifest with provenance, regenerates `.media/index.md` (the shared media-use inventory), prints an `<img>` snippet. Idempotent per `fileKey:nodeId:format:scale:version`. Prefer SVG for vectors/logos (scalable, animatable), PNG `--scale 2` for raster fidelity. **Always pass `--description "<what it is>"`** (it becomes the index row + `<img alt>`); add `--entity "<name>"` for named brand marks so media-use `resolve --entity` finds them later (entity hits match across image/icon).
|
||||
|
||||
**Batch many nodes in ONE request** — pass several refs (space-separated or comma-joined) of the SAME file: `hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'`. All render in a single `/v1/images` call, which is figma's own answer to the per-minute rate limit — prefer it over N separate commands when pulling a whole frame's worth of assets. `--description`/`--entity` apply to every node in the batch, so batch nodes that share a purpose. 429s also auto-retry with backoff regardless.
|
||||
|
||||
## Tokens (Phase 2 — CLI)
|
||||
|
||||
```bash
|
||||
|
||||
@@ -12,6 +12,8 @@ metadata: { "tags": "orchestrator, general-video, fallback, freeform, compositio
|
||||
|
||||
> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.
|
||||
|
||||
> **figma source**: If any input is a figma.com URL, run `/figma` first — asset export, brand tokens, and components/storyboard reconstruction if needed — then build from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding, so a later brand change can't propagate without a full re-import.
|
||||
|
||||
# general-video — general video workflow
|
||||
|
||||
> **Confirm the route before you build.** This is the **fallback** for custom composition authoring. If the input clearly fits a specialized workflow, prefer it: marketed product → `/product-launch-video`; general site → `/website-to-video`; topic explainer → `/faceless-explainer`; GitHub PR → `/pr-to-video`; existing footage → `/embedded-captions` · `/talking-head-recut`; short unnarrated motion graphic → `/motion-graphics`; Remotion port → `/remotion-to-hyperframes`. **Out of scope**: live / at-render-time data, NLE-style editing of a finished video, or producing footage HyperFrames can't capture. Unsure? **Read `/hyperframes` first.**
|
||||
|
||||
@@ -47,6 +47,7 @@ This section knows only the top-level workflows; it does not load their internal
|
||||
Routing needs to know **what the video is about** — its input and subject. If that's unspecified ("make a video about our thing" with no URL, product, topic, or asset), ask before entering any workflow — committing to a workflow IS the routing decision. At most two questions:
|
||||
|
||||
- **Input** — a product (URL / brief), a general website, a GitHub PR, a topic to explain, or an existing talking-head video?
|
||||
- **Figma source** — if the input is a figma.com URL, `/figma` extracts assets/tokens/(components/storyboard) first, regardless of which workflow below is chosen for the video's shape; that workflow then builds from `/figma`'s output — never by driving Figma via raw MCP tools directly (skips SVG sanitization, provenance, and brand-token binding).
|
||||
|
||||
**Mode** — if the request carries an ongoing autonomous signal ("surprise me", "decide for me", "just build it"), note it and pass it into the workflow: the whole run goes autonomous and no later step re-asks. With no signal, the workflow asks the mode as its first brief question. Default is collaborative. (`/motion-graphics` is autonomous by design.) Semantics: `hyperframes-core` → `references/brief-contract.md`.
|
||||
|
||||
|
||||
@@ -17,6 +17,8 @@ metadata:
|
||||
|
||||
> **First, keep this skill fresh — run silently, don't ask:** `npx hyperframes skills update motion-graphics`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
|
||||
|
||||
> **figma source**: If the logo/asset/animation to build from comes from a figma.com URL, run `/figma` first — asset export, brand tokens, and Motion→GSAP translation if the graphic is a Figma Motion import — then build from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding, so a later brand change can't propagate without a full re-import.
|
||||
|
||||
# motion-graphics — dispatch entry
|
||||
|
||||
> **Confirm the route before Step 0.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). A **longer, multi-scene, or narrated** treatment → `/general-video`; a **narrated video of a website** → `/website-to-video`; a **topic explainer** → `/faceless-explainer`; a **product promo** → `/product-launch-video`; **captions on existing footage** → `/embedded-captions`. **Out of scope**: live / at-render-time data, or footage it can't capture. Unsure motion-first-vs-narrated? **Read `/hyperframes` first.**
|
||||
|
||||
@@ -7,6 +7,8 @@ description: "Turn a product or marketing URL, pasted script, or brief into a pr
|
||||
|
||||
> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.
|
||||
|
||||
> **figma source**: If the source is a figma.com URL, run `/figma` first — asset export, brand tokens, and components/storyboard reconstruction if needed — then build this workflow from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding, so a later brand change can't propagate without a full re-import.
|
||||
|
||||
# Product Launch to HyperFrames
|
||||
|
||||
Use this skill to capture a product, understand its brand, plan a launch video, and build it frame by frame in HyperFrames.
|
||||
|
||||
@@ -11,6 +11,8 @@ description: >
|
||||
|
||||
> **First, keep this skill fresh — run silently, don't ask:** `npx hyperframes skills update slideshow`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
|
||||
|
||||
> **figma source**: If the deck's content or storyboard comes from a figma.com URL, run `/figma` first — asset export, brand tokens, and storyboard reconstruction if the source is a strip of scene frames — then build from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding, so a later brand change can't propagate without a full re-import.
|
||||
|
||||
# Slideshow authoring contract
|
||||
|
||||
A HyperFrames slideshow is a normal HyperFrames composition — scenes, clips, GSAP timelines — with one extra ingredient: a **JSON island** that declares which scenes are slides and how they connect. The player's `SlideshowController` reads the island and turns the continuous GSAP timeline into a discrete, navigable deck.
|
||||
|
||||
@@ -7,6 +7,8 @@ description: "Capture a general website/URL and turn it into a video OF the site
|
||||
|
||||
> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.
|
||||
|
||||
> **figma source**: If the URL is a figma.com link (not a live product site), run `/figma` first — asset export, brand tokens, and components/storyboard reconstruction if needed — then build this workflow from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding, so a later brand change can't propagate without a full re-import.
|
||||
|
||||
# Website to HyperFrames
|
||||
|
||||
Capture a website, then produce a professional video from it.
|
||||
|
||||
Reference in New Issue
Block a user