@crievo/omni 0.0.0-stage → 0.1.1

package/studio/web/pages/VideoPage/components/SoundTimeline/useEditorShortcuts.ts

@@ -0,0 +1,168 @@
+/* The timeline's keyboard: with a clip chosen, ← and → nudge it and Delete deletes it; Esc drops
+   the armed sound; Delete removes the chosen effects (or the bed); V, C and B switch the tool, and
+   with the area cut Delete, Backspace or Enter cut and Esc unmarks; Ctrl/Cmd + Z undoes and
+   Shift (or Ctrl + Y) redoes. Each listener keeps the dependencies it always had. */
+
+import { useEffect } from "react";
+import type { Clip, ClipKind, ClipSelection, Cut, Draft, EditorTool, Selection, SoundData } from "./types";
+import { layersInDeleteOrder } from "../../../../lib/sound-timeline";
+
+export function useEditorShortcuts({
+  data,
+  draft,
+  cuts,
+  clipSel,
+  clipsOf,
+  moveClip,
+  deleteClip,
+  setArmed,
+  sel,
+  setSel,
+  multi,
+  setMulti,
+  changeDraft,
+  tool,
+  chooseTool,
+  area,
+  setArea,
+  cutArea,
+  step,
+}: {
+  data: SoundData | null;
+  draft: Draft | null;
+  cuts: Cut[];
+  clipSel: ClipSelection | null;
+  clipsOf: (kind: ClipKind, id: string) => Clip[];
+  moveClip: (kind: ClipKind, id: string, k: number, offset: number) => void;
+  deleteClip: (kind: ClipKind, id: string, k: number) => void;
+  setArmed: (n: string | null) => void;
+  sel: Selection;
+  setSel: (s: Selection) => void;
+  multi: string[];
+  setMulti: (m: string[]) => void;
+  changeDraft: (f: (r: Draft) => void) => void;
+  tool: EditorTool;
+  chooseTool: (f: EditorTool) => void;
+  area: [number, number] | null;
+  setArea: (a: [number, number] | null) => void;
+  cutArea: () => void;
+  step: (from: "undo" | "redo") => void;
+}) {
+  /* with a clip chosen: ← and → nudge one frame (Shift: ten); Delete or Backspace delete */
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      if (!clipSel || (e.target as HTMLElement).closest("input, select, textarea, [contenteditable]")) return;
+      if (e.key === "Delete" || e.key === "Backspace") {
+        e.preventDefault();
+        deleteClip(clipSel.kind, clipSel.id, clipSel.k);
+        return;
+      }
+      if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+      e.preventDefault();
+      const nudge = (e.shiftKey ? 10 : 1) / (data?.format.fps ?? 30);
+      const c = clipsOf(clipSel.kind, clipSel.id)[clipSel.k];
+      if (c) moveClip(clipSel.kind, clipSel.id, clipSel.k, c.offset + (e.key === "ArrowLeft" ? -nudge : nudge));
+    };
+    addEventListener("keydown", key);
+    return () => removeEventListener("keydown", key);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [clipSel, draft, data]);
+
+  useEffect(() => {
+    const esc = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setArmed(null);
+    };
+    addEventListener("keydown", esc);
+    return () => removeEventListener("keydown", esc);
+  }, []);
+
+  /* Delete or Backspace with an effect chosen removes it from the timeline (with the background music chosen, removes it) */
+  useEffect(() => {
+    const del = (e: KeyboardEvent) => {
+      if (e.key !== "Delete" && e.key !== "Backspace") return;
+      const target = e.target as HTMLElement;
+      if (target.closest("input, select, textarea, [contenteditable]")) return;
+      if (tool === "cut" || !sel || !draft) return;
+      e.preventDefault();
+      if (sel === "bed") {
+        changeDraft(r => {
+          r.bed = null;
+        });
+        setSel(null);
+        return;
+      }
+      if (multi.length > 1) {
+        const pairs = layersInDeleteOrder(multi);
+        changeDraft(r => {
+          for (const [l, c] of pairs) r.places[l]?.sounds.splice(c, 1);
+        });
+        setMulti([]);
+        setSel(null);
+        return;
+      }
+      const sounds = draft.places[sel.place]?.sounds;
+      if (!sounds?.[sel.layer]) return;
+      changeDraft(r => {
+        r.places[sel.place].sounds.splice(sel.layer, 1);
+      });
+      setSel(sounds.length > 1 ? { place: sel.place, layer: Math.max(0, sel.layer - 1) } : null);
+    };
+    addEventListener("keydown", del);
+    return () => removeEventListener("keydown", del);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sel, draft, multi, tool]);
+
+  /* V and C switch the tool; with the cut, Delete, Backspace or Enter cut and Esc unmarks */
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      if (
+        (e.target as HTMLElement).closest("input, select, textarea, [contenteditable]") ||
+        e.metaKey ||
+        e.ctrlKey ||
+        e.altKey
+      )
+        return;
+      if (e.key === "v" || e.key === "V") {
+        chooseTool("select");
+        return;
+      }
+      if (e.key === "c" || e.key === "C") {
+        chooseTool("cut");
+        return;
+      }
+      if (e.key === "b" || e.key === "B") {
+        chooseTool("razor");
+        return;
+      }
+      if (tool !== "cut") return;
+      if (e.key === "Escape") {
+        setArea(null);
+        return;
+      }
+      if ((e.key === "Delete" || e.key === "Backspace" || e.key === "Enter") && area) {
+        e.preventDefault();
+        cutArea();
+      }
+    };
+    addEventListener("keydown", key);
+    return () => removeEventListener("keydown", key);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tool, area, cuts, data]);
+
+  /* Ctrl/Cmd + Z goes back one timeline step; with Shift, or Ctrl + Y, redoes */
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      if (!(e.metaKey || e.ctrlKey) || e.altKey) return;
+      /* inside a field, undo is the field's own */
+      if ((e.target as HTMLElement).closest("input, select, textarea, [contenteditable]")) return;
+      const z = e.code === "KeyZ",
+        y = e.code === "KeyY";
+      if (!z && !y) return;
+      e.preventDefault();
+      step(z && !e.shiftKey ? "undo" : "redo");
+    };
+    addEventListener("keydown", key);
+    return () => removeEventListener("keydown", key);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/useFitHeight.ts

@@ -0,0 +1,40 @@
+/* Preview and timeline fit the window: the height goes from the section top to the bottom of the
+   screen, and stops growing when the section touches the bottom of the stage rail (where it
+   sticks); only the right column scrolls. Measured again when the data arrives. */
+
+import { type RefObject, useEffect } from "react";
+
+export function useFitHeight(
+  root: RefObject<HTMLDivElement | null>,
+  data: unknown,
+  setHeight: (h: number | null) => void,
+) {
+  useEffect(() => {
+    let raf = 0;
+    const measure = () => {
+      cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(() => {
+        const el = root.current;
+        if (!el) return;
+        if (matchMedia("(max-width: 1050px)").matches) {
+          setHeight(null);
+          return;
+        }
+        const top = parseFloat(getComputedStyle(document.documentElement).getPropertyValue("--top-offset")) || 64;
+        const rail = document.querySelector<HTMLElement>(".rail")?.offsetHeight ?? 76;
+        document.documentElement.style.setProperty("--rail-height", `${rail}px`);
+        const fixed = top + rail + 8 + 11;
+        setHeight(Math.max(420, Math.round(innerHeight - Math.max(el.getBoundingClientRect().top, fixed) - 21)));
+      });
+    };
+    measure();
+    addEventListener("resize", measure);
+    /* capture: scroll doesn't bubble, and what scrolls is the .content panel, not the window */
+    addEventListener("scroll", measure, { passive: true, capture: true });
+    return () => {
+      cancelAnimationFrame(raf);
+      removeEventListener("resize", measure);
+      removeEventListener("scroll", measure, { capture: true });
+    };
+  }, [data]);
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/useFollowPlayhead.ts

@@ -0,0 +1,21 @@
+/* While playing, the timeline follows the playhead: when it gets near the right edge (or leaves on
+   the left), the view jumps a page and the playhead goes back near the start, like in Premiere. */
+
+import { type RefObject, useEffect, useRef } from "react";
+
+export function useFollowPlayhead(tracks: RefObject<HTMLDivElement | null>, t: number, playing: boolean, zoom: number) {
+  const scroller = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const el = scroller.current,
+      tr = tracks.current;
+    if (!playing || !el || !tr) return;
+    /* where the playhead is in the scrollable content, and the visible band without the icon column (pinned left) */
+    const head = tr.getBoundingClientRect().left - el.getBoundingClientRect().left + el.scrollLeft + t * zoom;
+    const sidebarWidth = el.querySelector<HTMLElement>(".sound-sidebar")?.offsetWidth ?? 0;
+    const left = el.scrollLeft + sidebarWidth,
+      right = el.scrollLeft + el.clientWidth;
+    if (head > right - 40 || head < left)
+      el.scrollLeft = Math.max(0, head - sidebarWidth - (el.clientWidth - sidebarWidth) * 0.1);
+  }, [t, playing, zoom]);
+  return scroller;
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/useListenMix.ts

@@ -0,0 +1,43 @@
+/* What you hear here, without changing the export: the narration volume (its own gain, which
+   changes while playing, without restarting) and the per-row mute (icon in the sidebar). The gain
+   nodes are created by playback; this keeps them in step with the controls. */
+
+import { useEffect, useRef, useState } from "react";
+import { audioCtx } from "../../../../lib/sound-audio";
+import { gainOf } from "../../../../lib/sound-timeline";
+import type { AudioRow } from "./types";
+
+export function useListenMix() {
+  /* narration mute: only for listening here (the export keeps the voice); the voice
+     goes through its own gain, which changes while playing, without restarting */
+  const [voiceVolume, setVoiceVolume] = useState(100);
+  const voiceVolumeRef = useRef(100);
+  const volumeBefore = useRef(100); /* the volume before muting, for the button to restore */
+  voiceVolumeRef.current = voiceVolume;
+  const voiceGain = useRef<GainNode | null>(null);
+  /* per-row mute (icon in the sidebar): silences all the row's audio, only for listening here */
+  const [muted, setMuted] = useState<Record<AudioRow, boolean>>({ voice: false, effects: false, bed: false });
+  const mutedRef = useRef(muted);
+  mutedRef.current = muted;
+  const effectsGain = useRef<GainNode | null>(null);
+  const bedGain = useRef<GainNode | null>(null);
+  useEffect(() => {
+    const now = audioCtx().currentTime;
+    voiceGain.current?.gain.setTargetAtTime(muted.voice ? 0 : gainOf(voiceVolume), now, 0.015);
+    effectsGain.current?.gain.setTargetAtTime(muted.effects ? 0 : 1, now, 0.015);
+    bedGain.current?.gain.setTargetAtTime(muted.bed ? 0 : 1, now, 0.015);
+  }, [voiceVolume, muted]);
+  return {
+    voiceVolume,
+    setVoiceVolume,
+    voiceVolumeRef,
+    volumeBefore,
+    voiceGain,
+    muted,
+    setMuted,
+    mutedRef,
+    effectsGain,
+    bedGain,
+  };
+}
+export type ListenMix = ReturnType<typeof useListenMix>;

package/studio/web/pages/VideoPage/components/SoundTimeline/usePlayback.ts

@@ -0,0 +1,231 @@
+/* Playback: the voice clips and the plan's effects play in Web Audio, each only inside the kept
+   spans (original time) joined in edited time; the bed plays straight through, whole (it is isolated
+   from the cuts; its plan is already on the edited timeline); the picture (export or scene MP4s) follows the
+   audio clock. The plan changed while playing: restarts from the same point. Space plays and pauses.
+   With the render at the chosen speed matching the edit (`sped`), that MP4 plays instead, picture and
+   sound together (the voice keeps its pitch, as atempo made it), and it is the clock: the timeline,
+   in edited time at 100%, runs `speed` times faster. */
+
+import { type RefObject, useCallback, useEffect, useRef } from "react";
+import type { ActionResult } from "../../../../lib/api";
+import { audioCtx, loadBuffer } from "../../../../lib/sound-audio";
+import { clipSpeed } from "../../../../../../tools/soundtrack.mjs";
+import { gainOf, keptSpans, mediaSrc, playbackWindows } from "../../../../lib/sound-timeline";
+import type { ListenMix } from "./useListenMix";
+import type { AudioRow, Clip, Cut, Plan, SoundData } from "./types";
+
+type SeekPicture = (tEd: number, running: boolean, force: boolean) => void;
+
+export function usePlayback({
+  slug,
+  data,
+  plan,
+  cuts,
+  draftLineClips,
+  editedTotal,
+  t,
+  setT,
+  playing,
+  setPlaying,
+  setResponse,
+  videoRef,
+  sceneVideos,
+  seekPictureRef,
+  seekPicture,
+  mix,
+  sped,
+}: {
+  slug: string;
+  data: SoundData | null;
+  plan: Plan | null;
+  cuts: Cut[];
+  draftLineClips: Record<string, Clip[]>;
+  editedTotal: number;
+  t: number;
+  setT: (t: number) => void;
+  playing: boolean;
+  setPlaying: (p: boolean) => void;
+  setResponse: (r: ActionResult) => void;
+  videoRef: RefObject<HTMLVideoElement | null>;
+  sceneVideos: RefObject<Record<string, HTMLVideoElement | null>>;
+  seekPictureRef: RefObject<SeekPicture>;
+  seekPicture: SeekPicture;
+  mix: ListenMix;
+  sped: { speed: number } | null;
+}) {
+  const { voiceGain, effectsGain, bedGain, mutedRef, voiceVolumeRef } = mix;
+  const sources = useRef<AudioBufferSourceNode[]>([]);
+  const clock = useRef<{ ctx0: number; t0: number } | null>(null);
+  /* the sped render is playing: its element is the clock */
+  const spedPlaying = useRef(false);
+
+  const stop = useCallback(() => {
+    sources.current.forEach(s => {
+      try {
+        s.stop();
+      } catch {
+        /* already stopped */
+      }
+    });
+    sources.current = [];
+    clock.current = null;
+    spedPlaying.current = false;
+    videoRef.current?.pause();
+    Object.values(sceneVideos.current).forEach(el => el?.pause());
+    setPlaying(false);
+  }, []);
+
+  const play = useCallback(
+    async (from: number) => {
+      if (!data || !plan) return;
+      stop();
+      if (sped && videoRef.current) {
+        const vid = videoRef.current;
+        seekPictureRef.current(from, false, true);
+        try {
+          await vid.play();
+        } catch {
+          setResponse({ ok: false, error: "O navegador não liberou o som do vídeo: clique em tocar de novo" });
+          return;
+        }
+        spedPlaying.current = true;
+        setPlaying(true);
+        return;
+      }
+      const c = audioCtx();
+      /* the browser only releases audio after a user gesture: without it resume()
+       stays pending forever; wait a little and warn instead of hanging */
+      await Promise.race([c.resume(), new Promise(r => setTimeout(r, 500))]);
+      if (c.state !== "running") {
+        setResponse({ ok: false, error: "O navegador não liberou o áudio desta página: clique em tocar de novo" });
+        return;
+      }
+      /* the voice plays per clip: the [from, to] span of the WAV, at the piece's place */
+      const audioTracks: { url: string; start: number; off?: number; dur?: number; speed?: number; row: AudioRow }[] = [
+        ...data.lines
+          .filter(f => f.wav)
+          .flatMap(f =>
+            (draftLineClips[f.id] ?? f.clips).map(cl => ({
+              url: mediaSrc(slug, f.wav!),
+              start: f.start + cl.from + cl.offset,
+              off: cl.from,
+              dur: cl.to - cl.from,
+              speed: clipSpeed(cl),
+              row: "voice" as const,
+            })),
+          ),
+        ...plan.items.map(it => ({ url: it.url, start: it.start, row: "effects" as const })),
+        ...(plan.bed ? [{ url: plan.bed.url, start: plan.bed.start, row: "bed" as const }] : []),
+      ];
+      const ready = await Promise.all(
+        audioTracks.map(async f => ({ ...f, b: await loadBuffer(f.url).catch(() => null) })),
+      );
+      const now = c.currentTime + 0.08;
+      voiceGain.current?.disconnect();
+      effectsGain.current?.disconnect();
+      bedGain.current?.disconnect();
+      const bus = (gain: number) => {
+        const g = c.createGain();
+        g.gain.value = gain;
+        g.connect(c.destination);
+        return g;
+      };
+      const gains: Record<AudioRow, GainNode> = {
+        voice: bus(mutedRef.current.voice ? 0 : gainOf(voiceVolumeRef.current)),
+        effects: bus(mutedRef.current.effects ? 0 : 1),
+        bed: bus(mutedRef.current.bed ? 0 : 1),
+      };
+      voiceGain.current = gains.voice;
+      effectsGain.current = gains.effects;
+      bedGain.current = gains.bed;
+      /* each file plays only in the kept spans (original time), joined in edited time */
+      const spans = keptSpans(cuts, data.total);
+      for (const f of ready) {
+        if (!f.b) continue;
+        /* the bed is isolated: its plan is already on the edited timeline, so it plays straight
+           through the cuts instead of being carved by them */
+        if (f.row === "bed") {
+          const off = Math.max(0, from - f.start);
+          if (f.b.duration - off <= 0) continue;
+          const s = c.createBufferSource();
+          s.buffer = f.b;
+          s.connect(gains.bed);
+          s.start(now + Math.max(0, f.start - from), off, f.b.duration - off);
+          sources.current.push(s);
+          continue;
+        }
+        for (const w of playbackWindows(f, f.b.duration, spans, from)) {
+          const s = c.createBufferSource();
+          s.buffer = f.b;
+          /* a sped voice piece: faster here, with a higher pitch (the export keeps the pitch) */
+          if (f.speed && f.speed !== 1) s.playbackRate.value = f.speed;
+          s.connect(gains[f.row]);
+          s.start(now + w.delay, w.offset, w.dur);
+          sources.current.push(s);
+        }
+      }
+      clock.current = { ctx0: now, t0: from };
+      seekPictureRef.current(from, true, true);
+      setPlaying(true);
+    },
+    [data, plan, stop, slug, cuts, draftLineClips, sped],
+  );
+
+  useEffect(() => {
+    if (!playing) return;
+    let raf = 0;
+    const tick = () => {
+      const r = clock.current;
+      const vid = videoRef.current;
+      if (spedPlaying.current && vid && sped) {
+        const now = vid.currentTime * sped.speed;
+        if (vid.ended || now >= editedTotal - 0.02) {
+          stop();
+          setT(editedTotal);
+          return;
+        }
+        setT(now);
+      } else if (r && data) {
+        const now = r.t0 + Math.max(0, audioCtx().currentTime - r.ctx0);
+        if (now >= editedTotal) {
+          stop();
+          setT(editedTotal);
+          return;
+        }
+        setT(now);
+        seekPictureRef.current(now, true, false);
+      }
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [playing, data, stop, editedTotal, sped]);
+
+  /* the plan changed while playing: restart from the current point to hear the change */
+  const planWhilePlaying = useRef<Plan | null>(null);
+  useEffect(() => {
+    if (playing && plan && planWhilePlaying.current && planWhilePlaying.current !== plan) play(t);
+    planWhilePlaying.current = plan;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [plan]);
+
+  useEffect(() => () => stop(), [stop]);
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      if (e.code !== "Space" || (e.target as HTMLElement).closest("input, select, textarea, button")) return;
+      e.preventDefault();
+      playing ? stop() : play(t >= editedTotal - 0.05 ? 0 : t);
+    };
+    addEventListener("keydown", key);
+    return () => removeEventListener("keydown", key);
+  }, [playing, play, stop, t, editedTotal]);
+
+  const seek = (to: number) => {
+    const x = Math.max(0, Math.min(editedTotal, to));
+    setT(x);
+    if (playing) play(x);
+    else seekPicture(x, false, true);
+  };
+
+  return { stop, play, seek };
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/usePlayerWidth.ts

@@ -0,0 +1,27 @@
+/* The player width in the vertical video, chosen by dragging its edge (null: automatic),
+   remembered in this browser. */
+
+import { useEffect, useRef, useState } from "react";
+import { PLAYER_WIDTH_KEY } from "../../../../lib/sound-timeline";
+
+export function usePlayerWidth() {
+  /* player width in the vertical video, chosen by dragging its edge (null: automatic), remembered in this browser */
+  const [manualWidth, setManualWidth] = useState<number | null>(() => {
+    try {
+      const n = Number(localStorage.getItem(PLAYER_WIDTH_KEY));
+      return n > 0 ? n : null;
+    } catch {
+      return null;
+    }
+  });
+  useEffect(() => {
+    try {
+      if (manualWidth) localStorage.setItem(PLAYER_WIDTH_KEY, String(manualWidth));
+      else localStorage.removeItem(PLAYER_WIDTH_KEY);
+    } catch {
+      /* no storage: valid for this visit */
+    }
+  }, [manualWidth]);
+  const widthDrag = useRef<{ x0: number; w0: number } | null>(null);
+  return { manualWidth, setManualWidth, widthDrag };
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/useSoundData.ts

@@ -0,0 +1,124 @@
+/* The timeline's data: every fetch resets the draft, undo and the dirty flag, like a reload; the
+   agent finishing an edit turn reloads it; a sound added to the library reloads only the catalog;
+   and every draft change is replanned (tools/sound.mjs, on the server), with some slack for
+   control drags. */
+
+import { type Dispatch, type RefObject, type SetStateAction, useCallback, useEffect, useRef } from "react";
+import { errorText } from "../../../../lib/api";
+import { clone } from "../../../../lib/sound-timeline";
+import { soundRoutes, useSoundQuery } from "../../../../hooks/useSound";
+import type { Draft, Plan, SoundData } from "./types";
+
+type History = { undo: Draft[]; redo: Draft[]; last: number };
+
+export function useSoundData({
+  slug,
+  agentEditing,
+  history,
+  setData,
+  setDataError,
+  setDraft,
+  setStacks,
+  setDirty,
+  setPending,
+  setArmed,
+}: {
+  slug: string;
+  agentEditing: boolean;
+  history: RefObject<History>;
+  setData: Dispatch<SetStateAction<SoundData | null>>;
+  setDataError: (e: string | null) => void;
+  setDraft: (d: Draft) => void;
+  setStacks: (s: { undo: number; redo: number }) => void;
+  setDirty: (d: boolean) => void;
+  setPending: (p: boolean) => void;
+  setArmed: (n: string | null) => void;
+}) {
+  /* the data: every fetch resets the draft, like a reload */
+  const query = useSoundQuery(slug);
+  const { refetch } = query;
+  const loadData = useCallback(() => {
+    void refetch();
+  }, [refetch]);
+  useEffect(() => {
+    const d = query.data;
+    if (!d) return;
+    if (d.error) {
+      setDataError(d.error);
+      return;
+    }
+    setData(d);
+    setDraft({
+      places: clone(d.places),
+      bed: clone(d.bed),
+      cuts: clone(d.cuts ?? []),
+      speed: d.speed ?? 1,
+      scene_clips: Object.fromEntries(d.scenes.map(c => [c.id, clone(c.clips)])),
+      line_clips: Object.fromEntries(d.lines.map(f => [f.id, clone(f.clips)])),
+    });
+    history.current = { undo: [], redo: [], last: 0 };
+    setStacks({ undo: 0, redo: 0 });
+    setDirty(false);
+    setPending(d.export_outdated);
+  }, [query.data]);
+  useEffect(() => {
+    if (query.error) setDataError(errorText(query.error));
+  }, [query.error]);
+  /* the agent finished an edit turn: the timeline comes back with what it saved */
+  const editingBefore = useRef(agentEditing);
+  useEffect(() => {
+    if (editingBefore.current && !agentEditing) loadData();
+    editingBefore.current = agentEditing;
+  }, [agentEditing, loadData]);
+
+  /* new sound in the library: only the catalog is reloaded, so unsaved timeline edits are kept */
+  const reloadCatalog = useCallback(
+    (added: string | null) => {
+      soundRoutes(slug)
+        .get()
+        .then(d => {
+          if (!d.error) {
+            setData(old => (old ? { ...old, catalog: d.catalog } : d));
+            if (added) setArmed(added);
+          }
+        })
+        .catch(() => {});
+    },
+    [slug],
+  );
+  return { loadData, reloadCatalog };
+}
+
+/* replans on every draft change, with some slack for control drags; only the latest request lands */
+export function useReplan({
+  slug,
+  draft,
+  setPlanning,
+  setPlanError,
+  setPlan,
+}: {
+  slug: string;
+  draft: Draft | null;
+  setPlanning: (p: boolean) => void;
+  setPlanError: (e: string | null) => void;
+  setPlan: (p: Plan) => void;
+}) {
+  const planRequest = useRef(0);
+  useEffect(() => {
+    if (!draft) return;
+    const n = ++planRequest.current;
+    setPlanning(true);
+    const id = setTimeout(async () => {
+      const r = await soundRoutes(slug).plan(draft);
+      if (n !== planRequest.current) return;
+      setPlanning(false);
+      if (!r.ok) {
+        setPlanError(r.error ?? "Erro ao planejar");
+        return;
+      }
+      setPlanError(null);
+      setPlan(r);
+    }, 220);
+    return () => clearTimeout(id);
+  }, [draft, slug]);
+}