diff --git a/packages/cli/src/server/studioServer.stampOnOpen.test.ts b/packages/cli/src/server/studioServer.stampOnOpen.test.ts
new file mode 100644
index 0000000000..5a4ba8dd6e
--- /dev/null
+++ b/packages/cli/src/server/studioServer.stampOnOpen.test.ts
@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { tmpdir } from "node:os";
+import { createStudioServer, type StudioServer } from "./studioServer.js";
+
+const SCENES = Array.from({ length: 24 }, (_, i) => `s${String(i).padStart(2, "0")}`);
+
+const scene = (id: string) => `
+
+`;
+
+const root = (ids: string[]) => `
+
+${ids.map((id, i) => `
`).join("\n")}
+
`;
+
+let dir: string;
+let server: StudioServer | undefined;
+
+beforeEach(() => {
+ dir = fs.mkdtempSync(path.join(tmpdir(), "hf-stamp-on-open-"));
+ fs.mkdirSync(path.join(dir, "compositions"));
+ fs.writeFileSync(path.join(dir, "index.html"), root(SCENES));
+ for (const id of SCENES)
+ fs.writeFileSync(path.join(dir, "compositions", `${id}.html`), scene(id));
+});
+
+afterEach(() => {
+ server?.watcher.close();
+ fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe("opening a film of external scenes", () => {
+ it("writes nothing to the project mid-session, so Studio sees no outside edit to reload for", async () => {
+ server = createStudioServer({ projectDir: dir, projectName: "film" });
+ const changed: string[] = [];
+ server.watcher.addListener((changedPath) => changed.push(changedPath));
+
+ expect((await server.app.request("/api/projects/film/preview")).status).toBe(200);
+ for (const id of SCENES) {
+ const comp = await server.app.request(
+ `/api/projects/film/preview/comp/compositions/${id}.html`,
+ );
+ expect(comp.status).toBe(200);
+ }
+ await new Promise((resolve) => setTimeout(resolve, 1000));
+
+ expect(changed).toEqual([]);
+ const stamped = fs.readFileSync(path.join(dir, "compositions", "s23.html"), "utf-8");
+ expect(stamped).toContain("data-hf-id=");
+ });
+});
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index f69917b4b8..f6796d7c1d 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -50,6 +50,7 @@ import {
type ResolvedProject,
type RenderJobState,
type BackgroundRemovalRender,
+ stampProjectHfIds,
} from "@hyperframes/studio-server";
import { resolveAutoProxy } from "../utils/projectConfig.js";
import { getElementScreenshotClip } from "@hyperframes/studio-server/screenshot-clip";
@@ -400,6 +401,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
const browserGpuMode = options.browserGpuMode ?? resolveLocalBrowserGpuMode();
const studioDir = resolveDistDir();
const runtimePath = resolveRuntimePath();
+ stampProjectHfIds(projectDir);
const watcher = createProjectWatcher(projectDir);
// ── CLI adapter for the shared studio API ──────────────────────────────
diff --git a/packages/studio-server/src/helpers/hfIdPersist.ts b/packages/studio-server/src/helpers/hfIdPersist.ts
index 1785861126..ed9a6a1816 100644
--- a/packages/studio-server/src/helpers/hfIdPersist.ts
+++ b/packages/studio-server/src/helpers/hfIdPersist.ts
@@ -1,6 +1,26 @@
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { closeSync, constants, fstatSync, openSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
import { replaceFileAtomically } from "./atomicFile.js";
+import { isInHiddenOrVendorDir, walkDir } from "./safePath.js";
+
+export const isCompositionSource = (html: string): boolean => /data-composition-id\s*=/.test(html);
+
+/** Pins hf-ids into every composition in the project. A host runs it once before it serves or
+ * watches the project: an id write during a session reaches Studio as an outside edit and reloads it. */
+export function stampProjectHfIds(projectDir: string): void {
+ for (const file of walkDir(projectDir)) {
+ if (!file.endsWith(".html") || isInHiddenOrVendorDir(file)) continue;
+ const absPath = join(projectDir, file);
+ let html: string;
+ try {
+ html = readFileSync(absPath, "utf-8");
+ } catch {
+ continue; // unreadable now; the preview route stamps it when it is served
+ }
+ if (isCompositionSource(html)) stampFileHfIds(absPath);
+ }
+}
/**
* Ensure `html` has `data-hf-id` attributes minted, and write the result back
diff --git a/packages/studio-server/src/index.ts b/packages/studio-server/src/index.ts
index 344d48f8b3..8ad9b5c1e0 100644
--- a/packages/studio-server/src/index.ts
+++ b/packages/studio-server/src/index.ts
@@ -11,6 +11,7 @@ export type {
StudioSelectionTextField,
} from "./types.js";
export { isSafePath, walkDir } from "./helpers/safePath.js";
+export { stampProjectHfIds } from "./helpers/hfIdPersist.js";
export {
patchElementInHtml,
splitElementInHtml,
diff --git a/packages/studio-server/src/routes/projects.ts b/packages/studio-server/src/routes/projects.ts
index a0a3580cb4..cec4e41899 100644
--- a/packages/studio-server/src/routes/projects.ts
+++ b/packages/studio-server/src/routes/projects.ts
@@ -3,17 +3,16 @@ import { join } from "node:path";
import type { Hono } from "hono";
import type { StudioApiAdapter } from "../types.js";
import { isInHiddenOrVendorDir, walkDir } from "../helpers/safePath.js";
+import { isCompositionSource } from "../helpers/hfIdPersist.js";
import { resolveProjectSignature } from "../helpers/projectSignature.js";
-const COMPOSITION_ID_RE = /data-composition-id\s*=/;
-
async function filterCompositionFiles(projectDir: string, files: string[]): Promise {
const htmlFiles = files.filter((f) => f.endsWith(".html") && !isInHiddenOrVendorDir(f));
const checks = await Promise.all(
htmlFiles.map(async (f) => {
try {
const content = await readFile(join(projectDir, f), "utf-8");
- return COMPOSITION_ID_RE.test(content);
+ return isCompositionSource(content);
} catch {
return false;
}