@hyperframes/studio 0.5.4 → 0.6.0-alpha.1

package/src/utils/clipboard.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Window } from "happy-dom";
+import { copyTextToClipboard } from "./clipboard";
+
+function installDocument(execCommand: (command: string) => boolean): void {
+  const window = new Window();
+  Object.assign(window, { SyntaxError });
+  Object.defineProperty(window.document, "execCommand", {
+    configurable: true,
+    value: execCommand,
+  });
+  vi.stubGlobal("document", window.document);
+}
+
+function installNavigator(
+  writeText: (text: string) => Promise<void>,
+  userAgent = "Mozilla/5.0 Chrome/120.0.0.0 Safari/537.36",
+): void {
+  vi.stubGlobal("navigator", {
+    clipboard: { writeText },
+    userAgent,
+  });
+}
+
+describe("copyTextToClipboard", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("uses the synchronous selection copy path first in Safari", async () => {
+    const execCommand = vi.fn((command: string) => command === "copy");
+    const writeText = vi.fn((_text: string) => Promise.resolve());
+
+    installDocument(execCommand);
+    installNavigator(
+      writeText,
+      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15",
+    );
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(true);
+
+    expect(execCommand).toHaveBeenCalledWith("copy");
+    expect(writeText).not.toHaveBeenCalled();
+    expect(document.querySelector("textarea")).toBeNull();
+  });
+
+  it("uses navigator.clipboard first outside Safari", async () => {
+    const execCommand = vi.fn((command: string) => command === "copy");
+    const writeText = vi.fn((_text: string) => Promise.resolve());
+
+    installDocument(execCommand);
+    installNavigator(writeText);
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(true);
+
+    expect(writeText).toHaveBeenCalledWith("copy me");
+    expect(execCommand).not.toHaveBeenCalled();
+  });
+
+  it("falls back to selection copy outside Safari when navigator.clipboard fails", async () => {
+    const execCommand = vi.fn((command: string) => command === "copy");
+    const writeText = vi.fn((_text: string) => Promise.reject(new Error("blocked")));
+
+    installDocument(execCommand);
+    installNavigator(writeText);
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(true);
+
+    expect(writeText).toHaveBeenCalledWith("copy me");
+    expect(execCommand).toHaveBeenCalledWith("copy");
+  });
+
+  it("reports failure when both copy paths fail", async () => {
+    const execCommand = vi.fn(() => false);
+    const writeText = vi.fn((_text: string) => Promise.reject(new Error("blocked")));
+
+    installDocument(execCommand);
+    installNavigator(
+      writeText,
+      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15",
+    );
+
+    await expect(copyTextToClipboard("copy me")).resolves.toBe(false);
+
+    expect(execCommand).toHaveBeenCalledWith("copy");
+    expect(writeText).toHaveBeenCalledWith("copy me");
+    expect(document.querySelector("textarea")).toBeNull();
+  });
+});

package/src/utils/clipboard.ts

@@ -0,0 +1,57 @@
+function copyWithSelection(text: string): boolean {
+  if (typeof document === "undefined" || !document.body || !document.execCommand) {
+    return false;
+  }
+
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "true");
+  textarea.style.position = "fixed";
+  textarea.style.top = "0";
+  textarea.style.left = "0";
+  textarea.style.width = "1px";
+  textarea.style.height = "1px";
+  textarea.style.padding = "0";
+  textarea.style.border = "0";
+  textarea.style.opacity = "0";
+  textarea.style.pointerEvents = "none";
+
+  document.body.appendChild(textarea);
+  textarea.focus({ preventScroll: true });
+  textarea.select();
+  textarea.setSelectionRange(0, text.length);
+
+  try {
+    return document.execCommand("copy");
+  } catch {
+    return false;
+  } finally {
+    document.body.removeChild(textarea);
+  }
+}
+
+function shouldCopyWithSelectionFirst(): boolean {
+  if (typeof navigator === "undefined") return false;
+
+  const userAgent = navigator.userAgent;
+  return /Safari/i.test(userAgent) && !/Chrome|Chromium|CriOS|FxiOS|Edg|OPR/i.test(userAgent);
+}
+
+export async function copyTextToClipboard(text: string): Promise<boolean> {
+  const useSelectionFirst = shouldCopyWithSelectionFirst();
+  if (useSelectionFirst && copyWithSelection(text)) {
+    return true;
+  }
+
+  const clipboard = typeof navigator !== "undefined" ? navigator.clipboard : undefined;
+  if (clipboard?.writeText) {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      // Fall back below when the browser still allows synchronous copy.
+    }
+  }
+
+  return !useSelectionFirst && copyWithSelection(text);
+}

package/src/utils/editHistory.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildEditHistoryEntry,
+  canApplyEditHistoryEntry,
+  createEmptyEditHistory,
+  hashEditHistoryContent,
+  pushEditHistoryEntry,
+  redoEditHistory,
+  undoEditHistory,
+} from "./editHistory";
+
+describe("edit history", () => {
+  it("pushes changed file snapshots onto undo and clears redo", () => {
+    const state = createEmptyEditHistory();
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": {
+          before: '<div style="left: 0px"></div>',
+          after: '<div style="left: 20px"></div>',
+        },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+
+    const withUndo = pushEditHistoryEntry(state, entry);
+    const redoEntry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Redoable edit",
+      files: {
+        "index.html": {
+          before: '<div style="left: 20px"></div>',
+          after: '<div style="left: 40px"></div>',
+        },
+      },
+      now: 200,
+      id: "redo-entry",
+    });
+
+    const next = pushEditHistoryEntry(
+      {
+        ...withUndo,
+        redo: [redoEntry],
+      },
+      {
+        ...entry,
+        id: "entry-2",
+        label: "Resize layer",
+        createdAt: 300,
+      },
+    );
+
+    expect(withUndo.undo).toHaveLength(1);
+    expect(withUndo.redo).toHaveLength(0);
+    expect(next.undo.map((item) => item.label)).toEqual(["Move layer", "Resize layer"]);
+    expect(next.redo).toHaveLength(0);
+  });
+
+  it("undo returns before contents and moves entry to redo", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    const result = undoEditHistory(state, { "index.html": hashEditHistoryContent("after") }, 200);
+
+    expect(result.ok).toBe(true);
+    expect(result.filesToWrite).toEqual({ "index.html": "before" });
+    expect(result.state.undo).toHaveLength(0);
+    expect(result.state.redo.map((item) => item.id)).toEqual(["entry-1"]);
+  });
+
+  it("redo returns after contents and moves entry to undo", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const undone = undoEditHistory(
+      pushEditHistoryEntry(createEmptyEditHistory(), entry),
+      { "index.html": hashEditHistoryContent("after") },
+      200,
+    ).state;
+
+    const result = redoEditHistory(undone, { "index.html": hashEditHistoryContent("before") }, 300);
+
+    expect(result.ok).toBe(true);
+    expect(result.filesToWrite).toEqual({ "index.html": "after" });
+    expect(result.state.undo.map((item) => item.id)).toEqual(["entry-1"]);
+    expect(result.state.redo).toHaveLength(0);
+  });
+
+  it("blocks undo when current content hash does not match the recorded after hash", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move layer",
+      files: {
+        "index.html": { before: "before", after: "after" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const state = pushEditHistoryEntry(createEmptyEditHistory(), entry);
+
+    const result = undoEditHistory(
+      state,
+      { "index.html": hashEditHistoryContent("external") },
+      200,
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toBe("content-mismatch");
+    expect(result.state).toBe(state);
+    expect(result.filesToWrite).toEqual({});
+  });
+
+  it("can validate all files in a multi-file entry before applying", () => {
+    const entry = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Update files",
+      files: {
+        "index.html": { before: "a", after: "b" },
+        "compositions/title.html": { before: "c", after: "d" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+
+    expect(
+      canApplyEditHistoryEntry(entry, "undo", {
+        "index.html": hashEditHistoryContent("b"),
+        "compositions/title.html": hashEditHistoryContent("d"),
+      }),
+    ).toEqual({ ok: true });
+    expect(
+      canApplyEditHistoryEntry(entry, "undo", {
+        "index.html": hashEditHistoryContent("b"),
+        "compositions/title.html": hashEditHistoryContent("external"),
+      }),
+    ).toEqual({ ok: false, reason: "content-mismatch", path: "compositions/title.html" });
+  });
+
+  it("prunes oldest undo entries when the limit is exceeded", () => {
+    let state = createEmptyEditHistory({ maxEntries: 2 });
+    for (let index = 1; index <= 3; index += 1) {
+      state = pushEditHistoryEntry(
+        state,
+        buildEditHistoryEntry({
+          projectId: "project-1",
+          label: `Edit ${index}`,
+          files: {
+            "index.html": { before: `${index - 1}`, after: `${index}` },
+          },
+          now: index,
+          id: `entry-${index}`,
+        }),
+        { maxEntries: 2 },
+      );
+    }
+
+    expect(state.undo.map((entry) => entry.id)).toEqual(["entry-2", "entry-3"]);
+  });
+
+  it("coalesces source editor edits for the same file inside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "a", after: "b" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const second = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "b", after: "c" },
+      },
+      now: 300,
+      id: "entry-2",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].id).toBe("entry-2");
+    expect(state.undo[0].files["index.html"].before).toBe("a");
+    expect(state.undo[0].files["index.html"].after).toBe("c");
+  });
+
+  it("does not coalesce source editor edits outside the coalesce window", () => {
+    const first = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "a", after: "b" },
+      },
+      now: 100,
+      id: "entry-1",
+    });
+    const second = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Edit source",
+      kind: "source",
+      coalesceKey: "source:index.html",
+      files: {
+        "index.html": { before: "b", after: "c" },
+      },
+      now: 5000,
+      id: "entry-2",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), first),
+      second,
+      { coalesceMs: 1000 },
+    );
+
+    expect(state.undo.map((entry) => entry.id)).toEqual(["entry-1", "entry-2"]);
+  });
+});

package/src/utils/editHistory.ts

@@ -0,0 +1,218 @@
+export type EditHistoryKind = "manual" | "motion" | "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());
+  });
+});