Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
// Hook: region mutations for the new editor shell. Wraps the project store
// with typed add/remove/select operations for zoom, trim, annotation, and
// speed regions. Each add creates a 2-second region at the current playhead
// (a reasonable default for the user to then resize).
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { toast } from "sonner";
import { toFileUrl } from "@/components/video-editor/projectPersistence";
import type {
AnnotationRegion,
AnnotationType,
Rotation3DPreset,
} from "@/components/video-editor/types";
import { useScopedT } from "@/contexts/I18nContext";
import type { LayoutPreset } from "../../layoutTypes";
import { DEFAULT_TEXT_PLATE } from "../annotations/background";
import { fitTextBox } from "../annotations/placement";
import {
collapseTracksToPills,
patchAudioTrack,
placeAudioTrackInDocument,
removeAudioTrack as removeAudioTrackInDocument,
trackGroupId,
} from "../document/audioTracks";
import { createId } from "../document/ids";
import {
addLayoutChange as addLayoutChangeInDocument,
applyLayoutSpan,
defaultLayoutPreset,
layoutRuns as getLayoutRuns,
legacyCameraRegions,
moveLayoutBoundary as moveLayoutBoundaryInDocument,
setLayoutPreset as setLayoutPresetInDocument,
} from "../document/layout";
import { resolveAspectRatioValue } from "../document/outputFormat";
import {
clearEditRegions,
countEditRegions,
duplicateClip as duplicateClipInDocument,
insertAssetClip,
moveClip as moveClipInDocument,
PLACEHOLDER_DURATION_SEC,
type RegionKind,
readSpeedRegions,
removeClip as removeClipInDocument,
removeRegion as removeRegionInDocument,
resequenceClips,
setClipSourceRange,
} from "../document/timeline";
import type {
AxcutAudioTrack,
AxcutClipCropRegion,
AxcutDocument,
AxcutShaderEffectRange,
} from "../schema";
import {
findShaderEffect,
pruneUnusedShaderEffects,
storedShaderEffectValues,
} from "../shaderEffects";
import { appendAutoZoomSuggestions } from "../timeline/apply-auto-zooms";
import { hasAnyClipWithCamera } from "../timeline/camera";
import { probeAudioDuration, probeVideoDimensions, probeVideoDuration } from "../timeline/duration";
import {
type AnnotationTrackDrop,
annotationDropLayers,
annotationTrackPills,
} from "../timeline/regionTracks";
import {
anchorRegionsWithDerivedMs,
dropPillsByIds,
replacePillSpan,
resolvePillIds,
resolveRegionIds,
} from "../timeline/timelineMap";
import { dropTrimPillsByIds, resolveTimelineSpanToTrim } from "../timeline/trim-mapping";
import { MAX_ZOOM_SCALE, MIN_ZOOM_SCALE } from "../timeline/zoom-scale";
import type { AutoZoomSuggestion } from "../timeline/zoom-suggestions";
import { getEditorSettings } from "./editorSettings";
import { saveWithDeadline, useProjectStore, waitForDocumentSaves } from "./projectStore";
import { currentWriteEpoch } from "./undoStack";
import { useSequentialTimelineOps } from "./useSequentialTimelineOps";
// How long a region lasts when the caller doesn't say. The timeline's toolbar
// passes its own duration instead, derived from the current zoom so the new pill
// always comes out the same WIDTH on screen (see PILL_CREATE_PX in V4Timeline).
// Every other entry point — keyboard shortcuts, the agent, auto-zooms — gets
// these 2 s, which is what all five add* used to hardcode.
const DEFAULT_NEW_REGION_SEC = 2;
// NaN-guarded floors. Timeline inputs arrive from drag deltas and persisted
// documents, both of which can carry NaN; every action needs the same guard.
const finiteSec = (n: number) => (Number.isFinite(n) ? Math.max(0, n) : 0);
const finiteMs = (n: number) => (Number.isFinite(n) ? Math.max(0, Math.round(n)) : 0);
const finiteFraction = (n: number) => (Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0.5);
// Placeholder duration applied to a freshly-inserted clip whose source asset hasn't
// reported its real duration yet (media drag → drop before the preview video fires
// `loadedmetadata`). `applyProbedDuration` (document layer) swaps it — and the
// extent-less clip a legacy v2 import mints — for the real length once metadata
// arrives. Defined there, re-exported here so existing importers keep working and the
// value has exactly one definition.
export { PLACEHOLDER_DURATION_SEC };
interface RegionHandle {
kind: RegionKind;
id: string;
}
/**
* Patch the region `id` belongs to: every fragment of it across clip junctions, or the
* pieces of one region would disagree and, by the merge rule, visibly split. Not the whole
* pill: a region that merely matches and touches it is another region, left alone so the
* pill separates (#1017, see `resolveRegionIds`).
*/
function patchRegionById<T extends { id: string; startMs: number; endMs: number; clipId?: string }>(
regions: T[],
id: string,
patch: Partial<T>,
annotations = false,
): T[] {
const under = new Set(resolveRegionIds(regions, id, 0.001, { annotations }));
return regions.map((r) => (under.has(r.id) ? { ...r, ...patch } : r));
}
/**
* Playhead position at CALL time, read imperatively — deliberately not a
* subscription.
*
* `currentTimeSec` is rewritten on every animation frame during playback (see
* VirtualPreview's rAF tick). Subscribing to it here would give this hook's
* return value a new identity 60×/s and re-render every consumer with it — and
* `useTimeline()` is called by the editor shell, so that meant re-rendering the
* whole editor (timeline, clips, waveforms, inspector) once per frame just to
* move the playhead a few pixels. That render cascade was the playhead's own
* stutter: React had to commit the entire tree before the playhead's DOM moved.
*
* Nothing in this hook RENDERS the playhead — the add* actions below only need
* its value at the instant the user fires them, which is exactly what a
* getState() read gives (and is strictly fresher than a captured render value).
*/
function playheadSec(): number {
return useProjectStore.getState().currentTimeSec;
}
/** What the inspector changes on an effect region: its parameter values, or its target. */
export interface ShaderEffectPatch {
values?: Record<string, unknown>;
target?: AxcutShaderEffectRange["target"];
}
/** Every fragment of the effect pill `id` (one region, cut at clip boundaries), patched alike so
* it stays one pill. Values keep only what differs from the definition's defaults. `null` when
* the region or its definition is gone. */
function patchShaderEffectPill(
doc: AxcutDocument,
id: string,
patch: ShaderEffectPatch,
): AxcutDocument | null {
const ranges = doc.shaderEffectRanges ?? [];
const region = ranges.find((r) => r.id === id);
const definition = region ? findShaderEffect(doc, region.effectId) : null;
if (!region || !definition) return null;
const ids = new Set(resolvePillIds(ranges, id));
return {
...doc,
shaderEffectRanges: ranges.map((r) =>
ids.has(r.id)
? {
...r,
...(patch.values
? { values: storedShaderEffectValues(definition, { ...r.values, ...patch.values }) }
: {}),
...(patch.target ? { target: patch.target } : {}),
}
: r,
),
};
}
export function useTimeline() {
const ts = useScopedT("settings");
const document = useProjectStore((s) => s.document);
const projectId = useProjectStore((s) => s.projectId);
const saveDocument = useProjectStore((s) => s.saveDocument);
const setDocument = useProjectStore((s) => s.setDocument);
const [selection, setSelection] = useState<RegionHandle | null>(null);
// F2.7 — shift-click multi-selection. `selection` stays the inspector's
// focused region (the last one clicked); `multiSelection` is the full set
// the Delete key operates on.
const [multiSelection, setMultiSelection] = useState<RegionHandle[]>([]);
const [clipSelection, setClipSelection] = useState<string | null>(null);
// The selected imported audio track (issue #350) lives in the project store —
// not here — because the media panel and the inspector, in different subtrees,
// both touch it (see projectStore). It shares "this is the thing I mean"
// exclusivity with the region/clip selection above, so the selects below clear
// it and it clears them, but it carries none of the region delete/anchor logic.
const selectedAudioTrackId = useProjectStore((s) => s.selectedAudioTrackId);
const setSelectedAudioTrackId = useProjectStore((s) => s.setSelectedAudioTrackId);
const storeAddAudioTrack = useProjectStore((s) => s.addAudioTrack);
const importAudioAsset = useProjectStore((s) => s.importAudioAsset);
// Pre-drag snapshots for the two optimistic paths (zoom focus, annotations), so a
// failed commit can put the document back instead of leaving an edit on screen that
// was never written.
const zoomFocusRollbackRef = useRef<AxcutDocument | null>(null);
const zoomFocusLiveRef = useRef<AxcutDocument | null>(null);
// And the focus drag's last value, which its commit puts back if a zoom write lands over it,
// with the write epoch it was made in.
const zoomFocusEditRef = useRef<{
id: string;
focus: { cx: number; cy: number };
epoch: number;
} | null>(null);
const annotationRollbackRef = useRef<AxcutDocument | null>(null);
const annotationLiveRef = useRef<AxcutDocument | null>(null);
const shaderEffectRollbackRef = useRef<AxcutDocument | null>(null);
const shaderEffectLiveRef = useRef<AxcutDocument | null>(null);
// A drag does not always end in a commit: `ZoomFocusOverlay` unmounts the moment
// `focusMode` flips to "auto", so `endDrag` never runs and the snapshot outlives the
// project. Left alone, resetting focus in project B and failing that save restored
// project A's document into B -- the next successful save then wrote A over B. It
// also pinned two whole documents per hook instance, and annotations can carry
// base64 image data URLs.
// biome-ignore lint/correctness/useExhaustiveDependencies: projectId is the trigger, not a read — the body only clears refs.
useEffect(() => {
zoomFocusRollbackRef.current = null;
zoomFocusLiveRef.current = null;
zoomFocusEditRef.current = null;
annotationRollbackRef.current = null;
annotationLiveRef.current = null;
shaderEffectRollbackRef.current = null;
shaderEffectLiveRef.current = null;
}, [projectId]);
const hasDoc = document !== null && projectId !== null;
// Clear a stale audio-track selection. `removeAudioTrack` clears it on an explicit
// delete, but an undo (or any document swap) can drop the selected track WITHOUT
// going through that op — and then `selectedAudioTrackId` points at nothing while the
// inspector stays open on an empty AudioTrackPane, recoverable only by clicking a facet.
useEffect(() => {
if (selectedAudioTrackId === null) return;
if (!document?.audioTracks.some((t) => trackGroupId(t) === selectedAudioTrackId)) {
setSelectedAudioTrackId(null);
}
}, [document, selectedAudioTrackId, setSelectedAudioTrackId]);
// Backfill missing source dimensions for any USED asset whose `video` was never probed.
// `probeAndCorrectClip` only populates dims on INSERT, gated on a null duration, so an asset
// saved with a duration but no dims (e.g. a project migrated from before dims were probed
// alongside duration) never gets re-probed — opening it triggers no insert. `asset.video` is
// the single source of truth for a clip's real shape/size: the ratio picker's ORIGINAL list
// (collectNativeFormats), the output resolution (referenceClipDims) and the export badges all
// read it, so an unpopulated one silently drops that clip from ALL of them — which is why a
// cropped clip could show under ORIGINAL while an un-probed 16:9 sibling was missing entirely.
// Probe once on load and persist via saveDocument with `history: false` (a write the user
// never made must not be what the next Ctrl+Z reverses), so the fix sticks and every consumer
// agrees without each re-probing on its own (what the export dialog used to do). Attempt each
// asset at most once per session, even on failure, so a file that can't be probed doesn't
// spin the effect on every document change.
const probedAssetIdsRef = useRef<Set<string>>(new Set());
useEffect(() => {
if (!document) return;
const usedAssetIds = new Set(document.timeline.clips.map((c) => c.assetId));
type Asset = (typeof document.assets)[number];
const needsScreen = (a: Asset) =>
Boolean(a.originalPath) && (!a.video || !a.video.width || !a.video.height);
// The camera is backfilled the same way and for the same reason. The PiP's layout
// box is derived from these dimensions, so an asset that never carried them was
// laid out from a hardcoded 4:3 — and differently depending on who was asking: the
// preview had a mounted <video> reporting the real size, an export had nothing, so
// a 16:9 camera came out framed one way on screen and another in the file.
const needsCamera = (a: Asset) =>
Boolean(a.cameraTrack?.sourcePath) && (!a.cameraTrack?.width || !a.cameraTrack?.height);
const missing = document.assets.filter(
(a) =>
usedAssetIds.has(a.id) &&
(needsScreen(a) || needsCamera(a)) &&
!probedAssetIdsRef.current.has(a.id),
);
if (missing.length === 0) return;
// No cleanup cancels this. The effect re-runs on EVERY document change, and a fresh
// recording changes it several times while the probe is out (placeholder seed,
// measured duration, camera link, auto-zoom). A cancel dropped the result while the
// asset was already marked attempted, so nothing ever probed it again that session and
// the take was exported with no dims. The write below re-reads the store instead, and
// the project check is the only staleness that matters.
const originatingProjectId = document.project.id;
void (async () => {
type Dims = { width: number; height: number };
const probed: Record<string, { video?: Dims; camera?: Dims }> = {};
for (const a of missing) {
probedAssetIdsRef.current.add(a.id);
const entry: { video?: Dims; camera?: Dims } = {};
if (needsScreen(a)) {
const dims = await probeVideoDimensions(toFileUrl(a.originalPath));
if (dims) entry.video = dims;
}
// Probed independently of the screen: one file being unreadable must not cost
// the other its dimensions, and a camera-less asset simply skips this.
if (a.cameraTrack && needsCamera(a)) {
const dims = await probeVideoDimensions(toFileUrl(a.cameraTrack.sourcePath));
if (dims) entry.camera = dims;
}
if (entry.video || entry.camera) probed[a.id] = entry;
}
if (Object.keys(probed).length === 0) return;
// The store only takes a document once its save returns, so a write still in flight
// (the fresh-recording auto-zooms, typically) is invisible here. Building on the store
// before it lands and saving after it would erase it. Wait it out; on a timeout,
// write nothing and let a later run probe again.
if ((await waitForDocumentSaves()) === "timeout") {
for (const id of Object.keys(probed)) probedAssetIdsRef.current.delete(id);
return;
}
// Re-read fresh state so a concurrent edit made while probing isn't stomped.
const current = useProjectStore.getState().document;
if (!current || current.project.id !== originatingProjectId) return;
// `history: false` — see the comment above: a backfill nobody asked for must
// not become the thing the next Ctrl+Z reverses.
await useProjectStore.getState().saveDocument(
{
...current,
assets: current.assets.map((a) => {
const found = probed[a.id];
if (!found) return a;
return {
...a,
...(found.video
? { video: { codec: "unknown", fps: 0, ...a.video, ...found.video } }
: {}),
...(found.camera && a.cameraTrack
? { cameraTrack: { ...a.cameraTrack, ...found.camera } }
: {}),
};
}),
},
{ history: false },
);
})();
}, [document]);
// Backfill the real duration of imported audio assets (issue #350), the audio
// counterpart of the dimension backfill above. `addAudioAsset` probes once at
// import; a transient failure (timeout, a file still being written) would
// otherwise leave `durationSec` at 0 forever, and a 0-length window is a track
// that never plays and a pill with no width. Re-probe on load — once per asset
// per session, success or not — and stamp both the asset AND every track that
// caches its duration, with `history: false` so the fix is not an undo step.
const probedAudioAssetIdsRef = useRef<Set<string>>(new Set());
useEffect(() => {
if (!document) return;
const usedAssetIds = new Set(document.audioTracks.map((t) => t.assetId));
const missing = document.assets.filter(
(a) =>
a.kind === "audio" &&
a.originalPath &&
usedAssetIds.has(a.id) &&
!(a.durationSec && a.durationSec > 0) &&
!probedAudioAssetIdsRef.current.has(a.id),
);
if (missing.length === 0) return;
// Mark every candidate BEFORE the first await. Marking each only as its turn
// came meant a document change that re-entered this effect while asset #1 was
// still awaiting found #2+ unmarked and probed them a second time.
for (const a of missing) probedAudioAssetIdsRef.current.add(a.id);
let cancelled = false;
void (async () => {
const probed: Record<string, number> = {};
for (const a of missing) {
const durationSec = await probeAudioDuration(toFileUrl(a.originalPath));
if (durationSec != null && durationSec > 0) probed[a.id] = durationSec;
}
if (cancelled || Object.keys(probed).length === 0) return;
const current = useProjectStore.getState().document;
if (!current) return;
await useProjectStore.getState().saveDocument(
{
...current,
assets: current.assets.map((a) =>
probed[a.id] ? { ...a, durationSec: probed[a.id] } : a,
),
audioTracks: current.audioTracks.map((t) =>
probed[t.assetId] && !(t.durationSec > 0)
? { ...t, durationSec: probed[t.assetId] }
: t,
),
},
{ history: false },
);
})();
return () => {
cancelled = true;
};
}, [document]);
// Every add* below anchors the new region to the clip(s) it covers before storing it.
// A modifier MUST own a clip anchor to survive reorder/trim (see
// technical-documentation/architecture/timeline-model.md) — writing only startMs/endMs
// would strand it. A region created across a clip boundary becomes one fragment per
// clip; the ruler renders them as one pill because their properties are equal.
const addZoom = useCallback(
async (durationSec = DEFAULT_NEW_REGION_SEC) => {
if (!document) return;
const timeMs = Math.round(playheadSec() * 1000);
const endMs = timeMs + Math.round(durationSec * 1000);
const anchored = anchorRegionsWithDerivedMs(
[
{
id: createId("zoom"),
startMs: timeMs,
endMs,
depth: 3,
// Auto: a zoom added with Z frames what the pointer is doing, like the ones
// placed at import. The centre is its fallback where no pointer was recorded.
focus: { cx: 0.5, cy: 0.5 },
focusMode: "auto" as const,
},
],
document.timeline.clips,
() => createId("zoom"),
);
const next: AxcutDocument = {
...document,
zoomRanges: [...document.zoomRanges, ...anchored] as AxcutDocument["zoomRanges"],
};
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
// Append several auto-generated zoom regions in one save (auto-enhance).
// Suggestions come from buildAutoZoomSuggestions, which already reserves
// existing zoom spans, so no extra overlap filtering is needed here.
// Returns the count actually added (0 when there's no doc/suggestions).
const addZoomsBulk = useCallback(
async (suggestions: AutoZoomSuggestion[]) => {
// Read from the store, not off the render closure. Unlike its `add*` siblings,
// which compute and save in the same tick, this one is reached from the wand
// AFTER a multi-second cursor-telemetry IPC: the closure document is the one
// from before that wait, so anything the user committed during it is missing
// from the snapshot, and writing the snapshot back drops their edit. Reading
// here is also what lets this compose with `useSequentialTimelineOps` -- same
// reason as `applyClipEdit`, `setTrimEntries` and `insertClipAt`.
const doc = useProjectStore.getState().document;
if (!doc || suggestions.length === 0) return 0;
// The same wait makes the PROJECT stale, and reading the document fresh is what
// exposes it: the suggestions were built from the OLD project's telemetry and its
// ruler, so applying them to whatever is loaded now writes one project's zooms into
// another. `saveDocument`'s epoch check cannot see this one -- the write is issued
// after the switch, not across it -- which is the same reason
// `documentAfterProbedDuration` carries an `originatingProjectId`.
if (useProjectStore.getState().projectId !== projectId) return 0;
// One append shared with the fresh-recording import path, so the wand and the
// import cannot drift apart. It anchors against the SAME document the write is
// built from: anchoring on stale clips and saving the fresh document would
// place the regions against a timeline that no longer exists.
const next = appendAutoZoomSuggestions(doc, suggestions);
if (!(await saveDocument(next, { history: true }))) return 0;
return suggestions.length;
},
[projectId, saveDocument],
);
const addTrim = useCallback(
async (durationSec = DEFAULT_NEW_REGION_SEC) => {
if (!document) return;
// Insert a 2s trim at the playhead in *timeline* time, then resolve it
// down to the correct clip's asset + source-time. Writing currentTimeSec
// straight into startSec (as before) only happened to be right for an
// identity single-clip project — for trimmed/reordered clips it landed
// the trim at the wrong source position.
const playhead = playheadSec();
const end = playhead + durationSec;
const resolved = resolveTimelineSpanToTrim(playhead, end, document.timeline.clips);
const asset =
document.assets.find((a) => a.id === document.project.primaryAssetId) ?? document.assets[0];
if (!resolved && !asset) return;
const next: AxcutDocument = {
...document,
timeline: {
...document.timeline,
trimRanges: [
...document.timeline.trimRanges,
{
id: createId("trim"),
assetId: resolved?.assetId ?? asset!.id,
// The carrier clip, so the cut lands on THAT clip and not on every clip
// sharing its media (see `trimAppliesToClip`). Absent only in the
// no-clip fallback below, where there is no clip to name.
...(resolved ? { clipId: resolved.clipId } : {}),
startSec: resolved?.sourceStartSec ?? playhead,
endSec: resolved?.sourceEndSec ?? end,
reason: "manual",
origin: "user" as const,
},
],
},
};
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
const addAnnotation = useCallback(
async (durationSec = DEFAULT_NEW_REGION_SEC) => {
if (!document) return;
const timeMs = Math.round(playheadSec() * 1000);
const draft: AnnotationRegion = {
id: createId("ann"),
startMs: timeMs,
endMs: timeMs + Math.round(durationSec * 1000),
type: "text" as AnnotationType,
// Real, localised text rather than an empty field. An empty annotation
// renders nothing at all, so the user added a region and saw no change
// on the canvas; the inspector's placeholder is CSS ghost text that
// never reaches `content`, so it never reached the compositor either.
// `textContent` stays empty because the render path reads
// `content || textContent` and seeding both would just duplicate it.
content: ts("annotation.defaultText"),
textContent: "",
// On the frame, free of the footage: padding never moves it.
space: "frame",
// A point at the centre of the frame; `fitTextBox` below grows the box around it.
position: { x: 50, y: 50 },
size: { width: 0, height: 0 },
style: {
color: "#ffffff",
backgroundColor: DEFAULT_TEXT_PLATE,
fontSize: 32,
fontFamily: "Inter",
fontWeight: "bold",
fontStyle: "normal",
textDecoration: "none",
textAlign: "center",
textAnimation: "none",
},
zIndex: Math.max(0, ...document.annotations.map((a) => a.zIndex)) + 1,
};
const frameAspect = resolveAspectRatioValue(
document,
getEditorSettings(document).aspectRatio,
);
const ann: AnnotationRegion = { ...draft, ...fitTextBox(draft, frameAspect) };
const created = anchorRegionsWithDerivedMs([ann], document.timeline.clips, () =>
createId("ann"),
);
const next: AxcutDocument = {
...document,
annotations: [
...document.annotations,
...created,
] as unknown as AxcutDocument["annotations"],
};
if (!(await saveDocument(next, { history: true }))) return;
// Select the freshly added annotation so its inspector opens and it shows a
// selection box on the canvas, ready to be retyped over.
const newId = created[0]?.id ?? ann.id;
setMultiSelection([{ kind: "annotation", id: newId }]);
setSelection({ kind: "annotation", id: newId });
// `ts` is memoised on [locale, namespace] by useScopedT, so this does not
// churn the callback identity between renders.
},
[document, saveDocument, ts],
);
const addSpeed = useCallback(
async (durationSec = DEFAULT_NEW_REGION_SEC) => {
if (!document) return;
const timeMs = Math.round(playheadSec() * 1000);
const endMs = timeMs + Math.round(durationSec * 1000);
const legacy = (document.legacyEditor as Record<string, unknown>) ?? {};
const prev = (legacy.speedRegions as unknown[]) ?? [];
const next: AxcutDocument = {
...document,
legacyEditor: {
...legacy,
speedRegions: [
...prev,
...anchorRegionsWithDerivedMs(
[{ id: createId("speed"), startMs: timeMs, endMs, speed: 1.5 as const }],
document.timeline.clips,
() => createId("speed"),
),
],
},
};
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
// Full Camera: a plain time span (no value) during which the preview/export
// grows the webcam overlay to (almost) fill the canvas and eases it back.
//
// With no webcam anywhere on the timeline there is nothing to grow, so the region
// renders nothing in the preview (`PreviewCanvas.effectiveLayout` short-circuits on
// a missing `webcamRect`) and nothing in the export — it just sits in
// `legacyEditor.cameraFullscreenRegions` forever. The agent's `addCameraFullscreen`
// tool already refuses this and says why (electron/ai-edition/agent-tools.ts,
// `noCameraUnderSpan`); the gate lives HERE rather than at each button so both UI
// entry points — the toolbar and the `C` shortcut — and any future one are covered
// by construction. `hasAnyClipWithCamera` is the consolidated answer to "does this
// project have a camera at all", used the same way by the Layout pane.
const addCameraFullscreen = useCallback(
async (durationSec = DEFAULT_NEW_REGION_SEC) => {
if (!document) return;
if (!hasAnyClipWithCamera(document.assets, document.timeline.clips)) return;
const timeMs = Math.round(playheadSec() * 1000);
const endMs = timeMs + Math.round(durationSec * 1000);
const next = applyLayoutSpan(document, timeMs / 1000, endMs / 1000, "camera-only");
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
const addLayoutChange = useCallback(
async (preset: LayoutPreset, timeSec = playheadSec()) => {
if (!document) return;
const next = addLayoutChangeInDocument(document, timeSec, preset);
if (next === document) return;
if (!(await saveDocument(next, { history: true }))) return;
const run = getLayoutRuns(next).find((r) => timeSec >= r.start && timeSec < r.end);
setClipSelection(null);
if (run && (getLayoutRuns(next).length > 1 || run.member.legacyCamera)) {
setClipSelection(null);
setSelection({ kind: "layout", id: run.ids[0] });
setMultiSelection([{ kind: "layout", id: run.ids[0] }]);
} else {
setSelection(null);
setMultiSelection([]);
}
},
[document, saveDocument],
);
const setLayoutPreset = useCallback(
async (id: string, preset: LayoutPreset) => {
if (!document) return;
const next = setLayoutPresetInDocument(document, id, preset);
if (next === document) return;
if (!(await saveDocument(next, { history: true }))) return;
// A merge can retire the selected fragment's id.
setSelection(null);
setMultiSelection([]);
},
[document, saveDocument],
);
const moveLayoutBoundary = useCallback(
async (id: string, timeSec: number) => {
if (!document) return;
const next = moveLayoutBoundaryInDocument(document, id, timeSec);
if (next !== document) await saveDocument(next, { history: true });
},
[document, saveDocument],
);
// Like updateTrimRange but also re-attaches the trim to a (possibly different) CLIP —
// needed when a trim is dragged across a clip boundary, whether or not the landing clip
// is backed by another asset. Re-pointing `clipId` as well as `assetId` is what makes a
// drag onto the second clip of a duplicated asset actually move the cut instead of
// leaving it on the first (the two are indistinguishable by asset + source range alone).
// Callers resolve the timeline span via `resolveTimelineSpanToTrim`.
const updateTrim = useCallback(
async (
trimId: string,
next: { assetId: string; clipId?: string; startSec: number; endSec: number },
) => {
if (!document) return;
const s = finiteSec(next.startSec);
const e = finiteSec(next.endSec);
const nextDoc: AxcutDocument = {
...document,
timeline: {
...document.timeline,
trimRanges: document.timeline.trimRanges.map((r) =>
r.id === trimId
? {
...r,
assetId: next.assetId,
clipId: next.clipId,
startSec: Math.min(s, e),
endSec: Math.max(s, e),
}
: r,
),
},
};
await saveDocument(nextDoc, { history: true });
},
[document, saveDocument],
);
// Reconcile the set of trim entries "owned" by one drag with a freshly
// ventilated result. A trim resized across a clip boundary can't stay a
// single source range (source-time is per asset), so it materialises as one
// entry per covered clip — the caller passes explicit, stable ids (so the
// dragged pill keeps its identity across frames) plus `dropIds` for entries a
// shrinking span no longer needs. Trims not owned by this drag are untouched.
const setTrimEntries = useCallback(
async (
entries: Array<{
id: string;
assetId: string;
clipId?: string;
sourceStartSec: number;
sourceEndSec: number;
}>,
dropIds: string[],
) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
const managed = new Set<string>([...entries.map((e) => e.id), ...dropIds]);
const others = doc.timeline.trimRanges.filter((r) => !managed.has(r.id));
const rebuilt = entries.map((e) => {
const prev = doc.timeline.trimRanges.find((r) => r.id === e.id);
const s = finiteSec(e.sourceStartSec);
const en = finiteSec(e.sourceEndSec);
return {
id: e.id,
assetId: e.assetId,
// Ventilation names the covered clip per entry; carrying it through is what
// keeps a drag over two clips of the SAME media as two distinct cuts rather
// than one that lands on both.
clipId: e.clipId,
startSec: Math.min(s, en),
endSec: Math.max(s, en),
reason: prev?.reason ?? "manual",
origin: prev?.origin ?? ("user" as const),
};
});
await saveDocument(
{
...doc,
timeline: { ...doc.timeline, trimRanges: [...others, ...rebuilt] },
},
{ history: true },
);
},
[saveDocument],
);
// The zoom pane's own write chain -- see `queueZoomWrite`. Only `enqueue` is used, so
// there is no fallback document to hand it.
const { enqueue: enqueueZoomWrite } = useSequentialTimelineOps({
fallbackDocument: null,
saveDocument,
});
// Every whole-document write to one zoom goes through this chain: the pane's one-field
// writes (level, 3D tilt, focus mode, cursor), a pill's span, and the focus
// commit. `write` runs INSIDE the chain, on the document the previous zoom write left, and
// returns its `saveDocument`. The level buttons step while the previous save is still out,
// and 3 -> 4 -> 5 built both saves from the render's depth-3 document: the main process does
// not order them, so the 4 could land last, and even in order one Ctrl+Z skipped a level. A
// neighbouring select changed, a pill resized or a focus committed while a level was pending
// rebuilt from that same document and put 3 back. Resolves `saveDocument`'s answer, so the
// level buttons can retry a failed write, or `"timeout"` when it did not come in time.
//
// Each request is bound to the project and write epoch it was asked against — the same
// pair `addAsset` samples: an undo bumps the epoch, a project switch swaps both, and a
// queued patch that only STARTS after such a replacement must not apply to the document
// that replaced its target. A save whose answer is unknown (`saveWithDeadline` timed out
// with the bridge still silent) may still land, so later zoom writes are refused until it
// settles instead of racing it — the same "a queued write racing a stuck one" the
// `waitForDocumentSaves` header calls out. The block is keyed to the save's own epoch:
// once a replacement moves the epoch, that save can no longer install anything
// (`saveDocument` drops it) and must stop blocking; a project switch does not move the
// epoch, so there the stuck save can still land and the block correctly stays.
const unknownZoomSavesRef = useRef<Array<number>>([]);
const queueZoomWrite = useCallback(
(write: (doc: AxcutDocument, historyBase: AxcutDocument | undefined) => Promise<boolean>) => {
const epoch = currentWriteEpoch();
const projectId = useProjectStore.getState().projectId;
return enqueueZoomWrite(async () => {
if (useProjectStore.getState().projectId !== projectId || currentWriteEpoch() !== epoch) {
return false;
}
if (unknownZoomSavesRef.current.filter((stuck) => stuck === epoch).length > 0) {
return false;
}
const doc = useProjectStore.getState().document;
if (!doc) return false;
// A focus drag not yet committed is on screen, so this write saves it too, and the
// commit will find nothing left to record. Its undo step reaches back to before
// the drag instead, or the drag could never be undone.
const historyBase =
doc === zoomFocusLiveRef.current
? (zoomFocusRollbackRef.current ?? undefined)
: undefined;
const save = write(doc, historyBase);
const outcome = await saveWithDeadline(save);
if (outcome === "timeout") {
// Unknown, not failed: the write may still land. Refuse later writes into
// this same document generation until the save settles or the epoch moves
// past it.
unknownZoomSavesRef.current.push(epoch);
void save
.then(
() => undefined,
() => undefined,
)
.finally(() => {
unknownZoomSavesRef.current = unknownZoomSavesRef.current.filter(
(stuck) => stuck !== epoch,
);
});
}
return outcome;
});
},
[enqueueZoomWrite],
);
// Reports not-taken for an unknown answer too, so the buttons retry.
const saveZoomPatch = useCallback(
(id: string, patch: Partial<AxcutDocument["zoomRanges"][number]>) =>
queueZoomWrite((doc, historyBase) =>
saveDocument(
{
...doc,
zoomRanges: patchRegionById(doc.zoomRanges, id, patch) as AxcutDocument["zoomRanges"],
},
{ history: true, historyBase },
),
).then((outcome) => outcome === true),
[queueZoomWrite, saveDocument],
);
// Span edits are GROUP-AWARE: dragging/resizing a pill re-anchors every fragment
// under the pill to the new ruler span, so an edit that crosses a clip
// boundary re-splits and one dragged back inside a clip collapses — one user edit stays
// one pill. See timelineMap.reanchorGroupSpan.
const updateZoomSpan = useCallback(
(id: string, startMs: number, endMs: number) => {
const s = finiteMs(startMs);
const e = finiteMs(endMs);
return queueZoomWrite((doc, historyBase) =>
saveDocument(
{
...doc,
zoomRanges: replacePillSpan(
doc.zoomRanges,
id,
Math.min(s, e),
Math.max(s, e),
doc.timeline.clips,
() => createId("zoom"),
) as AxcutDocument["zoomRanges"],
},
{ history: true, historyBase },
),
);
},
[queueZoomWrite, saveDocument],
);
// ponytail: the focus overlay drags at pointermove frequency (~60-120 Hz).
// Routing every frame through `saveDocument` (IPC round-trip + disk write
// + zod re-parse + full store replace) made dragging visibly laggy.
// `updateZoomFocusLive` mirrors `useEditorSettings`'s setLive/commit split:
// local-only store writes while dragging, one persisted save on release.
const updateZoomFocusLive = useCallback(
(id: string, focus: { cx: number; cy: number }) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
// The first live write of a drag is the one editing a document this callback
// did not itself produce, so it is the pre-drag state — the one thing worth
// returning to. It is remembered, not recorded: `commitZoomFocus` hands it to
// `saveDocument` as `historyBase`, so the whole gesture becomes ONE undo step
// and only once the write landed. Recording it here instead left the entry
// behind when the commit failed and rolled the document back to that very
// document — a Ctrl+Z that visibly did nothing, with `future` already wiped.
if (zoomFocusLiveRef.current !== doc) zoomFocusRollbackRef.current = doc;
const edit = {
id,
focus: { cx: finiteFraction(focus.cx), cy: finiteFraction(focus.cy) },
epoch: currentWriteEpoch(),
};
const next: AxcutDocument = {
...doc,
zoomRanges: patchRegionById(doc.zoomRanges, id, {
focus: edit.focus,
}) as AxcutDocument["zoomRanges"],
};
setDocument(next, { history: false });
zoomFocusLiveRef.current = next;
zoomFocusEditRef.current = edit;
},
[setDocument],
);
// On the zoom chain, like every zoom write: a level still being saved when the focus is
// committed would otherwise land first and be overwritten by this save, built before it.
const commitZoomFocus = useCallback(async () => {
// What the drag left, taken now. While the commit waits its turn, a zoom write queued
// before the drag can land, and it installs ITS document, built before the drag, in
// place of the dragged one.
const live = zoomFocusLiveRef.current;
const rollback = zoomFocusRollbackRef.current;
const epoch = currentWriteEpoch();
// A drag abandoned before an undo or a replacement is not this commit's to put back: the
// document it was made on is gone, and restoring its focus would undo the undo.
const pendingEdit = zoomFocusEditRef.current;
const edit = pendingEdit?.epoch === epoch ? pendingEdit : null;
zoomFocusRollbackRef.current = null;
zoomFocusLiveRef.current = null;
zoomFocusEditRef.current = null;
const pending: { save?: Promise<boolean> } = {};
const outcome = await queueZoomWrite((doc) => {
// The snapshot counts only while the document on screen is still the one this
// hook's last live write produced -- `updateZoomFocusLive`'s own identity test,
// read the other way round. Without it a commit that arrives with no live write
// in front of it picks up whatever an abandoned drag left behind, and every
// recording write since has already put the states in between on the stack: as a
// `historyBase` that makes one Ctrl+Z step over the lot, and on the failure path
// below it puts that buried document back on screen, silently dropping them.
// `handlePointerDown` sets `draggingRef` BEFORE its live write and that write
// returns early on a zero-size overlay rect, so `endDrag` can reach here bare.
//
// `historyBase` is the pre-drag document, not the one the store holds (that is the
// dragged one, written live); `null` when no live write happened, which records
// nothing, which is right: nothing changed.
let next = doc;
let historyBase = doc === live ? rollback : null;
const pill = edit ? doc.zoomRanges.find((zoom) => zoom.id === edit.id) : undefined;
if (
doc !== live &&
edit &&
pill &&
(pill.focus.cx !== edit.focus.cx || pill.focus.cy !== edit.focus.cy)
) {
// A zoom write landed over the drag and took its focus off screen. The focus goes
// back on top of that write, so both stay, and one Ctrl+Z takes the focus off it
// again. When the writes since carried the focus along, there is nothing to add.
next = {
...doc,
zoomRanges: patchRegionById(doc.zoomRanges, edit.id, {
focus: edit.focus,
}) as AxcutDocument["zoomRanges"],
};
historyBase = doc;
}
pending.save = saveDocument(next, { history: true, historyBase });
return pending.save;
});
// A save out of time has left the chain, but it can still fail: its answer, whenever it
// comes, decides the rollback, or the dragged focus stays on screen for a later save.
const saved = outcome === "timeout" && pending.save ? await pending.save : outcome;
if (saved === false && rollback) {
useProjectStore.setState((state) =>
// Only while the dragged document is still the one on screen, in the epoch it was
// committed in: anything else there was put by a write that landed, or by an undo.
// `dirty` is deliberately NOT cleared. The rollback target is the last document
// this drag started from, which is not the same as the last SAVED one: with two
// commits in flight the first one's unsaved document is what we restore. Saying
// "clean" there tells `beforeunload` and `setHasUnsavedChanges` there is nothing
// to save, and the window closes on real work without prompting.
state.document === live && currentWriteEpoch() === epoch
? { document: rollback, revision: state.revision + 1 }
: {},
);
}
}, [queueZoomWrite, saveDocument]);
// A preset level (`ZOOM_DEPTH_SCALES`, 1.25×–5×). It clears any custom scale, which
// would otherwise keep overriding the depth: the level picked is the level rendered.
const updateZoomDepth = useCallback(
(id: string, depth: 1 | 2 | 3 | 4 | 5 | 6) =>
saveZoomPatch(id, { depth, customScale: undefined }),
[saveZoomPatch],
);
// Any other level, from the pane's free field. Clamped to the renderer's range here, so no
// caller can store a scale that `effectiveZoomScale` would then read differently.
const updateZoomCustomScale = useCallback(
(id: string, scale: number) =>
saveZoomPatch(id, { customScale: Math.min(MAX_ZOOM_SCALE, Math.max(MIN_ZOOM_SCALE, scale)) }),
[saveZoomPatch],
);
// Same story as `focusMode` below: the 3D tilt was implemented end to end — schema
// (`rotationPreset`), migration, `sceneDescription` (`rotation:`), `rotation3d_for` in
// regions.rs and the perspective shader in compositor.rs — with no control to set it.
// `undefined` clears the preset back to a flat frame; `migrate.ts` already drops the field
// when it is falsy, so absent and "no rotation" are the same state.
const updateZoomRotation = useCallback(
(id: string, rotationPreset: Rotation3DPreset | undefined) =>
saveZoomPatch(id, { rotationPreset }),
[saveZoomPatch],
);
// Nothing could set `focusMode`: "auto" only ever arrived from the automatic suggestion pass
// (`zoomSuggestions.ts`), so a hand-drawn zoom stayed pinned to its static focus point with no
// way to make it follow the cursor. The capability itself was complete end to end —
// `sceneDescription.ts` ships the mode, `scene.rs` parses it, `regions.rs::resolve_focus`
// samples the cursor track — only this setter was missing.
//
// Writing "manual" explicitly is safe even though `migrate.ts` only persists "auto": an absent
// field MEANS manual, so both forms resolve identically.
const updateZoomFocusMode = useCallback(
(id: string, focusMode: "manual" | "auto") => saveZoomPatch(id, { focusMode }),
[saveZoomPatch],
);
const updateZoomHideCursor = useCallback(
(id: string, hideCursor: boolean | undefined) =>
saveZoomPatch(id, { hideCursor: hideCursor ? true : undefined }),
[saveZoomPatch],
);
const updateAnnotationSpan = useCallback(
async (id: string, startMs: number, endMs: number, drop?: AnnotationTrackDrop) => {
if (!document) return;
const s = Math.min(finiteMs(startMs), finiteMs(endMs));
const e = Math.max(finiteMs(startMs), finiteMs(endMs));
const pills = annotationTrackPills(document.annotations);
const pill = pills.find((p) => p.ids.includes(id));
if (!pill) return;
const layers = drop
? annotationDropLayers(pills, pill.id, { start: s / 1000, end: e / 1000 }, drop)
: new Map<string, number>();
const layerByRegion = new Map(
pills.flatMap((p) => p.ids.map((regionId) => [regionId, layers.get(p.id)] as const)),
);
const annotations = document.annotations.map((a) => {
const layer = layerByRegion.get(a.id);
return layer === undefined ? a : { ...a, zIndex: layer };
});
// Span and compositing order persist together as one undo step.
await saveDocument(
{
...document,
annotations: replacePillSpan(
annotations,
id,
s,
e,
document.timeline.clips,
() => createId("ann"),
0.001,
{},
{ annotations: true },
),
},
{ history: true },
);
},
[document, saveDocument],
);
// Drag/resize on the preview overlay (position, size, blur mask edits) — same
// live/commit split as updateZoomFocusLive/commitZoomFocus, for the same
// reason: local-only writes while dragging, one persisted save on release.
const updateAnnotationLive = useCallback(
(id: string, patch: Partial<AxcutDocument["annotations"][number]>) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
// One undo step per drag, recorded by the commit once it lands — same
// reasoning, and the same failed-commit hole, as `updateZoomFocusLive` above.
if (annotationLiveRef.current !== doc) annotationRollbackRef.current = doc;
const next: AxcutDocument = {
...doc,
annotations: patchRegionById(doc.annotations, id, patch, true),
};
setDocument(next, { history: false });
annotationLiveRef.current = next;
},
[setDocument],
);
const commitAnnotationChange = useCallback(async () => {
const doc = useProjectStore.getState().document;
if (!doc) return;
// See `commitZoomFocus`: the snapshot counts only while the document on screen is
// still the one this hook's live writes produced. This is the reachable half.
// The inspector's annotation `<textarea>` calls `updateAnnotationLive` on every
// keystroke and commits `onBlur`, and closing the panel unmounts the focused node
// before blur can fire: `V4Timeline`'s `startScrub` clears the selection from a
// pointerdown handler, and React flushes discrete events synchronously, so the
// textarea is gone before mousedown moves focus. (Deleting the region does NOT
// reach here — its button is an `onClick`, which runs after blur has committed.)
// `SliderCell` then wires mouseup
// straight to `onCommit`, so a bare click on a stroke-width thumb lands here
// carrying the typing's base. `NewEditorShell` builds one `useTimeline()` for
// both, so it is one instance's ref.
const rollback = annotationLiveRef.current === doc ? annotationRollbackRef.current : null;
annotationRollbackRef.current = null;
annotationLiveRef.current = null;
// The pre-drag document is the undo target, and it is recorded only if this write
// succeeds.
if (!(await saveDocument(doc, { history: true, historyBase: rollback })) && rollback) {
useProjectStore.setState((state) =>
// `dirty` is deliberately NOT cleared. The rollback target is the last document
// this drag started from, which is not the same as the last SAVED one: with two
// commits in flight the first one's unsaved document is what we restore. Saying
// "clean" there tells `beforeunload` and `setHasUnsavedChanges` there is nothing
// to save, and the window closes on real work without prompting.
state.document === doc ? { document: rollback, revision: state.revision + 1 } : {},
);
}
}, [saveDocument]);
const updateSpeedSpan = useCallback(
async (id: string, startMs: number, endMs: number) => {
if (!document) return;
const s = finiteMs(startMs);
const e = finiteMs(endMs);
const legacy = (document.legacyEditor as Record<string, unknown>) ?? {};
const prev = ((legacy.speedRegions as unknown[]) ?? []) as Array<{
id: string;
startMs: number;
endMs: number;
speed: number;
}>;
const next: AxcutDocument = {
...document,
legacyEditor: {
...legacy,
speedRegions: replacePillSpan(
prev,
id,
Math.min(s, e),
Math.max(s, e),
document.timeline.clips,
() => createId("speed"),
),
},
};
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
const updateCameraFullscreenSpan = useCallback(
async (id: string, startMs: number, endMs: number) => {
if (!document) return;
const s = finiteMs(startMs);
const e = finiteMs(endMs);
const runs = getLayoutRuns(document);
const index = runs.findIndex((r) => r.ids.includes(id));
if (index < 0) return;
const base = applyLayoutSpan(
document,
runs[index].start,
runs[index].end,
runs[index - 1]?.member.preset ?? defaultLayoutPreset(document),
);
const next = applyLayoutSpan(
base,
Math.min(s, e) / 1000,
Math.max(s, e) / 1000,
"camera-only",
);
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
const updateShaderEffectSpan = useCallback(
async (id: string, startMs: number, endMs: number) => {
if (!document) return;
const s = finiteMs(startMs);
const e = finiteMs(endMs);
// Clamped against the neighbouring effects: one effect runs at a time.
const next: AxcutDocument = {
...document,
shaderEffectRanges: replacePillSpan(
document.shaderEffectRanges ?? [],
id,
Math.min(s, e),
Math.max(s, e),
document.timeline.clips,
() => createId("fxr"),
),
};
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
// A discrete inspector edit (the target, a toggle): one save, one undo step.
const updateShaderEffect = useCallback(
async (id: string, patch: ShaderEffectPatch) => {
if (!document) return;
const next = patchShaderEffectPill(document, id, patch);
if (next) await saveDocument(next, { history: true });
},
[document, saveDocument],
);
// A continuous one (a slider, a colour): local writes while it lasts, then one save and one
// undo step from `commitShaderEffectChange`. The annotations' live path, for effects.
const updateShaderEffectLive = useCallback(
(id: string, patch: ShaderEffectPatch) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
const next = patchShaderEffectPill(doc, id, patch);
if (!next) return;
if (shaderEffectLiveRef.current !== doc) shaderEffectRollbackRef.current = doc;
setDocument(next, { history: false });
shaderEffectLiveRef.current = next;
},
[setDocument],
);
// `commitAnnotationChange`, for the effect refs: the pre-gesture document is the undo
// target, recorded only if the write lands, and put back if it does not.
const commitShaderEffectChange = useCallback(async () => {
const doc = useProjectStore.getState().document;
if (!doc) return;
const rollback = shaderEffectLiveRef.current === doc ? shaderEffectRollbackRef.current : null;
shaderEffectRollbackRef.current = null;
shaderEffectLiveRef.current = null;
if (!(await saveDocument(doc, { history: true, historyBase: rollback })) && rollback) {
useProjectStore.setState((state) =>
state.document === doc ? { document: rollback, revision: state.revision + 1 } : {},
);
}
}, [saveDocument]);
const updateSpeedValue = useCallback(
async (id: string, speed: number) => {
if (!document) return;
const legacy = (document.legacyEditor as Record<string, unknown>) ?? {};
const prev = ((legacy.speedRegions as unknown[]) ?? []) as Array<{
id: string;
startMs: number;
endMs: number;
speed: number;
}>;
const next: AxcutDocument = {
...document,
legacyEditor: {
...legacy,
speedRegions: patchRegionById(prev, id, { speed }),
},
};
await saveDocument(next, { history: true });
},
[document, saveDocument],
);
const removeRegion = useCallback(
async (kind: RegionKind, id: string) => {
if (!document) return;
// One shared mutator with the agent's removeTrim / removeModifier tools.
if (!(await saveDocument(removeRegionInDocument(document, kind, id), { history: true })))
return;
if (selection?.id === id) setSelection(null);
setMultiSelection((prev) => prev.filter((h) => h.id !== id));
},
[document, selection, saveDocument],
);
// F2.7 — batch removal for multi-selection: one document save (one undo
// snapshot) regardless of how many regions are selected.
const removeRegions = useCallback(
async (handles: RegionHandle[]) => {
if (!document || handles.length === 0) return;
const zoomIds = new Set(handles.filter((h) => h.kind === "zoom").map((h) => h.id));
const trimIds = new Set(handles.filter((h) => h.kind === "trim").map((h) => h.id));
const annotationIds = new Set(
handles.filter((h) => h.kind === "annotation").map((h) => h.id),
);
const speedIds = new Set(handles.filter((h) => h.kind === "speed").map((h) => h.id));
const cameraFullscreenIds = new Set(
handles.filter((h) => h.kind === "cameraFullscreen").map((h) => h.id),
);
const shaderEffectIds = new Set(
handles.filter((h) => h.kind === "shaderEffect").map((h) => h.id),
);
const legacy = (document.legacyEditor as Record<string, unknown>) ?? {};
const prevSpeed = dropPillsByIds(
(legacy.speedRegions as Array<{ id: string; startMs: number; endMs: number }>) ?? [],
speedIds,
);
const prevCameraFullscreen = dropPillsByIds(
(legacy.cameraFullscreenRegions as Array<{ id: string; startMs: number; endMs: number }>) ??
[],
cameraFullscreenIds,
);
let next: AxcutDocument = pruneUnusedShaderEffects({
...document,
zoomRanges: dropPillsByIds(document.zoomRanges, zoomIds) as AxcutDocument["zoomRanges"],
annotations: dropPillsByIds(document.annotations, annotationIds, { annotations: true }),
...(shaderEffectIds.size > 0
? {
shaderEffectRanges: dropPillsByIds(
document.shaderEffectRanges ?? [],
shaderEffectIds,
),
}
: {}),
timeline: {
...document.timeline,
// Whole-pill delete, same as the zoom/annotation lines above — a trim grown
// across a clip boundary is 2+ rows rendering as one stripe, and a bare id
// filter left the halves the selection didn't name still cutting.
trimRanges: dropTrimPillsByIds(
document.timeline.trimRanges,
document.timeline.clips,
trimIds,
),
},
legacyEditor:
speedIds.size > 0 || cameraFullscreenIds.size > 0
? { ...legacy, speedRegions: prevSpeed, cameraFullscreenRegions: prevCameraFullscreen }
: document.legacyEditor,
});
// Layout deletion closes a change; it must never punch a hole in the partition.
const layoutIds = new Set(handles.filter((h) => h.kind === "layout").map((h) => h.id));
for (const run of getLayoutRuns(next).reverse()) {
if (run.ids.some((id) => layoutIds.has(id)))
next = removeRegionInDocument(next, "layout", run.ids[0]);
}
if (!(await saveDocument(next, { history: true }))) return;
setSelection(null);
setMultiSelection([]);
},
[document, saveDocument],
);
// Every edit region (zoom, speed, trim, annotation, Full Camera), on every clip, in one
// write: one undo step brings them all back. Clips, media, audio tracks, captions and the
// transcript are content, not edits, and stay (see `clearEditRegions`).
//
// `hasEditRegions` counts the STORED regions, not the pills the lanes draw: a trim whose
// clip is gone is stored and cleared but has no pill. The toolbar button reads it too, so
// what shows the button and what the action clears are one count.
const hasEditRegions = document !== null && countEditRegions(document) > 0;
const clearTimeline = useCallback(async () => {
if (!document || !hasEditRegions) return;
if (!(await saveDocument(clearEditRegions(document), { history: true }))) return;
// Every region a selection can point at is gone. An audio track is not one of them.
if (selection && selection.kind !== "audio") setSelection(null);
setMultiSelection((prev) => prev.filter((h) => h.kind === "audio"));
}, [document, hasEditRegions, selection, saveDocument]);
// Selecting a pill and selecting a clip are the SAME act — "this is the thing
// I mean" — so they cancel each other. They used to be two states that could
// both be set: the user saw one highlighted element while the app still held
// the other, and everything keyed off "is a clip selected?" (copy, paste,
// delete) silently acted on the invisible one. Copy/paste is where it showed:
// it always operated on the clip, whatever the user had just clicked.
const selectRegion = useCallback(
(kind: RegionKind, id: string, opts?: { additive?: boolean }) => {
const handle = { kind, id };
setClipSelection(null);
setSelectedAudioTrackId(null);
if (opts?.additive) {
// Shift-click toggles membership; the focused region follows the click.
setMultiSelection((prev) => {
const exists = prev.some((h) => h.kind === kind && h.id === id);
return exists ? prev.filter((h) => !(h.kind === kind && h.id === id)) : [...prev, handle];
});
setSelection(handle);
return;
}
setMultiSelection([handle]);
setSelection(handle);
},
[setSelectedAudioTrackId],
);
const clearSelection = useCallback(() => {
setSelection(null);
setMultiSelection([]);
setClipSelection(null);
setSelectedAudioTrackId(null);
}, [setSelectedAudioTrackId]);
// The Edit Clip dialog's Apply, as ONE document and ONE save.
//
// Source range and crop are two edits made in a single user action, and they used to
// be two independent saves fired back to back. Both built their next document from
// the SAME pre-Apply one — the crop write never saw the source-range change — so
// whichever IPC write landed last silently dropped the other edit, with no error and
// no toast (#355). Composing them means the crop is applied to the *resequenced*
// clips, which is also the only order that can be right.
//
// Axcut-consistent clip trim: only the source range is user-editable (the dialog's
// draggable track). Changing it changes the clip's effective duration, so every clip
// is resequenced back-to-back afterward — same invariant as
// insertClipAt/moveClip/removeClip — instead of leaving downstream clips at their old
// timeline positions (which would overlap). That whole recipe (resequence width +
// clamp/rederive pills) lives in the one pure `setClipSourceRange`, shared with the op
// dispatcher and the LLM tool.
//
// Crop is a per-clip framing, not a document-wide setting — two clips (even from the
// same asset) can reasonably want different crops. `undefined` means the dialog's crop
// section was never touched (leave the stored value alone); `null` clears it back to
// "no crop" (full frame) rather than storing the identity region explicitly.
//
// The document is read from the store, not off the render closure, so this composes
// with `useSequentialTimelineOps`: queued behind another timeline write, it still sees
// what that write committed. Same reason as `setTrimEntries` / `insertClipAt`.
const applyClipEdit = useCallback(
async (
clipId: string,
sourceStartSec: number,
sourceEndSec: number,
cropRegion?: AxcutClipCropRegion | null,
) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
const next = setClipSourceRange(doc, clipId, sourceStartSec, sourceEndSec, cropRegion);
await saveDocument(next, { history: true });
},
[saveDocument],
);
// Background probe: read the asset's actual duration and patch the
// freshly-inserted clip to use it. Trims if the clip has already been
// trimmed (sourceEndSec != PLACEHOLDER_DURATION_SEC) so we never stomp
// on user edits. Also persists the duration back onto the asset so
// subsequent inserts use the cached value without re-probing.
const probeAndCorrectClip = useCallback(
async (assetId: string, clipId: string, originalPath: string) => {
const fileUrl = toFileUrl(originalPath);
// Dims probed alongside duration — otherwise `asset.video` stays permanently unset for
// most recordings (nothing else populates it), silently breaking anything that reads
// real source dimensions later (e.g. the export dialog's downscale/upscale badges).
const [probedDuration, probedDims] = await Promise.all([
probeVideoDuration(fileUrl),
probeVideoDimensions(fileUrl),
]);
const state = useProjectStore.getState();
const doc = state.document;
if (!doc) return;
const asset = doc.assets.find((a) => a.id === assetId);
const needsDims = probedDims != null && !asset?.video;
if (probedDuration == null && !needsDims) return;
// Guard: only correct clips still sitting at the 0..60s placeholder.
// If the user has since trimmed the clip or moved on, leave it alone.
const clip = doc.timeline.clips.find((c) => c.id === clipId);
const stillPlaceholder =
clip != null &&
clip.sourceStartSec === 0 &&
Math.abs((clip.sourceEndSec ?? 0) - PLACEHOLDER_DURATION_SEC) < 0.01;
const correctDuration = probedDuration != null && stillPlaceholder;
if (!correctDuration && !needsDims) return;
// Only correct the probed clip's own length here — do NOT hand-shift
// every sibling by the delta, since that has no notion of which clips
// sit before vs. after this one in timeline order (it used to shift
// earlier clips too, corrupting their positions). resequenceClips lays
// everything back-to-back from t=0 using each clip's own (now correct)
// length, so it's the correct + already-shared way to renormalize.
const oldClips = doc.timeline.clips;
const nextClips = correctDuration
? resequenceClips(
oldClips.map((c) =>
c.id === clipId
? {
...c,
sourceEndSec: probedDuration as number,
timelineEndSec: c.timelineStartSec + (probedDuration as number),
}
: c,
),
)
: oldClips;
const nextAssets = doc.assets.map((a) => {
if (a.id !== assetId) return a;
return {
...a,
...(correctDuration ? { durationSec: probedDuration as number } : {}),
...(needsDims ? { video: { codec: "unknown", fps: 0, ...a.video, ...probedDims } } : {}),
};
});
// `history: false`. Nothing about this write is a user action: `addAsset` never
// populates `durationSec`, so EVERY freshly imported asset lands at the 60s
// placeholder and fires this probe. Recording it put a placeholder-length clip
// on the undo stack a beat after the drop, so the first Ctrl+Z snapped the clip
// back to 60s instead of removing it — and a probe resolving after the user
// had already undone wiped `future`, destroying redo from a background write.
await state.saveDocument(
{
...doc,
assets: nextAssets,
timeline: { ...doc.timeline, clips: nextClips },
},
{ history: false },
);
},
[],
);
// Insert a new full-duration clip for `assetId` at position `index`
// (0 = before all, clips.length = after all), then resequence.
//
// ponytail: probe the file's actual duration via a throwaway <video> in
// the BACKGROUND so the drop event stays responsive. Earlier this awaited
// probeVideoDuration synchronously, which could take up to 5s on a slow
// disk or broken file path — the user saw the UI freeze for the whole
// probe window with no feedback. Now: insert the clip immediately at the
// placeholder (60s), then update its sourceEndSec / timelineEndSec when
// the probe resolves. If the user has since trimmed the clip, we leave it
// alone (same guard handleLoadedMetadata uses).
const insertClipAt = useCallback(
async (assetId: string, index: number) => {
const currentDoc = useProjectStore.getState().document;
if (!currentDoc) return;
const asset = currentDoc.assets.find((a) => a.id === assetId);
if (!asset) return;
// Insert immediately at whatever we know. If the asset has a cached
// durationSec we use it; otherwise we fall back to the placeholder
// and let the background probe correct it.
const knownDuration = asset.durationSec ?? PLACEHOLDER_DURATION_SEC;
const newClip = {
id: createId("clip"),
assetId,
sourceStartSec: 0,
sourceEndSec: knownDuration,
origin: "user" as const,
reason: "Inserted from media panel",
};
const finalDoc = insertAssetClip(currentDoc, index, newClip);
if (!(await saveDocument(finalDoc, { history: true }))) return;
setClipSelection(newClip.id);
// If we used the placeholder, kick off the probe in the background.
// Don't await — the drop is already responsive; the probe will
// correct the clip when it lands.
if (asset.durationSec == null) {
// Detached on purpose (see above), so it needs its own handler: the probe
// itself only ever resolves, but it finishes with a `saveDocument`, and
// that THROWS on a failed write. Losing a background duration correction
// is survivable — the clip keeps its placeholder length; an unhandled
// rejection is not.
void probeAndCorrectClip(assetId, newClip.id, asset.originalPath).catch((err) => {
console.warn("[timeline] background duration probe failed to save:", err);
});
}
},
[saveDocument, probeAndCorrectClip],
);
// Reorder a clip to a new index, then resequence timeline positions.
// Delegates to the shared document/timeline.ts implementation — the same
// function the agent tool-executor uses for "move_clip" ops — so both
// paths stay in step instead of maintaining two copies of the
// splice/resequence logic that could drift.
const moveClip = useCallback(
async (clipId: string, toIndex: number) => {
if (!document) return;
if (!document.timeline.clips.some((c) => c.id === clipId)) return;
await saveDocument(moveClipInDocument(document, clipId, toIndex), { history: true });
},
[document, saveDocument],
);
// Duplicate a clip in place (same asset + source range), inserted right
// after the original, then resequenced. Mirrors Axcut's Ctrl+C/Ctrl+V.
// Delegates to the shared implementation (see moveClip above).
const duplicateClip = useCallback(
async (clipId: string) => {
if (!document) return;
if (!document.timeline.clips.some((c) => c.id === clipId)) return;
// duplicateClipInDocument inserts the copy immediately after the
// original, so its index in the result is the original's index + 1.
const insertedIndex = document.timeline.clips.findIndex((c) => c.id === clipId) + 1;
const next = duplicateClipInDocument(document, clipId, "user", "Duplicated clip");
if (!(await saveDocument(next, { history: true }))) return;
setClipSelection(next.timeline.clips[insertedIndex]?.id ?? null);
},
[document, saveDocument],
);
const removeClip = useCallback(
async (clipId: string) => {
if (!document) return;
// One shared mutator with the agent's removeClip tool: reflow survivors + rederive pills.
if (!(await saveDocument(removeClipInDocument(document, clipId), { history: true }))) return;
if (clipSelection === clipId) setClipSelection(null);
},
[document, clipSelection, saveDocument],
);
// Mirror of selectRegion: picking a clip retires the pill selection.
const selectClip = useCallback(
(id: string) => {
setClipSelection(id);
setSelection(null);
setMultiSelection([]);
setSelectedAudioTrackId(null);
},
[setSelectedAudioTrackId],
);
// Picking an audio track retires every other selection, same exclusivity rule.
const selectAudioTrack = useCallback(
(id: string) => {
setSelectedAudioTrackId(id);
setSelection(null);
setMultiSelection([]);
setClipSelection(null);
},
[setSelectedAudioTrackId],
);
const speedRegions = hasDoc
? readSpeedRegions<{ id: string; startMs: number; endMs: number; speed: number }>(document)
: [];
const cameraFullscreenRegions = useMemo(
() => (document ? legacyCameraRegions(document) : []),
[document],
);
const layoutSegments = useMemo(() => (document ? getLayoutRuns(document) : []), [document]);
// One region per effect, never two at once; each names its definition.
const shaderEffectRanges = hasDoc ? (document.shaderEffectRanges ?? []) : [];
const shaderEffects = hasDoc ? (document.shaderEffects ?? []) : [];
// --- Timeline audio tracks (issue #350) -------------------------------------
// CLIP-ANCHORED like every region above: one user-visible track is one pill
// over one-or-more stored fragments, so these ops go through the shared pill
// helpers and address a track by its group id, never a fragment id.
// Place a new track for an imported audio asset, its head at the playhead (in
// RAW/document timeline seconds — the clock the ruler and playhead use, NOT the
// trim-compressed output programme the export mixes onto) unless the caller says
// otherwise. Delegates to the store op, which also selects the new track and
// returns its id (or null). On success, retire the hook-local region/clip
// selection so the new audio-track selection isn't held CONCURRENTLY with a
// stale region/clip one.
const addAudioTrack = useCallback(
async (
assetId: string,
timelineStartSec?: number,
options?: { kind?: "voiceover" | "music"; durationSec?: number; spanSec?: number },
): Promise<string | null> => {
const id = await storeAddAudioTrack(assetId, timelineStartSec ?? playheadSec(), options);
if (id) {
setSelection(null);
setMultiSelection([]);
setClipSelection(null);
}
return id;
},
[storeAddAudioTrack],
);
// Import an audio file and drop it on the timeline (issue #350). Lives here — not in
// the timeline toolbar — so the toolbar button and the keyboard shortcut (both call
// through `tl`) share one path. Opens a file picker, so unlike the region adds it takes
// no playhead duration; `importAudioAsset` places the track at the current playhead.
const addAudio = useCallback(async () => {
try {
// Inside the try so a rejected picker (an IPC failure, not a cancel) still reaches the
// localized toast instead of surfacing as an unhandled rejection. A cancel resolves with
// `success: false` and is a silent early return, not an error.
const picker = await window.electronAPI?.openAudioFilePicker?.();
if (!picker?.success || !picker.path) return;
const label = picker.name || picker.path.split(/[\\/]/).pop() || "Audio";
const asset = await importAudioAsset(picker.path, label);
// `importAudioAsset` selects the new track in the store, but the region/clip
// selections are hook-local state it can't touch — clear them here so an import
// doesn't leave a stale annotation/clip selected alongside the new track (the same
// exclusivity `addAudioTrack` keeps). Only on success: a failed import changes nothing.
if (asset) {
setSelection(null);
setMultiSelection([]);
setClipSelection(null);
}
} catch (err) {
toast.error(ts("audioTrack.importFailed"), {
description: err instanceof Error ? err.message : String(err),
});
}
}, [importAudioAsset, ts]);
const removeAudioTrack = useCallback(
async (trackId: string) => {
if (!document) return;
// Clear the inspector selection only AFTER the delete commits. A failed
// write leaves the track in the document, so it must keep its selection.
const ok = await saveDocument(removeAudioTrackInDocument(document, trackId), {
history: true,
});
if (ok && selectedAudioTrackId === trackId) setSelectedAudioTrackId(null);
},
[document, saveDocument, selectedAudioTrackId, setSelectedAudioTrackId],
);
// The commit for a lane drag or edge-resize: move the pill's whole span and
// re-ventilate it, so a track dragged across a cut becomes the right set of
// fragments in one write (one undo step). `offsetMs` is preserved as the
// track's own — `anchorAudioTrackFragments` re-derives each fragment's
// advance from the new geometry.
const placeAudioTrack = useCallback(
async (trackId: string, span: { startMs: number; endMs: number; offsetMs?: number }) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
// The door replaces the whole group, so the survivors no longer need naming here.
const [pill] = collapseTracksToPills(
doc.audioTracks.filter((t) => trackGroupId(t) === trackId),
);
if (!pill) return;
const moved = {
...pill,
startMs: Math.max(0, Math.round(span.startMs)),
endMs: Math.max(Math.round(span.startMs) + 1, Math.round(span.endMs)),
// A left-edge drag is a trim IN: the head moves right and the same
// amount is skipped in the source, so the audio under the pill stays
// put instead of sliding with it. Omitted by a plain move, which
// keeps the offset it already had.
offsetMs:
span.offsetMs === undefined ? pill.offsetMs : Math.max(0, Math.round(span.offsetMs)),
};
// A resize stops the dragged edge at the neighbour; a move keeps the take's
// duration and parks it against the wall. Cropping a take because it was
// dragged somewhere crowded would lose audio the user never asked to lose.
const next = placeAudioTrackInDocument(
doc,
moved,
() => createId("audio"),
span.offsetMs === undefined ? "move" : "resize",
);
if (next === doc) return;
await saveDocument(next, { history: true });
},
[saveDocument],
);
// Payload edits hit every fragment of the track — the halves of a split take
// must not disagree about gain, mute or loop.
const updateAudioTrack = useCallback(
async (
trackId: string,
patch: Partial<
Pick<AxcutAudioTrack, "gainDb" | "muted" | "loop" | "fadeInMs" | "fadeOutMs" | "offsetMs">
>,
) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
await saveDocument(patchAudioTrack(doc, trackId, patch), { history: true });
},
[saveDocument],
);
// Turning loop ON fills the rest of the programme with the track.
//
// Looping only means anything when the span EXCEEDS the source, so a toggle
// that changed nothing else did nothing at all — the user had to know to then
// drag the pill's right edge out, which is not a thing anyone guesses. Filling
// is what "loop" is for, it is one undo away, and the edge still trims it back
// to any length. Turning loop OFF deliberately leaves the span alone: shrinking
// it would throw away a length the user may have set by hand.
const setAudioTrackLoop = useCallback(
async (trackId: string, loop: boolean) => {
const doc = useProjectStore.getState().document;
if (!doc) return;
const fragments = doc.audioTracks.filter((t) => trackGroupId(t) === trackId);
const [pill] = collapseTracksToPills(fragments);
if (!pill) return;
// Refused on a voiceover. `anchorAudioTrackFragments` does not advance `offsetMs`
// across a looping track's fragments, so its words map to raw moments they do not
// occupy — the transcript lane drops it, and a cut authored from it would land in
// the wrong place. Music loops; narration does not (issue #560).
if (loop && pill.kind === "voiceover") return;
const programmeEndMs = Math.round(
doc.timeline.clips.reduce((max, c) => Math.max(max, c.timelineEndSec), 0) * 1000,
);
// One write, so the fill and the flag are a single undo step.
const patched = patchAudioTrack(doc, trackId, { loop });
if (!loop || programmeEndMs <= pill.endMs) {
await saveDocument(patched, { history: true });
return;
}
// The fill stops at the next pill of its own kind, not at the programme end: a
// bed filling the timeline must not swallow a second bed that comes after it.
const filled = placeAudioTrackInDocument(
patched,
{ ...pill, loop, endMs: programmeEndMs },
() => createId("audio"),
"resize",
);
await saveDocument(filled === patched ? patched : filled, { history: true });
},
[saveDocument],
);
const setAudioTrackGain = useCallback(
async (trackId: string, gainDb: number) => {
await updateAudioTrack(trackId, { gainDb });
},
[updateAudioTrack],
);
return {
zoomRegions: document?.zoomRanges ?? [],
trimRanges: document?.timeline.trimRanges ?? [],
audioTracks: document?.audioTracks ?? [],
// The pauses added words created. The ruler counts them; nothing else in the
// timeline store writes them (see `document/transcript.ts`).
annotationRegions: (document?.annotations ?? []) as unknown as AnnotationRegion[],
speedRegions,
cameraFullscreenRegions,
shaderEffectRanges,
shaderEffects,
layoutSegments,
addLayoutChange,
setLayoutPreset,
moveLayoutBoundary,
clips: document?.timeline.clips ?? [],
assets: document?.assets ?? [],
// The timeline marks where the user has ADDED words — text with no audio behind it.
// Read straight off the transcript: the word is the only record of an insert, and a
// mark derived from it can never disagree with the pane that shows the same word.
transcripts: document?.transcripts ?? [],
hasDoc,
selection,
multiSelection,
clipSelection,
addZoom,
addZoomsBulk,
addTrim,
addAnnotation,
addSpeed,
addCameraFullscreen,
removeRegion,
removeRegions,
hasEditRegions,
clearTimeline,
addAudioTrack,
addAudio,
removeAudioTrack,
updateAudioTrack,
setAudioTrackLoop,
placeAudioTrack,
setAudioTrackGain,
selectedAudioTrackId,
selectAudioTrack,
selectRegion,
clearSelection,
applyClipEdit,
insertClipAt,
moveClip,
duplicateClip,
removeClip,
selectClip,
updateTrim,
setTrimEntries,
updateZoomSpan,
updateZoomFocusLive,
commitZoomFocus,
updateZoomDepth,
updateZoomCustomScale,
updateZoomRotation,
updateZoomFocusMode,
updateZoomHideCursor,
updateAnnotationSpan,
updateAnnotationLive,
commitAnnotationChange,
updateSpeedSpan,
updateSpeedValue,
updateCameraFullscreenSpan,
updateShaderEffectSpan,
updateShaderEffect,
updateShaderEffectLive,
commitShaderEffectChange,
// T19 — drives the preview video during trim-edge resize.
setCurrentTime: useProjectStore((s) => s.setCurrentTime),
};
}