Skip to content

Write HTML. Render video. Built for agents.

feat(studio): record video state, edit targets and artifact cleanup in project history (#5524)

Xuanru Li893b4f6757f4
diff --git a/packages/studio-server/src/helpers/projectSignature.ts b/packages/studio-server/src/helpers/projectSignature.ts
index 1337da9a24..da440d4027 100644
--- a/packages/studio-server/src/helpers/projectSignature.ts
+++ b/packages/studio-server/src/helpers/projectSignature.ts
@@ -1,5 +1,6 @@
+import { readRenderOutputsOrNone, isRenderOutput } from "./renderOutputs.js";
import { createHash } from "node:crypto";
-import { lstatSync, readFileSync, readdirSync } from "node:fs";
+import { lstatSync, readFileSync, readdirSync, type Stats } from "node:fs";
import { extname, isAbsolute, relative, resolve, sep } from "node:path";
import { isAtomicTempPath } from "@hyperframes/core/atomic-file";
import type { ResolvedProject, StudioApiAdapter } from "../types.js";
@@ -68,6 +69,7 @@ export function affectsProjectSignature(projectDir: string, changedPath: string)
) {
return false;
}
+ if (isRenderOutput(projectDir, changedPath, readRenderOutputsOrNone(projectDir))) return false;
const segments = relativePath.split(sep);
if (STUDIO_SIGNATURE_MANIFEST_PATHS.includes(segments.join("/") as never)) return true;
return !segments.some((segment) => SIGNATURE_EXCLUDED_DIRS.has(segment));
@@ -106,10 +108,27 @@ function isTextContentEligible(file: string, size: number): boolean {
const isSkippedEntry = (entry: string) =>
SIGNATURE_EXCLUDED_DIRS.has(entry) || isAtomicTempPath(entry);
+function signatureEntryStat(
+ projectDir: string,
+ entry: string,
+ file: string,
+ outputs: readonly string[],
+): Stats | null {
+ if (isSkippedEntry(entry) || !isPathWithin(projectDir, file)) return null;
+ if (isRenderOutput(projectDir, file, outputs)) return null;
+ try {
+ const stat = lstatSync(file);
+ return stat.isSymbolicLink() ? null : stat;
+ } catch {
+ return null;
+ }
+}
+
function collectProjectSignatureFiles(
projectDir: string,
dir: string,
files: ProjectSignatureFile[],
+ outputs = readRenderOutputsOrNone(projectDir),
): void {
let entries: string[];
try {
@@ -119,18 +138,11 @@ function collectProjectSignatureFiles(
}
for (const entry of entries) {
- if (isSkippedEntry(entry)) continue;
const file = resolve(dir, entry);
- if (!isPathWithin(projectDir, file)) continue;
- let stat: ReturnType<typeof lstatSync>;
- try {
- stat = lstatSync(file);
- } catch {
- continue;
- }
- if (stat.isSymbolicLink()) continue;
+ const stat = signatureEntryStat(projectDir, entry, file, outputs);
+ if (!stat) continue;
if (stat.isDirectory()) {
- collectProjectSignatureFiles(projectDir, file, files);
+ collectProjectSignatureFiles(projectDir, file, files, outputs);
} else if (stat.isFile()) {
files.push({
file,
diff --git a/packages/studio-server/src/helpers/renderOutputs.test.ts b/packages/studio-server/src/helpers/renderOutputs.test.ts
new file mode 100644
index 0000000000..add58d25d0
--- /dev/null
+++ b/packages/studio-server/src/helpers/renderOutputs.test.ts
@@ -0,0 +1,93 @@
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, it } from "vitest";
+import { registerRenderOutput, readRenderOutputs } from "./renderOutputs.js";
+import { listProjectFiles, affectsProjectSignature } from "./projectSignature.js";
+import { openProjectHistory } from "../history/projectHistory.js";
+import { beginArtifactCapture, recordRenderSuccess } from "../history/videoState.js";
+
+it("keeps root render outputs out of revisions while tracking source video edits", async () => {
+ const root = mkdtempSync(join(tmpdir(), "hf-render-history-"));
+ const project = join(root, "project");
+ mkdirSync(project);
+ writeFileSync(join(project, "index.html"), "initial");
+ writeFileSync(join(project, "input.mp4"), "source video");
+ const history = await openProjectHistory({
+ projectDir: project,
+ historyRoot: join(root, "history"),
+ });
+ const state = () =>
+ JSON.parse(readFileSync(join(project, ".hyperframes/video-state.json"), "utf8"));
+ try {
+ const window = await history.beginWindow({ kind: "agent", name: "test" }, "edit");
+ writeFileSync(join(project, "index.html"), "edited");
+ await history.checkpoint();
+ const revision = state().currentRevision;
+ const output = join(project, "benefits.mp4");
+ await registerRenderOutput(project, output);
+ const capture = await beginArtifactCapture(project);
+ expect(capture.revision).toBe(revision);
+ for (const bytes of ["first render", "second render"]) {
+ writeFileSync(output, bytes);
+ const render = await recordRenderSuccess(project, output, "completed", capture);
+ expect(render.revision).toBe(revision);
+ await history.checkpoint();
+ expect(state().currentRevision).toBe(revision);
+ expect(state().pendingChanges).toBe(false);
+ expect(state().files["benefits.mp4"]).toBeUndefined();
+ }
+ expect(affectsProjectSignature(project, output)).toBe(false);
+ expect(affectsProjectSignature(project, join(project, "input.mp4"))).toBe(true);
+ writeFileSync(join(project, "input.mp4"), "updated source video");
+ await window.close();
+ expect(state().currentRevision).not.toBe(revision);
+ expect(Object.keys(state().revisions[state().currentRevision].files)).toEqual(["input.mp4"]);
+ const nextCapture = await beginArtifactCapture(project);
+ writeFileSync(join(project, "index.html"), "changed during rendering");
+ writeFileSync(output, "third render");
+ expect(
+ (await recordRenderSuccess(project, output, "completed", nextCapture)).revision,
+ ).toBeNull();
+ } finally {
+ await history.close();
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+it("registers concurrent custom outputs and directory renders without excluding other media", async () => {
+ const root = mkdtempSync(join(tmpdir(), "hf-render-registry-"));
+ try {
+ await Promise.all([
+ registerRenderOutput(root, join(root, "a.webm")),
+ registerRenderOutput(root, join(root, "hls")),
+ ]);
+ expect(readRenderOutputs(root)).toEqual(["a.webm", "hls"]);
+ mkdirSync(join(root, "hls"));
+ writeFileSync(join(root, "hls", "chunk.ts"), "output");
+ writeFileSync(join(root, "a.webm"), "output");
+ writeFileSync(join(root, "b.webm"), "input");
+ expect(listProjectFiles(root).map((file) => file.path)).toEqual(["b.webm"]);
+ await registerRenderOutput(root, join(root, "..", "external.mp4"));
+ expect(readRenderOutputs(root)).toEqual(["a.webm", "hls"]);
+ await expect(registerRenderOutput(root, root)).rejects.toThrow("project directory");
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+
+it("lists project files when the render output registry is unreadable", () => {
+ const project = mkdtempSync(join(tmpdir(), "hf-render-registry-"));
+ try {
+ writeFileSync(join(project, "index.html"), "x");
+ writeFileSync(join(project, ".hyperframes"), "a file, not a folder");
+ expect(readRenderOutputs(project)).toEqual([]);
+ rmSync(join(project, ".hyperframes"));
+ mkdirSync(join(project, ".hyperframes"));
+ writeFileSync(join(project, ".hyperframes", "render-outputs.json"), "{not json");
+ expect(() => readRenderOutputs(project)).toThrow();
+ expect(listProjectFiles(project).length).toBeGreaterThan(0);
+ expect(affectsProjectSignature(project, join(project, "index.html"))).toBe(true);
+ } finally {
+ rmSync(project, { recursive: true, force: true });
+ }
+});
diff --git a/packages/studio-server/src/helpers/renderOutputs.ts b/packages/studio-server/src/helpers/renderOutputs.ts
new file mode 100644
index 0000000000..9f882c7917
--- /dev/null
+++ b/packages/studio-server/src/helpers/renderOutputs.ts
@@ -0,0 +1,67 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
+import { takeHistoryOwnership } from "../history/ownerLock.js";
+import { pinProjectRecord } from "./safePath.js";
+
+const manifest = ".hyperframes/render-outputs.json";
+
+export function readRenderOutputs(projectDir: string): string[] {
+ const path = pinProjectRecord(projectDir, manifest);
+ if (!path) return [];
+ let text: string;
+ try {
+ text = readFileSync(path, "utf8");
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code;
+ if (code === "ENOENT" || code === "ENOTDIR") return [];
+ throw error;
+ }
+ const value = JSON.parse(text);
+ if (
+ value.version !== 1 ||
+ !Array.isArray(value.paths) ||
+ !value.paths.every(
+ (p: unknown) =>
+ typeof p === "string" &&
+ p !== "" &&
+ !isAbsolute(p) &&
+ !p.split(/[\\/]/).some((part) => part === ".." || part === "."),
+ )
+ )
+ throw new Error("Invalid render output registry.");
+ return value.paths;
+}
+
+export function readRenderOutputsOrNone(projectDir: string): string[] {
+ try {
+ return readRenderOutputs(projectDir);
+ } catch {
+ return [];
+ }
+}
+
+export function isRenderOutput(
+ projectDir: string,
+ path: string,
+ outputs: readonly string[],
+): boolean {
+ const candidate = relative(resolve(projectDir), resolve(path)).split(sep).join("/");
+ return outputs.some((output) => candidate === output || candidate.startsWith(`${output}/`));
+}
+
+export async function registerRenderOutput(projectDir: string, output: string): Promise<void> {
+ const path = relative(resolve(projectDir), resolve(output)).split(sep).join("/");
+ if (path === "") throw new Error("Render output cannot replace the project directory.");
+ if (isAbsolute(path) || path === ".." || path.startsWith("../")) return;
+ const registry = pinProjectRecord(projectDir, manifest);
+ const lock = pinProjectRecord(projectDir, ".hyperframes/render-outputs-lock");
+ if (!registry || !lock) throw new Error("Render output registry must stay inside the project.");
+ const release = await takeHistoryOwnership(lock, 5000);
+ try {
+ const paths = [...new Set([...readRenderOutputs(projectDir), path])].sort();
+ replaceFileAtomically(registry, JSON.stringify({ version: 1, paths }) + "\n", 0o644);
+ } finally {
+ release();
+ }
+}
diff --git a/packages/studio-server/src/helpers/safePath.ts b/packages/studio-server/src/helpers/safePath.ts
index 500927d40b..99f12cdc42 100644
--- a/packages/studio-server/src/helpers/safePath.ts
+++ b/packages/studio-server/src/helpers/safePath.ts
@@ -59,7 +59,15 @@ export function isPrivateProjectFile(projectDir: string, filePath: string): bool
* file checked here even if a link on the way is retargeted before the write.
*/
export function pinWithinProject(base: string, relativePath: string): string | null {
- const checked = resolveWithinProject(base, relativePath);
+ return pinResolved(base, resolveWithinProject(base, relativePath));
+}
+
+/** `pinWithinProject` for the app's and the CLI's own records under `.hyperframes/`, which no route serves. */
+export function pinProjectRecord(base: string, relativePath: string): string | null {
+ return pinResolved(base, resolveInProject(base, relativePath));
+}
+
+function pinResolved(base: string, checked: string | null): string | null {
if (!checked) return null;
const inside = relative(realFilePath(base), realFilePath(checked));
const escapes = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
diff --git a/packages/studio-server/src/history/artifactCleanup.test.ts b/packages/studio-server/src/history/artifactCleanup.test.ts
new file mode 100644
index 0000000000..92c3450b0d
--- /dev/null
+++ b/packages/studio-server/src/history/artifactCleanup.test.ts
@@ -0,0 +1,176 @@
+import * as fs from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, expect, it } from "vitest";
+import { openProjectHistory } from "./projectHistory.js";
+import {
+ beginArtifactCapture,
+ recordArtifacts,
+ recordRenderSuccess,
+ type VideoState,
+} from "./videoState.js";
+
+const cleanup: (() => Promise<void>)[] = [];
+afterEach(async () => {
+ for (const fn of cleanup.splice(0)) await fn();
+});
+async function fixture() {
+ const root = fs.mkdtempSync(join(tmpdir(), "hf-artifact-cleanup-"));
+ const projectDir = join(root, "project");
+ fs.mkdirSync(projectDir);
+ fs.writeFileSync(join(projectDir, "index.html"), "initial");
+ const history = await openProjectHistory({ projectDir, historyRoot: join(root, "history") });
+ cleanup.push(async () => {
+ await history.close();
+ fs.rmSync(root, { recursive: true, force: true });
+ });
+ const state = (): VideoState =>
+ JSON.parse(fs.readFileSync(join(projectDir, ".hyperframes/video-state.json"), "utf8"));
+ const output = join(projectDir, ".hyperframes", "out.mp4");
+ fs.writeFileSync(output, "video");
+ async function edit(text: string) {
+ const window = await history.beginWindow({ kind: "person", name: "You" }, "Edit");
+ fs.writeFileSync(join(projectDir, "index.html"), text);
+ await window.close();
+ return state().currentRevision!;
+ }
+ async function artifacts(id: string, custom = false) {
+ const capture = await beginArtifactCapture(projectDir);
+ const image = join(
+ projectDir,
+ custom ? "custom.png" : `.hyperframes/artifacts/snapshots/${id}.png`,
+ );
+ const report = join(projectDir, `.hyperframes/artifacts/checks/${id}.json`);
+ for (const path of [image, report]) {
+ fs.mkdirSync(join(path, ".."), { recursive: true });
+ fs.writeFileSync(path, id);
+ }
+ await recordArtifacts(projectDir, capture, [
+ { kind: "snapshot", id, scope: "full", image, time: 1 },
+ { kind: "check", id, scope: "project", report, metadata: { ok: true } },
+ ]);
+ return { image, report };
+ }
+ const render = async () =>
+ recordRenderSuccess(
+ fs.realpathSync(projectDir),
+ output,
+ "completed",
+ await beginArtifactCapture(projectDir),
+ );
+ return { projectDir, state, edit, artifacts, render, output };
+}
+
+it("retains current and last two rendered revisions, tombstones old artifacts, and preserves tombstones on later writes", async () => {
+ const f = await fixture();
+ const r1 = await f.edit("one"),
+ a1 = await f.artifacts("one");
+ await f.render();
+ const r2 = await f.edit("two"),
+ a2 = await f.artifacts("two");
+ await f.render();
+ await f.render();
+ expect(fs.existsSync(a1.image)).toBe(true);
+ const r3 = await f.edit("three"),
+ a3 = await f.artifacts("three");
+ await f.render();
+ const s = f.state();
+ expect(s.renders?.retainedRevisions).toEqual([r3, r2]);
+ expect(fs.existsSync(a1.image)).toBe(false);
+ expect(fs.existsSync(a1.report)).toBe(false);
+ for (const a of [a2, a3]) {
+ expect(fs.existsSync(a.image)).toBe(true);
+ expect(fs.existsSync(a.report)).toBe(true);
+ }
+ expect(s.snapshots.revisions[r1][0]).toMatchObject({ status: "cleaned", revision: r1, time: 1 });
+ expect(s.snapshots.revisions[r1][0].image).toBeUndefined();
+ expect(s.checks.revisions[r1][0].metadata).toEqual({ ok: true });
+ expect(s.snapshots.latest?.revision).toBe(r3);
+ await f.artifacts("later");
+ expect(f.state().snapshots.revisions[r1][0].status).toBe("cleaned");
+ expect(fs.existsSync(f.output)).toBe(true);
+});
+
+it("does not clean on missing output, unknown revision, or changed render inputs", async () => {
+ const f = await fixture();
+ await f.edit("one");
+ const a = await f.artifacts("one");
+ await f.render();
+ await f.edit("two");
+ await f.render();
+ await f.edit("three");
+ const capture = await beginArtifactCapture(f.projectDir);
+ await expect(
+ recordRenderSuccess(f.projectDir, join(f.projectDir, "missing.mp4"), "completed", capture),
+ ).rejects.toThrow();
+ await recordRenderSuccess(f.projectDir, f.output);
+ expect(fs.existsSync(a.image)).toBe(true);
+ await f.edit("four");
+ await recordRenderSuccess(f.projectDir, f.output, "completed", capture);
+ expect(f.state().renders?.latest?.revision).toBeNull();
+ expect(fs.existsSync(a.image)).toBe(true);
+});
+
+it("preserves custom paths, unversioned results, overwritten files and symlink targets", async () => {
+ const f = await fixture();
+ const unversioned = await f.artifacts("unversioned");
+ await f.edit("one");
+ const custom = await f.artifacts("custom", true);
+ const changed = await f.artifacts("changed"),
+ linked = await f.artifacts("linked");
+ fs.writeFileSync(changed.image, "new writer");
+ fs.unlinkSync(linked.image);
+ fs.symlinkSync(custom.image, linked.image);
+ await f.render();
+ await f.edit("two");
+ await f.render();
+ await f.edit("three");
+ await f.render();
+ for (const p of [
+ unversioned.image,
+ unversioned.report,
+ custom.image,
+ changed.image,
+ linked.image,
+ ])
+ expect(fs.existsSync(p)).toBe(true);
+});
+
+it("keeps a newer current revision when an older render completes", async () => {
+ const f = await fixture();
+ await f.edit("one");
+ await f.render();
+ await f.edit("two");
+ const capture = await beginArtifactCapture(f.projectDir);
+ await f.edit("three");
+ const a = await f.artifacts("three");
+ await recordRenderSuccess(f.projectDir, f.output, "completed", capture);
+ expect(fs.existsSync(a.image)).toBe(true);
+ expect(f.state().renders?.latest?.revision).toBeNull();
+});
+
+it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
+ "persists deletion work before unlink and retries failures without exposing dead paths",
+ async () => {
+ const f = await fixture();
+ const r1 = await f.edit("one"),
+ a = await f.artifacts("one");
+ await f.render();
+ await f.edit("two");
+ await f.render();
+ await f.edit("three");
+ const directory = join(a.image, "..");
+ fs.chmodSync(directory, 0o555);
+ cleanup.unshift(async () => {
+ fs.chmodSync(directory, 0o755);
+ });
+ await f.render();
+ expect(f.state().pendingArtifactCleanup).toHaveLength(1);
+ expect(fs.existsSync(a.image)).toBe(true);
+ expect(f.state().snapshots.revisions[r1][0].image).toBeUndefined();
+ fs.chmodSync(directory, 0o755);
+ await f.render();
+ expect(fs.existsSync(a.image)).toBe(false);
+ expect(f.state().pendingArtifactCleanup).toEqual([]);
+ },
+);
diff --git a/packages/studio-server/src/history/artifactCleanup.ts b/packages/studio-server/src/history/artifactCleanup.ts
new file mode 100644
index 0000000000..3a3fca47df
--- /dev/null
+++ b/packages/studio-server/src/history/artifactCleanup.ts
@@ -0,0 +1,167 @@
+import { createHash } from "node:crypto";
+import {
+ closeSync,
+ constants,
+ fstatSync,
+ lstatSync,
+ openSync,
+ readFileSync,
+ unlinkSync,
+} from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pinProjectRecord, realFilePath } from "../helpers/safePath.js";
+import type { ArtifactRecord, RenderRecord, VideoState } from "./videoState.js";
+
+export interface PendingArtifactCleanup {
+ path: string;
+ hash: string;
+ revision: string;
+ id: string;
+ kind: "checks" | "snapshots";
+}
+
+const kinds = ["checks", "snapshots"] as const;
+const records = (state: VideoState, kind: PendingArtifactCleanup["kind"]) => [
+ ...Object.values(state[kind].revisions).flat(),
+ ...state[kind].unversioned,
+];
+const protectedRevisions = (state: VideoState) =>
+ new Set([state.currentRevision, ...(state.renders?.retainedRevisions ?? [])]);
+
+function managedPath(
+ projectDir: string,
+ path: string,
+ kind: PendingArtifactCleanup["kind"],
+): boolean {
+ const canonicalProject = realFilePath(resolve(projectDir));
+ const canonicalPath = realFilePath(path);
+ const root = join(canonicalProject, ".hyperframes", "artifacts", kind);
+ const rel = relative(root, canonicalPath);
+ return (
+ isAbsolute(path) &&
+ rel !== "" &&
+ rel !== ".." &&
+ !rel.startsWith(`..${sep}`) &&
+ !isAbsolute(rel) &&
+ pinProjectRecord(canonicalProject, relative(canonicalProject, canonicalPath)) === canonicalPath
+ );
+}
+
+function updateLatest(state: VideoState): void {
+ for (const kind of kinds) {
+ const available = records(state, kind).filter((record) => record.status !== "cleaned");
+ if (
+ available.some(
+ (record) =>
+ record.id === state[kind].latest?.id && record.revision === state[kind].latest?.revision,
+ )
+ )
+ continue;
+ const latest = available.sort((a, b) => b.createdAt - a.createdAt)[0];
+ state[kind].latest = latest ? { revision: latest.revision, id: latest.id } : null;
+ }
+}
+
+export function planArtifactCleanup(
+ projectDir: string,
+ state: VideoState,
+ render: RenderRecord,
+): void {
+ const protectedIds = protectedRevisions(state);
+ const candidates: Array<{
+ kind: PendingArtifactCleanup["kind"];
+ record: ArtifactRecord;
+ path: string;
+ }> = [];
+ const keepPaths = new Set<string>();
+ const removable = (record: ArtifactRecord, path: string, kind: PendingArtifactCleanup["kind"]) =>
+ Boolean(record.revision) &&
+ !protectedIds.has(record.revision!) &&
+ record.createdAt <= render.completedAt &&
+ managedPath(projectDir, path, kind);
+ for (const kind of kinds) {
+ for (const record of records(state, kind)) {
+ const path = record.image ?? record.report;
+ if (!path || record.status === "cleaned") continue;
+ if (removable(record, path, kind)) candidates.push({ kind, record, path });
+ else keepPaths.add(realFilePath(path));
+ }
+ }
+ for (const { kind, record, path } of candidates) {
+ if (!keepPaths.has(realFilePath(path))) markCleaned(state, kind, record, path, render.id);
+ }
+ updateLatest(state);
+}
+
+function markCleaned(
+ state: VideoState,
+ kind: PendingArtifactCleanup["kind"],
+ record: ArtifactRecord,
+ path: string,
+ renderId: string,
+): void {
+ (state.pendingArtifactCleanup ??= []).push({
+ path,
+ hash: record.contentHash,
+ revision: record.revision!,
+ id: record.id,
+ kind,
+ });
+ delete record.image;
+ delete record.report;
+ record.status = "cleaned";
+ record.cleanedAfterRender = renderId;
+}
+
+function restoreCleaned(state: VideoState, item: PendingArtifactCleanup): void {
+ const record = state[item.kind].revisions[item.revision]?.find(
+ (candidate) => candidate.id === item.id,
+ );
+ if (record?.status !== "cleaned") return;
+ if (item.kind === "checks") record.report = item.path;
+ else record.image = item.path;
+ delete record.status;
+ delete record.cleanedAfterRender;
+}
+
+function stillPendingAfterUnlink(item: PendingArtifactCleanup): boolean {
+ let descriptor: number | undefined;
+ try {
+ descriptor = openSync(item.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+ const stat = fstatSync(descriptor);
+ if (!stat.isFile() || stat.isSymbolicLink()) return false;
+ const hash = createHash("sha256").update(readFileSync(descriptor)).digest("hex");
+ if (hash !== item.hash) return false;
+ const current = lstatSync(item.path);
+ if (current.dev !== stat.dev || current.ino !== stat.ino) return false;
+ unlinkSync(item.path);
+ return false;
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code !== "ENOENT";
+ } finally {
+ if (descriptor !== undefined) closeSync(descriptor);
+ }
+}
+
+export function finishArtifactCleanup(projectDir: string, state: VideoState): void {
+ const protectedIds = protectedRevisions(state);
+ const referenced = new Set(
+ kinds.flatMap((kind) =>
+ records(state, kind)
+ .flatMap((record) => record.image ?? record.report ?? [])
+ .map(realFilePath),
+ ),
+ );
+ state.pendingArtifactCleanup = (state.pendingArtifactCleanup ?? []).filter((item) => {
+ if (!managedPath(projectDir, item.path, item.kind)) return false;
+ const canonicalPath = realFilePath(item.path);
+ if (protectedIds.has(item.revision)) {
+ restoreCleaned(state, item);
+ return false;
+ }
+ if (state.pendingChanges) return true;
+ if (referenced.has(canonicalPath)) return false;
+ return stillPendingAfterUnlink({ ...item, path: canonicalPath });
+ });
+ updateLatest(state);
+}
diff --git a/packages/studio-server/src/history/historyLog.ts b/packages/studio-server/src/history/historyLog.ts
index ee5c3bf996..efb9164406 100644
--- a/packages/studio-server/src/history/historyLog.ts
+++ b/packages/studio-server/src/history/historyLog.ts
@@ -17,7 +17,16 @@ export interface HistoryFileChange {
export type HistoryEntrySide = "before" | "after";
+export interface HistoryTarget {
+ file: string;
+ id?: string;
+ hfId?: string;
+ selector?: string;
+ selectorIndex?: number;
+}
+
export interface HistoryEntry {
+ targets?: HistoryTarget[];
id: string;
who: HistoryWho;
label: string;
diff --git a/packages/studio-server/src/history/index.ts b/packages/studio-server/src/history/index.ts
index f8970d6fee..93b6407510 100644
--- a/packages/studio-server/src/history/index.ts
+++ b/packages/studio-server/src/history/index.ts
@@ -26,7 +26,23 @@ export {
export {
START as HISTORY_START,
type HistoryEntry,
+ type HistoryTarget,
type HistoryEntrySide,
type HistoryFileChange,
type HistoryWho,
} from "./historyLog.js";
+
+export {
+ beginArtifactCapture,
+ recordArtifact,
+ recordArtifacts,
+ artifactDirectory,
+ type ArtifactCapture,
+ type ArtifactInput,
+ type ArtifactRecord,
+ type VideoState,
+ recordRenderSuccess,
+ type RenderRecord,
+} from "./videoState.js";
+
+export { registerRenderOutput } from "../helpers/renderOutputs.js";
diff --git a/packages/studio-server/src/history/projectHistory.ts b/packages/studio-server/src/history/projectHistory.ts
index d1c8c6fbe6..f496829696 100644
--- a/packages/studio-server/src/history/projectHistory.ts
+++ b/packages/studio-server/src/history/projectHistory.ts
@@ -41,6 +41,7 @@ import {
type FolderIdentity,
} from "./historyId.js";
import { takeHistoryOwnership } from "./ownerLock.js";
+import { writeHistoryState } from "./videoState.js";
import {
START,
baselineRecord,
@@ -54,6 +55,7 @@ import {
undoneIds,
writeLog,
type HistoryEntry,
+ type HistoryTarget,
type HistoryEntrySide,
type HistoryFileChange,
type HistoryLog,
@@ -88,6 +90,7 @@ export interface ProjectHistoryOptions {
}
interface ClaimOptions {
+ targets?: readonly HistoryTarget[];
coalesceKey?: string;
idleMs?: number;
/** Per path, the version (fileContentVersion) the claimer overwrote: earlier changes stay their writer's. */
@@ -167,6 +170,7 @@ export interface ProjectHistory {
pin(id: string, pinned: boolean): void;
onEntry(listener: (entry: HistoryEntry) => void): () => void;
/** Takes in every pending write and commits every open window and the outside group. */
+ checkpoint(): Promise<void>;
flush(): Promise<void>;
/** True once another project stands at the folder's path: open that one's history instead. */
replacedAtPath(): boolean;
@@ -182,6 +186,7 @@ interface Tracked {
}
interface Group {
+ targets?: HistoryTarget[];
id: string;
who: HistoryWho;
label: string;
@@ -328,6 +333,18 @@ function addChange(group: Group, path: string, before: string | null, after: str
else group.changes.set(path, { path, before: from, after });
}
+const targetKey = (target: HistoryTarget) =>
+ JSON.stringify([target.file, target.id, target.hfId, target.selector, target.selectorIndex]);
+
+function keepTargetsOfItsFiles(entry: HistoryEntry): HistoryEntry {
+ const targets = entry.targets?.filter((target) =>
+ entry.files.some((file) => file.path === target.file),
+ );
+ if (targets?.length) entry.targets = targets;
+ else delete entry.targets;
+ return entry;
+}
+
class Engine {
readonly dir: string;
readonly foldsCase: boolean;
@@ -384,7 +401,22 @@ class Engine {
queue<T>(task: () => Promise<T>): Promise<T> {
if (this.closed)
return Promise.reject(new HistoryClosedError("This project's history is closed."));
- const run = this.tail.then(task);
+ const run = this.tail.then(async () => {
+ try {
+ return await task();
+ } finally {
+ if (this.whereFolder() === "here") {
+ await writeHistoryState(
+ this.dir,
+ this.projectId,
+ this.home,
+ this.log.entries,
+ this.manifest(),
+ manifestAt(this.log, this.log.entries.at(-1)?.id ?? START) ?? new Map(),
+ ).catch((error) => this.options.onError?.(error));
+ }
+ }
+ });
this.tail = run.catch(() => undefined);
return run;
}
@@ -684,7 +716,7 @@ class Engine {
who: HistoryWho,
label: string,
paths: readonly string[],
- { coalesceKey, idleMs, overwrote = {} }: ClaimOptions,
+ { coalesceKey, idleMs, overwrote = {}, targets = [] }: ClaimOptions,
): Promise<{ id: string } | null> {
await this.sweep();
const taken = await this.takeClaimed(who, paths, overwrote);
@@ -694,11 +726,21 @@ class Engine {
await this.commitPending();
const group = held ?? this.newGroup(who, label);
for (const change of taken) addChange(group, change.path, change.before, change.after);
+ this.addTargets(group, targets);
if (coalesceKey) return this.holdClaim(group, coalesceKey, idleMs);
const entry = await this.commit(group);
return entry && { id: entry.id };
}
+ addTargets(group: Group, targets: readonly HistoryTarget[]): void {
+ const unique = new Map((group.targets ?? []).map((target) => [targetKey(target), target]));
+ for (const target of targets) {
+ const normalized = { ...target, file: this.logPath(target.file) };
+ if (group.changes.has(normalized.file)) unique.set(targetKey(normalized), normalized);
+ }
+ group.targets = [...unique.values()];
+ }
+
/** A claim that took nothing still ends a held claim under another key. */
async claimNothing(coalesceKey: string | undefined): Promise<null> {
if (coalesceKey !== this.claimed?.key) await this.commitClaim();
@@ -868,7 +910,7 @@ class Engine {
if (!group.changes.size && !undoesEmptied) return null;
const pending = this.pendingEntry(group);
const endedAt = Math.max(pending.endedAt, this.log.entries.at(-1)?.endedAt ?? 0);
- const entry: HistoryEntry = { ...pending, endedAt, ...extra };
+ const entry = keepTargetsOfItsFiles({ ...pending, endedAt, ...extra });
this.log.entries.push(entry);
try {
this.persistLog({ type: "entry", entry });
@@ -1119,7 +1161,10 @@ class Engine {
);
return {
ok: true,
- entry: await this.writeAs(who, this.undoLabel(entry), target, { undoes: id }),
+ entry: await this.writeAs(who, this.undoLabel(entry), target, {
+ undoes: id,
+ ...(entry.targets && { targets: entry.targets }),
+ }),
};
}
@@ -1148,7 +1193,15 @@ class Engine {
pendingEntry(group: Group): HistoryEntry {
const files = [...group.changes.values()].sort((a, b) => a.path.localeCompare(b.path));
const { id, who, label, startedAt, lastWriteAt } = group;
- return { id, who, label, startedAt, endedAt: lastWriteAt ?? this.now(), files };
+ return {
+ id,
+ who,
+ label,
+ startedAt,
+ endedAt: lastWriteAt ?? this.now(),
+ files,
+ ...(group.targets?.length && { targets: group.targets }),
+ };
}
conflict(
@@ -1261,6 +1314,7 @@ class Engine {
this.listeners.add(listener);
return () => this.listeners.delete(listener);
},
+ checkpoint: () => this.queue(() => this.settle()),
flush: () => this.queue(() => this.settleAll()),
replacedAtPath: () => this.whereFolder() === "replaced",
close: () =>
diff --git a/packages/studio-server/src/history/videoState.test.ts b/packages/studio-server/src/history/videoState.test.ts
new file mode 100644
index 0000000000..bac83f7d97
--- /dev/null
+++ b/packages/studio-server/src/history/videoState.test.ts
@@ -0,0 +1,269 @@
+import {
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+ symlinkSync,
+ readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, describe, expect, it } from "vitest";
+import { openProjectHistory, type ProjectHistory } from "./projectHistory.js";
+import {
+ recordRenderSuccess,
+ artifactDirectory,
+ beginArtifactCapture,
+ recordArtifact,
+ recordArtifacts,
+ type VideoState,
+} from "./videoState.js";
+
+const cleanups: (() => Promise<void>)[] = [];
+afterEach(async () => {
+ for (const fn of cleanups.splice(0).reverse()) await fn();
+});
+const person = { kind: "person", name: "You" } as const;
+function read(dir: string): VideoState {
+ return JSON.parse(readFileSync(join(dir, ".hyperframes/video-state.json"), "utf8"));
+}
+async function fixture(options = {}) {
+ const root = mkdtempSync(join(tmpdir(), "hf-video-state-"));
+ const projectDir = join(root, "project");
+ const { mkdirSync } = await import("node:fs");
+ mkdirSync(projectDir);
+ writeFileSync(join(projectDir, "index.html"), "initial");
+ let history: ProjectHistory = await openProjectHistory({
+ projectDir,
+ historyRoot: join(root, "history"),
+ ...options,
+ });
+ cleanups.push(async () => {
+ await history.close();
+ rmSync(root, { recursive: true, force: true });
+ });
+ return {
+ projectDir,
+ get history() {
+ return history;
+ },
+ async reopen() {
+ await history.close();
+ history = await openProjectHistory({
+ projectDir,
+ historyRoot: join(root, "history"),
+ ...options,
+ });
+ },
+ async edit(text: string) {
+ const window = await history.beginWindow(person, "Edit title");
+ writeFileSync(join(projectDir, "index.html"), text);
+ await window.close();
+ return read(projectDir).currentRevision!;
+ },
+ };
+}
+
+describe("video state", () => {
+ it("projects real committed history and blob paths, pending writes, undo and redo", async () => {
+ const f = await fixture();
+ expect(read(f.projectDir).currentRevision).toBeNull();
+ const first = await f.edit("first");
+ const state = read(f.projectDir);
+ expect(state.pendingChanges).toBe(false);
+ expect(readFileSync(state.revisions[first].files["index.html"].before!, "utf8")).toBe(
+ "initial",
+ );
+ expect(readFileSync(state.revisions[first].files["index.html"].after!, "utf8")).toBe("first");
+ const window = await f.history.beginWindow(person, "Pending");
+ writeFileSync(join(f.projectDir, "index.html"), "pending");
+ f.history.noteChange("index.html");
+ await new Promise((r) => setTimeout(r, 80));
+ expect(read(f.projectDir).pendingChanges).toBe(true);
+ expect(read(f.projectDir).currentRevision).toBe(first);
+ await window.close();
+ const second = read(f.projectDir).currentRevision!;
+ await f.history.step("back", person);
+ expect(read(f.projectDir).revisions[read(f.projectDir).currentRevision!].undoes).toBe(second);
+ await f.history.step("forward", person);
+ expect(readFileSync(join(f.projectDir, "index.html"), "utf8")).toBe("pending");
+ const count = Object.keys(read(f.projectDir).revisions).length;
+ await f.history.flush();
+ expect(Object.keys(read(f.projectDir).revisions)).toHaveLength(count);
+ });
+
+ it("merges concurrent artifacts and history updates and retains records on restart", async () => {
+ const f = await fixture();
+ const revision = await f.edit("first");
+ const capture = await beginArtifactCapture(f.projectDir);
+ const image = join(f.projectDir, ".hyperframes/frame.png");
+ const report = join(f.projectDir, ".hyperframes/check.json");
+ writeFileSync(image, "png");
+ writeFileSync(report, "{}");
+ await Promise.all([
+ recordArtifact(f.projectDir, capture, {
+ kind: "snapshot",
+ id: "s1",
+ time: 3,
+ scope: "full",
+ image,
+ }),
+ recordArtifact(f.projectDir, capture, {
+ kind: "snapshot",
+ id: "s2",
+ time: 8,
+ scope: "full",
+ image: report,
+ }),
+ recordArtifact(f.projectDir, capture, { kind: "check", id: "c1", scope: "project", report }),
+ f.history.flush(),
+ ]);
+ expect(read(f.projectDir).snapshots.revisions[revision]).toHaveLength(2);
+ expect(read(f.projectDir).checks.latest).toEqual({ revision, id: "c1" });
+ await f.reopen();
+ expect(read(f.projectDir).snapshots.revisions[revision]).toHaveLength(2);
+ await recordArtifact(f.projectDir, capture, {
+ kind: "snapshot",
+ id: "s3",
+ time: 4,
+ scope: "full",
+ image,
+ });
+ expect(read(f.projectDir).snapshots.revisions[revision].map((x) => x.id)).toEqual(["s2", "s3"]);
+ });
+
+ it("does not attribute changed or uncommitted files to a revision", async () => {
+ const f = await fixture();
+ const noRevision = await beginArtifactCapture(f.projectDir);
+ expect(noRevision.revision).toBeNull();
+ await f.edit("first");
+ const capture = await beginArtifactCapture(f.projectDir);
+ writeFileSync(join(f.projectDir, "index.html"), "outside");
+ const image = join(f.projectDir, ".hyperframes/frame.png");
+ writeFileSync(image, "png");
+ await recordArtifact(f.projectDir, capture, {
+ kind: "snapshot",
+ id: "s1",
+ time: 1,
+ scope: "full",
+ image,
+ });
+ expect(read(f.projectDir).snapshots.latest?.revision).toBeNull();
+ expect(read(f.projectDir).snapshots.unversioned[0].attribution).toBe("inputs-changed");
+ expect((await beginArtifactCapture(f.projectDir)).revision).toBeNull();
+ });
+
+ it("removes pruned revision metadata and artifact associations", async () => {
+ const f = await fixture({ budgetBytes: 10 });
+ const first = await f.edit("first");
+ const capture = await beginArtifactCapture(f.projectDir);
+ const image = join(f.projectDir, ".hyperframes/old.png");
+ writeFileSync(image, "png");
+ await recordArtifact(f.projectDir, capture, {
+ kind: "snapshot",
+ id: "old",
+ time: 1,
+ scope: "full",
+ image,
+ });
+ expect(read(f.projectDir).snapshots.revisions[first]).toHaveLength(1);
+ await f.edit("second");
+ const state = read(f.projectDir);
+ expect(Object.keys(state.revisions)).toEqual(f.history.list().map((x) => x.id));
+ expect(state.revisions[first]).toBeUndefined();
+ expect(state.snapshots.revisions[first]).toBeUndefined();
+ expect(state.snapshots.latest).toBeNull();
+ expect(artifactDirectory(f.projectDir, "snapshots")).not.toBe(
+ artifactDirectory(f.projectDir, "snapshots"),
+ );
+ });
+ it("batches multiple frames without storing a second log or file versions", async () => {
+ const f = await fixture();
+ const revision = await f.edit("first");
+ const capture = await beginArtifactCapture(f.projectDir);
+ const image = join(f.projectDir, ".hyperframes/one.png");
+ const second = join(f.projectDir, ".hyperframes/two.png");
+ writeFileSync(image, "first image");
+ writeFileSync(second, "second image");
+ await recordArtifacts(f.projectDir, capture, [
+ { kind: "snapshot", id: "s1", time: 1, scope: "full", image },
+ { kind: "snapshot", id: "s2", time: 2, scope: "#title", image: second },
+ ]);
+ expect(read(f.projectDir).snapshots.revisions[revision]).toHaveLength(2);
+ expect(read(f.projectDir).snapshots.revisions[revision][0].contentHash).toMatch(
+ /^[a-f0-9]{64}$/,
+ );
+ expect(readdirSync(join(f.projectDir, ".hyperframes"))).not.toContain("events.jsonl");
+ expect(readdirSync(join(f.projectDir, ".hyperframes"))).not.toContain("blobs");
+ });
+
+ it("repairs malformed derived state without losing committed history", async () => {
+ const f = await fixture();
+ const revision = await f.edit("first");
+ writeFileSync(join(f.projectDir, ".hyperframes/video-state.json"), "{bad");
+ await f.history.flush();
+ expect(read(f.projectDir).currentRevision).toBe(revision);
+ expect(
+ readdirSync(join(f.projectDir, ".hyperframes")).some((name) =>
+ name.startsWith("video-state.json.invalid-"),
+ ),
+ ).toBe(true);
+ });
+
+ it("rejects a state file symlink outside the project", async () => {
+ const f = await fixture();
+ const outsideDir = mkdtempSync(join(tmpdir(), "hf-state-outside-"));
+ const outside = join(outsideDir, "video-state.json");
+ cleanups.unshift(async () => {
+ rmSync(outsideDir, { recursive: true, force: true });
+ });
+ writeFileSync(outside, "untouched");
+ const path = join(f.projectDir, ".hyperframes/video-state.json");
+ rmSync(path);
+ symlinkSync(outside, path);
+ await expect(beginArtifactCapture(f.projectDir)).rejects.toThrow("inside the project");
+ expect(readFileSync(outside, "utf8")).toBe("untouched");
+ });
+ it("keeps coalesced DOM target provenance in history and its state projection", async () => {
+ const f = await fixture();
+ const targets = [{ file: "index.html", id: "title" }];
+ writeFileSync(join(f.projectDir, "index.html"), "one");
+ await f.history.claim(person, "Drag", ["index.html"], { coalesceKey: "drag", targets });
+ writeFileSync(join(f.projectDir, "index.html"), "two");
+ await f.history.claim(person, "Drag", ["index.html"], {
+ coalesceKey: "drag",
+ targets: [...targets, { file: "index.html", selector: ".word", selectorIndex: 2 }],
+ });
+ await f.history.flush();
+ expect(f.history.list()).toHaveLength(1);
+ const expected = [...targets, { file: "index.html", selector: ".word", selectorIndex: 2 }];
+ expect(f.history.list()[0].targets).toEqual(expected);
+ const revision = read(f.projectDir).currentRevision!;
+ expect(read(f.projectDir).revisions[revision].targets).toEqual(expected);
+ await f.reopen();
+ expect(f.history.list()[0].targets).toEqual(expected);
+ await f.history.step("back", person);
+ expect(f.history.list().at(-1)?.targets).toEqual(expected);
+ expect(read(f.projectDir).revisions[read(f.projectDir).currentRevision!].targets).toEqual(
+ expected,
+ );
+ });
+});
+
+it("records each successful render without replacing revision or artifact state", async () => {
+ const { projectDir } = await fixture();
+ const before = read(projectDir);
+ writeFileSync(join(projectDir, "out.mp4"), "video");
+ const first = await recordRenderSuccess(projectDir, join(projectDir, "out.mp4"));
+ const second = await recordRenderSuccess(
+ projectDir,
+ join(projectDir, "out.mp4"),
+ "completed_with_warnings",
+ );
+ expect(second.id).not.toBe(first.id);
+ const state = read(projectDir);
+ expect(state.renders?.latest).toEqual(second);
+ expect(state.renders?.latest?.status).toBe("completed_with_warnings");
+ expect(state.revisions).toEqual(before.revisions);
+ expect(state.checks).toEqual(before.checks);
+});
diff --git a/packages/studio-server/src/history/videoState.ts b/packages/studio-server/src/history/videoState.ts
new file mode 100644
index 0000000000..6b16f3c9b1
--- /dev/null
+++ b/packages/studio-server/src/history/videoState.ts
@@ -0,0 +1,339 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, existsSync, readFileSync, renameSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
+import { pinProjectRecord } from "../helpers/safePath.js";
+import { listProjectFiles } from "../helpers/projectSignature.js";
+import { readId } from "./historyId.js";
+import { takeHistoryOwnership } from "./ownerLock.js";
+import {
+ planArtifactCleanup,
+ finishArtifactCleanup,
+ type PendingArtifactCleanup,
+} from "./artifactCleanup.js";
+import type { HistoryEntry, HistoryWho, HistoryTarget } from "./historyLog.js";
+
+export interface FileVersion {
+ hash: string;
+ content: string;
+}
+
+export interface RevisionState {
+ targets?: HistoryTarget[];
+ actor: HistoryWho;
+ label: string;
+ startedAt: number;
+ endedAt: number;
+ undoes?: string;
+ restoredTo?: string;
+ files: Record<string, { before: string | null; after: string | null }>;
+}
+
+export interface ArtifactInput {
+ kind: "check" | "snapshot";
+ id: string;
+ scope: string;
+ report?: string;
+ image?: string;
+ time?: number;
+ metadata?: Record<string, unknown>;
+}
+
+export interface ArtifactRecord extends Omit<ArtifactInput, "kind"> {
+ status?: "cleaned";
+ cleanedAfterRender?: string;
+ createdAt: number;
+ contentHash: string;
+ revision: string | null;
+ inputFingerprint: string;
+ inputScope: "local-project-files";
+ attribution: "recorded-revision" | "unversioned" | "inputs-changed";
+}
+
+interface ArtifactCollection {
+ latest: { revision: string | null; id: string } | null;
+ revisions: Record<string, ArtifactRecord[]>;
+ unversioned: ArtifactRecord[];
+}
+
+export interface RenderRecord {
+ revision?: string | null;
+ id: string;
+ completedAt: number;
+ output: string;
+ status: "completed" | "completed_with_warnings";
+}
+
+export interface VideoState {
+ version: 1;
+ historyId: string | null;
+ currentRevision: string | null;
+ pendingChanges: boolean;
+ files: Record<string, FileVersion>;
+ revisions: Record<string, RevisionState>;
+ checks: ArtifactCollection;
+ snapshots: ArtifactCollection;
+ renders?: { latest: RenderRecord | null; retainedRevisions?: string[] };
+ pendingArtifactCleanup?: PendingArtifactCleanup[];
+}
+
+function statePath(dir: string): string {
+ const path = pinProjectRecord(dir, ".hyperframes/video-state.json");
+ if (!path) throw new Error("Video state must stay inside the project.");
+ return path;
+}
+const collection = (): ArtifactCollection => ({ latest: null, revisions: {}, unversioned: [] });
+const emptyState = (): VideoState => ({
+ version: 1,
+ historyId: null,
+ currentRevision: null,
+ pendingChanges: true,
+ files: {},
+ revisions: {},
+ checks: collection(),
+ snapshots: collection(),
+});
+
+function readState(dir: string): VideoState {
+ if (!existsSync(statePath(dir))) return emptyState();
+ const state: VideoState = JSON.parse(readFileSync(statePath(dir), "utf8"));
+ if (state.version !== 1 || !state.checks || !state.snapshots || !state.revisions || !state.files)
+ throw new Error("Unsupported video-state schema.");
+ return state;
+}
+
+async function updateState(dir: string, update: (state: VideoState) => void): Promise<void> {
+ const lock = pinProjectRecord(dir, ".hyperframes/video-state-lock");
+ if (!lock) throw new Error("Video state lock must stay inside the project.");
+ const release = await takeHistoryOwnership(lock, 5000);
+ try {
+ let state: VideoState;
+ try {
+ state = readState(dir);
+ } catch (error) {
+ if (!(error instanceof SyntaxError)) throw error;
+ renameSync(statePath(dir), `${statePath(dir)}.invalid-${randomUUID()}`);
+ state = emptyState();
+ }
+ update(state);
+ replaceFileAtomically(statePath(dir), JSON.stringify(state, null, 2) + "\n", 0o644);
+ } finally {
+ release();
+ }
+}
+
+export async function writeHistoryState(
+ projectDir: string,
+ historyId: string,
+ historyDirectory: string,
+ entries: readonly HistoryEntry[],
+ currentFiles: ReadonlyMap<string, string>,
+ committedFiles: ReadonlyMap<string, string>,
+): Promise<void> {
+ const blob = (hash: string | null) =>
+ hash === null ? null : resolve(historyDirectory, "blobs", hash.slice(0, 2), hash);
+ await updateState(projectDir, (state) => {
+ if (state.historyId && state.historyId !== historyId) {
+ state.checks = collection();
+ state.snapshots = collection();
+ }
+ state.historyId = historyId;
+ state.currentRevision = entries.at(-1)?.id ?? null;
+ state.pendingChanges =
+ currentFiles.size !== committedFiles.size ||
+ [...currentFiles].some(([path, hash]) => committedFiles.get(path) !== hash);
+ state.files = Object.fromEntries(
+ [...currentFiles].map(([path, hash]) => [path, { hash, content: blob(hash)! }]),
+ );
+ state.revisions = Object.fromEntries(
+ entries.map((entry) => [entry.id, revisionState(entry, blob)]),
+ );
+ dropArtifactsOfGoneRevisions(state);
+ });
+}
+
+function revisionState(
+ entry: HistoryEntry,
+ blob: (hash: string | null) => string | null,
+): RevisionState {
+ const targets = entry.targets?.filter((target) =>
+ entry.files.some((file) => file.path === target.file),
+ );
+ return {
+ actor: entry.who,
+ ...(targets?.length && { targets }),
+ label: entry.label,
+ startedAt: entry.startedAt,
+ endedAt: entry.endedAt,
+ ...(entry.undoes && { undoes: entry.undoes }),
+ ...(entry.restoredTo && { restoredTo: entry.restoredTo }),
+ files: Object.fromEntries(
+ entry.files.map((file) => [
+ file.path,
+ { before: blob(file.before), after: blob(file.after) },
+ ]),
+ ),
+ };
+}
+
+function dropArtifactsOfGoneRevisions(state: VideoState): void {
+ const kept = (revision: string) =>
+ Boolean(state.revisions[revision]) ||
+ Boolean(state.renders?.retainedRevisions?.includes(revision));
+ for (const artifacts of [state.checks, state.snapshots]) {
+ for (const revision of Object.keys(artifacts.revisions)) {
+ if (!kept(revision)) delete artifacts.revisions[revision];
+ }
+ if (artifacts.latest?.revision && !state.revisions[artifacts.latest.revision])
+ artifacts.latest = null;
+ }
+}
+
+async function fileHashes(dir: string): Promise<Record<string, string>> {
+ const files: Record<string, string> = {};
+ for (const { path } of listProjectFiles(dir).sort((a, b) => a.path.localeCompare(b.path))) {
+ const hash = createHash("sha256");
+ for await (const chunk of createReadStream(join(dir, path))) hash.update(chunk);
+ files[path] = hash.digest("hex");
+ }
+ return files;
+}
+
+export interface ArtifactCapture {
+ revision: string | null;
+ fingerprint: string;
+}
+
+export async function beginArtifactCapture(projectDir: string): Promise<ArtifactCapture> {
+ const files = await fileHashes(projectDir);
+ const state = readState(projectDir);
+ const matches =
+ state.historyId !== null &&
+ readId(projectDir) === state.historyId &&
+ !state.pendingChanges &&
+ Object.entries(state.files).every(([path, file]) => files[path] === file.hash) &&
+ Object.keys(files)
+ .filter((path) => !path.split("/").some((part) => part.startsWith(".")))
+ .every((path) => state.files[path]?.hash === files[path]);
+ return {
+ revision: matches ? state.currentRevision : null,
+ fingerprint: createHash("sha256").update(JSON.stringify(files)).digest("hex"),
+ };
+}
+
+export async function recordArtifact(
+ projectDir: string,
+ capture: ArtifactCapture,
+ artifact: ArtifactInput,
+): Promise<ArtifactRecord[]> {
+ return recordArtifacts(projectDir, capture, [artifact]);
+}
+
+export async function recordArtifacts(
+ projectDir: string,
+ capture: ArtifactCapture,
+ artifactsToRecord: readonly ArtifactInput[],
+): Promise<ArtifactRecord[]> {
+ const records: ArtifactRecord[] = [];
+ const hashes = new Map<string, string>();
+ for (const artifact of artifactsToRecord) {
+ const path = artifact.kind === "check" ? artifact.report : artifact.image;
+ if (!path || !isAbsolute(path)) throw new Error("Artifact needs an absolute output path.");
+ hashes.set(artifact.id, createHash("sha256").update(readFileSync(path)).digest("hex"));
+ }
+ const after = await beginArtifactCapture(projectDir);
+ const unchanged = after.fingerprint === capture.fingerprint;
+ await updateState(projectDir, (state) => {
+ const revision = unchanged ? knownRevision(state, capture.revision) : null;
+ const attribution = attributionOf(unchanged, revision);
+ for (const artifact of artifactsToRecord) {
+ const { kind, ...fields } = artifact;
+ const record: ArtifactRecord = {
+ ...fields,
+ createdAt: Date.now(),
+ contentHash: hashes.get(artifact.id)!,
+ revision,
+ inputFingerprint: capture.fingerprint,
+ inputScope: "local-project-files",
+ attribution,
+ };
+ const artifacts = kind === "check" ? state.checks : state.snapshots;
+ dropSupersededArtifacts(artifacts, artifact);
+ const list = revision ? (artifacts.revisions[revision] ??= []) : artifacts.unversioned;
+ list.push(record);
+ records.push(record);
+ artifacts.latest = { revision, id: record.id };
+ }
+ });
+ return records;
+}
+
+function knownRevision(state: VideoState, revision: string | null | undefined): string | null {
+ return revision && state.revisions[revision] ? revision : null;
+}
+
+function attributionOf(unchanged: boolean, revision: string | null): ArtifactRecord["attribution"] {
+ if (!unchanged) return "inputs-changed";
+ return revision ? "recorded-revision" : "unversioned";
+}
+
+// An explicit output path can be reused; never retain a reference to overwritten evidence.
+function supersedes(artifact: ArtifactInput, previous: ArtifactRecord): boolean {
+ if (previous.status !== "cleaned" && !existsSync(previous.image ?? previous.report ?? ""))
+ return true;
+ if (previous.id === artifact.id) return true;
+ if (artifact.image && previous.image === artifact.image) return true;
+ return Boolean(artifact.report && previous.report === artifact.report);
+}
+
+function dropSupersededArtifacts(artifacts: ArtifactCollection, artifact: ArtifactInput): void {
+ for (const list of [...Object.values(artifacts.revisions), artifacts.unversioned]) {
+ for (let i = list.length - 1; i >= 0; i--) {
+ if (supersedes(artifact, list[i]!)) list.splice(i, 1);
+ }
+ }
+}
+
+export function artifactDirectory(projectDir: string, kind: "checks" | "snapshots"): string {
+ return join(resolve(projectDir), ".hyperframes", "artifacts", kind, randomUUID());
+}
+
+function retainRevision(retained: readonly string[], revision: string | null): string[] {
+ if (!revision) return [...retained];
+ return [revision, ...retained.filter((id) => id !== revision)].slice(0, 2);
+}
+
+export async function recordRenderSuccess(
+ projectDir: string,
+ output: string,
+ status: RenderRecord["status"] = "completed",
+ capture?: ArtifactCapture,
+): Promise<RenderRecord> {
+ const outputFile = statSync(output);
+ if (
+ (!outputFile.isFile() && !outputFile.isDirectory()) ||
+ (outputFile.isFile() && outputFile.size === 0)
+ )
+ throw new Error("Render output is missing or empty.");
+ const after = capture ? await beginArtifactCapture(projectDir) : null;
+ const record: RenderRecord = {
+ id: randomUUID(),
+ completedAt: Date.now(),
+ output: resolve(output),
+ status,
+ };
+ const unchanged = Boolean(capture && after?.fingerprint === capture.fingerprint);
+ await updateState(projectDir, (state) => {
+ record.revision = unchanged ? knownRevision(state, capture?.revision) : null;
+ state.renders = {
+ latest: record,
+ retainedRevisions: retainRevision(state.renders?.retainedRevisions ?? [], record.revision),
+ };
+ if (outputFile.isFile() && record.revision && !state.pendingChanges)
+ planArtifactCleanup(projectDir, state, record);
+ });
+ await updateState(projectDir, (state) => {
+ finishArtifactCleanup(projectDir, state);
+ });
+ return record;
+}
diff --git a/packages/studio-server/src/routes/history.test.ts b/packages/studio-server/src/routes/history.test.ts
index 44f2390086..b82ffcecb3 100644
--- a/packages/studio-server/src/routes/history.test.ts
+++ b/packages/studio-server/src/routes/history.test.ts
@@ -452,6 +452,29 @@ describe("history routes", () => {
expect(readFileSync(clip).equals(original)).toBe(true);
});
+ it("validates DOM targets and stores only targets of changed files", async () => {
+ const { projectDir, call } = await demoProject();
+ writeFileSync(join(projectDir, "index.html"), "B");
+ await call("/claim", {
+ label: "Title",
+ paths: ["index.html"],
+ targets: [
+ { file: "index.html", id: "title", selector: ".title", selectorIndex: 0, junk: "ignored" },
+ { file: "../outside.html", id: "outside" },
+ { file: "unchanged.html", id: "other" },
+ { file: "index.html", selector: ".word", selectorIndex: -1 },
+ { file: "index.html" },
+ null,
+ "bad",
+ ],
+ });
+ const { entries } = await (await call("")).json();
+ expect(entries[0].targets).toEqual([
+ { file: "index.html", id: "title", selector: ".title", selectorIndex: 0 },
+ { file: "index.html", selector: ".word" },
+ ]);
+ });
+
it("end a window given idleMs by itself once its writes stop", async () => {
const { projectDir, call } = await demoProject();
@@ -499,3 +522,21 @@ describe("history routes", () => {
expect((await call("")).status).toBe(404);
});
});
+
+it("checkpoints pending writes without closing an agent window", async () => {
+ const { projectDir, history, call } = await demoProject();
+ const who = { kind: "agent", name: "test-agent" } as const;
+ const window = await history.beginWindow(who, "Edit video");
+ writeFileSync(join(projectDir, "index.html"), "B");
+ const response = await call("/checkpoint", {});
+ expect(response.status).toBe(200);
+ const first = history.list().at(-1)!;
+ expect(first.who).toEqual(who);
+ expect(history.peek(first.id)?.["index.html"]).toBeTruthy();
+ await call("/checkpoint", {});
+ expect(history.list()).toHaveLength(1);
+ writeFileSync(join(projectDir, "index.html"), "C");
+ await window.close();
+ expect(history.list()).toHaveLength(2);
+ expect(history.list().at(-1)?.who).toEqual(who);
+});
diff --git a/packages/studio-server/src/routes/history.ts b/packages/studio-server/src/routes/history.ts
index e0bde16b06..df17f81a00 100644
--- a/packages/studio-server/src/routes/history.ts
+++ b/packages/studio-server/src/routes/history.ts
@@ -7,7 +7,7 @@ import {
type HistoryWindow,
type ProjectHistory,
} from "../history/projectHistory.js";
-import type { HistoryWho } from "../history/historyLog.js";
+import type { HistoryWho, HistoryTarget } from "../history/historyLog.js";
const YOU: HistoryWho = { kind: "person", name: "You" };
@@ -53,6 +53,36 @@ function versionsOf(value: unknown): Record<string, string> | undefined {
return pairs.length ? Object.fromEntries(pairs) : undefined;
}
+function targetsOf(value: unknown): HistoryTarget[] | undefined {
+ if (!Array.isArray(value)) return undefined;
+ const targets = value.flatMap((item) => targetOf(item) ?? []);
+ return targets.length ? targets : undefined;
+}
+
+function targetOf(item: unknown): HistoryTarget | null {
+ if (!item || typeof item !== "object") return null;
+ const fields = item as Record<string, unknown>;
+ if (typeof fields.file !== "string") return null;
+ const target: HistoryTarget = { file: fields.file, ...identityOf(fields) };
+ if (!target.id && !target.hfId && !target.selector) return null;
+ if (isSelectorIndex(fields.selectorIndex)) target.selectorIndex = fields.selectorIndex;
+ return target;
+}
+
+function identityOf(
+ fields: Record<string, unknown>,
+): Pick<HistoryTarget, "id" | "hfId" | "selector"> {
+ const identity: Pick<HistoryTarget, "id" | "hfId" | "selector"> = {};
+ for (const key of ["id", "hfId", "selector"] as const) {
+ const field = fields[key];
+ if (typeof field === "string" && field) identity[key] = field;
+ }
+ return identity;
+}
+
+const isSelectorIndex = (value: unknown): value is number =>
+ typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
/** What Cmd+Z or Cmd+Shift+Z would revert next, so Studio can name it on its buttons. */
function nextStep(history: ProjectHistory, direction: "back" | "forward") {
const target = history.next(direction, YOU);
@@ -88,6 +118,12 @@ export function registerHistoryRoutes(api: Hono, adapter: StudioApiAdapter): voi
return { entries, back: nextStep(history, "back"), forward: nextStep(history, "forward") };
}),
);
+ api.post(`${base}/checkpoint`, (c) =>
+ withHistory(adapter, c, async (history) => {
+ await history.checkpoint();
+ return { ok: true };
+ }),
+ );
api.post(`${base}/step`, (c) =>
withHistory(adapter, c, (history, body) =>
history.step(body.direction === "forward" ? "forward" : "back", YOU, writing(c)),
@@ -128,9 +164,11 @@ export function registerHistoryRoutes(api: Hono, adapter: StudioApiAdapter): voi
const paths = Array.isArray(body.paths) ? body.paths.filter((path) => text(path)) : [];
const coalesceKey = text(body.coalesceKey) ?? undefined;
const overwrote = versionsOf(body.overwrote);
+ const targets = targetsOf(body.targets);
const claimed = await history.claim(YOU, text(body.label) ?? "Edited in Studio", paths, {
...(coalesceKey && { coalesceKey, idleMs: idleOf(body) ?? Infinity }),
...(overwrote && { overwrote }),
+ ...(targets && { targets }),
});
return { claimed };
}),
diff --git a/packages/studio/src/hooks/useDomEditCommits.test.tsx b/packages/studio/src/hooks/useDomEditCommits.test.tsx
index 4303fa2395..9f2b3f4bb7 100644
--- a/packages/studio/src/hooks/useDomEditCommits.test.tsx
+++ b/packages/studio/src/hooks/useDomEditCommits.test.tsx
@@ -350,6 +350,11 @@ describe("useDomEditCommits z-index reorder persistence", () => {
// round-trip that separates them.
coalesceMs: Number.POSITIVE_INFINITY,
files: { "index.html": { before: original, after } },
+ targets: [
+ { file: "index.html", id: "a", hfId: "hf-card" },
+ { file: "index.html", id: "b" },
+ { file: "index.html", id: "c" },
+ ],
});
// FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
// The live DOM + store already hold the final state and the server matched
diff --git a/packages/studio/src/hooks/useDomEditCommits.ts b/packages/studio/src/hooks/useDomEditCommits.ts
index 8403ddc32b..b5c958a23a 100644
--- a/packages/studio/src/hooks/useDomEditCommits.ts
+++ b/packages/studio/src/hooks/useDomEditCommits.ts
@@ -178,6 +178,19 @@ export function useDomEditCommits({
coalesceKey: options.coalesceKey,
coalesceMs: options.coalesceMs,
files,
+ targets: batches
+ .filter((batch) => Object.hasOwn(files, batch.sourceFile))
+ .flatMap((batch) =>
+ batch.patches.map(({ target }) => ({
+ file: batch.sourceFile,
+ ...(target.id && { id: target.id }),
+ ...(target.hfId && { hfId: target.hfId }),
+ ...(target.selector && { selector: target.selector }),
+ ...(target.selectorIndex !== undefined && {
+ selectorIndex: target.selectorIndex,
+ }),
+ })),
+ ),
});
}
return {
diff --git a/packages/studio/src/hooks/useDomEditPersist.test.tsx b/packages/studio/src/hooks/useDomEditPersist.test.tsx
index f78a2a85d9..715f9ac4b9 100644
--- a/packages/studio/src/hooks/useDomEditPersist.test.tsx
+++ b/packages/studio/src/hooks/useDomEditPersist.test.tsx
@@ -116,6 +116,14 @@ describe("useDomEditPersist", () => {
coalesceKey: undefined,
coalesceMs: undefined,
files: { "index.html": { before: SOURCE, after: PATCHED } },
+ targets: [
+ {
+ file: "index.html",
+ hfId: "hf-card",
+ selector: '[data-hf-id="hf-card"]',
+ selectorIndex: 0,
+ },
+ ],
});
expect(params.forceReloadSdkSession).toHaveBeenCalledTimes(1);
expect(params.reloadPreview).toHaveBeenCalledTimes(1);
diff --git a/packages/studio/src/hooks/useDomEditPersist.ts b/packages/studio/src/hooks/useDomEditPersist.ts
index 63a5a98757..e193b653ab 100644
--- a/packages/studio/src/hooks/useDomEditPersist.ts
+++ b/packages/studio/src/hooks/useDomEditPersist.ts
@@ -22,12 +22,8 @@ import { reseekPreviewRuntime } from "./timelineTrackVisibility";
import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
import { readProjectFileContent } from "../utils/studioFileHistory";
-export interface RecordEditInput {
- label: string;
- coalesceKey?: string;
- coalesceMs?: number;
- files: Record<string, { before: string; after: string }>;
-}
+import type { RecordEditInput } from "../utils/studioFileHistory";
+export type { RecordEditInput } from "../utils/studioFileHistory";
export interface UseDomEditPersistParams {
activeCompPath: string | null;
@@ -164,6 +160,17 @@ export function useDomEditPersist({
await editHistory.recordEdit({
...history,
+ targets: [
+ {
+ file: targetPath,
+ ...(selection.id && { id: selection.id }),
+ ...(selection.hfId && { hfId: selection.hfId }),
+ ...(selection.selector && { selector: selection.selector }),
+ ...(selection.selectorIndex !== undefined && {
+ selectorIndex: selection.selectorIndex,
+ }),
+ },
+ ],
files: { [targetPath]: { before: originalContent, after: finalContent } },
});
return { patchData, patchedContent, finalContent };
diff --git a/packages/studio/src/hooks/usePersistentEditHistory.test.ts b/packages/studio/src/hooks/usePersistentEditHistory.test.ts
index 5f9706998e..5b44f4eed6 100644
--- a/packages/studio/src/hooks/usePersistentEditHistory.test.ts
+++ b/packages/studio/src/hooks/usePersistentEditHistory.test.ts
@@ -700,3 +700,23 @@ it("an undo taken before the view caught up with the edit still reports the prev
files: { "index.html": { previous: "B", restored: "A" } },
});
});
+
+it("stores DOM targets in existing history and retains them through undo and redo", async () => {
+ const { hook, save, readFile, history } = await studio();
+ save("B");
+ const targets = [{ file: "index.html", id: "title", selector: ".title", selectorIndex: 1 }];
+ await act(() =>
+ hook().recordEdit({
+ label: "Title",
+ targets,
+ files: { "index.html": { before: "A", after: "B" } },
+ }),
+ );
+ expect(history.list().at(-1)?.targets).toEqual(targets);
+ await vi.waitFor(() => expect(hook().canUndo).toBe(true));
+ await act(() => hook().undo({ readFile }));
+ expect(history.list().at(-1)?.targets).toEqual(targets);
+ await vi.waitFor(() => expect(hook().canRedo).toBe(true));
+ await act(() => hook().redo({ readFile }));
+ expect(history.list().at(-1)?.targets).toEqual(targets);
+});
diff --git a/packages/studio/src/hooks/usePersistentEditHistory.ts b/packages/studio/src/hooks/usePersistentEditHistory.ts
index 154e9b7a9d..f34d4be9eb 100644
--- a/packages/studio/src/hooks/usePersistentEditHistory.ts
+++ b/packages/studio/src/hooks/usePersistentEditHistory.ts
@@ -240,13 +240,14 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
}, [own]);
const recordEdit = useCallback(
- async ({ label, coalesceKey, coalesceMs, files, created = [] }: RecordEditInput) => {
+ async ({ label, coalesceKey, coalesceMs, files, targets, created = [] }: RecordEditInput) => {
if (!projectId) return;
const paths = [...Object.keys(files), ...created];
own.overtake();
const reply = await post(historyUrl(projectId, "/claim"), {
label,
paths,
+ ...(targets?.length && { targets }),
overwrote: await overwroteVersions(files),
...(coalesceKey && {
coalesceKey: claimKey(coalesceKey),
diff --git a/packages/studio/src/utils/sdkCutover.test.ts b/packages/studio/src/utils/sdkCutover.test.ts
index fe44373ff9..cf4e43e394 100644
--- a/packages/studio/src/utils/sdkCutover.test.ts
+++ b/packages/studio/src/utils/sdkCutover.test.ts
@@ -358,7 +358,10 @@ describe("sdkCutoverPersist", () => {
label: "Resize layer box",
});
expect(deps.editHistory.recordEdit).toHaveBeenCalledWith(
- expect.objectContaining({ label: "Resize layer box" }),
+ expect.objectContaining({
+ label: "Resize layer box",
+ targets: [{ file: "/comp.html", hfId: "hf-abc" }],
+ }),
);
});
diff --git a/packages/studio/src/utils/sdkCutover.ts b/packages/studio/src/utils/sdkCutover.ts
index 65f593b960..db0a454fd4 100644
--- a/packages/studio/src/utils/sdkCutover.ts
+++ b/packages/studio/src/utils/sdkCutover.ts
@@ -32,7 +32,6 @@ export type {
CutoverResult,
PublishSdkSession,
} from "./sdkEditTransaction";
-
function sdkFamilyEnabled(family: StudioSdkOperationFamily): boolean {
const configured = Object.prototype.hasOwnProperty.call(
studioAvailability,
@@ -54,7 +53,6 @@ function trackCutoverResult(
failedCutover(result.error, family, context);
}
}
-
/** True when targetPath isn't the composition the SDK session models. */
function wrongCompositionFile(deps: CutoverDeps, targetPath: string): boolean {
return deps.compositionPath != null && targetPath !== deps.compositionPath;
@@ -105,7 +103,18 @@ export async function sdkCutoverPersist(
(session) => {
for (const editOp of patchOpsToSdkEditOps(hfId, ops)) session.dispatch(editOp);
},
- options,
+ {
+ ...options,
+ targets: [
+ {
+ file: targetPath,
+ hfId,
+ ...(selection.id && { id: selection.id }),
+ ...(selection.selector && { selector: selection.selector }),
+ ...(selection.selectorIndex !== undefined && { selectorIndex: selection.selectorIndex }),
+ },
+ ],
+ },
);
trackCutoverResult(result, "dom", { hfId, opCount: ops.length });
return result;
@@ -155,7 +164,6 @@ export async function sdkTimingPersist(
return failedCutover(error, "timing", { hfId, opCount: 1 });
}
}
-
export async function sdkTimingBatchPersist(
changes: Array<{
hfId: string;
@@ -224,7 +232,6 @@ type SdkGsapTweenOp =
| { kind: "add"; target: string; spec: GsapTweenSpec }
| { kind: "set"; animationId: string; properties: Partial<GsapTweenSpec> }
| { kind: "remove"; animationId: string };
-
export function sdkGsapTweenPersist(
targetPath: string,
op: SdkGsapTweenOp,
@@ -276,7 +283,6 @@ export function sdkGsapTweenPersist(
});
});
}
-
async function dispatchGsapOpAndPersist(
family: "gsap-animation" | "gsap-keyframe",
targetPath: string,
@@ -327,7 +333,6 @@ async function dispatchGsapOpAndPersist(
return failedCutover(error, family, { opCount: 1 });
}
}
-
export function sdkGsapKeyframePersist(
targetPath: string,
animationId: string,
diff --git a/packages/studio/src/utils/sdkEditTransaction.ts b/packages/studio/src/utils/sdkEditTransaction.ts
index 7479ac4c61..69f6c70a94 100644
--- a/packages/studio/src/utils/sdkEditTransaction.ts
+++ b/packages/studio/src/utils/sdkEditTransaction.ts
@@ -1,3 +1,4 @@
+import type { EditContextTarget } from "./studioFileHistory";
import { openComposition, type Composition } from "@hyperframes/sdk";
import { hashContent, markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
import { trackStudioEvent } from "./studioTelemetry";
@@ -31,6 +32,7 @@ export interface CutoverDeps {
editHistory: {
recordEdit: (entry: {
label: string;
+ targets?: EditContextTarget[];
coalesceKey?: string;
coalesceMs?: number;
files: Record<string, { before: string; after: string }>;
@@ -56,6 +58,7 @@ export interface CutoverDeps {
}
export interface CutoverOptions {
+ targets?: EditContextTarget[];
label?: string;
coalesceKey?: string;
/** Coalesce window (ms); Infinity folds across a slow round-trip. */
@@ -232,6 +235,15 @@ async function rollbackWrite(
}
}
+function historyEntryOptions(options?: CutoverOptions) {
+ return {
+ label: options?.label ?? "Edit layer",
+ ...(options?.targets && { targets: options.targets }),
+ ...(options?.coalesceKey ? { coalesceKey: options.coalesceKey } : {}),
+ ...(options?.coalesceMs != null ? { coalesceMs: options.coalesceMs } : {}),
+ };
+}
+
async function writeAndRecord(
after: string,
targetPath: string,
@@ -247,9 +259,7 @@ async function writeAndRecord(
}
try {
await deps.editHistory.recordEdit({
- label: options?.label ?? "Edit layer",
- ...(options?.coalesceKey ? { coalesceKey: options.coalesceKey } : {}),
- ...(options?.coalesceMs != null ? { coalesceMs: options.coalesceMs } : {}),
+ ...historyEntryOptions(options),
files: { [targetPath]: { before: originalContent, after } },
});
return null;
diff --git a/packages/studio/src/utils/studioFileHistory.ts b/packages/studio/src/utils/studioFileHistory.ts
index e1cefcdc33..02e0155f68 100644
--- a/packages/studio/src/utils/studioFileHistory.ts
+++ b/packages/studio/src/utils/studioFileHistory.ts
@@ -1,10 +1,14 @@
+import type { HistoryTarget } from "@hyperframes/studio-server";
import { buildProjectApiPath } from "./projectRouting";
import type { MutableRefObject } from "react";
import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
import { studioApiFetch } from "./studioApiFetch";
+export type EditContextTarget = HistoryTarget;
+
export interface RecordEditInput {
+ targets?: EditContextTarget[];
label: string;
coalesceKey?: string;
coalesceMs?: number;
diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json
index 478af26fb6..7b0e4d556d 100644
--- a/scripts/package-size-budgets.json
+++ b/scripts/package-size-budgets.json
@@ -11,6 +11,6 @@
"@hyperframes/producer": { "packed": 729380, "unpacked": 2672493 },
"@hyperframes/sdk": { "packed": 90662, "unpacked": 325069 },
"@hyperframes/shader-transitions": { "packed": 212864, "unpacked": 825937 },
- "@hyperframes/studio": { "packed": 5973698, "unpacked": 23915921 },
- "@hyperframes/studio-server": { "packed": 134964, "unpacked": 528620 }
+ "@hyperframes/studio": { "packed": 5998328, "unpacked": 24360208 },
+ "@hyperframes/studio-server": { "packed": 134964, "unpacked": 532277 }
}