Skip to content

Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.

fix(figma): refresh screen thumbnails on the UP_TO_DATE path

grumingc91a0c1bd59e
diff --git a/understand-anything-plugin/packages/core/src/figma/__tests__/thumbnails.test.ts b/understand-anything-plugin/packages/core/src/figma/__tests__/thumbnails.test.ts
new file mode 100644
index 00000000..66c2bd8c
--- /dev/null
+++ b/understand-anything-plugin/packages/core/src/figma/__tests__/thumbnails.test.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { applyScreenThumbnails } from "../thumbnails";
+import type { GraphNode } from "../../types";
+
+function node(id: string, type: GraphNode["type"], nodeId: string): GraphNode {
+ return {
+ id, type, name: id, summary: id, tags: [type], complexity: "simple",
+ figmaMeta: { fileKey: "ABC", nodeId },
+ };
+}
+
+describe("applyScreenThumbnails", () => {
+ it("sets thumbnailUrl only on screen nodes present in the images map", () => {
+ const nodes: GraphNode[] = [
+ node("screen:10:0", "screen", "10:0"),
+ node("component:2:1", "component", "2:1"), // non-screen → ignored even if in map
+ node("screen:11:0", "screen", "11:0"), // screen but not in map → untouched
+ ];
+ const updated = applyScreenThumbnails(nodes, {
+ "10:0": "https://figma/a.png",
+ "2:1": "https://figma/c.png",
+ });
+ expect(updated).toBe(1);
+ expect(nodes[0].figmaMeta?.thumbnailUrl).toBe("https://figma/a.png");
+ expect(nodes[1].figmaMeta?.thumbnailUrl).toBeUndefined();
+ expect(nodes[2].figmaMeta?.thumbnailUrl).toBeUndefined();
+ });
+
+ it("returns 0 and mutates nothing when no screens match", () => {
+ const nodes: GraphNode[] = [node("screen:9:9", "screen", "9:9")];
+ const updated = applyScreenThumbnails(nodes, {});
+ expect(updated).toBe(0);
+ expect(nodes[0].figmaMeta?.thumbnailUrl).toBeUndefined();
+ });
+});
diff --git a/understand-anything-plugin/packages/core/src/figma/index.ts b/understand-anything-plugin/packages/core/src/figma/index.ts
index 042adaa2..ed398795 100644
--- a/understand-anything-plugin/packages/core/src/figma/index.ts
+++ b/understand-anything-plugin/packages/core/src/figma/index.ts
@@ -2,4 +2,5 @@ export { parseFileKey, FigmaApiSource } from "./source/api-source.js";
export type { FigmaSource, FigmaDocument, FigmaStyles, FigmaNode } from "./source/types.js";
export { parseDocument } from "./parse/parse-document.js";
export { extractTokens } from "./parse/tokens.js";
+export { applyScreenThumbnails } from "./thumbnails.js";
export { mergeDesignGraph, type DesignAnalysis } from "./merge.js";
diff --git a/understand-anything-plugin/packages/core/src/figma/thumbnails.ts b/understand-anything-plugin/packages/core/src/figma/thumbnails.ts
new file mode 100644
index 00000000..00f93ce3
--- /dev/null
+++ b/understand-anything-plugin/packages/core/src/figma/thumbnails.ts
@@ -0,0 +1,29 @@
+import type { GraphNode } from "../types.js";
+
+/**
+ * Set `figmaMeta.thumbnailUrl` on screen nodes from a Figma image-render map
+ * (Figma nodeId → pre-signed image URL). Mutates matching nodes in place and
+ * returns how many were updated.
+ *
+ * Shared by figma-scan.mjs: the normal scan sets thumbnails on freshly parsed
+ * nodes, and the UP_TO_DATE path re-renders and refreshes the existing graph's
+ * thumbnails — the URLs are pre-signed and expire after a few hours, so a
+ * re-run must refresh them or the dashboard shows broken sidebar previews.
+ */
+export function applyScreenThumbnails(
+ nodes: GraphNode[],
+ images: Record<string, string>,
+): number {
+ let updated = 0;
+ for (const n of nodes) {
+ if (n.type !== "screen") continue;
+ const figmaId = n.figmaMeta?.nodeId;
+ if (!figmaId || !n.figmaMeta) continue;
+ const url = images[figmaId];
+ if (url) {
+ n.figmaMeta.thumbnailUrl = url;
+ updated++;
+ }
+ }
+ return updated;
+}
diff --git a/understand-anything-plugin/skills/understand-figma/figma-scan.mjs b/understand-anything-plugin/skills/understand-figma/figma-scan.mjs
index b453f245..ea95a65f 100644
--- a/understand-anything-plugin/skills/understand-figma/figma-scan.mjs
+++ b/understand-anything-plugin/skills/understand-figma/figma-scan.mjs
@@ -1,7 +1,7 @@
#!/usr/bin/env node
import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
import { join } from "node:path";
-import { parseFileKey, FigmaApiSource, parseDocument, extractTokens } from "@understand-anything/core/figma";
+import { parseFileKey, FigmaApiSource, parseDocument, extractTokens, applyScreenThumbnails } from "@understand-anything/core/figma";
const [, , projectRoot, urlOrKey] = process.argv;
if (!projectRoot || !urlOrKey) {
@@ -23,6 +23,11 @@ if (existsSync(metaPath)) {
}
}
if (doc.version && prevVersion === doc.version && process.env.UNDERSTAND_FIGMA_FORCE !== "1") {
+ // Content is unchanged, but the stored screen thumbnail URLs are pre-signed
+ // and expire after a few hours. Refresh them in the existing graph so a later
+ // re-run doesn't leave the dashboard with broken sidebar thumbnails, then
+ // skip the expensive re-parse + LLM re-analysis.
+ await refreshThumbnailsInPlace(projectRoot, source);
console.error("UP_TO_DATE");
process.exit(0);
}
@@ -39,10 +44,7 @@ const edges = [...structural.edges, ...tokens.edges];
const screens = structural.nodes.filter((n) => n.type === "screen");
try {
const images = await source.renderImages(screens.map((n) => n.figmaMeta.nodeId));
- for (const s of screens) {
- const url = images[s.figmaMeta.nodeId];
- if (url) s.figmaMeta.thumbnailUrl = url;
- }
+ applyScreenThumbnails(structural.nodes, images);
} catch {
// thumbnails are optional — never fail the scan on image render
}
@@ -72,3 +74,28 @@ console.error(
`${count("component")} components, ${count("componentSet")} sets, ` +
`${count("instance")} instances, ${count("token")} tokens`,
);
+
+/**
+ * On the incremental UP_TO_DATE path we skip the full re-scan, but the screen
+ * thumbnail URLs already stored in knowledge-graph.json are pre-signed and
+ * expire after a few hours. Re-render them and patch the existing graph in
+ * place so the dashboard sidebar doesn't show broken images on a later re-run.
+ * Best-effort: never throw (thumbnails are optional).
+ */
+async function refreshThumbnailsInPlace(projectRoot, source) {
+ const graphPath = join(projectRoot, ".understand-anything", "knowledge-graph.json");
+ if (!existsSync(graphPath)) return;
+ try {
+ const graph = JSON.parse(readFileSync(graphPath, "utf8"));
+ const screens = (graph.nodes ?? []).filter(
+ (n) => n.type === "screen" && n.figmaMeta?.nodeId,
+ );
+ if (screens.length === 0) return;
+ const images = await source.renderImages(screens.map((n) => n.figmaMeta.nodeId));
+ if (applyScreenThumbnails(graph.nodes, images) > 0) {
+ writeFileSync(graphPath, JSON.stringify(graph, null, 2));
+ }
+ } catch {
+ // thumbnails are optional — never fail the up-to-date path on refresh
+ }
+}