@hyperframes/studio 0.6.109 → 0.6.111

package/src/components/storyboard/StoryboardSourceEditor.tsx

@@ -0,0 +1,231 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { marked } from "marked";
+import DOMPurify from "dompurify";
+import { SourceEditor } from "../editor/SourceEditor";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+
+export interface SourceFile {
+  path: string;
+  label: string;
+}
+
+export interface StoryboardSourceEditorProps {
+  files: SourceFile[];
+  /** Called after a successful save so the Board can re-parse the updated file. */
+  onSaved: () => void;
+  /** Surfaces unsaved-edit state so the parent can guard the Board↔Source toggle. */
+  onDirtyChange?: (dirty: boolean) => void;
+}
+
+const DISCARD_PROMPT = "Discard unsaved markdown changes?";
+
+interface EditableFile {
+  content: string;
+  setContent: (next: string) => void;
+  dirty: boolean;
+  loading: boolean;
+  saving: boolean;
+  error: string | null;
+  save: () => void;
+}
+
+/** Load a project file's raw text and track edits + save state via the shared file manager. */
+function useEditableFile(path: string, onSaved: () => void): EditableFile {
+  const { readProjectFile, writeProjectFile } = useFileManagerContext();
+  const [content, setContent] = useState("");
+  const [saved, setSaved] = useState("");
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!path) return;
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    readProjectFile(path)
+      .then((text) => {
+        if (cancelled) return;
+        setContent(text);
+        setSaved(text);
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setError(err instanceof Error ? err.message : "failed to load file");
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [path, readProjectFile]);
+
+  const save = useCallback(() => {
+    if (saving) return; // coalesce a fast double Cmd+S into one PUT
+    setSaving(true);
+    setError(null);
+    writeProjectFile(path, content)
+      .then(() => {
+        setSaved(content);
+        onSaved();
+      })
+      .catch((err: unknown) => setError(err instanceof Error ? err.message : "failed to save"))
+      .finally(() => setSaving(false));
+  }, [writeProjectFile, path, content, onSaved, saving]);
+
+  return { content, setContent, dirty: content !== saved, loading, saving, error, save };
+}
+
+/** Preview links open in a new tab with the `window.opener` back-channel severed. */
+function hardenLinks(node: Element): void {
+  if (node.tagName === "A" && node.hasAttribute("href")) {
+    node.setAttribute("target", "_blank");
+    node.setAttribute("rel", "noopener noreferrer");
+  }
+}
+
+/** Render markdown to sanitized HTML, debounced so we don't re-parse on every keystroke. */
+function useMarkdownPreview(source: string): string {
+  const [debounced, setDebounced] = useState(source);
+  const primed = useRef(false);
+  useEffect(() => {
+    // Paint the first non-empty content immediately (no 200ms blank window after a file
+    // loads), exactly once, then debounce all subsequent keystrokes.
+    if (!primed.current && source !== "") {
+      primed.current = true;
+      setDebounced(source);
+      return;
+    }
+    const id = window.setTimeout(() => setDebounced(source), 200);
+    return () => window.clearTimeout(id);
+  }, [source]);
+  return useMemo(() => {
+    // `{ async: false }` pins the synchronous string return (no Promise union to narrow).
+    const html = marked.parse(debounced, { async: false });
+    // Scope the link-hardening hook to this call; `finally` guarantees removal even if
+    // `sanitize` throws, so the hook can never leak into other DOMPurify consumers.
+    DOMPurify.addHook("afterSanitizeAttributes", hardenLinks);
+    try {
+      return DOMPurify.sanitize(html);
+    } finally {
+      DOMPurify.removeHook("afterSanitizeAttributes");
+    }
+  }, [debounced]);
+}
+
+function isSaveShortcut(event: React.KeyboardEvent): boolean {
+  return (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "s";
+}
+
+// Minimal prose styling for the rendered preview (Tailwind doesn't style raw HTML).
+const PREVIEW_PROSE =
+  "text-sm leading-relaxed text-neutral-300 " +
+  "[&_h1]:mb-2 [&_h1]:mt-5 [&_h1]:text-xl [&_h1]:font-semibold [&_h1]:text-neutral-100 " +
+  "[&_h2]:mb-1.5 [&_h2]:mt-5 [&_h2]:text-base [&_h2]:font-semibold [&_h2]:text-neutral-100 " +
+  "[&_h3]:mt-4 [&_h3]:font-semibold [&_h3]:text-neutral-200 " +
+  "[&_p]:my-2 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:pl-5 [&_ol]:my-2 [&_ol]:list-decimal [&_ol]:pl-5 " +
+  "[&_code]:rounded [&_code]:bg-neutral-800 [&_code]:px-1 [&_code]:text-[0.85em] [&_code]:text-neutral-200 " +
+  "[&_pre]:my-3 [&_pre]:overflow-auto [&_pre]:rounded [&_pre]:bg-neutral-900 [&_pre]:p-3 " +
+  "[&_pre_code]:bg-transparent [&_pre_code]:p-0 " +
+  "[&_hr]:my-4 [&_hr]:border-neutral-800 [&_a]:text-sky-400 [&_strong]:text-neutral-100 " +
+  "[&_img]:my-2 [&_img]:max-w-full [&_img]:h-auto [&_img]:rounded " +
+  "[&_table]:my-3 [&_th]:border [&_th]:border-neutral-800 [&_th]:px-2 [&_th]:py-1 " +
+  "[&_td]:border [&_td]:border-neutral-800 [&_td]:px-2 [&_td]:py-1";
+
+/**
+ * Raw markdown editor + live preview for the storyboard's canonical files
+ * (STORYBOARD.md / SCRIPT.md). Markdown stays the source of truth: saving writes
+ * the file and re-parses the Board. Deliberately raw (not WYSIWYG) so the
+ * structured frame fields can't be mangled; the preview is sanitized before render.
+ */
+// fallow-ignore-next-line complexity
+export function StoryboardSourceEditor({
+  files,
+  onSaved,
+  onDirtyChange,
+}: StoryboardSourceEditorProps) {
+  const [selected, setSelected] = useState(files[0]?.path ?? "");
+  // Reconcile against the current file list so a removed/renamed file can't strand the tab.
+  const activePath = files.some((f) => f.path === selected) ? selected : (files[0]?.path ?? "");
+  const file = useEditableFile(activePath, onSaved);
+  const previewHtml = useMarkdownPreview(file.content);
+
+  // Surface dirty state to the parent (guards the Board↔Source toggle) and warn
+  // on browser-level navigation while there are unsaved edits.
+  useEffect(() => onDirtyChange?.(file.dirty), [onDirtyChange, file.dirty]);
+  useEffect(() => {
+    if (!file.dirty) return;
+    const onBeforeUnload = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      event.returnValue = "";
+    };
+    window.addEventListener("beforeunload", onBeforeUnload);
+    return () => window.removeEventListener("beforeunload", onBeforeUnload);
+  }, [file.dirty]);
+
+  // Switching files discards the in-memory buffer; confirm when there are unsaved edits.
+  const selectFile = (path: string) => {
+    if (path === activePath) return;
+    if (file.dirty && !window.confirm(DISCARD_PROMPT)) return;
+    setSelected(path);
+  };
+
+  return (
+    <div
+      className="flex flex-1 min-h-0 flex-col"
+      onKeyDown={(e) => {
+        if (!isSaveShortcut(e)) return;
+        e.preventDefault();
+        if (file.dirty && !file.saving) file.save();
+      }}
+    >
+      <div className="flex items-center gap-1 border-b border-neutral-800 px-4 py-2">
+        {files.map((f) => (
+          <button
+            key={f.path}
+            type="button"
+            onClick={() => selectFile(f.path)}
+            className={`rounded px-2.5 py-1 text-xs font-medium transition-colors ${
+              activePath === f.path
+                ? "bg-neutral-800 text-neutral-100"
+                : "text-neutral-400 hover:text-neutral-200"
+            }`}
+          >
+            {f.label}
+          </button>
+        ))}
+        <div className="ml-auto flex items-center gap-3">
+          {file.error && <span className="text-xs text-red-400">{file.error}</span>}
+          <span className="text-xs text-neutral-500">
+            {file.saving ? "Saving…" : file.dirty ? "Unsaved changes" : "Saved"}
+          </span>
+          <button
+            type="button"
+            onClick={file.save}
+            disabled={!file.dirty || file.saving}
+            className="rounded bg-emerald-600 px-3 py-1 text-xs font-medium text-white disabled:opacity-40"
+          >
+            Save
+          </button>
+        </div>
+      </div>
+      <div className="flex flex-1 min-h-0">
+        <div className="w-1/2 min-w-0 border-r border-neutral-800">
+          {file.loading ? (
+            <div className="p-4 text-sm text-neutral-500">Loading {activePath}…</div>
+          ) : (
+            <SourceEditor
+              content={file.content}
+              language="markdown"
+              filePath={activePath}
+              onChange={file.setContent}
+            />
+          )}
+        </div>
+        <div className="w-1/2 min-w-0 overflow-auto bg-neutral-950 px-6 py-4">
+          <div className={PREVIEW_PROSE} dangerouslySetInnerHTML={{ __html: previewHtml }} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/storyboard/StoryboardStatusLegend.tsx

@@ -0,0 +1,21 @@
+import { FRAME_STATUS_META, FRAME_STATUS_ORDER } from "./frameStatus";
+
+/**
+ * Explains the frame lifecycle: a frame advances outline → built → animated.
+ * Mirrors the status chips on each tile (shares FRAME_STATUS_META).
+ */
+export function StoryboardStatusLegend() {
+  return (
+    <div className="flex flex-wrap items-center gap-x-5 gap-y-1.5 text-[11px] text-neutral-500">
+      <span className="uppercase tracking-wider text-neutral-600">Status</span>
+      {FRAME_STATUS_ORDER.map((status, i) => (
+        <span key={status} className="flex items-center gap-1.5">
+          {i > 0 && <span className="text-neutral-700">→</span>}
+          <span className={`h-2 w-2 rounded-full ${FRAME_STATUS_META[status].dotClass}`} />
+          <span className="font-medium text-neutral-300">{FRAME_STATUS_META[status].label}</span>
+          <span className="text-neutral-500">— {FRAME_STATUS_META[status].description}</span>
+        </span>
+      ))}
+    </div>
+  );
+}

package/src/components/storyboard/StoryboardView.tsx

@@ -0,0 +1,78 @@
+import type { ReactNode } from "react";
+import { useStoryboard } from "../../hooks/useStoryboard";
+import { StoryboardLoaded } from "./StoryboardLoaded";
+
+export interface StoryboardViewProps {
+  projectId: string;
+  /** Select a composition in the timeline (used by the frame focus "Open in Preview"). */
+  onSelectComposition: (path: string) => void;
+}
+
+/**
+ * Top-level storyboard stage. Replaces the timeline/preview when the view mode
+ * is `storyboard`. Handles the load states here; once a storyboard exists,
+ * {@link StoryboardLoaded} owns the Board ↔ Source experience.
+ */
+// fallow-ignore-next-line complexity
+export function StoryboardView({ projectId, onSelectComposition }: StoryboardViewProps) {
+  const { data, loading, error, reload } = useStoryboard(projectId);
+
+  if (loading) return <StoryboardFrame>{<Message>Loading storyboard…</Message>}</StoryboardFrame>;
+  if (error) {
+    return (
+      <StoryboardFrame>
+        <Message tone="error">Couldn’t load the storyboard: {error}</Message>
+      </StoryboardFrame>
+    );
+  }
+  if (!data) return <StoryboardFrame>{null}</StoryboardFrame>;
+  if (!data.exists) {
+    return (
+      <StoryboardFrame>
+        <EmptyState path={data.path} />
+      </StoryboardFrame>
+    );
+  }
+
+  return (
+    <StoryboardLoaded
+      projectId={projectId}
+      data={data}
+      reload={reload}
+      onSelectComposition={onSelectComposition}
+    />
+  );
+}
+
+function StoryboardFrame({ children }: { children: ReactNode }) {
+  return (
+    <div className="flex-1 min-h-0 overflow-auto bg-neutral-950 text-neutral-200">
+      <div className="mx-auto max-w-[1400px] px-8 py-8">{children}</div>
+    </div>
+  );
+}
+
+function Message({ children, tone = "muted" }: { children: ReactNode; tone?: "muted" | "error" }) {
+  return (
+    <div
+      className={`px-6 py-12 text-center text-sm ${
+        tone === "error" ? "text-red-400" : "text-neutral-500"
+      }`}
+    >
+      {children}
+    </div>
+  );
+}
+
+function EmptyState({ path }: { path: string }) {
+  return (
+    <div className="rounded-lg border border-dashed border-neutral-800 px-6 py-16 text-center">
+      <h2 className="text-base font-semibold text-neutral-300">No storyboard yet</h2>
+      <p className="mx-auto mt-2 max-w-md text-sm text-neutral-500">
+        Add a <code className="rounded bg-neutral-900 px-1 py-0.5 text-neutral-400">{path}</code> at
+        the project root to plan this video frame by frame. Your agent can create and iterate on it
+        for you.
+      </p>
+    </div>
+  );
+}

package/src/components/storyboard/frameStatus.ts

@@ -0,0 +1,36 @@
+import type { FrameStatus } from "@hyperframes/core/storyboard";
+
+/**
+ * Single source of truth for how each frame lifecycle status is presented —
+ * label, tooltip, description, and the chip/dot color classes — so the tile
+ * chip and the legend dot can't drift apart.
+ */
+export const FRAME_STATUS_META: Record<
+  FrameStatus,
+  { label: string; tooltip: string; description: string; chipClass: string; dotClass: string }
+> = {
+  outline: {
+    label: "Outline",
+    tooltip: "Planned in text — no HTML frame built yet.",
+    description: "Planned in text. Story and intent exist; the visual isn’t built.",
+    chipClass: "bg-neutral-800 text-neutral-300",
+    dotClass: "bg-neutral-500",
+  },
+  built: {
+    label: "Built",
+    tooltip: "Static HTML frame built — not animated yet.",
+    description: "The HTML frame exists as a static key moment. Look is locked; motion isn’t.",
+    chipClass: "bg-sky-500/20 text-sky-300",
+    dotClass: "bg-sky-400",
+  },
+  animated: {
+    label: "Animated",
+    tooltip: "Keyframed and animated — plays in the final cut.",
+    description: "Keyframed into motion. This is the file stitched into the final video.",
+    chipClass: "bg-emerald-500/20 text-emerald-300",
+    dotClass: "bg-emerald-400",
+  },
+};
+
+/** The lifecycle order an agent advances each frame through. */
+export const FRAME_STATUS_ORDER: FrameStatus[] = ["outline", "built", "animated"];

package/src/contexts/ViewModeContext.tsx

@@ -0,0 +1,98 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+/**
+ * Top-level Studio view mode.
+ *
+ * `timeline` is the existing NLE/preview stage. `storyboard` replaces that stage
+ * with the storyboard contact sheet. The mode is mirrored to the `?view=` query
+ * param so it survives reloads and — importantly — so an agent can deep-link the
+ * user straight into the storyboard by navigating the tab to `?view=storyboard`.
+ */
+export type StudioViewMode = "timeline" | "storyboard";
+
+const VIEW_QUERY_PARAM = "view";
+
+function readViewModeFromUrl(): StudioViewMode {
+  if (typeof window === "undefined") return "timeline";
+  return new URLSearchParams(window.location.search).get(VIEW_QUERY_PARAM) === "storyboard"
+    ? "storyboard"
+    : "timeline";
+}
+
+function writeViewModeToUrl(mode: StudioViewMode): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (mode === "storyboard") {
+    url.searchParams.set(VIEW_QUERY_PARAM, "storyboard");
+  } else {
+    url.searchParams.delete(VIEW_QUERY_PARAM);
+  }
+  window.history.replaceState(window.history.state, "", url);
+}
+
+export interface ViewModeValue {
+  viewMode: StudioViewMode;
+  setViewMode: (mode: StudioViewMode) => void;
+}
+
+/**
+ * Owns the view-mode state. When `enabled` is false (storyboard flag off) the
+ * mode is pinned to `timeline` and the URL is left untouched, so the feature is
+ * fully inert until the flag is on.
+ */
+export function useViewModeState(enabled: boolean): ViewModeValue {
+  const [viewMode, setMode] = useState<StudioViewMode>(() =>
+    enabled ? readViewModeFromUrl() : "timeline",
+  );
+
+  // Reflect genuine browser back/forward between history entries with a different
+  // `?view=`. Note: our own writes use `replaceState` (below), which does NOT fire
+  // `popstate`, so this listener never sees them — `setViewMode` updates state directly.
+  // An agent deep-links by doing a full navigation to `?view=storyboard` (picked up by
+  // the mount-time read); a scripted `pushState`/`replaceState` to `?view=` would not be
+  // reflected here, by design.
+  useEffect(() => {
+    if (!enabled) return;
+    const onPopState = () => setMode(readViewModeFromUrl());
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, [enabled]);
+
+  const setViewMode = useCallback(
+    (mode: StudioViewMode) => {
+      if (!enabled) return;
+      setMode(mode);
+      writeViewModeToUrl(mode);
+    },
+    [enabled],
+  );
+
+  const effectiveMode = enabled ? viewMode : "timeline";
+  return useMemo(() => ({ viewMode: effectiveMode, setViewMode }), [effectiveMode, setViewMode]);
+}
+
+const ViewModeContext = createContext<ViewModeValue | null>(null);
+
+export function useViewMode(): ViewModeValue {
+  const ctx = useContext(ViewModeContext);
+  if (!ctx) throw new Error("useViewMode must be used within ViewModeProvider");
+  return ctx;
+}
+
+export function ViewModeProvider({
+  value,
+  children,
+}: {
+  value: ViewModeValue;
+  children: ReactNode;
+}) {
+  return <ViewModeContext value={value}>{children}</ViewModeContext>;
+}

package/src/hooks/gsapScriptCommitTypes.ts

@@ -2,8 +2,6 @@ import type { ParsedGsap } from "@hyperframes/core/gsap-parser";
 import type { Composition } from "@hyperframes/sdk";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { EditHistoryKind } from "../utils/editHistory";
-import type { ShadowGsapOp } from "../utils/sdkShadow";
-import type { ShadowKeyframeOp } from "../utils/sdkShadowGsapKeyframe";
 
 export interface MutationResult {
   ok: boolean;
@@ -28,10 +26,6 @@ export interface CommitMutationOptions {
    * (and under distinct keys) run concurrently as before.
    */
   serializeKey?: string;
-  /** Stage 7 Step 3b: typed SDK equivalent of this mutation for value-fidelity shadow. */
-  shadowGsapOp?: ShadowGsapOp;
-  /** Typed SDK equivalent of a keyframe mutation for keyframe value-fidelity shadow (gsap_keyframe). */
-  shadowKeyframeOp?: ShadowKeyframeOp;
 }
 
 export type CommitMutation = (
@@ -70,6 +64,9 @@ export interface GsapScriptCommitsParams {
   onCacheInvalidate: () => void;
   onFileContentChanged?: (path: string, content: string) => void;
   showToast: (message: string, tone?: "error" | "info") => void;
-  /** Stage 7 Step 3b: SDK session for shadow GSAP dispatch (server stays authoritative). */
+  /** Stage 7 §3.5: SDK session for routing GSAP tween ops through addGsapTween/setGsapTween/removeGsapTween. */
   sdkSession?: Composition | null;
+  writeProjectFile?: (path: string, content: string) => Promise<void>;
+  /** Resync the in-memory SDK session after a server-authoritative write. */
+  forceReloadSdkSession?: () => void;
 }

package/src/hooks/sdkSelfWriteRegistry.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import {
+  hashContent,
+  markSelfWrite,
+  isSelfWriteEcho,
+  resetSelfWriteRegistry,
+} from "./sdkSelfWriteRegistry";
+import { shouldReloadOnFileChange } from "./useSdkSession";
+
+describe("sdkSelfWriteRegistry (finding #14)", () => {
+  beforeEach(() => resetSelfWriteRegistry());
+
+  it("recognizes the echo of bytes we just wrote", () => {
+    markSelfWrite("/comp.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>")).toBe(true);
+  });
+
+  it("does NOT match different content on the same path (an undo's reverted bytes)", () => {
+    markSelfWrite("/comp.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/comp.html", "<html>REVERTED</html>")).toBe(false);
+  });
+
+  it("is keyed per file — a self-write to one file can't mask a change to another", () => {
+    markSelfWrite("/a.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/b.html", "<html>A</html>")).toBe(false);
+  });
+
+  it("consumes a matched entry so a later genuine external write isn't suppressed", () => {
+    markSelfWrite("/comp.html", "<html>A</html>");
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>")).toBe(true);
+    // A second arrival of identical bytes is NOT our echo — must reload.
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>")).toBe(false);
+  });
+
+  it("expires entries past the TTL so a stale self-write can't suppress forever", () => {
+    const t0 = 1_000_000;
+    markSelfWrite("/comp.html", "<html>A</html>", t0);
+    // 3 s later (> 2 s TTL) the entry is gone.
+    expect(isSelfWriteEcho("/comp.html", "<html>A</html>", t0 + 3000)).toBe(false);
+  });
+
+  it("hashes are stable and distinguish different content", () => {
+    expect(hashContent("x")).toBe(hashContent("x"));
+    expect(hashContent("x")).not.toBe(hashContent("y"));
+  });
+});
+
+describe("shouldReloadOnFileChange (finding #14)", () => {
+  beforeEach(() => resetSelfWriteRegistry());
+
+  it("suppresses the reload when content matches a registered self-write (cutover echo)", () => {
+    markSelfWrite("/comp.html", "<html>SELF</html>");
+    expect(shouldReloadOnFileChange("/comp.html", "<html>SELF</html>", true)).toBe(false);
+  });
+
+  it("reloads on an undo write even inside the suppress window (content differs)", () => {
+    // The cutover registered SELF; the undo writes REVERTED bytes within the
+    // same 2 s window. Time-only suppression dropped this; identity reloads it.
+    markSelfWrite("/comp.html", "<html>SELF</html>");
+    expect(shouldReloadOnFileChange("/comp.html", "<html>REVERTED</html>", true)).toBe(true);
+  });
+
+  it("falls back to the time window only when content is unavailable", () => {
+    expect(shouldReloadOnFileChange("/comp.html", null, true)).toBe(false);
+    expect(shouldReloadOnFileChange("/comp.html", null, false)).toBe(true);
+  });
+});

package/src/hooks/sdkSelfWriteRegistry.ts

@@ -0,0 +1,77 @@
+/**
+ * Self-write identity registry — discriminates an SDK cutover ECHO from a genuine
+ * external write (notably undo/redo) in the file-change reload-suppression path.
+ *
+ * The old suppression was purely time-based: any file-change within 2 s of the
+ * shared `domEditSaveTimestampRef` was swallowed. But BOTH an SDK cutover
+ * self-write AND an undo write set that same timestamp, so the window could not
+ * tell "the echo of the bytes I just wrote" (suppress) from "the reverted bytes
+ * an undo just wrote" (must reload). An undo that landed inside the window was
+ * silently dropped, leaving the in-memory SDK doc on stale pre-undo content.
+ *
+ * Fix: tag each cutover self-write with the CONTENT it wrote (by hash). A
+ * file-change reload is suppressed only when the new on-disk content matches a
+ * recently-registered self-write hash — i.e. it is provably our own echo. Undo
+ * writes are never registered (they don't flow through persistSdkSerialize), so
+ * their content won't match and the reload always fires. Identity, not a clock.
+ */
+
+const SELF_WRITE_TTL_MS = 2000;
+
+interface SelfWriteEntry {
+  hash: string;
+  at: number;
+}
+
+// Module-scoped: the studio process has a single SDK session lifecycle at a time
+// and persists are funnelled through one persistSdkSerialize. Keyed by file path
+// so a self-write to one file can't mask a real external change to another.
+const registry = new Map<string, SelfWriteEntry[]>();
+
+/**
+ * Stable 32-bit FNV-1a hash of content. Collisions only risk SUPPRESSING a real
+ * reload, and only within the 2 s TTL for the exact same file — negligible, and
+ * strictly safer than the prior time-only window it replaces.
+ */
+export function hashContent(content: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < content.length; i++) {
+    h ^= content.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16);
+}
+
+function prune(entries: SelfWriteEntry[], now: number): SelfWriteEntry[] {
+  return entries.filter((e) => now - e.at < SELF_WRITE_TTL_MS);
+}
+
+/** Record that WE wrote `content` to `path` (an SDK cutover self-write). */
+export function markSelfWrite(path: string, content: string, now: number = Date.now()): void {
+  const next = prune(registry.get(path) ?? [], now);
+  next.push({ hash: hashContent(content), at: now });
+  registry.set(path, next);
+}
+
+/**
+ * True when `content` matches a self-write registered for `path` within the TTL.
+ * Consumes the matched entry so a later genuinely-external write of identical
+ * bytes isn't suppressed forever.
+ */
+export function isSelfWriteEcho(path: string, content: string, now: number = Date.now()): boolean {
+  const entries = prune(registry.get(path) ?? [], now);
+  const hash = hashContent(content);
+  const idx = entries.findIndex((e) => e.hash === hash);
+  if (idx === -1) {
+    registry.set(path, entries);
+    return false;
+  }
+  entries.splice(idx, 1);
+  registry.set(path, entries);
+  return true;
+}
+
+/** Test-only: drop all registered self-writes. */
+export function resetSelfWriteRegistry(): void {
+  registry.clear();
+}

package/src/hooks/timelineEditingHelpers.ts

@@ -97,6 +97,7 @@ export interface PersistTimelineEditInput {
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
+  coalesceKey?: string;
 }
 
 export async function persistTimelineEdit(input: PersistTimelineEditInput): Promise<void> {
@@ -119,6 +120,7 @@ export async function persistTimelineEdit(input: PersistTimelineEditInput): Prom
     projectId: input.projectId,
     label: input.label,
     kind: "timeline",
+    coalesceKey: input.coalesceKey,
     files: { [targetPath]: patchedContent },
     readFile: async () => originalContent,
     writeFile: input.writeProjectFile,