@hyperframes/studio 0.5.0-alpha.10 → 0.5.0-alpha.12

package/src/utils/editHistory.ts

@@ -0,0 +1,218 @@
+export type EditHistoryKind = "manual" | "timeline" | "source";
+
+export interface EditHistoryFileSnapshot {
+  before: string;
+  after: string;
+  beforeHash: string;
+  afterHash: string;
+}
+
+export interface EditHistoryEntry {
+  id: string;
+  projectId: string;
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  createdAt: number;
+  files: Record<string, EditHistoryFileSnapshot>;
+}
+
+export interface EditHistoryState {
+  version: 1;
+  updatedAt: number;
+  undo: EditHistoryEntry[];
+  redo: EditHistoryEntry[];
+}
+
+export interface EditHistoryOptions {
+  maxEntries?: number;
+  coalesceMs?: number;
+}
+
+export interface BuildEditHistoryEntryInput {
+  id: string;
+  projectId: string;
+  label: string;
+  kind?: EditHistoryKind;
+  coalesceKey?: string;
+  now: number;
+  files: Record<string, { before: string; after: string }>;
+}
+
+export type EditHistoryDirection = "undo" | "redo";
+
+export type EditHistoryApplyCheck =
+  | { ok: true }
+  | { ok: false; reason: "content-mismatch"; path: string };
+
+export type EditHistoryTransitionResult =
+  | {
+      ok: true;
+      state: EditHistoryState;
+      entry: EditHistoryEntry;
+      filesToWrite: Record<string, string>;
+    }
+  | {
+      ok: false;
+      reason: "empty" | "content-mismatch";
+      state: EditHistoryState;
+      filesToWrite: Record<string, string>;
+      path?: string;
+    };
+
+const DEFAULT_MAX_ENTRIES = 100;
+const DEFAULT_COALESCE_MS = 1500;
+
+export function hashEditHistoryContent(content: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < content.length; index += 1) {
+    hash ^= content.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function createEmptyEditHistory(_options?: EditHistoryOptions): EditHistoryState {
+  return {
+    version: 1,
+    updatedAt: 0,
+    undo: [],
+    redo: [],
+  };
+}
+
+export function buildEditHistoryEntry(input: BuildEditHistoryEntryInput): EditHistoryEntry {
+  const files: Record<string, EditHistoryFileSnapshot> = {};
+  for (const [path, snapshot] of Object.entries(input.files)) {
+    if (snapshot.before === snapshot.after) continue;
+    files[path] = {
+      before: snapshot.before,
+      after: snapshot.after,
+      beforeHash: hashEditHistoryContent(snapshot.before),
+      afterHash: hashEditHistoryContent(snapshot.after),
+    };
+  }
+
+  return {
+    id: input.id,
+    projectId: input.projectId,
+    label: input.label,
+    kind: input.kind ?? "manual",
+    coalesceKey: input.coalesceKey,
+    createdAt: input.now,
+    files,
+  };
+}
+
+export function pushEditHistoryEntry(
+  state: EditHistoryState,
+  entry: EditHistoryEntry,
+  options?: EditHistoryOptions,
+): EditHistoryState {
+  if (Object.keys(entry.files).length === 0) return state;
+
+  const coalesceMs = options?.coalesceMs ?? DEFAULT_COALESCE_MS;
+  const maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const previous = state.undo[state.undo.length - 1];
+  let undo = state.undo;
+
+  if (
+    previous &&
+    previous.coalesceKey &&
+    previous.coalesceKey === entry.coalesceKey &&
+    entry.createdAt - previous.createdAt <= coalesceMs
+  ) {
+    const files: Record<string, EditHistoryFileSnapshot> = {};
+    for (const [path, snapshot] of Object.entries(entry.files)) {
+      const previousSnapshot = previous.files[path];
+      files[path] = previousSnapshot
+        ? {
+            before: previousSnapshot.before,
+            after: snapshot.after,
+            beforeHash: previousSnapshot.beforeHash,
+            afterHash: snapshot.afterHash,
+          }
+        : snapshot;
+    }
+    undo = [...state.undo.slice(0, -1), { ...entry, files }];
+  } else {
+    undo = [...state.undo, entry];
+  }
+
+  return {
+    version: 1,
+    updatedAt: entry.createdAt,
+    undo: undo.slice(Math.max(0, undo.length - maxEntries)),
+    redo: [],
+  };
+}
+
+export function canApplyEditHistoryEntry(
+  entry: EditHistoryEntry,
+  direction: EditHistoryDirection,
+  currentHashes: Record<string, string>,
+): EditHistoryApplyCheck {
+  for (const [path, snapshot] of Object.entries(entry.files)) {
+    const expected = direction === "undo" ? snapshot.afterHash : snapshot.beforeHash;
+    if (currentHashes[path] !== expected) {
+      return { ok: false, reason: "content-mismatch", path };
+    }
+  }
+  return { ok: true };
+}
+
+export function undoEditHistory(
+  state: EditHistoryState,
+  currentHashes: Record<string, string>,
+  now: number,
+): EditHistoryTransitionResult {
+  const entry = state.undo[state.undo.length - 1];
+  if (!entry) return { ok: false, reason: "empty", state, filesToWrite: {} };
+
+  const check = canApplyEditHistoryEntry(entry, "undo", currentHashes);
+  if (!check.ok) {
+    return { ok: false, reason: check.reason, path: check.path, state, filesToWrite: {} };
+  }
+
+  return {
+    ok: true,
+    entry,
+    filesToWrite: Object.fromEntries(
+      Object.entries(entry.files).map(([path, snapshot]) => [path, snapshot.before]),
+    ),
+    state: {
+      version: 1,
+      updatedAt: now,
+      undo: state.undo.slice(0, -1),
+      redo: [...state.redo, entry],
+    },
+  };
+}
+
+export function redoEditHistory(
+  state: EditHistoryState,
+  currentHashes: Record<string, string>,
+  now: number,
+): EditHistoryTransitionResult {
+  const entry = state.redo[state.redo.length - 1];
+  if (!entry) return { ok: false, reason: "empty", state, filesToWrite: {} };
+
+  const check = canApplyEditHistoryEntry(entry, "redo", currentHashes);
+  if (!check.ok) {
+    return { ok: false, reason: check.reason, path: check.path, state, filesToWrite: {} };
+  }
+
+  return {
+    ok: true,
+    entry,
+    filesToWrite: Object.fromEntries(
+      Object.entries(entry.files).map(([path, snapshot]) => [path, snapshot.after]),
+    ),
+    state: {
+      version: 1,
+      updatedAt: now,
+      undo: [...state.undo, entry],
+      redo: state.redo.slice(0, -1),
+    },
+  };
+}

package/src/utils/editHistoryStorage.test.ts

@@ -0,0 +1,37 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { buildEditHistoryEntry, createEmptyEditHistory, pushEditHistoryEntry } from "./editHistory";
+import {
+  createMemoryEditHistoryStorage,
+  loadEditHistoryState,
+  saveEditHistoryState,
+} from "./editHistoryStorage";
+
+describe("edit history storage", () => {
+  let storage: ReturnType<typeof createMemoryEditHistoryStorage>;
+
+  beforeEach(() => {
+    storage = createMemoryEditHistoryStorage();
+  });
+
+  it("returns empty history for projects without persisted state", async () => {
+    const state = await loadEditHistoryState(storage, "project-1");
+
+    expect(state).toEqual(createEmptyEditHistory());
+  });
+
+  it("saves and loads history per project", async () => {
+    const entry = buildEditHistoryEntry({
+      id: "entry-1",
+      projectId: "project-1",
+      label: "Move layer",
+      files: { "index.html": { before: "a", after: "b" } },
+      now: 100,
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    await saveEditHistoryState(storage, "project-1", state);
+
+    expect(await loadEditHistoryState(storage, "project-1")).toEqual(state);
+    expect(await loadEditHistoryState(storage, "project-2")).toEqual(createEmptyEditHistory());
+  });
+});

package/src/utils/editHistoryStorage.ts

@@ -0,0 +1,99 @@
+import { createEmptyEditHistory, type EditHistoryState } from "./editHistory";
+
+export interface EditHistoryStorageAdapter {
+  get(projectId: string): Promise<EditHistoryState | null>;
+  set(projectId: string, state: EditHistoryState): Promise<void>;
+  delete(projectId: string): Promise<void>;
+}
+
+const DB_NAME = "hyperframes-studio-edit-history";
+const DB_VERSION = 1;
+const STORE_NAME = "project-history";
+
+export function createMemoryEditHistoryStorage(): EditHistoryStorageAdapter {
+  const states = new Map<string, EditHistoryState>();
+  return {
+    async get(projectId) {
+      return states.get(projectId) ?? null;
+    },
+    async set(projectId, state) {
+      states.set(projectId, structuredClone(state));
+    },
+    async delete(projectId) {
+      states.delete(projectId);
+    },
+  };
+}
+
+function openEditHistoryDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (!globalThis.indexedDB) {
+      reject(new Error("IndexedDB is not available"));
+      return;
+    }
+
+    const request = globalThis.indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME);
+      }
+    };
+    request.onerror = () => reject(request.error ?? new Error("Failed to open edit history db"));
+    request.onsuccess = () => resolve(request.result);
+  });
+}
+
+function withStore<T>(
+  mode: IDBTransactionMode,
+  callback: (store: IDBObjectStore) => IDBRequest<T>,
+): Promise<T> {
+  return openEditHistoryDb().then(
+    (db) =>
+      new Promise<T>((resolve, reject) => {
+        const tx = db.transaction(STORE_NAME, mode);
+        const request = callback(tx.objectStore(STORE_NAME));
+        request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+        request.onsuccess = () => resolve(request.result);
+        tx.oncomplete = () => db.close();
+        tx.onerror = () => {
+          db.close();
+          reject(tx.error ?? new Error("IndexedDB transaction failed"));
+        };
+      }),
+  );
+}
+
+export function createIndexedDbEditHistoryStorage(): EditHistoryStorageAdapter {
+  return {
+    async get(projectId) {
+      return (
+        (await withStore<EditHistoryState | undefined>("readonly", (store) =>
+          store.get(projectId),
+        )) ?? null
+      );
+    },
+    async set(projectId, state) {
+      await withStore<IDBValidKey>("readwrite", (store) => store.put(state, projectId));
+    },
+    async delete(projectId) {
+      await withStore<undefined>("readwrite", (store) => store.delete(projectId));
+    },
+  };
+}
+
+export async function loadEditHistoryState(
+  storage: EditHistoryStorageAdapter,
+  projectId: string,
+): Promise<EditHistoryState> {
+  const state = await storage.get(projectId);
+  return state ?? createEmptyEditHistory();
+}
+
+export async function saveEditHistoryState(
+  storage: EditHistoryStorageAdapter,
+  projectId: string,
+  state: EditHistoryState,
+): Promise<void> {
+  await storage.set(projectId, state);
+}

package/src/utils/frameCapture.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "./frameCapture";
+
+describe("frame capture utilities", () => {
+  it("builds a PNG capture URL for the master composition", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-04-29T12:00:00Z"));
+
+    expect(
+      buildFrameCaptureUrl({
+        projectId: "demo project",
+        compositionPath: null,
+        currentTime: 1.23456,
+        origin: "http://localhost:5194",
+      }),
+    ).toBe(
+      "http://localhost:5194/api/projects/demo%20project/thumbnail/index.html?t=1.235&format=png&v=1777464000000",
+    );
+
+    vi.useRealTimers();
+  });
+
+  it("builds a safe filename from a nested composition path", () => {
+    expect(buildFrameCaptureFilename("compositions/intro.html", 2.5)).toBe("intro-2-500s.png");
+  });
+});

package/src/utils/frameCapture.ts

@@ -0,0 +1,38 @@
+export interface FrameCaptureRequest {
+  projectId: string;
+  compositionPath: string | null;
+  currentTime: number;
+  origin?: string;
+}
+
+function normalizeCompositionPath(compositionPath: string | null): string {
+  return compositionPath && compositionPath !== "master" ? compositionPath : "index.html";
+}
+
+export function buildFrameCaptureUrl({
+  projectId,
+  compositionPath,
+  currentTime,
+  origin = window.location.origin,
+}: FrameCaptureRequest): string {
+  const compPath = normalizeCompositionPath(compositionPath);
+  const url = new URL(
+    `/api/projects/${encodeURIComponent(projectId)}/thumbnail/${encodeURIComponent(compPath)}`,
+    origin,
+  );
+  url.searchParams.set("t", Math.max(0, currentTime).toFixed(3));
+  url.searchParams.set("format", "png");
+  url.searchParams.set("v", String(Date.now()));
+  return url.toString();
+}
+
+export function buildFrameCaptureFilename(compositionPath: string | null, currentTime: number) {
+  const compPath = normalizeCompositionPath(compositionPath);
+  const base =
+    compPath
+      .split("/")
+      .pop()
+      ?.replace(/\.html$/i, "") || "frame";
+  const frameTime = Math.max(0, currentTime).toFixed(3).replace(".", "-");
+  return `${base}-${frameTime}s.png`;
+}

package/src/utils/studioFileHistory.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it, vi } from "vitest";
+import { saveProjectFilesWithHistory } from "./studioFileHistory";
+
+describe("saveProjectFilesWithHistory", () => {
+  it("reads before content, writes after content, and records a history entry", async () => {
+    const reads: Record<string, string> = { "index.html": "before" };
+    const writes: Record<string, string> = {};
+    const recordEdit = vi.fn();
+
+    await saveProjectFilesWithHistory({
+      projectId: "project-1",
+      label: "Move layer",
+      kind: "manual",
+      files: { "index.html": "after" },
+      readFile: async (path) => reads[path],
+      writeFile: async (path, content) => {
+        writes[path] = content;
+      },
+      recordEdit,
+    });
+
+    expect(writes).toEqual({ "index.html": "after" });
+    expect(recordEdit).toHaveBeenCalledWith({
+      label: "Move layer",
+      kind: "manual",
+      coalesceKey: undefined,
+      files: { "index.html": { before: "before", after: "after" } },
+    });
+  });
+
+  it("skips writes and history for unchanged content", async () => {
+    const writeFile = vi.fn();
+    const recordEdit = vi.fn();
+
+    const changedPaths = await saveProjectFilesWithHistory({
+      projectId: "project-1",
+      label: "Edit layer",
+      kind: "manual",
+      files: { "index.html": "same" },
+      readFile: async () => "same",
+      writeFile,
+      recordEdit,
+    });
+
+    expect(changedPaths).toEqual([]);
+    expect(writeFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+  });
+
+  it("rolls back files already written when a later file write fails", async () => {
+    const reads: Record<string, string> = {
+      "index.html": "index-before",
+      "scene.html": "scene-before",
+    };
+    const writes: Array<[string, string]> = [];
+    const recordEdit = vi.fn();
+
+    await expect(
+      saveProjectFilesWithHistory({
+        projectId: "project-1",
+        label: "Move layer",
+        kind: "manual",
+        files: {
+          "index.html": "index-after",
+          "scene.html": "scene-after",
+        },
+        readFile: async (path) => reads[path],
+        writeFile: async (path, content) => {
+          writes.push([path, content]);
+          if (path === "scene.html") {
+            throw new Error("disk full");
+          }
+        },
+        recordEdit,
+      }),
+    ).rejects.toThrow("disk full");
+
+    expect(writes).toEqual([
+      ["index.html", "index-after"],
+      ["scene.html", "scene-after"],
+      ["index.html", "index-before"],
+    ]);
+    expect(recordEdit).not.toHaveBeenCalled();
+  });
+
+  it("rolls back written files when the injected history recorder throws", async () => {
+    const reads: Record<string, string> = {
+      "index.html": "index-before",
+      "scene.html": "scene-before",
+    };
+    const writes: Array<[string, string]> = [];
+
+    await expect(
+      saveProjectFilesWithHistory({
+        projectId: "project-1",
+        label: "Move layer",
+        kind: "manual",
+        files: {
+          "index.html": "index-after",
+          "scene.html": "scene-after",
+        },
+        readFile: async (path) => reads[path],
+        writeFile: async (path, content) => {
+          writes.push([path, content]);
+        },
+        recordEdit: async () => {
+          throw new Error("history unavailable");
+        },
+      }),
+    ).rejects.toThrow("history unavailable");
+
+    expect(writes).toEqual([
+      ["index.html", "index-after"],
+      ["scene.html", "scene-after"],
+      ["scene.html", "scene-before"],
+      ["index.html", "index-before"],
+    ]);
+  });
+
+  it("reports rollback failure with the original write failure", async () => {
+    const reads: Record<string, string> = {
+      "index.html": "index-before",
+      "scene.html": "scene-before",
+    };
+    const writes: Array<[string, string]> = [];
+
+    await expect(
+      saveProjectFilesWithHistory({
+        projectId: "project-1",
+        label: "Move layer",
+        kind: "manual",
+        files: {
+          "index.html": "index-after",
+          "scene.html": "scene-after",
+        },
+        readFile: async (path) => reads[path],
+        writeFile: async (path, content) => {
+          writes.push([path, content]);
+          if (path === "scene.html" && content === "scene-after") {
+            throw new Error("write denied");
+          }
+          if (path === "index.html" && content === "index-before") {
+            throw new Error("rollback denied");
+          }
+        },
+        recordEdit: vi.fn(),
+      }),
+    ).rejects.toThrow("rollback did not complete");
+
+    expect(writes).toEqual([
+      ["index.html", "index-after"],
+      ["scene.html", "scene-after"],
+      ["index.html", "index-before"],
+    ]);
+  });
+});

package/src/utils/studioFileHistory.ts

@@ -0,0 +1,61 @@
+import type { EditHistoryKind } from "./editHistory";
+
+interface SaveProjectFilesWithHistoryInput {
+  projectId: string;
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, string>;
+  readFile: (path: string) => Promise<string>;
+  writeFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (entry: {
+    label: string;
+    kind: EditHistoryKind;
+    coalesceKey?: string;
+    files: Record<string, { before: string; after: string }>;
+  }) => Promise<void>;
+}
+
+export async function saveProjectFilesWithHistory({
+  label,
+  kind,
+  coalesceKey,
+  files,
+  readFile,
+  writeFile,
+  recordEdit,
+}: SaveProjectFilesWithHistoryInput): Promise<string[]> {
+  const snapshots: Record<string, { before: string; after: string }> = {};
+  for (const [path, after] of Object.entries(files)) {
+    const before = await readFile(path);
+    if (before !== after) {
+      snapshots[path] = { before, after };
+    }
+  }
+
+  const changedPaths = Object.keys(snapshots);
+  if (changedPaths.length === 0) return [];
+
+  const writtenPaths: string[] = [];
+  try {
+    for (const path of changedPaths) {
+      await writeFile(path, snapshots[path].after);
+      writtenPaths.push(path);
+    }
+
+    await recordEdit({ label, kind, coalesceKey, files: snapshots });
+  } catch (error) {
+    try {
+      for (const path of writtenPaths.reverse()) {
+        await writeFile(path, snapshots[path].before);
+      }
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "Failed to save project files and rollback did not complete",
+      );
+    }
+    throw error;
+  }
+  return changedPaths;
+}