@hyperframes/studio 0.8.6 → 0.8.8

package/src/captions/store.ts

@@ -9,17 +9,36 @@ import {
 
 let nextSplitId = 0;
 
+const HISTORY_CAP = 50;
+/** Coalesce rapid same-target edits (typing, nudging) into one history entry. */
+const HISTORY_COALESCE_MS = 800;
+
 interface CaptionState {
   isEditMode: boolean;
+  /** User explicitly exited caption editing — suppresses auto re-activation. */
+  dismissed: boolean;
   model: CaptionModel | null;
   selectedSegmentIds: Set<string>;
   selectedGroupId: string | null;
   sourceFilePath: string | null;
+  /** Load/save failure surfaced to the user (null = healthy). */
+  syncError: string | null;
+  /** Registered by useCaptionSync so error banners can retry the save. */
+  retrySave: (() => void) | null;
+
+  // Undo/redo (in-memory model snapshots)
+  past: CaptionModel[];
+  future: CaptionModel[];
+  undo: () => CaptionModel | null;
+  redo: () => CaptionModel | null;
 
   // Basic
   setEditMode: (active: boolean) => void;
+  setDismissed: (dismissed: boolean) => void;
   setModel: (model: CaptionModel | null) => void;
   setSourceFilePath: (path: string | null) => void;
+  setSyncError: (error: string | null) => void;
+  setRetrySave: (fn: (() => void) | null) => void;
 
   // Selection
   selectSegment: (id: string, additive?: boolean) => void;
@@ -53,19 +72,70 @@ interface CaptionState {
 
 const initialState = {
   isEditMode: false,
+  dismissed: false,
   model: null,
   selectedSegmentIds: new Set<string>(),
   selectedGroupId: null,
   sourceFilePath: null,
+  syncError: null,
+  retrySave: null,
+  past: [] as CaptionModel[],
+  future: [] as CaptionModel[],
 };
 
+// Coalescing bookkeeping lives outside the store — it is not renderable state.
+let lastHistoryKey: string | null = null;
+let lastHistoryAt = 0;
+
+/**
+ * Snapshot the current model onto the undo stack before a mutation.
+ * `key` identifies the edit target so rapid repeats (typing a value, arrow-key
+ * nudging) coalesce into a single entry instead of one per keystroke.
+ */
+function pushHistory(
+  state: Pick<CaptionState, "model" | "past">,
+  key: string,
+): Partial<Pick<CaptionState, "past" | "future">> {
+  if (!state.model) return {};
+  const now = Date.now();
+  if (lastHistoryKey === key && now - lastHistoryAt < HISTORY_COALESCE_MS) {
+    lastHistoryAt = now;
+    return { future: [] };
+  }
+  lastHistoryKey = key;
+  lastHistoryAt = now;
+  const past = [...state.past, state.model].slice(-HISTORY_CAP);
+  return { past, future: [] };
+}
+
 export const useCaptionStore = create<CaptionState>((set, get) => ({
   ...initialState,
 
   // Basic
   setEditMode: (active) => set({ isEditMode: active }),
+  setDismissed: (dismissed) => set({ dismissed }),
   setModel: (model) => set({ model }),
   setSourceFilePath: (path) => set({ sourceFilePath: path }),
+  setSyncError: (error) => set({ syncError: error }),
+  setRetrySave: (fn) => set({ retrySave: fn }),
+
+  // Undo/redo
+  undo: () => {
+    const { model, past, future } = get();
+    const prev = past[past.length - 1];
+    if (!prev || !model) return null;
+    lastHistoryKey = null;
+    set({ model: prev, past: past.slice(0, -1), future: [...future, model] });
+    return prev;
+  },
+  redo: () => {
+    const { model, past, future } = get();
+    const next = future[future.length - 1];
+    if (!next || !model) return null;
+    lastHistoryKey = null;
+    set({ model: next, past: [...past, model].slice(-HISTORY_CAP), future: future.slice(0, -1) });
+    return next;
+  },
 
   // Selection
   selectSegment: (id, additive = false) =>
@@ -111,7 +181,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
       if (!segment) return {};
       const segments = new Map(state.model.segments);
       segments.set(segmentId, { ...segment, style: { ...segment.style, ...style } });
-      return { model: { ...state.model, segments } };
+      return {
+        ...pushHistory(state, `seg-style:${segmentId}`),
+        model: { ...state.model, segments },
+      };
     }),
 
   updateSegmentText: (segmentId, text) =>
@@ -121,7 +194,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
       if (!segment) return {};
       const segments = new Map(state.model.segments);
       segments.set(segmentId, { ...segment, text });
-      return { model: { ...state.model, segments } };
+      return {
+        ...pushHistory(state, `seg-text:${segmentId}`),
+        model: { ...state.model, segments },
+      };
     }),
 
   updateSegmentTiming: (segmentId, start, end) =>
@@ -131,7 +207,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
       if (!segment) return {};
       const segments = new Map(state.model.segments);
       segments.set(segmentId, { ...segment, start, end });
-      return { model: { ...state.model, segments } };
+      return {
+        ...pushHistory(state, `seg-timing:${segmentId}`),
+        model: { ...state.model, segments },
+      };
     }),
 
   // Group mutations
@@ -142,7 +221,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
       if (!group) return {};
       const groups = new Map(state.model.groups);
       groups.set(groupId, { ...group, style: { ...group.style, ...style } });
-      return { model: { ...state.model, groups } };
+      return {
+        ...pushHistory(state, `group-style:${groupId}`),
+        model: { ...state.model, groups },
+      };
     }),
 
   updateGroupContainer: (groupId, container) =>
@@ -155,7 +237,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
         ...group,
         containerStyle: { ...group.containerStyle, ...container },
       });
-      return { model: { ...state.model, groups } };
+      return {
+        ...pushHistory(state, `group-container:${groupId}`),
+        model: { ...state.model, groups },
+      };
     }),
 
   updateGroupAnimation: (groupId, phase, animation) =>
@@ -173,7 +258,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
         ...group,
         animation: { ...group.animation, [phase]: mergedPhase },
       });
-      return { model: { ...state.model, groups } };
+      return {
+        ...pushHistory(state, `group-anim:${groupId}:${phase}`),
+        model: { ...state.model, groups },
+      };
     }),
 
   splitGroup: (groupId, atSegmentId) =>
@@ -206,7 +294,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
         }
       });
 
-      return { model: { ...state.model, groups, segments, groupOrder } };
+      return {
+        ...pushHistory(state, `split:${groupId}:${atSegmentId}:${nextSplitId}`),
+        model: { ...state.model, groups, segments, groupOrder },
+      };
     }),
 
   mergeGroups: (groupId1, groupId2) =>
@@ -236,7 +327,11 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
       // Clear selection if it referenced group2
       const selectedGroupId = state.selectedGroupId === groupId2 ? null : state.selectedGroupId;
 
-      return { model: { ...state.model, groups, segments, groupOrder }, selectedGroupId };
+      return {
+        ...pushHistory(state, `merge:${groupId1}:${groupId2}`),
+        model: { ...state.model, groups, segments, groupOrder },
+        selectedGroupId,
+      };
     }),
 
   // Bulk
@@ -250,7 +345,10 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
           segments.set(segmentId, { ...segment, style: { ...segment.style, ...style } });
         }
       }
-      return { model: { ...state.model, segments } };
+      return {
+        ...pushHistory(state, `sel-style:${[...state.selectedSegmentIds].join(",")}`),
+        model: { ...state.model, segments },
+      };
     }),
 
   applyAnimationToAll: (animation) =>
@@ -260,13 +358,21 @@ export const useCaptionStore = create<CaptionState>((set, get) => ({
       for (const [id, group] of groups) {
         groups.set(id, { ...group, animation });
       }
-      return { model: { ...state.model, groups } };
+      return {
+        ...pushHistory(state, "apply-anim-all"),
+        model: { ...state.model, groups },
+      };
     }),
 
-  // Reset
-  reset: () =>
-    set({
+  // Reset — keeps retrySave (registered once by useCaptionSync for the app's lifetime)
+  reset: () => {
+    lastHistoryKey = null;
+    set((state) => ({
       ...initialState,
+      retrySave: state.retrySave,
       selectedSegmentIds: new Set<string>(),
-    }),
+      past: [],
+      future: [],
+    }));
+  },
 }));

package/src/components/EditorShell.selectionSync.test.tsx

@@ -52,7 +52,6 @@ vi.mock("./nle/PreviewPane", () => ({ PreviewPane: () => null }));
 vi.mock("./nle/PreviewOverlays", () => ({ PreviewOverlays: () => null }));
 vi.mock("./nle/TimelinePane", () => ({ TimelinePane: () => null }));
 vi.mock("../captions/components/CaptionTimeline", () => ({ CaptionTimeline: () => null }));
-vi.mock("./StudioFeedbackBar", () => ({ StudioFeedbackBar: () => null }));
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
@@ -82,6 +81,7 @@ describe("EditorShell timeline selection sync", () => {
           handleTimelineElementResize={vi.fn()}
           handleTimelineGroupResize={vi.fn()}
           handleToggleTrackHidden={vi.fn()}
+          setAudioGroupAttribute={{ setLive: vi.fn(), setQuiet: vi.fn() }}
           handleBlockedTimelineEdit={vi.fn()}
           handleTimelineElementSplit={vi.fn()}
           handleRazorSplit={vi.fn()}

package/src/components/EditorShell.tsx

@@ -85,6 +85,9 @@ export function EditorShell({
   handleTimelineElementResize,
   handleTimelineGroupResize,
   handleToggleTrackHidden,
+  setAudioGroupAttribute,
+  handleGroupClips,
+  setElementFxAttribute,
   handleBlockedTimelineEdit,
   handleTimelineElementSplit,
   handleRazorSplit,
@@ -135,6 +138,9 @@ export function EditorShell({
     handleTimelineElementResize,
     handleTimelineGroupResize,
     handleToggleTrackHidden,
+    setAudioGroupAttribute,
+    handleGroupClips,
+    setElementFxAttribute,
     handleBlockedTimelineEdit,
     handleTimelineElementSplit,
     handleRazorSplit,
@@ -231,6 +237,12 @@ function EditorShellBody({
 }: EditorShellBodyProps) {
   const { compositionStack, updateCompositionStack, containerRef } = useNLEContext();
 
+  // The caption track's blocks are seek targets; CaptionTimeline took an onSeek
+  // prop that nothing ever passed, so clicking a block did nothing.
+  const seekCaptionTime = useCallback((time: number) => {
+    usePlayerStore.getState().requestSeek(time);
+  }, []);
+
   // Keyboard: Escape to pop composition level
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -282,7 +294,7 @@ function EditorShellBody({
                   Captions
                 </span>
               </div>
-              <CaptionTimeline pixelsPerSecond={100} />
+              <CaptionTimeline pixelsPerSecond={100} onSeek={seekCaptionTime} />
             </div>
           ) : undefined
         }

package/src/components/StudioRightPanel.tsx

@@ -45,6 +45,7 @@ export function StudioRightPanel({
   domEditSaveTimestampRef,
   recordEdit,
   onToggleElementHidden,
+  onAutoGroupCarveSources,
   onAddMediaOverlay,
 }: StudioRightPanelProps) {
   const {
@@ -328,6 +329,7 @@ export function StudioRightPanel({
         copiedAgentPrompt={copiedAgentPrompt}
         onClearSelection={clearDomSelection}
         onToggleElementHidden={onToggleElementHidden}
+        onAutoGroupCarveSources={onAutoGroupCarveSources}
         onUngroup={handleUngroupSelection}
         onSetStyle={handleDomStyleCommit}
         onSetAttribute={handleDomAttributeCommit}

package/src/components/StudioRightPanel.types.ts

@@ -51,5 +51,6 @@ export interface StudioRightPanelProps extends StudioEditPersistenceProps {
     files: Record<string, { before: string; after: string }>;
   }) => Promise<void>;
   onToggleElementHidden?: ToggleHiddenHandler;
+  onAutoGroupCarveSources?: (clipIds: readonly string[], groupId: string) => Promise<void>;
   onAddMediaOverlay?: AddMediaOverlayHandler;
 }

package/src/components/editor/AnimationCard.tsx

@@ -197,7 +197,8 @@ export const AnimationCard = memo(function AnimationCard({
       <button
         type="button"
         onClick={() => setExpanded((v) => !v)}
-        className="flex w-full items-center gap-2 py-1.5"
+        aria-expanded={expanded}
+        className="flex w-full items-center gap-2 py-1.5 active:scale-[0.99]"
       >
         <span
           className="rounded bg-panel-accent/10 px-1.5 py-0.5 text-[10px] font-semibold text-panel-accent"

package/src/components/editor/AnimationCardParts.tsx

@@ -46,8 +46,9 @@ function RemoveButton({ onClick, title }: { onClick: () => void; title: string }
     <button
       type="button"
       onClick={onClick}
-      className="flex-shrink-0 rounded p-0.5 text-neutral-600 transition-colors hover:bg-neutral-800 hover:text-red-400"
+      className="relative flex-shrink-0 rounded p-1.5 text-neutral-600 transition-colors hover:bg-neutral-800 hover:text-red-400 active:scale-[0.95]"
       title={title}
+      aria-label={title}
     >
       <svg
         width="12"
@@ -87,13 +88,15 @@ export function PropertyRow({
           </span>
           <button
             type="button"
+            role="switch"
+            aria-checked={isVisible}
             onClick={() => onCommit(isVisible ? "hidden" : "visible")}
-            className="flex-shrink-0 rounded-full transition-all duration-150 relative"
+            className="flex-shrink-0 rounded-full transition-colors duration-200 relative"
             style={{ width: 28, height: 16, background: isVisible ? P.accent : P.borderInput }}
             title={isVisible ? "Visible — click to hide" : "Hidden — click to show"}
           >
             <span
-              className="absolute top-[2px] left-0 rounded-full transition-transform duration-150"
+              className="absolute top-[2px] left-0 rounded-full transition-transform duration-200"
               style={{
                 width: 12,
                 height: 12,

package/src/components/editor/ArcPathControls.tsx

@@ -45,14 +45,17 @@ export const ArcPathControls = memo(function ArcPathControls({
         <span className={LABEL}>Arc Motion</span>
         <button
           type="button"
+          role="switch"
+          aria-checked={Boolean(arcPath.enabled)}
+          aria-label="Arc motion"
           onClick={handleToggle}
           disabled={disabled}
-          className="relative rounded-full transition-all duration-150"
+          className="relative rounded-full transition-colors duration-200"
           style={{ width: 28, height: 16, background: arcPath.enabled ? P.accent : P.borderInput }}
           title={arcPath.enabled ? "Disable arc motion" : "Enable arc motion"}
         >
           <span
-            className="absolute top-[2px] left-0 rounded-full transition-transform duration-150"
+            className="absolute top-[2px] left-0 rounded-full transition-transform duration-200"
             style={{
               width: 12,
               height: 12,
@@ -69,9 +72,12 @@ export const ArcPathControls = memo(function ArcPathControls({
             <span className={LABEL}>Auto-Rotate</span>
             <button
               type="button"
+              role="switch"
+              aria-checked={Boolean(arcPath.autoRotate)}
+              aria-label="Auto-rotate along path"
               onClick={handleAutoRotate}
               disabled={disabled}
-              className="relative rounded-full transition-all duration-150"
+              className="relative rounded-full transition-colors duration-200"
               style={{
                 width: 28,
                 height: 16,
@@ -84,7 +90,7 @@ export const ArcPathControls = memo(function ArcPathControls({
               }
             >
               <span
-                className="absolute top-[2px] left-0 rounded-full transition-transform duration-150"
+                className="absolute top-[2px] left-0 rounded-full transition-transform duration-200"
                 style={{
                   width: 12,
                   height: 12,

package/src/components/editor/BlockParamsPanel.test.tsx

@@ -0,0 +1,170 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { BlockParam } from "@hyperframes/core/registry";
+import { FileManagerProvider } from "../../contexts/FileManagerContext";
+import type { useFileManager } from "../../hooks/useFileManager";
+import { StudioPlaybackProvider, type StudioPlaybackValue } from "../../contexts/StudioContext";
+import { BlockParamsPanel } from "./BlockParamsPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.useFakeTimers();
+
+const PARAMS: BlockParam[] = [
+  { key: "--bg-color", label: "Background", type: "color", default: "#0c0c0c" },
+  { key: "--text-color", label: "Text color", type: "color", default: "#fafafa" },
+];
+
+const playbackValue: StudioPlaybackValue = {
+  captionEditMode: false,
+  compositionLoading: false,
+  refreshKey: 0,
+  setRefreshKey: vi.fn(),
+  timelineElements: [],
+  isPlaying: false,
+  refreshPreviewDocumentVersion: vi.fn(),
+};
+
+function makeFileManager(content: { value: string }) {
+  const readProjectFile = vi.fn(async () => content.value);
+  const writeProjectFile = vi.fn(async (_path: string, next: string) => {
+    content.value = next;
+  });
+  // The panel only touches read/writeProjectFile; the rest of the context
+  // surface is irrelevant to these tests.
+  const value = { readProjectFile, writeProjectFile } as unknown as ReturnType<
+    typeof useFileManager
+  >;
+  return { value, readProjectFile, writeProjectFile };
+}
+
+let root: Root | null = null;
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+  vi.clearAllTimers();
+});
+
+function renderPanel(fileManager: ReturnType<typeof makeFileManager>["value"]) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(
+      <StudioPlaybackProvider value={playbackValue}>
+        <FileManagerProvider value={fileManager}>
+          <BlockParamsPanel
+            blockName="vfx-demo"
+            blockTitle="VFX Demo"
+            params={PARAMS}
+            compositionPath="compositions/vfx-demo.html"
+            onClose={vi.fn()}
+          />
+        </FileManagerProvider>
+      </StudioPlaybackProvider>,
+    );
+  });
+}
+
+function changeParam(label: string, next: string) {
+  const input = document.querySelector<HTMLInputElement>(`input[aria-label="${label} value"]`);
+  if (!input) throw new Error(`no input for ${label}`);
+  act(() => {
+    const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+    setter?.call(input, next);
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+  });
+}
+
+async function flushCommit() {
+  await act(async () => {
+    vi.advanceTimersByTime(350);
+    // Drain the read → guard → write promise chain.
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
+describe("BlockParamsPanel commit safety", () => {
+  it("refuses a multi-occurrence value and never mutates the unrelated sibling", async () => {
+    // The param's default (#0c0c0c) also appears on an UNRELATED element. The
+    // panel has no way to tell which occurrence belongs to the param, so it
+    // must refuse rather than risk rewriting `.unrelated`. Nothing is written.
+    const content = {
+      value: ".block { background: #0c0c0c; } .unrelated { border-color: #0c0c0c; }",
+    };
+    const before = content.value;
+    const fm = makeFileManager(content);
+    renderPanel(fm.value);
+
+    changeParam("Background", "#123456");
+    await flushCommit();
+
+    expect(fm.writeProjectFile).not.toHaveBeenCalled();
+    expect(content.value).toBe(before); // both occurrences untouched
+    expect(content.value).toContain(".unrelated { border-color: #0c0c0c; }");
+    expect(document.body.textContent).toContain("appears 2×");
+  });
+
+  it("writes a unique occurrence with token boundaries (no substring corruption)", async () => {
+    // #0c0c0c is unique here — the 8-digit #0c0c0cff must NOT match (token
+    // boundary), so exactly one occurrence rewrites and the hex8 is preserved.
+    const content = {
+      value: ".a { background: #0c0c0c; } .c { color: #0c0c0cff; }",
+    };
+    const fm = makeFileManager(content);
+    renderPanel(fm.value);
+
+    changeParam("Background", "#123456");
+    await flushCommit();
+
+    expect(fm.writeProjectFile).toHaveBeenCalledTimes(1);
+    expect(content.value).toBe(".a { background: #123456; } .c { color: #0c0c0cff; }");
+  });
+
+  it("refuses once a previously-unique value later collides with unrelated content", async () => {
+    const content = {
+      value: ".a { background: #0c0c0c; } .b { color: #fafafa; }",
+    };
+    const fm = makeFileManager(content);
+    renderPanel(fm.value);
+
+    // #0c0c0c is unique → first commit writes; now #fafafa appears 2×.
+    changeParam("Background", "#fafafa");
+    await flushCommit();
+    expect(content.value).toBe(".a { background: #fafafa; } .b { color: #fafafa; }");
+
+    // Next edit's current value (#fafafa) now matches 2× → refuse.
+    changeParam("Background", "#ff0000");
+    await flushCommit();
+
+    expect(fm.writeProjectFile).toHaveBeenCalledTimes(1); // no second write
+    expect(content.value).toBe(".a { background: #fafafa; } .b { color: #fafafa; }");
+    expect(document.body.textContent).toContain("appears 2×");
+  });
+
+  it("keeps a pending commit for one param when another param is edited", async () => {
+    const content = {
+      value: ".a { background: #0c0c0c; } .b { color: #fafafa; }",
+    };
+    const fm = makeFileManager(content);
+    renderPanel(fm.value);
+
+    // Edit both params back-to-back within the 300ms debounce window: the
+    // second edit must not cancel the first param's pending commit.
+    changeParam("Background", "#111111");
+    changeParam("Text color", "#222222");
+    await flushCommit();
+    await flushCommit();
+
+    expect(content.value).toContain("#111111");
+    expect(content.value).toContain("#222222");
+  });
+});