@hyperframes/studio 0.5.0-alpha.1 → 0.5.0-alpha.11

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;
+}

package/src/utils/timelineAssetDrop.test.ts

@@ -12,6 +12,8 @@ describe("getTimelineAssetKind", () => {
   it("detects image, video, and audio assets", () => {
     expect(getTimelineAssetKind("assets/photo.png")).toBe("image");
     expect(getTimelineAssetKind("assets/clip.mp4")).toBe("video");
+    expect(getTimelineAssetKind("assets/clip.mov")).toBe("video");
+    expect(getTimelineAssetKind("assets/music.mp3")).toBe("audio");
     expect(getTimelineAssetKind("assets/music.wav")).toBe("audio");
   });
 });
@@ -78,11 +80,69 @@ describe("resolveTimelineAssetSrc", () => {
 });
 
 describe("buildTimelineFileDropPlacements", () => {
-  it("uses the dropped start and stacks multiple files onto successive tracks", () => {
-    expect(buildTimelineFileDropPlacements({ start: 1.5, track: 2 }, 3)).toEqual([
+  it("returns no placements for an empty drop set", () => {
+    expect(buildTimelineFileDropPlacements({ start: 1.5, track: 2 }, [])).toEqual([]);
+  });
+
+  it("uses the dropped start and spaces multiple files by duration on the same track", () => {
+    expect(buildTimelineFileDropPlacements({ start: 1.5, track: 2 }, [1.2, 1.6, 1.1])).toEqual([
+      { start: 1.5, track: 2 },
+      { start: 2.7, track: 2 },
+      { start: 4.3, track: 2 },
+    ]);
+  });
+
+  it("uses fallback spacing when a duration is unavailable", () => {
+    expect(buildTimelineFileDropPlacements({ start: 1.5, track: 2 }, [1.2, 0, 1.1])).toEqual([
       { start: 1.5, track: 2 },
-      { start: 1.5, track: 3 },
-      { start: 1.5, track: 4 },
+      { start: 2.7, track: 2 },
+      { start: 7.7, track: 2 },
+    ]);
+  });
+
+  it("moves the spaced sequence to a clear track when the dropped row is occupied", () => {
+    expect(
+      buildTimelineFileDropPlacements(
+        { start: 1.5, track: 2 },
+        [1.2, 1.6, 1.1],
+        [
+          { start: 0, duration: 8, track: 2 },
+          { start: 0, duration: 4, track: 5 },
+        ],
+      ),
+    ).toEqual([
+      { start: 1.5, track: 6 },
+      { start: 2.7, track: 6 },
+      { start: 4.3, track: 6 },
+    ]);
+  });
+
+  it("keeps a requested track above occupied rows when that track is clear", () => {
+    expect(
+      buildTimelineFileDropPlacements(
+        { start: 1.5, track: 8 },
+        [1.2, 1.6],
+        [
+          { start: 0, duration: 8, track: 2 },
+          { start: 0, duration: 4, track: 5 },
+        ],
+      ),
+    ).toEqual([
+      { start: 1.5, track: 8 },
+      { start: 2.7, track: 8 },
+    ]);
+  });
+
+  it("moves a default-track drop to a clear row when track 0 is occupied at time 0", () => {
+    expect(
+      buildTimelineFileDropPlacements(
+        { start: 0, track: 0 },
+        [1.2, 1.6],
+        [{ start: 0, duration: 8, track: 0 }],
+      ),
+    ).toEqual([
+      { start: 0, track: 1 },
+      { start: 1.2, track: 1 },
     ]);
   });
 });

package/src/utils/timelineAssetDrop.ts

@@ -1,6 +1,7 @@
 import { AUDIO_EXT, IMAGE_EXT, VIDEO_EXT } from "./mediaTypes";
 
 export const TIMELINE_ASSET_MIME = "application/x-hyperframes-asset";
+const FALLBACK_TIMELINE_FILE_DROP_DURATION = 5;
 
 export type TimelineAssetKind = "image" | "video" | "audio";
 
@@ -46,12 +47,33 @@ export function resolveTimelineAssetSrc(targetPath: string, assetPath: string):
 
 export function buildTimelineFileDropPlacements(
   placement: { start: number; track: number },
-  count: number,
+  durations: number[],
+  occupiedClips: Array<{ start: number; duration: number; track: number }> = [],
 ): Array<{ start: number; track: number }> {
-  return Array.from({ length: Math.max(0, count) }, (_, index) => ({
-    start: placement.start,
-    track: placement.track + index,
-  }));
+  let nextStart = Math.round(Math.max(0, placement.start) * 100) / 100;
+  const sequenceStart = nextStart;
+  const resolvedDurations = durations.map((duration) =>
+    Number.isFinite(duration) && duration > 0 ? duration : FALLBACK_TIMELINE_FILE_DROP_DURATION,
+  );
+  const sequenceEnd = resolvedDurations.reduce(
+    (end, duration) => Math.round((end + duration) * 100) / 100,
+    sequenceStart,
+  );
+  const overlapsDropTrack = occupiedClips.some((clip) => {
+    if (clip.track !== placement.track) return false;
+    const clipStart = Math.max(0, clip.start);
+    const clipEnd = clipStart + Math.max(0, clip.duration);
+    return sequenceStart < clipEnd && sequenceEnd > clipStart;
+  });
+  const track = overlapsDropTrack
+    ? Math.max(placement.track, ...occupiedClips.map((clip) => clip.track)) + 1
+    : placement.track;
+
+  return resolvedDurations.map((duration) => {
+    const start = nextStart;
+    nextStart = Math.round((nextStart + duration) * 100) / 100;
+    return { start, track };
+  });
 }
 
 export function resolveTimelineAssetInitialGeometry(source: string): {