@hyperframes/studio 0.7.58 → 0.7.59

package/src/hooks/useTimelineEditing.test.tsx

@@ -1108,6 +1108,7 @@ describe("useTimelineEditing duration rollback on failed persist", () => {
     stubProjectFetch(ROLLBACK_SOURCE);
     usePlayerStore.getState().setDuration(4);
     vi.spyOn(console, "error").mockImplementation(() => {});
+    const showToast = vi.fn();
     const hook = renderTimelineEditingHook({
       timelineElements: [clip],
       iframe,
@@ -1116,8 +1117,9 @@ describe("useTimelineEditing duration rollback on failed persist", () => {
       writeProjectFile,
       recordEdit: vi.fn(async () => {}),
       reloadPreview: vi.fn(),
+      showToast,
     });
-    return { iframe, clip, hook, writeError };
+    return { iframe, clip, hook, showToast, writeError };
   }
 
   /**
@@ -1137,6 +1139,7 @@ describe("useTimelineEditing duration rollback on failed persist", () => {
       await flushAsyncWork();
     });
     expect(rejection).toBe(ctx.writeError);
+    expect(ctx.showToast).toHaveBeenCalledWith("write failed", "error");
     expect(usePlayerStore.getState().duration).toBe(4);
     expect(rootDurationAttr(ctx.iframe)).toBe("4");
   }

package/src/hooks/useTimelineEditing.ts

@@ -32,8 +32,9 @@ import {
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
-import { sdkTimingPersist } from "../utils/sdkCutover";
+import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
+import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
 type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
   stackingReorder?: TimelineStackingReorderIntent | null;
@@ -53,6 +54,7 @@ export function useTimelineEditing({
   uploadProjectFiles,
   isRecordingRef,
   sdkSession,
+  publishSdkSession,
   forceReloadSdkSession,
   handleDomZIndexReorderCommitRef,
 }: UseTimelineEditingOptions) {
@@ -121,10 +123,10 @@ export function useTimelineEditing({
     recordEdit,
     reloadPreview,
     sdkSession,
+    publishSdkSession,
     showToast,
     writeProjectFile,
   });
-
   const handleTimelineElementMove = useCallback(
     // fallow-ignore-next-line complexity
     (element: TimelineElement, updates: TimelineMoveUpdates) => {
@@ -215,10 +217,11 @@ export function useTimelineEditing({
                   // Capture on-disk bytes as the undo `before` so undoing a timing move
                   // restores the file verbatim, not a normalized full-DOM re-emit.
                   readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+                  publishSession: publishSdkSession,
                 },
                 { label: "Move timeline clip", coalesceKey },
-              ).then((handled) => {
-                if (!handled) return moveFallback();
+              ).then((result) => {
+                if (!cutoverCommittedOrThrow(result)) return moveFallback();
               });
             }
             return moveFallback();
@@ -226,6 +229,7 @@ export function useTimelineEditing({
           .catch((error) => {
             // Failed persist: revert the optimistic duration readout + live root.
             rollbackDuration();
+            showToast(getStudioSaveErrorMessage(error), "error");
             throw error;
           });
       };
@@ -236,12 +240,14 @@ export function useTimelineEditing({
       enqueueEdit,
       activeCompPath,
       sdkSession,
+      publishSdkSession,
       recordEdit,
       writeProjectFile,
       reloadPreview,
       domEditSaveTimestampRef,
       timelineElements,
       handleDomZIndexReorderCommitRef,
+      showToast,
     ],
   );
 
@@ -255,9 +261,6 @@ export function useTimelineEditing({
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-duration", formatTimelineAttributeNumber(updates.duration)],
       ];
-      // Patch the live playback-start/media-start attr too, or a resize that
-      // trims the playback start leaves the preview showing the old in-point
-      // until the next reload (the persisted patch handles it via pbs below).
       if (updates.playbackStart != null) {
         const liveAttr =
           element.playbackStartAttr === "playback-start"
@@ -319,15 +322,17 @@ export function useTimelineEditing({
                 // Capture on-disk bytes as the undo `before` so undoing a timing
                 // resize restores the file verbatim, not a normalized full-DOM re-emit.
                 readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+                publishSession: publishSdkSession,
               },
               { label: "Resize timeline clip", coalesceKey },
-            ).then((handled) => {
-              if (!handled) return resizeFallback();
+            ).then((result) => {
+              if (!cutoverCommittedOrThrow(result)) return resizeFallback();
             })
           : resizeFallback();
       return persistDone.catch((error) => {
         // Failed persist: revert the optimistic duration readout + live root.
         rollbackDuration();
+        showToast(getStudioSaveErrorMessage(error), "error");
         throw error;
       });
     },
@@ -336,10 +341,12 @@ export function useTimelineEditing({
       enqueueEdit,
       activeCompPath,
       sdkSession,
+      publishSdkSession,
       recordEdit,
       writeProjectFile,
       reloadPreview,
       domEditSaveTimestampRef,
+      showToast,
     ],
   );
 
@@ -360,7 +367,6 @@ export function useTimelineEditing({
   const handleToggleElementHidden = useTimelineElementVisibilityEditing({
     projectIdRef,
     activeCompPath,
-    timelineElements,
     showToast,
     writeProjectFile,
     recordEdit,

package/src/hooks/useTimelineEditingTypes.ts

@@ -2,6 +2,7 @@ import type { MutableRefObject, RefObject } from "react";
 import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
 import type { EditHistoryKind } from "../utils/editHistory";
+import type { PublishSdkSession } from "../utils/sdkCutover";
 
 interface RecordEditInput {
   label: string;
@@ -40,6 +41,8 @@ export interface UseTimelineEditingOptions {
   isRecordingRef?: RefObject<boolean>;
   /** Stage 7 §3.2: SDK session for routing timing ops through setTiming. */
   sdkSession?: Composition | null;
+  /** Publish a fully persisted candidate SDK session. */
+  publishSdkSession?: PublishSdkSession;
   /** Resync the SDK session after a server-authoritative timeline write. */
   forceReloadSdkSession?: () => void;
   handleDomZIndexReorderCommitRef?: MutableRefObject<TimelineZIndexReorderCommit | null>;

package/src/hooks/useTimelineGroupEditing.ts

@@ -1,7 +1,11 @@
 import { useCallback, type MutableRefObject, type RefObject } from "react";
 import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
-import { sdkTimingBatchPersist } from "../utils/sdkCutover";
+import {
+  cutoverCommittedOrThrow,
+  sdkTimingBatchPersist,
+  type PublishSdkSession,
+} from "../utils/sdkCutover";
 import {
   buildTimelineMoveTimingPatch,
   buildTimelineResizeTimingPatch,
@@ -20,6 +24,7 @@ import {
   shiftGsapPositions,
   syncPreviewContentDuration,
 } from "./timelineTimingSync";
+import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
 export interface TimelineGroupMoveChange {
   element: TimelineElement;
@@ -53,6 +58,7 @@ interface UseTimelineGroupEditingOptions {
   recordEdit: (input: RecordEditInput) => Promise<void>;
   reloadPreview: () => void;
   sdkSession?: Composition | null;
+  publishSdkSession?: PublishSdkSession;
   showToast: (message: string, tone?: "error" | "info") => void;
   writeProjectFile: (path: string, content: string) => Promise<void>;
 }
@@ -108,6 +114,7 @@ export function useTimelineGroupEditing({
   recordEdit,
   reloadPreview,
   sdkSession,
+  publishSdkSession,
   showToast,
   writeProjectFile,
 }: UseTimelineGroupEditingOptions) {
@@ -189,7 +196,7 @@ export function useTimelineGroupEditing({
         input.eligible &&
         input.sdkChanges.every((change) => change !== null);
       if (!canUseSdk) return false;
-      return sdkTimingBatchPersist(
+      const result = await sdkTimingBatchPersist(
         input.sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
         sharedPath,
         sdkSession,
@@ -200,14 +207,17 @@ export function useTimelineGroupEditing({
           domEditSaveTimestampRef,
           compositionPath: activeCompPath,
           readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+          publishSession: publishSdkSession,
         },
         { label: input.label, coalesceKey: input.coalesceKey, coalesceMs: input.coalesceMs },
       );
+      return cutoverCommittedOrThrow(result);
     },
     [
       activeCompPath,
       domEditSaveTimestampRef,
       projectIdRef,
+      publishSdkSession,
       recordEdit,
       reloadPreview,
       sdkSession,
@@ -313,6 +323,7 @@ export function useTimelineGroupEditing({
         // Failed persist: revert the optimistic duration readout + live root
         // alongside the gesture owner's store rollback.
         rollbackDuration();
+        showToast(getStudioSaveErrorMessage(error), "error");
         throw error;
       });
     },
@@ -324,6 +335,7 @@ export function useTimelineGroupEditing({
       recordEdit,
       reloadPreview,
       trySdkBatchPersist,
+      showToast,
     ],
   );
 
@@ -419,6 +431,7 @@ export function useTimelineGroupEditing({
         // Failed persist: revert the optimistic duration readout + live root
         // alongside the gesture owner's store rollback.
         rollbackDuration();
+        showToast(getStudioSaveErrorMessage(error), "error");
         throw error;
       });
     },
@@ -430,6 +443,7 @@ export function useTimelineGroupEditing({
       recordEdit,
       reloadPreview,
       trySdkBatchPersist,
+      showToast,
     ],
   );
 

package/src/hooks/useVariablesPersist.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import type { Composition } from "@hyperframes/sdk";
-import { persistSdkSerialize } from "../utils/sdkCutover";
+import { cutoverCommittedOrThrow, persistSdkCandidateMutation } from "../utils/sdkCutover";
 import type { UseSlideshowPersistParams } from "./useSlideshowPersist";
 
 /** Same single-writer dependency set the slideshow persist path uses. */
@@ -21,6 +21,7 @@ export function useVariablesPersist({
   recordEdit,
   reloadPreview,
   domEditSaveTimestampRef,
+  publishSdkSession,
 }: UseVariablesPersistParams): (
   label: string,
   mutate: (session: Composition) => void,
@@ -30,11 +31,8 @@ export function useVariablesPersist({
       if (!sdkSession) return false;
       const path = activeCompPath ?? "index.html";
       const originalContent = await readProjectFile(path);
-      mutate(sdkSession);
-      const after = sdkSession.serialize();
-      if (after === originalContent) return false;
-      await persistSdkSerialize(
-        after,
+      const result = await persistSdkCandidateMutation(
+        sdkSession,
         path,
         originalContent,
         {
@@ -43,10 +41,13 @@ export function useVariablesPersist({
           reloadPreview,
           domEditSaveTimestampRef,
           compositionPath: activeCompPath,
+          readProjectFile,
+          publishSession: publishSdkSession,
         },
+        mutate,
         { label },
       );
-      return true;
+      return cutoverCommittedOrThrow(result);
     },
     [
       sdkSession,
@@ -56,6 +57,7 @@ export function useVariablesPersist({
       recordEdit,
       reloadPreview,
       domEditSaveTimestampRef,
+      publishSdkSession,
     ],
   );
 }

package/src/icons/SystemIcons.tsx

@@ -21,6 +21,7 @@ import {
   ArrowClockwise,
   Gear,
   Scissors as PhScissors,
+  Link as PhLink,
 } from "@phosphor-icons/react";
 import type { Icon as PhosphorIcon, IconProps as PhosphorIconProps } from "@phosphor-icons/react";
 
@@ -69,3 +70,4 @@ export const Camera = makeIcon(PhCamera);
 export const RotateCw = makeIcon(ArrowClockwise);
 export const Settings = makeIcon(Gear);
 export const Scissors = makeIcon(PhScissors);
+export const Link = makeIcon(PhLink);

package/src/styles/studio.css

@@ -447,3 +447,25 @@ body {
     animation: none;
   }
 }
+
+/* Flat inspector group header/body entrance (FlatGroupHeader) */
+@keyframes hf-flat-group-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.hf-flat-group-enter {
+  animation: hf-flat-group-in 120ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-flat-group-enter {
+    animation: none;
+  }
+}

package/src/styles/tailwind-preset.shared.js

@@ -12,11 +12,16 @@ const studioPreset = {
         },
         panel: {
           bg: "#0C0C0E",
+          // Open inspector-section body — slightly lighter than headers (bg)
+          // so the recessed scrollable region reads distinct.
+          "bg-inset": "#121214",
           input: "#161618",
           surface: "#18181B",
           hover: "#27272A",
           border: "#1E1E1E",
           "border-input": "#27272A",
+          hairline: "#1A1A1C",
+          "text-0": "#FAFAFA",
           "text-1": "#E4E4E7",
           "text-2": "#A1A1AA",
           "text-3": "#71717A",
@@ -24,6 +29,8 @@ const studioPreset = {
           "text-5": "#3F3F46",
           accent: "#3CE6AC",
           danger: "#EF4444",
+          media: "#00E3FF",
+          container: "#F5A623",
         },
       },
     },

package/src/utils/designInputTracking.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const trackStudioEvent = vi.fn();
+vi.mock("./studioTelemetry", () => ({
+  trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
+}));
+
+import {
+  __resetDesignInputThrottle,
+  slugifyDesignInput,
+  trackDesignInput,
+} from "./designInputTracking";
+
+beforeEach(() => {
+  trackStudioEvent.mockReset();
+  __resetDesignInputThrottle();
+  vi.restoreAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("trackDesignInput", () => {
+  it("emits one design_input event with ui/section/control/name", () => {
+    trackDesignInput({ ui: "flat", section: "Style", control: "metric", name: "Opacity" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith("design_input", {
+      ui: "flat",
+      section: "style",
+      control: "metric",
+      name: "opacity",
+    });
+  });
+
+  it("slugifies compound names and sections", () => {
+    trackDesignInput({
+      ui: "classic",
+      section: "Color Grading",
+      control: "slider",
+      name: "Font Size",
+    });
+    expect(trackStudioEvent).toHaveBeenCalledWith("design_input", {
+      ui: "classic",
+      section: "color-grading",
+      control: "slider",
+      name: "font-size",
+    });
+  });
+
+  it("marks an unresolved name as 'unnamed' (R3 coverage signal)", () => {
+    trackDesignInput({ ui: "classic", section: "style", control: "button", name: "" });
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "design_input",
+      expect.objectContaining({ name: "unnamed" }),
+    );
+  });
+
+  it("coalesces repeated fires of the same input within the window (R4)", () => {
+    const nowSpy = vi.spyOn(performance, "now");
+    // Same key, three quick fires -> 1 event.
+    nowSpy.mockReturnValue(1000);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    nowSpy.mockReturnValue(1100);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    nowSpy.mockReturnValue(1500);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+
+    // A different input within the window is NOT collapsed.
+    nowSpy.mockReturnValue(1550);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "scale" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(2);
+
+    // Same input after the window fires again.
+    nowSpy.mockReturnValue(2200);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(3);
+  });
+
+  it("never throws even if the underlying tracker throws", () => {
+    trackStudioEvent.mockImplementation(() => {
+      throw new Error("ingest down");
+    });
+    expect(() =>
+      trackDesignInput({ ui: "flat", section: "style", control: "metric", name: "opacity" }),
+    ).not.toThrow();
+  });
+});
+
+describe("slugifyDesignInput", () => {
+  it("lowercases, collapses non-alphanumerics, and trims dashes", () => {
+    expect(slugifyDesignInput("  Border Radius (px) ")).toBe("border-radius-px");
+    expect(slugifyDesignInput("X")).toBe("x");
+    expect(slugifyDesignInput("---")).toBe("");
+  });
+});

package/src/utils/designInputTracking.ts

@@ -0,0 +1,80 @@
+import { trackStudioEvent } from "./studioTelemetry";
+
+// Per-input usage telemetry for the design (inspector) panel. Both inspector UIs
+// (classic PropertyPanel, flat PropertyPanelFlat) funnel their inputs through this
+// one helper so usage can be ranked by input to find removal candidates. Emits the
+// batched `studio:design_input` event via trackStudioEvent (opt-out-aware, never-throw).
+//
+// Fire convention (kept consistent across both UIs):
+//   - Discrete controls (metric/text/select/segmented/toggle/color/button) fire only
+//     when a real committed value change happens (the commit site guards on
+//     next !== current).
+//   - Continuous controls (sliders, scrub) fire once per user interaction that
+//     produced commits, even if the net value ends unchanged — net-change-at-settle
+//     is unreliable for them because mid-drag commits have already advanced the value,
+//     so "did the user work this control" is the honest signal. The coalescing window
+//     below collapses the many mid-drag commits into that single event.
+
+export type DesignInputUi = "flat" | "classic";
+
+export interface DesignInputDescriptor {
+  ui: DesignInputUi;
+  /** Section slug the input lives under (e.g. "style", "color-grading"). */
+  section: string;
+  /** Control kind: "metric" | "slider" | "select" | "segmented" | "toggle" | "color" | "text" | "button" | … */
+  control: string;
+  /** Input identity — the field label or CSS/GSAP property. Slugified for stable ranking. */
+  name: string;
+}
+
+// Continuous controls (sliders, scrub, wheel-nudge, live-commit text) fire many
+// commits per interaction. Collapse repeated fires of the same input within this
+// window into one event so a single drag counts once (R4).
+const COALESCE_WINDOW_MS = 600;
+
+const lastFiredByKey = new Map<string, number>();
+
+function now(): number {
+  // performance.now() is monotonic and available in the studio runtime and jsdom.
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : 0;
+}
+
+export function slugifyDesignInput(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}
+
+/** Test seam: clear the coalescing state between cases. */
+export function __resetDesignInputThrottle(): void {
+  lastFiredByKey.clear();
+}
+
+export function trackDesignInput(descriptor: DesignInputDescriptor): void {
+  try {
+    const section = slugifyDesignInput(descriptor.section) || "unknown";
+    const name = slugifyDesignInput(descriptor.name);
+    // An input with no resolvable name is useless for the removal analysis (R3).
+    // Emit it anyway (so a coverage test can catch it) but under an explicit marker.
+    const control = descriptor.control || "unknown";
+    const key = `${descriptor.ui}:${section}:${control}:${name || "unnamed"}`;
+
+    const t = now();
+    const last = lastFiredByKey.get(key);
+    if (last !== undefined && t - last < COALESCE_WINDOW_MS) return;
+    lastFiredByKey.set(key, t);
+
+    trackStudioEvent("design_input", {
+      ui: descriptor.ui,
+      section,
+      control,
+      name: name || "unnamed",
+    });
+  } catch {
+    // Telemetry must never break the edit path.
+  }
+}

package/src/utils/sdkCutover.gate.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 
 // Dark-launch contract: with STUDIO_SDK_CUTOVER_ENABLED=false, EVERY cutover
-// persist chokepoint must return false so the caller takes the legacy server
+// persist chokepoint must explicitly decline so the caller takes the legacy server
 // path — even when a valid SDK session exists (one always does, for
 // shadow/selection). This is the contract the prod flag-flip rests on; a future
 // refactor of the gate guards that silently re-enables cutover on flag-off
@@ -31,12 +31,12 @@ const makeDeps = () =>
     domEditSaveTimestampRef: { current: 0 },
   }) as never;
 
-describe("dark-launch gate — STUDIO_SDK_CUTOVER_ENABLED=false ⇒ persist returns false", () => {
+describe("dark-launch gate — STUDIO_SDK_CUTOVER_ENABLED=false ⇒ persist declines", () => {
   it("sdkTimingPersist falls back without writing", async () => {
     const deps = makeDeps();
-    expect(await sdkTimingPersist("hf-a", "/c.html", { start: 1 }, makeSession(), deps)).toBe(
-      false,
-    );
+    expect(
+      await sdkTimingPersist("hf-a", "/c.html", { start: 1 }, makeSession(), deps),
+    ).toMatchObject({ status: "declined", reason: "feature_disabled" });
     expect(
       (deps as unknown as { writeProjectFile: ReturnType<typeof vi.fn> }).writeProjectFile,
     ).not.toHaveBeenCalled();
@@ -50,12 +50,12 @@ describe("dark-launch gate — STUDIO_SDK_CUTOVER_ENABLED=false ⇒ persist retu
         makeSession(),
         makeDeps(),
       ),
-    ).toBe(false);
+    ).toMatchObject({ status: "declined", reason: "feature_disabled" });
   });
 
   it("sdkDeletePersist falls back", async () => {
     expect(
       await sdkDeletePersist("hf-a", "<html></html>", "/c.html", makeSession(), makeDeps()),
-    ).toBe(false);
+    ).toMatchObject({ status: "declined", reason: "feature_disabled" });
   });
 });