@hyperframes/studio 0.8.60 → 0.8.62

package/src/player/lib/timelineDOM.test.ts

@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
+import { gsap } from "gsap";
 import {
   createTimelineElementFromManifestClip,
   parseTimelineFromDOM,
@@ -20,6 +21,33 @@ function makeDoc(html: string): Document {
 }
 
 describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
+  it("bridges a real GSAP transition marker onto both named clips", () => {
+    document.body.innerHTML = `
+      <div data-composition-id="root">
+        <img data-hf-id="outgoing" data-start="0" data-duration="2.5" data-track-index="0" />
+        <img data-hf-id="incoming" data-start="2" data-duration="2.5" data-track-index="0" />
+      </div>
+    `;
+    const timeline = gsap.timeline({ paused: true });
+    timeline.addLabel("hf:transition:outgoing:incoming:crossfade", 2);
+    const runtimeWindow = window as Window & {
+      __timelines?: Record<string, typeof timeline>;
+    };
+    runtimeWindow.__timelines = { main: timeline };
+
+    try {
+      const elements = parseTimelineFromDOM(document, 5);
+      expect(elements.map((element) => element.transitionLabel)).toEqual([
+        "hf:transition:outgoing:incoming:crossfade",
+        "hf:transition:outgoing:incoming:crossfade",
+      ]);
+    } finally {
+      delete runtimeWindow.__timelines;
+      timeline.kill();
+      document.body.innerHTML = "";
+    }
+  });
+
   it("harvests hfId from a data-start element that has data-hf-id", () => {
     const doc = makeDoc(`
       <div data-composition-id="root">

package/src/player/lib/timelineDOM.ts

@@ -9,10 +9,11 @@
  */
 
 import type { TimelineElement } from "../store/playerStore";
-import type { ClipManifestClip } from "./playbackTypes";
+import type { ClipManifestClip, IframeWindow, TimelineLike } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
 import { groupInfoFor } from "./timelineGroupInfo";
+import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -75,6 +76,9 @@ export function createTimelineElementFromManifestClip(params: {
 }): TimelineElement {
   const { clip, fallbackIndex, doc } = params;
   let hostEl = params.hostEl ?? null;
+  const transitionLabels = doc
+    ? transitionLabelsForDocument(doc, (doc.defaultView as IframeWindow | null)?.__timelines)
+    : new Map<Element, string>();
   const label = getTimelineElementDisplayLabel({
     id: clip.id,
     label: clip.label,
@@ -108,6 +112,10 @@ export function createTimelineElementFromManifestClip(params: {
   const entry: TimelineElement = {
     id: identity.id,
     label,
+    transitionLabel:
+      (hostEl && transitionLabels.get(hostEl)) ||
+      hostEl?.getAttribute("data-transition-label") ||
+      undefined,
     key: identity.key,
     kind: clip.kind,
     tag: resolveClipTag(clip),
@@ -134,6 +142,10 @@ export function createTimelineElementFromManifestClip(params: {
 
   if (hostEl) {
     applyMediaMetadataFromElement(entry, hostEl);
+    if (!entry.src) {
+      const rawSrc = hostEl.getAttribute("src");
+      if (rawSrc) entry.src = new URL(rawSrc, hostEl.baseURI).href;
+    }
     if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;
     const timelineRole = hostEl.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
@@ -205,11 +217,19 @@ export function createTimelineElementFromManifestClip(params: {
  * Parse [data-start] elements from a Document into TimelineElement[].
  * Shared helper — used by onIframeLoad fallback, handleMessage, and enrichMissingCompositions.
  */
-export function parseTimelineFromDOM(doc: Document, rootDuration: number): TimelineElement[] {
+export function parseTimelineFromDOM(
+  doc: Document,
+  rootDuration: number,
+  timelines?: Readonly<Record<string, TimelineLike>>,
+): TimelineElement[] {
   const rootComp = doc.querySelector("[data-composition-id]");
   const nodes = doc.querySelectorAll("[data-start]");
   const els: TimelineElement[] = [];
   let trackCounter = 0;
+  const transitionLabels = transitionLabelsForDocument(
+    doc,
+    timelines ?? (doc.defaultView as IframeWindow | null)?.__timelines,
+  );
 
   // fallow-ignore-next-line complexity
   nodes.forEach((node) => {
@@ -252,6 +272,8 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     const entry: TimelineElement = {
       id: identity.id,
       label,
+      transitionLabel:
+        transitionLabels.get(el) ?? el.getAttribute("data-transition-label") ?? undefined,
       key: identity.key,
       kind:
         compId && compId !== rootComp?.getAttribute("data-composition-id")

package/src/player/lib/timelineIframeHelpers.ts

@@ -22,6 +22,7 @@ import {
   readTimelineElementZIndex,
 } from "./timelineElementHelpers";
 import { postRuntimeControlMessage } from "./runtimeProtocol";
+import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
 
 // ---------------------------------------------------------------------------
 // Viewport / DOM normalisation
@@ -414,6 +415,7 @@ function buildMissingCompositionEntry(params: {
 }): TimelineElement | null {
   const { doc, iframeWin, element, compositionId, rootDuration, fallbackIndex, resolveEnd } =
     params;
+  const transitionLabels = transitionLabelsForDocument(doc, iframeWin.__timelines);
   const timing = readClipTiming(element, {
     resolveReferenceEnd: (refId) => resolveEnd(refId, new Set([compositionId])),
   });
@@ -447,6 +449,8 @@ function buildMissingCompositionEntry(params: {
   const entry: TimelineElement = {
     id: identity.id,
     label,
+    transitionLabel:
+      transitionLabels.get(element) ?? element.getAttribute("data-transition-label") ?? undefined,
     key: identity.key,
     tag: element.tagName.toLowerCase(),
     start: window.start,
@@ -459,6 +463,9 @@ function buildMissingCompositionEntry(params: {
     selectorIndex,
     sourceFile,
     zIndex: readTimelineElementZIndex(element),
+    src: optionalNonEmpty(element.getAttribute("src"))
+      ? new URL(element.getAttribute("src")!, element.baseURI).href
+      : undefined,
   };
   return attachCompositionSource(entry, element, compositionSrc);
 }

package/src/player/lib/timelineTransitionMetadata.ts

@@ -0,0 +1,52 @@
+import type { TimelineLike } from "./playbackTypes";
+
+const TRANSITION_LABEL_PREFIX = "hf:transition:";
+
+type TimelineWithLabels = TimelineLike & {
+  labels?: Record<string, number>;
+  getLabels?: () => Record<string, number>;
+};
+
+function transitionParts(label: string): [string, string] | null {
+  if (!label.startsWith(TRANSITION_LABEL_PREFIX)) return null;
+  const parts = label.slice(TRANSITION_LABEL_PREFIX.length).split(":");
+  if (parts.length < 3 || !parts[0] || !parts[1]) return null;
+  return [parts[0], parts[1]];
+}
+
+function findTimedElement(doc: Document, markerId: string): Element | null {
+  for (const candidate of [markerId, `el-${markerId}`]) {
+    const byId = doc.getElementById(candidate);
+    if (byId?.hasAttribute("data-start")) return byId;
+  }
+  return (
+    Array.from(doc.querySelectorAll("[data-start]")).find(
+      (element) =>
+        element.getAttribute("data-hf-id") === markerId ||
+        element.getAttribute("data-composition-id") === markerId,
+    ) ?? null
+  );
+}
+
+export function transitionLabelsForDocument(
+  doc: Document,
+  timelines: Readonly<Record<string, TimelineLike>> | undefined,
+): ReadonlyMap<Element, string> {
+  const labels = new Map<Element, string>();
+  if (!timelines) return labels;
+
+  for (const timeline of Object.values(timelines) as TimelineWithLabels[]) {
+    const timelineLabels = timeline.getLabels?.() ?? timeline.labels ?? {};
+    for (const label of Object.keys(timelineLabels)) {
+      const pair = transitionParts(label);
+      if (!pair) continue;
+      const outgoing = findTimedElement(doc, pair[0]);
+      const incoming = findTimedElement(doc, pair[1]);
+      if (outgoing && incoming) {
+        labels.set(outgoing, label);
+        labels.set(incoming, label);
+      }
+    }
+  }
+  return labels;
+}

package/src/player/lib/timelineViewportBudgets.ts

@@ -49,6 +49,7 @@ export interface TimelineViewportBudgets {
 
 const MEBIBYTE = 1024 * 1024;
 const DAY_MS = 24 * 60 * 60 * 1000;
+export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); // 4K timeline width / tallest 16:9 tile.
 
 /**
  * The sole default budget owner for timeline viewport and media virtualization.
@@ -66,7 +67,7 @@ export const TIMELINE_VIEWPORT_BUDGETS: Readonly<TimelineViewportBudgets> = Obje
   posterMaxPhysicalWidth: 240,
   posterMaxPhysicalHeight: 135,
   posterDprCap: 1.5,
-  richPreviewFrameCount: 6,
+  richPreviewFrameCount: MAX_VISIBLE_THUMBNAIL_FRAMES,
   concurrentVideoDecodes: 2,
   concurrentMetadataJobs: 4,
   concurrentCompositionFetches: 2,

package/src/player/store/timelineElement.ts

@@ -12,6 +12,7 @@ import type { ClipManifestClip } from "../lib/playbackTypes";
 export interface TimelineElement {
   id: string;
   label?: string;
+  transitionLabel?: string;
   key?: string;
   kind?: ClipManifestClip["kind"];
   tag: string;

package/src/styles/hex-baseline.json

@@ -1,5 +1,5 @@
 {
-  "total": 302,
+  "total": 297,
   "files": {
     "packages/studio/src/captions/components/CaptionOverlay.tsx": 5,
     "packages/studio/src/captions/components/CaptionTimeline.tsx": 11,
@@ -49,7 +49,7 @@
     "packages/studio/src/components/sidebar/AudioRow.tsx": 2,
     "packages/studio/src/components/ui/HyperframesMark.tsx": 4,
     "packages/studio/src/hooks/useInlineTextEdit.ts": 1,
-    "packages/studio/src/player/components/AudioWaveform.tsx": 1,
+    "packages/studio/src/player/components/AudioWaveform.tsx": 2,
     "packages/studio/src/player/components/BeatStrip.tsx": 6,
     "packages/studio/src/player/components/CompositionThumbnail.tsx": 2,
     "packages/studio/src/player/components/Player.tsx": 2,
@@ -58,7 +58,7 @@
     "packages/studio/src/player/components/SpeedMenu.tsx": 2,
     "packages/studio/src/player/components/trackHeaderLabelRows.tsx": 6,
     "packages/studio/src/telemetry/client.ts": 1,
-    "packages/studio/src/webmcp/webmcpTestUtils.ts": 1,
-    "packages/studio/src/styles/studio.css": 48
+    "packages/studio/src/styles/studio.css": 48,
+    "packages/studio/src/webmcp/webmcpTestUtils.ts": 1
   }
 }

package/src/styles/studio.css

@@ -208,6 +208,72 @@ body {
     var(--timeline-clip-shadow);
 }
 
+.timeline-transition {
+  position: absolute;
+  width: 0;
+  height: 0;
+  pointer-events: none;
+  z-index: 30;
+}
+
+.timeline-transition__zone {
+  position: absolute;
+  left: calc(var(--timeline-transition-zone-width) / -2);
+  top: -21px;
+  width: var(--timeline-transition-zone-width);
+  height: 42px;
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--timeline-transition-zone);
+  filter: blur(2.5px);
+  opacity: 0.95;
+}
+
+.timeline-transition__image {
+  position: absolute;
+  inset: -4px;
+  background-position: center;
+  background-size: cover;
+}
+
+.timeline-transition__image--out {
+  mask-image: linear-gradient(90deg, black 0%, transparent 100%);
+}
+
+.timeline-transition__image--in {
+  mask-image: linear-gradient(90deg, transparent 0%, black 100%);
+}
+
+.timeline-transition__badge {
+  position: absolute;
+  left: -14px;
+  top: -14px;
+  display: grid;
+  width: 28px;
+  height: 28px;
+  place-items: center;
+  border: 1px solid color-mix(in srgb, var(--timeline-transition-badge-ink) 22%, transparent);
+  border-radius: 999px;
+  background: var(--timeline-transition-badge);
+  box-shadow: 0 2px 5px var(--timeline-playhead-shadow);
+}
+
+.timeline-transition__badge svg {
+  width: 17px;
+  height: 17px;
+}
+.timeline-transition__frame,
+.timeline-transition__frame--out,
+.timeline-transition__frame--in {
+  fill: none;
+  stroke: var(--timeline-transition-badge-ink);
+  stroke-width: 1.5;
+}
+.timeline-transition__intersection {
+  fill: var(--timeline-transition-badge-ink);
+  opacity: 0.7;
+}
+
 .timeline-clip::before {
   content: "";
   position: absolute;
@@ -245,6 +311,24 @@ body {
     0 8px 24px var(--timeline-clip-shadow-dragging);
 }
 
+/* Mute greys the pill in place. Hot path: no transition. */
+.timeline-clip.is-audio[data-clip-hidden="true"],
+.timeline-clip.is-audio[data-audio-muted="true"] {
+  background-color: var(--timeline-clip-audio-muted-bg);
+  transition: none;
+}
+
+.timeline-audio-link {
+  position: absolute;
+  z-index: 4;
+  top: -9px;
+  left: 50%;
+  width: 1px;
+  height: 10px;
+  background: var(--timeline-audio-link);
+  pointer-events: none;
+}
+
 .timeline-clip.is-hovered {
   background-color: var(--clip-bg-hover);
 }

package/src/styles/theme.css

@@ -68,6 +68,8 @@
   --timeline-clip-audio-border: rgba(167, 139, 250, 0.4);
   --timeline-clip-audio-bg-hover: rgba(167, 139, 250, 0.24);
   --timeline-clip-audio-bg-dragging: rgba(60, 52, 84, 0.96);
+  --timeline-clip-audio-muted-bg: rgb(72, 74, 78);
+  --timeline-audio-link: #a0aaa4;
   --timeline-clip-selection: rgba(255, 255, 255, 0.85);
   --timeline-clip-selection-highlight: rgb(255 255 255 / 0.55);
   --timeline-clip-radius: 8px;
@@ -91,10 +93,12 @@
     transparent 100%
   );
   --timeline-thumbnail-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
-  --timeline-waveform-bar-rgb: 75, 163, 210;
+  --timeline-waveform-bar-rgb: 245, 237, 255;
+  --timeline-waveform-muted-rgb: 236, 238, 242;
+  --timeline-waveform-baseline-rgb: 226, 216, 238;
   --timeline-waveform-error: repeating-linear-gradient(
     90deg,
-    rgba(75, 163, 210, 0.35) 0 2px,
+    rgba(245, 237, 255, 0.35) 0 2px,
     transparent 2px 5px
   );
   --timeline-waveform-label-shadow: 0 1px 3px rgba(0, 0, 0, 0.9);
@@ -148,6 +152,9 @@
   --timeline-clip-shadow-dragging: rgba(0, 0, 0, 0.4);
   --timeline-playhead-glow: rgba(60, 230, 172, 0.14);
   --timeline-playhead-shadow: rgba(0, 0, 0, 0.55);
+  --timeline-transition-zone: rgba(255, 255, 255, 0.2);
+  --timeline-transition-badge: rgba(237, 244, 239, 0.98);
+  --timeline-transition-badge-ink: rgba(36, 56, 45, 0.96);
 
   /* -------------------------------------------------------------- geometry */
 
@@ -361,6 +368,7 @@
   --timeline-audio-link: #626d66;
   --timeline-waveform-bar-rgb: 20, 12, 32;
   --timeline-waveform-muted-rgb: 24, 28, 26;
+  --timeline-waveform-baseline-rgb: 76, 62, 88;
   --timeline-waveform-error: repeating-linear-gradient(
     90deg,
     rgba(20, 12, 32, 0.35) 0 2px,

package/src/utils/sdkCutover.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   shouldUseSdkCutover,
   sdkCutoverPersist,
@@ -14,6 +14,7 @@ import {
 import { openComposition } from "@hyperframes/sdk";
 import { createMemoryAdapter } from "@hyperframes/sdk/adapters/memory";
 import type { PatchOperation } from "./sourcePatcher";
+import { StudioSaveNetworkError } from "./studioSaveDiagnostics";
 
 vi.mock("../components/editor/manualEditingAvailability", () => ({
   STUDIO_SDK_CUTOVER_ENABLED: true,
@@ -1404,3 +1405,103 @@ gsap.timeline().to('[data-hf-id="hf-layer"]', { duration: 1, x: 100 });
     expect(written).toContain("gsap.timeline()");
   });
 });
+
+describe("sdk_cutover_failed classification (error_kind)", () => {
+  const makeDeps = (overrides: Partial<Parameters<typeof sdkCutoverPersist>[5]> = {}) => ({
+    editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+    writeProjectFile: vi.fn().mockResolvedValue(undefined),
+    reloadPreview: vi.fn(),
+    ...candidateTestDeps(),
+    ...overrides,
+  });
+
+  const makeSession = () =>
+    ({
+      getElement: vi.fn().mockReturnValue({ inlineStyles: {} }),
+      dispatch: vi.fn(),
+      serialize: vi
+        .fn()
+        .mockReturnValueOnce("<html>before</html>")
+        .mockReturnValue("<html></html>"),
+      batch: vi.fn((fn: () => void) => fn()),
+    }) as unknown as Parameters<typeof sdkCutoverPersist>[4];
+
+  beforeEach(() => {
+    vi.mocked(trackStudioEvent).mockClear();
+  });
+
+  // The production gate event this fix exists for: a bare `TypeError` from an
+  // UNWRAPPED raw fetch (`readProjectFile`'s implementation in
+  // useProjectFileWriter.ts, or writeProjectFile's own preflight — neither
+  // wraps as StudioSaveNetworkError). Without the message-based fallback in
+  // `cutoverErrorKind`, this files as `error_kind: "sdk"` and trips the
+  // cutover-failure rollback gate on a network blip the SDK never owned.
+  it("classifies a bare fetch TypeError from readProjectFile as network", async () => {
+    const deps = makeDeps({
+      readProjectFile: vi.fn().mockRejectedValue(new TypeError("Failed to fetch")),
+    });
+    const session = makeSession();
+    const sel = { hfId: "hf-abc" } as never;
+
+    const result = await sdkCutoverPersist(
+      sel,
+      [styleOp("color", "red")],
+      "before",
+      "/path.html",
+      session,
+      deps,
+    );
+
+    expect(result.status).toBe("failed");
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "sdk_cutover_failed",
+      expect.objectContaining({ family: "dom", error_kind: "network" }),
+    );
+  });
+
+  it("classifies StudioSaveNetworkError from writeProjectFile as network", async () => {
+    const deps = makeDeps({
+      writeProjectFile: vi.fn().mockRejectedValue(new StudioSaveNetworkError("Failed to save")),
+    });
+    const session = makeSession();
+    const sel = { hfId: "hf-abc" } as never;
+
+    const result = await sdkCutoverPersist(
+      sel,
+      [styleOp("color", "red")],
+      "before",
+      "/path.html",
+      session,
+      deps,
+    );
+
+    expect(result.status).toBe("failed");
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "sdk_cutover_failed",
+      expect.objectContaining({ family: "dom", error_kind: "network" }),
+    );
+  });
+
+  it("classifies a plain error as an sdk defect, not network", async () => {
+    const deps = makeDeps({
+      writeProjectFile: vi.fn().mockRejectedValue(new Error("disk full")),
+    });
+    const session = makeSession();
+    const sel = { hfId: "hf-abc" } as never;
+
+    const result = await sdkCutoverPersist(
+      sel,
+      [styleOp("color", "red")],
+      "before",
+      "/path.html",
+      session,
+      deps,
+    );
+
+    expect(result.status).toBe("failed");
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "sdk_cutover_failed",
+      expect.objectContaining({ family: "dom", error_kind: "sdk" }),
+    );
+  });
+});

package/src/utils/sdkCutover.ts

@@ -11,8 +11,8 @@ import {
   shouldDeclineTextCutoverForTarget,
 } from "./sdkCutoverEligibility";
 import {
-  asCutoverError,
   declinedCutover,
+  failedCutover,
   persistSdkCandidateMutation,
   type CutoverDeps,
   type CutoverOptions,
@@ -45,12 +45,13 @@ function sdkFamilyEnabled(family: StudioSdkOperationFamily): boolean {
 
 function trackCutoverResult(
   result: CutoverResult,
+  family: StudioSdkOperationFamily,
   context: { hfId?: string | null; opCount: number },
 ): void {
   if (result.status === "committed") {
-    trackStudioEvent("sdk_cutover_success", context);
+    trackStudioEvent("sdk_cutover_success", { ...context, family });
   } else if (result.status === "failed") {
-    trackStudioEvent("sdk_cutover_failed", { ...context, error: result.error.message });
+    failedCutover(result.error, family, context);
   }
 }
 
@@ -106,7 +107,7 @@ export async function sdkCutoverPersist(
     },
     options,
   );
-  trackCutoverResult(result, { hfId, opCount: ops.length });
+  trackCutoverResult(result, "dom", { hfId, opCount: ops.length });
   return result;
 }
 
@@ -148,12 +149,10 @@ export async function sdkTimingPersist(
       options,
       serializedBefore,
     );
-    trackCutoverResult(result, { hfId, opCount: 1 });
+    trackCutoverResult(result, "timing", { hfId, opCount: 1 });
     return result;
   } catch (error) {
-    const failed = { status: "failed", error: asCutoverError(error) } as const;
-    trackStudioEvent("sdk_cutover_failed", { hfId, error: failed.error.message });
-    return failed;
+    return failedCutover(error, "timing", { hfId, opCount: 1 });
   }
 }
 
@@ -202,24 +201,22 @@ export async function sdkTimingBatchPersist(
       serializedBefore,
     );
     if (result.status === "failed") {
-      trackStudioEvent("sdk_cutover_failed", {
+      return failedCutover(result.error, "timing", {
         hfId: changes[0]?.hfId ?? null,
-        error: result.error.message,
+        opCount: changes.length,
       });
-      return result;
     }
     trackStudioEvent("sdk_cutover_success", {
       hfId: changes[0]?.hfId ?? null,
       opCount: changes.length,
+      family: "timing",
     });
     return result;
   } catch (error) {
-    const failed = { status: "failed", error: asCutoverError(error) } as const;
-    trackStudioEvent("sdk_cutover_failed", {
+    return failedCutover(error, "timing", {
       hfId: changes[0]?.hfId ?? null,
-      error: failed.error.message,
+      opCount: changes.length,
     });
-    return failed;
   }
 }
 
@@ -321,15 +318,13 @@ async function dispatchGsapOpAndPersist(
       serializedBefore,
     );
     if (result.status === "committed") {
-      trackStudioEvent("sdk_cutover_success", { opCount: 1 });
+      trackStudioEvent("sdk_cutover_success", { opCount: 1, family });
     } else if (result.status === "failed") {
-      trackStudioEvent("sdk_cutover_failed", { error: result.error.message });
+      return failedCutover(result.error, family, { opCount: 1 });
     }
     return result;
   } catch (error) {
-    const failed = { status: "failed", error: asCutoverError(error) } as const;
-    trackStudioEvent("sdk_cutover_failed", { error: failed.error.message });
-    return failed;
+    return failedCutover(error, family, { opCount: 1 });
   }
 }
 
@@ -595,6 +590,6 @@ export async function sdkDeletePersist(
     (session) => session.removeElement(hfId),
     { label: "Delete element" },
   );
-  trackCutoverResult(result, { hfId, opCount: 1 });
+  trackCutoverResult(result, "lifecycle", { hfId, opCount: 1 });
   return result;
 }

package/src/utils/sdkEditTransaction.ts

@@ -4,6 +4,11 @@ import { hashContent, markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
 import { trackStudioEvent } from "./studioTelemetry";
 import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
 import type { StudioSdkOperationFamily } from "./sdkCutoverPolicy";
+import {
+  StudioFileConflictError,
+  StudioSaveHttpError,
+  StudioSaveNetworkError,
+} from "./studioSaveDiagnostics";
 
 export type CutoverResult =
   | { status: "declined"; reason: string }
@@ -91,10 +96,54 @@ export function declinedCutover(
   return { status: "declined", reason };
 }
 
-export function asCutoverError(error: unknown): Error {
+function asCutoverError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error));
 }
 
+// Browser rejection strings for a fetch that never produced a response (offline,
+// the dev server gone, a CSP/PNA block, an extension rewriting fetch). See
+// `useSdkSession.ts`'s `readProjectFileOptional` catch for the same list.
+const FETCH_REJECTION_MESSAGE = /Failed to fetch|Load failed|NetworkError when attempting to fetch/;
+
+/**
+ * Classify a cutover failure for the gate dashboard. `writeProjectFile`'s own
+ * fetch wraps a rejection as `StudioSaveNetworkError`, but two raw fetches in
+ * this same transaction — `readProjectFile` (via `captureOnDiskBefore`) and
+ * `writeProjectFile`'s own read-before-write preflight — throw an unwrapped
+ * `TypeError` that reaches here undecorated. Without the message fallback,
+ * those file as `"sdk"` and trip the cutover-failure rollback gate on a
+ * network blip the SDK never had a chance to own.
+ */
+function cutoverErrorKind(error: Error): "network" | "conflict" | "http" | "sdk" {
+  if (error instanceof StudioSaveNetworkError) return "network";
+  if (error instanceof StudioFileConflictError) return "conflict";
+  if (error instanceof StudioSaveHttpError) return "http";
+  if (error.name === "TypeError" && FETCH_REJECTION_MESSAGE.test(error.message)) return "network";
+  return "sdk";
+}
+
+/**
+ * Record a cutover that could not commit. Replaces ad hoc `trackStudioEvent("sdk_cutover_failed", ...)`
+ * calls so every gate event carries `family` and `error_kind` — without them the
+ * dashboard's rollback gate (any `sdk_cutover_failed` on a flipped version) cannot
+ * distinguish a real SDK defect from a rejected fetch it doesn't own.
+ */
+export function failedCutover(
+  error: unknown,
+  family: StudioSdkOperationFamily,
+  context: { hfId?: string | null; opCount?: number } = {},
+): CutoverResult {
+  const err = asCutoverError(error);
+  trackStudioEvent("sdk_cutover_failed", {
+    ...context,
+    family,
+    error_kind: cutoverErrorKind(err),
+    ...(err instanceof StudioSaveHttpError ? { status: err.statusCode } : {}),
+    error: err.message,
+  });
+  return { status: "failed", error: err };
+}
+
 /** Only an explicit decline may enter the legacy mutation backend. */
 export function cutoverCommittedOrThrow(result: CutoverResult): boolean {
   if (result.status === "failed") throw result.error;