@hyperframes/studio 0.8.78 → 0.8.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.78",
+  "version": "0.8.80",
   "description": "",
   "repository": {
     "type": "git",
@@ -52,12 +52,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.78",
-    "@hyperframes/sdk": "0.8.78",
-    "@hyperframes/player": "0.8.78",
-    "@hyperframes/shader-transitions": "0.8.78",
-    "@hyperframes/studio-server": "0.8.78",
-    "@hyperframes/core": "0.8.78"
+    "@hyperframes/core": "0.8.80",
+    "@hyperframes/parsers": "0.8.80",
+    "@hyperframes/player": "0.8.80",
+    "@hyperframes/sdk": "0.8.80",
+    "@hyperframes/shader-transitions": "0.8.80",
+    "@hyperframes/studio-server": "0.8.80"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -73,7 +73,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.78"
+    "@hyperframes/producer": "0.8.80"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -209,6 +209,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
       refreshFileTree: fileManager.refreshFileTree,
       reloadPreview,
       showToast,
+      dismissToast,
     },
     previewIframeRef,
     setRightCollapsed: panelLayout.setRightCollapsed,
@@ -239,6 +240,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,
     handleDomEditElementDelete: domEditDeleteBridge,
     previewIframeRef,
+    waitForPendingDomEditSaves: previewPersistence.waitForPendingDomEditSaves,
   });
   const appHotkeys = useAppHotkeys({
     handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,
@@ -259,7 +261,10 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     handleDuplicate,
     onResetKeyframes: () => resetKeyframesRef.current(),
     onDeleteSelectedKeyframes: () => deleteSelectedKeyframesRef.current(),
-    onAfterUndoRedo: () => invalidateGsapCacheRef.current(),
+    onAfterUndoRedo: (restore) => {
+      invalidateGsapCacheRef.current();
+      timelineEditing.restoreLiveLanes(restore);
+    },
     onGroupSelection: () => domEditSessionRef.current.handleGroupSelection(),
     onUngroupSelection: () => domEditSessionRef.current.handleUngroupSelection(),
     activeCompPath,

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

@@ -87,7 +87,7 @@ describe("TimelineFxPopover", () => {
     act(() => {
       button?.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
     });
-    expect(onChainPreview).toHaveBeenCalledWith(EMPTY_CHAIN);
+    expect(onChainPreview).toHaveBeenCalledWith(EMPTY_CHAIN, true);
   });
 
   it("Escape closes without letting the keystroke propagate past the popover", () => {

package/src/components/editor/TimelineFxPopover.tsx

@@ -75,7 +75,7 @@ export interface TimelineFxPopoverProps {
    *  selected clip's attribute — the caller resolves which). */
   onChainChange: (next: HfAudioFxChain) => void;
   /** Preview a hypothetical chain on the running graph without persisting. */
-  onChainPreview?: (next: HfAudioFxChain) => void;
+  onChainPreview?: (next: HfAudioFxChain, ended?: boolean) => void;
   onAuditionTransport?: (on: boolean) => void;
   /** Select the target the way clicking it in the timeline does, and ensure
    *  the property panel's Audio FX group is expanded. */

package/src/components/editor/manualEdits.ts

@@ -11,6 +11,7 @@ export {
 
 export {
   readFileChangeAffectedCompositions,
+  readFileChangeAffectsPreview,
   readFileChangeField,
   readStudioFileChangePath,
 } from "./manualEditsParsing";

package/src/components/editor/manualEditsParsing.ts

@@ -34,6 +34,10 @@ export function readStudioFileChangePath(payload: unknown): string | null {
   return path === null ? null : normalizeStudioFileChangePath(path);
 }
 
+export function readFileChangeAffectsPreview(payload: unknown): boolean {
+  return asPayloadRecord(payload)?.affectsPreview !== false;
+}
+
 /**
  * The compositions whose thumbnails a change can alter, or `null` for all of them. Anything
  * but a list of paths (an older server, the Vite dev host) reads as "all".

package/src/components/editor/useFxAudition.ts

@@ -11,7 +11,7 @@ import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
 
 export function useFxAudition(
   chain: HfAudioFxChain,
-  onChainPreview: ((chain: HfAudioFxChain) => void) | undefined,
+  onChainPreview: ((chain: HfAudioFxChain, ended?: boolean) => void) | undefined,
   onAuditionTransport: ((on: boolean) => void) | undefined,
 ) {
   /**
@@ -45,7 +45,7 @@ export function useFxAudition(
         // Stop before reverting, for the mirror of that reason — the last thing
         // heard should be the preset, not a frame of the chain coming back.
         onAuditionTransport?.(false);
-        onChainPreview(auditionBase.current);
+        onChainPreview(auditionBase.current, true);
         auditionBase.current = null;
       }
     },
@@ -96,7 +96,7 @@ export function useFxAudition(
     () => () => {
       if (auditionBase.current) {
         transportRef.current?.(false);
-        previewRef.current?.(auditionBase.current);
+        previewRef.current?.(auditionBase.current, true);
       }
     },
     [],

package/src/components/nle/useTimelineEditCallbacks.ts

@@ -1,3 +1,4 @@
+import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
 import { useCallback, useMemo } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { TimelineElement } from "../../player";
@@ -40,7 +41,13 @@ export interface TimelineEditCallbackDeps {
   handleToggleTrackHidden: (track: number, hidden: boolean) => Promise<void> | void;
   setAudioGroupAttribute: {
     setLive: (groupId: string, attr: string, value: string | null) => void;
-    setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
+    revertLive?: (groupId: string, attr: string) => void;
+    setQuiet: (
+      groupId: string,
+      attr: string,
+      value: string | null,
+      label: string,
+    ) => Promise<TimelineEditOutcome | void>;
   };
   handleBlockedTimelineEdit: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
@@ -55,12 +62,13 @@ export interface TimelineEditCallbackDeps {
   /** C1's single-clip FX write, addressed by the clip itself. */
   setElementFxAttribute?: {
     setLive: (element: TimelineElement, attr: string, value: string | null) => void;
+    revertLive?: (element: TimelineElement, attr: string) => void;
     setQuiet: (
       element: TimelineElement,
       attr: string,
       value: string | null,
       label: string,
-    ) => Promise<void>;
+    ) => Promise<TimelineEditOutcome | void>;
   };
 }
 
@@ -210,9 +218,11 @@ export function useTimelineEditCallbacks({
       onToggleTrackHidden: handleToggleTrackHidden,
       onSetAudioGroupAttributeLive: setAudioGroupAttribute.setLive,
       onSetAudioGroupAttributeQuiet: setAudioGroupAttribute.setQuiet,
+      onRevertAudioGroupAttributeLive: setAudioGroupAttribute.revertLive,
       onGroupClips: handleGroupClips,
       onSetElementAttributeLive: setElementFxAttribute?.setLive,
       onSetElementAttributeQuiet: setElementFxAttribute?.setQuiet,
+      onRevertElementAttributeLive: setElementFxAttribute?.revertLive,
       onBlockedEditAttempt: handleBlockedTimelineEdit,
       onSplitElement: handleTimelineElementSplit,
       onRazorSplit: handleRazorSplit,

package/src/contexts/DomEditContext.tsx

@@ -13,6 +13,7 @@ export interface DomEditActionsValue extends Pick<
   | "handlePreviewCanvasPointerLeave"
   | "applyDomSelection"
   | "clearDomSelection"
+  | "refreshDomEditSelectionFromPreview"
   | "handleDomStyleCommit"
   | "handleDomStyleCommitForSelection"
   | "handleDomAttributeCommit"
@@ -155,6 +156,7 @@ export function DomEditProvider({
     handlePreviewCanvasPointerLeave,
     applyDomSelection,
     clearDomSelection,
+    refreshDomEditSelectionFromPreview,
     handleDomStyleCommit,
     handleDomStyleCommitForSelection,
     handleDomAttributeCommit,
@@ -248,6 +250,7 @@ export function DomEditProvider({
       handlePreviewCanvasPointerLeave,
       applyDomSelection,
       clearDomSelection,
+      refreshDomEditSelectionFromPreview,
       handleDomStyleCommit,
       handleDomStyleCommitForSelection,
       handleDomAttributeCommit,
@@ -322,6 +325,7 @@ export function DomEditProvider({
       handlePreviewCanvasPointerLeave,
       applyDomSelection,
       clearDomSelection,
+      refreshDomEditSelectionFromPreview,
       handleDomStyleCommit,
       handleDomStyleCommitForSelection,
       handleDomAttributeCommit,

package/src/contexts/TimelineEditContext.tsx

@@ -44,9 +44,11 @@ export function TimelineEditProvider({
       value.onToggleTrackHidden,
       value.onSetAudioGroupAttributeLive,
       value.onSetAudioGroupAttributeQuiet,
+      value.onRevertAudioGroupAttributeLive,
       value.onGroupClips,
       value.onSetElementAttributeLive,
       value.onSetElementAttributeQuiet,
+      value.onRevertElementAttributeLive,
       value.onBlockedEditAttempt,
       value.onSplitElement,
       value.onRazorSplit,

package/src/hooks/liveLanes.ts

@@ -0,0 +1,147 @@
+import { useRef, useState } from "react";
+import { readTargetAttribute, type PatchTarget } from "./timelineEditingHelpers";
+
+/** Where a lane's value lives in source, so an undo can re-read it. */
+export interface LiveLaneSource {
+  path: string;
+  target: PatchTarget | null;
+  attr: string;
+}
+
+/** The files an undo or redo rewrote. */
+export interface LiveLaneRestore {
+  paths?: string[];
+  files?: Record<string, { restored: string }>;
+}
+
+/** Per-lane live-preview state: the value before a gesture, pending saves, the last verified value. */
+function createLiveLanes(project: () => string, composition: () => string) {
+  const before = new Map<string, string | null>();
+  const sources = new Map<string, LiveLaneSource>();
+  const pending = new Map<string, Set<number>>();
+  const verified = new Map<string, string | null>();
+  // Lanes whose before-value was read with no save pending, so it is what the file holds.
+  const clean = new Set<string>();
+  let saves = 0;
+  const take = (key: string): string | null | undefined => {
+    const claimed = before.has(key) ? (before.get(key) ?? null) : undefined;
+    before.delete(key);
+    clean.delete(key);
+    if (!pending.has(key)) sources.delete(key);
+    return claimed;
+  };
+  const overtaken = (key: string, save: number): boolean =>
+    [...(pending.get(key) ?? [])].some((newer) => newer > save);
+  const rebase = (key: string, value: string | null | undefined): void => {
+    if (value === undefined) {
+      clean.delete(key);
+      verified.delete(key);
+      return;
+    }
+    if (before.has(key)) before.set(key, value);
+    if (pending.has(key)) verified.set(key, value);
+    if (pending.has(key)) clean.delete(key);
+    else clean.add(key);
+  };
+  const scoped = (laneKey: string): string => `${project()}\n${composition()}\n${laneKey}`;
+  return {
+    preview(laneKey: string, readCurrent: () => string | null, source: LiveLaneSource): void {
+      const key = scoped(laneKey);
+      if (before.has(key)) return;
+      before.set(key, readCurrent());
+      sources.set(key, source);
+      if (!pending.has(key)) clean.add(key);
+    },
+    // A save. Its settle records what the file holds: `saved`, else the last value verified on
+    // this lane (a landed save, a read-back, or a clean before-value), never an unsaved one.
+    // Store and preview follow only while no newer save is pending and its composition is open,
+    // and the preview only while no drag is live.
+    claim(laneKey: string, apply: LiveLaneApply, source: LiveLaneSource): LiveLaneSave {
+      const key = scoped(laneKey);
+      const open = () => scoped(laneKey) === key;
+      const trusted = clean.has(key);
+      const claimed = take(key);
+      const mine = ++saves;
+      sources.set(key, source);
+      if (claimed !== undefined && trusted) verified.set(key, claimed);
+      pending.set(key, (pending.get(key) ?? new Set<number>()).add(mine));
+      const preview = (value: string | null) => {
+        if (open() && !before.has(key) && !overtaken(key, mine)) apply.preview(value);
+      };
+      return {
+        preview,
+        read(value) {
+          verified.set(key, value);
+        },
+        settle(saved) {
+          const inFlight = pending.get(key);
+          inFlight?.delete(mine);
+          if (saved !== undefined) verified.set(key, saved);
+          const value = verified.get(key);
+          // With no save left in flight the file can change under it (undo, an outside edit).
+          if (!inFlight?.size) {
+            pending.delete(key);
+            verified.delete(key);
+            if (!before.has(key)) sources.delete(key);
+          }
+          if (value === undefined || overtaken(key, mine) || !open()) return;
+          if (before.has(key)) {
+            before.set(key, value);
+            clean.add(key);
+          }
+          apply.store(value);
+          preview(value);
+        },
+      };
+    },
+    // A gesture refused before it saved: put its before-value back, which hands the lane
+    // back to any save still pending on it.
+    revert(laneKey: string, apply: LiveLaneApply): void {
+      const claimed = take(scoped(laneKey));
+      if (claimed === undefined) return;
+      apply.preview(claimed);
+      apply.store(claimed);
+    },
+    // An undo or redo rewrote files under the project's live gestures and pending saves, in any
+    // composition: each takes what the restored file holds, or stops trusting a value it cannot read.
+    restore({ paths = [], files }: LiveLaneRestore): void {
+      const inProject = `${project()}\n`;
+      for (const [key, source] of sources) {
+        if (key.startsWith(inProject) && paths.includes(source.path)) {
+          rebase(key, restoredValue(source, files));
+        }
+      }
+    },
+  };
+}
+
+function restoredValue({ path, target, attr }: LiveLaneSource, files: LiveLaneRestore["files"]) {
+  const html = files?.[path]?.restored;
+  return html === undefined || !target ? undefined : readTargetAttribute(html, target, attr);
+}
+
+/** A hook's live lanes, scoped to the project and composition open when each save starts. */
+export function useLiveLanes(
+  projectIdRef: { readonly current: string | null },
+  activeCompPath: string | null,
+) {
+  const compositionRef = useRef(activeCompPath);
+  compositionRef.current = activeCompPath;
+  const [lanes] = useState(() =>
+    createLiveLanes(
+      () => projectIdRef.current ?? "",
+      () => compositionRef.current ?? "",
+    ),
+  );
+  return lanes;
+}
+
+interface LiveLaneSave {
+  preview: (value: string | null) => void;
+  read: (value: string | null) => void;
+  settle: (saved?: string | null) => void;
+}
+interface LiveLaneApply {
+  preview: (value: string | null) => void;
+  store: (value: string | null) => void;
+}

package/src/hooks/timelineAudioGroupVolume.ts

@@ -1,4 +1,9 @@
-import { useCallback, useRef } from "react";
+import { useCallback } from "react";
+import {
+  failedTimelineSave,
+  projectForTimelineSave,
+  type TimelineEditOutcome,
+} from "./timelineEditPermission";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { usePlayerStore } from "../player";
@@ -7,8 +12,10 @@ import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
 import {
   buildPatchTarget,
   persistElementAttribute,
+  readSavedAttribute,
   type RecordEditInput,
 } from "./timelineEditingHelpers";
+import { useLiveLanes, type LiveLaneRestore, type LiveLaneSource } from "./liveLanes";
 import type {
   MutableRef,
   UseTimelineElementVisibilityEditingInput,
@@ -145,6 +152,8 @@ interface SetAudioGroupAttributeInput {
   value: string | null;
   label: string;
   previewIframe: HTMLIFrameElement | null;
+  patchLive: (value: string | null) => void;
+  onFileRead: (value: string | null) => void;
   writeProjectFile: (path: string, content: string) => Promise<void>;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   pendingTimelineEditPathRef: MutableRef<Set<string>>;
@@ -156,6 +165,28 @@ interface SetAudioGroupAttributeInput {
  * `createAudioGroupAndAssignMembers`'s save shape but for a single element
  * and attribute rather than a member-assignment sweep.
  */
+function groupSaveTarget(
+  previewIframe: HTMLIFrameElement | null,
+  groupId: string,
+  activeCompPath: string | null,
+) {
+  const groupEl = previewIframe?.contentDocument?.getElementById(groupId) ?? null;
+  return {
+    targetPath: resolveGroupSourceFile(groupEl) || activeCompPath || "index.html",
+    patchTarget: buildPatchTarget({ domId: groupId }),
+  };
+}
+
+function groupLiveSource(
+  previewIframe: HTMLIFrameElement | null,
+  groupId: string,
+  activeCompPath: string | null,
+  attr: string,
+): LiveLaneSource {
+  const { targetPath, patchTarget } = groupSaveTarget(previewIframe, groupId, activeCompPath);
+  return { path: targetPath, target: patchTarget, attr };
+}
+
 async function setAudioGroupAttribute({
   projectId,
   activeCompPath,
@@ -164,10 +195,12 @@ async function setAudioGroupAttribute({
   value,
   label,
   previewIframe,
+  patchLive,
+  onFileRead,
   writeProjectFile,
   recordEdit,
   pendingTimelineEditPathRef,
-}: SetAudioGroupAttributeInput): Promise<string[]> {
+}: SetAudioGroupAttributeInput): Promise<string[] | null> {
   // The file that actually CONTAINS the group element, not just the active
   // composition. A hand-authored sub-composition can declare both the members
   // and their `<hf-audio-group>`, and until sub-comp children inherited
@@ -176,10 +209,8 @@ async function setAudioGroupAttribute({
   // means `readTagSnippetByTarget` finds nothing and every mute, fader move and
   // FX preset throws "Unable to patch element in index.html". Every sibling
   // timeline writer already routes `element.sourceFile || activeCompPath`.
-  const groupEl = previewIframe?.contentDocument?.getElementById(groupId) ?? null;
-  const targetPath = resolveGroupSourceFile(groupEl) || activeCompPath || "index.html";
-  const patchTarget = buildPatchTarget({ domId: groupId });
-  if (!patchTarget) return [];
+  const { targetPath, patchTarget } = groupSaveTarget(previewIframe, groupId, activeCompPath);
+  if (!patchTarget) return null;
 
   return persistElementAttribute({
     projectId,
@@ -191,7 +222,8 @@ async function setAudioGroupAttribute({
     writeProjectFile,
     recordEdit,
     pendingTimelineEditPathRef,
-    patchLive: (v) => patchLiveGroupAttribute(previewIframe, groupId, attr, v),
+    patchLive,
+    onFileRead,
   });
 }
 
@@ -213,55 +245,73 @@ export function useSetAudioGroupAttribute({
   isRecordingRef,
 }: UseTimelineElementVisibilityEditingInput): {
   setLive: (groupId: string, attr: string, value: string | null) => void;
-  setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
+  setQuiet: (
+    groupId: string,
+    attr: string,
+    value: string | null,
+    label: string,
+  ) => Promise<TimelineEditOutcome>;
   revertLive: (groupId: string, attr: string) => void;
+  restoreLive: (restore: LiveLaneRestore) => void;
 } {
-  const liveBeforeRef = useRef(new Map<string, string | null>());
+  const liveLanes = useLiveLanes(projectIdRef, activeCompPath);
   const setLive = useCallback(
     (groupId: string, attr: string, value: string | null) => {
       const key = audioGroupAttributeLiveKey(groupId, attr);
       const target = previewIframeRef.current?.contentDocument?.getElementById(groupId);
-      if (!liveBeforeRef.current.has(key)) {
-        liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
-      }
+      liveLanes.preview(
+        key,
+        () => target?.getAttribute(attr) ?? null,
+        groupLiveSource(previewIframeRef.current, groupId, activeCompPath, attr),
+      );
       patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value);
       // Live too, not just on commit: a fader drag is `setLive` per frame and
       // `setQuiet` once on release, so without this the strip's own readout
       // fights the drag.
       syncStoredGroupAttribute(groupId, attr, value);
     },
+    [liveLanes, previewIframeRef, activeCompPath],
+  );
+  const laneApply = useCallback(
+    (groupId: string, attr: string) => ({
+      preview: (value: string | null) =>
+        patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value),
+      store: (value: string | null) => syncStoredGroupAttribute(groupId, attr, value),
+    }),
     [previewIframeRef],
   );
+  const claimLive = useCallback(
+    (groupId: string, attr: string, source: LiveLaneSource) =>
+      liveLanes.claim(audioGroupAttributeLiveKey(groupId, attr), laneApply(groupId, attr), source),
+    [liveLanes, laneApply],
+  );
   const revertLive = useCallback(
-    (groupId: string, attr: string) => {
-      const key = audioGroupAttributeLiveKey(groupId, attr);
-      if (!liveBeforeRef.current.has(key)) return;
-      patchLiveGroupAttribute(
-        previewIframeRef.current,
-        groupId,
-        attr,
-        liveBeforeRef.current.get(key) ?? null,
-      );
-      syncStoredGroupAttribute(
-        groupId,
-        attr,
-        previewIframeRef.current?.contentDocument?.getElementById(groupId)?.getAttribute(attr) ??
-          null,
-      );
-      liveBeforeRef.current.delete(key);
-    },
-    [previewIframeRef],
+    (groupId: string, attr: string) =>
+      liveLanes.revert(audioGroupAttributeLiveKey(groupId, attr), laneApply(groupId, attr)),
+    [liveLanes, laneApply],
   );
   const setQuiet = useCallback(
-    async (groupId: string, attr: string, value: string | null, label: string) => {
-      if (isRecordingRef?.current) {
-        showToast("Cannot edit timeline while recording", "error");
-        return;
-      }
-      const pid = projectIdRef.current;
-      if (!pid) return;
+    async (
+      groupId: string,
+      attr: string,
+      value: string | null,
+      label: string,
+    ): Promise<TimelineEditOutcome> => {
+      const project = projectIdRef.current;
+      const pid = projectForTimelineSave(isRecordingRef?.current, project, showToast);
+      // Settles on what the file holds, so overlapping saves that fail cannot leave
+      // the preview or the store on a value that never landed.
+      const source = groupLiveSource(previewIframeRef.current, groupId, activeCompPath, attr);
+      const live = claimLive(groupId, attr, source);
+      const unsaved = async (outcome: TimelineEditOutcome): Promise<TimelineEditOutcome> => {
+        live.settle(
+          await readSavedAttribute(project, source.path, source.target, attr, writeProjectFile),
+        );
+        return outcome;
+      };
+      if (typeof pid !== "string") return unsaved(pid);
       try {
-        await setAudioGroupAttribute({
+        const written = await setAudioGroupAttribute({
           projectId: pid,
           activeCompPath,
           groupId,
@@ -269,30 +319,24 @@ export function useSetAudioGroupAttribute({
           value,
           label,
           previewIframe: previewIframeRef.current,
+          patchLive: live.preview,
+          onFileRead: live.read,
           writeProjectFile,
           recordEdit,
           pendingTimelineEditPathRef,
         });
-        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
-        syncStoredGroupAttribute(groupId, attr, value);
+        if (!written)
+          return unsaved(failedTimelineSave("This group has no id to save it by", showToast));
+        live.settle(value);
+        return { status: "saved" };
       } catch (error) {
-        // `persistElementAttribute` leaves the live DOM at the previous value
-        // however it failed — it unwinds a failed save, and an unresolvable
-        // target now throws before patching at all. But `setLive` mirrored the
-        // in-progress value into the store on every drag frame — so without
-        // this the fader reads 0.4 while
-        // the preview and the file are both back at 1.0, and nothing re-parses
-        // to correct it (a live patch causing no parse is this mirror's whole
-        // premise). Re-mirror from the DOM, which is now authoritative again.
-        const live = previewIframeRef.current?.contentDocument?.getElementById(groupId);
-        syncStoredGroupAttribute(groupId, attr, live?.getAttribute(attr) ?? null);
         console.error("[Timeline] Failed to set group attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update group";
-        showToast(message);
-        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
+        return unsaved(failedTimelineSave(message, showToast));
       }
     },
     [
+      claimLive,
       activeCompPath,
       previewIframeRef,
       writeProjectFile,
@@ -303,5 +347,5 @@ export function useSetAudioGroupAttribute({
       projectIdRef,
     ],
   );
-  return { setLive, setQuiet, revertLive };
+  return { setLive, setQuiet, revertLive, restoreLive: liveLanes.restore };
 }