@hyperframes/studio 0.8.75 → 0.8.76

package/src/hooks/useClipboard.test.ts

@@ -1,6 +1,12 @@
 // @vitest-environment jsdom
+import { ensureHfIds } from "@hyperframes/parsers";
 import { describe, expect, it } from "vitest";
-import { pasteTimelineClips, resolveFreeTrack, type PlacedClip } from "./useClipboard";
+import {
+  pasteElementHtml,
+  pasteTimelineClips,
+  resolveFreeTrack,
+  type PlacedClip,
+} from "./useClipboard";
 import { extendRootDurationInSource } from "../utils/rootDuration";
 import type { TimelineClipboardClip } from "../utils/clipboardPayload";
 import type { TimelineElement } from "../player";
@@ -8,6 +14,9 @@ import type { TimelineElement } from "../player";
 const ROOT =
   '<div id="claude-paper" data-composition-id="claude-paper" data-start="0" data-duration="10"></div>';
 
+const hfIdsIn = (html: string) =>
+  Array.from(html.matchAll(/data-hf-id=["']([^"']+)/g), (m) => m[1]);
+
 function clip(id: string, start: number, duration: number, track: number): TimelineClipboardClip {
   return {
     html: `<audio id="${id}" src="typenew.mp3" data-start="${start}" data-duration="${duration}" data-track-index="${track}"></audio>`,
@@ -77,7 +86,7 @@ describe("pasteTimelineClips", () => {
     expect(content).toMatch(/data-track-index="133"/);
   });
 
-  it("strips the copied data-hf-id so a fresh one mints on next save", () => {
+  it("gives a pasted clip a fresh data-hf-id, never the copied one", () => {
     const clipWithHfId: TimelineClipboardClip = {
       html: '<audio data-hf-id="hf-75o7" id="sfx-type-0" src="typenew.mp3" data-start="7.8" data-duration="0.57" data-track-index="109"></audio>',
       start: 7.8,
@@ -85,10 +94,44 @@ describe("pasteTimelineClips", () => {
       track: 109,
     };
     const { content } = pasteTimelineClips(ROOT, [clipWithHfId], 40, []);
-    expect(content).not.toContain("data-hf-id");
+    expect(content).not.toContain("hf-75o7");
+    expect(hfIdsIn(content)).toHaveLength(1);
+  });
+
+  it("leaves nothing for the server to stamp, so the file undo recorded is what stays on disk", () => {
+    const stamped = ensureHfIds(
+      ROOT.replace("</div>", `${clip("sfx-1", 1, 2, 0).html}${clip("sfx-2", 3, 2, 0).html}</div>`),
+    );
+    const copies = hfIdsIn(stamped).length;
+    const original = (id: string) => ({
+      ...clip(id, 1, 2, 0),
+      html: stamped.match(new RegExp(`<audio[^>]*id="${id}"[^>]*></audio>`))![0],
+    });
+    const { content } = pasteTimelineClips(stamped, [original("sfx-1"), original("sfx-2")], 11, []);
+    const ids = hfIdsIn(content);
+    expect(ids).toHaveLength(copies + 2);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(hfIdsIn(ensureHfIds(content))).toHaveLength(ids.length);
+  });
+
+  it("remints a nested clip's descendants clear of their originals already in the file", () => {
+    const nested =
+      '<div id="comp-1" data-start="1" data-duration="2" data-track-index="0"><span>a</span><span>b</span></div>';
+    const stamped = ensureHfIds(ROOT.replace("</div>", `${nested}</div>`));
+    const copied = stamped.match(/<div[^>]*id="comp-1"[^>]*>.*?<\/div>/)![0];
+    const { content } = pasteTimelineClips(
+      stamped,
+      [{ html: copied, start: 1, duration: 2, track: 0 }],
+      11,
+      [],
+    );
+    const ids = hfIdsIn(content);
+    expect(ids).toHaveLength(hfIdsIn(stamped).length + 3);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(hfIdsIn(ensureHfIds(content))).toHaveLength(ids.length);
   });
 
-  it("strips a nested descendant's data-hf-id too, not just the root's", () => {
+  it("remints a nested descendant's data-hf-id too, not just the root's", () => {
     // A composition-instance clip's descendants carry their own hf-ids; a
     // clone must remint all of them, not just the root, or the descendants
     // collide with their originals the same way the root would.
@@ -101,7 +144,7 @@ describe("pasteTimelineClips", () => {
     const { content } = pasteTimelineClips(ROOT, [nested], 40, []);
     expect(content).not.toContain("hf-root");
     expect(content).not.toContain("hf-child");
-    expect(content).not.toContain("data-hf-id");
+    expect(hfIdsIn(content)).toHaveLength(2);
   });
 
   it("does not strip text content that happens to contain the data-hf-id string", () => {
@@ -145,7 +188,7 @@ describe("pasteTimelineClips", () => {
     expect(content).toContain(`id="${ids[0]}"`);
   });
 
-  it("strips a single-quoted data-hf-id, not just a double-quoted one", () => {
+  it("remints a single-quoted data-hf-id, not just a double-quoted one", () => {
     const singleQuoted: TimelineClipboardClip = {
       html: '<audio data-hf-id=\'hf-75o7\' id="sfx-type-0" src="typenew.mp3" data-start="7.8" data-duration="0.57" data-track-index="109"></audio>',
       start: 7.8,
@@ -153,10 +196,11 @@ describe("pasteTimelineClips", () => {
       track: 109,
     };
     const { content } = pasteTimelineClips(ROOT, [singleQuoted], 40, []);
-    expect(content).not.toContain("data-hf-id");
+    expect(content).not.toContain("hf-75o7");
+    expect(hfIdsIn(content)).toHaveLength(1);
   });
 
-  it("strips data-hf-id even when an earlier attribute value contains a literal >", () => {
+  it("remints data-hf-id even when an earlier attribute value contains a literal >", () => {
     // A `>` inside title's value would close a bracket-scoped tag regex
     // early, leaving data-hf-id (which comes after it) outside the matched
     // span and unstripped. A real parser doesn't have this failure mode.
@@ -167,7 +211,8 @@ describe("pasteTimelineClips", () => {
       track: 109,
     };
     const { content } = pasteTimelineClips(ROOT, [gtInAttr], 40, []);
-    expect(content).not.toContain("data-hf-id");
+    expect(content).not.toContain("hf-xyz");
+    expect(hfIdsIn(content)).toHaveLength(1);
   });
 
   it("still strips data-hf-id from bare text with no element root", () => {
@@ -182,7 +227,7 @@ describe("pasteTimelineClips", () => {
   });
 
   it("still strips data-hf-id from a tag the HTML parser hoists out of body (e.g. title)", () => {
-    // A <title> never reaches DOMParser's body, so stripHfIds's DOM walk sees
+    // A <title> never reaches DOMParser's body, so remintHfIds's DOM walk sees
     // no root element here -- this exercises the regex fallback, not the walk.
     const hoisted: TimelineClipboardClip = {
       html: '<title data-hf-id="hf-leak">x</title>',
@@ -232,3 +277,17 @@ describe("pasteTimelineClips + extendRootDurationInSource", () => {
     expect(extended).toContain('data-duration="10"');
   });
 });
+
+describe("pasteElementHtml", () => {
+  it("gives a pasted element and its children ids of their own, so an edit to the copy stays on it", () => {
+    const stamped = ensureHfIds(
+      ROOT.replace("</div>", '<p id="title" class="t">Hello <b>there</b></p></div>'),
+    );
+    const copied = stamped.match(/<p[^>]*id="title"[^>]*>.*?<\/p>/)![0];
+    const content = pasteElementHtml(stamped, { html: copied, originSelector: "#title" });
+    const ids = hfIdsIn(content);
+    expect(ids).toHaveLength(hfIdsIn(stamped).length + 2);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(hfIdsIn(ensureHfIds(content))).toHaveLength(ids.length);
+  });
+});

package/src/hooks/useClipboard.ts

@@ -1,4 +1,5 @@
 import { useCallback, useRef } from "react";
+import { EXCLUDED_TAGS, mintHfId, walkCompositionDescendants } from "@hyperframes/parsers/hf-ids";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
@@ -13,7 +14,6 @@ import { collectHtmlIds } from "../utils/studioHelpers";
 import { insertTimelineAssetIntoSource } from "../utils/timelineAssetDrop";
 import { extendRootDurationInSource } from "../utils/rootDuration";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
-import type { EditHistoryKind } from "../utils/editHistory";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { findElementForSelection } from "../components/editor/domEditingElement";
 import { findTimelineElementInIframe, readFileContent } from "./timelineEditingHelpers";
@@ -22,7 +22,6 @@ import { timeRangesOverlap } from "../player/components/timelineCollision";
 
 interface RecordEditInput {
   label: string;
-  kind: EditHistoryKind;
   coalesceKey?: string;
   files: Record<string, { before: string; after: string }>;
 }
@@ -100,10 +99,10 @@ export function resolveFreeTrack(preferred: PlacedClip, taken: readonly PlacedCl
   return maxTrack + 1;
 }
 
-/** Strips data-hf-id from the root and every descendant so a clone re-mints
- *  its own. DOMParser, not a bracket-scoped regex, so a `>` inside an earlier
- *  attribute value or a single-quoted id can't defeat the strip. */
-function stripHfIds(html: string, parser: DOMParser): string {
+/** Gives a clone's root and every descendant a fresh data-hf-id, clear of `taken`. Minted here,
+ *  inside the edit, or the server stamps them on the next preview load, behind undo's back.
+ *  DOMParser, not a regex, so a `>` inside an attribute value can't defeat it. */
+function remintHfIds(html: string, parser: DOMParser, taken: Set<string>): string {
   const root = parser.parseFromString(html, "text/html").body.firstElementChild;
   if (!root) {
     // A tag the HTML parser hoists out of <body> (title/meta/style/base/link)
@@ -112,11 +111,28 @@ function stripHfIds(html: string, parser: DOMParser): string {
     // of these tags today.
     return html.replace(/\sdata-hf-id=("[^"]*"|'[^']*')/g, "");
   }
-  root.querySelectorAll("[data-hf-id]").forEach((el) => el.removeAttribute("data-hf-id"));
-  root.removeAttribute("data-hf-id");
+  const elements = [root];
+  walkCompositionDescendants(root, (el) => elements.push(el));
+  for (const el of elements) {
+    if (EXCLUDED_TAGS.has(el.tagName.toLowerCase())) el.removeAttribute("data-hf-id");
+    else el.setAttribute("data-hf-id", mintHfId(el, taken));
+  }
   return root.outerHTML;
 }
 
+const HF_ID_ATTR_RE = /\bdata-hf-id\s*=\s*["']?([^"'\s>]+)/gi;
+const hfIdsInFile = (content: string) =>
+  new Set(Array.from(content.matchAll(HF_ID_ATTR_RE), (match) => match[1]));
+
+export function pasteElementHtml(
+  content: string,
+  payload: { html: string; originSelector?: string; originSelectorIndex?: number },
+): string {
+  const reminted = remintHfIds(payload.html, new DOMParser(), hfIdsInFile(content));
+  const deduped = deduplicateIds(reminted, collectHtmlIds(content));
+  return insertAsSibling(content, deduped, payload.originSelector, payload.originSelectorIndex);
+}
+
 /** Shared insertion path for paste and duplicate, anchored at the playhead or
  *  the selection's end respectively. Returns the final ids so the caller can
  *  select what it just placed, and the furthest end any clip lands at so the
@@ -138,9 +154,10 @@ export function pasteTimelineClips(
   let result = content;
   let requiredEnd = 0;
   const domParser = new DOMParser();
+  const takenHfIds = hfIdsInFile(content);
   for (const clip of clips) {
-    const stripped = stripHfIds(clip.html, domParser);
-    const deduped = deduplicateIds(stripped, existingIds);
+    const reminted = remintHfIds(clip.html, domParser, takenHfIds);
+    const deduped = deduplicateIds(reminted, existingIds);
     existingIds = existingIds.concat(collectHtmlIds(deduped));
     const newStart = anchorTime + (clip.start - groupMinStart);
     const newTrack = resolveFreeTrack(
@@ -280,13 +297,7 @@ export function useClipboard({
         patchedContent = extendRootDurationInSource(pasted.content, pasted.requiredEnd);
         pastedIds = pasted.ids;
       } else {
-        const deduped = deduplicateIds(payload.html, collectHtmlIds(originalContent));
-        patchedContent = insertAsSibling(
-          originalContent,
-          deduped,
-          payload.originSelector,
-          payload.originSelectorIndex,
-        );
+        patchedContent = pasteElementHtml(originalContent, payload);
       }
 
       const label =
@@ -297,7 +308,6 @@ export function useClipboard({
       await saveProjectFilesWithHistory({
         projectId: pid,
         label,
-        kind: "timeline" as EditHistoryKind,
         files: { [targetPath]: patchedContent },
         readFile: async () => originalContent,
         writeFile: writeProjectFile,
@@ -348,7 +358,6 @@ export function useClipboard({
       await saveProjectFilesWithHistory({
         projectId: pid,
         label: clipLabel("Duplicate", clips.length),
-        kind: "timeline" as EditHistoryKind,
         files: { [targetPath]: patchedContent },
         readFile: async () => originalContent,
         writeFile: writeProjectFile,

package/src/hooks/useDomEditCommits.test.tsx

@@ -340,7 +340,6 @@ describe("useDomEditCommits z-index reorder persistence", () => {
       expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
       expect(rendered.recordEdit).toHaveBeenCalledWith({
         label: "Reorder layers",
-        kind: "manual",
         coalesceKey: "z-reorder:test",
         // Unbounded per-gesture fold window (keys are unique per gesture):
         // the z entry and its mirror/lane counterpart fold across the server

package/src/hooks/useDomEditCommits.ts

@@ -12,7 +12,6 @@ import {
 } from "../utils/studioSaveDiagnostics";
 import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
-import type { EditHistoryKind } from "../utils/editHistory";
 import type { CommitDomEditPatchBatches, PersistDomEditOperations } from "./domEditCommitTypes";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import {
@@ -38,7 +37,6 @@ import { studioWriteHeaders } from "../utils/studioFileVersion";
 import { reseekPreviewRuntime } from "./timelineTrackVisibility";
 interface RecordEditInput {
   label: string;
-  kind: EditHistoryKind;
   coalesceKey?: string;
   coalesceMs?: number;
   files: Record<string, { before: string; after: string }>;
@@ -286,7 +284,6 @@ export function useDomEditCommits({
 
       await editHistory.recordEdit({
         label: options?.label ?? "Edit layer",
-        kind: "manual",
         coalesceKey: options?.coalesceKey,
         coalesceMs: options?.coalesceMs,
         files: { [targetPath]: { before: originalContent, after: finalContent } },
@@ -365,7 +362,6 @@ export function useDomEditCommits({
           if (changed) {
             await editHistory.recordEdit({
               label: options.label,
-              kind: "manual",
               coalesceKey: options.coalesceKey,
               coalesceMs: options.coalesceMs,
               files,

package/src/hooks/useEditHistoryActions.test.tsx

@@ -11,12 +11,15 @@ import { useEditHistoryActions, type EditHistoryHandle } from "./useEditHistoryA
 let root: Root | null = null;
 afterEach(() => act(() => root?.unmount()));
 
-function mount(result: { ok: boolean; reason?: string; label?: string; paths?: string[] }) {
+function mount(result: {
+  ok: boolean;
+  reason?: string;
+  message?: string;
+  label?: string;
+  paths?: string[];
+}) {
   const editHistory = {
-    undo: vi.fn<EditHistoryHandle["undo"]>(async (cb) => {
-      if (result.ok) await cb.writeFile("index.html", "before");
-      return result;
-    }),
+    undo: vi.fn<EditHistoryHandle["undo"]>(async () => result),
     redo: vi.fn<EditHistoryHandle["redo"]>(async () => result),
   };
   const deps = {
@@ -42,34 +45,48 @@ function mount(result: { ok: boolean; reason?: string; label?: string; paths?: s
 }
 
 describe("useEditHistoryActions", () => {
-  it("undo writes through the host writer, resyncs the preview and toasts the label", async () => {
-    const { deps, actions } = mount({ ok: true, label: "Move clip", paths: ["index.html"] });
+  it("undo resyncs the preview and toasts the step as the history names it", async () => {
+    const { deps, actions } = mount({ ok: true, label: "Undid: Move clip", paths: ["index.html"] });
     await act(() => actions.undo());
     expect(deps.waitForPendingDomEditSaves).toHaveBeenCalled();
-    expect(deps.writeProjectFile).toHaveBeenCalledWith("index.html", "before");
     expect(deps.onAfterUndoRedo).toHaveBeenCalled();
     expect(deps.forceReloadSdkSession).toHaveBeenCalled();
     expect(deps.syncHistoryPreviewAfterApply).toHaveBeenCalled();
-    expect(deps.showToast).toHaveBeenCalledWith("Undid Move clip", "info");
+    expect(deps.showToast).toHaveBeenCalledWith("Undid: Move clip", "info");
   });
 
   it("redo reports the redone label and skips the SDK reload for other files", async () => {
-    const { deps, actions } = mount({ ok: true, label: "Split clip", paths: ["other.html"] });
+    const { deps, actions } = mount({
+      ok: true,
+      label: "Redid: Split clip",
+      paths: ["other.html"],
+    });
     await act(() => actions.redo());
     expect(deps.forceReloadSdkSession).not.toHaveBeenCalled();
-    expect(deps.showToast).toHaveBeenCalledWith("Redid Split clip", "info");
+    expect(deps.showToast).toHaveBeenCalledWith("Redid: Split clip", "info");
   });
 
-  it("explains a refused undo when the file changed on disk", async () => {
-    const { deps, actions } = mount({ ok: false, reason: "content-mismatch" });
+  it("names the files that changed since the edit when an undo is refused", async () => {
+    const { deps, actions } = mount({
+      ok: false,
+      reason: "content-mismatch",
+      paths: ["index.html"],
+    });
     await act(() => actions.undo());
     expect(deps.showToast).toHaveBeenCalledWith(
-      "File changed outside Studio. Undo history was not applied.",
+      "Can't undo: index.html changed since that edit.",
       "info",
     );
     expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();
   });
 
+  it("says why when the history could not take the step", async () => {
+    const { deps, actions } = mount({ ok: false, reason: "failed", message: "disk full" });
+    await act(() => actions.undo());
+    expect(deps.showToast).toHaveBeenCalledWith("Undo failed: disk full", "error");
+    expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();
+  });
+
   it("waits for pending saves first and reads the motion file through the optional reader", async () => {
     const { deps, actions } = mount({ ok: true, label: "Move clip", paths: ["index.html"] });
     const order: string[] = [];

package/src/hooks/useEditHistoryActions.ts

@@ -6,6 +6,7 @@ import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordin
 interface HistoryResult {
   ok: boolean;
   reason?: string;
+  message?: string;
   label?: string;
   paths?: string[];
   /** Per-file restored/previous content, used to soft-apply the preview. */
@@ -13,7 +14,6 @@ interface HistoryResult {
 }
 interface HistoryFileCallbacks {
   readFile: (path: string) => Promise<string>;
-  writeFile: (path: string, content: string) => Promise<void>;
   serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
 }
 export interface EditHistoryHandle {
@@ -40,7 +40,7 @@ export interface UseEditHistoryActionsOptions {
   forceReloadSdkSession?: () => void;
 }
 
-/** Applies one persisted file-history step: the single owner of undo/redo over project files. */
+/** Takes one step of the project's history: the single owner of undo/redo over project files. */
 export function useEditHistoryActions({
   editHistory,
   readOptionalProjectFile,
@@ -66,15 +66,21 @@ export function useEditHistoryActions({
 
   const apply = useCallback(
     async (direction: "undo" | "redo") => {
-      const [noun, verb] = direction === "undo" ? ["Undo", "Undid"] : ["Redo", "Redid"];
+      const noun = direction === "undo" ? "Undo" : "Redo";
       await waitForPendingDomEditSaves();
       const result = await editHistory[direction]({
         readFile: readHistoryFile,
-        writeFile: writeProjectFile,
         serialize: serializeHistoryFiles,
       });
       if (!result.ok && result.reason === "content-mismatch") {
-        showToast(`File changed outside Studio. ${noun} history was not applied.`, "info");
+        showToast(
+          `Can't ${direction}: ${result.paths?.join(", ")} changed since that edit.`,
+          "info",
+        );
+        return;
+      }
+      if (!result.ok && result.reason === "failed") {
+        showToast(`${noun} failed: ${result.message}`, "error");
         return;
       }
       if (result.ok && result.label) {
@@ -83,7 +89,7 @@ export function useEditHistoryActions({
           forceReloadSdkSession?.();
         }
         await syncHistoryPreviewAfterApply({ paths: result.paths, files: result.files });
-        showToast(`${verb} ${result.label}`, "info");
+        showToast(result.label, "info");
       }
     },
     [
@@ -92,7 +98,6 @@ export function useEditHistoryActions({
       showToast,
       syncHistoryPreviewAfterApply,
       waitForPendingDomEditSaves,
-      writeProjectFile,
       serializeHistoryFiles,
       onAfterUndoRedo,
       activeCompPath,

package/src/hooks/useEditorSave.ts

@@ -1,6 +1,5 @@
 import { useCallback, useRef } from "react";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
-import type { EditHistoryKind } from "../utils/editHistory";
 import {
   StudioFileConflictError,
   buildStudioSaveFailureProperties,
@@ -12,7 +11,6 @@ const FAILURE_BURST_MS = 5_000;
 
 interface RecordEditInput {
   label: string;
-  kind: EditHistoryKind;
   coalesceKey?: string;
   files: Record<string, { before: string; after: string }>;
 }
@@ -108,7 +106,6 @@ export function useEditorSave({
       const task = saveProjectFilesWithHistory({
         projectId: candidate.projectId,
         label: "Edit source",
-        kind: "source",
         coalesceKey: `source:${candidate.path}`,
         files: { [candidate.path]: candidate.content },
         readFile: readProjectFile,

package/src/hooks/useElementLifecycleOps.ts

@@ -185,7 +185,6 @@ export function useElementLifecycleOps({
         await saveProjectFilesWithHistory({
           projectId: pid,
           label: "Delete element",
-          kind: "timeline",
           files: { [targetPath]: patchedContent },
           readFile: async () => originalContent,
           // remove-element already wrote the removal, so disk holds THAT — not

package/src/hooks/useEnableKeyframes.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 import { act, createElement, useRef } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
@@ -400,6 +400,10 @@ function stubFlatTweenConversion(id: string): {
 }
 
 describe("useEnableKeyframes — flat tween transaction", () => {
+  beforeEach(() => {
+    usePlayerStore.setState({ timelineProjectId: "test-project", previewBooted: true });
+  });
+
   it("skips the convert reload and coalesces an outside-range terminal soft reload", async () => {
     window.location.hash = "#/project/test-project";
     usePlayerStore.setState({ currentTime: 3 });
@@ -468,6 +472,10 @@ describe("useEnableKeyframes — flat tween transaction", () => {
 });
 
 describe("useEnableKeyframes — new tween on a class-only element", () => {
+  beforeEach(() => {
+    usePlayerStore.setState({ timelineProjectId: "test-project", previewBooted: true });
+  });
+
   it("targets the selected sibling alone, not every element sharing its class", async () => {
     window.location.hash = "#/project/test-project";
     usePlayerStore.setState({ currentTime: 1 });

package/src/hooks/useFileManager.ts

@@ -2,7 +2,6 @@ import { useState, useCallback, useRef } from "react";
 import type { EditingFile } from "../utils/studioHelpers";
 import { FONT_EXT, isMediaFile } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
-import type { EditHistoryKind } from "../utils/editHistory";
 import { findTagByTarget, type PatchTarget } from "../utils/sourcePatcher";
 import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
 import { useFileTree } from "./useFileTree";
@@ -13,7 +12,6 @@ import { useProjectFileWriter } from "./useProjectFileWriter";
 
 interface RecordEditInput {
   label: string;
-  kind: EditHistoryKind;
   coalesceKey?: string;
   files: Record<string, { before: string; after: string }>;
 }

package/src/hooks/useGroupCommits.ts

@@ -146,7 +146,6 @@ async function commitStructuralMutation(
   await saveProjectFilesWithHistory({
     projectId: pid,
     label,
-    kind: "manual",
     files: { [targetPath]: patchedContent },
     readFile: async () => originalContent,
     writeFile: deps.writeProjectFile,

package/src/hooks/useGsapScriptCommits.ts

@@ -326,7 +326,6 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     if (result.before == null || result.after == null) return;
     await editHistory.recordEdit({
       label: options.label,
-      kind: "manual",
       coalesceKey: options.coalesceKey,
       coalesceMs: options.coalesceMs,
       files: { [targetPath]: { before: result.before, after: result.after } },

package/src/hooks/useLintModal.test.tsx

@@ -2,8 +2,9 @@
 
 import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useLintModal } from "./useLintModal";
+import { usePlayerStore } from "../player/store/playerStore";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -15,6 +16,10 @@ function Probe() {
   return null;
 }
 
+beforeEach(() => {
+  usePlayerStore.setState({ timelineProjectId: "demo", previewBooted: true });
+});
+
 afterEach(() => {
   if (root) act(() => root?.unmount());
   root = null;
@@ -63,3 +68,31 @@ describe("useLintModal hasLintError", () => {
     expect(latest?.hasLintError).toBe(true);
   });
 });
+
+describe("useLintModal background lint", () => {
+  it("waits for the live preview to boot before asking the server to lint", async () => {
+    usePlayerStore.setState({ previewBooted: false });
+    const fetchStub = vi.fn(lintResponse([]));
+    vi.stubGlobal("fetch", fetchStub);
+    root = createRoot(document.createElement("div"));
+    await act(async () => root?.render(<Probe />));
+    expect(fetchStub).not.toHaveBeenCalled();
+
+    await act(async () => usePlayerStore.getState().markPreviewBooted());
+    expect(fetchStub).toHaveBeenCalledTimes(1);
+  });
+
+  it("never lints a project the user left before its preview booted", async () => {
+    usePlayerStore.setState({ previewBooted: false });
+    const fetchStub = vi.fn(lintResponse([]));
+    vi.stubGlobal("fetch", fetchStub);
+    root = createRoot(document.createElement("div"));
+    await act(async () => root?.render(<Probe />));
+
+    await act(async () => {
+      usePlayerStore.getState().beginTimelineSession("another-project");
+      usePlayerStore.getState().markPreviewBooted();
+    });
+    expect(fetchStub).not.toHaveBeenCalled();
+  });
+});