@hyperframes/studio 0.6.95 → 0.6.97

package/src/utils/domEditSaveQueue.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDomEditSaveQueue } from "./domEditSaveQueue";
+import { StudioSaveHttpError } from "./studioSaveDiagnostics";
+
+describe("dom edit save queue", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("opens the breaker after consecutive failures and rejects new work until reset", async () => {
+    const onOpen = vi.fn();
+    const onReset = vi.fn();
+    const queue = createDomEditSaveQueue({
+      failureThreshold: 2,
+      onOpen,
+      onReset,
+    });
+
+    await expect(
+      queue.enqueue(async () => {
+        throw new StudioSaveHttpError("Server down", 503);
+      }),
+    ).rejects.toThrow("Server down");
+    await expect(
+      queue.enqueue(async () => {
+        throw new StudioSaveHttpError("Still down", 503);
+      }),
+    ).rejects.toThrow("Still down");
+
+    expect(onOpen).toHaveBeenCalledWith({
+      consecutiveFailures: 2,
+      errorMessage: "Still down",
+      statusCode: 503,
+    });
+
+    let thirdRan = false;
+    await expect(
+      queue.enqueue(async () => {
+        thirdRan = true;
+      }),
+    ).rejects.toThrow("Auto-save is paused");
+    expect(thirdRan).toBe(false);
+
+    queue.reset();
+    expect(onReset).toHaveBeenCalledOnce();
+
+    await queue.enqueue(async () => {
+      thirdRan = true;
+    });
+    expect(thirdRan).toBe(true);
+    queue.destroy();
+  });
+
+  it("keeps an open breaker paused even when already queued work succeeds", async () => {
+    const onOpen = vi.fn();
+    const onReset = vi.fn();
+    const queue = createDomEditSaveQueue({
+      failureThreshold: 1,
+      onOpen,
+      onReset,
+    });
+
+    let rejectFirst: ((error: Error) => void) | null = null;
+    let resolveFirstStarted: (() => void) | null = null;
+    const firstStarted = new Promise<void>((resolve) => {
+      resolveFirstStarted = resolve;
+    });
+    const first = queue.enqueue(
+      () =>
+        new Promise<void>((_resolve, reject) => {
+          rejectFirst = reject;
+          resolveFirstStarted?.();
+        }),
+    );
+    const second = queue.enqueue(async () => {});
+
+    await firstStarted;
+    expect(rejectFirst).toBeTypeOf("function");
+    rejectFirst?.(new StudioSaveHttpError("Server down", 503));
+    await expect(first).rejects.toThrow("Server down");
+    await expect(second).resolves.toBeUndefined();
+
+    expect(onOpen).toHaveBeenCalledOnce();
+    expect(onReset).not.toHaveBeenCalled();
+
+    await expect(queue.enqueue(async () => {})).rejects.toThrow("Auto-save is paused");
+
+    queue.reset();
+    expect(onReset).toHaveBeenCalledOnce();
+    queue.destroy();
+  });
+
+  it("resets consecutive failures after a successful save", async () => {
+    const onOpen = vi.fn();
+    const queue = createDomEditSaveQueue({
+      failureThreshold: 2,
+      onOpen,
+    });
+
+    await expect(
+      queue.enqueue(async () => {
+        throw new Error("first failure");
+      }),
+    ).rejects.toThrow("first failure");
+
+    await queue.enqueue(async () => {});
+
+    await expect(
+      queue.enqueue(async () => {
+        throw new Error("second failure after success");
+      }),
+    ).rejects.toThrow("second failure after success");
+
+    expect(onOpen).not.toHaveBeenCalled();
+    queue.destroy();
+  });
+});

package/src/utils/domEditSaveQueue.ts

@@ -0,0 +1,87 @@
+import { getStudioSaveErrorMessage, getStudioSaveStatusCode } from "./studioSaveDiagnostics";
+
+interface DomEditSaveQueueOpenEvent {
+  consecutiveFailures: number;
+  errorMessage: string;
+  statusCode: number | null;
+}
+
+interface DomEditSaveQueueOptions {
+  failureThreshold?: number;
+  onOpen?: (event: DomEditSaveQueueOpenEvent) => void;
+  onReset?: () => void;
+}
+
+export interface DomEditSaveQueue {
+  enqueue: (save: () => Promise<void>) => Promise<void>;
+  waitForIdle: () => Promise<void>;
+  reset: () => void;
+  destroy: () => void;
+}
+
+const DEFAULT_FAILURE_THRESHOLD = 5;
+
+export class DomEditSaveQueueOpenError extends Error {
+  constructor() {
+    super("Auto-save is paused. Dismiss the warning to retry DOM edits.");
+    this.name = "DomEditSaveQueueOpenError";
+  }
+}
+
+export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): DomEditSaveQueue {
+  const failureThreshold = options.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+
+  let tail = Promise.resolve();
+  let consecutiveFailures = 0;
+  let breakerOpen = false;
+
+  const reset = (notify = true) => {
+    const wasOpen = breakerOpen;
+    consecutiveFailures = 0;
+    breakerOpen = false;
+    if (notify && wasOpen) options.onReset?.();
+  };
+
+  const open = (error: unknown) => {
+    if (breakerOpen) return;
+    breakerOpen = true;
+    options.onOpen?.({
+      consecutiveFailures,
+      errorMessage: getStudioSaveErrorMessage(error),
+      statusCode: getStudioSaveStatusCode(error) ?? null,
+    });
+  };
+
+  const run = async (save: () => Promise<void>) => {
+    try {
+      await save();
+      if (!breakerOpen) consecutiveFailures = 0;
+    } catch (error) {
+      consecutiveFailures += 1;
+      if (consecutiveFailures >= failureThreshold) open(error);
+      throw error;
+    }
+  };
+
+  return {
+    enqueue(save) {
+      if (breakerOpen) return Promise.reject(new DomEditSaveQueueOpenError());
+      const queued = tail.catch(() => undefined).then(() => run(save));
+      tail = queued.then(
+        () => undefined,
+        () => undefined,
+      );
+      return queued;
+    },
+
+    async waitForIdle() {
+      await tail.catch(() => undefined);
+    },
+
+    reset,
+
+    destroy() {
+      reset(false);
+    },
+  };
+}

package/src/utils/studioHelpers.ts

@@ -12,7 +12,7 @@ export interface AppToast {
   tone: "error" | "info";
 }
 
-export type RightPanelTab = "layers" | "design" | "motion" | "renders" | "block-params";
+export type RightPanelTab = "layers" | "design" | "renders" | "block-params";
 
 export interface AgentModalAnchorPoint {
   x: number;

package/src/utils/studioSaveDiagnostics.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  StudioSaveHttpError,
+  StudioSaveNetworkError,
+  buildStudioSaveFailureProperties,
+  getStudioSaveStatusCode,
+  retryStudioSave,
+} from "./studioSaveDiagnostics";
+
+describe("studio save diagnostics", () => {
+  it("builds save_failure properties with stable diagnostics", () => {
+    const error = new StudioSaveHttpError("Failed to save index.html (503)", 503);
+
+    expect(
+      buildStudioSaveFailureProperties({
+        source: "code_editor",
+        error,
+        filePath: "index.html",
+        mutationType: "put",
+        attempt: 3,
+      }),
+    ).toEqual({
+      source: "code_editor",
+      error_message: "Failed to save index.html (503)",
+      status_code: 503,
+      file_path: "index.html",
+      mutation_type: "put",
+      attempt: 3,
+      label: undefined,
+      target_id: undefined,
+      target_selector: undefined,
+      target_source_file: undefined,
+    });
+  });
+
+  it("reads nested status codes from error causes", () => {
+    const cause = new StudioSaveHttpError("Too many requests", 429);
+    const error = new Error("retry wrapper") as Error & { cause?: unknown };
+    error.cause = cause;
+
+    expect(getStudioSaveStatusCode(error)).toBe(429);
+  });
+
+  it("retries transient save failures with exponential backoff and jitter", async () => {
+    const sleeps: number[] = [];
+    const operation = vi
+      .fn<(attempt: number) => Promise<string>>()
+      .mockRejectedValueOnce(new StudioSaveHttpError("Server restarting", 503))
+      .mockRejectedValueOnce(new StudioSaveHttpError("Still restarting", 503))
+      .mockRejectedValueOnce(new StudioSaveHttpError("Almost ready", 503))
+      .mockResolvedValue("saved");
+
+    await expect(
+      retryStudioSave(operation, {
+        random: () => 0.5,
+        sleep: async (delayMs) => {
+          sleeps.push(delayMs);
+        },
+      }),
+    ).resolves.toBe("saved");
+
+    expect(operation).toHaveBeenCalledTimes(4);
+    expect(operation.mock.calls.map(([attempt]) => attempt)).toEqual([1, 2, 3, 4]);
+    expect(sleeps).toEqual([500, 1000, 2000]);
+  });
+
+  it("does not retry non-transient client failures", async () => {
+    const operation = vi
+      .fn<(attempt: number) => Promise<string>>()
+      .mockRejectedValue(new StudioSaveHttpError("Too large", 413));
+
+    await expect(
+      retryStudioSave(operation, {
+        sleep: async () => {},
+      }),
+    ).rejects.toThrow("Too large");
+
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries typed network failures", async () => {
+    const operation = vi
+      .fn<(attempt: number) => Promise<string>>()
+      .mockRejectedValueOnce(new StudioSaveNetworkError("network dropped"))
+      .mockResolvedValue("saved");
+
+    await expect(
+      retryStudioSave(operation, {
+        sleep: async () => {},
+      }),
+    ).resolves.toBe("saved");
+
+    expect(operation).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not retry plain JavaScript errors", async () => {
+    const operation = vi
+      .fn<(attempt: number) => Promise<string>>()
+      .mockRejectedValue(new Error("local assertion failed"));
+
+    await expect(
+      retryStudioSave(operation, {
+        sleep: async () => {},
+      }),
+    ).rejects.toThrow("local assertion failed");
+
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it("aborts while waiting between retry attempts", async () => {
+    const controller = new AbortController();
+    const operation = vi
+      .fn<(attempt: number) => Promise<string>>()
+      .mockRejectedValue(new StudioSaveHttpError("Server restarting", 503));
+
+    const pending = retryStudioSave(operation, {
+      signal: controller.signal,
+      sleep: async (_delayMs, signal) => {
+        controller.abort();
+        if (signal?.aborted) throw new DOMException("Save aborted", "AbortError");
+      },
+    });
+
+    await expect(pending).rejects.toMatchObject({ name: "AbortError" });
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+});

package/src/utils/studioSaveDiagnostics.ts

@@ -0,0 +1,200 @@
+import { trackStudioEvent } from "./studioTelemetry";
+
+type StudioTelemetryValue = string | number | boolean | null | undefined;
+const STUDIO_SAVE_ATTEMPT_PROPERTY = "__studioSaveAttempt";
+
+export interface StudioSaveFailureInput {
+  source: string;
+  error: unknown;
+  statusCode?: number | null;
+  filePath?: string | null;
+  mutationType?: string | null;
+  attempt?: number | null;
+  label?: string | null;
+  targetId?: string | null;
+  targetSelector?: string | null;
+  targetSourceFile?: string | null;
+}
+
+export class StudioSaveHttpError extends Error {
+  readonly statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "StudioSaveHttpError";
+    this.statusCode = statusCode;
+  }
+}
+
+export class StudioSaveNetworkError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "StudioSaveNetworkError";
+  }
+}
+
+function readNumericProperty(value: object, key: string): number | undefined {
+  const record = value as Record<string, unknown>;
+  const property = record[key];
+  return typeof property === "number" && Number.isFinite(property) ? property : undefined;
+}
+
+function createStudioSaveAbortError(): Error {
+  if (typeof DOMException !== "undefined") return new DOMException("Save aborted", "AbortError");
+  const error = new Error("Save aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+function throwIfStudioSaveAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw createStudioSaveAbortError();
+}
+
+function attachStudioSaveAttempt(error: unknown, attempt: number): unknown {
+  if (!error || typeof error !== "object") return error;
+  try {
+    Object.defineProperty(error, STUDIO_SAVE_ATTEMPT_PROPERTY, {
+      value: attempt,
+      configurable: true,
+    });
+  } catch {
+    // Best-effort diagnostic only.
+  }
+  return error;
+}
+
+export function getStudioSaveErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === "string" && error.trim()) return error;
+  return "Unknown save failure";
+}
+
+export function getStudioSaveStatusCode(error: unknown): number | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const direct =
+    readNumericProperty(error, "statusCode") ??
+    readNumericProperty(error, "status") ??
+    readNumericProperty(error, "status_code");
+  if (direct != null) return direct;
+
+  const cause = (error as { cause?: unknown }).cause;
+  if (cause && cause !== error) return getStudioSaveStatusCode(cause);
+  return undefined;
+}
+
+function getStudioSaveAttempt(error: unknown): number | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const direct = readNumericProperty(error, STUDIO_SAVE_ATTEMPT_PROPERTY);
+  if (direct != null) return direct;
+
+  const cause = (error as { cause?: unknown }).cause;
+  if (cause && cause !== error) return getStudioSaveAttempt(cause);
+  return undefined;
+}
+
+function isStudioSaveAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+function isRetryableStudioSaveError(error: unknown): boolean {
+  if (isStudioSaveAbortError(error)) return false;
+  if (error instanceof StudioSaveNetworkError) return true;
+  const statusCode = getStudioSaveStatusCode(error);
+  if (statusCode == null) return false;
+  return statusCode === 408 || statusCode === 425 || statusCode === 429 || statusCode >= 500;
+}
+
+export function buildStudioSaveFailureProperties(
+  input: StudioSaveFailureInput,
+): Record<string, StudioTelemetryValue> {
+  const statusCode = input.statusCode ?? getStudioSaveStatusCode(input.error) ?? null;
+  const attempt = input.attempt ?? getStudioSaveAttempt(input.error) ?? undefined;
+  return {
+    source: input.source,
+    error_message: getStudioSaveErrorMessage(input.error),
+    status_code: statusCode,
+    file_path: input.filePath ?? input.targetSourceFile ?? undefined,
+    mutation_type: input.mutationType ?? undefined,
+    attempt,
+    label: input.label ?? undefined,
+    target_id: input.targetId ?? undefined,
+    target_selector: input.targetSelector ?? undefined,
+    target_source_file: input.targetSourceFile ?? undefined,
+  };
+}
+
+export function trackStudioSaveFailure(input: StudioSaveFailureInput): void {
+  trackStudioEvent("save_failure", buildStudioSaveFailureProperties(input));
+}
+
+export async function createStudioSaveHttpError(
+  response: Response,
+  fallbackMessage: string,
+): Promise<StudioSaveHttpError> {
+  let body = "";
+  try {
+    body = await response.text();
+  } catch {
+    body = "";
+  }
+  const detail = body.trim().slice(0, 300);
+  const message = detail
+    ? `${fallbackMessage} (${response.status}): ${detail}`
+    : `${fallbackMessage} (${response.status})`;
+  return new StudioSaveHttpError(message, response.status);
+}
+
+export async function retryStudioSave<T>(
+  operation: (attempt: number) => Promise<T>,
+  options: {
+    retries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterRatio?: number;
+    random?: () => number;
+    signal?: AbortSignal;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    sleep?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+  } = {},
+): Promise<T> {
+  const retries = options.retries ?? 3;
+  const baseDelayMs = options.baseDelayMs ?? 500;
+  const maxDelayMs = options.maxDelayMs ?? 8000;
+  const jitterRatio = options.jitterRatio ?? 0.25;
+  const random = options.random ?? Math.random;
+  const shouldRetry = options.shouldRetry ?? isRetryableStudioSaveError;
+  const sleep =
+    options.sleep ??
+    ((delayMs: number, signal?: AbortSignal) =>
+      new Promise<void>((resolve, reject) => {
+        throwIfStudioSaveAborted(signal);
+        const onAbort = () => {
+          globalThis.clearTimeout(timeout);
+          reject(createStudioSaveAbortError());
+        };
+        const timeout = globalThis.setTimeout(() => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve();
+        }, delayMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+      }));
+  const maxAttempts = retries + 1;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      throwIfStudioSaveAborted(options.signal);
+      return await operation(attempt);
+    } catch (error) {
+      const failure = attachStudioSaveAttempt(error, attempt);
+      if (attempt >= maxAttempts || !shouldRetry(failure, attempt)) throw failure;
+      const retryIndex = attempt - 1;
+      const exponentialDelay = Math.min(baseDelayMs * 2 ** retryIndex, maxDelayMs);
+      const jitterSpan = exponentialDelay * jitterRatio;
+      const jitteredDelay = Math.round(exponentialDelay + (random() * 2 - 1) * jitterSpan);
+      const delayMs = Math.max(0, Math.min(maxDelayMs, jitteredDelay));
+      await sleep(delayMs, options.signal);
+    }
+  }
+
+  throw new Error("Save retry loop exited unexpectedly");
+}

package/src/utils/studioUrlState.test.ts

@@ -159,7 +159,6 @@ describe("studio url state", () => {
   it("normalizes url tabs against feature flags", () => {
     expect(normalizeStudioUrlPanelTab("renders")).toBe("renders");
     expect(normalizeStudioUrlPanelTab("layers", { inspectorPanelsEnabled: false })).toBe("renders");
-    expect(normalizeStudioUrlPanelTab("motion", { motionPanelEnabled: false })).toBe("design");
   });
 
   it("hydrates seek first, preserves the initial url state, then restores selection", async () => {

package/src/utils/studioUrlState.ts

@@ -1,9 +1,6 @@
 import type { RightPanelTab } from "./studioHelpers";
 import { buildProjectHash, parseProjectHashRoute } from "./projectRouting";
-import {
-  STUDIO_INSPECTOR_PANELS_ENABLED,
-  STUDIO_MOTION_PANEL_ENABLED,
-} from "../components/editor/manualEditingAvailability";
+import { STUDIO_INSPECTOR_PANELS_ENABLED } from "../components/editor/manualEditingAvailability";
 
 export interface StudioUrlSelectionState {
   sourceFile?: string;
@@ -21,22 +18,19 @@ export interface StudioUrlState {
   selection: StudioUrlSelectionState | null;
 }
 
-const VALID_TABS: RightPanelTab[] = ["layers", "design", "motion", "renders"];
+const VALID_TABS: RightPanelTab[] = ["layers", "design", "renders"];
 
 export function normalizeStudioUrlPanelTab(
   tab: RightPanelTab | null,
   options: {
     inspectorPanelsEnabled?: boolean;
-    motionPanelEnabled?: boolean;
   } = {},
 ): RightPanelTab | null {
   if (!tab) return null;
   if (!VALID_TABS.includes(tab)) return null;
   const inspectorPanelsEnabled = options.inspectorPanelsEnabled ?? STUDIO_INSPECTOR_PANELS_ENABLED;
-  const motionPanelEnabled = options.motionPanelEnabled ?? STUDIO_MOTION_PANEL_ENABLED;
 
   if (!inspectorPanelsEnabled && tab !== "renders") return "renders";
-  if (tab === "motion" && !motionPanelEnabled) return "design";
   return tab;
 }