@hyperframes/studio 0.8.55 → 0.8.57

package/src/hooks/useSdkSession.ts

@@ -25,6 +25,34 @@ type ProjectFileReadFailure =
 
 type ProjectFileReadResult = { ok: true; content: string } | ProjectFileReadFailure;
 
+/**
+ * Record a read that produced no usable content, and answer which project — if
+ * any — the failure identifies as unreachable.
+ *
+ * No SDK session follows a failed read, so EVERY cutover chokepoint takes the
+ * server path and emits nothing — the shadow never runs either. A broken read
+ * would otherwise be a silent, total SDK bypass, which is why this is recorded
+ * at all.
+ *
+ * Only a 404 identifies the *project*: the server answered, and its answer was
+ * that it does not serve this id. A 5xx, a dropped request, an unexpected body
+ * and an empty file all say nothing about which project the server serves, so
+ * none of them claim it. See `unreachableProject` on the handle.
+ *
+ * A function rather than three more conditions inline: the read callback it is
+ * called from is a long pre-existing async body already near the complexity
+ * threshold, and this branch is one coherent unit.
+ */
+function reportReadFailure(read: ProjectFileReadFailure, projectId: string): string | null {
+  trackStudioEvent("sdk_session_unavailable", {
+    stage: "read",
+    reason: read.reason,
+    ...(read.reason === "http_error" ? { status: read.status } : {}),
+  });
+  if (read.reason !== "http_error") return null;
+  return read.status === 404 ? projectId : null;
+}
+
 /**
  * Read a project file's content (optional read — a missing file is not an
  * error). Replaces the removed SDK http adapter's `read()` — the only thing
@@ -96,6 +124,19 @@ export interface SdkSessionHandle {
    * side of that path is covered by usePersistentEditHistory.test.ts.
    */
   forceReload: () => void;
+  /**
+   * Set when this server answered the composition read with a 404 for the
+   * project it was asked to open. In the CLI-embedded host — the only host
+   * that reports telemetry at all (`telemetry/policy.ts` suppresses Vite dev)
+   * — that does not mean the project is gone. It means this Studio is serving
+   * a *different* one; the project is untouched on disk. Either way every edit
+   * in this tab fails, and until now it failed silently.
+   *
+   * `null` for every other failure: a 500 or a dropped request says nothing
+   * about which project the server serves, and `absent_or_empty` /
+   * `missing_content` say nothing about the project at all.
+   */
+  unreachableProject: string | null;
 }
 
 interface SdkSessionOwner {
@@ -173,6 +214,7 @@ export function useSdkSession(
   const [reloadToken, setReloadToken] = useState(0);
   const reloadTokenRef = useRef(reloadToken);
   reloadTokenRef.current = reloadToken;
+  const [unreachableProject, setUnreachableProject] = useState<string | null>(null);
 
   useEffect(
     () =>
@@ -195,6 +237,7 @@ export function useSdkSession(
     if (previous) disposeSdkSession(previous.session);
 
     if (!projectId || !activeCompPath) {
+      setUnreachableProject(null);
       return () => {
         cancelled = true;
       };
@@ -211,17 +254,10 @@ export function useSdkSession(
       .then(async (read) => {
         if (cancelled) return;
         if (!read.ok) {
-          // No SDK session follows, so EVERY cutover chokepoint below takes the
-          // server path and emits nothing — the shadow never runs either. This
-          // is the only place a missing session can originate, so a broken read
-          // would otherwise be a silent, total SDK bypass.
-          trackStudioEvent("sdk_session_unavailable", {
-            stage: "read",
-            reason: read.reason,
-            ...(read.reason === "http_error" ? { status: read.status } : {}),
-          });
+          setUnreachableProject(reportReadFailure(read, projectId));
           return;
         }
+        setUnreachableProject(null);
         const content = read.content;
         // No persist queue: Studio's writeProjectFile (via sdkCutover's
         // persistSdkSerialize) is the SINGLE writer. Wiring the SDK persist
@@ -316,5 +352,5 @@ export function useSdkSession(
     ownedSession.reloadToken === reloadToken
       ? ownedSession.session
       : null;
-  return { session, publish, forceReload };
+  return { session, publish, forceReload, unreachableProject };
 }

package/src/hooks/useServerConnection.hashProject.test.tsx

@@ -2,8 +2,11 @@
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { trackStudioEvent } from "../utils/studioTelemetry";
 import { useServerConnection } from "./useServerConnection";
 
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 const captured: { projectId: string | null } = { projectId: null };
@@ -55,6 +58,7 @@ describe("useServerConnection hash project id", () => {
 
   afterEach(() => {
     vi.unstubAllGlobals();
+    vi.mocked(trackStudioEvent).mockClear();
   });
 
   it("keeps a hash id the server can resolve", async () => {
@@ -92,3 +96,302 @@ describe("useServerConnection hash project id", () => {
     await act(async () => root.unmount());
   });
 });
+
+/** Per-project status, so one test can hold two projects in different states. */
+function stubFetchByProject(statuses: Record<string, number | "reject">) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      if (url === "/api/projects") {
+        return {
+          ok: true,
+          json: async () => ({ projects: [{ id: "real-project" }] }),
+        } as Response;
+      }
+      const id = decodeURIComponent(url.replace("/api/projects/", ""));
+      const status = statuses[id];
+      if (status === "reject") throw new TypeError("Failed to fetch");
+      if (status === undefined) return { ok: false, status: 404 } as Response;
+      return { ok: status === 200, status } as Response;
+    }),
+  );
+}
+
+async function changeHash(hash: string) {
+  await act(async () => {
+    window.location.hash = hash;
+  });
+  await flush();
+}
+
+/**
+ * Change the hash WITHOUT the test itself pushing or firing anything.
+ *
+ * `location.hash =` does both, which makes "did the CODE push?" unanswerable —
+ * the test's own navigation moves history.length either way. replaceState does
+ * neither, so the dispatch is explicit and any growth after it is the hook's.
+ */
+async function replaceHashAndDispatch(hash: string) {
+  await act(async () => {
+    window.history.replaceState(null, "", hash);
+    window.dispatchEvent(new Event("hashchange"));
+  });
+  await flush();
+}
+
+/**
+ * The hashchange path took any id the URL offered, with no validation — so the
+ * mount fix from v0.8.52 could be walked straight around by changing projects.
+ * These pin the second door shut.
+ */
+describe("useServerConnection hashchange validation", () => {
+  beforeEach(() => {
+    captured.projectId = null;
+    window.location.hash = "";
+    vi.mocked(trackStudioEvent).mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("adopts a hash id the server can resolve", async () => {
+    stubFetchByProject({ first: 200, second: 200 });
+    const root = await renderWithHash("#project/first");
+    expect(captured.projectId).toBe("first");
+
+    await changeHash("#project/second");
+    expect(captured.projectId).toBe("second");
+    await act(async () => root.unmount());
+  });
+
+  it("falls back to the first project when the new hash id is gone", async () => {
+    stubFetchByProject({ first: 200, deleted: 404 });
+    const root = await renderWithHash("#project/first");
+    expect(captured.projectId).toBe("first");
+
+    await changeHash("#project/deleted");
+    expect(captured.projectId).toBe("real-project");
+    expect(window.location.hash).toContain("real-project");
+    await act(async () => root.unmount());
+  });
+
+  it("keeps the new hash id when the check itself fails", async () => {
+    // Same transient-tolerance as the mount path: a blip must not rewrite the
+    // user's hash out from under a project that is actually fine.
+    stubFetchByProject({ first: 200, flaky: "reject" });
+    const root = await renderWithHash("#project/first");
+
+    await changeHash("#project/flaky");
+    expect(captured.projectId).toBe("flaky");
+    await act(async () => root.unmount());
+  });
+
+  it("reports the hashchange verdict with its stage", async () => {
+    stubFetchByProject({ first: 200, deleted: 404 });
+    const root = await renderWithHash("#project/first");
+    vi.mocked(trackStudioEvent).mockClear();
+
+    await changeHash("#project/deleted");
+    const verdicts = vi
+      .mocked(trackStudioEvent)
+      .mock.calls.filter(([name]) => name === "project_hash_validated");
+    expect(verdicts).toEqual([
+      ["project_hash_validated", { stage: "hashchange", outcome: "missing", status: 404 }],
+    ]);
+    await act(async () => root.unmount());
+  });
+
+  it("ignores a verdict that lands after the user moved on", async () => {
+    // Two changes in quick succession. The first check resolves late; if it were
+    // trusted, it would adopt a project the user already navigated away from.
+    let releaseFirst: (() => void) | null = null;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string) => {
+        if (url === "/api/projects") {
+          return {
+            ok: true,
+            json: async () => ({ projects: [{ id: "real-project" }] }),
+          } as Response;
+        }
+        const id = decodeURIComponent(url.replace("/api/projects/", ""));
+        if (id === "slow") {
+          await new Promise<void>((resolve) => {
+            releaseFirst = resolve;
+          });
+          return { ok: true, status: 200 } as Response;
+        }
+        return { ok: true, status: 200 } as Response;
+      }),
+    );
+
+    const root = await renderWithHash("#project/slow");
+    await flush();
+    // Move on before the slow validation answers.
+    await act(async () => {
+      window.location.hash = "#project/fast";
+    });
+    await flush();
+    expect(captured.projectId).toBe("fast");
+
+    // Now let the stale check resolve. It must not win.
+    await act(async () => {
+      releaseFirst?.();
+    });
+    await flush();
+    expect(captured.projectId).toBe("fast");
+    await act(async () => root.unmount());
+  });
+
+  it("falls back to the CURRENT project list, not the one from mount", async () => {
+    // The mount fetch is a snapshot. A long-lived tab is exactly the case this
+    // path exists for, so re-reading the list is the difference between landing
+    // on a project that exists and landing on the one that was first an hour ago.
+    let list = [{ id: "old-first" }];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string) => {
+        if (url === "/api/projects") {
+          return { ok: true, json: async () => ({ projects: list }) } as Response;
+        }
+        const id = decodeURIComponent(url.replace("/api/projects/", ""));
+        return { ok: id !== "deleted", status: id === "deleted" ? 404 : 200 } as Response;
+      }),
+    );
+
+    const root = await renderWithHash("#project/old-first");
+    expect(captured.projectId).toBe("old-first");
+
+    list = [{ id: "new-first" }];
+    await changeHash("#project/deleted");
+    expect(captured.projectId).toBe("new-first");
+    await act(async () => root.unmount());
+  });
+
+  it("re-reads the list on a second dead hash rather than reusing the first answer", async () => {
+    // The caching version is invisible with one dead hash — firstProjectId runs
+    // once, so a memo and a fresh fetch look identical. Two dead hashes with the
+    // list changing in between is what separates them.
+    let list = [{ id: "first-a" }];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string) => {
+        if (url === "/api/projects") {
+          return { ok: true, json: async () => ({ projects: list }) } as Response;
+        }
+        const id = decodeURIComponent(url.replace("/api/projects/", ""));
+        return { ok: id === "alive", status: id === "alive" ? 200 : 404 } as Response;
+      }),
+    );
+
+    const root = await renderWithHash("#project/alive");
+    await changeHash("#project/dead-one");
+    expect(captured.projectId).toBe("first-a");
+
+    list = [{ id: "first-b" }];
+    await changeHash("#project/dead-two");
+    expect(captured.projectId).toBe("first-b");
+    await act(async () => root.unmount());
+  });
+
+  it("rewrites a dead hash without adding a history entry", async () => {
+    // `location.hash =` pushes, which would leave the dead id one Back away —
+    // and Back would then re-validate, fall back and push again, forever.
+    stubFetchByProject({ first: 200, deleted: 404 });
+    const root = await renderWithHash("#project/first");
+
+    const before = window.history.length;
+    await replaceHashAndDispatch("#project/deleted");
+    expect(captured.projectId).toBe("real-project");
+    expect(window.history.length).toBe(before);
+    await act(async () => root.unmount());
+  });
+
+  it("rewrites the mount fallback without adding a history entry", async () => {
+    // The mount path pushed until now — the same bug from the other end: Back
+    // returned to the dead id, which re-validates and pushes again.
+    stubFetchByProject({ deleted: 404 });
+    window.history.replaceState(null, "", "#project/deleted");
+    const before = window.history.length;
+
+    const root = await renderWithHash("#project/deleted");
+    expect(captured.projectId).toBe("real-project");
+    expect(window.history.length).toBe(before);
+    await act(async () => root.unmount());
+  });
+});
+
+/**
+ * The verdict event. Until it existed, a tab that kept its hash because the
+ * check itself failed was indistinguishable in production from one that never
+ * ran the check — different causes, different fixes, one silent bucket.
+ */
+describe("project_hash_validated", () => {
+  // Mount only: assigning window.location.hash is what happy-dom turns into a
+  // hashchange, so the listener reports too. This describe is about the mount
+  // path; the hashchange verdicts have their own.
+  const verdictCalls = () =>
+    vi
+      .mocked(trackStudioEvent)
+      .mock.calls.filter(
+        ([name, props]) =>
+          name === "project_hash_validated" &&
+          (props as { stage?: string } | undefined)?.stage === "mount",
+      );
+
+  beforeEach(() => {
+    captured.projectId = null;
+    window.location.hash = "";
+    vi.mocked(trackStudioEvent).mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("reports an ok verdict with its status", async () => {
+    stubFetch({ status: 200 });
+    const root = await renderWithHash("#project/stale-or-not");
+    expect(verdictCalls()).toEqual([
+      ["project_hash_validated", { stage: "mount", outcome: "ok", status: 200 }],
+    ]);
+    await act(async () => root.unmount());
+  });
+
+  it("reports a missing verdict with the 404", async () => {
+    stubFetch({ status: 404 });
+    const root = await renderWithHash("#project/deleted-project");
+    expect(verdictCalls()).toEqual([
+      ["project_hash_validated", { stage: "mount", outcome: "missing", status: 404 }],
+    ]);
+    await act(async () => root.unmount());
+  });
+
+  it("reports unknown with no status when the check is rejected", async () => {
+    // The point of the event: this case LOOKS like success from outside (the
+    // hash is kept) but is a failed check. Only the verdict says so.
+    stubFetch("reject");
+    const root = await renderWithHash("#project/unreachable-check");
+    expect(verdictCalls()).toEqual([
+      ["project_hash_validated", { stage: "mount", outcome: "unknown" }],
+    ]);
+    await act(async () => root.unmount());
+  });
+
+  it("reports unknown — not missing — for a 5xx", async () => {
+    stubFetch({ status: 500 });
+    const root = await renderWithHash("#project/server-erroring");
+    expect(verdictCalls()).toEqual([
+      ["project_hash_validated", { stage: "mount", outcome: "unknown", status: 500 }],
+    ]);
+    await act(async () => root.unmount());
+  });
+
+  it("emits nothing when there is no hash id to validate", async () => {
+    stubFetch({ status: 200 });
+    const root = await renderWithHash("");
+    expect(verdictCalls()).toEqual([]);
+    await act(async () => root.unmount());
+  });
+});

package/src/hooks/useServerConnection.ts

@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react";
 import { buildProjectHash, parseProjectIdFromHash } from "../utils/projectRouting";
 import { useMountEffect } from "./useMountEffect";
+import { trackStudioEvent } from "../utils/studioTelemetry";
 
 interface ServerConnectionState {
   projectId: string | null;
@@ -28,16 +29,65 @@ interface ServerConnectionState {
  * `/api/projects` list would be wrong twice over: that list omits session ids
  * (which resolve fine) and skips project dirs without an `index.html`.
  */
-async function resolveHashProject(id: string): Promise<"ok" | "missing" | "unknown"> {
+type ProjectHashVerdict = {
+  outcome: "ok" | "missing" | "unknown";
+  /** HTTP status when the server answered; absent on a rejected request. */
+  status?: number;
+};
+
+async function resolveHashProject(id: string): Promise<ProjectHashVerdict> {
   try {
     const res = await fetch(`/api/projects/${encodeURIComponent(id)}`);
-    if (res.ok) return "ok";
-    return res.status === 404 ? "missing" : "unknown";
+    if (res.ok) return { outcome: "ok", status: res.status };
+    return { outcome: res.status === 404 ? "missing" : "unknown", status: res.status };
   } catch {
-    return "unknown";
+    return { outcome: "unknown" };
   }
 }
 
+/**
+ * What the hash validation decided. Without this, a tab that kept a hash
+ * because the check itself failed ("unknown") is indistinguishable from one
+ * that never ran the check — the two have different fixes and, until this
+ * event, no way to tell them apart in production.
+ */
+/**
+ * Rewrite the project hash WITHOUT pushing a history entry.
+ *
+ * `location.hash =` pushes. That leaves the dead id as the previous entry, so
+ * Back returns to it — and now that hashchange validates, Back would re-run the
+ * whole fallback and push again, leaving a trail of dead ids the user cannot
+ * escape with the Back button.
+ */
+function replaceProjectHash(projectId: string): void {
+  window.history.replaceState(null, "", buildProjectHash(projectId));
+}
+
+/**
+ * The first project the server offers, for a hash that resolves to nothing.
+ *
+ * Fetched here rather than cached from mount: the mount fetch is a snapshot,
+ * and the scenario this exists for is exactly the one where the project list
+ * changed underneath a long-lived tab.
+ */
+async function firstProjectId(): Promise<string | null> {
+  try {
+    const res = await fetch("/api/projects");
+    const data = (await res.json()) as { projects?: Array<{ id?: string }> };
+    return data.projects?.[0]?.id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function reportHashVerdict(stage: "mount" | "hashchange", verdict: ProjectHashVerdict): void {
+  trackStudioEvent("project_hash_validated", {
+    stage,
+    outcome: verdict.outcome,
+    ...(verdict.status === undefined ? {} : { status: verdict.status }),
+  });
+}
+
 export function useServerConnection(): ServerConnectionState {
   const [projectId, setProjectId] = useState<string | null>(null);
   const [resolving, setResolving] = useState(true);
@@ -69,11 +119,12 @@ export function useServerConnection(): ServerConnectionState {
           // Telemetry after the read-reason split: 120 http_error/404 reads
           // across 5 users in 24h, ~24 each, never recovering.
           if (hashProjectId) {
-            const state = await resolveHashProject(hashProjectId);
+            const verdict = await resolveHashProject(hashProjectId);
             if (cancelled) return;
+            reportHashVerdict("mount", verdict);
             // "unknown" keeps the old behaviour: a transient failure must not
             // rewrite the user's hash out from under a valid project.
-            if (state !== "missing") {
+            if (verdict.outcome !== "missing") {
               setProjectId(hashProjectId);
               setWaitingForServer(false);
               return;
@@ -83,7 +134,7 @@ export function useServerConnection(): ServerConnectionState {
           if (first) {
             setProjectId(first.id);
             setWaitingForServer(false);
-            window.location.hash = buildProjectHash(first.id);
+            replaceProjectHash(first.id);
           } else {
             scheduleRetry();
           }
@@ -107,7 +158,29 @@ export function useServerConnection(): ServerConnectionState {
   useEffect(() => {
     const onHashChange = () => {
       const next = parseProjectIdFromHash(window.location.hash);
-      if (next && next !== projectId) setProjectId(next);
+      if (!next || next === projectId) return;
+      // Validated, not adopted. The mount path has checked its hash since
+      // v0.8.52; this path took any id the URL offered, so changing projects
+      // re-armed the same dead-tab failure the mount check exists to prevent.
+      void (async () => {
+        const verdict = await resolveHashProject(next);
+        // Ground truth, not a captured flag. This effect re-registers on every
+        // projectId change, so a generation counter in this closure would reset
+        // and an in-flight verdict from the previous registration would read as
+        // current — adopting a project the user has already navigated away from.
+        // The hash itself cannot go stale.
+        if (parseProjectIdFromHash(window.location.hash) !== next) return;
+        reportHashVerdict("hashchange", verdict);
+        if (verdict.outcome !== "missing") {
+          setProjectId(next);
+          return;
+        }
+        const fallbackId = await firstProjectId();
+        if (parseProjectIdFromHash(window.location.hash) !== next) return;
+        if (!fallbackId) return;
+        setProjectId(fallbackId);
+        replaceProjectHash(fallbackId);
+      })();
     };
     window.addEventListener("hashchange", onHashChange);
     return () => window.removeEventListener("hashchange", onHashChange);

package/src/hooks/useTimelineAssetDropOps.test.tsx

@@ -103,7 +103,7 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     expect(usePlayerStore.getState().selectedElementId).toBe("index.html#clip");
   });
 
-  it("measures the insert row against the visible rows, not clips the timeline hides", async () => {
+  it("measures the insert row against every manifest timeline row", async () => {
     const clip = (id: string, track: number): TimelineElement => ({
       id,
       key: id,
@@ -123,7 +123,6 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
       }),
       "</main>",
     ].join("\n");
-    usePlayerStore.getState().setTopLevelIds(new Set(["a", "b"]));
     const writeProjectFile = vi.fn().mockResolvedValue(undefined);
     const getDrop = renderDropHook(source, writeProjectFile, [
       clip("a", 0),
@@ -136,8 +135,8 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     });
 
     const [, written] = writeProjectFile.mock.calls[0] as [string, string];
-    expect(written).toContain('id="b" data-start="0" data-track-index="2"');
-    expect(written).toContain('id="hidden" data-start="0" data-track-index="1"');
+    expect(written).toContain('id="b" data-start="0" data-track-index="3"');
+    expect(written).toContain('id="hidden" data-start="0" data-track-index="2"');
     expect(written).toMatch(/<video id="clip"[^>]*data-track-index="1"/);
   });
 

package/src/hooks/useTimelineAssetDropOps.ts

@@ -25,8 +25,6 @@ import { commitTimelineCompositionInsertion } from "../utils/timelineComposition
 import { extendRootDurationInSource } from "../utils/rootDuration";
 import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 import { selectAndRevealTimelineElement } from "../player/components/timelineDropReveal";
-import { selectTimelineRowElements } from "../player/hooks/useTimelineRowElements";
-import { usePlayerStore } from "../player/store/playerStore";
 
 /** The first uploaded file opens the new track (if asked); the rest land on the lane it landed on. */
 function fileDropPlacement(
@@ -127,10 +125,7 @@ export function useTimelineAssetDropOps({
         const { source: sourceWithRoom, track } = resolveDropTrack({
           source: originalContent,
           // insertRow counts the rows the timeline shows, so plan against those.
-          elements: selectTimelineRowElements(
-            relevantElements,
-            usePlayerStore.getState().topLevelIds,
-          ),
+          elements: relevantElements,
           placement,
           dropped: {
             id: newId,

package/src/hooks/useTimelineEditing.test.tsx

@@ -1561,21 +1561,24 @@ describe("useTimelineEditing: canEdit gate", () => {
     unmount();
   });
 
-  it("resolves toggle-track-hidden against the expanded rows, not the raw timelineElements prop", async () => {
-    // Regression: canEdit must resolve against the expanded rows
-    // (timelineTrackVisibility.ts's own invariant), not the raw
-    // timelineElements prop — proven by making the two disagree below.
+  it("resolves toggle-track-hidden against the store-owned timeline rows", async () => {
+    // The visibility hook reads the single store-owned row source. The editing
+    // guard must receive that same source so a blocked row cannot fall through
+    // to the write path.
     const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
     const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
     usePlayerStore.getState().setElements([clip]);
     const showToast = vi.fn();
     const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const canEdit = vi.fn((element: TimelineElement) =>
+      element.id === "clip" ? { blocked: true as const, reason: "Reserved by an agent" } : true,
+    );
     let hook: ReturnType<typeof useTimelineEditing> | null = null;
     function Harness() {
       hook = useTimelineEditing({
         projectId: "p1",
         activeCompPath: "index.html",
-        timelineElements: [], // deliberately does not contain `clip`
+        timelineElements: [clip],
         showToast,
         writeProjectFile,
         recordEdit: vi.fn(),
@@ -1583,8 +1586,7 @@ describe("useTimelineEditing: canEdit gate", () => {
         previewIframeRef: { current: iframe },
         pendingTimelineEditPathRef: { current: new Set<string>() },
         uploadProjectFiles: vi.fn(),
-        canEdit: (element) =>
-          element.id === "clip" ? { blocked: true, reason: "Reserved by an agent" } : true,
+        canEdit,
       });
       return null;
     }
@@ -1596,6 +1598,7 @@ describe("useTimelineEditing: canEdit gate", () => {
       await flushAsyncWork();
     });
 
+    expect(canEdit).toHaveBeenCalledWith(clip);
     expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
     expect(writeProjectFile).not.toHaveBeenCalled();
     unmount();