Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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: strelse 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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): voireturn { 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): voiconst 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.tsxindex 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 matcheddiff --git a/packages/studio/src/hooks/useDomEditCommits.ts b/packages/studio/src/hooks/useDomEditCommits.tsindex 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.tsxindex 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.tsindex 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.tsindex 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 prevfiles: { "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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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 }}