@hyperframes/studio 0.8.107 → 0.8.108

package/src/player/components/clipMenuToolItems.tsx

@@ -0,0 +1,235 @@
+import { useRef, useState, type KeyboardEvent } from "react";
+import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
+import { HF_COLOR_GRADING_ATTR } from "@hyperframes/core/color-grading";
+import type { TimelineElement } from "../store/playerStore";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { useCropPresetBarStore } from "../../components/editor/cropPresetStore";
+import {
+  CHARACTER_CHOICES,
+  LOOK_CHOICES,
+  VOICE_CHOICES,
+  activeLook,
+  activeVoicePreset,
+  chainWithVoicePreset,
+  lookAttrValue,
+  type ClipToolChoice,
+} from "./clipToolAttrs";
+import { useClipToolState } from "./useClipToolState";
+
+export type ClipMenuToolGroup = "time" | "sound" | "picture";
+
+interface ClipMenuToolItemsProps {
+  group: ClipMenuToolGroup;
+  element: TimelineElement;
+  currentTime: number;
+  onClose: () => void;
+}
+
+const ROW_CLASS =
+  "w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-none focus-visible:bg-neutral-800 text-neutral-300 hover:bg-neutral-800 cursor-pointer";
+const DISABLED_ROW_CLASS =
+  "w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-none text-neutral-600 cursor-not-allowed";
+const SUBMENU_WIDTH = 170;
+
+interface ChoiceSection {
+  heading?: string;
+  choices: readonly ClipToolChoice[];
+}
+
+function focusSibling(menu: HTMLElement | null, step: number): void {
+  if (!menu) return;
+  const items = Array.from(menu.querySelectorAll<HTMLButtonElement>('[role="menuitemradio"]'));
+  const index = items.findIndex((item) => item === document.activeElement);
+  items[(index + step + items.length) % items.length]?.focus();
+}
+
+function ChoiceSubmenu({
+  label,
+  sections,
+  activeId,
+  onPick,
+}: {
+  label: string;
+  sections: readonly ChoiceSection[];
+  activeId: string | null;
+  onPick: (id: string | null) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [flipLeft, setFlipLeft] = useState(false);
+  const rowRef = useRef<HTMLButtonElement | null>(null);
+  const submenuRef = useRef<HTMLDivElement | null>(null);
+
+  const show = (focusFirst: boolean) => {
+    const rect = rowRef.current?.getBoundingClientRect();
+    setFlipLeft(rect ? rect.right + SUBMENU_WIDTH > window.innerWidth : false);
+    setOpen(true);
+    if (focusFirst) requestAnimationFrame(() => focusSibling(submenuRef.current, 1));
+  };
+
+  const onSubmenuKeyDown = (event: KeyboardEvent) => {
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault();
+      event.stopPropagation();
+      focusSibling(submenuRef.current, event.key === "ArrowDown" ? 1 : -1);
+    } else if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      event.stopPropagation();
+      setOpen(false);
+      rowRef.current?.focus();
+    }
+  };
+
+  const choiceRow = (id: string | null, text: string) => (
+    <button
+      key={id ?? "none"}
+      type="button"
+      role="menuitemradio"
+      aria-checked={activeId === id}
+      className={ROW_CLASS}
+      onClick={() => onPick(id)}
+    >
+      <span className="flex items-center gap-1.5">
+        <span aria-hidden="true" className="w-3 text-center">
+          {activeId === id ? "✓" : ""}
+        </span>
+        {text}
+      </span>
+    </button>
+  );
+
+  return (
+    <div className="relative" onMouseEnter={() => show(false)} onMouseLeave={() => setOpen(false)}>
+      <button
+        ref={rowRef}
+        type="button"
+        role="menuitem"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        className={ROW_CLASS}
+        onClick={() => show(true)}
+        onKeyDown={(event) => {
+          if (event.key !== "ArrowRight") return;
+          event.preventDefault();
+          show(true);
+        }}
+      >
+        <span>{label}</span>
+        <span className="text-neutral-500 text-[10px] ml-3">▸</span>
+      </button>
+      {open && (
+        <div
+          ref={submenuRef}
+          role="menu"
+          aria-label={label}
+          className="absolute top-0 z-10 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1"
+          style={{ width: SUBMENU_WIDTH, ...(flipLeft ? { right: "100%" } : { left: "100%" }) }}
+          onKeyDown={onSubmenuKeyDown}
+        >
+          {choiceRow(null, "None")}
+          {sections.map((section, index) => (
+            <div key={section.heading ?? index}>
+              {section.heading && (
+                <>
+                  <div className="my-1 border-t border-neutral-700/60" />
+                  <div className="px-3 py-1 text-[9px] uppercase tracking-wide text-neutral-500">
+                    {section.heading}
+                  </div>
+                </>
+              )}
+              {section.choices.map((choice) => choiceRow(choice.id, choice.label))}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+const VOICE_SECTIONS: readonly ChoiceSection[] = [
+  { choices: VOICE_CHOICES },
+  { heading: "Character", choices: CHARACTER_CHOICES },
+];
+const LOOK_SECTIONS: readonly ChoiceSection[] = [{ choices: LOOK_CHOICES }];
+
+function isPictureClip(tag: string): boolean {
+  return tag === "video" || tag === "img";
+}
+
+function FreezeFrameItem({ element, currentTime, onClose }: Omit<ClipMenuToolItemsProps, "group">) {
+  const { onFreezeFrame } = useTimelineEditContextOptional();
+  if (!onFreezeFrame || element.tag.trim().toLowerCase() !== "video") return null;
+  const inside = currentTime > element.start && currentTime < element.start + element.duration;
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      className={inside ? ROW_CLASS : DISABLED_ROW_CLASS}
+      disabled={!inside}
+      onClick={() => {
+        void onFreezeFrame(element, currentTime);
+        onClose();
+      }}
+    >
+      <span>{inside ? "Freeze frame" : "Freeze frame (move playhead inside clip)"}</span>
+    </button>
+  );
+}
+
+/** Freeze (time), Voice (sound), Look and Crop (picture); sound and picture end in their own divider. */
+export function ClipMenuToolItems(props: ClipMenuToolItemsProps) {
+  if (props.group === "time") return <FreezeFrameItem {...props} />;
+  return <ClipMenuAttributeItems {...props} />;
+}
+
+function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsProps) {
+  const { onSetElementAttributeQuiet } = useTimelineEditContextOptional();
+  const state = useClipToolState(element);
+  const openCropBar = useCropPresetBarStore((s) => s.open);
+  if (!onSetElementAttributeQuiet) return null;
+
+  const write = (attr: string, value: string | null, label: string) => {
+    void onSetElementAttributeQuiet(element, attr, value, label);
+    onClose();
+  };
+
+  if (group === "sound") {
+    if (!state.hasSound) return null;
+    return (
+      <>
+        <ChoiceSubmenu
+          label="Voice"
+          sections={VOICE_SECTIONS}
+          activeId={activeVoicePreset(state.fxChain)}
+          onPick={(id) =>
+            write(HF_AUDIO_FX_ATTR, chainWithVoicePreset(state.fxChain, id), "Voice preset")
+          }
+        />
+        <div className="my-1 border-t border-neutral-700/60" />
+      </>
+    );
+  }
+
+  if (!isPictureClip(state.tag)) return null;
+  return (
+    <>
+      <ChoiceSubmenu
+        label="Look"
+        sections={LOOK_SECTIONS}
+        activeId={activeLook(state.colorGrading)}
+        onPick={(id) => write(HF_COLOR_GRADING_ATTR, lookAttrValue(id), "Look")}
+      />
+      <button
+        type="button"
+        role="menuitem"
+        className={ROW_CLASS}
+        onClick={() => {
+          openCropBar({ hfId: element.hfId, id: element.domId ?? element.id });
+          onClose();
+        }}
+      >
+        <span>Crop</span>
+      </button>
+      <div className="my-1 border-t border-neutral-700/60" />
+    </>
+  );
+}

package/src/player/components/clipPeakRuns.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { clipPeakRuns } from "./clipPeakRuns";
+
+const map = (bins: number[]) => ({ binSeconds: 1, bins });
+
+describe("clipPeakRuns", () => {
+  it("marks bins at or above -1 dBFS after the clip's gain and names the loudest", () => {
+    const { runs, peakDbfs } = clipPeakRuns(
+      map([0.1, 0.95, 0.99, 0.2, 0.9]),
+      { mediaStart: 0, sourceSpan: 5 },
+      1,
+    );
+    expect(runs).toEqual([
+      { from: 0.2, to: 0.6 },
+      { from: 0.8, to: 1 },
+    ]);
+    expect(peakDbfs).toBeCloseTo(20 * Math.log10(0.99), 6);
+  });
+
+  it("puts nothing on a -12 dBFS clip, and marks it once boosted by +12 dB", () => {
+    const quiet = map([0.25, 0.25]);
+    expect(clipPeakRuns(quiet, { mediaStart: 0, sourceSpan: 2 }, 1)).toEqual({
+      runs: [],
+      peakDbfs: null,
+    });
+    expect(clipPeakRuns(quiet, { mediaStart: 0, sourceSpan: 2 }, 4).runs).toHaveLength(1);
+  });
+
+  it("only reads the trimmed window, positioned within the clip", () => {
+    const { runs } = clipPeakRuns(map([1, 0, 0, 1, 0]), { mediaStart: 2, sourceSpan: 2 }, 1);
+    expect(runs).toEqual([{ from: 0.5, to: 1 }]);
+  });
+
+  it("is empty for a muted clip or an empty window", () => {
+    expect(clipPeakRuns(map([1]), { mediaStart: 0, sourceSpan: 1 }, 0).runs).toEqual([]);
+    expect(clipPeakRuns(map([1]), { mediaStart: 0, sourceSpan: 0 }, 1).runs).toEqual([]);
+  });
+});

package/src/player/components/clipPeakRuns.ts

@@ -0,0 +1,59 @@
+import { EXPORT_PEAK_CEILING } from "../../utils/exportPeakCeiling";
+
+export interface PeakMap {
+  binSeconds: number;
+  bins: number[];
+}
+
+export interface ClipSourceWindow {
+  mediaStart: number;
+  sourceSpan: number;
+}
+
+export interface ClipPeakMarkRuns {
+  runs: Array<{ from: number; to: number }>;
+  peakDbfs: number | null;
+}
+
+/**
+ * Where, as fractions of the clip, its source at the clip's own gain reaches the
+ * export ceiling, and the loudest point when it does. Adjacent hot bins merge.
+ */
+export function clipPeakRuns(
+  map: PeakMap,
+  window: ClipSourceWindow,
+  gain: number,
+): ClipPeakMarkRuns {
+  const runs: ClipPeakMarkRuns["runs"] = [];
+  if (!(window.sourceSpan > 0) || !(map.binSeconds > 0) || !(gain > 0))
+    return { runs, peakDbfs: null };
+  const first = Math.max(0, Math.floor(window.mediaStart / map.binSeconds));
+  const last = Math.min(
+    map.bins.length,
+    Math.ceil((window.mediaStart + window.sourceSpan) / map.binSeconds),
+  );
+  const toFraction = (bin: number) =>
+    Math.min(1, Math.max(0, (bin * map.binSeconds - window.mediaStart) / window.sourceSpan));
+  let loudest = 0;
+  for (let bin = first; bin < last; bin++) {
+    const level = (map.bins[bin] ?? 0) * gain;
+    if (level < EXPORT_PEAK_CEILING) continue;
+    loudest = Math.max(loudest, level);
+    const previous = runs.at(-1);
+    const from = toFraction(bin);
+    const to = toFraction(bin + 1);
+    if (previous && previous.to >= from) previous.to = to;
+    else runs.push({ from, to });
+  }
+  return { runs, peakDbfs: runs.length > 0 ? 20 * Math.log10(loudest) : null };
+}
+
+export function isPeakMap(value: unknown): value is PeakMap {
+  if (typeof value !== "object" || value === null) return false;
+  const bins: unknown = Reflect.get(value, "bins");
+  return (
+    typeof Reflect.get(value, "binSeconds") === "number" &&
+    Array.isArray(bins) &&
+    bins.every((bin) => typeof bin === "number")
+  );
+}

package/src/player/components/clipToolAttrs.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vitest";
+import { parseAudioFxChain, serializeAudioFxChain } from "@hyperframes/core/audio-fx";
+import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";
+import {
+  activeLook,
+  activeVoicePreset,
+  chainWithVoicePreset,
+  hasCrop,
+  isDucked,
+  lookAttrValue,
+  readClipBadges,
+  splitVisibleBadges,
+  type ClipToolState,
+} from "./clipToolAttrs";
+
+const presetsIn = (raw: string | null) =>
+  raw ? [...new Set(parseAudioFxChain(raw).nodes.map((n) => n.fromPreset ?? n.type))] : [];
+
+const handNode = serializeAudioFxChain({
+  version: 1,
+  nodes: [{ id: "n1", type: "highpass", enabled: true, params: { frequency: 80 } }],
+});
+
+describe("voice presets", () => {
+  it("writes the chosen preset's nodes and reads it back", () => {
+    const raw = chainWithVoicePreset(null, "voice-clean");
+    expect(presetsIn(raw)).toEqual(["voice-clean"]);
+    expect(activeVoicePreset(raw)).toBe("voice-clean");
+  });
+
+  it("is single-choice: picking another menu preset replaces the first", () => {
+    const raw = chainWithVoicePreset(chainWithVoicePreset(null, "voice-clean"), "telephone");
+    expect(presetsIn(raw)).toEqual(["telephone"]);
+  });
+
+  it("None drops the attribute when the chain held only the preset", () => {
+    expect(chainWithVoicePreset(chainWithVoicePreset(null, "voice-warm"), null)).toBeNull();
+  });
+
+  it("None keeps nodes that are not from a menu preset", () => {
+    const withPreset = chainWithVoicePreset(handNode, "voice-broadcast");
+    expect(presetsIn(withPreset)).toEqual(["highpass", "voice-broadcast"]);
+    expect(chainWithVoicePreset(withPreset, null)).toBe(handNode);
+  });
+
+  it("re-applying the same preset keeps one copy", () => {
+    const once = chainWithVoicePreset(null, "megaphone");
+    const twice = chainWithVoicePreset(once, "megaphone");
+    expect(parseAudioFxChain(twice ?? "").nodes).toHaveLength(
+      parseAudioFxChain(once ?? "").nodes.length,
+    );
+  });
+});
+
+describe("looks", () => {
+  it("writes the minimal preset form the runtime resolves", () => {
+    const raw = lookAttrValue("warm-daylight");
+    expect(raw).toBe('{"preset":"warm-daylight","intensity":1}');
+    expect(normalizeHfColorGrading(JSON.parse(raw ?? ""))?.preset).toBe("warm-daylight");
+    expect(activeLook(raw)).toBe("warm-daylight");
+  });
+
+  it("None removes the attribute", () => {
+    expect(lookAttrValue(null)).toBeNull();
+  });
+
+  it("reads a full inspector-written grading and ignores garbage", () => {
+    expect(activeLook('{"preset":"mono-clean","intensity":0.4,"adjust":{"contrast":0.2}}')).toBe(
+      "mono-clean",
+    );
+    expect(activeLook("{nope")).toBeNull();
+    expect(activeLook('{"preset":"mono-clean","enabled":false}')).toBeNull();
+  });
+});
+
+describe("small readers", () => {
+  it("treats an inset of zero or none as no crop", () => {
+    expect(hasCrop("inset(10px 0px 10px 0px)")).toBe(true);
+    expect(hasCrop("inset(0px)")).toBe(false);
+    expect(hasCrop("none")).toBe(false);
+    expect(hasCrop(null)).toBe(false);
+  });
+
+  it("reads a carve as ducked unless it is switched off", () => {
+    expect(isDucked('{"sources":["vo"]}')).toBe(true);
+    expect(isDucked('{"enabled":false,"sources":["vo"]}')).toBe(false);
+    expect(isDucked(null)).toBe(false);
+  });
+});
+
+const baseState: ClipToolState = {
+  tag: "video",
+  hasSound: true,
+  volume: null,
+  muted: false,
+  fxChain: null,
+  automation: null,
+  colorGrading: null,
+  clipPath: null,
+  carve: null,
+  link: null,
+};
+
+const rampAutomation = JSON.stringify({
+  version: 1,
+  lanes: [
+    {
+      target: "rate",
+      points: [
+        { t: 0, v: 0.5 },
+        { t: 2, v: 1 },
+      ],
+    },
+  ],
+});
+
+describe("readClipBadges", () => {
+  it("shows nothing for a plain clip at 100%", () => {
+    expect(readClipBadges(baseState)).toEqual([]);
+  });
+
+  it("lists every applied tool in the wireframe's order", () => {
+    const labels = readClipBadges({
+      ...baseState,
+      volume: 1.8,
+      fxChain: chainWithVoicePreset(null, "voice-clean"),
+      automation: rampAutomation,
+      colorGrading: lookAttrValue("warm-daylight"),
+      clipPath: "inset(0px 20px)",
+      carve: "{}",
+      link: "talk",
+    }).map((b) => b.label);
+    expect(labels).toEqual([
+      "Linked",
+      "Warm daylight",
+      "Voice: Clean",
+      "Ramp",
+      "Crop",
+      "Ducked",
+      "180%",
+    ]);
+  });
+
+  it("badges a muted audio clip but not muted b-roll", () => {
+    expect(readClipBadges({ ...baseState, tag: "audio", muted: true })[0]?.label).toBe("Muted");
+    expect(readClipBadges({ ...baseState, hasSound: false, muted: true })).toEqual([]);
+  });
+
+  it("caps at two visible badges plus the link badge", () => {
+    const badges = readClipBadges({
+      ...baseState,
+      link: "talk",
+      colorGrading: lookAttrValue("mono-clean"),
+      clipPath: "inset(5px)",
+      volume: 0.6,
+    });
+    const { visible, hidden } = splitVisibleBadges(badges);
+    expect(visible.map((b) => b.label)).toEqual(["Linked", "Mono", "Crop"]);
+    expect(hidden.map((b) => b.label)).toEqual(["60%"]);
+  });
+});

package/src/player/components/clipToolAttrs.ts

@@ -0,0 +1,187 @@
+/**
+ * The attribute each clip-menu tool writes, and what a clip's attributes say is applied.
+ * Pure over strings so the menu, the badges and an agent's hand edits all agree.
+ */
+
+import {
+  parseAudioFxChain,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import { activeAudioFxPresetIds } from "@hyperframes/core/audio-fx-presets";
+import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";
+import { parseRateLane } from "@hyperframes/core/speed-ramp";
+import { applyPresetToChain } from "../../components/editor/useApplyAudioFxPreset";
+
+export interface ClipToolChoice {
+  id: string;
+  label: string;
+}
+
+export const VOICE_CHOICES: readonly ClipToolChoice[] = [
+  { id: "voice-clean", label: "Clean" },
+  { id: "voice-broadcast", label: "Broadcast" },
+  { id: "voice-warm", label: "Warm" },
+];
+
+export const CHARACTER_CHOICES: readonly ClipToolChoice[] = [
+  { id: "telephone", label: "Telephone" },
+  { id: "radio-am", label: "AM Radio" },
+  { id: "megaphone", label: "Megaphone" },
+];
+
+export const LOOK_CHOICES: readonly ClipToolChoice[] = [
+  { id: "warm-daylight", label: "Warm daylight" },
+  { id: "clean-studio", label: "Clean studio" },
+  { id: "vintage-wash", label: "Vintage wash" },
+  { id: "mono-clean", label: "Mono" },
+  { id: "deep-contrast", label: "Deep contrast" },
+  { id: "home-movie-8mm", label: "Home movie" },
+];
+
+const VOICE_MENU_IDS = new Set([...VOICE_CHOICES, ...CHARACTER_CHOICES].map((c) => c.id));
+
+const EMPTY_CHAIN: HfAudioFxChain = { version: 1, nodes: [] };
+
+function parseChainOrEmpty(raw: string | null | undefined): HfAudioFxChain {
+  if (!raw) return EMPTY_CHAIN;
+  try {
+    return parseAudioFxChain(raw);
+  } catch {
+    return EMPTY_CHAIN;
+  }
+}
+
+function labelFor(choices: readonly ClipToolChoice[], id: string | null): string | null {
+  return choices.find((choice) => choice.id === id)?.label ?? null;
+}
+
+export function activeVoicePreset(rawChain: string | null | undefined): string | null {
+  const ids = activeAudioFxPresetIds(parseChainOrEmpty(rawChain));
+  return ids.find((id) => VOICE_MENU_IDS.has(id)) ?? null;
+}
+
+function voicePresetLabel(id: string | null): string | null {
+  return labelFor(VOICE_CHOICES, id) ?? labelFor(CHARACTER_CHOICES, id);
+}
+
+/**
+ * The `data-fx-chain` after choosing a voice preset, or `null` to drop the attribute.
+ * Single choice: the other menu presets' nodes go; carve, leveller and hand-added nodes stay.
+ */
+export function chainWithVoicePreset(
+  rawChain: string | null | undefined,
+  presetId: string | null,
+): string | null {
+  const chain = parseChainOrEmpty(rawChain);
+  const others = chain.nodes.filter(
+    (node) =>
+      !node.fromPreset || !VOICE_MENU_IDS.has(node.fromPreset) || node.fromPreset === presetId,
+  );
+  const kept: HfAudioFxChain = { ...chain, nodes: others };
+  const next = presetId ? (applyPresetToChain(kept, presetId, undefined) ?? kept) : kept;
+  return next.nodes.length > 0 ? serializeAudioFxChain(next) : null;
+}
+
+function parseJson(raw: string | null | undefined): unknown {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function activeLook(rawGrading: string | null | undefined): string | null {
+  return normalizeHfColorGrading(parseJson(rawGrading))?.preset ?? null;
+}
+
+function lookLabel(id: string | null): string | null {
+  return labelFor(LOOK_CHOICES, id);
+}
+
+export function lookAttrValue(presetId: string | null): string | null {
+  return presetId ? JSON.stringify({ preset: presetId, intensity: 1 }) : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function isDucked(rawCarve: string | null | undefined): boolean {
+  const carve = parseJson(rawCarve);
+  return isRecord(carve) && carve["enabled"] !== false;
+}
+
+function hasRateRamp(rawAutomation: string | null | undefined): boolean {
+  return parseRateLane(rawAutomation) !== null;
+}
+
+const ZERO_INSET = /^inset\(\s*0(px|%)?\s*\)$/i;
+
+export function hasCrop(clipPath: string | null | undefined): boolean {
+  const value = clipPath?.trim() ?? "";
+  return value !== "" && value !== "none" && !ZERO_INSET.test(value);
+}
+
+export type ClipBadgeKind = "link" | "look" | "voice" | "ramp" | "crop" | "ducked" | "volume";
+
+export interface ClipBadge {
+  kind: ClipBadgeKind;
+  label: string;
+}
+
+/** What a clip's attributes say is applied; the element's own attributes, as read off its node. */
+export interface ClipToolState {
+  tag: string;
+  hasSound: boolean;
+  volume: number | null;
+  muted: boolean;
+  fxChain: string | null;
+  automation: string | null;
+  colorGrading: string | null;
+  clipPath: string | null;
+  carve: string | null;
+  link: string | null;
+}
+
+function volumeBadge(state: ClipToolState): ClipBadge | null {
+  const isAudio = state.tag === "audio";
+  if (!isAudio && !state.hasSound) return null;
+  if (state.muted) return { kind: "volume", label: "Muted" };
+  const volume = state.volume ?? 1;
+  if (Math.abs(volume - 1) < 0.005) return null;
+  return { kind: "volume", label: `${Math.round(volume * 100)}%` };
+}
+
+/** Badges in the wireframe's order: look, voice, ramp, crop, ducked, volume. The link badge leads. */
+export function readClipBadges(state: ClipToolState): ClipBadge[] {
+  const look = lookLabel(activeLook(state.colorGrading));
+  const voice = voicePresetLabel(activeVoicePreset(state.fxChain));
+  const volume = volumeBadge(state);
+  const badges: Array<ClipBadge | null> = [
+    state.link ? { kind: "link", label: "Linked" } : null,
+    look ? { kind: "look", label: look } : null,
+    voice ? { kind: "voice", label: `Voice: ${voice}` } : null,
+    hasRateRamp(state.automation) ? { kind: "ramp", label: "Ramp" } : null,
+    hasCrop(state.clipPath) ? { kind: "crop", label: "Crop" } : null,
+    isDucked(state.carve) ? { kind: "ducked", label: "Ducked" } : null,
+    volume,
+  ];
+  return badges.filter((badge): badge is ClipBadge => badge !== null);
+}
+
+const MAX_VISIBLE_BADGES = 2;
+
+/** The link badge is always shown; the rest cap at two, then `+N`. */
+export function splitVisibleBadges(badges: readonly ClipBadge[]): {
+  visible: ClipBadge[];
+  hidden: ClipBadge[];
+} {
+  const link = badges.filter((badge) => badge.kind === "link");
+  const rest = badges.filter((badge) => badge.kind !== "link");
+  return {
+    visible: [...link, ...rest.slice(0, MAX_VISIBLE_BADGES)],
+    hidden: rest.slice(MAX_VISIBLE_BADGES),
+  };
+}

package/src/player/components/timelineCallbacks.ts

@@ -118,6 +118,7 @@ export interface TimelineEditCallbacks {
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
+  onFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;
   onDeleteKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
   onDeleteAllKeyframes?: (element: TimelineElement, animationId?: string) => void;
   onMoveKeyframeToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;