@hyperframes/studio 0.7.37 → 0.7.39

package/src/hooks/useToast.ts

@@ -2,24 +2,77 @@ import { useState, useCallback, useRef } from "react";
 import { useMountEffect } from "./useMountEffect";
 import type { AppToast } from "../utils/studioHelpers";
 
+interface ToastItem extends AppToast {
+  id: number;
+  /** True while the exit animation plays, just before removal. */
+  leaving?: boolean;
+}
+
+const AUTO_DISMISS_MS = 4000;
+const EXIT_MS = 160;
+const MAX_TOASTS = 3;
+
+let nextToastId = 1;
+
+/**
+ * Stacked toasts (max 3). Info toasts auto-dismiss after 4s; error toasts
+ * persist until explicitly dismissed so failures can't silently vanish.
+ */
 export function useToast() {
-  const [appToast, setAppToast] = useState<AppToast | null>(null);
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const timersRef = useRef<Map<number, ReturnType<typeof setTimeout>>>(new Map());
 
-  const showToast = useCallback((message: string, tone: AppToast["tone"] = "error") => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    setAppToast({ message, tone });
-    timerRef.current = setTimeout(() => setAppToast(null), 4000);
+  const clearTimer = useCallback((id: number) => {
+    const timer = timersRef.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersRef.current.delete(id);
+    }
   }, []);
 
+  const removeToast = useCallback(
+    (id: number) => {
+      clearTimer(id);
+      setToasts((prev) => prev.filter((t) => t.id !== id));
+    },
+    [clearTimer],
+  );
+
+  const dismissToast = useCallback(
+    (id: number) => {
+      clearTimer(id);
+      // Mark leaving so the exit animation plays, then remove.
+      setToasts((prev) => prev.map((t) => (t.id === id ? { ...t, leaving: true } : t)));
+      const timer = setTimeout(() => removeToast(id), EXIT_MS);
+      timersRef.current.set(id, timer);
+    },
+    [clearTimer, removeToast],
+  );
+
+  const showToast = useCallback(
+    (message: string, tone: AppToast["tone"] = "error") => {
+      const id = nextToastId++;
+      setToasts((prev) => {
+        const next = [...prev, { id, message, tone }];
+        // Cap the stack; drop the oldest (and its pending timer).
+        while (next.length > MAX_TOASTS) {
+          const dropped = next.shift();
+          if (dropped) clearTimer(dropped.id);
+        }
+        return next;
+      });
+      if (tone !== "error") {
+        const timer = setTimeout(() => dismissToast(id), AUTO_DISMISS_MS);
+        timersRef.current.set(id, timer);
+      }
+    },
+    [clearTimer, dismissToast],
+  );
+
   useMountEffect(() => () => {
-    if (timerRef.current) clearTimeout(timerRef.current);
+    for (const timer of timersRef.current.values()) clearTimeout(timer);
+    timersRef.current.clear();
   });
 
-  const dismissToast = useCallback(() => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    setAppToast(null);
-  }, []);
-
-  return { appToast, showToast, dismissToast };
+  return { toasts, showToast, dismissToast };
 }

package/src/player/components/ShortcutsPanel.tsx

@@ -60,6 +60,15 @@ const SHORTCUT_SECTIONS = [
       { key: "⇧ Drag", label: "Uniform resize" },
     ],
   },
+  {
+    title: "Crop",
+    hints: [
+      { key: "DblClick", label: "Crop selected element" },
+      { key: "Drag edge", label: "Adjust crop side" },
+      { key: "Drag frame", label: "Move crop window" },
+      { key: "Esc", label: "Exit crop (or click outside)" },
+    ],
+  },
   {
     title: "Panels",
     hints: [

package/src/player/store/playerStore.ts

@@ -111,6 +111,15 @@ interface PlayerState {
   autoKeyframeEnabled: boolean;
   setAutoKeyframeEnabled: (enabled: boolean) => void;
 
+  /** Crop mode. Armed from the preview toolbar, the Clip panel, or a
+   *  double-click on a croppable selection; while armed, edge handles on the
+   *  selection adjust a non-destructive clip-path inset. `available` is
+   *  published by DomEditOverlay when the selection can be cropped. */
+  cropMode: boolean;
+  setCropMode: (active: boolean) => void;
+  cropAvailable: boolean;
+  setCropAvailable: (available: boolean) => void;
+
   /** Multi-select: additional selected elements beyond selectedElementId. */
   selectedElementIds: Set<string>;
   toggleSelectedElementId: (id: string) => void;
@@ -246,6 +255,11 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setMotionPathCreateAvailable: (available) => set({ motionPathCreateAvailable: available }),
   autoKeyframeEnabled: true,
   setAutoKeyframeEnabled: (enabled) => set({ autoKeyframeEnabled: enabled }),
+  cropMode: false,
+  setCropMode: (active) => set({ cropMode: active }),
+  cropAvailable: false,
+  setCropAvailable: (available) =>
+    set(available ? { cropAvailable: true } : { cropAvailable: false, cropMode: false }),
 
   selectedElementIds: new Set<string>(),
   toggleSelectedElementId: (id: string) =>

package/src/styles/studio.css

@@ -251,3 +251,64 @@ body {
   background: linear-gradient(90deg, #06e3fa, #4fdb5e);
   transition: transform 160ms ease;
 }
+
+/* Toast enter/exit (StudioToast) */
+@keyframes hf-toast-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes hf-toast-out {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
+.hf-toast-enter {
+  animation: hf-toast-in 160ms ease-out;
+}
+
+.hf-toast-exit {
+  animation: hf-toast-out 160ms ease-in forwards;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-toast-enter,
+  .hf-toast-exit {
+    animation: none;
+  }
+  .hf-toast-exit {
+    opacity: 0;
+  }
+}
+
+/* Overlay/backdrop entrance — the heaviest visual changes shouldn't pop in */
+@keyframes hf-backdrop-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+.hf-backdrop-in {
+  animation: hf-backdrop-in 150ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-backdrop-in {
+    animation: none;
+  }
+}

package/src/utils/sdkResolverShadow.test.ts

@@ -98,6 +98,23 @@ describe("A. Flag gating", () => {
     expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
   });
 
+  it("A2c: empty session → ONE tagged session_empty event per session, no attempt", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    flushAttemptCounts(); // drain counts left by earlier tests
+    const session = await openComposition("<!DOCTYPE html><html><body></body></html>");
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "blue" }];
+    runResolverShadow(session, "hf-anything", ops);
+    runResolverShadow(session, "hf-other", ops); // repeat edits do not re-emit
+    const events = trackedEvents.filter((e) => e.event === "sdk_resolver_shadow");
+    // The modeling gap stays VISIBLE (silence would blind the tripwire to the
+    // exact class that exposed the template-comp bug) but is distinguishable
+    // and rate-limited to once per session instance.
+    expect(events).toHaveLength(1);
+    expect(events[0]?.props.sessionEmpty).toBe(true);
+    expect(JSON.stringify(events[0]?.props.mismatches)).toContain("session_empty");
+    expect(flushAttemptCounts()).toBeNull(); // can't cut over → not in the denominator
+  });
+
   it("A3: shadow depends ONLY on shadow flag, not on STUDIO_SDK_CUTOVER_ENABLED", async () => {
     // The mock always returns STUDIO_SDK_CUTOVER_ENABLED=false. Use a divergence
     // (poisoned session) so the flag-on case emits; flag-off must stay silent.
@@ -268,7 +285,12 @@ describe("C. Resolver-parity detection", () => {
 
   it("C8 sourceHfIdCount: emitted element_not_found carries source occurrence count", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
-    const session = { getElement: () => null, getElements: () => [] } as unknown as Composition;
+    // One unrelated element so the session isn't "empty" (empty sessions are
+    // skipped as structural modeling gaps) — it just can't resolve hf-dup.
+    const session = {
+      getElement: () => null,
+      getElements: () => [{ id: "hf-other" }],
+    } as unknown as Composition;
     // id present twice in source (duplicate-id ambiguity) but absent from session
     const source = `<div data-hf-id="hf-dup">a</div><div data-hf-id="hf-dup">b</div>`;
     runResolverShadow(
@@ -282,7 +304,10 @@ describe("C. Resolver-parity detection", () => {
 
   it("C8 sourceLooseMatchOnly: hfId matches source only as plain text, not a data-hf-id attribute", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
-    const session = { getElement: () => null, getElements: () => [] } as unknown as Composition;
+    const session = {
+      getElement: () => null,
+      getElements: () => [{ id: "hf-other" }],
+    } as unknown as Composition;
     // "hf-widget" appears only inside a class name, never as data-hf-id="hf-widget".
     const source = `<div class="hf-widget-container">no attribute match here</div>`;
     runResolverShadow(
@@ -436,7 +461,7 @@ describe("F. recordResolverParity", () => {
     expect(ev?.sourceHfIdCount).toBeUndefined();
   });
 
-  it("fails open: a readSource error still emits (no suppression)", async () => {
+  it("fails open: a readSource error still emits (no suppression), tagged sourceReadFailed", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
     const session = await openComposition(BASE_HTML);
     await recordResolverParity(session, "hf-missing", "setTiming", () =>
@@ -445,6 +470,31 @@ describe("F. recordResolverParity", () => {
     const ev = lastShadow();
     expect(ev?.mismatchCount).toBe(1);
     expect(ev?.sourceHfIdCount).toBeUndefined();
+    // Distinguishes "reader threw" from "no reader wired" — every wild emission
+    // of the setTiming class had an absent sourceHfIdCount and the two cases
+    // were indistinguishable in telemetry.
+    expect(ev?.sourceReadFailed).toBe(true);
+  });
+
+  it("does not tag sourceReadFailed when no reader is supplied", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-missing", "setTiming");
+    expect(lastShadow()?.sourceReadFailed).toBeUndefined();
+  });
+
+  it("empty session → ONE tagged session_empty event, no attempt, no element_not_found", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    flushAttemptCounts(); // drain any counts left by earlier tests
+    const session = await openComposition("<!DOCTYPE html><html><body></body></html>");
+    await recordResolverParity(session, "hf-anything", "setTiming");
+    await recordResolverParity(session, "hf-other", "setTiming"); // no re-emit
+    const events = trackedEvents.filter((e) => e.event === "sdk_resolver_shadow");
+    expect(events).toHaveLength(1);
+    expect(events[0]?.props.sessionEmpty).toBe(true);
+    expect(JSON.stringify(events[0]?.props.mismatches)).toContain("session_empty");
+    expect(JSON.stringify(events[0]?.props.mismatches)).not.toContain("element_not_found");
+    expect(flushAttemptCounts()).toBeNull(); // can't cut over → not in the denominator
   });
 
   it("tags sourceLooseMatchOnly when hfId matches source only as plain text, not a data-hf-id attribute", async () => {

package/src/utils/sdkResolverShadow.ts

@@ -24,7 +24,12 @@ import { trackStudioEvent, flushViaBeacon } from "./studioTelemetry";
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface SdkResolverMismatch {
-  kind: "element_not_found" | "value_mismatch" | "dispatch_error" | "animation_not_found";
+  kind:
+    | "element_not_found"
+    | "value_mismatch"
+    | "dispatch_error"
+    | "animation_not_found"
+    | "session_empty";
   hfId?: string;
   animationId?: string;
   property?: string;
@@ -347,6 +352,34 @@ function redactMismatches(mismatches: SdkResolverMismatch[]): SdkResolverMismatc
  * (see below). The session is shared with the cutover path, so it MUST end the
  * call exactly as it started.
  */
+// Sessions whose empty-session modeling gap has already been reported — one
+// event per session instance, not one per edit (the per-edit storm is noise;
+// the EXISTENCE of the gap is the signal).
+const emptySessionReported = new WeakSet<Composition>();
+
+/**
+ * An empty session structurally cannot resolve ANY id — a modeling gap (empty
+ * file, comp shape the SDK can't parse into elements), not a resolver
+ * divergence, and it can't cut over either, so it stays out of the attempt
+ * denominator. But silence would blind the tripwire to exactly the class that
+ * exposed the template-comp bug — so emit ONE distinguishable `session_empty`
+ * event per session, then skip. Returns true when the caller should skip.
+ */
+function reportEmptySession(session: Composition, opLabel: string): boolean {
+  if (session.getElements().length !== 0) return false;
+  if (!emptySessionReported.has(session)) {
+    emptySessionReported.add(session);
+    trackStudioEvent("sdk_resolver_shadow", {
+      opLabel,
+      sessionEmpty: true,
+      sessionElementCount: 0,
+      mismatchCount: 1,
+      mismatches: JSON.stringify([{ kind: "session_empty" } satisfies SdkResolverMismatch]),
+    });
+  }
+  return true;
+}
+
 export function runResolverShadow(
   session: Composition,
   hfId: string | null | undefined,
@@ -356,6 +389,7 @@ export function runResolverShadow(
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!hfId) return;
   try {
+    if (reportEmptySession(session, "dom-edit")) return;
     recordAttempt("dom-edit");
     const mismatches = sdkResolverShadowCheck(session, hfId, ops, sourceContent);
     // Emit only on divergence — parity is silent, matching recordResolverParity
@@ -409,6 +443,7 @@ export async function recordResolverParity(
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !hfId) return;
   try {
+    if (reportEmptySession(session, opLabel)) return;
     recordAttempt(opLabel);
     if (resolveSnapshot(session, hfId)) return; // resolves — parity, nothing to record
     // Capture BEFORE any await: this call is fire-and-forget (`void recordResolverParity(...)`)
@@ -419,11 +454,13 @@ export async function recordResolverParity(
     const sessionElementCount = session.getElements().length;
     // Cheap check passed above, so the source read only runs on a real divergence.
     let source: string | undefined;
+    let sourceReadFailed = false;
     if (readSource) {
       try {
         source = await readSource();
       } catch {
         source = undefined; // fail-open: a read error must not drop a real divergence
+        sourceReadFailed = true;
       }
     }
     // Runtime-generated node the static parse can't model — suppress (mirrors the dom-edit path).
@@ -444,6 +481,9 @@ export async function recordResolverParity(
       // Lets telemetry consumers filter this cohort without parsing the
       // sourceHfIdCount comment above.
       ...(strictCount === 0 ? { sourceLooseMatchOnly: true } : {}),
+      // The reader was wired but threw — distinguishes "read failed, emitted
+      // fail-open without the suppression/count checks" from "no reader wired".
+      ...(sourceReadFailed ? { sourceReadFailed: true } : {}),
       mismatchCount: 1,
       mismatches: JSON.stringify([
         { kind: "element_not_found", hfId } satisfies SdkResolverMismatch,

package/src/utils/studioPendingEdits.test.ts

@@ -0,0 +1,43 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import {
+  addStudioPendingEditFlushListener,
+  flushStudioPendingEdits,
+  trackStudioPendingEdit,
+} from "./studioPendingEdits";
+
+describe("studio pending edit flush", () => {
+  it("waits for mounted panels to persist pending local edits", async () => {
+    const persist = vi.fn(async () => undefined);
+    const remove = addStudioPendingEditFlushListener(persist);
+
+    try {
+      await flushStudioPendingEdits();
+      expect(persist).toHaveBeenCalledTimes(1);
+    } finally {
+      remove();
+    }
+  });
+
+  it("waits for edits already started by unmounted panels", async () => {
+    const steps: string[] = [];
+    let resolvePersist!: () => void;
+    trackStudioPendingEdit(
+      new Promise<void>((resolve) => {
+        resolvePersist = resolve;
+      }).then(() => {
+        steps.push("persisted");
+      }),
+    );
+
+    const flushed = flushStudioPendingEdits().then(() => {
+      steps.push("flushed");
+    });
+    await Promise.resolve();
+    expect(steps).toEqual([]);
+
+    resolvePersist();
+    await flushed;
+    expect(steps).toEqual(["persisted", "flushed"]);
+  });
+});

package/src/utils/studioPendingEdits.ts

@@ -0,0 +1,45 @@
+const STUDIO_FLUSH_PENDING_EDITS_EVENT = "hf-studio-flush-pending-edits";
+
+interface StudioFlushPendingEditsDetail {
+  promises: Array<Promise<unknown>>;
+}
+
+const pendingEditPromises = new Set<Promise<unknown>>();
+
+export function trackStudioPendingEdit(
+  result: Promise<unknown> | unknown,
+): Promise<unknown> | undefined {
+  if (!result) return undefined;
+  const promise = Promise.resolve(result);
+  pendingEditPromises.add(promise);
+  promise.then(
+    () => pendingEditPromises.delete(promise),
+    () => pendingEditPromises.delete(promise),
+  );
+  return promise;
+}
+
+export async function flushStudioPendingEdits(): Promise<void> {
+  const detail: StudioFlushPendingEditsDetail = { promises: [] };
+  window.dispatchEvent(
+    new CustomEvent<StudioFlushPendingEditsDetail>(STUDIO_FLUSH_PENDING_EDITS_EVENT, { detail }),
+  );
+  while (detail.promises.length > 0 || pendingEditPromises.size > 0) {
+    const promises = [...detail.promises, ...pendingEditPromises];
+    detail.promises = [];
+    await Promise.allSettled(promises);
+  }
+}
+
+export function addStudioPendingEditFlushListener(
+  handler: () => Promise<unknown> | unknown,
+): () => void {
+  const listener = (event: Event) => {
+    const detail = (event as CustomEvent<StudioFlushPendingEditsDetail>).detail;
+    if (!detail?.promises) return;
+    const promise = trackStudioPendingEdit(handler());
+    if (promise) detail.promises.push(promise);
+  };
+  window.addEventListener(STUDIO_FLUSH_PENDING_EDITS_EVENT, listener);
+  return () => window.removeEventListener(STUDIO_FLUSH_PENDING_EDITS_EVENT, listener);
+}

package/src/utils/studioUiPreferences.ts

@@ -7,6 +7,7 @@ export interface StoredPreviewZoomState {
 export interface StudioUiPreferences {
   leftCollapsed?: boolean;
   timelineVisible?: boolean;
+  timelineHeight?: number;
   playbackRate?: number;
   audioMuted?: boolean;
   previewZoom?: StoredPreviewZoomState;
@@ -48,6 +49,9 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.timelineVisible === "boolean") {
       preferences.timelineVisible = parsed.timelineVisible;
     }
+    if (typeof parsed.timelineHeight === "number" && Number.isFinite(parsed.timelineHeight)) {
+      preferences.timelineHeight = parsed.timelineHeight;
+    }
     if (typeof parsed.playbackRate === "number" && Number.isFinite(parsed.playbackRate)) {
       preferences.playbackRate = parsed.playbackRate;
     }