@hyperframes/studio 0.6.6 → 0.6.8

package/src/utils/sourcePatcher.test.ts

@@ -208,4 +208,289 @@ describe("applyPatchByTarget", () => {
     expect(patched).toContain(`<div class="headline clip" data-start="0"></div>`);
     expect(patched).toContain(`<div class="headline clip" data-start="2.5"></div>`);
   });
+
+  it("escapes JSON attribute values containing double-quotes and round-trips them", () => {
+    const html = `<div id="card" data-start="0"></div>`;
+    const motionJson = JSON.stringify({ preset: "fadeIn", start: 0, duration: 1.5 });
+
+    const patched = applyPatch(html, "card", {
+      type: "attribute",
+      property: "data-hf-studio-motion",
+      value: motionJson,
+    });
+
+    // The raw HTML must NOT contain unescaped quotes inside the attribute
+    expect(patched).not.toMatch(/data-hf-studio-motion="[^"]*"[^"]*"/);
+    // Entities should be present
+    expect(patched).toContain("&quot;");
+
+    // Reading the attribute back should return the original JSON
+    const readBack = readAttributeByTarget(patched, { id: "card" }, "data-hf-studio-motion");
+    expect(readBack).toBe(motionJson);
+  });
+
+  it("escapes and round-trips data-hf-studio-motion-original-transform with quotes", () => {
+    const html = `<div id="hero" data-start="0"></div>`;
+    const transform = `rotate(15deg) translate("50px", "100px")`;
+
+    const patched = applyPatchByTarget(
+      html,
+      { id: "hero" },
+      {
+        type: "attribute",
+        property: "data-hf-studio-motion-original-transform",
+        value: transform,
+      },
+    );
+
+    // No broken attribute boundary
+    expect(patched).not.toMatch(/data-hf-studio-motion-original-transform="[^"]*"[^"]*"/);
+
+    const readBack = readAttributeByTarget(
+      patched,
+      { id: "hero" },
+      "data-hf-studio-motion-original-transform",
+    );
+    expect(readBack).toBe(transform);
+  });
+
+  it("escapes ampersands and angle brackets in attribute values", () => {
+    const html = `<div id="el" data-start="0"></div>`;
+    const value = `a&b<c>d"e`;
+
+    const patched = applyPatch(html, "el", {
+      type: "attribute",
+      property: "data-custom",
+      value,
+    });
+
+    expect(patched).toContain("a&amp;b&lt;c&gt;d&quot;e");
+
+    const readBack = readAttributeByTarget(patched, { id: "el" }, "data-custom");
+    expect(readBack).toBe(value);
+  });
+
+  it("updates an already-escaped attribute value to a new escaped value", () => {
+    const html = `<div id="card" data-start="0"></div>`;
+    const first = JSON.stringify({ preset: "fadeIn" });
+    const second = JSON.stringify({ preset: "slideUp", easing: "ease-out" });
+
+    const patched1 = applyPatch(html, "card", {
+      type: "attribute",
+      property: "data-hf-studio-motion",
+      value: first,
+    });
+    const patched2 = applyPatch(patched1, "card", {
+      type: "attribute",
+      property: "data-hf-studio-motion",
+      value: second,
+    });
+
+    const readBack = readAttributeByTarget(patched2, { id: "card" }, "data-hf-studio-motion");
+    expect(readBack).toBe(second);
+  });
+});
+
+describe("motion attribute round-trip via sourcePatcher", () => {
+  it("round-trips data-hf-studio-motion JSON through patch and read", () => {
+    const html = `<div id="hero" style="position: absolute">Hero</div>`;
+    const motion = {
+      start: 0.5,
+      duration: 1,
+      ease: "power3.out",
+      from: { opacity: 0, y: 40 },
+      to: { opacity: 1, y: 0 },
+    };
+    const motionJson = JSON.stringify(motion);
+
+    const patched = applyPatchByTarget(
+      html,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion", value: motionJson },
+    );
+
+    const readBack = readAttributeByTarget(patched, { id: "hero" }, "data-hf-studio-motion");
+    expect(readBack).toBeDefined();
+    expect(JSON.parse(readBack!)).toEqual(motion);
+  });
+
+  it("round-trips motion with customEase containing SVG path data", () => {
+    const html = `<div id="card" class="clip" data-start="0" data-duration="10">Card</div>`;
+    const motion = {
+      start: 0.25,
+      duration: 0.8,
+      ease: "studio-card-bounce",
+      customEase: { id: "studio-card-bounce", data: "M0,0 C0.18,0.9 0.32,1 1,1" },
+      from: { y: 44, autoAlpha: 0 },
+      to: { y: 0, autoAlpha: 1 },
+    };
+    const motionJson = JSON.stringify(motion);
+
+    const patched = applyPatchByTarget(
+      html,
+      { id: "card" },
+      { type: "attribute", property: "data-hf-studio-motion", value: motionJson },
+    );
+
+    const readBack = readAttributeByTarget(patched, { id: "card" }, "data-hf-studio-motion");
+    expect(readBack).toBeDefined();
+    expect(JSON.parse(readBack!)).toEqual(motion);
+  });
+
+  it("round-trips all four motion attributes (motion + three originals)", () => {
+    const html = `<div id="hero" style="transform: rotate(5deg); opacity: 0.8; visibility: visible">Hero</div>`;
+    const motion = {
+      start: 0,
+      duration: 0.6,
+      ease: "power2.out",
+      from: { autoAlpha: 0, y: 32 },
+      to: { autoAlpha: 1, y: 0 },
+    };
+
+    let result = html;
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion", value: JSON.stringify(motion) },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      {
+        type: "attribute",
+        property: "data-hf-studio-motion-original-transform",
+        value: "rotate(5deg)",
+      },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion-original-opacity", value: "0.8" },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      {
+        type: "attribute",
+        property: "data-hf-studio-motion-original-visibility",
+        value: "visible",
+      },
+    );
+
+    expect(
+      JSON.parse(readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion")!),
+    ).toEqual(motion);
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-transform"),
+    ).toBe("rotate(5deg)");
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-opacity"),
+    ).toBe("0.8");
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-visibility"),
+    ).toBe("visible");
+  });
+
+  it("removes all four motion attributes when clearing", () => {
+    const html = `<div id="hero" style="position: absolute">Hero</div>`;
+    const motion = {
+      start: 0,
+      duration: 1,
+      ease: "none",
+      from: { opacity: 0 },
+      to: { opacity: 1 },
+    };
+
+    let result = html;
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion", value: JSON.stringify(motion) },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion-original-transform", value: "" },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion-original-opacity", value: "1" },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion-original-visibility", value: "" },
+    );
+
+    // Verify all four attributes exist
+    expect(readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion")).toBeDefined();
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-transform"),
+    ).toBeDefined();
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-opacity"),
+    ).toBeDefined();
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-visibility"),
+    ).toBeDefined();
+
+    // Remove all four
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion", value: null },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion-original-transform", value: null },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion-original-opacity", value: null },
+    );
+    result = applyPatchByTarget(
+      result,
+      { id: "hero" },
+      { type: "attribute", property: "data-hf-studio-motion-original-visibility", value: null },
+    );
+
+    expect(readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion")).toBeUndefined();
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-transform"),
+    ).toBeUndefined();
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-opacity"),
+    ).toBeUndefined();
+    expect(
+      readAttributeByTarget(result, { id: "hero" }, "data-hf-studio-motion-original-visibility"),
+    ).toBeUndefined();
+  });
+
+  it("round-trips motion via selector when element has no id", () => {
+    const html = `<div class="headline clip" style="position: absolute">Title</div>`;
+    const motion = {
+      start: 0.3,
+      duration: 0.5,
+      ease: "sine.out",
+      from: { scale: 0.88, autoAlpha: 0 },
+      to: { scale: 1, autoAlpha: 1 },
+    };
+
+    const patched = applyPatchByTarget(
+      html,
+      { selector: ".headline" },
+      { type: "attribute", property: "data-hf-studio-motion", value: JSON.stringify(motion) },
+    );
+
+    const readBack = readAttributeByTarget(
+      patched,
+      { selector: ".headline" },
+      "data-hf-studio-motion",
+    );
+    expect(readBack).toBeDefined();
+    expect(JSON.parse(readBack!)).toEqual(motion);
+  });
 });

package/src/utils/sourcePatcher.ts

@@ -11,6 +11,24 @@ function escapeStyleAttributeValue(value: string, quote: string): string {
   return quote === '"' ? value.replace(/"/g, """) : value.replace(/'/g, "'");
 }
 
+/** Escape a string for safe use inside a double-quoted HTML attribute. */
+function escapeHtmlAttribute(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** Reverse escapeHtmlAttribute so callers get the original value. */
+function unescapeHtmlAttribute(value: string): string {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
 function splitInlineStyleDeclarations(style: string): string[] {
   const declarations: string[] = [];
   let current = "";
@@ -71,7 +89,7 @@ function splitInlineStyleDeclarations(style: string): string[] {
 export interface PatchOperation {
   type: "inline-style" | "attribute" | "text-content";
   property: string;
-  value: string;
+  value: string | null;
 }
 
 export interface PatchTarget {
@@ -133,7 +151,12 @@ export function resolveSourceFile(
 /**
  * Apply a style property change to an element's inline style in the HTML source.
  */
-function patchInlineStyle(html: string, elementId: string, prop: string, value: string): string {
+function patchInlineStyle(
+  html: string,
+  elementId: string,
+  prop: string,
+  value: string | null,
+): string {
   // Find the element tag with this id
   const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(elementId)}\\2[^>]*)>`, "i");
   const match = idPattern.exec(html);
@@ -143,7 +166,12 @@ function patchInlineStyle(html: string, elementId: string, prop: string, value:
   return patchInlineStyleInTag(html, tag, prop, value);
 }
 
-function patchInlineStyleInTag(html: string, tag: string, prop: string, value: string): string {
+function patchInlineStyleInTag(
+  html: string,
+  tag: string,
+  prop: string,
+  value: string | null,
+): string {
   if (!tag) return html;
 
   // Check if there's an existing style attribute
@@ -160,16 +188,22 @@ function patchInlineStyleInTag(html: string, tag: string, prop: string, value: s
       const val = part.slice(colon + 1).trim();
       if (key) props.set(key, val);
     }
-    // Update/add the property
-    props.set(prop, value);
-    // Rebuild style string
+    // Update/add or remove the property
+    if (value === null) {
+      props.delete(prop);
+    } else {
+      props.set(prop, value);
+    }
+    // Rebuild style string; keep style="" if empty (harmless)
     const newStyle = Array.from(props.entries())
       .map(([k, v]) => `${k}: ${escapeStyleAttributeValue(v, quote)}`)
       .join("; ");
     const newTag = tag.replace(styleMatch[0], `style=${quote}${newStyle}${quote}`);
     return html.replace(tag, newTag);
   } else {
-    // No existing style — add one
+    // No existing style attribute
+    if (value === null) return html; // nothing to remove
+    // Add one
     const newTag =
       tag.replace(/>$/, "") + ` style="${prop}: ${escapeStyleAttributeValue(value, '"')}"`;
     return html.replace(tag, newTag);
@@ -180,7 +214,7 @@ function patchInlineStyleByTarget(
   html: string,
   target: PatchTarget,
   prop: string,
-  value: string,
+  value: string | null,
 ): string {
   const match = findTagByTarget(html, target);
   if (!match) return html;
@@ -198,7 +232,7 @@ function replaceTagAtMatch(html: string, match: TagMatch, newTag: string): strin
   return `${html.slice(0, match.start)}${newTag}${html.slice(match.end)}`;
 }
 
-function findTagByTarget(html: string, target: PatchTarget): TagMatch | null {
+export function findTagByTarget(html: string, target: PatchTarget): TagMatch | null {
   if (target.id) {
     const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(target.id)}\\2[^>]*)>`, "i");
     const match = idPattern.exec(html);
@@ -265,7 +299,7 @@ export function readAttributeByTarget(
 
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
   const valueMatch = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`).exec(match.tag);
-  return valueMatch?.[2];
+  return valueMatch?.[2] != null ? unescapeHtmlAttribute(valueMatch[2]) : undefined;
 }
 
 export function readTagSnippetByTarget(html: string, target: PatchTarget): string | undefined {
@@ -277,43 +311,65 @@ function patchAttributeByTarget(
   html: string,
   target: PatchTarget,
   attr: string,
-  value: string,
+  value: string | null,
 ): string {
   const match = findTagByTarget(html, target);
   if (!match) return html;
 
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
-  const attrPattern = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`);
+  const attrPattern = new RegExp(`\\b${escapeRegex(fullAttr)}=(["'])([^"']*)\\1`);
   const tag = match.tag;
 
+  if (value === null) {
+    // Remove the attribute if present
+    if (!attrPattern.test(tag)) return html;
+    const removePattern = new RegExp(`\\s+${escapeRegex(fullAttr)}=(["'])[^"']*\\1`);
+    const newTag = tag.replace(removePattern, "");
+    return replaceTagAtMatch(html, match, newTag);
+  }
+
+  const escaped = escapeHtmlAttribute(value);
   if (attrPattern.test(tag)) {
-    const newTag = tag.replace(attrPattern, `${fullAttr}="${value}"`);
+    const newTag = tag.replace(attrPattern, `${fullAttr}="${escaped}"`);
     return replaceTagAtMatch(html, match, newTag);
   }
 
-  const newTag = tag + ` ${fullAttr}="${value}"`;
+  const newTag = tag + ` ${fullAttr}="${escaped}"`;
   return replaceTagAtMatch(html, match, newTag);
 }
 
 /**
  * Apply an attribute change to an element in the HTML source.
  */
-function patchAttribute(html: string, elementId: string, attr: string, value: string): string {
+function patchAttribute(
+  html: string,
+  elementId: string,
+  attr: string,
+  value: string | null,
+): string {
   const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(elementId)}\\2[^>]*)>`, "i");
   const match = idPattern.exec(html);
   if (!match) return html;
 
   const tag = match[1];
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
-  const attrPattern = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`);
+  const attrPattern = new RegExp(`\\b${escapeRegex(fullAttr)}=(["'])([^"']*)\\1`);
+
+  if (value === null) {
+    if (!attrPattern.test(tag)) return html;
+    const removePattern = new RegExp(`\\s+${escapeRegex(fullAttr)}=(["'])[^"']*\\1`);
+    const newTag = tag.replace(removePattern, "");
+    return html.replace(tag, newTag);
+  }
 
+  const escaped = escapeHtmlAttribute(value);
   if (attrPattern.test(tag)) {
     // Update existing attribute
-    const newTag = tag.replace(attrPattern, `${fullAttr}="${value}"`);
+    const newTag = tag.replace(attrPattern, `${fullAttr}="${escaped}"`);
     return html.replace(tag, newTag);
   } else {
     // Add new attribute
-    const newTag = tag + ` ${fullAttr}="${value}"`;
+    const newTag = tag + ` ${fullAttr}="${escaped}"`;
     return html.replace(tag, newTag);
   }
 }
@@ -381,7 +437,7 @@ export function applyPatch(html: string, elementId: string, op: PatchOperation):
     case "attribute":
       return patchAttribute(html, elementId, op.property, op.value);
     case "text-content":
-      return patchTextContent(html, elementId, op.value);
+      return op.value !== null ? patchTextContent(html, elementId, op.value) : html;
     default:
       return html;
   }
@@ -401,7 +457,7 @@ export function applyPatchByTarget(html: string, target: PatchTarget, op: PatchO
     case "attribute":
       return patchAttributeByTarget(html, target, op.property, op.value);
     case "text-content":
-      return patchTextContentByTarget(html, target, op.value);
+      return op.value !== null ? patchTextContentByTarget(html, target, op.value) : html;
     default:
       return html;
   }

package/src/utils/studioPreviewHelpers.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from "vitest";
+import { pauseStudioPreviewPlayback } from "./studioPreviewHelpers";
+
+describe("pauseStudioPreviewPlayback", () => {
+  it("pauses through __player without pausing sibling timelines directly", () => {
+    const playerPause = vi.fn();
+    const timelinePause = vi.fn();
+    const siblingPause = vi.fn();
+
+    const iframe = {
+      contentWindow: {
+        __player: {
+          getTime: () => 4.25,
+          pause: playerPause,
+        },
+        __timeline: {
+          time: () => 4.25,
+          pause: timelinePause,
+        },
+        __timelines: {
+          root: {
+            pause: siblingPause,
+          },
+        },
+      },
+    } as unknown as HTMLIFrameElement;
+
+    expect(pauseStudioPreviewPlayback(iframe)).toBe(4.25);
+    expect(playerPause).toHaveBeenCalledTimes(1);
+    expect(timelinePause).not.toHaveBeenCalled();
+    expect(siblingPause).not.toHaveBeenCalled();
+  });
+
+  it("falls back to pausing timelines directly when __player is unavailable", () => {
+    const timelinePause = vi.fn();
+    const siblingPause = vi.fn();
+
+    const iframe = {
+      contentWindow: {
+        __timeline: {
+          time: () => 2.5,
+          pause: timelinePause,
+        },
+        __timelines: {
+          root: {
+            pause: siblingPause,
+          },
+        },
+      },
+    } as unknown as HTMLIFrameElement;
+
+    expect(pauseStudioPreviewPlayback(iframe)).toBe(2.5);
+    expect(timelinePause).toHaveBeenCalledTimes(1);
+    expect(siblingPause).toHaveBeenCalledTimes(1);
+  });
+});

package/src/utils/studioPreviewHelpers.ts

@@ -1,5 +1,9 @@
 import type { DomEditViewport, DomEditSelection } from "../components/editor/domEditing";
 import { resolveVisualDomEditSelectionTarget } from "../components/editor/domEditing";
+import {
+  getDomLayerPatchTarget,
+  isElementComputedVisible,
+} from "../components/editor/domEditingElement";
 import { usePlayerStore, liveTime } from "../player";
 import { getEventTargetElement } from "./studioHelpers";
 
@@ -56,6 +60,28 @@ export function getPreviewLocalPointer(
   return resolvePreviewLocalPointer(iframe, doc, win, clientX, clientY);
 }
 
+const POINTER_EVENTS_OVERRIDE_ID = "__hf_studio_pointer_events_override__";
+
+function forcePointerEventsAuto(doc: Document): HTMLStyleElement | null {
+  try {
+    const style = doc.createElement("style");
+    style.id = POINTER_EVENTS_OVERRIDE_ID;
+    style.textContent = "* { pointer-events: auto !important; }";
+    doc.head.appendChild(style);
+    return style;
+  } catch {
+    return null;
+  }
+}
+
+function removePointerEventsOverride(style: HTMLStyleElement | null): void {
+  try {
+    style?.remove();
+  } catch {
+    // cross-origin or detached doc
+  }
+}
+
 export function getPreviewTargetFromPointer(
   iframe: HTMLIFrameElement,
   clientX: number,
@@ -75,17 +101,25 @@ export function getPreviewTargetFromPointer(
   const localPointer = resolvePreviewLocalPointer(iframe, doc, win, clientX, clientY);
   if (!localPointer) return null;
 
-  if (typeof doc.elementsFromPoint === "function") {
-    const visualTarget = resolveVisualDomEditSelectionTarget(
-      doc.elementsFromPoint(localPointer.x, localPointer.y),
-      {
-        activeCompositionPath,
-      },
-    );
-    if (visualTarget) return visualTarget;
-  }
+  const overrideStyle = forcePointerEventsAuto(doc);
+  try {
+    if (typeof doc.elementsFromPoint === "function") {
+      const visualTarget = resolveVisualDomEditSelectionTarget(
+        doc.elementsFromPoint(localPointer.x, localPointer.y),
+        {
+          activeCompositionPath,
+        },
+      );
+      if (visualTarget) return visualTarget;
+    }
 
-  return getEventTargetElement(doc.elementFromPoint(localPointer.x, localPointer.y));
+    const fallback = getEventTargetElement(doc.elementFromPoint(localPointer.x, localPointer.y));
+    if (!fallback || !getDomLayerPatchTarget(fallback, activeCompositionPath)) return null;
+    if (!isElementComputedVisible(fallback)) return null;
+    return fallback;
+  } finally {
+    removePointerEventsOverride(overrideStyle);
+  }
 }
 
 export function buildRasterClickSelectionContext(
@@ -160,11 +194,15 @@ export function pauseStudioPreviewPlayback(iframe: HTMLIFrameElement | null): nu
   if (!win) return null;
 
   try {
-    let pausedTime: number | null = null;
     const player = objectLike(Reflect.get(win, "__player"));
-    pausedTime = readPlaybackTime(player, "getTime") ?? pausedTime;
-    callPlaybackMethod(player, "pause");
+    const playerPausedTime = readPlaybackTime(player, "getTime");
+    const playerPause = player ? Reflect.get(player, "pause") : null;
+    if (typeof playerPause === "function") {
+      callPlaybackMethod(player, "pause");
+      return playerPausedTime;
+    }
 
+    let pausedTime: number | null = null;
     const timeline = objectLike(Reflect.get(win, "__timeline"));
     pausedTime = pausedTime ?? readPlaybackTime(timeline, "time");
     callPlaybackMethod(timeline, "pause");

package/src/utils/studioUiPreferences.test.ts

@@ -21,11 +21,13 @@ describe("studio UI preferences", () => {
 
     writeStudioUiPreferences({ timelineVisible: false }, storage);
     writeStudioUiPreferences({ playbackRate: 1.5 }, storage);
+    writeStudioUiPreferences({ audioMuted: true }, storage);
     writeStudioUiPreferences({ previewZoom: { zoomPercent: 160, panX: -20, panY: 12 } }, storage);
 
     expect(readStudioUiPreferences(storage)).toEqual({
       timelineVisible: false,
       playbackRate: 1.5,
+      audioMuted: true,
       previewZoom: { zoomPercent: 160, panX: -20, panY: 12 },
     });
   });
@@ -38,6 +40,7 @@ describe("studio UI preferences", () => {
         leftCollapsed: "yes",
         timelineVisible: true,
         playbackRate: Number.NaN,
+        audioMuted: "false",
         previewZoom: { zoomPercent: 150, panX: 0, panY: "bad" },
       }),
     );

package/src/utils/studioUiPreferences.ts

@@ -8,6 +8,7 @@ export interface StudioUiPreferences {
   leftCollapsed?: boolean;
   timelineVisible?: boolean;
   playbackRate?: number;
+  audioMuted?: boolean;
   previewZoom?: StoredPreviewZoomState;
 }
 
@@ -44,6 +45,9 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.playbackRate === "number" && Number.isFinite(parsed.playbackRate)) {
       preferences.playbackRate = parsed.playbackRate;
     }
+    if (typeof parsed.audioMuted === "boolean") {
+      preferences.audioMuted = parsed.audioMuted;
+    }
     if (isRecord(parsed.previewZoom)) {
       const { zoomPercent, panX, panY } = parsed.previewZoom;
       if (