Skip to content

Commit 5842dd8

Browse files
fix(studio): invalidate the preview signature off the watcher that sees project writes (#3364)
* fix(studio): invalidate the preview signature off the watcher that sees project writes The preview ETag is a hash of the project's files, memoised per project directory. That cache was cleared from Vite's own watcher, which `server.watch.ignored` deliberately excludes `data/projects/**` from, so nothing ever cleared it: the ETag stayed frozen for the life of the dev server, the preview answered every revalidation with 304, and the browser went on serving the composition as it was when it first loaded. The visible cost is thumbnails. Their disk cache key already content-hashes the composition, so an edit correctly asks for a fresh capture, but the capture is taken against the stale page, and a clip's filmstrip keeps showing frames of a layout that no longer exists until the dev server is restarted. Studio already runs its own chokidar watcher over exactly these directories, because Vite's would answer a composition edit with a full page reload. That watcher now owns the invalidation, and the cache asks it to follow any project directory it has not seen. All five event types count: an added or deleted asset changes the signature as surely as an edited one. The cache moves behind `createProjectSignatureCache` so the invalidation rule is a unit under test rather than a subscription buried in the adapter. * fix(studio): filter signature invalidation, and stop the CLI server missing motion saves Review follow-up on the unfiltered invalidation. The watcher fired on everything under a project dir, but the signature walk skips 14 directories and `.thumbnails` is one of them. That directory is where the thumbnail route keeps its disk cache, and every capture also reads the preview, so populating a timeline row discarded the memo on roughly every request of the one workload it exists for. The filter is a single exported predicate beside the exclusion set it reads, and it is applied inside `invalidate` rather than at the watcher, so no caller can subscribe and forget it. It is deliberately not `WATCHER_EXCLUDED_DIRS`: that set is character-identical but drops all of `.hyperframes/`, and the signature reads two manifest files back out of there. Which is the same bug, still live, in the CLI server: its watcher filters through `shouldWatchProjectFile`, so `.hyperframes/studio-motion.json` never reached the listener that clears the cached signature. Studio writes that file at runtime, so saving motion state left the preview ETag stale until restart. The watcher now admits signature-relevant paths and the reload listener re-applies its own filter, so what triggers a browser reload is unchanged. Also from review: drop the `createViteAdapter` signature-cache default, which produced exactly the memo-nothing-clears bug this PR fixes, and correct the docstring — the content hash is already gated behind a stat fingerprint, so what the memo saves is the walk.
1 parent 09a5ef7 commit 5842dd8

8 files changed

Lines changed: 328 additions & 53 deletions

File tree

‎packages/cli/src/server/fileWatcher.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
import { watch, type FSWatcher } from "node:fs";
2+
import { join } from "node:path";
3+
import { affectsProjectSignature } from "@hyperframes/studio-server";
24

35
export type FileChangeListener = (relativePath: string) => void;
46

@@ -42,7 +44,17 @@ export function createProjectWatcher(projectDir: string): ProjectWatcher {
4244
watcher = watch(projectDir, { recursive: true }, (_event, filename) => {
4345
if (!filename) return;
4446
const relativePath = filename.toString();
45-
if (!shouldWatchProjectFile(relativePath)) return;
47+
// The reload filter excludes all of `.hyperframes/`, but two files in
48+
// there feed the preview signature and Studio writes one of them at
49+
// runtime — dropping those at ingest left the CLI server's ETag stale
50+
// until restart. Admit them here and let the reload listener re-apply
51+
// its own filter, so what triggers a browser reload is unchanged.
52+
if (
53+
!shouldWatchProjectFile(relativePath) &&
54+
!affectsProjectSignature(projectDir, join(projectDir, relativePath))
55+
) {
56+
return;
57+
}
4658

4759
pendingPaths.add(relativePath);
4860
if (debounceTimer) clearTimeout(debounceTimer);

‎packages/cli/src/server/studioServer.ts‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,11 @@ import { Hono, type Context } from "hono";
99
import { streamSSE } from "hono/streaming";
1010
import { existsSync, readFileSync, writeFileSync, statSync, unlinkSync } from "node:fs";
1111
import { resolve, join, basename } from "node:path";
12-
import { createProjectWatcher, type ProjectWatcher } from "./fileWatcher.js";
12+
import {
13+
createProjectWatcher,
14+
shouldWatchProjectFile,
15+
type ProjectWatcher,
16+
} from "./fileWatcher.js";
1317
import {
1418
hashSignatureParts,
1519
loadRuntimeSource,
@@ -32,6 +36,7 @@ import {
3236
consumeFileWriteReceipt,
3337
fileContentVersion,
3438
getMimeType,
39+
affectsProjectSignature,
3540
type PreviewApiAdapter,
3641
thumbnailDeviceScaleFactor,
3742
type ResolvedProject,
@@ -359,8 +364,10 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
359364

360365
const project: ResolvedProject = { id: projectId, dir: projectDir, title: projectId };
361366
let cachedProjectSignature: string | null = null;
362-
watcher.addListener(() => {
363-
cachedProjectSignature = null;
367+
watcher.addListener((changedPath) => {
368+
if (affectsProjectSignature(projectDir, join(projectDir, changedPath))) {
369+
cachedProjectSignature = null;
370+
}
364371
});
365372

366373
const adapter: PreviewApiAdapter = {
@@ -770,7 +777,11 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
770777
.writeSSE({ event: "file-change", data: JSON.stringify(receipt ?? { path }) })
771778
.catch(() => {});
772779
};
773-
watcher.addListener(listener);
780+
// Re-applied here because the watcher now also emits the signature
781+
// manifest files, which must not trigger a browser reload.
782+
watcher.addListener((changedPath) => {
783+
if (shouldWatchProjectFile(changedPath)) listener(changedPath);
784+
});
774785
while (true) {
775786
await stream.sleep(30000);
776787
}
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import { describe, expect, it } from "vitest";
2+
import { resolve } from "node:path";
3+
import { affectsProjectSignature } from "./projectSignature.js";
4+
5+
const PROJECT = resolve("/projects/demo");
6+
const affects = (relativePath: string) =>
7+
affectsProjectSignature(PROJECT, resolve(PROJECT, relativePath));
8+
9+
describe("affectsProjectSignature", () => {
10+
it("accepts a file the signature walk collects", () => {
11+
expect(affects("index.html")).toBe(true);
12+
expect(affects("assets/logo.png")).toBe(true);
13+
});
14+
15+
it("rejects the caches the walk skips", () => {
16+
// .thumbnails is the one that matters: the thumbnail route writes a capture
17+
// there and reads the preview on the next one, so invalidating on it throws
18+
// the memo away on roughly every request of the workload it exists for.
19+
expect(affects(".thumbnails/frame-0.jpg")).toBe(false);
20+
expect(affects("node_modules/pkg/index.js")).toBe(false);
21+
expect(affects("renders/out.mp4")).toBe(false);
22+
});
23+
24+
it("rejects a directory event on an excluded dir itself", () => {
25+
expect(affects(".thumbnails")).toBe(false);
26+
});
27+
28+
it("accepts the two manifest files the signature reads back out of .hyperframes", () => {
29+
// The reload watcher's exclusion set is character-identical to the walk's but
30+
// drops all of .hyperframes/. Filtering with it would stop a motion-state save
31+
// from ever invalidating — the same stale-ETag bug in a new place.
32+
expect(affects(".hyperframes/studio-motion.json")).toBe(true);
33+
expect(affects(".hyperframes/studio-manual-edits.json")).toBe(true);
34+
});
35+
36+
it("rejects everything else inside .hyperframes", () => {
37+
expect(affects(".hyperframes/cache/blob.bin")).toBe(false);
38+
});
39+
40+
it("rejects a path outside the project", () => {
41+
expect(affectsProjectSignature(PROJECT, resolve("/projects/other/index.html"))).toBe(false);
42+
expect(affectsProjectSignature(PROJECT, PROJECT)).toBe(false);
43+
});
44+
});

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

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { createHash } from "node:crypto";
22
import { lstatSync, readFileSync, readdirSync } from "node:fs";
3-
import { extname, isAbsolute, relative, resolve } from "node:path";
3+
import { extname, isAbsolute, relative, resolve, sep } from "node:path";
44
import type { ResolvedProject, StudioApiAdapter } from "../types.js";
55

66
const SIGNATURE_TEXT_EXTENSIONS = new Set([
@@ -37,6 +37,36 @@ const STUDIO_SIGNATURE_MANIFEST_PATHS = [
3737
".hyperframes/studio-motion.json",
3838
] as const;
3939

40+
/**
41+
* Whether a write at `changedPath` can change `createProjectSignature(projectDir)`.
42+
*
43+
* Owned here because it is the exact complement of what the walk below collects,
44+
* and a second copy of that reasoning drifts the moment either set changes. A
45+
* watcher that invalidates on everything is not merely wasteful: `.thumbnails/`
46+
* is written by the thumbnail route on every capture, and each capture reads the
47+
* preview, so an unfiltered watcher discards the memo on roughly every request of
48+
* the one workload the memo exists for.
49+
*
50+
* Note this is not `WATCHER_EXCLUDED_DIRS`, which is character-identical but
51+
* excludes all of `.hyperframes/` — the signature deliberately reads two manifest
52+
* files from inside it, so filtering with that set would stop motion-state saves
53+
* from ever invalidating.
54+
*
55+
* Every segment is tested, not just the parents, so a directory event on an
56+
* excluded dir itself (`unlinkDir .thumbnails`) is filtered too. The cost is that
57+
* a *file* literally named `dist` at the project root reads as excluded; the walk
58+
* would collect it, so it is a false negative, and no real project has one.
59+
*/
60+
export function affectsProjectSignature(projectDir: string, changedPath: string): boolean {
61+
const relativePath = relative(resolve(projectDir), resolve(changedPath));
62+
if (relativePath === "" || relativePath.startsWith("..") || isAbsolute(relativePath)) {
63+
return false;
64+
}
65+
const segments = relativePath.split(sep);
66+
if (STUDIO_SIGNATURE_MANIFEST_PATHS.includes(segments.join("/") as never)) return true;
67+
return !segments.some((segment) => SIGNATURE_EXCLUDED_DIRS.has(segment));
68+
}
69+
4070
interface ProjectSignatureFile {
4171
file: string;
4272
mtimeMs: number;

‎packages/studio-server/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
export { createStudioApi } from "./createStudioApi.js";
2-
export { createProjectSignature } from "./helpers/projectSignature.js";
2+
export { createProjectSignature, affectsProjectSignature } from "./helpers/projectSignature.js";
33
export type {
44
StudioApiAdapter,
55
ResolvedProject,
Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
import { describe, expect, it } from "vitest";
2+
import { resolve } from "node:path";
3+
import { createProjectSignatureCache } from "./vite.adapter";
4+
5+
const PROJECT = resolve("/projects/demo");
6+
7+
/** A compute that changes every call, so a stale read is visible as a repeat. */
8+
function countingCompute() {
9+
let calls = 0;
10+
return {
11+
compute: () => `sig-${++calls}`,
12+
get calls() {
13+
return calls;
14+
},
15+
};
16+
}
17+
18+
describe("createProjectSignatureCache", () => {
19+
it("memoises a project's signature", () => {
20+
const source = countingCompute();
21+
const cache = createProjectSignatureCache({ compute: source.compute });
22+
23+
expect(cache.get(PROJECT)).toBe("sig-1");
24+
expect(cache.get(PROJECT)).toBe("sig-1");
25+
expect(source.calls).toBe(1);
26+
});
27+
28+
it("recomputes after a file inside the project changes", () => {
29+
const source = countingCompute();
30+
const cache = createProjectSignatureCache({ compute: source.compute });
31+
32+
expect(cache.get(PROJECT)).toBe("sig-1");
33+
cache.invalidate(resolve(PROJECT, "index.html"));
34+
35+
// The preview ETag is this string. Serving "sig-1" again answers the
36+
// browser's revalidation with a 304 and the pre-edit composition is what
37+
// renders — which is how a thumbnail taken after an edit showed the old frame.
38+
expect(cache.get(PROJECT)).toBe("sig-2");
39+
});
40+
41+
it("recomputes for an asset added or removed, not only one edited", () => {
42+
const source = countingCompute();
43+
const cache = createProjectSignatureCache({ compute: source.compute });
44+
45+
cache.get(PROJECT);
46+
cache.invalidate(resolve(PROJECT, "assets/new-clip.mp4"));
47+
expect(cache.get(PROJECT)).toBe("sig-2");
48+
49+
cache.invalidate(resolve(PROJECT, "compositions/scene.html"));
50+
expect(cache.get(PROJECT)).toBe("sig-3");
51+
});
52+
53+
it("leaves other projects alone", () => {
54+
const signatures = new Map([
55+
[PROJECT, "demo"],
56+
[resolve("/projects/other"), "other"],
57+
]);
58+
let bumped = 0;
59+
const cache = createProjectSignatureCache({
60+
compute: (dir) => `${signatures.get(dir)}-${bumped}`,
61+
});
62+
63+
expect(cache.get(PROJECT)).toBe("demo-0");
64+
expect(cache.get(resolve("/projects/other"))).toBe("other-0");
65+
66+
bumped = 1;
67+
cache.invalidate(resolve(PROJECT, "index.html"));
68+
69+
expect(cache.get(PROJECT)).toBe("demo-1");
70+
expect(cache.get(resolve("/projects/other"))).toBe("other-0");
71+
});
72+
73+
it("asks for a project directory to be watched once, on first use", () => {
74+
const watched: string[] = [];
75+
const cache = createProjectSignatureCache({
76+
compute: () => "sig",
77+
watch: (dir) => watched.push(dir),
78+
});
79+
80+
cache.get(PROJECT);
81+
cache.get(PROJECT);
82+
cache.invalidate(resolve(PROJECT, "index.html"));
83+
cache.get(PROJECT);
84+
85+
// Re-registering on every recompute would stack duplicate chokidar entries.
86+
expect(watched).toEqual([PROJECT]);
87+
});
88+
89+
it("normalises the directory it is asked about", () => {
90+
const source = countingCompute();
91+
const cache = createProjectSignatureCache({ compute: source.compute });
92+
93+
expect(cache.get(PROJECT)).toBe("sig-1");
94+
expect(cache.get(`${PROJECT}/`)).toBe("sig-1");
95+
expect(cache.get(resolve(PROJECT, "nested/.."))).toBe("sig-1");
96+
expect(source.calls).toBe(1);
97+
});
98+
99+
it("does not invalidate on a write the signature cannot see", () => {
100+
const source = countingCompute();
101+
const cache = createProjectSignatureCache({ compute: source.compute });
102+
103+
cache.get(PROJECT);
104+
// Each thumbnail capture writes here and then reads the preview, so an
105+
// unfiltered watcher discards the memo on roughly every request of the one
106+
// workload the memo exists for.
107+
cache.invalidate(resolve(PROJECT, ".thumbnails/frame-0.jpg"));
108+
109+
expect(cache.get(PROJECT)).toBe("sig-1");
110+
expect(source.calls).toBe(1);
111+
});
112+
113+
it("invalidates on a motion-state save, which lives under an otherwise-skipped dir", () => {
114+
const source = countingCompute();
115+
const cache = createProjectSignatureCache({ compute: source.compute });
116+
117+
cache.get(PROJECT);
118+
cache.invalidate(resolve(PROJECT, ".hyperframes/studio-motion.json"));
119+
120+
expect(cache.get(PROJECT)).toBe("sig-2");
121+
});
122+
});

0 commit comments

Comments
 (0)