fix(studio-server): key the waveform cache on the file, not just its path

Two takes written to the same path returned the first one's waveform, so a
re-recorded track drew the shape of the audio it replaced. The key now carries
size and mtime, which is enough to notice the bytes changed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: vanceingalls

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

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { buildWaveformCacheKey } from "./waveform.js";
+
+describe("buildWaveformCacheKey", () => {
+  it("is stable for the same file", () => {
+    const a = buildWaveformCacheKey("assets/music-bed.m4a", { size: 4187869, mtimeMs: 1000 });
+    const b = buildWaveformCacheKey("assets/music-bed.m4a", { size: 4187869, mtimeMs: 1000 });
+    expect(a).toBe(b);
+  });
+
+  it("changes when the file behind the path is replaced", () => {
+    // The case this exists for: an asset rebuilt in place — same name, new
+    // content. Keyed on the path alone the cache served the old peaks forever,
+    // so a bed whose ducking had just been removed still drew as ducked.
+    const before = buildWaveformCacheKey("assets/music-bed.m4a", { size: 4187869, mtimeMs: 1000 });
+    const after = buildWaveformCacheKey("assets/music-bed.m4a", { size: 3900000, mtimeMs: 2000 });
+    expect(after).not.toBe(before);
+  });
+
+  it("separates two files of the same size edited at different times, and vice versa", () => {
+    const base = { size: 100, mtimeMs: 1000 };
+    expect(buildWaveformCacheKey("a.m4a", base)).not.toBe(
+      buildWaveformCacheKey("a.m4a", { ...base, mtimeMs: 1001 }),
+    );
+    expect(buildWaveformCacheKey("a.m4a", base)).not.toBe(
+      buildWaveformCacheKey("a.m4a", { ...base, size: 101 }),
+    );
+  });
+
+  it("keeps distinct assets apart and stays a plain filename", () => {
+    const fp = { size: 10, mtimeMs: 5 };
+    expect(buildWaveformCacheKey("a/b.m4a", fp)).not.toBe(buildWaveformCacheKey("a/c.m4a", fp));
+    expect(buildWaveformCacheKey("a/b.m4a", fp)).not.toMatch(/[/\\]/);
+    expect(buildWaveformCacheKey("a/b.m4a", fp)).toMatch(/\.json$/);
+  });
+});

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

@@ -7,8 +7,28 @@ const SAMPLE_RATE = 4000;
 const PEAK_COUNT = 4000;
 const WAVEFORM_CACHE_VERSION = "v2";
 
-export function buildWaveformCacheKey(assetPath: string): string {
-  return `${WAVEFORM_CACHE_VERSION}_${assetPath.replace(/[/\\]/g, "_")}.json`;
+/**
+ * Cache filename for one asset's peaks, keyed on its content as well as its name.
+ *
+ * The path alone is not an identity. An asset rebuilt in place — a bed
+ * re-encoded without its ducking, a plate swapped for the right one — keeps its
+ * name and gets new samples, and a path-keyed entry then served the old peaks
+ * for the rest of the project's life: the timeline drew a duck that was no
+ * longer in the file, which reads as the render having done it. Size and mtime
+ * are what a rebuild always changes, and both are already on the stat the route
+ * takes to check the file exists.
+ *
+ * Without a fingerprint it falls back to the old path-only key, so a caller that
+ * cannot stat still gets caching rather than an error.
+ */
+export function buildWaveformCacheKey(
+  assetPath: string,
+  fingerprint?: { size: number; mtimeMs: number },
+): string {
+  const name = assetPath.replace(/[/\\]/g, "_");
+  if (!fingerprint) return `${WAVEFORM_CACHE_VERSION}_${name}.json`;
+  const stamp = `${fingerprint.size}-${Math.round(fingerprint.mtimeMs)}`;
+  return `${WAVEFORM_CACHE_VERSION}_${name}_${stamp}.json`;
 }
 
 function computePeaks(floats: Float32Array, count: number): number[] {

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

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { Hono } from "hono";
 import type { StudioApiAdapter } from "../types.js";
@@ -13,10 +13,13 @@ export function registerWaveformRoutes(api: Hono, adapter: StudioApiAdapter): vo
       c.req.path.replace(`/projects/${project.id}/waveform/`, "").split("?")[0] ?? "",
     );
     const audioPath = join(project.dir, assetPath);
-    if (!existsSync(audioPath)) return c.json({ error: "file not found" }, 404);
+    const stats = statSync(audioPath, { throwIfNoEntry: false });
+    if (!stats) return c.json({ error: "file not found" }, 404);
 
     const cacheDir = join(project.dir, ".waveform-cache");
-    const cachePath = join(cacheDir, buildWaveformCacheKey(assetPath));
+    // Keyed on the file's size and mtime as well as its name, so re-encoding an
+    // asset in place invalidates its peaks instead of drawing the old ones.
+    const cachePath = join(cacheDir, buildWaveformCacheKey(assetPath, stats));
 
     if (existsSync(cachePath)) {
       try {