perf(studio): re-render only the edited scene's thumbnails after an edit (#4315)

* perf(studio): refresh only the edited scene's thumbnails and let the preview load first

One scene edit regenerated every sidebar and timeline thumbnail, and those renders starved the new preview's requests on the Studio server. The thumbnail cache now keys on what a composition renders from, the server names the compositions a write affects, only those thumbnails refresh, and composition thumbnails wait while a shadow preview reload is in flight.

* test(studio): pin scene-scoped thumbnail reuse and the preview-reload hold

Memoizes the scoped thumbnail signature on the project signature so requests keep reusing the adapter's cached one, keeps the fresh-signature check that catches a write the watcher has not reported yet, and adds tests for sibling-scene reuse, root-head invalidation, the affected-composition set, per-path revisions and the scheduler hold.

* refactor(studio): share the file-change payload guard

* fix(studio): match thumbnail revisions for scenes mounted with a ./ path

* perf(studio): keep signature cache keys constant-size

* style(studio): format thumbnail-scope changes

* docs(studio): trim thumbnail input comments

Author: miguel-heygen

packages/cli/src/server/studioServer.ts

@@ -39,6 +39,7 @@ import {
   fileContentVersion,
   getMimeType,
   affectsProjectSignature,
+  compositionsAffectedBy,
   type PreviewApiAdapter,
   thumbnailDeviceScaleFactor,
   type ResolvedProject,
@@ -834,7 +835,14 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
         stream
           .writeSSE({
             event: "file-change",
-            data: JSON.stringify({ path, version, projectId: project.id, ...receipt }),
+            data: JSON.stringify({
+              path,
+              version,
+              projectId: project.id,
+              // Which thumbnails this write can change; null means all of them.
+              affectedCompositions: compositionsAffectedBy(projectDir, path),
+              ...receipt,
+            }),
           })
           .catch(() => {});
       };

packages/studio-server/src/helpers/compositionInputs.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { compositionsAffectedBy } from "./compositionInputs";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function project(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "hf-composition-inputs-"));
+  dirs.push(dir);
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(join(dir, path, ".."), { recursive: true });
+    writeFileSync(join(dir, path), content);
+  }
+  return dir;
+}
+
+const mount = (src: string) => `<div data-composition-src="${src}"></div>`;
+
+describe("compositionsAffectedBy", () => {
+  const dir = () =>
+    project({
+      "index.html": mount("compositions/a.html") + mount("./compositions/b.html"),
+      "compositions/a.html": `<template>${mount("compositions/nested.html")}</template>`,
+      "compositions/b.html": "<template>b</template>",
+      "compositions/nested.html": "<template>nested</template>",
+      "compositions/unmounted.html": "<template>draft</template>",
+      "assets/logo.svg": "<svg/>",
+    });
+
+  it("names a scene and the compositions that mount it, not its siblings", () => {
+    expect(compositionsAffectedBy(dir(), "compositions/b.html")).toEqual([
+      "index.html",
+      "compositions/b.html",
+    ]);
+    expect(compositionsAffectedBy(dir(), "compositions/nested.html")).toEqual([
+      "index.html",
+      "compositions/a.html",
+      "compositions/nested.html",
+    ]);
+  });
+
+  it("reaches every composition from the root, an asset, or a file the root does not mount", () => {
+    expect(compositionsAffectedBy(dir(), "index.html")).toBeNull();
+    expect(compositionsAffectedBy(dir(), "assets/logo.svg")).toBeNull();
+    expect(compositionsAffectedBy(dir(), "compositions/unmounted.html")).toBeNull();
+  });
+
+  it("reads watcher paths with either separator", () => {
+    expect(compositionsAffectedBy(dir(), "compositions\\b.html")).toEqual([
+      "index.html",
+      "compositions/b.html",
+    ]);
+  });
+});

packages/studio-server/src/helpers/compositionInputs.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from "node:fs";
+import { createProjectSignature } from "./projectSignature.js";
+import { resolveWithinProject } from "./safePath.js";
+
+const ROOT_COMPOSITION = "index.html";
+// A regex, not a parser: a stray match (say, inside a script string) only widens what a
+// change invalidates, never narrows it.
+const COMPOSITION_SRC = /\bdata-composition-src\s*=\s*(["'])(.*?)\1/g;
+
+type SourceReader = (compPath: string) => string | null;
+
+function projectReader(projectDir: string): SourceReader {
+  const sources = new Map<string, string | null>();
+  return (compPath) => {
+    if (!sources.has(compPath)) {
+      const file = resolveWithinProject(projectDir, compPath);
+      let source: string | null = null;
+      try {
+        source = file ? readFileSync(file, "utf-8") : null;
+      } catch {
+        // Missing or unreadable: it mounts nothing, and still counts as mounted by its host.
+      }
+      sources.set(compPath, source);
+    }
+    return sources.get(compPath) ?? null;
+  };
+}
+
+function normalizeSource(src: string): string | null {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith("//")) return null;
+  const path = src.split(/[?#]/)[0]?.replace(/^\.?\//, "") ?? "";
+  return path || null;
+}
+
+/** `compPath` plus every composition it mounts, transitively, resolved from the project root as the bundler does. */
+function closureOf(read: SourceReader, compPath: string): Set<string> {
+  const closure = new Set<string>();
+  const visit = (path: string) => {
+    if (closure.has(path)) return;
+    closure.add(path);
+    for (const match of (read(path) ?? "").matchAll(COMPOSITION_SRC)) {
+      const mounted = normalizeSource(match[2] ?? "");
+      if (mounted) visit(mounted);
+    }
+  };
+  visit(compPath);
+  return closure;
+}
+
+// ponytail: this and projectSignature's per-exclusion cache keep one small entry per (project,
+// composition) ever thumbnailed, never evicted; LRU them if a server ever holds thousands.
+const inputSignatures = new Map<string, { projectSignature: string; inputSignature: string }>();
+
+// What a thumbnail of `compPath` renders from: the project minus the compositions the root
+// mounts that `compPath` does not. The root always counts (previews use its head).
+export function compositionInputSignature(
+  projectDir: string,
+  compPath: string,
+  projectSignature: string,
+): string {
+  const key = `${projectDir}\0${compPath}`;
+  const known = inputSignatures.get(key);
+  if (known?.projectSignature === projectSignature) return known.inputSignature;
+  const read = projectReader(projectDir);
+  const inputs = closureOf(read, normalizeSource(compPath) ?? compPath).add(ROOT_COMPOSITION);
+  const siblings = [...closureOf(read, ROOT_COMPOSITION)].filter((path) => !inputs.has(path));
+  const inputSignature = createProjectSignature(projectDir, new Set(siblings));
+  inputSignatures.set(key, { projectSignature, inputSignature });
+  return inputSignature;
+}
+
+/**
+ * Compositions whose rendered frames a write at `changedPath` can change, or `null` for all
+ * of them: the root, assets and any file the root does not mount reach every composition.
+ */
+export function compositionsAffectedBy(projectDir: string, changedPath: string): string[] | null {
+  const changed = changedPath.replace(/\\/g, "/");
+  const read = projectReader(projectDir);
+  const mounted = closureOf(read, ROOT_COMPOSITION);
+  if (changed === ROOT_COMPOSITION || !mounted.has(changed)) return null;
+  return [...mounted].filter((path) => closureOf(read, path).has(changed));
+}

packages/studio-server/src/helpers/projectSignature.ts

@@ -197,16 +197,28 @@ export async function resolveProjectAndSignature(
 
 /**
  * Creates a stable preview cache-busting signature for project source plus Studio manifests.
+ * `excluding` (project-relative paths) leaves those files out.
  */
-export function createProjectSignature(projectDir: string): string {
+export function createProjectSignature(
+  projectDir: string,
+  excluding: ReadonlySet<string> = new Set(),
+): string {
   const normalizedProjectDir = resolve(projectDir);
-  const files: ProjectSignatureFile[] = [];
-  collectProjectSignatureFiles(normalizedProjectDir, normalizedProjectDir, files);
-  collectProjectSignatureManifestFiles(normalizedProjectDir, files);
+  const collected: ProjectSignatureFile[] = [];
+  collectProjectSignatureFiles(normalizedProjectDir, normalizedProjectDir, collected);
+  collectProjectSignatureManifestFiles(normalizedProjectDir, collected);
+  const files = collected.filter(
+    (entry) => !excluding.has(relative(normalizedProjectDir, entry.file).split(sep).join("/")),
+  );
   files.sort((a, b) => a.file.localeCompare(b.file));
 
   const fingerprint = createProjectFingerprint(normalizedProjectDir, files);
-  const cached = projectSignatureCache.get(normalizedProjectDir);
+  const cacheKey = excluding.size
+    ? `${normalizedProjectDir}\0${createHash("sha256")
+        .update([...excluding].sort().join("\0"))
+        .digest("hex")}`
+    : normalizedProjectDir;
+  const cached = projectSignatureCache.get(cacheKey);
   if (cached?.fingerprint === fingerprint) return cached.signature;
 
   const hash = createHash("sha256");
@@ -228,6 +240,6 @@ export function createProjectSignature(projectDir: string): string {
     hash.update("\0");
   }
   const signature = hash.digest("hex").slice(0, 24);
-  projectSignatureCache.set(normalizedProjectDir, { fingerprint, signature });
+  projectSignatureCache.set(cacheKey, { fingerprint, signature });
   return signature;
 }

packages/studio-server/src/index.ts

@@ -1,5 +1,6 @@
 export { createStudioApi } from "./createStudioApi.js";
 export { createProjectSignature, affectsProjectSignature } from "./helpers/projectSignature.js";
+export { compositionsAffectedBy } from "./helpers/compositionInputs.js";
 export type {
   StudioApiAdapter,
   ResolvedProject,

packages/studio-server/src/routes/thumbnail.test.ts

@@ -4,6 +4,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   readdirSync,
   rmSync,
   truncateSync,
@@ -317,6 +318,54 @@ describe("registerThumbnailRoutes", () => {
     expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
   });
 
+  function writeTwoScenes(dir: string): { sceneA: string; sceneB: string } {
+    writeFileSync(
+      join(dir, "index.html"),
+      `<head><style>body { margin: 0 }</style></head><div data-width="640" data-height="360">` +
+        `<div data-composition-src="compositions/a.html"></div>` +
+        `<div data-composition-src="compositions/b.html"></div></div>`,
+    );
+    mkdirSync(join(dir, "compositions"), { recursive: true });
+    const sceneA = join(dir, "compositions", "a.html");
+    const sceneB = join(dir, "compositions", "b.html");
+    writeFileSync(sceneA, `<template><div data-composition-id="a">A</div></template>`);
+    writeFileSync(sceneB, `<template><div data-composition-id="b">B</div></template>`);
+    return { sceneA, sceneB };
+  }
+
+  it("keeps a scene's cached thumbnail when a sibling scene changes", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+    const { sceneA } = writeTwoScenes(project.dir);
+    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=2&v=test";
+
+    await app.request(url);
+    writeFileSync(sceneA, `<template><div data-composition-id="a">A, edited</div></template>`);
+    await app.request(url);
+
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
+  });
+
+  it("regenerates a scene thumbnail when the root it is built on changes", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+    writeTwoScenes(project.dir);
+    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=2&v=test";
+
+    await app.request(url);
+    const root = join(project.dir, "index.html");
+    writeFileSync(root, readFileSync(root, "utf-8").replace("margin: 0", "margin: 4px"));
+    await app.request(url);
+
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
+  });
+
   it("regenerates a thumbnail when imported CSS changes", async () => {
     const adapter = createAdapter();
     const project = await adapter.resolveProject("demo");
@@ -365,26 +414,51 @@ describe("registerThumbnailRoutes", () => {
     expect(getProjectSignature).toHaveBeenNthCalledWith(1, project.dir);
   });
 
-  it("does not cache generated pixels under a signature that changed in flight", async () => {
+  it("does not cache generated pixels when the composition's inputs changed in flight", async () => {
     const adapter = createAdapter();
     const project = await adapter.resolveProject("demo");
     if (!project) throw new Error("missing project");
-    const signatures = ["old", "new", "old", "old"];
-    adapter.getProjectSignature = vi.fn(() => signatures.shift() ?? "old");
+    const { sceneB } = writeTwoScenes(project.dir);
     adapter.generateThumbnail = vi
       .fn()
-      .mockResolvedValueOnce(Buffer.from("rendered-after-change"))
-      .mockResolvedValueOnce(Buffer.from("rendered-old"));
+      .mockImplementationOnce(async () => {
+        writeFileSync(sceneB, `<template><div data-composition-id="b">B, edited</div></template>`);
+        return Buffer.from("rendered-after-change");
+      })
+      .mockResolvedValueOnce(Buffer.from("rendered-current"));
     const app = new Hono();
     registerThumbnailRoutes(app, adapter);
-    const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
+    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=3";
 
     expect(await (await app.request(url)).text()).toBe("rendered-after-change");
     expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
-    expect(await (await app.request(url)).text()).toBe("rendered-old");
+    expect(await (await app.request(url)).text()).toBe("rendered-current");
     expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
   });
 
+  it("does not cache pixels changed in flight behind a stale adapter signature", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const { sceneB } = writeTwoScenes(project.dir);
+    const stale = createProjectSignature(project.dir);
+    adapter.getProjectSignature = () => stale;
+    adapter.generateThumbnail = vi
+      .fn()
+      .mockImplementationOnce(async () => {
+        writeFileSync(sceneB, `<template><div data-composition-id="b">B, edited</div></template>`);
+        return Buffer.from("rendered-after-change");
+      })
+      .mockResolvedValueOnce(Buffer.from("rendered-again"));
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=3";
+
+    expect(await (await app.request(url)).text()).toBe("rendered-after-change");
+    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
+    expect(await (await app.request(url)).text()).toBe("rendered-again");
+  });
+
   it("keeps changed studio motion separated in the disk cache", async () => {
     const adapter = createAdapter();
     const project = await adapter.resolveProject("demo");

packages/studio-server/src/routes/thumbnail.ts

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import type { StudioApiAdapter } from "../types.js";
 import { STUDIO_MANUAL_EDITS_PATH } from "../helpers/manualEditsRenderScript.js";
+import { compositionInputSignature } from "../helpers/compositionInputs.js";
 import { createProjectSignature, resolveProjectAndSignature } from "../helpers/projectSignature.js";
 import { STUDIO_MOTION_PATH } from "../helpers/studioMotionRenderScript.js";
 import { thumbnailGenerationCoordinator } from "./thumbnailGenerationCoordinator.js";
@@ -86,6 +87,8 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
       c.req.path.replace(`/projects/${project.id}/thumbnail/`, "").split("?")[0] ?? "",
     );
     if (compPath && !compPath.includes(".")) compPath += ".html";
+    // Keyed on what this composition renders from, so editing one scene leaves the others cached.
+    const inputSignature = compositionInputSignature(project.dir, compPath, projectSignature);
 
     const url = new URL(c.req.url, `http://${c.req.header("host") || "localhost"}`);
     const rawSeekTime = url.searchParams.get("t");
@@ -159,14 +162,14 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
     const urlVersionKey = urlVersion
       ? `_${urlVersion.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 32)}`
       : "";
-    const projectSignatureKey = `_${createHash("sha1").update(projectSignature).digest("hex").slice(0, 16)}`;
+    const inputSignatureKey = `_${createHash("sha1").update(inputSignature).digest("hex").slice(0, 16)}`;
     const outputScale =
       outputMode === "source"
         ? 1
         : Math.min(1, THUMBNAIL_MAX_OUTPUT_WIDTH / compW, THUMBNAIL_MAX_OUTPUT_HEIGHT / compH);
     const outputWidth = Math.max(1, Math.round(compW * outputScale));
     const outputHeight = Math.max(1, Math.round(compH * outputScale));
-    const cacheKey = `${THUMBNAIL_CACHE_VERSION}${urlVersionKey}${projectSignatureKey}${manualEditsKey}${motionKey}${sourceKey}_${format}_${outputMode}_${compPath.replace(/\//g, "_")}_${compW}x${compH}_${outputWidth}x${outputHeight}_${sourceMtime}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
+    const cacheKey = `${THUMBNAIL_CACHE_VERSION}${urlVersionKey}${inputSignatureKey}${manualEditsKey}${motionKey}${sourceKey}_${format}_${outputMode}_${compPath.replace(/\//g, "_")}_${compW}x${compH}_${outputWidth}x${outputHeight}_${sourceMtime}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
     const cachePath = join(cacheDir, cacheKey);
     if (!prunedCacheDirs.has(cacheDir)) {
       prunedCacheDirs.add(cacheDir);
@@ -202,12 +205,13 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
           });
           if (!generated) return null;
           const afterGeneration = await resolveProjectAndSignature(adapter, project.id);
-          const freshSignature = createProjectSignature(project.dir);
+          const inputsUnchanged = (signature: string) =>
+            compositionInputSignature(project.dir, compPath, signature) === inputSignature;
+          // Both the adapter's signature and a fresh one: the adapter's can lag the watcher.
           if (
-            !afterGeneration ||
-            afterGeneration.project.dir !== project.dir ||
-            afterGeneration.signature !== projectSignature ||
-            freshSignature !== projectSignature
+            afterGeneration?.project.dir !== project.dir ||
+            !inputsUnchanged(afterGeneration.signature) ||
+            !inputsUnchanged(createProjectSignature(project.dir))
           ) {
             // The browser may have rendered content written after this request
             // captured its cache identity. Return the pixels to this caller,