@hyperframes/studio 0.8.3 → 0.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "",
   "repository": {
     "type": "git",
@@ -47,11 +47,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.3",
-    "@hyperframes/parsers": "0.8.3",
-    "@hyperframes/player": "0.8.3",
-    "@hyperframes/sdk": "0.8.3",
-    "@hyperframes/studio-server": "0.8.3"
+    "@hyperframes/core": "0.8.5",
+    "@hyperframes/parsers": "0.8.5",
+    "@hyperframes/player": "0.8.5",
+    "@hyperframes/sdk": "0.8.5",
+    "@hyperframes/studio-server": "0.8.5"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -68,7 +68,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.3"
+    "@hyperframes/producer": "0.8.5"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -218,10 +218,9 @@ export function StudioApp() {
   });
   const clearDomSelectionRef = useRef<() => void>(() => {});
   const domEditSelectionBridgeRef = useRef<DomEditSelection | null>(null);
-  const handleDomEditElementDeleteRef = useRef<(s: DomEditSelection) => Promise<void>>(
-    async () => {},
-  );
-  const domEditDeleteBridge = (s: DomEditSelection) => handleDomEditElementDeleteRef.current(s);
+  type DomEditDelete = (s: DomEditSelection, o?: { expandGroup?: boolean }) => Promise<void>;
+  const handleDomEditElementDeleteRef = useRef<DomEditDelete>(async () => {});
+  const domEditDeleteBridge: DomEditDelete = (s, o) => handleDomEditElementDeleteRef.current(s, o);
   const resetKeyframesRef = useRef<() => boolean>(() => false);
   const deleteSelectedKeyframesRef = useRef<() => void>(() => {});
   const { handleCopy, handlePaste, handleCut } = useClipboard({
@@ -238,7 +237,7 @@ export function StudioApp() {
     previewIframeRef,
   });
   const appHotkeys = useAppHotkeys({
-    handleTimelineElementDelete: timelineEditing.handleTimelineElementDelete,
+    handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,
     handleTimelineElementSplit: timelineEditing.handleTimelineElementSplit,
     handleDomEditElementDelete: domEditDeleteBridge,
     domEditSelectionRef: domEditSelectionBridgeRef,
@@ -282,6 +281,7 @@ export function StudioApp() {
     setRightCollapsed: panelLayout.setRightCollapsed,
     setRightPanelTab: panelLayout.setRightPanelTab,
     showToast,
+    isRecordingRef: isGestureRecordingRef,
     refreshPreviewDocumentVersion,
     queueDomEditSave: previewPersistence.queueDomEditSave,
     readProjectFile: fileManager.readProjectFile,
@@ -298,7 +298,7 @@ export function StudioApp() {
     previewDocumentVersion,
     rightPanelTab: panelLayout.rightPanelTab,
     applyStudioManualEditsToPreviewRef: previewPersistence.applyStudioManualEditsToPreviewRef,
-    syncPreviewHistoryHotkey: appHotkeys.syncPreviewHistoryHotkey,
+    syncPreviewHotkeys: appHotkeys.syncPreviewHotkeys,
     reloadPreview,
     setRefreshKey,
     openSourceForSelection: fileManager.openSourceForSelection,
@@ -365,7 +365,6 @@ export function StudioApp() {
     isGestureRecordingRef,
   });
   handleToggleRecordingRef.current = handleToggleRecording;
-  const recordingToggle = handleToggleRecording;
   const canvasRectRef = useRef<DOMRect | null>(null);
   useLayoutEffect(() => {
     if (gestureState !== "recording" || !previewIframe) {
@@ -378,8 +377,7 @@ export function StudioApp() {
     (iframe: HTMLIFrameElement | null) => {
       previewIframeRef.current = iframe;
       setPreviewIframe(iframe);
-      appHotkeys.syncPreviewTimelineHotkey(iframe);
-      appHotkeys.syncPreviewHistoryHotkey(iframe);
+      appHotkeys.syncPreviewHotkeys(iframe);
       resetConsoleErrors();
       refreshPreviewDocumentVersion();
     },
@@ -526,7 +524,7 @@ export function StudioApp() {
                           }}
                           recordingState={gestureState}
                           recordingDuration={gestureRecording.recordingDuration}
-                          onToggleRecording={recordingToggle}
+                          onToggleRecording={handleToggleRecording}
                           sdkSession={sdkHandle.session}
                           publishSdkSession={sdkHandle.publish}
                           forceReloadSdkSession={sdkHandle.forceReload}
@@ -561,7 +559,7 @@ export function StudioApp() {
                     shouldShowSelectedDomBounds={shouldShowSelectedDomBounds}
                     isGestureRecording={gestureState === "recording"}
                     recordingState={gestureState}
-                    onToggleRecording={recordingToggle}
+                    onToggleRecording={handleToggleRecording}
                     blockPreview={blockPreview}
                     gestureOverlay={
                       gestureState === "recording" && previewIframe ? (

package/src/components/editor/LayersPanel.tsx

@@ -23,6 +23,9 @@ import { useLayerReorderTimelineMirror } from "../nle/useCanvasZOrderTimelineMir
 import { runZLaneGesture } from "../nle/zLaneGesture";
 import { useLayerRevealOverride } from "./useLayerRevealOverride";
 
+// Rows this panel renders before it stops. A display budget, not a document limit.
+const LAYERS_PANEL_MAX_ROWS = 80;
+
 const TAG_ICONS: Record<string, string> = {
   video: "Vi",
   audio: "Au",
@@ -137,11 +140,13 @@ export const LayersPanel = memo(function LayersPanel() {
     // A preview reload detaches the drilled-into wrapper; exit drill-in if so.
     if (activeGroupElement && !activeGroupElement.isConnected) setActiveGroupElement(null);
 
-    const items = collectDomEditLayerItems(root, {
-      activeCompositionPath: activeCompPath,
-      isMasterView,
-      activeGroupElement,
-    });
+    const items = collectDomEditLayerItems(
+      root,
+      { activeCompositionPath: activeCompPath, isMasterView, activeGroupElement },
+      // How many rows this panel is willing to render, nothing more. Hit-testing
+      // callers deliberately take the whole document instead.
+      LAYERS_PANEL_MAX_ROWS,
+    );
     setLayers(sortLayersByZIndex(items));
   }, [previewIframeRef, activeCompPath, isMasterView, activeGroupElement, setActiveGroupElement]);
 

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

@@ -34,7 +34,7 @@ function AppHotkeyHarness() {
   const leftSidebarRef = useRef<LeftSidebarHandle | null>(null);
 
   useAppHotkeys({
-    handleTimelineElementDelete: vi.fn(),
+    handleTimelineElementsDelete: vi.fn(async () => {}),
     handleTimelineElementSplit: vi.fn(),
     handleDomEditElementDelete: vi.fn(),
     domEditSelectionRef,

package/src/components/editor/domEditingLayers.test.ts

@@ -224,3 +224,27 @@ describe("buildTextFieldChildLocator", () => {
     expect(buildTextFieldChildLocator(fields, "missing")).toBeNull();
   });
 });
+
+describe("collectDomEditLayerItems item budget", () => {
+  function documentWith(count: number): HTMLElement {
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "index.html");
+    for (let i = 0; i < count; i++) {
+      const child = document.createElement("div");
+      child.id = `el-${i}`;
+      root.append(child);
+    }
+    return root;
+  }
+
+  it("returns the whole document by default", () => {
+    // A default cap here silently truncated the marquee's candidate list: a drag
+    // over the whole canvas only ever saw the first 80 elements, so everything
+    // past them was unselectable and survived a Delete.
+    expect(collectDomEditLayerItems(documentWith(200), opts)).toHaveLength(200);
+  });
+
+  it("truncates only when a caller asks for a rendering budget", () => {
+    expect(collectDomEditLayerItems(documentWith(200), opts, 80)).toHaveLength(80);
+  });
+});

package/src/components/editor/domEditingLayers.ts

@@ -458,10 +458,14 @@ export function countDomEditChildLayers(
   return count;
 }
 
+// Every editable element under `root`, in document order. `maxItems` is a
+// caller's rendering budget, not a property of the document: hit-testing
+// callers (marquee, off-canvas indicators) must see all of it, and sharing a
+// truncated list left everything past the cut unselectable however far you drag.
 export function collectDomEditLayerItems(
   root: HTMLElement | null | undefined,
   options: DomEditContextOptions,
-  maxItems = 80,
+  maxItems = Number.POSITIVE_INFINITY,
 ): DomEditLayerItem[] {
   if (!root) return [];
 

package/src/components/editor/marqueeCommit.ts

@@ -24,16 +24,18 @@ interface MarqueeHit {
 }
 
 /**
- * Synchronous core of the marquee: the elements whose overlay-space rect
- * intersects the marquee rect. Uses the SAME `toOverlayRect` basis as the
- * single-selection / group-selection boxes, so what the marquee highlights
- * and selects is exactly the box the user sees when they click an element.
- * Shared by the live candidate highlight (per pointer-move) and the mouse-up
- * commit. No async source probe — that only happens once, on commit.
+ * Every element the marquee could hit, with the overlay-space rect it would be
+ * tested against. Uses the SAME `toOverlayRect` basis as the single-selection /
+ * group-selection boxes, so what the marquee highlights and selects is exactly
+ * the box the user sees when they click an element.
+ *
+ * Measured once per drag rather than per pointer-move: this reads layout for
+ * every element in the document, and a captured page has enough of them that
+ * doing it 60 times a second stalls the tab. The iframe DOM does not mutate
+ * mid-drag, so the rects it returns stay true for the whole gesture.
  */
 // fallow-ignore-next-line complexity
-function collectMarqueeHits(
-  rect: Rect,
+function collectMarqueeCandidates(
   iframe: HTMLIFrameElement,
   overlayEl: HTMLDivElement,
   activeCompositionPath: string,
@@ -53,35 +55,39 @@ function collectMarqueeHits(
     height: declH > 0 ? declH : rootEl.getBoundingClientRect().height || 1,
   };
 
-  const hits: MarqueeHit[] = [];
+  const candidates: MarqueeHit[] = [];
   for (const item of items) {
     const el = item.element;
     if (!isElementComputedVisible(el)) continue;
     if (coversComposition(el.getBoundingClientRect(), viewport)) continue;
     const overlayRect = toVisibleOverlayRect(overlayEl, iframe, el);
     if (!overlayRect) continue;
-    const r: Rect = {
-      left: overlayRect.left,
-      top: overlayRect.top,
-      width: overlayRect.width,
-      height: overlayRect.height,
-    };
-    if (!rectsOverlap(rect, r)) continue;
-    hits.push({ element: el, rect: r });
+    candidates.push({
+      element: el,
+      rect: {
+        left: overlayRect.left,
+        top: overlayRect.top,
+        width: overlayRect.width,
+        height: overlayRect.height,
+      },
+    });
   }
 
-  return hits;
+  return candidates;
+}
+
+function hitsWithin(rect: Rect, candidates: MarqueeHit[]): MarqueeHit[] {
+  return candidates.filter((candidate) => rectsOverlap(rect, candidate.rect));
 }
 
 async function runMarqueeIntersection(
   rect: Rect,
-  iframe: HTMLIFrameElement,
-  overlayEl: HTMLDivElement,
+  candidates: MarqueeHit[],
   activeCompositionPath: string,
 ): Promise<DomEditSelection[]> {
   const isMasterView = !activeCompositionPath || activeCompositionPath === "index.html";
   const hits: DomEditSelection[] = [];
-  for (const { element } of collectMarqueeHits(rect, iframe, overlayEl, activeCompositionPath)) {
+  for (const { element } of hitsWithin(rect, candidates)) {
     const sel = await resolveDomEditSelection(element, {
       activeCompositionPath,
       isMasterView,
@@ -116,6 +122,8 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
   // iframe DOM doesn't mutate during a drag, so a sync intersection per move
   // is cheap (clean layout → no thrash).
   const [candidateRects, setCandidateRects] = useState<Rect[]>([]);
+  // Measured once when the drag passes the threshold and reused until it ends.
+  const candidatesRef = useRef<MarqueeHit[] | null>(null);
 
   const commitMarquee = useCallback(
     async (
@@ -126,7 +134,8 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
       const overlay = deps.overlayRef.current;
       if (!iframe || !overlay || !deps.onMarqueeSelectRef.current) return;
       const acp = deps.activeCompositionPathRef.current ?? "index.html";
-      const hits = await runMarqueeIntersection(rect, iframe, overlay, acp);
+      const candidates = candidatesRef.current ?? collectMarqueeCandidates(iframe, overlay, acp);
+      const hits = await runMarqueeIntersection(rect, candidates, acp);
       deps.onMarqueeSelectRef.current(hits, additive);
     },
     [deps.iframeRef, deps.overlayRef, deps.onMarqueeSelectRef, deps.activeCompositionPathRef],
@@ -145,6 +154,7 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
           const dy = m.currentY - m.startY;
           if (Math.hypot(dx, dy) < MARQUEE_THRESHOLD_PX) return;
           m.pastThreshold = true;
+          candidatesRef.current = null;
         }
         const rect: Rect = {
           left: Math.min(m.startX, m.currentX),
@@ -157,7 +167,8 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
         const overlay = deps.overlayRef.current;
         if (iframe && overlay) {
           const acp = deps.activeCompositionPathRef.current ?? "index.html";
-          setCandidateRects(collectMarqueeHits(rect, iframe, overlay, acp).map((h) => h.rect));
+          candidatesRef.current ??= collectMarqueeCandidates(iframe, overlay, acp);
+          setCandidateRects(hitsWithin(rect, candidatesRef.current).map((h) => h.rect));
         }
         return;
       }
@@ -191,6 +202,7 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
         }
         setMarqueeRect(null);
         setCandidateRects([]);
+        candidatesRef.current = null;
         return;
       }
       deps.gestures.onPointerUp(event);
@@ -203,6 +215,7 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
       marqueeRef.current = null;
       setMarqueeRect(null);
       setCandidateRects([]);
+      candidatesRef.current = null;
       return;
     }
     deps.gestures.clearPointerState(deps.selectionRef);

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

@@ -4,6 +4,7 @@ import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { DomEditOverlay } from "./DomEditOverlay";
+import { RECOMPUTE_INTERVAL_MS } from "./offCanvasIndicatorRefresh";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
@@ -47,7 +48,12 @@ function domRect(left: number, top: number, width: number, height: number): DOMR
   };
 }
 
+// The refresh rebuilds at most every RECOMPUTE_INTERVAL_MS — it walks the whole
+// preview and reads layout per element, which is too much to do per frame while
+// animation is writing inline styles. Waiting past that window is what makes
+// consecutive frames here represent consecutive rebuilds.
 async function flushAnimationFrames(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, RECOMPUTE_INTERVAL_MS + 5));
   await new Promise<void>((resolve) => {
     requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
   });

package/src/components/editor/offCanvasIndicatorRefresh.throttle.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { RECOMPUTE_INTERVAL_MS, rebuildDue } from "./offCanvasIndicatorRefresh";
+
+describe("rebuildDue", () => {
+  it("collapses mutations arriving inside one window into a single rebuild", () => {
+    // A rebuild walks the whole preview and reads layout per element, and what
+    // marks it dirty is a MutationObserver on inline style — which is how
+    // animation writes. Without this, playback pays that on nearly every frame.
+    const first = 1_000;
+    expect(rebuildDue(true, Number.NEGATIVE_INFINITY, first)).toBe(true);
+    expect(rebuildDue(true, first, first + RECOMPUTE_INTERVAL_MS - 1)).toBe(false);
+    expect(rebuildDue(true, first, first + RECOMPUTE_INTERVAL_MS)).toBe(true);
+  });
+
+  it("never rebuilds when nothing changed", () => {
+    expect(rebuildDue(false, Number.NEGATIVE_INFINITY, 1_000)).toBe(false);
+  });
+});

package/src/components/editor/offCanvasIndicatorRefresh.ts

@@ -43,11 +43,29 @@ function observeDoc(doc: Document, markDirty: () => void): MutationObserver | nu
   return observer;
 }
 
+/**
+ * How often the indicator geometry may be rebuilt.
+ *
+ * A rebuild walks every element in the preview and reads layout for each —
+ * 6.5ms on an 825-element captured page, against a 16.7ms frame. What marks it
+ * dirty is a MutationObserver on inline style, which is exactly how animation
+ * writes, so playback would pay that on close to every frame. The indicators
+ * are a passive affordance: refreshing them a few times a second is
+ * indistinguishable on screen and keeps the cost off the frame budget.
+ */
+export const RECOMPUTE_INTERVAL_MS = 100;
+
+/** Dirty, and far enough past the last rebuild to be worth paying for another. */
+export function rebuildDue(dirty: boolean, lastAt: number, now: number): boolean {
+  return dirty && now - lastAt >= RECOMPUTE_INTERVAL_MS;
+}
+
 export function startOffCanvasIndicatorRefresh(
   options: OffCanvasIndicatorRefreshOptions,
 ): () => void {
   let frame = 0;
   let lastCompSig = "";
+  let lastRecomputeAt = Number.NEGATIVE_INFINITY;
   const markDirty = () => {
     options.dirtyRef.current = true;
   };
@@ -76,7 +94,10 @@ export function startOffCanvasIndicatorRefresh(
       if (options.dirtyRef.current) clearIndicators(options);
       return;
     }
-    if (!options.dirtyRef.current) return;
+    // Staying dirty while throttled is what makes the next eligible frame rebuild.
+    const now = performance.now();
+    if (!rebuildDue(options.dirtyRef.current, lastRecomputeAt, now)) return;
+    lastRecomputeAt = now;
     options.dirtyRef.current = false;
     recomputeOffCanvasIndicators(
       iframe,

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

@@ -131,9 +131,9 @@ describe("FlatMediaSection — cutout", () => {
 });
 
 describe("FlatMediaSection — volume/rate/media-start", () => {
-  it("renders volume at its stored percentage and commits a new value on drag", () => {
+  it("renders unity volume as neutral 0 dB at the slider midpoint", () => {
     const onSetAttribute = vi.fn();
-    const element = makeVideoElement({ dataAttributes: { volume: "0.5" } });
+    const element = makeVideoElement({ dataAttributes: { volume: "1" } });
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
@@ -149,13 +149,16 @@ describe("FlatMediaSection — volume/rate/media-start", () => {
         />,
       );
     });
-    expect(host.textContent).toContain("50%");
+    expect(host.textContent).toContain("0.0 dB");
+    expect(
+      host.querySelector('[data-flat-slider-track="true"]')?.getAttribute("aria-valuenow"),
+    ).toBe("0");
     act(() => root.unmount());
   });
 
-  it("commits a new volume value on slider track pointerdown", () => {
+  it("commits +12 dB of boost from the upper half of the volume fader", () => {
     const onSetAttribute = vi.fn();
-    const element = makeVideoElement({ dataAttributes: { volume: "0.2" } });
+    const element = makeVideoElement({ dataAttributes: { volume: "1" } });
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
@@ -176,11 +179,13 @@ describe("FlatMediaSection — volume/rate/media-start", () => {
       value: () => ({ left: 0, width: 100, top: 0, height: 2, right: 100, bottom: 2 }),
     });
     act(() => {
-      volumeTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 50 }));
-      volumeTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 50 }));
+      volumeTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 100 }));
+      volumeTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 100 }));
     });
-    // starting volume 0.2 (draft=20); min=0, max=100, ratio=0.5 -> raw=50 -> commit(50) -> 50/100=0.5 -> "0.5"
-    expect(onSetAttribute).toHaveBeenCalledWith("volume", "0.5");
+    // Six decimals, not two: at two the bottom of the dB fader collapses onto
+    // "0" (a hard mute) and every stop below unity writes a value the knob then
+    // jumps away from.
+    expect(onSetAttribute).toHaveBeenCalledWith("volume", "3.981072");
     act(() => root.unmount());
   });
 

package/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -13,6 +13,14 @@ import {
 import { FlatSelectRow, FlatSlider } from "./propertyPanelFlatPrimitives";
 import { FlatToggle } from "./propertyPanelFlatToggle";
 import { AutomationToggle } from "./propertyPanelFxControls";
+import {
+  AUDIO_GAIN_FADER_MAX,
+  AUDIO_GAIN_FADER_MIN,
+  audioFaderPositionToGain,
+  formatAudioGain,
+  audioGainToFaderPosition,
+  audioGainToText,
+} from "@hyperframes/core/audio-gain";
 
 // fallow-ignore-next-line complexity
 export function FlatMediaSection({
@@ -54,7 +62,7 @@ export function FlatMediaSection({
   const el = element.element;
 
   const volume = parseNumericValue(element.dataAttributes.volume ?? "") ?? 1;
-  const volumePercent = Math.round(volume * 100);
+  const volumeFaderPosition = audioGainToFaderPosition(volume);
   const mediaStart =
     Number.parseFloat(
       element.dataAttributes["media-start"] ?? element.dataAttributes["playback-start"] ?? "0",
@@ -215,13 +223,16 @@ export function FlatMediaSection({
             <div className="min-w-0 flex-1">
               <FlatSlider
                 label="Volume"
-                value={volumePercent}
-                min={0}
-                max={100}
-                tier={volumePercent === 100 ? "default" : "explicitCustom"}
-                displayValue={`${volumePercent}%`}
+                value={volumeFaderPosition}
+                min={AUDIO_GAIN_FADER_MIN}
+                max={AUDIO_GAIN_FADER_MAX}
+                tier={volume === 1 ? "default" : "explicitCustom"}
+                displayValue={audioGainToText(volume)}
                 disabled={volumeAutomated}
-                onCommit={(next) => void onSetAttribute("volume", formatNumericValue(next / 100))}
+                centerTick
+                onCommit={(next) =>
+                  void onSetAttribute("volume", formatAudioGain(audioFaderPositionToGain(next)))
+                }
               />
             </div>
             <AutomationToggle

package/src/components/editor/propertyPanelMediaSection.tsx

@@ -13,6 +13,14 @@ import {
 } from "./propertyPanelHelpers";
 import { Section, SegmentedControl, SelectField, SliderControl } from "./propertyPanelPrimitives";
 import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+import {
+  AUDIO_GAIN_FADER_MAX,
+  AUDIO_GAIN_FADER_MIN,
+  audioFaderPositionToGain,
+  formatAudioGain,
+  audioGainToFaderPosition,
+  audioGainToText,
+} from "@hyperframes/core/audio-gain";
 
 // fallow-ignore-next-line complexity
 export function MediaSection({
@@ -47,7 +55,7 @@ export function MediaSection({
   const el = element.element;
 
   const volume = parseNumericValue(element.dataAttributes.volume ?? "") ?? 1;
-  const volumePercent = Math.round(volume * 100);
+  const volumeFaderPosition = audioGainToFaderPosition(volume);
 
   const mediaStart =
     Number.parseFloat(
@@ -250,14 +258,14 @@ export function MediaSection({
               <span className={LABEL}>Volume</span>
               <SliderControl
                 trackName="Volume"
-                value={volumePercent}
-                min={0}
-                max={100}
+                value={volumeFaderPosition}
+                min={AUDIO_GAIN_FADER_MIN}
+                max={AUDIO_GAIN_FADER_MAX}
                 step={1}
-                displayValue={`${volumePercent}%`}
-                formatDisplayValue={(next) => `${Math.round(next)}%`}
+                displayValue={audioGainToText(volume)}
+                formatDisplayValue={(next) => audioGainToText(audioFaderPositionToGain(next))}
                 onCommit={(next) => {
-                  void onSetAttribute("volume", formatNumericValue(next / 100));
+                  void onSetAttribute("volume", formatAudioGain(audioFaderPositionToGain(next)));
                 }}
               />
             </div>

package/src/components/nle/NLEPreview.tsx

@@ -354,28 +354,6 @@ export const NLEPreview = memo(function NLEPreview({
     return () => document.removeEventListener("wheel", handleWheel, { capture: true });
   }, [applyZoom, applyPan]);
 
-  useEffect(() => {
-    const viewport = viewportRef.current;
-    if (!viewport) return;
-
-    const handleDblClick = (event: MouseEvent) => {
-      if (isPreviewAtFit(zoomRef.current)) return;
-      const rect = viewport.getBoundingClientRect();
-      if (
-        event.clientX < rect.left ||
-        event.clientX > rect.right ||
-        event.clientY < rect.top ||
-        event.clientY > rect.bottom
-      ) {
-        return;
-      }
-      applyZoom(DEFAULT_PREVIEW_ZOOM);
-    };
-
-    document.addEventListener("dblclick", handleDblClick, { capture: true });
-    return () => document.removeEventListener("dblclick", handleDblClick, { capture: true });
-  }, [applyZoom]);
-
   useEffect(() => {
     const isInsideViewport = (clientX: number, clientY: number): DOMRect | null => {
       const viewport = viewportRef.current;

package/src/components/storyboard/FramePoster.test.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { FramePoster } from "./FramePoster";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const roots: Root[] = [];
+
+afterEach(() => {
+  act(() => roots.splice(0).forEach((root) => root.unmount()));
+  document.body.replaceChildren();
+});
+
+// A fresh host per render: several cases compare two surfaces side by side.
+function renderPoster(surface?: "tile" | "hero"): HTMLImageElement {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  roots.push(root);
+  act(() => {
+    root.render(
+      <FramePoster
+        projectId="demo"
+        src="frames/01-hero.html"
+        seconds={3}
+        title="hero"
+        surface={surface}
+      />,
+    );
+  });
+  const img = host.querySelector("img");
+  if (!img) throw new Error("poster did not render an <img>");
+  return img;
+}
+
+describe("FramePoster", () => {
+  // Regression: the contact sheet stretched a 240x135 capture across a wide,
+  // high-density card, making body copy, thin lines, and sprite details blurry.
+  it.each([
+    [undefined, "storyboard"],
+    ["tile", "storyboard"],
+    ["hero", "source"],
+  ] as const)("captures the %s surface at %s density", (surface, output) => {
+    const url = new URL(renderPoster(surface).src);
+
+    expect(url.searchParams.get("output")).toBe(output);
+    expect(url.pathname).toBe("/api/projects/demo/thumbnail/frames/01-hero.html");
+  });
+
+  it("defaults to the tile surface", () => {
+    expect(renderPoster().className).toBe(renderPoster("tile").className);
+  });
+
+  it("letterboxes only the hero, so a tile still fills its cell", () => {
+    expect(renderPoster("hero").className).toContain("object-contain");
+    expect(renderPoster("tile").className).toContain("object-cover");
+  });
+});