@hyperframes/studio 0.8.59 → 0.8.61

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;

package/src/utils/studioUiPreferences.ts

@@ -25,7 +25,7 @@ export interface StudioUiPreferences {
   snapToGrid?: boolean;
   /** Timeline magnet: snap clip drags/trims/drops to playhead, clip edges, and beats. */
   timelineSnapEnabled?: boolean;
-  /** Audio level meters at the timeline's right edge; shown unless hidden here. */
+  /** Audio level meters at the timeline's right edge; hidden unless enabled here. */
   audioMetersVisible?: boolean;
   /** Keeps the main track gapless: deleting a clip closes the gap. Distinct
    *  from `timelineSnapEnabled` ("Magnet", drag/trim snapping). */