@dailies-studio/shot-editor 0.1.0

package/src/panels/material/MaterialPicker.tsx

@@ -0,0 +1,172 @@
+// Pick a TSL generator to paint over a model's albedo.
+//
+// ── NO GL IN HERE, AND THAT IS NOT A COMPROMISE ─────────────────────────
+//
+// The shot chrome is three-free by test, so a live preview tile would have to
+// live in the stage iframe and be pushed across the bridge. It would also buy
+// nothing: the studio already SHIPS a rendered PNG for every catalog entry
+// (`packages/effects/thumbs`, served at the server's own thumbs route), made by
+// the same generators on the same renderer. A live tile would show the same
+// image for more machinery and one GL context per card.
+//
+// ── WHY IT IS A DIALOG AND NOT A PANEL ──────────────────────────────────
+//
+// Picking a material is a MODE the author enters from one place and leaves the
+// moment they choose — the same shape `ExportDialog` has. A permanent panel
+// would need a permanent home in a shell whose three columns are all spoken
+// for, and would ask "which layer is this for?" on every render instead of
+// once at the point the author asked.
+import { useEffect, useMemo, useState } from "react";
+import { useShotEditor, useStore } from "../../state/context.js";
+import type { ComponentRow } from "../../api.js";
+
+/** The one module whose builtins are TSL generators. Paper's shaders are DOM
+ *  background layers and particles are emitters; neither is a surface a mesh
+ *  can wear, and both would be a card that produced a document the runtime
+ *  cannot resolve. */
+const EFFECTS_MODULE = "@dailies-studio/effects";
+
+/** Fixed shelf order, mirroring the 2D lane's Library. A category this chrome
+ *  does not know (a newer server) appends after, alphabetically, rather than
+ *  vanishing. */
+const CATEGORY_ORDER = ["noise", "patterns", "organic", "space", "material", "decor"];
+
+const CATEGORY_LABELS: Record<string, string> = {
+  noise: "Noise",
+  patterns: "Patterns",
+  organic: "Organic",
+  space: "Space",
+  material: "Material",
+  decor: "Decor",
+};
+
+function categoryLabel(category: string): string {
+  return CATEGORY_LABELS[category] ?? category.charAt(0).toUpperCase() + category.slice(1);
+}
+
+/** A stable colour per id, for a card whose thumbnail has not been generated.
+ *  Deterministic so the same generator always wears the same placeholder. */
+function thumbGradient(id: string): string {
+  let h = 2166136261;
+  for (let i = 0; i < id.length; i += 1) {
+    h ^= id.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  h = h >>> 0;
+  const hue1 = h % 360;
+  const hue2 = (hue1 + 40 + ((h >>> 9) % 160)) % 360;
+  return `linear-gradient(${(h >>> 17) % 360}deg, hsl(${hue1} 45% 30%), hsl(${hue2} 60% 55%))`;
+}
+
+export function MaterialPicker() {
+  const store = useStore();
+  const request = useShotEditor((s) => s.materialPicker);
+  const library = useShotEditor((s) => s.library);
+  const libraryLoaded = useShotEditor((s) => s.libraryLoaded);
+  const [query, setQuery] = useState("");
+
+  useEffect(() => {
+    if (!libraryLoaded) void store.refreshLibrary();
+  }, [libraryLoaded, store]);
+
+  const shelves = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    const rows = library.filter(
+      (row): row is ComponentRow & { effect: NonNullable<ComponentRow["effect"]> } =>
+        row.builtin === true && row.host === "three" && row.rel === EFFECTS_MODULE && row.effect !== undefined,
+    );
+    const matching =
+      needle === ""
+        ? rows
+        : rows.filter(
+            (row) =>
+              row.name.toLowerCase().includes(needle) ||
+              row.effect.tags.some((t) => t.toLowerCase().includes(needle)),
+          );
+    const byCategory = new Map<string, typeof matching>();
+    for (const row of matching) {
+      const list = byCategory.get(row.effect.category);
+      if (list) list.push(row);
+      else byCategory.set(row.effect.category, [row]);
+    }
+    return [...byCategory.entries()].sort((a, b) => {
+      const ai = CATEGORY_ORDER.indexOf(a[0]);
+      const bi = CATEGORY_ORDER.indexOf(b[0]);
+      if (ai === bi) return a[0].localeCompare(b[0]);
+      // An unknown category sorts after every known one rather than at the top.
+      return (ai < 0 ? CATEGORY_ORDER.length : ai) - (bi < 0 ? CATEGORY_ORDER.length : bi);
+    });
+  }, [library, query]);
+
+  if (request === null) return null;
+  const count = request.layerIds.length;
+
+  return (
+    <div className="dialog-overlay" onPointerDown={() => store.closeMaterialPicker()}>
+      <div
+        className="dialog material-picker"
+        role="dialog"
+        aria-label="Choose a material"
+        onPointerDown={(e) => e.stopPropagation()}
+      >
+        <div className="dialog-title">Material</div>
+        <div className="dialog-field">
+          <span className="dialog-label">{count === 1 ? "1 mesh layer" : `${count} mesh layers`}</span>
+          <input
+            className="material-search"
+            type="search"
+            placeholder="Search materials"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            autoFocus
+          />
+        </div>
+        <div className="dialog-body">
+          {!libraryLoaded ? (
+            <p className="dialog-message">Loading…</p>
+          ) : shelves.length === 0 ? (
+            <p className="dialog-message">No material matches “{query}”.</p>
+          ) : (
+            shelves.map(([category, rows]) => (
+              <section key={category} className="material-shelf">
+                <h3>{categoryLabel(category)}</h3>
+                <div className="material-grid">
+                  {rows.map((row) => (
+                    <button
+                      key={row.id}
+                      type="button"
+                      className="material-card"
+                      title={
+                        row.effect.softwareRaster === "unfinished"
+                          ? `${row.name} — may not finish a software-rasterized render (--gl swangle); use --gl angle.`
+                          : row.name
+                      }
+                      onClick={() => store.applyMeshMaterial(request.layerIds, row.id)}
+                    >
+                      {row.effect.thumb === undefined ? (
+                        <span className="material-thumb" style={{ background: thumbGradient(row.id) }} />
+                      ) : (
+                        <img className="material-thumb" src={row.effect.thumb} alt="" />
+                      )}
+                      <span className="material-name">{row.name}</span>
+                      {row.effect.softwareRaster === "unfinished" ? (
+                        <span className="material-badge" aria-hidden="true">
+                          slow
+                        </span>
+                      ) : null}
+                    </button>
+                  ))}
+                </div>
+              </section>
+            ))
+          )}
+        </div>
+        <div className="dialog-actions">
+          <button type="button" onClick={() => store.closeMaterialPicker()}>
+            Cancel
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/panels/stage/StageMenu.tsx

@@ -0,0 +1,38 @@
+// The stage's right-click menu.
+//
+// It is one effect over a MAILBOX. The stage reports a right press, the store
+// parks it on `stageMenu` with a fresh object every time, and this opens the
+// shared `useContextMenu` at that point with the entries `layerMenuEntries`
+// builds. Nothing here decides what a menu says, and nothing here edits a
+// document — see state/menu.ts for why both belong there.
+//
+// ── WHY THE IDENTITY OF THE MAILBOX MATTERS ─────────────────────────────
+//
+// A second right-click at the same point on the same layer is the same VALUE
+// and a different EVENT. The effect keys on the object, so the store minting a
+// fresh one per press is what makes the menu open again rather than once.
+import { useEffect } from "react";
+import { useContextMenu } from "@dailies-studio/ui";
+import { layerMenuEntries, menuTargetsFor } from "../../state/menu.js";
+import { useShotEditor, useStore } from "../../state/context.js";
+
+export function StageMenu() {
+  const store = useStore();
+  const request = useShotEditor((s) => s.stageMenu);
+  const menu = useContextMenu();
+  const { open, close } = menu;
+  useEffect(() => {
+    if (request === null) {
+      close();
+      return;
+    }
+    // Read at OPEN time, not through the selector: the store has already
+    // applied this press's selection policy by the time the mailbox lands, so
+    // the entries describe what is actually selected rather than what was.
+    const state = store.getState();
+    const entries = layerMenuEntries(store, state, menuTargetsFor(state, state.selection));
+    if (entries.length === 0) return;
+    open(request.at, entries);
+  }, [request, store, open, close]);
+  return <>{menu.menu}</>;
+}

package/src/panels/stage/StagePanel.tsx

@@ -0,0 +1,131 @@
+// The stage iframe. Mounted ONCE, for the life of the chrome.
+//
+// /shot-stage.html is served through the project's Vite
+// (virtual:shot-stage-entry) so the three stack resolves to the studio's pinned
+// copies. `connectStage` polls for `window.__shotStudio` after each load (a
+// Vite-triggered reload mints a fresh bridge — reconnect and re-attach) and
+// registers the STORE's handlers; the store then owns every push: doc on
+// history change, frame on seek, selection on every selection write, and the
+// full re-push on `onReady`.
+//
+// This component is DELIBERATELY nothing but the iframe and its connect effect.
+// It renders no conditional siblings, holds no error state and takes no
+// children, because it is the shell's backdrop: `App` mounts it as the
+// unconditional, unkeyed FIRST child of the shell root and the CSS pins it
+// `position: fixed; inset: 0` behind the floating panels. Anything conditional
+// living in here would share a parent with the iframe, and the whole point of
+// the arrangement is that no shell state can reorder, reparent or remount it.
+//
+// A REMOUNT IS EXPENSIVE HERE IN A WAY IT IS NOT IN THE 2D LANE: it costs a
+// full iframe document load, a fresh WebGPU adapter request, every layer raster
+// re-drawn, and a dead stage for at least one connect poll — and the module-
+// level raster LRU lives in the iframe's realm, so it dies with it.
+// test/stageIdentity.test.tsx is the gate.
+//
+// The connect FAILURE therefore reports upward, into the shell's overlay strip,
+// rather than rendering a sibling strip here.
+//
+// Note main.tsx mounts under StrictMode, so this effect double-runs in dev:
+// connect, abort + attachStage(null), connect again. The abort path rejects
+// with "stage connect aborted" and is swallowed. The iframe ELEMENT is not
+// remounted by that — only the effect re-runs — and any future effect touching
+// the bridge must survive the same double-invoke.
+import { useEffect, useRef } from "react";
+import { useStore } from "../../state/context.js";
+import { connectStage } from "../../bridge.js";
+
+/** The stage URL, resolved ONCE at module load. Only the perf flag crosses the
+ *  boundary — never the chrome's whole search string: the chrome rewrites
+ *  ?shot/?scene via history.replaceState, and an iframe src interpolating live
+ *  location.search would RELOAD the stage (fresh WebGPU adapter, every raster
+ *  redrawn) on every document switch. */
+const STAGE_SRC =
+  "/shot-stage.html" +
+  (typeof window !== "undefined" && new URLSearchParams(window.location.search).get("perf") === "1"
+    ? "?perf=1"
+    : "");
+
+export function StagePanel({
+  /** Report a stage connect failure to the shell's overlay strip (null clears). */
+  onConnectError,
+}: {
+  onConnectError: (message: string | null) => void;
+}) {
+  const store = useStore();
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const aborter = new AbortController();
+    const connect = (): void => {
+      onConnectError(null);
+      void connectStage(iframe, store.stageHandlers, { signal: aborter.signal })
+        .then((bridge) => {
+          if (!aborter.signal.aborted) store.attachStage(bridge);
+        })
+        .catch((e) => {
+          if (!aborter.signal.aborted) {
+            onConnectError(e instanceof Error ? e.message : String(e));
+          }
+        });
+    };
+    iframe.addEventListener("load", connect);
+    connect(); // the load event may already have fired
+    return () => {
+      aborter.abort();
+      iframe.removeEventListener("load", connect);
+      store.attachStage(null);
+      // The error belonged to the connection being torn down; it is the shell's
+      // state now, so it has to be cleared explicitly rather than dying with a
+      // local useState.
+      onConnectError(null);
+    };
+  }, [store, onConnectError]);
+
+  return (
+    <iframe
+      ref={iframeRef}
+      className="stage-frame"
+      src={STAGE_SRC}
+      title="Stage"
+      // The stage pins the cursor for the duration of a G / R / S transform,
+      // and an iframe cannot without the delegation. Without it
+      // `requestPointerLock` rejects and the modal falls back to cancelling
+      // when the pointer leaves — which is what it did before.
+      allow="pointer-lock"
+      onPointerEnter={focusStage}
+    />
+  );
+}
+
+/**
+ * KEYBOARD FOCUS FOLLOWS THE POINTER ONTO THE STAGE.
+ *
+ * This lane spans two documents and keyboard events go to exactly one of them.
+ * The stage relays every key it receives UP into the same resolver the chrome
+ * uses (`onKey`), so a focused stage loses nothing — but the reverse is not
+ * true: the stage holds key state the chrome cannot see, and `spaceRef` (the
+ * pan gate in StageApp) is the load-bearing one. With focus in the chrome,
+ * holding space and dragging the stage did not pan; it played the shot and
+ * orbited, and nothing anywhere said why. On a fresh load focus starts in the
+ * chrome, so that was the FIRST thing an author met.
+ *
+ * Entering rather than pressing, because the gesture is "hold space, THEN
+ * press" — a focus move on pointerdown arrives one press too late.
+ *
+ * NOT WHILE SOMETHING IS BEING TYPED INTO. Sliding the pointer across the
+ * canvas while naming a layer must not swallow the rest of the name. The chrome
+ * can read its own `activeElement`, which is the only side of the boundary this
+ * check needs.
+ */
+function focusStage(e: React.PointerEvent<HTMLIFrameElement>): void {
+  const active = document.activeElement as HTMLElement | null;
+  if (
+    active !== null &&
+    (active.isContentEditable || active.tagName === "INPUT" || active.tagName === "TEXTAREA")
+  ) {
+    return;
+  }
+  e.currentTarget.focus();
+}

package/src/panels/timeline/AudioLane.tsx

@@ -0,0 +1,340 @@
+// The audio lane: one coloured band per clip at its MASTER position.
+//
+// ── WHY IT IS ONE LANE AND NOT A TRACK PER CLIP ─────────────────────────
+//
+// `doc.audio` is a flat record of master-timed clips with no lane field, and
+// the reference editor draws one music bed under the whole video. A lane-packer
+// would be inventing a document concept the schema deliberately does not have,
+// and the first thing it would need is somewhere to persist which lane a clip
+// landed in. Clips overlap by drawing over each other, in document order.
+//
+// ── THE GESTURES ────────────────────────────────────────────────────────
+//
+//   BODY      moves the clip — and every marker inside it (see writeAudioDrag).
+//   ⌥ BODY    SLIPS the source under a bar that stays put.
+//   IN / OUT  trim; the head trim moves `offsetFrames` with `frame` so the
+//             audio under the remaining bar does not slide.
+//   FADES     the two corner handles, dragged along the bar.
+//   GAIN      the horizontal rubber band, dragged vertically.
+//
+// All of them go through `beginBlockDrag`/`endBlockDrag`, which is the dock's
+// ONE history scrub: each gesture is one undo entry and Escape restores the
+// base by reference. All of them snap through the shared `snap.ts` — there is
+// no second snapper in this lane.
+import { useEffect, useRef, useState } from "react";
+import type { PointerEvent as ReactPointerEvent } from "react";
+import { drawClipWaveform, frameToPx, loadPeaks, startDrag } from "@dailies-studio/timeline";
+import type { PeakData } from "@dailies-studio/timeline";
+import { framesToSeconds } from "@dailies-studio/engine";
+import type { Rational } from "@dailies-studio/engine";
+import { MAX_AUDIO_GAIN } from "@dailies-studio/shot/doc";
+import type { AudioClipRef, ShotAsset } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { audioClipView, frameDelta } from "./model.js";
+import type { AudioDrag } from "./model.js";
+import { isSnapSuppressed } from "./snap.js";
+import type { SnapPress } from "./snap.js";
+
+const WAVE_COLOR = "rgba(150, 205, 255, 0.7)";
+/** Canvas px. Matches the bar's inner height in styles.css. */
+const WAVE_H = 26;
+
+export function AudioLane(props: { ppf: number; labelWidth: number; beginSnap?: SnapPress }) {
+  const { ppf, labelWidth, beginSnap } = props;
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const [error, setError] = useState<string | null>(null);
+  const [importing, setImporting] = useState(false);
+  const [over, setOver] = useState(false);
+  const fileRef = useRef<HTMLInputElement | null>(null);
+
+  if (doc === null) return null;
+  const clips = Object.values(doc.audio);
+
+  /**
+   * NEW CLIPS LAND AT THE PLAYHEAD, dropped ones included.
+   *
+   * A drop carries an x, and every NLE reads it as the position. This chrome
+   * has one creation rule and it is the playhead — the toolbar, the shot button
+   * and the layer tools all obey it — and a lane that quietly used a different
+   * one would make "where does the thing I make appear" a question with two
+   * answers. The clip is draggable the moment it exists.
+   */
+  const importFiles = (files: FileList | null): void => {
+    const file = files?.[0];
+    if (file === undefined) return;
+    setError(null);
+    setImporting(true);
+    void store
+      .importAudio(file)
+      .catch((e: unknown) => setError(e instanceof Error ? e.message : String(e)))
+      .finally(() => setImporting(false));
+  };
+
+  return (
+    <div
+      className={`audio-lane${over ? " is-over" : ""}`}
+      data-testid="audio-lane"
+      onDragOver={(e) => {
+        e.preventDefault();
+        setOver(true);
+      }}
+      onDragLeave={() => setOver(false)}
+      onDrop={(e) => {
+        e.preventDefault();
+        setOver(false);
+        importFiles(e.dataTransfer?.files ?? null);
+      }}
+    >
+      <div className="audio-label-cell" style={{ width: labelWidth }}>
+        <span className="audio-lane-name">Audio</span>
+        <button
+          type="button"
+          className="audio-add"
+          title="Import audio at the playhead"
+          disabled={importing}
+          onClick={() => fileRef.current?.click()}
+        >
+          {importing ? "…" : "+"}
+        </button>
+        <input
+          ref={fileRef}
+          className="audio-file-input"
+          type="file"
+          accept="audio/*"
+          hidden
+          data-testid="audio-file-input"
+          onChange={(e) => {
+            importFiles(e.currentTarget.files);
+            // Cleared so re-picking the SAME file fires change again.
+            e.currentTarget.value = "";
+          }}
+        />
+      </div>
+      <div className="audio-track">
+        {clips.length === 0 && !importing ? (
+          <span className="audio-empty">Drop an audio file here, or press +</span>
+        ) : null}
+        {clips.map((clip) => (
+          <AudioClipBar
+            key={clip.id}
+            clip={clip}
+            asset={doc.assets[clip.asset]}
+            fps={doc.fps}
+            ppf={ppf}
+            beginSnap={beginSnap}
+          />
+        ))}
+      </div>
+      {error === null ? null : (
+        <p className="audio-error" role="status" data-testid="audio-error">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+function AudioClipBar(props: {
+  clip: AudioClipRef;
+  asset: ShotAsset | undefined;
+  fps: Rational;
+  ppf: number;
+  beginSnap: SnapPress | undefined;
+}) {
+  const { clip, asset, fps, ppf, beginSnap } = props;
+  const store = useStore();
+  const c = audioClipView(clip);
+  const left = frameToPx(c.frame, ppf);
+  const width = Math.max(8, frameToPx(c.durationFrames, ppf));
+
+  /**
+   * One press handler for every frame-valued gesture.
+   *
+   * `anchor` is WHAT THE POINTER IS CARRYING, in master frames, because that is
+   * the edge the snap has to bite on: the out edge for an out drag, the fade
+   * corners for the fade handles, the clip's own start for a slip (the bar is
+   * not moving, but the source under it is measured from there).
+   */
+  const drag =
+    (mode: AudioDrag) =>
+    (e: ReactPointerEvent<HTMLElement>): void => {
+      e.preventDefault();
+      e.stopPropagation();
+      // Read AT THE PRESS: a gesture whose meaning changed under a key held
+      // mid-drag would slip a clip the author was only moving.
+      const effective: AudioDrag = mode === "body" && e.altKey ? "slip" : mode;
+      const startX = e.clientX;
+      const snap = beginSnap?.({ audioClipId: clip.id }, isSnapSuppressed(e));
+      const anchor =
+        effective === "out"
+          ? c.frame + c.durationFrames
+          : effective === "fade-in"
+            ? c.frame + c.fadeInFrames
+            : effective === "fade-out"
+              ? c.frame + c.durationFrames - c.fadeOutFrames
+              : c.frame;
+      store.beginBlockDrag();
+      startDrag(e, {
+        onMove(ev) {
+          const raw = frameDelta(ev.clientX - startX, ppf);
+          const delta = snap === undefined ? raw : snap(anchor + raw) - anchor;
+          store.dragAudio(clip.id, effective, delta);
+        },
+        onEnd: (commit) => store.endBlockDrag(commit),
+      });
+    };
+
+  /** The rubber band. Vertical, and NOT snapped: gain has no other gain to
+   *  land on, and the frame targets are the wrong axis entirely. */
+  const dragGain = (e: ReactPointerEvent<HTMLElement>): void => {
+    e.preventDefault();
+    e.stopPropagation();
+    const startY = e.clientY;
+    const from = c.gain;
+    const height = e.currentTarget.parentElement?.clientHeight ?? WAVE_H;
+    store.beginBlockDrag();
+    startDrag(e, {
+      onMove(ev) {
+        // Down is louder-negative: the band's top is MAX_AUDIO_GAIN.
+        store.dragAudioGain(clip.id, from - ((ev.clientY - startY) / Math.max(1, height)) * MAX_AUDIO_GAIN);
+      },
+      onEnd: (commit) => store.endBlockDrag(commit),
+    });
+  };
+
+  const fadeInPx = frameToPx(c.fadeInFrames, ppf);
+  const fadeOutPx = frameToPx(c.fadeOutFrames, ppf);
+
+  return (
+    <div
+      className={`audio-clip${c.muted ? " is-muted" : ""}`}
+      data-audio-clip={clip.id}
+      style={{ left, width }}
+      onPointerDown={drag("body")}
+      title={`${asset?.path ?? clip.asset} · drag to move it and its markers, ⌥drag to slip the source, ⌘drag to ignore snapping`}
+    >
+      <AudioWaveform clip={c} asset={asset} fps={fps} widthPx={width} />
+
+      {/* The fade ramps, drawn as ONE polyline over the whole bar so the two
+          fades and the flat middle cannot disagree about the level between
+          them. Inert: the corner handles below take the pointer. */}
+      {c.fadeInFrames > 0 || c.fadeOutFrames > 0 ? (
+        <svg className="audio-fade-curve" viewBox={`0 0 ${width} ${WAVE_H}`} preserveAspectRatio="none" aria-hidden="true">
+          <polyline
+            points={`0,${WAVE_H} ${fadeInPx},0 ${Math.max(fadeInPx, width - fadeOutPx)},0 ${width},${WAVE_H}`}
+            fill="none"
+          />
+        </svg>
+      ) : null}
+
+      <span
+        className="audio-gain-band"
+        data-handle="audio-gain"
+        style={{ bottom: `${(c.gain / MAX_AUDIO_GAIN) * 100}%` }}
+        onPointerDown={dragGain}
+        title={`Gain ${c.gain.toFixed(2)} — drag up or down`}
+      />
+
+      <span className="audio-clip-name">{asset?.path.replace(/^[0-9a-f]{8}-/, "") ?? clip.asset}</span>
+
+      <span
+        className="audio-handle audio-handle-in"
+        data-handle="audio-in"
+        onPointerDown={drag("in")}
+        aria-hidden="true"
+      />
+      <span
+        className="audio-handle audio-handle-out"
+        data-handle="audio-out"
+        onPointerDown={drag("out")}
+        aria-hidden="true"
+      />
+      <span
+        className="audio-fade audio-fade-in"
+        data-handle="audio-fade-in"
+        style={{ left: fadeInPx }}
+        onPointerDown={drag("fade-in")}
+        title={`Fade in ${c.fadeInFrames}f`}
+      />
+      <span
+        className="audio-fade audio-fade-out"
+        data-handle="audio-fade-out"
+        style={{ left: Math.max(0, width - fadeOutPx) }}
+        onPointerDown={drag("fade-out")}
+        title={`Fade out ${c.fadeOutFrames}f`}
+      />
+
+      <span className="audio-clip-buttons">
+        <button
+          type="button"
+          className="audio-clip-btn"
+          aria-label={c.muted ? "Unmute clip" : "Mute clip"}
+          aria-pressed={c.muted}
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={() => store.toggleAudioMute(clip.id)}
+        >
+          {c.muted ? "🔇" : "🔊"}
+        </button>
+        <button
+          type="button"
+          className="audio-clip-btn"
+          aria-label="Remove clip"
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={() => store.removeAudio(clip.id)}
+        >
+          ×
+        </button>
+      </span>
+    </div>
+  );
+}
+
+/**
+ * The clip's slice of its source, drawn from the asset's ONE fine peak level.
+ *
+ * `loadPeaks` is keyed on the content-addressed asset PATH, so every clip of
+ * the same track shares one decode and a zoom only picks a different integer
+ * decimation out of it — nothing here refetches. (Not the asset id: that is a
+ * filename slug this lane mints per document, so it repeats across shots.)
+ */
+function AudioWaveform(props: {
+  clip: { offsetFrames: number; durationFrames: number };
+  asset: ShotAsset | undefined;
+  fps: Rational;
+  widthPx: number;
+}) {
+  const { clip, asset, fps, widthPx } = props;
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const [data, setData] = useState<PeakData | null>(null);
+
+  useEffect(() => {
+    if (asset === undefined) return;
+    let alive = true;
+    loadPeaks(asset)
+      .then((d) => {
+        if (alive) setData(d);
+      })
+      .catch(() => {
+        // Decoration. A clip with no waveform still trims, fades and plays.
+      });
+    return () => {
+      alive = false;
+    };
+  }, [asset]);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (canvas === null || data === null || data.peaks.length === 0) return;
+    drawClipWaveform(canvas, {
+      data,
+      fromSeconds: framesToSeconds(clip.offsetFrames, fps),
+      toSeconds: framesToSeconds(clip.offsetFrames + clip.durationFrames, fps),
+      widthPx,
+      heightPx: WAVE_H,
+      color: WAVE_COLOR,
+    });
+  }, [data, widthPx, fps, clip.offsetFrames, clip.durationFrames]);
+
+  return <canvas className="audio-wave" ref={canvasRef} aria-hidden="true" />;
+}