@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/LifespanRow.tsx

@@ -1,19 +1,24 @@
-// A layer's LIFESPAN bar: one rounded bar per layer, at its master position.
+// A layer's LIFESPAN bar: one rounded bar per layer, at its master position —
+// and, for a `kind: "video"` layer, that bar is a CLIP: a filmstrip over the
+// recording's own waveform.
 //
-// ── THE BLOCK IS THE ATOM, AND THE LIFESPAN IS THE LAYER ────────────────
+// ── THE LIFESPAN IS THE LAYER ───────────────────────────────────────────
 //
-// The disclosure triangle expands this row into one DERIVED row per channel
-// the layer's blocks write (ChannelRow.tsx) — property rows with keyframe
-// diamonds, the Figma/Lottie read. The channel rows are views, never storage:
-// every gesture on one drags the whole BLOCK, in one undo entry, and the
-// preset's name lives in the span's tooltip and the Animate tab. The block is
-// still where this timeline's DOCUMENT stops.
+// The disclosure triangle expands this row into one row per tracked property
+// (ChannelRow.tsx), with keyframe diamonds, the Figma/Lottie read.
 //
 // ── THREE GESTURES, AND WHY THE THIRD IS NOT OPTIONAL ───────────────────
 //
-//   BODY drags the bar AND every block on the layer with it.
-//   IN / OUT move one end and touch no block.
-//   SLIP (⌥ held) moves every block and leaves the bar exactly where it is.
+//   BODY drags the bar AND every keyframe on the layer with it.
+//   IN / OUT move one end and touch no keyframe.
+//   SLIP (⌥ held) moves every keyframe and leaves the bar exactly where it is.
+//
+// ⇧ MEANS NOTHING ON THESE THREE, and that is a decision rather than an
+// omission. ⌥ has been the slip on every row kind since this dock shipped, so
+// a chord that merely adds ⇧ is a slip an author already had in their hands:
+// reading it as some other gesture would retime an ordinary layer from a key
+// combination whose meaning nobody announced changing. ⇧⌥ is therefore the
+// slip too, everywhere except a clip, where the chord is new (below).
 //
 // Body-versus-edge is After Effects verbatim, and no tool makes it a preference
 // — so there is no setting here either. SLIP is the one every two-gesture
@@ -26,140 +31,818 @@
 // restores the document by reference — every capture re-derives from the base,
 // which is also why the delta below is measured from the press and never
 // accumulated.
+//
+// ── AND WHAT A VIDEO BAR ADDS ───────────────────────────────────────────
+//
+// The same three words mean the clip ops for a video layer (`writeLifespan`
+// dispatches; this file only names the gesture), plus two the other kinds have
+// no use for:
+//
+//   ⇧⌥ BODY   slides THIS bar alone, out of a selection that would otherwise
+//             travel with it. A CLIP GESTURE ONLY: on every other kind the
+//             chord stays the slip it has always been.
+//   ROLL      the handle on the waveform half of an abutting out edge: it moves
+//             the SEAM, so this clip's tail and the next clip's head trade
+//             frames and nothing around the pair shifts.
+//
+// On every kind, the body drag carries the whole selection when the pressed bar
+// is in it, which is what selecting three bars in order to move them together
+// means. ⇧-click adds a bar to the selection or takes it out.
+//
+// ── AND WHY THE BAR IS DOM, LIKE EVERY OTHER BAR IN THIS DOCK ───────────
+//
+// Two canvases hang inside it — `Filmstrip` for the picture and `AudioWaveform`
+// for the sound, both pixel data with no DOM spelling — and everything else,
+// the bar, the edge, the held-frame hatch, the handles and the label, stays
+// elements, because that is what the rest of the dock is and what its
+// hit-testing, its hover and its tests all assume.
 import { frameToPx, startDrag } from "@dailies-studio/timeline";
-import type { PointerEvent as ReactPointerEvent } from "react";
+import {
+  IconChevron,
+  IconChevronDown,
+  IconEye,
+  IconEyeOff,
+  IconLock,
+  IconUnlock,
+  IconVolume,
+  IconVolumeOff,
+} from "@dailies-studio/ui";
+import type { CSSProperties, PointerEvent as ReactPointerEvent } from "react";
+import type { Rational } from "@dailies-studio/engine";
+import { firstKeyframeFrame, isDefId, legalRollRange, legalTrimRange, setVideoSound } from "@dailies-studio/shot/doc";
+import type { Layer3D, VideoLayer3D } from "@dailies-studio/shot/doc";
+import { MASK_ICON, iconFor, isComponentGlyph } from "../../icons.js";
+import { MaskBracket } from "../maskMarks.js";
+import type { MaskMarks } from "../maskMarks.js";
 import { useShotEditor, useStore } from "../../state/context.js";
-import type { LifespanDrag, MasterRow } from "./model.js";
-import { frameDelta } from "./model.js";
+import { AudioWaveform } from "./AudioLane.js";
+import { Filmstrip } from "./Filmstrip.js";
+import type { HeldSpan, LifespanDrag, MasterRow, VideoRow } from "./model.js";
+import {
+  CLIP_NAME_GAP_PX,
+  VIDEO_EDGE_H,
+  VIDEO_PICTURE_H,
+  VIDEO_ROW_H,
+  VIDEO_WAVE_H,
+  clipNamePlace,
+  clipRowOf,
+  frameDelta,
+  lifespanOf,
+  trimHandlePx,
+} from "./model.js";
+import { StaggerChip, StaggerGhost, setStaggerPreview, useStaggerGhost, useStaggerReadout } from "./staggerPreview.js";
 import type { SnapPress } from "./snap.js";
 import { isSnapSuppressed } from "./snap.js";
+import { useLive } from "./useLive.js";
+import { formatCombo } from "../../state/shortcuts.js";
+import { PeerDots } from "../header/PresenceStack.js";
 
 /** ⌥ turns a body drag into a slip. Alt is the modifier both AE and Premiere
  *  put on the timeline's third gesture, and it does not collide with the snap
  *  suppressor (⌘/ctrl) — so a slip can be snapped or not, like every other
- *  drag. */
+ *  drag.
+ *
+ *  ⇧ IS NOT READ HERE. Requiring `!shiftKey` would have silently taken ⇧⌥ away
+ *  from every row kind that already had it as a slip; the one row where the
+ *  chord means something else is the clip, and `gestureOf` is where that fork
+ *  lives so it can be read against the row's kind in one place. */
 function isSlip(event: { altKey: boolean }): boolean {
   return event.altKey;
 }
 
+/** ⇧⌥ is the slide: the same body move, on this bar alone. A CLIP gesture, and
+ *  `gestureOf` is the only caller because it is the only reader that knows
+ *  whether this row is one. */
+function isSolo(event: { altKey: boolean; shiftKey: boolean }): boolean {
+  return event.altKey && event.shiftKey;
+}
+
+/**
+ * THE HELD-FRAME HATCH.
+ *
+ * A frozen tail looks EXACTLY like footage on a filmstrip — the last picture,
+ * repeated, is still a picture — so an author who cannot see it ships a shot
+ * that stops moving three seconds before it ends. Diagonal hatching over both
+ * strips is the mark, because it survives whatever the tile under it happens to
+ * be: a light frame, a dark frame, or no strip at all.
+ *
+ * Built from `--timeline-ink` rather than a fixed colour, so it reads in both
+ * appearances against both the picture and the waveform.
+ */
+const HELD_HATCH =
+  "repeating-linear-gradient(135deg," +
+  " color-mix(in srgb, var(--timeline-ink) 34%, transparent) 0 1.5px," +
+  " color-mix(in srgb, var(--timeline-ink) 6%, transparent) 1.5px 5px)";
+
 export function LifespanRow({
   row,
+  layer,
   sceneId,
   sceneStart,
+  originFrames = 0,
   ppf,
+  fps,
   labelWidth,
+  laneW,
   expanded,
+  revealed = false,
   onToggle,
   beginSnap,
+  mask,
 }: {
   row: MasterRow;
+  /**
+   * The row's own layer, for its KIND GLYPH. A dock row and an outliner row
+   * naming the same element drew two different things: a name here, a name and
+   * its icon there. The glyph is the taxonomy, so it belongs to both.
+   *
+   * Optional because `MasterRow` is the dock's projection and carries no layer:
+   * the caller resolves it out of the container the row lives in, and a row
+   * whose layer has just been deleted under a render draws its name alone
+   * rather than throwing.
+   */
+  layer?: Layer3D | undefined;
   sceneId: string;
-  /** The scene's master start. Drawing only: the store takes a scene-local
-   *  DELTA, which is the same number in both clocks. */
+  /** The scene's master start. Drawing AND the snap conversion below: the store
+   *  takes a scene-local DELTA, which is the same number in both clocks. */
   sceneStart: number;
+  /** The shot context's re-zero. DRAWING ONLY — never the snap conversion, or a
+   *  drag inside a shot would snap `start` frames from where it should. */
+  originFrames?: number;
   ppf: number;
+  /** The container's rate. A video row turns source FRAMES into the seconds its
+   *  strip and its peaks are cut on; every other row ignores it. */
+  fps: Rational;
   labelWidth: number;
+  /** The track's drawn width, so a name too long for its clip can go beside it
+   *  on the side that has room (`clipNamePlace`). Absent: the name stays in. */
+  laneW?: number;
   expanded: boolean;
+  /** A pick elsewhere just revealed this row: flash it once (`is-revealed`). */
+  revealed?: boolean;
   onToggle(): void;
   beginSnap?: SnapPress;
+  /** The row's mask marks (gap 7): the glyph, the bracket and the bar's mode
+   *  label, read by `maskMarksOf` like the outline's. */
+  mask?: MaskMarks | undefined;
 }) {
   const store = useStore();
+  // MEMBERSHIP, not the array. Subscribing to `s.selection` woke every lifespan
+  // row on screen for every selection change, when the only rows whose output
+  // moved are the two whose membership flipped. The whole selection is read at
+  // the PRESS instead, off the store, which is the only moment the drag handler
+  // below wants it.
   const selected = useShotEditor((s) => s.selection.includes(row.layerId));
+  const ghostFrom = useStaggerGhost(row.layerId);
+  const readout = useStaggerReadout(row.layerId);
   const { lifespan } = row;
+  // THE ONE PREDICATE, and `expandedLayerHeight` in TimelineDock reads the same
+  // call: see `clipRowOf` for why the height and the render cannot be allowed
+  // two answers. Read once here, for the class, the box and the body alike.
+  const video = clipRowOf(layer, row);
 
   /** Selecting a row in another scene NAVIGATES first: the stage shows one
    *  scene, so handles on a layer three scenes away would be handles on
    *  nothing — and `select` orders within the current scene, so the selection
-   *  would resolve to empty. */
-  const pick = (): void => {
+   *  would resolve to empty.
+   *
+   *  ⇧ (without ⌥, which is the slide) toggles this row in a selection of the
+   *  same container, as in every design tool. Pressing a row that is already
+   *  selected keeps the selection, so the group a drag carried is still the
+   *  selection after it lands. */
+  const pick = (e?: { shiftKey: boolean; altKey: boolean }): void => {
+    const s = store.getState();
+    const here = s.editingDef === null ? sceneId === s.sceneId : sceneId === s.editingDef;
+    if (here && e?.shiftKey === true && !e.altKey) {
+      store.select(
+        s.selection.includes(row.layerId)
+          ? s.selection.filter((id) => id !== row.layerId)
+          : [...s.selection, row.layerId],
+      );
+      return;
+    }
     store.focusScene(sceneId);
-    store.select([row.layerId]);
+    if (!(here && s.selection.includes(row.layerId))) store.select([row.layerId]);
   };
 
   const drag =
-    (mode: LifespanDrag) =>
+    (mode: "body" | "in" | "out" | "roll") =>
     (e: ReactPointerEvent<HTMLElement>): void => {
       e.preventDefault();
       e.stopPropagation();
-      pick();
+      // WHAT IS MOVING is decided BEFORE the selection changes. Pressing a bar
+      // that is already selected moves the group and keeps it selected;
+      // pressing any other bar selects it and moves it alone, which is what
+      // every NLE does.
+      //
+      // NOT INSIDE A DEFINITION: a group move goes through `shiftLayer`, which
+      // only finds layers in `doc.scenesById`, so there the plain "body" moves
+      // the pressed bar. This list is also the snap exclusion below, so it must
+      // name exactly the bars that move.
+      //
+      // A ROLL IS THE OTHER TWO-BAR GESTURE, and it is the exclusion half of
+      // this list rather than the group half. A seam IS the partner's `in` and
+      // this bar's `out` at one frame, so a roll that named only its own row
+      // offered the snapper a target sitting exactly on the frame being
+      // dragged: the pull won every comparison and the drag stuck where it
+      // already was. `gestureOf` returns the roll before it ever reads this
+      // list, so widening it here cannot turn a roll into a group move.
+      //
+      // The partner's OTHER edge and its keys go with it, which is the same
+      // ceiling the pressed row has always paid: the exclusion's grain is a
+      // layer, not a frame.
+      const carried =
+        mode === "roll"
+          ? video?.rollPartner == null
+            ? [row.layerId]
+            : [row.layerId, video.rollPartner]
+          : mode === "body" && selected && !isDefId(sceneId)
+            ? store.getState().selection
+            : [row.layerId];
+      pick(e);
       const startX = e.clientX;
       // Read at the PRESS: the pose the drag is measured from, and the two
       // modifiers. A gesture whose meaning changed under a held key mid-drag
       // would retime an animation the author was only moving.
-      const slipping = mode === "body" && isSlip(e);
-      const effective: LifespanDrag = slipping ? "slip" : mode;
-      const snap = beginSnap?.({ sceneId, layerId: row.layerId }, isSnapSuppressed(e));
-      // WHAT THE POINTER IS CARRYING is what snaps: the out edge for an out
-      // drag, the earliest block for a slip (the bar is not moving), the in
-      // edge for everything else.
+      const effective = gestureOf(mode, e, video ?? null, carried);
+      if (effective === null) return;
+      // ── WHERE THIS EDGE MAY LEGALLY LAND ──────────────────────────────
+      //
+      // A clip's edge is bounded by its FOOTAGE as well as by its scene, and
+      // `trimLayer` refuses rather than clamps when the constraints do not
+      // intersect. The range is read ONCE, at the press, and spends itself
+      // twice: it bounds the pointer's own travel below, and it goes to the
+      // snapper, which drops every target outside it at collection time. That
+      // second half is why an edge cannot stick to a guide the op would then
+      // clamp away from.
+      //
+      // A SEAM IS BOUNDED THE SAME WAY, through `legalRollRange`, and it is
+      // wired for the same half: `rollLayers` already clamps the frame it
+      // writes, so without this the document was right and the GUIDE was free
+      // to point at a frame the op would then clamp away from, which reads as
+      // a broken drag even when what lands is legal.
+      const doc = store.getState().doc;
+      const legal =
+        doc === null || video === undefined
+          ? null
+          : mode === "in" || mode === "out"
+            ? legalTrimRange(doc, sceneId, row.layerId, mode)
+            : mode === "roll" && video.rollPartner !== null
+              ? legalRollRange(doc, sceneId, row.layerId, video.rollPartner)
+              : null;
+      const clampLegal = (sceneFrame: number): number =>
+        legal === null || legal.empty === true
+          ? sceneFrame
+          : Math.max(legal.min, Math.min(legal.max, sceneFrame));
+      // EVERY BAR THIS GESTURE CARRIES is excluded from the target list, not
+      // just the pressed one: a bar sits exactly on its own edge, so any one of
+      // the others would win every comparison and pin the drag at zero travel.
+      //
+      // A STAGGER DOES NOT SNAP (Paper page 23): each bar moves a different
+      // distance, so a guide under the pointer would describe none of them.
+      const stagger = typeof effective !== "string" && "stagger" in effective;
+      const snap = stagger
+        ? undefined
+        : beginSnap?.(
+            carried.length > 1
+              ? { sceneId, layerId: row.layerId, layerIds: carried }
+              : { sceneId, layerId: row.layerId },
+            isSnapSuppressed(e),
+            // MASTER frames, because that is the base the targets are collected
+            // in. An empty range survives the shift as an empty one, so
+            // "nowhere legal to go" still filters everything out.
+            legal === null ? undefined : { min: legal.min + sceneStart, max: legal.max + sceneStart },
+          );
+      // WHAT THE POINTER IS CARRYING is what snaps, and for a slip that is
+      // never the bar: the bar does not move. A non-video slip carries its
+      // earliest keyframe; a video slip carries the source's own t=0 crossing, so
+      // "put the start of the take on this beat" is the alignment the pull
+      // offers. Everything else carries the edge it is dragging.
       const anchor =
-        effective === "out"
+        mode === "out" || mode === "roll"
           ? lifespan.out
-          : effective === "slip"
-            ? row.blocks.reduce((min, b) => Math.min(min, b.frame), Infinity)
-            : lifespan.in;
+          : effective !== "slip"
+            ? lifespan.in
+            : video === undefined
+              ? firstKeyframeFrame(layer?.tracks)
+              : video.offsetFrames;
+      // The ghosts: each moving bar's `in` at the press, in the lane's own
+      // drawing clock, which is the clock every row draws its bar in. A stagger
+      // never runs inside a definition (`carried` is one bar there), so the
+      // container is a scene.
+      const scene = doc?.scenesById[sceneId];
+      const from: Record<string, number> = {};
+      if (stagger && scene !== undefined)
+        for (const id of carried) {
+          const layer = scene.layersById[id];
+          if (layer !== undefined) from[id] = sceneStart - originFrames + lifespanOf(layer, scene.durationFrames).in;
+        }
+      if (stagger) setStaggerPreview({ from, grabbed: row.layerId, step: 0 });
       store.beginBlockDrag();
       startDrag(e, {
         onMove(ev) {
           const raw = frameDelta(ev.clientX - startX, ppf);
+          const want = clampLegal(anchor + raw);
           // A signed delta into master space and straight back, so the store
           // still only ever sees a scene-local number.
-          const delta =
-            snap === undefined || !Number.isFinite(anchor)
-              ? raw
-              : snap(anchor + raw + sceneStart) - sceneStart - anchor;
-          store.dragLifespan(sceneId, row.layerId, effective, delta);
+          //
+          // NO SECOND CLAMP around the snapper: every target it can answer with
+          // is inside the range now, and its other answer is the rounded
+          // candidate, which is bounded on the line above and cannot round out
+          // of a range whose ends are integers.
+          const landed = snap === undefined || !Number.isFinite(anchor) ? want : snap(want + sceneStart) - sceneStart;
+          store.dragLifespan(sceneId, row.layerId, effective, landed - anchor);
+          if (stagger) setStaggerPreview({ from, grabbed: row.layerId, step: Math.round(landed - anchor) });
+        },
+        onEnd: (commit) => {
+          if (stagger) setStaggerPreview(null);
+          store.endBlockDrag(commit);
         },
-        onEnd: (commit) => store.endBlockDrag(commit),
       });
     };
 
-  const left = frameToPx(sceneStart + lifespan.in, ppf);
+  // Named once and used twice, for `useLive`'s reason: the frame the bar is
+  // DRAWN at and the frame it is judged live at must be one arithmetic.
+  const startLane = sceneStart - originFrames + lifespan.in;
+  const live = useLive(startLane, startLane + (lifespan.out - lifespan.in), originFrames);
+  const left = frameToPx(startLane, ppf);
   const width = Math.max(8, frameToPx(lifespan.out - lifespan.in, ppf));
+  // A NAME IS NEVER CUT SHORT. A video clip draws its own name over its picture.
+  const namePlace = video !== undefined || laneW === undefined ? "inside" : clipNamePlace(left, width, row.label, laneW);
+  /**
+   * THE ADAPTIVE GRAB ZONE IS A CLIP AFFORDANCE, and it stays scoped to one.
+   *
+   * `.lifespan-handle { width: 8px }` in styles.css is what every bar in this
+   * dock has always been grabbed by. Setting a width inline on every row
+   * silently retuned the hit target on kinds that have nothing to do with
+   * video AND left that rule dead for all of them, which is a stylesheet that
+   * describes a different machine than the code.
+   *
+   * ponytail: "two 8px handles ARE a six-frame bar" is true of every kind, so
+   * widening this is defensible. It is a deliberate change to every row's hit
+   * target and it has to retire the CSS literal in the same move; it is not
+   * this fix, and half of it is worse than neither half.
+   */
+  const clipHandle: CSSProperties | undefined =
+    video === undefined ? undefined : { width: trimHandlePx(width) };
+  const barStyle: CSSProperties =
+    video === undefined
+      ? { left, width }
+      : // The clip bar owns its own box: no padding, no border and no vertical
+        // inset, so the 32 + 1 + 22 budget in model.ts is exactly the row's
+        // content height. Selection still shows, because `.is-selected` is an
+        // OUTLINE rather than a border.
+        {
+          left,
+          width,
+          top: 0,
+          bottom: 0,
+          padding: 0,
+          border: 0,
+          borderRadius: 4,
+          flexDirection: "column",
+          alignItems: "stretch",
+        };
 
   return (
     <div
-      className={`lifespan-row${selected ? " is-selected" : ""}`}
+      className={`lifespan-row${selected ? " is-selected" : ""}${live ? " is-live" : ""}${video === undefined ? "" : " is-video"}${revealed ? " is-revealed" : ""}${
+        mask?.off === true ? " is-mask-off" : ""
+      }`}
       data-lifespan={row.layerId}
       data-row-scene={sceneId}
+      style={video === undefined ? undefined : { height: VIDEO_ROW_H }}
+      // The stage lights this row's layer while the cursor is here:
+      // identity-diffed in the store, one SVG repaint stage-side.
+      onPointerEnter={() => store.hoverLayer(row.layerId)}
+      onPointerLeave={() => store.hoverLayer(null)}
     >
-      <div className="lifespan-label-cell" style={{ width: labelWidth, paddingLeft: 4 + row.depth * 12 }}>
+      <div
+        className="lifespan-label-cell"
+        style={{ width: labelWidth, "--depth": row.depth, "--mask-inset": `${mask?.inset ?? 0}px` } as CSSProperties}
+      >
+        {mask === undefined ? null : <MaskBracket segments={mask.segments} base="var(--space-2)" />}
         <button
           type="button"
           className="lifespan-disclosure"
           aria-expanded={expanded}
-          aria-label={expanded ? `Hide ${row.label}'s blocks` : `Show ${row.label}'s blocks`}
+          aria-label={expanded ? `Hide ${row.label}'s keyframes` : `Show ${row.label}'s keyframes`}
           onClick={onToggle}
         >
-          {expanded ? "▾" : "▸"}
+          {expanded ? <IconChevronDown /> : <IconChevron />}
         </button>
+        {/* OUTSIDE the name button, the rule FilePanel's own kind glyph keeps:
+            the button's textContent is the layer's label and nothing else, which
+            is what a screen reader announces and what the tests compare. */}
+        {layer === undefined ? null : (
+          <span
+            className={`layer-kind${
+              mask?.icon === "mask" ? " is-mask" : mask?.icon == null && isComponentGlyph(layer) ? " is-component" : ""
+            }`}
+            aria-hidden="true"
+          >
+            {mask?.icon == null ? iconFor(layer) : MASK_ICON}
+          </span>
+        )}
         <button type="button" className="lifespan-name" onClick={pick}>
           {row.label}
         </button>
+        {/* The mask's mode, the outline's badge (Paper page 25). */}
+        {mask?.badge == null ? null : (
+          <span className="mask-badge" title={mask.badge}>
+            {mask.badge}
+          </span>
+        )}
+        {/* Who else holds this layer (Paper page 21), a dot each. */}
+        <PeerDots at={(p) => p.sel.includes(row.layerId)} />
+        {layer === undefined ? null : <RowSwitches layer={layer} video={video} sceneId={sceneId} />}
       </div>
       <div className="lifespan-lane">
+        {ghostFrom === null ? null : (
+          <StaggerGhost fromFrame={ghostFrom} width={width} shift={startLane - ghostFrom} ppf={ppf} />
+        )}
         <div
-          className={`lifespan-bar${selected ? " is-selected" : ""}`}
-          style={{ left, width }}
+          className={`lifespan-bar${live ? " is-live" : ""}${selected ? " is-selected" : ""}${
+            video === undefined ? "" : " is-video"
+          }${mask?.badge == null ? "" : " is-mask"}`}
+          style={barStyle}
           data-bar={row.layerId}
           onPointerDown={drag("body")}
-          title={`${row.label} · ${lifespan.in}–${lifespan.out} · drag to move it and its blocks, ⌥drag to slip the blocks alone, ⌘drag to ignore snapping`}
+          title={formatCombo(
+            video === undefined
+              ? `${row.label} · ${lifespan.in}–${lifespan.out} · drag to move it and its keys, ⌥drag to slip the keys alone or to stagger a selection, ⌘drag to ignore snapping`
+              : `${row.label} · ${lifespan.in}–${lifespan.out} · drag to move the clip, ⌥drag to slip the footage under it or to stagger a selection, ⇧⌥drag to move this clip alone, ⌘drag to ignore snapping`,
+          )}
         >
+          {video === undefined || layer?.kind !== "video" ? null : (
+            <ClipBody
+              layer={layer}
+              video={video}
+              fps={fps}
+              ppf={ppf}
+              leftPx={left}
+              widthPx={width}
+              labelWidth={labelWidth}
+              lifespanIn={lifespan.in}
+              label={row.label}
+            />
+          )}
           <span
             className="lifespan-handle lifespan-handle-in"
             data-handle="lifespan-in"
+            style={clipHandle}
             onPointerDown={drag("in")}
             aria-hidden="true"
           />
-          <span className="lifespan-bar-name">{row.label}</span>
+          {video === undefined && namePlace === "inside" ? <span className="lifespan-bar-name">{row.label}</span> : null}
+          {mask?.badge == null ? null : <span className="lifespan-bar-mask">mask · {mask.badge}</span>}
+          {/* THE OUT EDGE CARRIES TWO GESTURES WHEN THERE IS A SEAM, so they
+              are split by HEIGHT rather than stacked on one 3-to-10px strip:
+              the trim keeps the picture half, the roll takes the waveform half.
+              Each target is then at least 22px tall, and the seam is where an
+              author already looks for a rolling edit. With no abutting
+              neighbour the trim handle is full height, as on any other bar. */}
           <span
             className="lifespan-handle lifespan-handle-out"
             data-handle="lifespan-out"
+            style={video?.rollPartner == null ? clipHandle : { ...clipHandle, bottom: VIDEO_WAVE_H }}
             onPointerDown={drag("out")}
             aria-hidden="true"
           />
+          {video?.rollPartner == null ? null : (
+            <span
+              className="lifespan-handle lifespan-handle-roll"
+              data-handle="lifespan-roll"
+              style={{ ...clipHandle, right: 0, top: VIDEO_PICTURE_H + VIDEO_EDGE_H, cursor: "ew-resize" }}
+              onPointerDown={drag("roll")}
+              aria-hidden="true"
+            />
+          )}
         </div>
+        {namePlace === "inside" ? null : (
+          // Beside the clip, not in it: after it, or before it at the track's
+          // end. Not a drag target, so a press lands on the lane as on any gap.
+          <span
+            className={`lifespan-bar-name is-outside is-${namePlace}`}
+            style={
+              namePlace === "after"
+                ? { left: left + width + CLIP_NAME_GAP_PX }
+                : { left: left - CLIP_NAME_GAP_PX, transform: "translateX(-100%)" }
+            }
+          >
+            {row.label}
+          </span>
+        )}
+        {readout === null ? null : <StaggerChip step={readout.step} left={left + width} />}
       </div>
     </div>
   );
 }
+
+/**
+ * Which document write a press means, or null when it means nothing.
+ *
+ * Kept out of the handler so the mapping is one expression a reader can check
+ * against the header's table, and so the two modifier predicates are read
+ * exactly once, at the press.
+ *
+ * Null only for a roll with no partner, which the handle's own render condition
+ * already prevents: it is guarded here as well because the two conditions would
+ * otherwise have to stay in step by hand, and the cost of a stale one is a roll
+ * against an empty id.
+ */
+function gestureOf(
+  mode: "body" | "in" | "out" | "roll",
+  event: { altKey: boolean; shiftKey: boolean },
+  video: VideoRow | null,
+  carried: readonly string[],
+): LifespanDrag | null {
+  if (mode === "roll") return video?.rollPartner == null ? null : { roll: video.rollPartner };
+  if (mode !== "body") return mode;
+  // THE CLIP FORK IS FIRST AND IT IS THE ONLY ONE ⇧ REACHES. Off a clip the
+  // chord falls through to the slip below, which is what ⌥ with or without ⇧
+  // has always done on an ordinary row — and `writeLifespan` routes "shift" to
+  // `shiftLayer` above its own video fork, so leaking the word here would
+  // rewrite a rect's window from a gesture that used to move only its keys.
+  if (video !== null && isSolo(event)) return "shift";
+  // ⌥ ON A SELECTION FANS IT OUT; on one bar it is still the slip.
+  if (isSlip(event)) return carried.length > 1 ? { stagger: carried } : "slip";
+  // A group move needs the ids; one bar does not, and the word form is what
+  // every existing test already speaks.
+  return carried.length > 1 ? { move: carried } : "body";
+}
+
+/**
+ * The picture, the edge and the wave, stacked.
+ *
+ * The EDGE is a line and not a lighter fill on purpose: in the light theme
+ * `--panel-raised` is `--panel`, so a surface step up between the two strips
+ * would be invisible. A 1px rule is what reads in both appearances.
+ */
+function ClipBody({
+  layer,
+  video,
+  fps,
+  ppf,
+  leftPx,
+  widthPx,
+  labelWidth,
+  lifespanIn,
+  label,
+}: {
+  layer: VideoLayer3D;
+  video: VideoRow;
+  fps: Rational;
+  ppf: number;
+  /** The bar's left edge in LANE pixels, exactly as the row placed it. */
+  leftPx: number;
+  widthPx: number;
+  labelWidth: number;
+  /** The bar's own left edge, in scene frames, so the held stretches can be
+   *  placed relative to it. */
+  lifespanIn: number;
+  label: string;
+}) {
+  // ── THE AUDIBLE SPAN IS NOT THE BAR ────────────────────────────────────
+  //
+  // A recording's inline sound starts where the FOOTAGE starts, not where the
+  // window opens: `declaredVideoSoundClip` (timeline.ts) places it at
+  // `max(lifetime.in, video.offsetFrames)` and runs it to `lifetime.out`, and
+  // every mixer reads that one function. Handing the waveform the whole bar
+  // drew peaks across the lead hatch, which is the exact stretch that has no
+  // sound in it — the picture and the sound disagreeing about where the take
+  // begins, on the one row built to show that they agree.
+  //
+  // The same expression off the same two fields, rather than a second answer:
+  // `video.sound.durationFrames` IS that function's `out - from` over this same
+  // window, so the span ends on the bar's own out edge and needs no clamp here.
+  // A window that never opens is dropped one step earlier, as a null `sound`.
+  const soundFrom = Math.max(lifespanIn, Math.trunc(video.offsetFrames));
+  return (
+    <>
+      {/* THE STRIP'S CONTAINING BLOCK, and that is what this span is for.
+          `Filmstrip` places itself absolutely against its positioned ancestor
+          and fills it top to bottom; against the BAR that would be all 56px and
+          the waveform would be under footage. Against this it is the 32 the
+          picture owns. `overflow: hidden` is what cuts a column that straddles
+          either end, which is the clip the plan's own header relies on. */}
+      <span
+        className="lifespan-clip-picture"
+        style={{ height: VIDEO_PICTURE_H, position: "relative", overflow: "hidden", flex: "none" }}
+      >
+        <Filmstrip
+          layer={layer}
+          asset={video.pictureAsset}
+          fps={fps}
+          lifetimeIn={lifespanIn}
+          ppf={ppf}
+          barLeftPx={leftPx}
+          barWidthPx={widthPx}
+          labelWidth={labelWidth}
+        />
+        {/* POSITIONED, because the strip is: CSS paints a positioned descendant
+            over in-flow content whatever the document order, so a plain span
+            here would vanish under the footage. `Filmstrip`'s own mount note
+            says so, and this is the row keeping that side of the contract. */}
+        <span
+          className="lifespan-bar-name"
+          style={{
+            position: "relative",
+            // BLOCK, because `.lifespan-bar-name`'s `overflow: hidden` and
+            // `text-overflow: ellipsis` do nothing on an inline box. In an
+            // ordinary bar it is a flex ITEM and therefore already blockified;
+            // here it is a child of the picture strip and is not.
+            display: "block",
+            lineHeight: `${VIDEO_PICTURE_H}px`,
+            padding: "0 6px",
+          }}
+        >
+          {label}
+        </span>
+      </span>
+      <span
+        className="lifespan-clip-edge"
+        aria-hidden="true"
+        style={{ height: VIDEO_EDGE_H, background: "var(--bar-rest-line)", flex: "none" }}
+      />
+      <span className="lifespan-clip-sound" style={{ height: VIDEO_WAVE_H, position: "relative", flex: "none" }}>
+        {video.sound === null ? null : (
+          // POSITIONED, and that is the whole mechanism: `.audio-wave` is
+          // `position: absolute; inset: 0`, so the canvas fills its nearest
+          // positioned ancestor whatever pixel width it was drawn at. The box
+          // is the audible span; `widthPx` only says how many pixels of peaks
+          // to put in it.
+          <span
+            data-clip-wave=""
+            style={{
+              position: "absolute",
+              top: 0,
+              bottom: 0,
+              left: frameToPx(soundFrom - lifespanIn, ppf),
+              width: frameToPx(video.sound.durationFrames, ppf),
+            }}
+          >
+            <AudioWaveform
+              clip={video.sound}
+              asset={video.soundAsset}
+              fps={fps}
+              widthPx={frameToPx(video.sound.durationFrames, ppf)}
+              heightPx={VIDEO_WAVE_H}
+            />
+          </span>
+        )}
+      </span>
+      {/* OVER BOTH STRIPS, because the held picture is held in the waveform's
+          half of the bar too — there is simply no sound out there either. */}
+      <HeldMark span={video.lead} lifespanIn={lifespanIn} ppf={ppf} which="lead" />
+      <HeldMark span={video.hold} lifespanIn={lifespanIn} ppf={ppf} which="hold" />
+    </>
+  );
+}
+
+/** One frozen stretch, hatched, with a rule on the crossing itself so the exact
+ *  frame the picture stops on is readable and not merely implied. */
+function HeldMark({
+  span,
+  lifespanIn,
+  ppf,
+  which,
+}: {
+  span: HeldSpan | null;
+  lifespanIn: number;
+  ppf: number;
+  which: "lead" | "hold";
+}) {
+  if (span === null) return null;
+  const from = frameToPx(span.from - lifespanIn, ppf);
+  const to = frameToPx(span.to - lifespanIn, ppf);
+  // The rule sits on the crossing, which is the INNER end of the stretch: the
+  // lead freezes up to its `to` and the hold from its `from`.
+  const rule = which === "lead" ? "borderRight" : "borderLeft";
+  return (
+    <span
+      className={`lifespan-held is-${which}`}
+      data-held={which}
+      aria-hidden="true"
+      title={
+        which === "lead"
+          ? "The recording has not started yet: this stretch is its first frame, frozen"
+          : "The recording has run out: this stretch is its last frame, frozen"
+      }
+      style={{
+        position: "absolute",
+        top: 0,
+        bottom: 0,
+        left: from,
+        width: Math.max(1, to - from),
+        background: HELD_HATCH,
+        [rule]: "1px solid color-mix(in srgb, var(--timeline-ink) 45%, transparent)",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+/**
+ * The switches in a row's label cell: every row carries eye and lock, a clip
+ * with sound adds mute.
+ *
+ * EYE and LOCK are the layer's own flags and MUTE is the recording's inline
+ * sound. Mute is a different switch from the eye by design: `hidden` is the
+ * picture, `video.sound.muted` is the audio, which is the split every NLE draws
+ * and the split `videoSoundClip` already reads.
+ *
+ * ── ALL THREE NAME THEIR SUBJECT, AND THE EYE USED NOT TO ──────────────
+ *
+ * The outliner writes its two flags as `select` + `toggleFlag`, and that is
+ * sound THERE: its rows are the current container's by construction, so the
+ * container `toggleFlag` resolves for itself (`editingDef ?? state.sceneId`) is
+ * the one the row is in. This dock is one MASTER strip. `state.sceneId` follows
+ * the PLAYHEAD, so a row here is routinely in another scene, and the same pair
+ * copied over addressed a container the row is not in: `select` dropped an id
+ * that resolves in neither home and cleared the selection, `toggleFlag` then
+ * had nothing to write, and in a document whose ids were not minted against
+ * `usedIdsOf` it wrote to the playhead scene's layer of the same id instead.
+ *
+ * So each switch hands the verb this ROW's container and this row's layer, the
+ * way the bar's own drags hand `dragLifespan` its `sceneId`. Mute already did;
+ * it is now the shape all three share. Pressing one no longer moves the
+ * selection or the playhead either, which is what "a switch is not a
+ * navigation" means on a strip that shows the whole video at once.
+ *
+ * SOLO IS NOT HERE, and that is not an omission. Soloing is MONITORING: it
+ * changes what the author hears now and must never reach the document, so it
+ * belongs in the store's workspace-prefs family beside the other "where the
+ * author is standing" state. This file cannot add it — see the handoff note on
+ * store.ts — and a button that toggles nothing is worse than no button.
+ */
+function RowSwitches({
+  layer,
+  video,
+  sceneId,
+}: {
+  layer: Layer3D;
+  video: VideoRow | undefined;
+  sceneId: string;
+}) {
+  const store = useStore();
+  const hidden = layer.hidden === true;
+  const locked = layer.locked === true;
+  return (
+    <>
+      <button
+        type="button"
+        className="layer-flag"
+        data-switch="hidden"
+        aria-pressed={hidden}
+        aria-label={`${hidden ? "Show" : "Hide"} ${layer.label}`}
+        onPointerDown={(e) => e.stopPropagation()}
+        onClick={() => store.toggleFlag("hidden", { containerId: sceneId, layerIds: [layer.id] })}
+      >
+        {hidden ? <IconEyeOff /> : <IconEye />}
+      </button>
+      <button
+        type="button"
+        className="layer-flag"
+        data-switch="locked"
+        aria-pressed={locked}
+        aria-label={`${locked ? "Unlock" : "Lock"} ${layer.label}`}
+        onPointerDown={(e) => e.stopPropagation()}
+        onClick={() => store.toggleFlag("locked", { containerId: sceneId, layerIds: [layer.id] })}
+      >
+        {locked ? <IconLock /> : <IconUnlock />}
+      </button>
+      {/* Only when there IS a soundtrack. A recording that declares none has no
+          capability here to keep an affordance visible for. */}
+      {video === undefined || !video.hasSound || layer.kind !== "video" ? null : (
+        <button
+          type="button"
+          className="layer-flag"
+          data-switch="muted"
+          aria-pressed={video.muted}
+          aria-label={`${video.muted ? "Unmute" : "Mute"} ${layer.label}`}
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={() => {
+            if (layer.video.sound === undefined) return;
+            // THE RECORD IS RE-READ INSIDE THE EDIT, never the one this row
+            // closed over at render. `rowLayer` is the BASE layer (TimelineDock
+            // reads `layersById` directly), so the gain here is authored and not
+            // a sample of a keyframed curve. That hazard is `SoundRows`'s, and
+            // `baseSoundOf` in TimeSection.tsx answers it. The hazard HERE is
+            // staleness: a mute pressed after another panel committed a fade
+            // would spread this render's record back over it. Scene-addressed
+            // like `setVideoSound` itself, so a definition container answers
+            // undefined rather than handing back a record the op would refuse.
+            store.edit((doc) => {
+              const base = doc.scenesById[sceneId]?.layersById[layer.id];
+              if (base === undefined || base.kind !== "video" || base.video.sound === undefined) return doc;
+              return setVideoSound(doc, sceneId, layer.id, { ...base.video.sound, muted: !video.muted });
+            });
+          }}
+        >
+          {video.muted ? <IconVolumeOff /> : <IconVolume />}
+        </button>
+      )}
+    </>
+  );
+}