{
+ it('uses the registered shared media URL instead of a page-owned throwaway blob URL', () => {
+ const source = readFileSync(new URL('./audio-meter-panel.tsx', import.meta.url), 'utf8')
+
+ expect(source).toContain(
+ "import { resolveMediaUrl } from '@/features/editor/deps/media-library'",
+ )
+ expect(source).toContain('resolveMediaUrl(mediaId)')
+ expect(source).not.toContain('.getMediaBlobUrl(mediaId)')
+ expect(source).not.toContain('URL.revokeObjectURL(blobUrl)')
+ })
+})
diff --git a/src/features/editor/components/editor.test.tsx b/src/features/editor/components/editor.test.tsx
index 11bf87910..b3c35a122 100644
--- a/src/features/editor/components/editor.test.tsx
+++ b/src/features/editor/components/editor.test.tsx
@@ -1,5 +1,5 @@
import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
-import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
import type { ReactNode } from 'react'
const mocks = vi.hoisted(() => ({
@@ -30,6 +30,9 @@ const mocks = vi.hoisted(() => ({
initTransitionChainSubscription: vi.fn(() => vi.fn()),
createProjectUpgradeBackup: vi.fn(),
resizablePanelGroup: vi.fn(),
+ editorWidth: 1440,
+ setLeftSidebarOpen: vi.fn(),
+ setRightSidebarOpen: vi.fn(),
}))
vi.mock('@tanstack/react-router', () => ({
@@ -69,15 +72,21 @@ vi.mock('@/app/error-boundary', () => ({
}))
vi.mock('./toolbar', () => ({
- Toolbar: () =>
,
+ Toolbar: ({ compact }: { compact?: boolean }) => (
+
+ ),
}))
vi.mock('./media-sidebar', () => ({
- MediaSidebar: () =>
,
+ MediaSidebar: ({ mobileDrawer }: { mobileDrawer?: boolean }) => (
+
+ ),
}))
vi.mock('./properties-sidebar', () => ({
- PropertiesSidebar: () =>
,
+ PropertiesSidebar: ({ mobileDrawer }: { mobileDrawer?: boolean }) => (
+
+ ),
}))
vi.mock('./preview-area', () => ({
@@ -106,11 +115,17 @@ vi.mock('./interaction-lock-region', () => ({
}))
vi.mock('./audio-meter-panel', () => ({
- AudioMeterPanel: () =>
,
+ AudioMeterPanel: ({ mobileDrawer }: { mobileDrawer?: boolean }) => (
+
+ ),
}))
vi.mock('@/features/editor/deps/timeline-ui', () => ({
- importTimeline: vi.fn().mockResolvedValue({ Timeline: () =>
}),
+ importTimeline: vi.fn().mockResolvedValue({
+ Timeline: ({ compact }: { compact?: boolean }) => (
+
+ ),
+ }),
importBentoLayoutDialog: vi.fn().mockResolvedValue({ BentoLayoutDialog: () => null }),
importFillerRemovalDialog: vi.fn().mockResolvedValue({ FillerRemovalDialog: () => null }),
importReverseConformDialog: vi.fn().mockResolvedValue({ ReverseConformDialog: () => null }),
@@ -149,6 +164,7 @@ vi.mock('../hooks/use-auto-save', () => ({
}))
vi.mock('@/features/editor/deps/timeline-hooks', () => ({
+ useHostTimelineShortcuts: vi.fn(),
useTimelineShortcuts: vi.fn(),
useTransitionBreakageNotifications: vi.fn(),
}))
@@ -234,6 +250,9 @@ vi.mock('@/shared/state/editor', () => ({
propertiesFullColumn: boolean
mediaFullColumn: boolean
workspace: string
+ sourcePreviewMediaId: string | null
+ setLeftSidebarOpen: typeof mocks.setLeftSidebarOpen
+ setRightSidebarOpen: typeof mocks.setRightSidebarOpen
}) => unknown,
) =>
selector({
@@ -241,6 +260,9 @@ vi.mock('@/shared/state/editor', () => ({
propertiesFullColumn: mocks.editorState.propertiesFullColumn,
mediaFullColumn: mocks.editorState.mediaFullColumn,
workspace: mocks.editorState.workspace,
+ sourcePreviewMediaId: null,
+ setLeftSidebarOpen: mocks.setLeftSidebarOpen,
+ setRightSidebarOpen: mocks.setRightSidebarOpen,
}),
}))
@@ -516,3 +538,135 @@ describe('editor shell height ownership', () => {
expect(standalone).toContainElement(screen.getByRole('application'))
})
})
+
+describe('editor responsive shell', () => {
+ const project = { id: 'project-1', name: 'Project', width: 1920, height: 1080, fps: 30 }
+ const migration = { storedSchemaVersion: 9, currentSchemaVersion: 9, requiresUpgrade: false }
+
+ beforeAll(() => {
+ vi.stubGlobal('requestIdleCallback', (callback: IdleRequestCallback) => {
+ callback({ didTimeout: false, timeRemaining: () => 50 } as IdleDeadline)
+ return 1
+ })
+ vi.stubGlobal('cancelIdleCallback', vi.fn())
+ vi.stubGlobal(
+ 'ResizeObserver',
+ class ResizeObserverMock {
+ private readonly callback: ResizeObserverCallback
+
+ constructor(callback: ResizeObserverCallback) {
+ this.callback = callback
+ }
+
+ observe(target: Element) {
+ this.callback(
+ [
+ {
+ target,
+ contentRect: { width: mocks.editorWidth },
+ borderBoxSize: [{ inlineSize: mocks.editorWidth, blockSize: 844 }],
+ } as unknown as ResizeObserverEntry,
+ ],
+ this as unknown as ResizeObserver,
+ )
+ }
+
+ disconnect() {}
+ unobserve() {}
+ },
+ )
+ })
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ mocks.editorWidth = 1440
+ mocks.editorState.workspace = 'edit'
+ mocks.editorState.propertiesFullColumn = false
+ mocks.editorState.mediaFullColumn = false
+ mocks.loadTimeline.mockResolvedValue(undefined)
+ mocks.loadMediaItems.mockResolvedValue(undefined)
+ })
+
+ afterEach(() => cleanup())
+
+ it('starts 390px standalone with core surfaces visible and persisted desktop panels untouched', async () => {
+ mocks.editorWidth = 390
+
+ render(
)
+
+ const shell = screen.getByRole('application')
+ await waitFor(() => expect(shell).toHaveAttribute('data-editor-layout', 'mobile'))
+ expect(screen.getByTestId('toolbar')).toHaveAttribute('data-compact', 'true')
+ expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'true')
+ expect(screen.queryByTestId('media-sidebar')).not.toBeInTheDocument()
+ expect(screen.queryByTestId('properties-sidebar')).not.toBeInTheDocument()
+ expect(screen.queryByTestId('audio-meter-panel')).not.toBeInTheDocument()
+ expect(mocks.setLeftSidebarOpen).not.toHaveBeenCalled()
+ expect(mocks.setRightSidebarOpen).not.toHaveBeenCalled()
+ expect(mocks.syncSidebarLayout).not.toHaveBeenCalled()
+ })
+
+ it('opens each 390px panel as a focus-restoring drawer and closes it with Escape', async () => {
+ mocks.editorWidth = 390
+ render(
)
+ await waitFor(() =>
+ expect(screen.getByRole('application')).toHaveAttribute('data-editor-layout', 'mobile'),
+ )
+
+ for (const name of ['Media', 'Properties', 'Meters']) {
+ const trigger = screen.getByRole('button', { name })
+ trigger.focus()
+ fireEvent.click(trigger)
+
+ const drawer = await screen.findByRole('dialog', { name })
+ expect(drawer).toBeInTheDocument()
+ expect(drawer).toContainElement(document.activeElement as HTMLElement)
+ const expectedTestId =
+ name === 'Media'
+ ? 'media-sidebar'
+ : name === 'Properties'
+ ? 'properties-sidebar'
+ : 'audio-meter-panel'
+ expect(screen.getByTestId(expectedTestId)).toHaveAttribute('data-mobile-drawer', 'true')
+
+ fireEvent.keyDown(document, { key: 'Escape' })
+ await waitFor(() => expect(screen.queryByRole('dialog', { name })).not.toBeInTheDocument())
+ await waitFor(() => expect(trigger).toHaveFocus())
+ }
+ })
+
+ it('uses the same 390px layout inside a definite-height host surface', async () => {
+ mocks.editorWidth = 390
+ const hostRuntime = { mountStores: vi.fn(), unmountStores: vi.fn() }
+
+ render(
+
+
+
,
+ )
+
+ await waitFor(() =>
+ expect(screen.getByRole('application')).toHaveAttribute('data-editor-layout', 'mobile'),
+ )
+ expect(screen.getByTestId('toolbar')).toHaveAttribute('data-compact', 'true')
+ expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'true')
+ expect(hostRuntime.mountStores).toHaveBeenCalledTimes(1)
+ })
+
+ it('preserves the existing 320/288/84 desktop layout branch at 1440px', async () => {
+ render(
)
+
+ const shell = screen.getByRole('application')
+ await waitFor(() => expect(shell).toHaveAttribute('data-editor-layout', 'desktop'))
+ expect(screen.getByTestId('toolbar')).toHaveAttribute('data-compact', 'false')
+ expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'false')
+ expect(screen.getByTestId('media-sidebar')).toHaveAttribute('data-mobile-drawer', 'false')
+ expect(screen.getByTestId('properties-sidebar')).toHaveAttribute('data-mobile-drawer', 'false')
+ expect(screen.getByTestId('audio-meter-panel')).toHaveAttribute('data-mobile-drawer', 'false')
+ })
+})
diff --git a/src/features/editor/components/editor.tsx b/src/features/editor/components/editor.tsx
index 22bd989ac..bf4924977 100644
--- a/src/features/editor/components/editor.tsx
+++ b/src/features/editor/components/editor.tsx
@@ -13,6 +13,12 @@ import { PreviewArea } from './preview-area'
import { MotionPreviewArea, MotionTimelineDock } from './compose-workspace/compose-layout'
import { InteractionLockRegion } from './interaction-lock-region'
import { AudioMeterPanel } from './audio-meter-panel'
+import {
+ MobileEditorDrawer,
+ MobileEditorPanelBar,
+ type MobileEditorPanel,
+} from './mobile-editor-layout'
+import { MOBILE_EDITOR_MAX_WIDTH, useCompactEditorLayout } from '../hooks/use-compact-editor-layout'
import {
importTimeline,
importBentoLayoutDialog,
@@ -465,11 +471,17 @@ export const LoadedEditor = memo(function LoadedEditor({
const syncSidebarLayout = useEditorStore((s) => s.syncSidebarLayout)
const propertiesFullColumn = useEditorStore((s) => s.propertiesFullColumn)
const mediaFullColumn = useEditorStore((s) => s.mediaFullColumn)
+ const sourcePreviewMediaId = useEditorStore((s) => s.sourcePreviewMediaId)
const workspace = useEditorStore((s) => s.workspace)
const isMaskEditingActive = useMaskEditorStore((s) => s.isEditing)
const hasRefreshedMigrationStateRef = useRef(false)
const localRefreshMigrationRef = useRef<(() => Promise
) | null>(null)
const timelinePanelRef = useRef(null)
+ const editorRootRef = useRef(null)
+ const compact = useCompactEditorLayout(editorRootRef)
+ const [mobilePanel, setMobilePanel] = useState(null)
+ const mobilePanelTriggerRef = useRef(null)
+ const previousSourcePreviewMediaIdRef = useRef(sourcePreviewMediaId)
const previousWorkspaceRef = useRef(workspace)
// Guard against concurrent saves (e.g., spamming Ctrl+S)
@@ -620,8 +632,34 @@ export const LoadedEditor = memo(function LoadedEditor({
])
useEffect(() => {
+ const measuredWidth = editorRootRef.current?.getBoundingClientRect().width
+ if (compact || (measuredWidth !== undefined && measuredWidth <= MOBILE_EDITOR_MAX_WIDTH)) return
syncSidebarLayout(editorLayout)
- }, [editorLayout, syncSidebarLayout])
+ }, [compact, editorLayout, syncSidebarLayout])
+
+ useEffect(() => {
+ const previousSource = previousSourcePreviewMediaIdRef.current
+ previousSourcePreviewMediaIdRef.current = sourcePreviewMediaId
+ if (compact && sourcePreviewMediaId && sourcePreviewMediaId !== previousSource) {
+ setMobilePanel('source')
+ } else if (!sourcePreviewMediaId && mobilePanel === 'source') {
+ setMobilePanel(null)
+ }
+ }, [compact, mobilePanel, sourcePreviewMediaId])
+
+ useEffect(() => {
+ if (!compact) setMobilePanel(null)
+ }, [compact])
+
+ const openMobilePanel = useCallback((panel: MobileEditorPanel) => {
+ mobilePanelTriggerRef.current =
+ document.activeElement instanceof HTMLElement ? document.activeElement : null
+ setMobilePanel(panel)
+ }, [])
+
+ const closeMobilePanel = useCallback(() => {
+ setMobilePanel(null)
+ }, [])
// Apply the per-workspace timeline split when switching workspaces:
// snapshot the outgoing workspace's split, then restore the incoming
@@ -751,14 +789,16 @@ export const LoadedEditor = memo(function LoadedEditor({
return (
{!hostRuntime &&
}
{!hostRuntime &&
}
@@ -778,13 +818,21 @@ export const LoadedEditor = memo(function LoadedEditor({
onExportBundle={hostRuntime ? undefined : handleExportBundle}
onOpenRenderQueue={hostRuntime ? undefined : handleOpenRenderQueue}
renderQueueCount={hostRuntime ? 0 : renderQueueActiveCount}
+ compact={compact}
/>
+ {compact && (
+
+ )}
+
{/* Main Layout: Full-height sidebar + vertical split */}
{/* Left Sidebar - Media Library (full column mode) */}
- {mediaFullColumn && !hidesDefaultSidebars && (
+ {!compact && mediaFullColumn && !hidesDefaultSidebars && (
@@ -797,7 +845,7 @@ export const LoadedEditor = memo(function LoadedEditor({
@@ -828,7 +876,7 @@ export const LoadedEditor = memo(function LoadedEditor({
>
{/* Left Sidebar - Media Library (inline with preview) */}
- {!mediaFullColumn && (
+ {!compact && !mediaFullColumn && (
@@ -841,12 +889,12 @@ export const LoadedEditor = memo(function LoadedEditor({
{isMotionWorkspace ? (
) : (
-
+
)}
{/* Right Sidebar - Properties (inline with preview) */}
- {!propertiesFullColumn && (
+ {!compact && !propertiesFullColumn && (
@@ -876,11 +924,11 @@ export const LoadedEditor = memo(function LoadedEditor({
) : (
-
+
)}
@@ -889,7 +937,7 @@ export const LoadedEditor = memo(function LoadedEditor({
)}
{/* Right Sidebar - Properties (full column mode) */}
- {propertiesFullColumn && !hidesDefaultSidebars && (
+ {!compact && propertiesFullColumn && !hidesDefaultSidebars && (
@@ -898,6 +946,20 @@ export const LoadedEditor = memo(function LoadedEditor({
)}
+ {compact && (
+
{
+ useEditorStore.getState().setSourcePreviewMediaId(null)
+ closeMobilePanel()
+ }}
+ />
+ )}
+
{!hostRuntime && (
{/* Export Dialog */}
diff --git a/src/features/editor/components/media-sidebar.tsx b/src/features/editor/components/media-sidebar.tsx
index 5d57f3ae8..edd8ce02b 100644
--- a/src/features/editor/components/media-sidebar.tsx
+++ b/src/features/editor/components/media-sidebar.tsx
@@ -52,6 +52,7 @@ import {
} from '@/features/editor/deps/timeline-utils'
import { addAdjustmentLayer } from '../utils/add-adjustment-layer'
import type { TextItem, ShapeItem, ShapeType } from '@/types/timeline'
+import type { EditorSidebarTab } from '@/config/editor-workspaces'
import { useMaskEditorStore } from '@/features/editor/deps/preview'
import type { VisualEffect, GpuEffect } from '@/types/effects'
import { EFFECT_PRESETS } from '@/types/effects'
@@ -288,7 +289,127 @@ const TEXT_TEMPLATE_GROUPS: ReadonlyArray<{
const DEFAULT_TEXT_TEMPLATE_LABEL = 'Text'
const ADD_TEXT_TEMPLATE_LABEL = 'Add Text'
-export const MediaSidebar = memo(function MediaSidebar() {
+interface MediaSidebarProps {
+ mobileDrawer?: boolean
+ onRequestClose?: () => void
+}
+
+function resolveMediaSidebarPresentation({
+ mobileDrawer,
+ leftSidebarOpen,
+ sidebarWidth,
+ drawerWidth,
+ onRequestClose,
+ toggleLeftSidebar,
+}: {
+ mobileDrawer: boolean
+ leftSidebarOpen: boolean
+ sidebarWidth: number
+ drawerWidth: number
+ onRequestClose?: () => void
+ toggleLeftSidebar: () => void
+}) {
+ if (mobileDrawer) {
+ return {
+ panelOpen: true,
+ panelWidth: drawerWidth,
+ mode: 'drawer' as const,
+ collapsePanel: onRequestClose ?? toggleLeftSidebar,
+ }
+ }
+ return {
+ panelOpen: leftSidebarOpen,
+ panelWidth: sidebarWidth,
+ mode: 'inline' as const,
+ collapsePanel: toggleLeftSidebar,
+ }
+}
+
+function selectMediaSidebarCategory({
+ id,
+ mobileDrawer,
+ activeTab,
+ leftSidebarOpen,
+ setActiveTab,
+ toggleLeftSidebar,
+ triggerPreviews,
+}: {
+ id: EditorSidebarTab
+ mobileDrawer: boolean
+ activeTab: EditorSidebarTab
+ leftSidebarOpen: boolean
+ setActiveTab: (tab: EditorSidebarTab) => void
+ toggleLeftSidebar: () => void
+ triggerPreviews: () => void
+}) {
+ if (mobileDrawer) {
+ setActiveTab(id)
+ if (id === 'effects') triggerPreviews()
+ return
+ }
+ if (activeTab === id && leftSidebarOpen) {
+ toggleLeftSidebar()
+ return
+ }
+ setActiveTab(id)
+ if (!leftSidebarOpen) toggleLeftSidebar()
+ if (id === 'effects') triggerPreviews()
+}
+
+function MediaSidebarDockButton({
+ mobileDrawer,
+ mediaFullColumn,
+ toggleMediaFullColumn,
+}: {
+ mobileDrawer: boolean
+ mediaFullColumn: boolean
+ toggleMediaFullColumn: () => void
+}) {
+ const { t } = useTranslation()
+ if (mobileDrawer) return null
+ const label = mediaFullColumn
+ ? t('editor.propertiesSidebar.dockToPreview')
+ : t('editor.propertiesSidebar.expandFullColumn')
+ return (
+
+ )
+}
+
+function MediaSidebarResizeHandle({
+ visible,
+ onMouseDown,
+}: {
+ visible: boolean
+ onMouseDown: (event: React.MouseEvent) => void
+}) {
+ if (!visible) return null
+ return (
+
+ )
+}
+
+export const MediaSidebar = memo(function MediaSidebar({
+ mobileDrawer = false,
+ onRequestClose,
+}: MediaSidebarProps) {
const { t } = useTranslation()
const hostMode = useEditorHostMode()
const { host } = useEditorHostContext()
@@ -306,6 +427,14 @@ export const MediaSidebar = memo(function MediaSidebar() {
const sidebarWidth = useEditorStore((s) => s.sidebarWidth)
const setSidebarWidth = useEditorStore((s) => s.setSidebarWidth)
const prefersReducedMotion = useReducedMotion()
+ const { panelOpen, panelWidth, mode, collapsePanel } = resolveMediaSidebarPresentation({
+ mobileDrawer,
+ leftSidebarOpen,
+ sidebarWidth,
+ drawerWidth: editorLayout.leftSidebarDefaultWidth,
+ onRequestClose,
+ toggleLeftSidebar,
+ })
const [aiTabActivated, setAiTabActivated] = useState(activeTab === 'ai')
// The Lottie panel hits an external API on mount, so keep it unmounted until
@@ -322,10 +451,10 @@ export const MediaSidebar = memo(function MediaSidebar() {
// order without yanking focus mid-animation; clear it immediately on open so
// the panel is interactive as it slides in. Mirrors the right sidebar's
// contentVisible/onAnimationComplete handoff.
- const [contentInert, setContentInert] = useState(!leftSidebarOpen)
+ const [contentInert, setContentInert] = useState(!panelOpen)
useEffect(() => {
- if (leftSidebarOpen) setContentInert(false)
- }, [leftSidebarOpen])
+ if (panelOpen) setContentInert(false)
+ }, [panelOpen])
// NOTE: the heavy media-library subtree is deliberately NOT gated behind
// Activity `hidden` when collapsed. React defers the hidden→visible reveal, so
@@ -608,7 +737,7 @@ export const MediaSidebar = memo(function MediaSidebar() {
}, [])
return (
-
+
{/* Vertical Category Bar */}
{/* Resize Handle */}
- {leftSidebarOpen && (
-
- )}
+
)
diff --git a/src/features/editor/components/mobile-editor-layout.tsx b/src/features/editor/components/mobile-editor-layout.tsx
new file mode 100644
index 000000000..6beda7098
--- /dev/null
+++ b/src/features/editor/components/mobile-editor-layout.tsx
@@ -0,0 +1,123 @@
+import { AudioLines, FolderOpen, MonitorPlay, SlidersHorizontal } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { Button } from '@/components/ui/button'
+import { Dialog, DialogContent, DialogTitle } from '@/components/ui/dialog'
+import { MediaSidebar } from './media-sidebar'
+import { PropertiesSidebar } from './properties-sidebar'
+import { AudioMeterPanel } from './audio-meter-panel'
+import { MobileSourceMonitor } from './preview-area'
+
+export type MobileEditorPanel = 'media' | 'properties' | 'source' | 'meters'
+
+interface MobileEditorPanelBarProps {
+ sourceAvailable: boolean
+ onOpen(panel: MobileEditorPanel): void
+}
+
+export function MobileEditorPanelBar({ sourceAvailable, onOpen }: MobileEditorPanelBarProps) {
+ const { t } = useTranslation()
+ const items = [
+ {
+ id: 'media' as const,
+ label: t('editor.mediaSidebar.media'),
+ icon: FolderOpen,
+ },
+ {
+ id: 'properties' as const,
+ label: t('editor.propertiesSidebar.title'),
+ icon: SlidersHorizontal,
+ },
+ ...(sourceAvailable
+ ? [
+ {
+ id: 'source' as const,
+ label: t('media.info.source'),
+ icon: MonitorPlay,
+ },
+ ]
+ : []),
+ {
+ id: 'meters' as const,
+ label: t('editor.audioMeters.meters'),
+ icon: AudioLines,
+ },
+ ]
+
+ return (
+
+ {items.map(({ id, label, icon: Icon }) => (
+
+ ))}
+
+ )
+}
+
+interface MobileEditorDrawerProps {
+ panel: MobileEditorPanel | null
+ container: HTMLElement | null
+ sourceMediaId: string | null
+ restoreFocusTo: HTMLElement | null
+ onClose(): void
+ onCloseSource(): void
+}
+
+export function MobileEditorDrawer({
+ panel,
+ container,
+ sourceMediaId,
+ restoreFocusTo,
+ onClose,
+ onCloseSource,
+}: MobileEditorDrawerProps) {
+ const { t } = useTranslation()
+ const titles: Record
= {
+ media: t('editor.mediaSidebar.media'),
+ properties: t('editor.propertiesSidebar.title'),
+ source: t('media.info.source'),
+ meters: t('editor.audioMeters.meters'),
+ }
+ const title = panel ? titles[panel] : ''
+
+ return (
+
+ )
+}
diff --git a/src/features/editor/components/preview-area.tsx b/src/features/editor/components/preview-area.tsx
index b9eb0587f..8c822d785 100644
--- a/src/features/editor/components/preview-area.tsx
+++ b/src/features/editor/components/preview-area.tsx
@@ -32,6 +32,7 @@ interface PreviewAreaProps {
}
durationInFrames?: number
preferProjectStoreMetadata?: boolean
+ compact?: boolean
}
type PreviewChrome = 'edit' | 'color'
@@ -181,6 +182,7 @@ export const PreviewArea = memo(function PreviewArea({
project,
durationInFrames,
preferProjectStoreMetadata = true,
+ compact = false,
}: PreviewAreaProps) {
const { t } = useTranslation()
const previewContainerRef = useRef(null)
@@ -507,7 +509,8 @@ export const PreviewArea = memo(function PreviewArea({
}
}, [])
- const hasSidePanels = !!sourcePreviewMediaId || scopesPanelOpen
+ const showInlineSourceMonitor = !!sourcePreviewMediaId && !compact
+ const hasSidePanels = showInlineSourceMonitor || scopesPanelOpen
const previewChrome: PreviewChrome = workspace === 'color' ? 'color' : 'edit'
const programPanelPercent = Math.max(
0,
@@ -521,7 +524,7 @@ export const PreviewArea = memo(function PreviewArea({
role="region"
aria-label="Preview area"
>
- {sourcePreviewMediaId && (
+ {showInlineSourceMonitor && sourcePreviewMediaId && (
<>
)
})
+
+export function MobileSourceMonitor({
+ mediaId,
+ onClose,
+}: {
+ mediaId: string
+ onClose: () => void
+}) {
+ return (
+
+
+
+
+
+ )
+}
diff --git a/src/features/editor/components/properties-sidebar/index.tsx b/src/features/editor/components/properties-sidebar/index.tsx
index 116a2d7e5..3de484224 100644
--- a/src/features/editor/components/properties-sidebar/index.tsx
+++ b/src/features/editor/components/properties-sidebar/index.tsx
@@ -147,7 +147,15 @@ function getClipHeader(items: HeaderItem[]) {
* Shows TransitionPanel when a transition is selected, MarkerPanel when a marker
* is selected, ClipPanel when clips are selected, CanvasPanel otherwise.
*/
-export const PropertiesSidebar = memo(function PropertiesSidebar() {
+interface PropertiesSidebarProps {
+ mobileDrawer?: boolean
+ onRequestClose?: () => void
+}
+
+export const PropertiesSidebar = memo(function PropertiesSidebar({
+ mobileDrawer = false,
+ onRequestClose,
+}: PropertiesSidebarProps) {
const { t } = useTranslation()
const hostMode = useEditorHostMode()
const editorDensity = useSettingsStore((s) => s.editorDensity)
@@ -161,6 +169,8 @@ export const PropertiesSidebar = memo(function PropertiesSidebar() {
const togglePropertiesFullColumn = useEditorStore((s) => s.togglePropertiesFullColumn)
const workspace = useEditorStore((s) => s.workspace)
const clipInspectorTab = useEditorStore((s) => s.clipInspectorTab)
+ const panelOpen = mobileDrawer || rightSidebarOpen
+ const panelWidth = mobileDrawer ? editorLayout.rightSidebarDefaultWidth : rightSidebarWidth
const selectedItemIds = useSelectionStore((s) => s.selectedItemIds)
const selectedMarkerId = useSelectionStore((s) => s.selectedMarkerId)
const selectedTransitionId = useSelectionStore((s) => s.selectedTransitionId)
@@ -218,10 +228,10 @@ export const PropertiesSidebar = memo(function PropertiesSidebar() {
// Keep the panel content mounted + visible while the collapse animation plays
// so it slides out smoothly instead of blinking away. Only switch Activity to
// `hidden` (the perf win) once the close animation has actually settled.
- const [contentVisible, setContentVisible] = useState(rightSidebarOpen)
+ const [contentVisible, setContentVisible] = useState(panelOpen)
useEffect(() => {
- if (rightSidebarOpen) setContentVisible(true)
- }, [rightSidebarOpen])
+ if (panelOpen) setContentVisible(true)
+ }, [panelOpen])
// Resize handle logic
const isResizingRef = useRef(false)
@@ -278,53 +288,56 @@ export const PropertiesSidebar = memo(function PropertiesSidebar() {
tracks the pointer instead of easing behind it. */}
{
- if (!rightSidebarOpen) setContentVisible(false)
+ if (!panelOpen) setContentVisible(false)
}}
>
{/* Use Activity for React 19 performance optimization */}
-
+
{/* Sidebar Header */}
-
+ {!mobileDrawer && (
+
+ )}
{headerLabel}
@@ -345,7 +358,7 @@ export const PropertiesSidebar = memo(function PropertiesSidebar() {
width: EDITOR_LAYOUT_CSS_VALUES.sidebarHeaderButtonSize,
height: EDITOR_LAYOUT_CSS_VALUES.sidebarHeaderButtonSize,
}}
- onClick={toggleRightSidebar}
+ onClick={mobileDrawer ? onRequestClose : toggleRightSidebar}
aria-label={t('editor.mediaSidebar.collapsePanel')}
>
@@ -401,7 +414,7 @@ export const PropertiesSidebar = memo(function PropertiesSidebar() {
{/* Resize Handle */}
- {rightSidebarOpen && (
+ {rightSidebarOpen && !mobileDrawer && (
0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`
}
+function projectDurationSeconds(maxItemEndFrame: number, fps: number): number {
+ return fps > 0 ? maxItemEndFrame / fps : 0
+}
+
+function LocalInferenceToolbarStatus({ hostMode }: { hostMode: boolean }) {
+ return hostMode ? null :
+}
+
interface ToolbarProps {
projectId: string
project: {
@@ -76,6 +86,208 @@ interface ToolbarProps {
onOpenRenderQueue?: () => void
/** Number of queued + rendering jobs, shown as a badge on the queue button. */
renderQueueCount?: number
+ compact?: boolean
+}
+
+interface MobileToolbarProps extends ToolbarProps {
+ hostMode: boolean
+ showUnsavedDialog: boolean
+ showShortcutsDialog: boolean
+ showSettingsDialog: boolean
+ showWhatsNewDialog: boolean
+ isSaveAnimating: boolean
+ saveAnimationKey: number
+ handleBackClick(): void
+ handleSave(): Promise
+ openWhatsNew(): void
+ setShowUnsavedDialog(open: boolean): void
+ setShowShortcutsDialog(open: boolean): void
+ setShowSettingsDialog(open: boolean): void
+ setShowWhatsNewDialog(open: boolean): void
+}
+
+// The compact toolbar keeps the four essential actions visible while gathering
+// host/local utility branches into one tested overflow surface. Its standalone
+// and host variants are covered by tests/browser/responsive-editor.spec.ts.
+// fallow-ignore-next-line complexity
+function MobileToolbar({
+ project,
+ onBack,
+ onSave,
+ onExport,
+ onExportBundle,
+ onOpenRenderQueue,
+ renderQueueCount = 0,
+ hostMode,
+ showUnsavedDialog,
+ showShortcutsDialog,
+ showSettingsDialog,
+ showWhatsNewDialog,
+ isSaveAnimating,
+ saveAnimationKey,
+ handleBackClick,
+ handleSave,
+ openWhatsNew,
+ setShowUnsavedDialog,
+ setShowShortcutsDialog,
+ setShowSettingsDialog,
+ setShowWhatsNewDialog,
+}: MobileToolbarProps) {
+ const { t } = useTranslation()
+
+ return (
+
+
+
+ {onSave && onBack && (
+
+ )}
+
+
+
+
+
+ {onSave && (
+
+ )}
+
+ {(onExport || onExportBundle) && (
+
+
+
+
+
+
+
+ {t('toolbar.exportVideo')}
+
+
+
+ {t('toolbar.downloadProjectZip')}
+
+
+
+ )}
+
+
+ {!hostMode && (
+
+ )}
+
+
+
+
+
+
+
+ {project.name}
+ {onOpenRenderQueue && (
+
+
+ {t('toolbar.renderQueue')}
+ {renderQueueCount > 0 && {renderQueueCount}}
+
+ )}
+
+
+ {t('toolbar.whatsNew')}
+
+ setShowSettingsDialog(true)} disabled={hostMode}>
+
+ {t('toolbar.settings')}
+
+ setShowShortcutsDialog(true)}>
+
+ {t('toolbar.keyboardShortcuts')}
+
+
+
+
+ User Guide
+
+
+
+
+
+ GitHub
+
+
+
+
+
+ Discord
+
+
+
+
+
+
+
+
- {!hostMode &&
}
+
diff --git a/src/features/editor/components/workspace-switcher.tsx b/src/features/editor/components/workspace-switcher.tsx
index ba388b9b7..93afdab82 100644
--- a/src/features/editor/components/workspace-switcher.tsx
+++ b/src/features/editor/components/workspace-switcher.tsx
@@ -22,7 +22,11 @@ const WORKSPACE_ITEMS: readonly {
* (scopes, inspector tab, sidebar tab, timeline split) without touching
* selection, playhead, or project state.
*/
-export const WorkspaceSwitcher = memo(function WorkspaceSwitcher() {
+export const WorkspaceSwitcher = memo(function WorkspaceSwitcher({
+ compact = false,
+}: {
+ compact?: boolean
+}) {
const { t } = useTranslation()
const workspace = useEditorStore((s) => s.workspace)
const setWorkspace = useEditorStore((s) => s.setWorkspace)
@@ -49,7 +53,8 @@ export const WorkspaceSwitcher = memo(function WorkspaceSwitcher() {
aria-selected={isActive}
onClick={() => setWorkspace(id)}
className={cn(
- 'flex h-7 items-center gap-1.5 rounded-[5px] px-3 text-xs font-medium transition-colors',
+ 'flex h-7 min-w-0 items-center gap-1 rounded-[5px] text-xs font-medium transition-colors',
+ compact ? 'px-1.5' : 'gap-1.5 px-3',
isActive
? 'bg-background text-foreground shadow-sm'
: 'text-muted-foreground hover:text-foreground',
diff --git a/src/features/editor/hooks/use-compact-editor-layout.ts b/src/features/editor/hooks/use-compact-editor-layout.ts
new file mode 100644
index 000000000..a8c611390
--- /dev/null
+++ b/src/features/editor/hooks/use-compact-editor-layout.ts
@@ -0,0 +1,29 @@
+import { useLayoutEffect, useState, type RefObject } from 'react'
+
+export const MOBILE_EDITOR_MAX_WIDTH = 767
+
+export function useCompactEditorLayout(rootRef: RefObject
): boolean {
+ const [compact, setCompact] = useState(
+ () => typeof window !== 'undefined' && window.innerWidth <= MOBILE_EDITOR_MAX_WIDTH,
+ )
+
+ useLayoutEffect(() => {
+ const root = rootRef.current
+ if (!root) return
+
+ const update = (width: number) => {
+ const nextCompact = width <= MOBILE_EDITOR_MAX_WIDTH
+ setCompact((current) => (current === nextCompact ? current : nextCompact))
+ }
+
+ update(root.getBoundingClientRect().width || root.clientWidth || window.innerWidth)
+ const observer = new ResizeObserver((entries) => {
+ const entry = entries[0]
+ if (entry) update(entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width)
+ })
+ observer.observe(root)
+ return () => observer.disconnect()
+ }, [rootRef])
+
+ return compact
+}
diff --git a/src/features/editor/hooks/use-editor-hotkeys.ts b/src/features/editor/hooks/use-editor-hotkeys.ts
index aeb6b5ad7..e84395c61 100644
--- a/src/features/editor/hooks/use-editor-hotkeys.ts
+++ b/src/features/editor/hooks/use-editor-hotkeys.ts
@@ -1,6 +1,5 @@
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
-import { useResolvedHotkeys } from '@/features/editor/deps/settings'
import { useEditorStore } from '@/shared/state/editor'
import { useSceneBrowserStore } from '@/features/editor/deps/scene-browser'
@@ -24,12 +23,11 @@ interface EditorHotkeyCallbacks {
* Uses react-hotkeys-hook with granular Zustand selectors
*/
export function useEditorHotkeys(callbacks: EditorHotkeyCallbacks = {}) {
- const hotkeys = useResolvedHotkeys()
const enableLocalUi = callbacks.enableLocalUi ?? true
// Save: Cmd/Ctrl+S
- useHotkeys(
- hotkeys.SAVE,
+ useCommandHotkey(
+ 'SAVE',
(event) => {
event.preventDefault()
if (callbacks.onSave) {
@@ -41,8 +39,8 @@ export function useEditorHotkeys(callbacks: EditorHotkeyCallbacks = {}) {
)
// Export: Cmd/Ctrl+Shift+E
- useHotkeys(
- hotkeys.EXPORT,
+ useCommandHotkey(
+ 'EXPORT',
(event) => {
event.preventDefault()
if (callbacks.onExport) {
@@ -56,8 +54,8 @@ export function useEditorHotkeys(callbacks: EditorHotkeyCallbacks = {}) {
// Open Scene Browser: Cmd/Ctrl+Shift+F — capture phase because the
// default browser binding is a no-op here but Chrome will still eat it
// if our listener is in bubbling phase.
- useHotkeys(
- hotkeys.OPEN_SCENE_BROWSER,
+ useCommandHotkey(
+ 'OPEN_SCENE_BROWSER',
(event) => {
if (!enableLocalUi) return
event.preventDefault()
@@ -69,8 +67,8 @@ export function useEditorHotkeys(callbacks: EditorHotkeyCallbacks = {}) {
// Workspace switching: Alt+1 (Edit), Alt+2 (Color), Alt+3 (Motion).
// WORKSPACE_ANIMATE retains its persisted command id for shortcut migration.
- useHotkeys(
- hotkeys.WORKSPACE_EDIT,
+ useCommandHotkey(
+ 'WORKSPACE_EDIT',
(event) => {
if (!enableLocalUi) return
event.preventDefault()
@@ -80,8 +78,8 @@ export function useEditorHotkeys(callbacks: EditorHotkeyCallbacks = {}) {
[enableLocalUi],
)
- useHotkeys(
- hotkeys.WORKSPACE_COLOR,
+ useCommandHotkey(
+ 'WORKSPACE_COLOR',
(event) => {
if (!enableLocalUi) return
event.preventDefault()
@@ -91,8 +89,8 @@ export function useEditorHotkeys(callbacks: EditorHotkeyCallbacks = {}) {
[enableLocalUi],
)
- useHotkeys(
- hotkeys.WORKSPACE_ANIMATE,
+ useCommandHotkey(
+ 'WORKSPACE_ANIMATE',
(event) => {
if (!enableLocalUi) return
event.preventDefault()
diff --git a/src/features/editor/host/contract.ts b/src/features/editor/host/contract.ts
index 4e16365d6..294dcc9aa 100644
--- a/src/features/editor/host/contract.ts
+++ b/src/features/editor/host/contract.ts
@@ -7,6 +7,7 @@ import type {
TimelineRevision,
} from '@/features/editor/codepress/contract'
import type { FreeCutFrameDocument } from '@/features/editor/codepress/document'
+import { sanitizeHotkeyOverrides, type HotkeyOverrideMap } from '@/config/hotkeys'
/**
* The browser surface is deliberately a port. It knows how to render and
@@ -328,6 +329,32 @@ export interface EditorHostNavigation {
back(): void
}
+export const HOST_SHORTCUTS_SCHEMA = 'freecut-host-shortcuts'
+export const HOST_SHORTCUTS_VERSION = 1
+
+/** Versioned shortcut payload shared by the host, UI, and agent settings surface. */
+export interface HostShortcutSettings {
+ schema: typeof HOST_SHORTCUTS_SCHEMA
+ version: typeof HOST_SHORTCUTS_VERSION
+ overrides: HotkeyOverrideMap
+}
+
+export interface EditorShortcutPort {
+ getSettings(): Promise | HostShortcutSettings
+ setSettings(settings: HostShortcutSettings): Promise | void
+ subscribe?(listener: (settings: HostShortcutSettings) => void): () => void
+}
+
+export function createHostShortcutSettings(
+ overrides: HotkeyOverrideMap = {},
+): HostShortcutSettings {
+ return {
+ schema: HOST_SHORTCUTS_SCHEMA,
+ version: HOST_SHORTCUTS_VERSION,
+ overrides: sanitizeHotkeyOverrides(overrides),
+ }
+}
+
export interface EditorHost {
readonly capabilities: EditorCapabilityMap
load(): Promise | EmbeddedEditorSnapshot
@@ -343,6 +370,8 @@ export interface EditorHost {
* the surface calls when it tears the runtime down.
*/
subscribe?(listener: (snapshot: EmbeddedEditorSnapshot) => void): () => void
+ /** Optional host/agent round-trip for user-configurable keyboard shortcuts. */
+ shortcuts?: EditorShortcutPort
/** Optional application-issued transcript read/preview boundary. */
transcript?: EditorTranscriptPort
navigation?: EditorHostNavigation
diff --git a/src/features/editor/host/editor-surface.tsx b/src/features/editor/host/editor-surface.tsx
index c078f9bfd..535eba118 100644
--- a/src/features/editor/host/editor-surface.tsx
+++ b/src/features/editor/host/editor-surface.tsx
@@ -15,6 +15,7 @@ import { EditorHostProvider } from './context-provider'
import { HostCaptionEditorProvider } from './caption-editor-context'
import { HostTranscriptEditorProvider } from './transcript-editor-context'
import { EmbeddedEditorHostRuntime } from './runtime'
+import { mountHostShortcutSettings } from './shortcut-settings'
import '@/index.css'
interface HostSurfaceState {
@@ -40,27 +41,53 @@ export function FreeCutEditorSurface({ host }: { host: EditorHost }) {
useEffect(() => {
let cancelled = false
let unsubscribe: (() => void) | undefined
+ let unmountShortcutSettings: (() => void) | undefined
+ const shortcutSettingsAbortController = new AbortController()
setState(null)
setError(null)
- void Promise.all([Promise.resolve(host.load()), i18nReady])
- .then(([snapshot]) => {
- if (cancelled) return
+
+ const initialize = async () => {
+ unmountShortcutSettings = await mountHostShortcutSettings(
+ host,
+ shortcutSettingsAbortController.signal,
+ )
+ if (cancelled) {
+ unmountShortcutSettings()
+ unmountShortcutSettings = undefined
+ return
+ }
+
+ const [snapshot] = await Promise.all([Promise.resolve(host.load()), i18nReady])
+ if (!cancelled) {
const runtime = new EmbeddedEditorHostRuntime(host, snapshot)
- // An out-of-band host revision enters through the same controller the
- // result of a submitted edit does, so the surface adopts it in place
- // rather than being remounted with a new `host`.
+ // Host-pushed snapshots and submitted edits share one authoritative
+ // controller, while shortcut settings retain their independent port.
unsubscribe = host.subscribe?.((next) =>
runtime.controller.replaceAuthoritativeSnapshot(next),
)
setState({ snapshot, runtime })
- })
+ }
+ }
+
+ void initialize()
+ .then(() => undefined)
.catch((caught) => {
- if (!cancelled) setError(caught instanceof Error ? caught : new Error(String(caught)))
+ unsubscribe?.()
+ unsubscribe = undefined
+ shortcutSettingsAbortController.abort()
+ unmountShortcutSettings?.()
+ unmountShortcutSettings = undefined
+ if (cancelled) return
+ setError(caught instanceof Error ? caught : new Error(String(caught)))
})
+
return () => {
cancelled = true
unsubscribe?.()
unsubscribe = undefined
+ shortcutSettingsAbortController.abort()
+ unmountShortcutSettings?.()
+ unmountShortcutSettings = undefined
}
}, [host])
diff --git a/src/features/editor/host/index.ts b/src/features/editor/host/index.ts
index 63835412b..55ddefa59 100644
--- a/src/features/editor/host/index.ts
+++ b/src/features/editor/host/index.ts
@@ -7,6 +7,8 @@ export type { EditorHostContextValue } from './context'
export type { EditorHostProviderProps } from './context-provider'
export {
DEFAULT_HOST_CAPABILITIES,
+ HOST_SHORTCUTS_SCHEMA,
+ HOST_SHORTCUTS_VERSION,
MAX_TRANSCRIPT_CURSOR_LENGTH,
MAX_TRANSCRIPT_COMMAND_TEXT_BYTES,
MAX_TRANSCRIPT_DURATION_US,
@@ -16,6 +18,7 @@ export {
MAX_TRANSCRIPT_SELECTIONS,
SUPPORTED_HOST_COMMANDS,
capabilityForCommand,
+ createHostShortcutSettings,
createLocalEditorHost,
isHostCapabilityEnabled,
} from './contract'
@@ -24,6 +27,7 @@ export type {
EditorCapabilityMap,
EditorHost,
EditorHostNavigation,
+ EditorShortcutPort,
EmbeddedEditorAsset,
EmbeddedEditorProject,
EmbeddedEditorSnapshot,
@@ -35,6 +39,7 @@ export type {
HostEditResult,
HostMediaKind,
HostNotice,
+ HostShortcutSettings,
HostTranscriptCommandAction,
HostTranscriptCommandPreview,
HostTranscriptCommandPreviewRequest,
diff --git a/src/features/editor/host/shortcut-settings.test.ts b/src/features/editor/host/shortcut-settings.test.ts
new file mode 100644
index 000000000..0db8de565
--- /dev/null
+++ b/src/features/editor/host/shortcut-settings.test.ts
@@ -0,0 +1,541 @@
+// @vitest-environment jsdom
+
+import { createElement } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { fireEvent, render, waitFor } from '@testing-library/react'
+import { useHotkeys } from 'react-hotkeys-hook'
+import { HOTKEY_OPTIONS } from '@/config/hotkeys'
+import { useResolvedHotkeys } from '@/features/editor/deps/settings'
+import { useSettingsStore } from '@/features/editor/deps/settings'
+import { useHostTimelineShortcuts } from '@/features/editor/deps/timeline-hooks'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { createHostShortcutSettings, type EditorHost, type HostShortcutSettings } from './contract'
+import { HOST_SHORTCUT_RETRY_DELAYS_MS, mountHostShortcutSettings } from './shortcut-settings'
+
+function HostShortcutHarness() {
+ useHostTimelineShortcuts()
+ return null
+}
+
+function ConflictingShortcutHarness({ onAddKeyframe }: { onAddKeyframe: () => void }) {
+ const hotkeys = useResolvedHotkeys()
+ useHotkeys(hotkeys.EDIT_KEYFRAME_ADD, onAddKeyframe, HOTKEY_OPTIONS, [onAddKeyframe])
+ useHostTimelineShortcuts()
+ return null
+}
+
+function createShortcutHost(initial: HostShortcutSettings) {
+ const listeners = new Set<(settings: HostShortcutSettings) => void>()
+ const setSettings = vi.fn()
+ const notify = vi.fn()
+ const host: EditorHost = {
+ capabilities: {},
+ load: vi.fn(() => {
+ throw new Error('not used')
+ }),
+ resolveMedia: vi.fn(() => null),
+ submitEdit: vi.fn(() => {
+ throw new Error('not used')
+ }),
+ shortcuts: {
+ getSettings: vi.fn(() => initial),
+ setSettings,
+ subscribe: (listener) => {
+ listeners.add(listener)
+ return () => listeners.delete(listener)
+ },
+ },
+ notify,
+ }
+
+ return {
+ host,
+ setSettings,
+ notify,
+ listenerCount: () => listeners.size,
+ emit: (settings: HostShortcutSettings) => {
+ for (const listener of listeners) listener(settings)
+ },
+ }
+}
+
+function createDeferred() {
+ let resolve!: (value: T | PromiseLike) => void
+ let reject!: (reason?: unknown) => void
+ const promise = new Promise((resolvePromise, rejectPromise) => {
+ resolve = resolvePromise
+ reject = rejectPromise
+ })
+ return { promise, resolve, reject }
+}
+
+function createRetryScheduler() {
+ let nextTimerId = 0
+ const timers = new Map void; delayMs: number }>()
+ return {
+ scheduler: {
+ setTimeout: (callback: () => void, delayMs: number) => {
+ const timerId = ++nextTimerId
+ timers.set(timerId, { callback, delayMs })
+ return timerId
+ },
+ clearTimeout: (timer: unknown) => timers.delete(timer as number),
+ },
+ pendingCount: () => timers.size,
+ pendingDelays: () => [...timers.values()].map((timer) => timer.delayMs),
+ runNext: async () => {
+ const entry = timers.entries().next().value as
+ | [number, { callback: () => void; delayMs: number }]
+ | undefined
+ if (!entry) throw new Error('No retry timer is pending')
+ timers.delete(entry[0])
+ entry[1].callback()
+ await Promise.resolve()
+ await Promise.resolve()
+ },
+ }
+}
+
+describe('host shortcut settings round trip', () => {
+ beforeEach(() => {
+ useSettingsStore.getState().resetHotkeys()
+ usePlaybackStore.setState({
+ isPlaying: false,
+ playbackRate: 1,
+ transportMode: 'normal',
+ })
+ })
+
+ afterEach(() => {
+ vi.useRealTimers()
+ })
+
+ it('hydrates host bindings, persists UI changes, and accepts agent updates', async () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({ PLAY_PAUSE: 'shift+space' })
+ const harness = createShortcutHost(
+ createHostShortcutSettings({
+ SHUTTLE_REVERSE: 'q',
+ SHUTTLE_PAUSE: 'w',
+ SHUTTLE_FORWARD: 'e',
+ }),
+ )
+
+ const unmount = await mountHostShortcutSettings(harness.host)
+
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({
+ SHUTTLE_REVERSE: 'q',
+ SHUTTLE_PAUSE: 'w',
+ SHUTTLE_FORWARD: 'e',
+ })
+
+ render(createElement(HostShortcutHarness))
+ fireEvent.keyDown(document, { key: 'e', code: 'KeyE' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ playbackRate: 1,
+ transportMode: 'shuttle',
+ })
+ fireEvent.keyDown(document, { key: 'w', code: 'KeyW' })
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+ fireEvent.keyDown(document, { key: 'q', code: 'KeyQ' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ playbackRate: -1,
+ transportMode: 'shuttle',
+ })
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+
+ await waitFor(() =>
+ expect(harness.setSettings).toHaveBeenLastCalledWith(
+ createHostShortcutSettings({
+ SHUTTLE_REVERSE: 'q',
+ SHUTTLE_PAUSE: 'x',
+ SHUTTLE_FORWARD: 'e',
+ }),
+ ),
+ )
+
+ harness.emit(
+ createHostShortcutSettings({
+ SHUTTLE_REVERSE: 'q',
+ SHUTTLE_PAUSE: 'w',
+ SHUTTLE_FORWARD: 'e',
+ }),
+ )
+
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({
+ SHUTTLE_REVERSE: 'q',
+ SHUTTLE_PAUSE: 'w',
+ SHUTTLE_FORWARD: 'e',
+ })
+ expect(harness.notify).not.toHaveBeenCalled()
+
+ unmount()
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({
+ PLAY_PAUSE: 'shift+space',
+ })
+ })
+
+ it('keeps late hydration from host A inert after host B replaces it', async () => {
+ let resolveA!: (settings: HostShortcutSettings) => void
+ const hostA = createShortcutHost(createHostShortcutSettings({ SHUTTLE_REVERSE: 'a' }))
+ hostA.host.shortcuts!.getSettings = vi.fn(
+ () => new Promise((resolve) => (resolveA = resolve)),
+ )
+ const mountA = mountHostShortcutSettings(hostA.host)
+
+ const hostB = createShortcutHost(createHostShortcutSettings({ SHUTTLE_REVERSE: 'b' }))
+ const unmountB = await mountHostShortcutSettings(hostB.host)
+ resolveA(createHostShortcutSettings({ SHUTTLE_REVERSE: 'a' }))
+ const unmountA = await mountA
+
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({ SHUTTLE_REVERSE: 'b' })
+ expect(hostA.listenerCount()).toBe(0)
+ unmountA()
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({ SHUTTLE_REVERSE: 'b' })
+ unmountB()
+ })
+
+ it('invalidates deferred host A when replacement B omits the optional shortcut port', async () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({ PLAY_PAUSE: 'shift+space' })
+ let resolveA!: (settings: HostShortcutSettings) => void
+ const hostA = createShortcutHost(createHostShortcutSettings({ SHUTTLE_REVERSE: 'a' }))
+ hostA.host.shortcuts!.getSettings = vi.fn(
+ () => new Promise((resolve) => (resolveA = resolve)),
+ )
+ const mountA = mountHostShortcutSettings(hostA.host)
+ const hostB = { ...createShortcutHost(createHostShortcutSettings({})).host }
+ delete hostB.shortcuts
+
+ const unmountB = await mountHostShortcutSettings(hostB)
+ resolveA(createHostShortcutSettings({ SHUTTLE_REVERSE: 'a' }))
+ const unmountA = await mountA
+
+ expect(hostA.listenerCount()).toBe(0)
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({
+ PLAY_PAUSE: 'shift+space',
+ })
+ unmountA()
+ unmountB()
+ })
+
+ it('cancels deferred hydration on unmount before subscribing', async () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({ PLAY_PAUSE: 'shift+space' })
+ let resolveSettings!: (settings: HostShortcutSettings) => void
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_REVERSE: 'q' }))
+ host.host.shortcuts!.getSettings = vi.fn(
+ () => new Promise((resolve) => (resolveSettings = resolve)),
+ )
+ const controller = new AbortController()
+ const mounting = mountHostShortcutSettings(host.host, controller.signal)
+
+ controller.abort()
+ resolveSettings(createHostShortcutSettings({ SHUTTLE_REVERSE: 'q' }))
+ const unmount = await mounting
+
+ expect(host.listenerCount()).toBe(0)
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({
+ PLAY_PAUSE: 'shift+space',
+ })
+ unmount()
+ })
+
+ it('does not execute a queued write after its host is disposed', async () => {
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ const unmount = await mountHostShortcutSettings(host.host)
+ const pending = Promise.resolve()
+ host.setSettings.mockReturnValueOnce(pending)
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ unmount()
+ await Promise.resolve()
+ expect(host.setSettings).not.toHaveBeenCalled()
+ })
+
+ it('drops an older outbound write when newer host input arrives', async () => {
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ const unmount = await mountHostShortcutSettings(host.host)
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ host.emit(createHostShortcutSettings({ SHUTTLE_PAUSE: 'w' }))
+ await Promise.resolve()
+ expect(host.setSettings).not.toHaveBeenCalled()
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({ SHUTTLE_PAUSE: 'w' })
+ unmount()
+ })
+
+ it('reconciles newer subscribed state after an older write finishes last', async () => {
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ const firstWrite = createDeferred()
+ host.setSettings.mockReturnValueOnce(firstWrite.promise)
+ const unmount = await mountHostShortcutSettings(host.host)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await waitFor(() => expect(host.setSettings).toHaveBeenCalledTimes(1))
+
+ host.emit(createHostShortcutSettings({ SHUTTLE_PAUSE: 'w' }))
+ firstWrite.resolve()
+
+ await waitFor(() =>
+ expect(host.setSettings).toHaveBeenLastCalledWith(
+ createHostShortcutSettings({ SHUTTLE_PAUSE: 'w' }),
+ ),
+ )
+ expect(host.setSettings).toHaveBeenCalledTimes(2)
+ unmount()
+ })
+
+ it('retries the newest subscribed state after an older write rejects', async () => {
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ const firstWrite = createDeferred()
+ host.setSettings.mockReturnValueOnce(firstWrite.promise)
+ const unmount = await mountHostShortcutSettings(host.host)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await waitFor(() => expect(host.setSettings).toHaveBeenCalledTimes(1))
+ host.emit(createHostShortcutSettings({ SHUTTLE_PAUSE: 'w' }))
+ firstWrite.reject(new Error('old write failed'))
+
+ await waitFor(() =>
+ expect(host.setSettings).toHaveBeenLastCalledWith(
+ createHostShortcutSettings({ SHUTTLE_PAUSE: 'w' }),
+ ),
+ )
+ expect(host.notify).toHaveBeenCalledWith(
+ expect.objectContaining({ kind: 'error', message: expect.stringContaining('save') }),
+ )
+ unmount()
+ })
+
+ it('retries the newest desired settings after their host write rejects', async () => {
+ vi.useFakeTimers()
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ host.setSettings.mockRejectedValueOnce(new Error('transient failure'))
+ const unmount = await mountHostShortcutSettings(host.host)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await Promise.resolve()
+ await Promise.resolve()
+ expect(host.setSettings).toHaveBeenCalledTimes(1)
+
+ await vi.advanceTimersByTimeAsync(HOST_SHORTCUT_RETRY_DELAYS_MS[0])
+
+ expect(host.setSettings).toHaveBeenCalledTimes(2)
+ expect(host.setSettings).toHaveBeenLastCalledWith(
+ createHostShortcutSettings({ SHUTTLE_PAUSE: 'x' }),
+ )
+ unmount()
+ })
+
+ it('backs repeated failures with one capped timer and no tight loop', async () => {
+ const retry = createRetryScheduler()
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ host.setSettings.mockRejectedValue(new Error('persistent failure'))
+ const unmount = await mountHostShortcutSettings(host.host, undefined, retry.scheduler)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await Promise.resolve()
+ await Promise.resolve()
+ expect(host.setSettings).toHaveBeenCalledTimes(1)
+ expect(retry.pendingCount()).toBe(1)
+ expect(retry.pendingDelays()).toEqual([HOST_SHORTCUT_RETRY_DELAYS_MS[0]])
+
+ await retry.runNext()
+ expect(host.setSettings).toHaveBeenCalledTimes(2)
+ expect(retry.pendingCount()).toBe(1)
+ expect(retry.pendingDelays()).toEqual([HOST_SHORTCUT_RETRY_DELAYS_MS[1]])
+
+ for (let retryIndex = 2; retryIndex < HOST_SHORTCUT_RETRY_DELAYS_MS.length; retryIndex += 1) {
+ await retry.runNext()
+ expect(retry.pendingCount()).toBe(1)
+ expect(retry.pendingDelays()).toEqual([HOST_SHORTCUT_RETRY_DELAYS_MS[retryIndex]])
+ }
+ await retry.runNext()
+ expect(retry.pendingCount()).toBe(1)
+ expect(retry.pendingDelays()).toEqual([HOST_SHORTCUT_RETRY_DELAYS_MS.at(-1)!])
+ expect(host.setSettings).toHaveBeenCalledTimes(HOST_SHORTCUT_RETRY_DELAYS_MS.length + 1)
+ unmount()
+ expect(retry.pendingCount()).toBe(0)
+ })
+
+ it('persists only the newest desired settings after a change during backoff', async () => {
+ const retry = createRetryScheduler()
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ host.setSettings.mockRejectedValueOnce(new Error('transient failure'))
+ const unmount = await mountHostShortcutSettings(host.host, undefined, retry.scheduler)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await Promise.resolve()
+ await Promise.resolve()
+ expect(retry.pendingCount()).toBe(1)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'f10')
+ await Promise.resolve()
+ await Promise.resolve()
+
+ expect(host.setSettings).toHaveBeenCalledTimes(2)
+ expect(host.setSettings).toHaveBeenLastCalledWith(
+ createHostShortcutSettings({ SHUTTLE_PAUSE: 'f10' }),
+ )
+ expect(retry.pendingCount()).toBe(0)
+ unmount()
+ })
+
+ it('cancels a pending retry when equal inbound settings acknowledge the desired value', async () => {
+ const retry = createRetryScheduler()
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ host.setSettings.mockRejectedValueOnce(new Error('transient failure'))
+ const unmount = await mountHostShortcutSettings(host.host, undefined, retry.scheduler)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await Promise.resolve()
+ await Promise.resolve()
+ expect(retry.pendingCount()).toBe(1)
+
+ host.emit(createHostShortcutSettings({ SHUTTLE_PAUSE: 'x' }))
+ expect(retry.pendingCount()).toBe(0)
+ expect(host.setSettings).toHaveBeenCalledTimes(1)
+ unmount()
+ })
+
+ it('cancels a disposed host retry and fences it from the replacement host', async () => {
+ const retry = createRetryScheduler()
+ const hostA = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'a' }))
+ hostA.setSettings.mockRejectedValueOnce(new Error('transient failure'))
+ const unmountA = await mountHostShortcutSettings(hostA.host, undefined, retry.scheduler)
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await Promise.resolve()
+ await Promise.resolve()
+ expect(retry.pendingCount()).toBe(1)
+
+ const hostB = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'b' }))
+ const unmountB = await mountHostShortcutSettings(hostB.host, undefined, retry.scheduler)
+ expect(retry.pendingCount()).toBe(0)
+ expect(hostA.setSettings).toHaveBeenCalledTimes(1)
+ expect(hostB.setSettings).not.toHaveBeenCalled()
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'f10')
+ await Promise.resolve()
+ expect(hostB.setSettings).toHaveBeenCalledTimes(1)
+ unmountA()
+ unmountB()
+ })
+
+ it('fences in-flight host A work when host B replaces it', async () => {
+ const hostA = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'a' }))
+ const firstWrite = createDeferred()
+ hostA.setSettings.mockReturnValueOnce(firstWrite.promise)
+ const unmountA = await mountHostShortcutSettings(hostA.host)
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await waitFor(() => expect(hostA.setSettings).toHaveBeenCalledTimes(1))
+
+ const hostB = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'b' }))
+ const unmountB = await mountHostShortcutSettings(hostB.host)
+ expect(hostA.listenerCount()).toBe(0)
+ expect(hostB.listenerCount()).toBe(1)
+
+ hostA.emit(createHostShortcutSettings({ SHUTTLE_PAUSE: 'z' }))
+ firstWrite.resolve()
+ await Promise.resolve()
+ await Promise.resolve()
+
+ expect(hostA.setSettings).toHaveBeenCalledTimes(1)
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({ SHUTTLE_PAUSE: 'b' })
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'f10')
+ await waitFor(() => expect(hostB.setSettings).toHaveBeenCalledTimes(1))
+
+ unmountA()
+ expect(hostB.listenerCount()).toBe(1)
+ unmountB()
+ expect(hostB.listenerCount()).toBe(0)
+ })
+
+ it('suppresses equal subscription echoes without a redundant write loop', async () => {
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ const write = createDeferred()
+ host.setSettings.mockReturnValueOnce(write.promise)
+ const unmount = await mountHostShortcutSettings(host.host)
+
+ useSettingsStore.getState().setHotkeyBinding('SHUTTLE_PAUSE', 'x')
+ await waitFor(() => expect(host.setSettings).toHaveBeenCalledTimes(1))
+ host.emit(createHostShortcutSettings({ SHUTTLE_PAUSE: 'x' }))
+ write.resolve()
+ await Promise.resolve()
+ await Promise.resolve()
+
+ expect(host.setSettings).toHaveBeenCalledTimes(1)
+ expect(host.listenerCount()).toBe(1)
+ unmount()
+ expect(host.listenerCount()).toBe(0)
+ })
+
+ it('removes the host subscriber on unmount', async () => {
+ const host = createShortcutHost(createHostShortcutSettings({ SHUTTLE_PAUSE: 'p' }))
+ const unmount = await mountHostShortcutSettings(host.host)
+ expect(host.listenerCount()).toBe(1)
+ unmount()
+ expect(host.listenerCount()).toBe(0)
+ })
+
+ it('resolves a host collision so capture and bubbling listeners fire one intended action', async () => {
+ const harness = createShortcutHost(
+ createHostShortcutSettings({
+ SHUTTLE_PAUSE: 'k',
+ EDIT_KEYFRAME_ADD: 'k',
+ }),
+ )
+ const unmount = await mountHostShortcutSettings(harness.host)
+ const addKeyframe = vi.fn()
+
+ render(createElement(ConflictingShortcutHarness, { onAddKeyframe: addKeyframe }))
+ usePlaybackStore.setState({ isPlaying: true })
+ fireEvent.keyDown(document, { key: 'k', code: 'KeyK' })
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+ expect(addKeyframe).not.toHaveBeenCalled()
+
+ fireEvent.keyDown(document, { key: 'K', code: 'KeyK', shiftKey: true })
+ expect(addKeyframe).toHaveBeenCalledTimes(1)
+ expect(harness.notify).toHaveBeenCalledWith(expect.objectContaining({ kind: 'conflict' }))
+
+ unmount()
+ })
+
+ it('retains the last valid settings and reports derived host conflict metadata', async () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({ PLAY_PAUSE: 'shift+space' })
+ const harness = createShortcutHost(
+ createHostShortcutSettings({
+ MARK_IN: 'j',
+ SHUTTLE_REVERSE: 'i',
+ }),
+ )
+
+ const unmount = await mountHostShortcutSettings(harness.host)
+
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({ PLAY_PAUSE: 'shift+space' })
+ expect(harness.notify).toHaveBeenCalledWith({
+ kind: 'conflict',
+ message: expect.stringMatching(/shift\+j.*MARK_IN.*JOIN_ITEMS.*last valid/i),
+ })
+ expect(harness.setSettings).not.toHaveBeenCalled()
+ unmount()
+ })
+
+ it('retains the last valid settings and reports meta versus mod host conflicts', async () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({ PLAY_PAUSE: 'shift+space' })
+ const harness = createShortcutHost(
+ createHostShortcutSettings({
+ MARK_IN: 'meta+j',
+ JOIN_ITEMS: 'mod+shift+j',
+ }),
+ )
+
+ const unmount = await mountHostShortcutSettings(harness.host)
+
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({ PLAY_PAUSE: 'shift+space' })
+ expect(harness.notify).toHaveBeenCalledWith({
+ kind: 'conflict',
+ message: expect.stringMatching(/MARK_IN.*JOIN_ITEMS.*last valid/i),
+ })
+ expect(harness.setSettings).not.toHaveBeenCalled()
+ unmount()
+ })
+})
diff --git a/src/features/editor/host/shortcut-settings.ts b/src/features/editor/host/shortcut-settings.ts
new file mode 100644
index 000000000..703a6fed6
--- /dev/null
+++ b/src/features/editor/host/shortcut-settings.ts
@@ -0,0 +1,277 @@
+import {
+ resolveHotkeyConfiguration,
+ type HotkeyConflictWarning,
+ type HotkeyOverrideMap,
+} from '@/config/hotkeys'
+import { useSettingsStore } from '@/features/editor/deps/settings'
+import {
+ HOST_SHORTCUTS_SCHEMA,
+ HOST_SHORTCUTS_VERSION,
+ createHostShortcutSettings,
+ type EditorHost,
+ type HostShortcutSettings,
+} from './contract'
+
+export const HOST_SHORTCUT_RETRY_DELAYS_MS = [100, 250, 500, 1_000, 2_000] as const
+
+export interface HostShortcutRetryScheduler {
+ setTimeout(callback: () => void, delayMs: number): unknown
+ clearTimeout(timer: unknown): void
+}
+
+const DEFAULT_HOST_SHORTCUT_RETRY_SCHEDULER: HostShortcutRetryScheduler = {
+ setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+ clearTimeout: (timer) => clearTimeout(timer as ReturnType),
+}
+
+function normalizeHostShortcutSettings(settings: HostShortcutSettings): {
+ settings: HostShortcutSettings
+ warnings: HotkeyConflictWarning[]
+} {
+ if (settings.schema !== HOST_SHORTCUTS_SCHEMA || settings.version !== HOST_SHORTCUTS_VERSION) {
+ throw new Error('Unsupported host shortcut settings schema')
+ }
+
+ const resolution = resolveHotkeyConfiguration(settings.overrides)
+ return {
+ settings: createHostShortcutSettings(resolution.overrides),
+ warnings: resolution.warnings,
+ }
+}
+
+function copyOverrides(overrides: HotkeyOverrideMap): HotkeyOverrideMap {
+ return { ...overrides }
+}
+
+interface ShortcutOwnership {
+ epoch: number
+ standaloneOverrides: HotkeyOverrideMap
+ dispose?: () => void
+}
+
+let nextOwnershipEpoch = 0
+let currentOwnership: ShortcutOwnership | null = null
+
+/**
+ * Hydrates host-owned shortcuts before the editor mounts, then keeps UI and
+ * host/agent changes synchronized for the lifetime of the embedded surface.
+ */
+export async function mountHostShortcutSettings(
+ host: EditorHost,
+ signal?: AbortSignal,
+ retryScheduler: HostShortcutRetryScheduler = DEFAULT_HOST_SHORTCUT_RETRY_SCHEDULER,
+): Promise<() => void> {
+ const previousOwnership = currentOwnership
+ const standaloneOverrides = copyOverrides(
+ previousOwnership?.standaloneOverrides ?? useSettingsStore.getState().hotkeyOverrides,
+ )
+ previousOwnership?.dispose?.()
+ const ownership: ShortcutOwnership = {
+ epoch: ++nextOwnershipEpoch,
+ standaloneOverrides,
+ }
+ currentOwnership = ownership
+ let applyingHostSettings = false
+ let disposed = false
+ let unsubscribeHost: (() => void) | undefined
+ let unsubscribeStore: (() => void) | undefined
+ let retryTimer: unknown
+
+ const isCurrent = () => !disposed && currentOwnership?.epoch === ownership.epoch
+
+ const dispose = () => {
+ if (disposed) return
+ disposed = true
+ if (retryTimer !== undefined) retryScheduler.clearTimeout(retryTimer)
+ retryTimer = undefined
+ unsubscribeStore?.()
+ unsubscribeHost?.()
+ signal?.removeEventListener('abort', dispose)
+ if (currentOwnership?.epoch !== ownership.epoch) return
+ currentOwnership = null
+ useSettingsStore.getState().replaceHotkeyOverrides(ownership.standaloneOverrides)
+ }
+ ownership.dispose = dispose
+
+ if (signal?.aborted) {
+ dispose()
+ return dispose
+ }
+ signal?.addEventListener('abort', dispose, { once: true })
+
+ // Replacing a host invalidates the previous epoch immediately, including
+ // while either host is still resolving getSettings. Keep the standalone
+ // snapshot visible until this owner has authoritative settings to apply.
+ useSettingsStore.getState().replaceHotkeyOverrides(ownership.standaloneOverrides)
+
+ const port = host.shortcuts
+ if (!port) {
+ return dispose
+ }
+
+ const reportFailure = (message: string) => {
+ host.notify?.({ kind: 'error', message })
+ }
+
+ const settingsEqual = (left: HostShortcutSettings, right: HostShortcutSettings) => {
+ const leftKeys = Object.keys(left.overrides)
+ const rightKeys = Object.keys(right.overrides)
+ return (
+ leftKeys.length === rightKeys.length &&
+ leftKeys.every(
+ (key) =>
+ left.overrides[key as keyof HotkeyOverrideMap] ===
+ right.overrides[key as keyof HotkeyOverrideMap],
+ )
+ )
+ }
+
+ let desiredSettings: HostShortcutSettings | null = null
+ let settledSettings: HostShortcutSettings | null = null
+ let inFlightSettings: HostShortcutSettings | null = null
+ let reconcileAfterFlight = false
+ let reconcileScheduled = false
+ let retryAttempt = 0
+
+ const cancelRetry = (resetAttempt = false) => {
+ if (retryTimer !== undefined) retryScheduler.clearTimeout(retryTimer)
+ retryTimer = undefined
+ if (resetAttempt) retryAttempt = 0
+ }
+
+ const canStartReconcile = () => {
+ if (!isCurrent()) return false
+ if (inFlightSettings || !desiredSettings) return false
+ if (reconcileAfterFlight || !settledSettings) return true
+ return !settingsEqual(desiredSettings, settledSettings)
+ }
+
+ const desiredDiffersFrom = (settings: HostShortcutSettings) =>
+ desiredSettings !== null && !settingsEqual(desiredSettings, settings)
+
+ const hasUnsettledDesiredSettings = () =>
+ desiredSettings !== null &&
+ (settledSettings === null || !settingsEqual(desiredSettings, settledSettings))
+
+ const finishReconcile = (settingsToWrite: HostShortcutSettings, succeeded: boolean) => {
+ if (!isCurrent()) return
+ if (succeeded) {
+ settledSettings = settingsToWrite
+ retryAttempt = 0
+ }
+ const desiredChanged = desiredDiffersFrom(settingsToWrite)
+ inFlightSettings = null
+ if (desiredChanged || reconcileAfterFlight) {
+ scheduleReconcile()
+ return
+ }
+ if (!succeeded && hasUnsettledDesiredSettings()) {
+ scheduleRetry()
+ }
+ }
+
+ const persistDesiredSettings = async () => {
+ reconcileScheduled = false
+ if (!canStartReconcile()) return
+
+ const settingsToWrite = desiredSettings!
+ inFlightSettings = settingsToWrite
+ reconcileAfterFlight = false
+ let succeeded = false
+ try {
+ await Promise.resolve(port.setSettings(settingsToWrite))
+ succeeded = true
+ } catch {
+ if (isCurrent()) reportFailure('Could not save keyboard shortcuts to the host.')
+ }
+ finishReconcile(settingsToWrite, succeeded)
+ }
+
+ function scheduleReconcile() {
+ if (reconcileScheduled || inFlightSettings || !desiredSettings) return
+ reconcileScheduled = true
+ void Promise.resolve().then(persistDesiredSettings)
+ }
+
+ function scheduleRetry() {
+ if (retryTimer !== undefined || inFlightSettings || !desiredSettings || !isCurrent()) return
+ const retryIndex = Math.min(retryAttempt, HOST_SHORTCUT_RETRY_DELAYS_MS.length - 1)
+ const delay = HOST_SHORTCUT_RETRY_DELAYS_MS[retryIndex]!
+ retryAttempt += 1
+ retryTimer = retryScheduler.setTimeout(() => {
+ retryTimer = undefined
+ scheduleReconcile()
+ }, delay)
+ }
+
+ const applyHostSettings = (settings: HostShortcutSettings) => {
+ if (!isCurrent()) return
+ const normalized = normalizeHostShortcutSettings(settings)
+ if (normalized.warnings.length > 0) {
+ for (const warning of normalized.warnings) {
+ host.notify?.({
+ kind: 'conflict',
+ message: `Shortcut ${warning.binding} for ${warning.command} conflicts with ${warning.conflictingCommand}; retained the last valid shortcut settings.`,
+ })
+ }
+ return
+ }
+ applyingHostSettings = true
+ try {
+ useSettingsStore.getState().replaceHotkeyOverrides(normalized.settings.overrides)
+ } finally {
+ applyingHostSettings = false
+ }
+ desiredSettings = normalized.settings
+ // A subscription is persisted host authority. It acknowledges an equal
+ // dirty value and supersedes a differing value unless an older write can
+ // still finish afterward, in which case that authority is reconciled once.
+ settledSettings = normalized.settings
+ cancelRetry(true)
+ if (inFlightSettings) {
+ reconcileAfterFlight = !settingsEqual(inFlightSettings, normalized.settings)
+ }
+ }
+
+ let initialSettings: HostShortcutSettings
+ try {
+ initialSettings = await Promise.resolve(port.getSettings())
+ } catch (error) {
+ dispose()
+ throw error
+ }
+ if (!isCurrent()) {
+ return dispose
+ }
+ desiredSettings = createHostShortcutSettings(
+ copyOverrides(useSettingsStore.getState().hotkeyOverrides),
+ )
+ settledSettings = initialSettings
+ applyHostSettings(initialSettings)
+
+ unsubscribeHost = port.subscribe?.((settings) => {
+ if (!isCurrent()) return
+ try {
+ applyHostSettings(settings)
+ } catch {
+ reportFailure('Could not apply keyboard shortcuts from the host.')
+ }
+ })
+
+ unsubscribeStore = useSettingsStore.subscribe((state, previousState) => {
+ if (
+ disposed ||
+ applyingHostSettings ||
+ state.hotkeyOverrides === previousState.hotkeyOverrides
+ ) {
+ return
+ }
+
+ const settings = createHostShortcutSettings(copyOverrides(state.hotkeyOverrides))
+ desiredSettings = settings
+ cancelRetry(true)
+ scheduleReconcile()
+ })
+
+ return dispose
+}
diff --git a/src/features/export/components/export-dialog.test.tsx b/src/features/export/components/export-dialog.test.tsx
index 4b712d11d..406d51a1b 100644
--- a/src/features/export/components/export-dialog.test.tsx
+++ b/src/features/export/components/export-dialog.test.tsx
@@ -9,6 +9,69 @@ const mockDownloadVideo = vi.fn()
const mockResetState = vi.fn()
const mockGetSupportedCodecs = vi.fn<(...args: unknown[]) => Promise>()
+const { mainSequence, selectedSequence, mockGetExportableSequence } = vi.hoisted(() => {
+ const sequence = (id: string | null, name: string, itemId: string) => {
+ const trackId = `track-${itemId}`
+ const item = {
+ id: itemId,
+ trackId,
+ type: 'text' as const,
+ from: 0,
+ durationInFrames: 30,
+ label: name,
+ text: name,
+ color: '#ffffff',
+ }
+ return {
+ id,
+ name,
+ tracks: [
+ {
+ id: trackId,
+ name: 'V1',
+ kind: 'video' as const,
+ height: 60,
+ locked: false,
+ visible: true,
+ muted: false,
+ solo: false,
+ order: 0,
+ items: [item],
+ },
+ ],
+ items: [item],
+ transitions: [],
+ keyframes: [],
+ fps: 30,
+ width: 1920,
+ height: 1080,
+ backgroundColor: '#000000',
+ masterBusDb: 0,
+ durationFrames: 30,
+ inPoint: null,
+ outPoint: null,
+ markers: [],
+ }
+ }
+
+ const main = sequence(null, 'Main Timeline', 'main-title')
+ const selected = sequence('agent-cut', 'Agent Cut', 'agent-title')
+ return {
+ mainSequence: main,
+ selectedSequence: selected,
+ mockGetExportableSequence: vi.fn((id: string | null) => (id === selected.id ? selected : main)),
+ }
+})
+
+vi.mock('@/features/export/deps/timeline-compositions', () => ({
+ getActiveExportSequenceId: () => null,
+ getExportableSequence: mockGetExportableSequence,
+ listExportableSequences: () => [
+ { id: null, name: mainSequence.name },
+ { id: selectedSequence.id, name: selectedSequence.name },
+ ],
+}))
+
vi.mock('../hooks/use-client-render', () => ({
useClientRender: () => ({
isExporting: false,
@@ -115,4 +178,22 @@ describe('ExportDialog', () => {
const h265Option = await screen.findByRole('option', { name: /H\.265/i })
expect(h265Option).toHaveAttribute('data-disabled')
})
+
+ it('passes the selected sequence snapshot to direct export', async () => {
+ mockGetSupportedCodecs.mockResolvedValue(['avc'])
+ mockStartExport.mockResolvedValue(undefined)
+
+ render( {}} />)
+
+ fireEvent.keyDown(screen.getByLabelText('Sequence'), { key: 'ArrowDown' })
+ fireEvent.click(await screen.findByRole('option', { name: selectedSequence.name }))
+
+ const exportButton = screen.getByRole('button', { name: 'Export Video' })
+ await waitFor(() => expect(exportButton).not.toBeDisabled())
+ fireEvent.click(exportButton)
+
+ await waitFor(() => {
+ expect(mockStartExport).toHaveBeenCalledWith(expect.any(Object), selectedSequence)
+ })
+ })
})
diff --git a/src/features/export/components/export-dialog.tsx b/src/features/export/components/export-dialog.tsx
index 1b0332335..e64ce7b7b 100644
--- a/src/features/export/components/export-dialog.tsx
+++ b/src/features/export/components/export-dialog.tsx
@@ -394,8 +394,7 @@ export function ExportDialog({ open, onClose, onOpenRenderQueue }: ExportDialogP
const reversedClipIds = new Set(
items
.filter(
- (item) =>
- (item.type === 'video' || item.type === 'audio') && item.isReversed === true,
+ (item) => (item.type === 'video' || item.type === 'audio') && item.isReversed === true,
)
.map((item) => item.id),
)
@@ -643,8 +642,9 @@ export function ExportDialog({ open, onClose, onOpenRenderQueue }: ExportDialogP
// Start export
const handleStartExport = async () => {
+ const seq = captureSelection()
setView('progress')
- await startExport(buildExtendedSettings())
+ await startExport(buildExtendedSettings(), seq)
}
// The active render range for a sequence (whole timeline unless in/out set).
@@ -1574,8 +1574,7 @@ export function ExportDialog({ open, onClose, onOpenRenderQueue }: ExportDialogP
- {status === 'preparing' &&
- (progressMessage ?? t('export.progress.preparing'))}
+ {status === 'preparing' && (progressMessage ?? t('export.progress.preparing'))}
{status === 'rendering' && t('export.progress.rendering')}
{status === 'encoding' && t('export.progress.encoding')}
{status === 'finalizing' && t('export.progress.finalizing')}
diff --git a/src/features/export/hooks/client-render-source.test.ts b/src/features/export/hooks/client-render-source.test.ts
new file mode 100644
index 000000000..0105c64b6
--- /dev/null
+++ b/src/features/export/hooks/client-render-source.test.ts
@@ -0,0 +1,51 @@
+// @vitest-environment node
+
+import { describe, expect, it } from 'vite-plus/test'
+import type { ExportableSequence } from '@/features/export/deps/timeline-compositions'
+import { resolveClientRenderSource } from './client-render-source'
+
+function makeSequence(overrides: Partial = {}): ExportableSequence {
+ return {
+ id: 'selected',
+ name: 'Selected',
+ tracks: [],
+ items: [],
+ transitions: [],
+ keyframes: [],
+ fps: 24,
+ width: 1280,
+ height: 720,
+ masterBusDb: -3,
+ durationFrames: 0,
+ inPoint: null,
+ outPoint: null,
+ markers: [],
+ ...overrides,
+ }
+}
+
+describe('resolveClientRenderSource', () => {
+ it('preserves an explicitly unset selected-sequence range and EQ', () => {
+ const sequence = makeSequence({ busAudioEq: undefined, backgroundColor: undefined })
+ const result = resolveClientRenderSource(
+ sequence,
+ makeSequence({ id: null, inPoint: 30, outPoint: 90 }),
+ {
+ busAudioEq: { enabled: true, lowGainDb: 4, midGainDb: 2, highGainDb: 3 },
+ masterBusDb: 6,
+ },
+ { width: 1920, height: 1080, backgroundColor: '#ff0000' },
+ )
+
+ expect(result).toMatchObject({
+ fps: 24,
+ inPoint: null,
+ outPoint: null,
+ busAudioEq: undefined,
+ masterBusDb: -3,
+ backgroundColor: undefined,
+ width: 1280,
+ height: 720,
+ })
+ })
+})
diff --git a/src/features/export/hooks/client-render-source.ts b/src/features/export/hooks/client-render-source.ts
new file mode 100644
index 000000000..23a9bde74
--- /dev/null
+++ b/src/features/export/hooks/client-render-source.ts
@@ -0,0 +1,43 @@
+import type { ExportableSequence } from '@/features/export/deps/timeline-compositions'
+import { DEFAULT_PROJECT_HEIGHT, DEFAULT_PROJECT_WIDTH } from '@/shared/projects/defaults'
+
+type TimelineRenderSource = Pick<
+ ExportableSequence,
+ 'tracks' | 'items' | 'transitions' | 'fps' | 'inPoint' | 'outPoint' | 'keyframes'
+>
+
+type PlaybackRenderSource = Pick
+
+interface ProjectRenderMetadata {
+ width?: number
+ height?: number
+ backgroundColor?: string
+}
+
+/**
+ * Select one complete render source. Once a sequence snapshot is supplied,
+ * its nullable/optional values are authoritative too: an unset range or EQ
+ * must not inherit state from whichever timeline happens to be active.
+ */
+export function resolveClientRenderSource(
+ sequence: ExportableSequence | undefined,
+ timeline: TimelineRenderSource,
+ playback: PlaybackRenderSource,
+ projectMetadata: ProjectRenderMetadata | undefined,
+) {
+ const source = sequence ?? timeline
+ return {
+ tracks: source.tracks,
+ items: source.items,
+ transitions: source.transitions,
+ fps: source.fps,
+ inPoint: source.inPoint,
+ outPoint: source.outPoint,
+ keyframes: source.keyframes,
+ busAudioEq: sequence ? sequence.busAudioEq : playback.busAudioEq,
+ masterBusDb: sequence ? sequence.masterBusDb : playback.masterBusDb,
+ backgroundColor: sequence ? sequence.backgroundColor : projectMetadata?.backgroundColor,
+ width: sequence?.width ?? projectMetadata?.width ?? DEFAULT_PROJECT_WIDTH,
+ height: sequence?.height ?? projectMetadata?.height ?? DEFAULT_PROJECT_HEIGHT,
+ }
+}
diff --git a/src/features/export/hooks/use-client-render.test.tsx b/src/features/export/hooks/use-client-render.test.tsx
new file mode 100644
index 000000000..df351144d
--- /dev/null
+++ b/src/features/export/hooks/use-client-render.test.tsx
@@ -0,0 +1,333 @@
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { StrictMode, type PropsWithChildren } from 'react'
+
+const mocks = vi.hoisted(() => ({
+ resolveMediaUrls: vi.fn(),
+ runRender: vi.fn(),
+ resolveClientSettings: vi.fn(),
+ mapRequestedClientSettings: vi.fn(),
+ trySmartCopyExport: vi.fn(),
+ convertTimelineToComposition: vi.fn(),
+ buildTranscriptSubtitleCues: vi.fn(),
+ releaseTemporaryExportOutput: vi.fn(),
+ setResult: vi.fn(),
+}))
+
+vi.mock('@/features/export/deps/media-library', () => ({
+ resolveMediaUrls: mocks.resolveMediaUrls,
+}))
+vi.mock('../utils/smart-copy', () => ({ trySmartCopyExport: mocks.trySmartCopyExport }))
+vi.mock('../utils/render-pipeline', () => ({
+ isExtendedSettings: (settings: unknown) =>
+ typeof settings === 'object' && settings !== null && 'mode' in settings,
+ mapRequestedClientSettings: mocks.mapRequestedClientSettings,
+ resolveClientSettings: mocks.resolveClientSettings,
+ runRender: mocks.runRender,
+}))
+vi.mock('../utils/timeline-to-composition', () => ({
+ convertTimelineToComposition: mocks.convertTimelineToComposition,
+}))
+vi.mock('../utils/embedded-subtitle-export', () => ({
+ buildTranscriptSubtitleCues: mocks.buildTranscriptSubtitleCues,
+}))
+vi.mock('@/shared/utils/subtitles', () => ({ serializeSrt: vi.fn(() => '') }))
+vi.mock('../utils/export-output-target', () => ({
+ releaseTemporaryExportOutput: mocks.releaseTemporaryExportOutput,
+}))
+vi.mock('../utils/client-renderer', () => ({
+ formatBytes: (bytes: number) => `${bytes} bytes`,
+ estimateFileSize: vi.fn(() => 1),
+ getSupportedCodecs: vi.fn(async () => []),
+ getVideoBitrateForQuality: vi.fn(() => 1),
+ mapToClientSettings: vi.fn(() => ({})),
+}))
+vi.mock('@/features/export/deps/timeline', () => ({
+ useTimelineStore: {
+ getState: () => ({
+ tracks: [],
+ items: [],
+ transitions: [],
+ fps: 30,
+ inPoint: null,
+ outPoint: null,
+ keyframes: [],
+ busAudioEq: [],
+ masterBusDb: 0,
+ backgroundColor: '#000',
+ width: 1920,
+ height: 1080,
+ }),
+ },
+}))
+vi.mock('@/features/export/deps/projects', () => ({
+ useProjectStore: { getState: () => ({ currentProject: null }) },
+}))
+vi.mock('@/shared/state/playback', () => ({
+ usePlaybackStore: { getState: () => ({}) },
+}))
+vi.mock('./client-render-source', () => ({
+ resolveClientRenderSource: (_sequence: unknown, state: unknown) => state,
+}))
+vi.mock('@/shared/projects/defaults', () => ({
+ DEFAULT_PROJECT_WIDTH: 1920,
+ DEFAULT_PROJECT_HEIGHT: 1080,
+}))
+vi.mock('@/shared/logging/logger', () => ({
+ createLogger: () => ({
+ startEvent: () => ({ set: vi.fn(), merge: vi.fn(), success: vi.fn(), failure: vi.fn() }),
+ warn: vi.fn(),
+ event: vi.fn(),
+ }),
+ createOperationId: () => 'test-op',
+}))
+
+import { useClientRender } from './use-client-render'
+
+const settings = { quality: 'medium', resolution: { width: 640, height: 360 } } as Record<
+ string,
+ unknown
+>
+const renderedResult = {
+ blob: new Blob(['encoded']),
+ fileSize: 7,
+ duration: 1,
+ mimeType: 'video/mp4',
+}
+
+function deferred() {
+ let resolve!: (value: T) => void
+ let reject!: (error: unknown) => void
+ const promise = new Promise((res, rej) => {
+ resolve = res
+ reject = rej
+ })
+ return { promise, resolve, reject }
+}
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ mocks.trySmartCopyExport.mockResolvedValue({ result: null })
+ const clientSettings = {
+ resolution: { width: 640, height: 360 },
+ subtitleMode: 'burn',
+ codec: 'avc',
+ container: 'mp4',
+ }
+ mocks.mapRequestedClientSettings.mockReturnValue({
+ clientSettings,
+ exportMode: 'video',
+ renderWholeProject: false,
+ })
+ mocks.resolveClientSettings.mockImplementation(async (settings: { subtitleMode?: string }) => ({
+ clientSettings: { ...clientSettings, subtitleMode: settings.subtitleMode ?? 'burn' },
+ exportMode: 'video',
+ renderWholeProject: false,
+ }))
+ mocks.convertTimelineToComposition.mockReturnValue({ tracks: [], durationInFrames: 30 })
+ mocks.resolveMediaUrls.mockImplementation(async (tracks: unknown) => tracks)
+ mocks.buildTranscriptSubtitleCues.mockReturnValue([])
+ mocks.releaseTemporaryExportOutput.mockResolvedValue(undefined)
+})
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('useClientRender lifecycle ownership', () => {
+ it('aborts the active render on unmount and propagates its signal through media resolution', async () => {
+ const render = deferred()
+ mocks.runRender.mockReturnValue(
+ render.promise.then((result) => ({ result, renderPath: 'worker' })),
+ )
+ const hook = renderHook(() => useClientRender(), {
+ wrapper: ({ children }: PropsWithChildren) => {children},
+ })
+
+ let exportPromise!: Promise
+ await act(async () => {
+ exportPromise = hook.result.current.startExport(settings as never)
+ await Promise.resolve()
+ })
+ expect(mocks.resolveMediaUrls).toHaveBeenCalledWith(
+ [],
+ expect.objectContaining({ useProxy: false, signal: expect.any(AbortSignal) }),
+ )
+ const signal = mocks.resolveMediaUrls.mock.calls[0]![1].signal as AbortSignal
+ hook.unmount()
+ expect(signal.aborted).toBe(true)
+ render.resolve(renderedResult)
+ await act(async () => {
+ await exportPromise
+ })
+ })
+
+ it('aborts replacement renders and releases a result that becomes stale', async () => {
+ const first = deferred()
+ const second = deferred()
+ mocks.runRender
+ .mockReturnValueOnce(first.promise.then((result) => ({ result, renderPath: 'worker' })))
+ .mockReturnValueOnce(second.promise.then((result) => ({ result, renderPath: 'worker' })))
+ const hook = renderHook(() => useClientRender())
+ let firstExport!: Promise
+ await act(async () => {
+ firstExport = hook.result.current.startExport(settings as never)
+ await Promise.resolve()
+ })
+ const firstSignal = mocks.runRender.mock.calls[0]![0].signal as AbortSignal
+ let secondExport!: Promise
+ await act(async () => {
+ secondExport = hook.result.current.startExport(settings as never)
+ await Promise.resolve()
+ })
+ expect(firstSignal.aborted).toBe(true)
+ first.resolve(renderedResult)
+ second.resolve({ ...renderedResult, blob: new Blob(['second']) })
+ await act(async () => {
+ await Promise.all([firstExport, secondExport])
+ })
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledWith(renderedResult)
+ })
+
+ it('ignores progress and result ownership from an aborted run after a restart', async () => {
+ const first = deferred()
+ const secondResult = { ...renderedResult, blob: new Blob(['second']) }
+ const second = deferred()
+ mocks.runRender
+ .mockReturnValueOnce(first.promise.then((result) => ({ result, renderPath: 'worker' })))
+ .mockReturnValueOnce(second.promise.then((result) => ({ result, renderPath: 'worker' })))
+ const hook = renderHook(() => useClientRender())
+
+ let firstExport!: Promise
+ await act(async () => {
+ firstExport = hook.result.current.startExport(settings as never)
+ await Promise.resolve()
+ })
+ const firstProgress = mocks.runRender.mock.calls[0]![0].onProgress
+
+ let secondExport!: Promise
+ await act(async () => {
+ secondExport = hook.result.current.startExport(settings as never)
+ await Promise.resolve()
+ })
+ const secondProgress = mocks.runRender.mock.calls[1]![0].onProgress
+
+ act(() => {
+ secondProgress({
+ phase: 'rendering',
+ progress: 25,
+ message: 'new run',
+ currentFrame: 5,
+ totalFrames: 20,
+ })
+ })
+ expect(hook.result.current).toMatchObject({
+ progress: 25,
+ progressMessage: 'new run',
+ status: 'rendering',
+ })
+
+ act(() => {
+ firstProgress({
+ phase: 'encoding',
+ progress: 90,
+ message: 'stale run',
+ currentFrame: 18,
+ totalFrames: 20,
+ })
+ })
+ expect(hook.result.current).toMatchObject({
+ progress: 25,
+ progressMessage: 'new run',
+ status: 'rendering',
+ })
+
+ second.resolve(secondResult)
+ await act(async () => {
+ await secondExport
+ })
+ expect(hook.result.current).toMatchObject({
+ progress: 100,
+ status: 'completed',
+ result: secondResult,
+ })
+
+ act(() => {
+ firstProgress({
+ phase: 'finalizing',
+ progress: 99,
+ message: 'late stale run',
+ currentFrame: 20,
+ totalFrames: 20,
+ })
+ })
+ expect(hook.result.current).toMatchObject({
+ progress: 100,
+ status: 'completed',
+ result: secondResult,
+ })
+
+ first.resolve(renderedResult)
+ await act(async () => {
+ await firstExport
+ })
+ expect(hook.result.current.result).toBe(secondResult)
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledWith(renderedResult)
+ })
+
+ it('aborts a cancelled run exactly once when unmount races its completion', async () => {
+ const abortSpy = vi.spyOn(AbortController.prototype, 'abort')
+ const render = deferred()
+ mocks.runRender.mockReturnValue(
+ render.promise.then((result) => ({ result, renderPath: 'worker' })),
+ )
+ const hook = renderHook(() => useClientRender(), {
+ wrapper: ({ children }: PropsWithChildren) => {children},
+ })
+
+ let exportPromise!: Promise
+ await act(async () => {
+ exportPromise = hook.result.current.startExport(settings as never)
+ await Promise.resolve()
+ })
+ act(() => hook.result.current.cancelExport())
+ hook.unmount()
+
+ expect(abortSpy).toHaveBeenCalledTimes(1)
+ render.resolve(renderedResult)
+ await act(async () => {
+ await exportPromise
+ })
+ expect(abortSpy).toHaveBeenCalledTimes(1)
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledTimes(1)
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledWith(renderedResult)
+ })
+
+ it('releases a rendered output when finalization/update work throws before ownership transfer', async () => {
+ const output = {
+ ...renderedResult,
+ temporaryOutput: { directory: 'scratch', fileName: 'out.mp4' },
+ }
+ mocks.runRender.mockResolvedValue({ result: output, renderPath: 'worker' })
+ mocks.buildTranscriptSubtitleCues.mockImplementation(() => {
+ throw new Error('state/update failed')
+ })
+ const hook = renderHook(() => useClientRender())
+ await act(async () => {
+ await hook.result.current.startExport({ ...settings, subtitleMode: 'sidecar' } as never)
+ })
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledTimes(1)
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledWith(output)
+ })
+
+ it('releases a successfully owned result once on unmount, with reset/unmount causing no double release', async () => {
+ mocks.runRender.mockResolvedValue({ result: renderedResult, renderPath: 'worker' })
+ const hook = renderHook(() => useClientRender())
+ await act(async () => {
+ await hook.result.current.startExport(settings as never)
+ })
+ expect(hook.result.current.result).toBe(renderedResult)
+ act(() => hook.result.current.resetState())
+ hook.unmount()
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledTimes(1)
+ expect(mocks.releaseTemporaryExportOutput).toHaveBeenCalledWith(renderedResult)
+ })
+})
diff --git a/src/features/export/hooks/use-client-render.ts b/src/features/export/hooks/use-client-render.ts
index aa2009645..70c866b7a 100644
--- a/src/features/export/hooks/use-client-render.ts
+++ b/src/features/export/hooks/use-client-render.ts
@@ -31,11 +31,13 @@ import { buildTranscriptSubtitleCues } from '../utils/embedded-subtitle-export'
import { serializeSrt } from '@/shared/utils/subtitles'
import { releaseTemporaryExportOutput } from '../utils/export-output-target'
import { useTimelineStore } from '@/features/export/deps/timeline'
+import type { ExportableSequence } from '@/features/export/deps/timeline-compositions'
import { useProjectStore } from '@/features/export/deps/projects'
import { DEFAULT_PROJECT_HEIGHT, DEFAULT_PROJECT_WIDTH } from '@/shared/projects/defaults'
import { resolveMediaUrls } from '@/features/export/deps/media-library'
import { usePlaybackStore } from '@/shared/state/playback'
import { createLogger, createOperationId } from '@/shared/logging/logger'
+import { resolveClientRenderSource } from './client-render-source'
const log = createLogger('Export')
@@ -61,7 +63,10 @@ interface UseClientRenderReturn {
result: ClientRenderResult | null
// Actions
- startExport: (settings: ExportSettings | ExtendedExportSettings) => Promise
+ startExport: (
+ settings: ExportSettings | ExtendedExportSettings,
+ sequence?: ExportableSequence,
+ ) => Promise
cancelExport: () => void
downloadVideo: () => void
resetState: () => void
@@ -84,15 +89,40 @@ export function useClientRender(): UseClientRenderReturn {
const [status, setStatus] = useState('idle')
const [error, setError] = useState(null)
const [result, setResult] = useState(null)
- const resultRef = useRef(null)
+ const resultOwnerRef = useRef<{
+ runToken: number
+ result: ClientRenderResult
+ released: boolean
+ } | null>(null)
+
+ const activeRunRef = useRef<{
+ token: number
+ controller: AbortController
+ } | null>(null)
+ const latestRunTokenRef = useRef(0)
+
+ const abortActiveRun = useCallback(() => {
+ const run = activeRunRef.current
+ if (!run) return
+ activeRunRef.current = null
+ if (!run.controller.signal.aborted) run.controller.abort()
+ }, [])
- // AbortController for cancellation
- const abortControllerRef = useRef(null)
+ const releaseOwnedResult = useCallback(
+ (
+ owner: { runToken: number; result: ClientRenderResult; released: boolean } | null | undefined,
+ ) => {
+ if (!owner || owner.released) return
+ owner.released = true
+ void releaseTemporaryExportOutput(owner.result)
+ },
+ [],
+ )
/**
* Handle progress updates from the render engine
*/
- const handleProgress = useCallback((progressData: RenderProgress) => {
+ const applyProgress = useCallback((progressData: RenderProgress) => {
setProgress(progressData.progress)
setProgressMessage(progressData.message)
setRenderedFrames(progressData.currentFrame)
@@ -119,14 +149,38 @@ export function useClientRender(): UseClientRenderReturn {
* Start client-side export
*/
const startExport = useCallback(
- async (settings: ExportSettings | ExtendedExportSettings) => {
+ async (settings: ExportSettings | ExtendedExportSettings, sequence?: ExportableSequence) => {
const opId = createOperationId()
const event = log.startEvent('render', opId)
+ const runToken = ++latestRunTokenRef.current
+ abortActiveRun()
+ const controller = new AbortController()
+ const run = { token: runToken, controller }
+ activeRunRef.current = run
+ let temporaryResult: ClientRenderResult | null = null
+
+ const releaseTemporaryResult = () => {
+ const ownedResult = temporaryResult
+ temporaryResult = null
+ if (ownedResult) void releaseTemporaryExportOutput(ownedResult)
+ }
+ const isActive = () =>
+ activeRunRef.current === run &&
+ latestRunTokenRef.current === runToken &&
+ !controller.signal.aborted
+ const ensureActive = () => {
+ if (!isActive()) {
+ throw new DOMException('Render cancelled', 'AbortError')
+ }
+ }
+ const handleRunProgress = (progressData: RenderProgress) => {
+ if (isActive()) applyProgress(progressData)
+ }
try {
- const previousResult = resultRef.current
- resultRef.current = null
- void releaseTemporaryExportOutput(previousResult)
+ const previousResultOwner = resultOwnerRef.current
+ resultOwnerRef.current = null
+ releaseOwnedResult(previousResultOwner)
setIsExporting(true)
setProgress(0)
setProgressMessage(undefined)
@@ -134,28 +188,31 @@ export function useClientRender(): UseClientRenderReturn {
setResult(null)
setStatus('preparing')
- // Create abort controller for cancellation
- abortControllerRef.current = new AbortController()
-
// Read current state from stores
const state = useTimelineStore.getState()
- const { tracks, items, transitions, fps, inPoint, outPoint, keyframes } = state
-
- // Get project metadata (background color and native resolution)
const currentProject = useProjectStore.getState().currentProject
- const busAudioEq = usePlaybackStore.getState().busAudioEq
- const masterBusDb = usePlaybackStore.getState().masterBusDb
- const backgroundColor = currentProject?.metadata?.backgroundColor
- // Use PROJECT resolution for composition (transform calculations match preview)
- const projectWidth = currentProject?.metadata?.width ?? DEFAULT_PROJECT_WIDTH
- const projectHeight = currentProject?.metadata?.height ?? DEFAULT_PROJECT_HEIGHT
+ const playback = usePlaybackStore.getState()
+ const {
+ tracks,
+ items,
+ transitions,
+ fps,
+ inPoint,
+ outPoint,
+ keyframes,
+ busAudioEq,
+ masterBusDb,
+ backgroundColor,
+ width: projectWidth,
+ height: projectHeight,
+ } = resolveClientRenderSource(sequence, state, playback, currentProject?.metadata)
const requested = mapRequestedClientSettings(settings, fps)
// When renderWholeProject is true, ignore in/out points.
const { exportMode, renderWholeProject } = requested
const effectiveInPoint = renderWholeProject ? null : inPoint
const effectiveOutPoint = renderWholeProject ? null : outPoint
- const signal = abortControllerRef.current.signal
+ const signal = controller.signal
const smartCopy = await trySmartCopyExport(
{
@@ -173,12 +230,19 @@ export function useClientRender(): UseClientRenderReturn {
masterBusDb,
},
signal,
- handleProgress,
+ handleRunProgress,
)
+ ensureActive()
if (smartCopy.result) {
- resultRef.current = smartCopy.result
- setResult(smartCopy.result)
+ temporaryResult = smartCopy.result
+ setResult(temporaryResult)
+ resultOwnerRef.current = {
+ runToken,
+ result: temporaryResult,
+ released: false,
+ }
+ temporaryResult = null
setStatus('completed')
setProgress(100)
event.set('renderPath', 'smart-copy')
@@ -192,6 +256,7 @@ export function useClientRender(): UseClientRenderReturn {
// Resolve settings + codec fallback only when an encoder is required.
const { clientSettings, codecFallback } = await resolveClientSettings(settings, fps)
+ ensureActive()
if (codecFallback) event.set('codecFallback', codecFallback)
const extended = isExtendedSettings(settings)
@@ -246,7 +311,11 @@ export function useClientRender(): UseClientRenderReturn {
// Resolve media URLs (convert mediaIds to blob URLs)
// Export always uses full-res source, never proxies
- const resolvedTracks = await resolveMediaUrls(composition.tracks, { useProxy: false })
+ const resolvedTracks = await resolveMediaUrls(composition.tracks, {
+ useProxy: false,
+ signal,
+ })
+ ensureActive()
composition.tracks = resolvedTracks
// Count resolved items for diagnostics
@@ -291,8 +360,10 @@ export function useClientRender(): UseClientRenderReturn {
exportMode,
composition,
signal,
- onProgress: handleProgress,
+ onProgress: handleRunProgress,
})
+ temporaryResult = renderResult
+ ensureActive()
if (fallbackReason) event.set('workerFallbackReason', fallbackReason)
// Sidecar mode: the video is muxed clean; build the .srt from the same
@@ -310,8 +381,10 @@ export function useClientRender(): UseClientRenderReturn {
}
}
- resultRef.current = finalResult
+ if (finalResult !== renderResult) temporaryResult = finalResult
setResult(finalResult)
+ resultOwnerRef.current = { runToken, result: finalResult, released: false }
+ temporaryResult = null
setStatus('completed')
setProgress(100)
@@ -322,6 +395,8 @@ export function useClientRender(): UseClientRenderReturn {
duration: renderResult.duration,
})
} catch (err) {
+ releaseTemporaryResult()
+ if (runToken !== latestRunTokenRef.current) return
if (err instanceof DOMException && err.name === 'AbortError') {
event.set('outcome', 'cancelled')
event.set('duration_ms', Date.now())
@@ -334,11 +409,13 @@ export function useClientRender(): UseClientRenderReturn {
setStatus('failed')
}
} finally {
- setIsExporting(false)
- abortControllerRef.current = null
+ if (activeRunRef.current === run) {
+ activeRunRef.current = null
+ setIsExporting(false)
+ }
}
},
- [handleProgress],
+ [abortActiveRun, applyProgress, releaseOwnedResult],
)
/**
@@ -346,12 +423,12 @@ export function useClientRender(): UseClientRenderReturn {
* which posts the cancel to its worker and terminates it.
*/
const cancelExport = useCallback(() => {
- if (abortControllerRef.current) {
- abortControllerRef.current.abort()
+ if (activeRunRef.current) {
+ abortActiveRun()
setStatus('cancelled')
setIsExporting(false)
}
- }, [])
+ }, [abortActiveRun])
/**
* Download the rendered video/audio
@@ -402,8 +479,8 @@ export function useClientRender(): UseClientRenderReturn {
* Reset state
*/
const resetState = useCallback(() => {
- abortControllerRef.current?.abort()
- abortControllerRef.current = null
+ latestRunTokenRef.current++
+ abortActiveRun()
setIsExporting(false)
setProgress(0)
setProgressMessage(undefined)
@@ -411,18 +488,21 @@ export function useClientRender(): UseClientRenderReturn {
setTotalFrames(undefined)
setStatus('idle')
setError(null)
- const previousResult = resultRef.current
- resultRef.current = null
- void releaseTemporaryExportOutput(previousResult)
+ const previousResultOwner = resultOwnerRef.current
+ resultOwnerRef.current = null
+ releaseOwnedResult(previousResultOwner)
setResult(null)
- }, [])
+ }, [abortActiveRun, releaseOwnedResult])
useEffect(
() => () => {
- void releaseTemporaryExportOutput(resultRef.current)
- resultRef.current = null
+ latestRunTokenRef.current++
+ abortActiveRun()
+ const ownedResult = resultOwnerRef.current
+ resultOwnerRef.current = null
+ releaseOwnedResult(ownedResult)
},
- [],
+ [abortActiveRun, releaseOwnedResult],
)
/**
diff --git a/src/features/export/hooks/use-render-queue-runner.ts b/src/features/export/hooks/use-render-queue-runner.ts
index 1c76aadb8..e280068a7 100644
--- a/src/features/export/hooks/use-render-queue-runner.ts
+++ b/src/features/export/hooks/use-render-queue-runner.ts
@@ -110,7 +110,10 @@ async function renderQueuedJob(job: RenderJob): Promise {
)
// Resolve mediaIds → blob URLs fresh at render time (export never proxies).
- composition.tracks = await resolveMediaUrls(composition.tracks, { useProxy: false })
+ composition.tracks = await resolveMediaUrls(composition.tracks, {
+ useProxy: false,
+ signal: controller.signal,
+ })
const { result, renderPath, fallbackReason } = await runRender({
clientSettings: job.clientSettings,
diff --git a/src/features/export/utils/canvas-render-orchestrator.ts b/src/features/export/utils/canvas-render-orchestrator.ts
index 7748689ad..c2ee46c25 100644
--- a/src/features/export/utils/canvas-render-orchestrator.ts
+++ b/src/features/export/utils/canvas-render-orchestrator.ts
@@ -28,7 +28,7 @@ import { createExportOutputTarget } from './export-output-target'
// Subsystems
import { createCompositionRenderer } from './client-render-engine'
-import { runPipelinedFrameLoop } from './pipelined-frame-loop'
+import { createPipelinedFrameLoopFailureState, runPipelinedFrameLoop } from './pipelined-frame-loop'
function getLog() {
return createLogger('CanvasRenderOrchestrator')
@@ -714,6 +714,7 @@ export async function renderComposition(options: RenderEngineOptions): Promise {
if (videoRenderingStarted) return
const boundedSeconds = Math.min(durationSeconds, completedSeconds)
@@ -760,6 +761,7 @@ export async function renderComposition(options: RenderEngineOptions): Promise {
audioError = error
+ frameLoopFailureState.reportFailure(error)
})
onProgress({
@@ -787,21 +789,31 @@ export async function renderComposition(options: RenderEngineOptions): Promise audioError,
- renderFrame: async (frame) => {
- await renderer.renderFrame(frame)
- // Scale to output resolution if needed
- if (needsScaling) {
- outputCtx.clearRect(0, 0, exportWidth, exportHeight)
- outputCtx.drawImage(renderCanvas, 0, 0, exportWidth, exportHeight)
+ failureState: frameLoopFailureState,
+ renderFrame: async (frame, reportFailure) => {
+ try {
+ await renderer.renderFrame(frame)
+ // Scale to output resolution if needed
+ if (needsScaling) {
+ outputCtx.clearRect(0, 0, exportWidth, exportHeight)
+ outputCtx.drawImage(renderCanvas, 0, 0, exportWidth, exportHeight)
+ }
+ } catch (error) {
+ reportFailure(error)
+ throw error
}
},
// VideoSampleSource does NOT close samples (unlike CanvasSource) — the
// loop closes each sample to release the VideoFrame's GPU memory.
captureSample: (frame) =>
new VideoSample(outputCanvas, { timestamp: frame / fps, duration: 1 / fps }),
- encodeSample: (sample, keyFrame) =>
- keyFrame ? videoSource.add(sample, { keyFrame: true }) : videoSource.add(sample),
+ encodeSample: (sample, keyFrame, reportFailure) => {
+ const encoding = keyFrame
+ ? videoSource.add(sample, { keyFrame: true })
+ : videoSource.add(sample)
+ void encoding.catch(reportFailure)
+ return encoding
+ },
onAbort: () => output.cancel(),
onFrameProgress: (frame) => {
onProgress({
diff --git a/src/features/export/utils/canvas-video-extractor.test.ts b/src/features/export/utils/canvas-video-extractor.test.ts
index 854060020..67c6756d5 100644
--- a/src/features/export/utils/canvas-video-extractor.test.ts
+++ b/src/features/export/utils/canvas-video-extractor.test.ts
@@ -1,7 +1,10 @@
-import { describe, expect, it, vi } from 'vite-plus/test'
+import { afterEach, describe, expect, it, vi } from 'vite-plus/test'
import { VideoFrameExtractor } from './canvas-video-extractor'
describe('VideoFrameExtractor lifecycle', () => {
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
it('closes a sample yielded after the extractor was disposed', async () => {
let resolveNext!: (result: IteratorResult<{ close: () => void }>) => void
const nextResult = new Promise void }>>((resolve) => {
@@ -34,4 +37,45 @@ describe('VideoFrameExtractor lifecycle', () => {
expect(sample.close).toHaveBeenCalledTimes(1)
expect(iterator.return).toHaveBeenCalledTimes(1)
})
+
+ it('reports an expected no-sample fallback as structured debug telemetry only', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const debug = vi.spyOn(console, 'log').mockImplementation(() => undefined)
+ const extractor = new VideoFrameExtractor('blob:test', 'test-item')
+ const internals = extractor as unknown as {
+ lastFailureKind: 'none' | 'no-sample' | 'decode-error'
+ reportDrawFailure: (timestamp: number, clampedTime: number, error: unknown) => boolean
+ }
+ internals.lastFailureKind = 'no-sample'
+
+ expect(internals.reportDrawFailure(1, 0.99, null)).toBe(false)
+
+ expect(warn).not.toHaveBeenCalled()
+ expect(debug).toHaveBeenCalledWith(
+ '[VideoFrameExtractor] Mediabunny frame extraction fallback',
+ expect.objectContaining({ itemId: 'test-item', reason: 'no-sample', failures: 1 }),
+ )
+ })
+
+ it('keeps a genuine decode failure visible as one clear warning', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const extractor = new VideoFrameExtractor('blob:test', 'test-item')
+ const internals = extractor as unknown as {
+ lastFailureKind: 'none' | 'no-sample' | 'decode-error'
+ reportDrawFailure: (timestamp: number, clampedTime: number, error: unknown) => boolean
+ }
+ internals.lastFailureKind = 'decode-error'
+
+ internals.reportDrawFailure(1, 0.99, new Error('decoder exploded'))
+
+ expect(warn).toHaveBeenCalledTimes(1)
+ expect(warn).toHaveBeenCalledWith(
+ '[VideoFrameExtractor] Mediabunny frame extraction failed',
+ expect.objectContaining({
+ itemId: 'test-item',
+ reason: 'decode-error',
+ error: 'decoder exploded',
+ }),
+ )
+ })
})
diff --git a/src/features/export/utils/canvas-video-extractor.ts b/src/features/export/utils/canvas-video-extractor.ts
index d452fabec..534ba664a 100644
--- a/src/features/export/utils/canvas-video-extractor.ts
+++ b/src/features/export/utils/canvas-video-extractor.ts
@@ -139,11 +139,10 @@ export class VideoFrameExtractor {
if (typeof this.videoTrack.canDecode === 'function') {
const decodable = await this.videoTrack.canDecode()
if (!decodable) {
- this.logInitFailure(
- 'Video track is not decodable via mediabunny/WebCodecs',
- { itemId: this.itemId },
- 'warn',
- )
+ log.debug('Skipping unsupported mediabunny decode path', {
+ itemId: this.itemId,
+ reason: 'track-not-decodable',
+ })
return false
}
}
@@ -597,7 +596,9 @@ export class VideoFrameExtractor {
error: error instanceof Error ? error.message : String(error),
}
- if (shouldWarn && !this.options.logFrameFailuresAsDebug) {
+ if (this.lastFailureKind === 'no-sample') {
+ log.debug('Mediabunny frame extraction fallback', logData)
+ } else if (shouldWarn && !this.options.logFrameFailuresAsDebug) {
log.warn('Mediabunny frame extraction failed', logData)
} else {
log.debug('Mediabunny frame extraction failed', logData)
diff --git a/src/features/export/utils/client-render-engine.test.ts b/src/features/export/utils/client-render-engine.test.ts
index 4015a78b4..b6945a4de 100644
--- a/src/features/export/utils/client-render-engine.test.ts
+++ b/src/features/export/utils/client-render-engine.test.ts
@@ -403,7 +403,7 @@ describe('selectPreviewVideoSource', () => {
).toEqual(['blob:original', null, null])
})
- it('includes cached proxies when proxy media is selected', () => {
+ it('keeps the authoritative current source ahead of stale item and registered URLs', () => {
expect(
getPreviewVideoSourceCandidates({
itemSource: 'blob:proxy',
@@ -412,7 +412,21 @@ describe('selectPreviewVideoSource', () => {
cachedSource: 'blob:source',
useProxyMedia: true,
}),
- ).toEqual(['blob:proxy', 'blob:proxy', 'blob:registered-proxy', 'blob:source'])
+ ).toEqual(['blob:proxy', 'blob:source', 'blob:registered-proxy', 'blob:proxy'])
+ })
+
+ it('selects a relinked current source instead of stale registered and item fallbacks', () => {
+ expect(
+ selectPreviewVideoSource({
+ candidates: getPreviewVideoSourceCandidates({
+ itemSource: 'blob:old-item',
+ proxySource: null,
+ registeredSource: 'blob:old-registered',
+ cachedSource: 'blob:new-current',
+ useProxyMedia: true,
+ }),
+ }),
+ ).toBe('blob:new-current')
})
it('selects the cached proxy when a compound item still carries its original source', () => {
diff --git a/src/features/export/utils/client-render-engine.ts b/src/features/export/utils/client-render-engine.ts
index 01924ad3f..f12c1d4da 100644
--- a/src/features/export/utils/client-render-engine.ts
+++ b/src/features/export/utils/client-render-engine.ts
@@ -210,7 +210,7 @@ export function getPreviewVideoSourceCandidates({
useProxyMedia: boolean
}): Array {
if (useProxyMedia) {
- return [proxySource, itemSource, registeredSource, cachedSource]
+ return [proxySource, cachedSource, registeredSource, itemSource]
}
// blobUrlManager owns the current original-media URL and is also what the
@@ -305,12 +305,15 @@ function selectComparisonVideoSource(
registeredSource: string | undefined,
useProxyMedia: boolean,
): string | null {
- return selectFirstMediaSource([
- registeredSource,
- useProxyMedia && item.mediaId ? resolveProxyUrl(item.mediaId) : null,
- item.src,
- item.mediaId ? blobUrlManager.get(item.mediaId) : null,
- ])
+ return selectFirstMediaSource(
+ getPreviewVideoSourceCandidates({
+ itemSource: item.src,
+ proxySource: item.mediaId ? resolveProxyUrl(item.mediaId) : null,
+ registeredSource,
+ cachedSource: item.mediaId ? blobUrlManager.get(item.mediaId) : null,
+ useProxyMedia,
+ }),
+ )
}
function selectExportVideoSource(
@@ -385,20 +388,26 @@ function waitForFallbackVideoReady(options: {
})
}
+function resolveRendererProxySource(
+ item: VideoItem | ImageItem | LottieItem,
+ useProxyMedia: boolean,
+): string | null {
+ if (!useProxyMedia || item.type !== 'video' || !item.mediaId) return null
+ return resolveProxyUrl(item.mediaId)
+}
+
async function resolveRendererMediaSource(
item: VideoItem | ImageItem | LottieItem,
useProxyMedia: boolean,
signal?: AbortSignal,
): Promise {
throwIfAborted(signal)
- if (useProxyMedia && item.type === 'video' && item.mediaId) {
- const proxyUrl = resolveProxyUrl(item.mediaId)
- if (proxyUrl) return proxyUrl
- }
- if (item.src) return item.src
- if (!item.mediaId) return null
+ const proxyUrl = resolveRendererProxySource(item, useProxyMedia)
+ if (proxyUrl) return proxyUrl
+ if (!item.mediaId) return item.src ?? null
const cachedUrl = blobUrlManager.get(item.mediaId)
if (cachedUrl) return cachedUrl
+ if (item.src) return item.src
const resolvedUrl = await resolveMediaUrl(item.mediaId)
throwIfAborted(signal)
return resolvedUrl || null
diff --git a/src/features/export/utils/pipelined-frame-loop.test.ts b/src/features/export/utils/pipelined-frame-loop.test.ts
index e4e503dce..8b5a0e7c1 100644
--- a/src/features/export/utils/pipelined-frame-loop.test.ts
+++ b/src/features/export/utils/pipelined-frame-loop.test.ts
@@ -5,8 +5,12 @@
// shape on mocks without importing production code). End-to-end protection of
// the full orchestrator remains the headless chrome e2e (headless/test.mjs).
-import { describe, it, expect } from 'vite-plus/test'
-import { runPipelinedFrameLoop } from './pipelined-frame-loop'
+import { describe, it, expect, vi } from 'vite-plus/test'
+import {
+ createPipelinedFrameLoopFailureState,
+ runPipelinedFrameLoop,
+ type PipelinedFrameLoopFailureState,
+} from './pipelined-frame-loop'
interface Deferred {
promise: Promise
@@ -36,23 +40,31 @@ interface FakeSample {
interface HarnessOptions {
signal?: AbortSignal
- getPendingError?: () => unknown
+ failureState?: PipelinedFrameLoopFailureState
renderImpl?: (frame: number) => void | Promise
encodeImpl?: (sample: FakeSample, keyFrame: boolean) => Promise
+ closeImpl?: (sample: FakeSample) => void
+ onAbortImpl?: () => void | Promise
}
function createHarness(totalFrames: number, opts: HarnessOptions = {}) {
const events: string[] = []
const samples: FakeSample[] = []
+ const failureState = opts.failureState ?? createPipelinedFrameLoopFailureState()
const run = () =>
runPipelinedFrameLoop({
totalFrames,
signal: opts.signal,
- getPendingError: opts.getPendingError,
- renderFrame: async (frame) => {
+ failureState,
+ renderFrame: async (frame, reportFailure) => {
events.push(`render-${frame}`)
- await opts.renderImpl?.(frame)
+ try {
+ await opts.renderImpl?.(frame)
+ } catch (error) {
+ reportFailure(error)
+ throw error
+ }
},
captureSample: (frame) => {
const sample: FakeSample = {
@@ -61,27 +73,31 @@ function createHarness(totalFrames: number, opts: HarnessOptions = {}) {
close() {
this.closed = true
events.push(`close-${frame}`)
+ opts.closeImpl?.(this)
},
}
samples.push(sample)
events.push(`capture-${frame}`)
return sample
},
- encodeSample: (sample, keyFrame) => {
+ encodeSample: (sample, keyFrame, reportFailure) => {
events.push(`encode-start-${sample.frame}${keyFrame ? '-key' : ''}`)
- return (opts.encodeImpl?.(sample, keyFrame) ?? Promise.resolve()).then(() => {
+ const encoding = opts.encodeImpl?.(sample, keyFrame) ?? Promise.resolve()
+ void encoding.catch(reportFailure)
+ return encoding.then(() => {
events.push(`encode-end-${sample.frame}`)
})
},
onAbort: async () => {
events.push('abort-cancel')
+ await opts.onAbortImpl?.()
},
onFrameProgress: (frame) => {
events.push(`progress-${frame}`)
},
})
- return { events, samples, run }
+ return { events, samples, failureState, run }
}
const indexOf = (events: string[], event: string) => {
@@ -90,7 +106,282 @@ const indexOf = (events: string[], event: string) => {
return index
}
+type FailureSource = 'render' | 'encode' | 'abort' | 'audio'
+
+interface FailureOrderCase {
+ name: string
+ first: FailureSource
+ second: FailureSource
+ expected: FailureSource
+}
+
+const failureOrderCases: FailureOrderCase[] = [
+ { name: 'render first then abort', first: 'render', second: 'abort', expected: 'render' },
+ { name: 'render first then audio', first: 'render', second: 'audio', expected: 'render' },
+ { name: 'encode first then abort', first: 'encode', second: 'abort', expected: 'encode' },
+ { name: 'abort first then render', first: 'abort', second: 'render', expected: 'abort' },
+ { name: 'abort first then encode', first: 'abort', second: 'encode', expected: 'abort' },
+ { name: 'audio first then render', first: 'audio', second: 'render', expected: 'audio' },
+]
+
+const failureOrderMatrix = failureOrderCases.flatMap((testCase) => [
+ { ...testCase, timing: 'same turn' as const },
+ { ...testCase, timing: 'one microtask apart' as const },
+])
+
describe('runPipelinedFrameLoop', () => {
+ it.each(failureOrderMatrix)(
+ 'preserves source order: $name ($timing)',
+ async ({ first, second, expected, timing }) => {
+ const controller = new AbortController()
+ const render = deferred()
+ const encode = deferred()
+ const audio = deferred()
+ const errors: Record = {
+ render: new Error('render source failed'),
+ encode: new Error('encode source failed'),
+ audio: new Error('audio source failed'),
+ abort: null,
+ }
+ const cleanupError = new Error('abort cleanup must not mask the primary failure')
+ const failureState = createPipelinedFrameLoopFailureState()
+ const observedAudio = audio.promise.then(
+ () => undefined,
+ (error: unknown) => failureState.reportFailure(error),
+ )
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ const removeListener = vi.spyOn(controller.signal, 'removeEventListener')
+ process.on('unhandledRejection', onUnhandledRejection)
+
+ let renderSettled = false
+ let encodeSettled = false
+ let audioSettled = false
+ let outcome: Promise | undefined
+
+ const fire = (source: FailureSource) => {
+ switch (source) {
+ case 'render':
+ renderSettled = true
+ render.reject(errors.render)
+ break
+ case 'encode':
+ encodeSettled = true
+ encode.reject(errors.encode)
+ break
+ case 'audio':
+ audioSettled = true
+ audio.reject(errors.audio)
+ break
+ case 'abort':
+ controller.abort()
+ break
+ }
+ }
+
+ try {
+ const { events, samples, run } = createHarness(2, {
+ signal: controller.signal,
+ failureState,
+ renderImpl: (frame) => (frame === 1 ? render.promise : undefined),
+ encodeImpl: () => encode.promise,
+ onAbortImpl: () => {
+ throw cleanupError
+ },
+ })
+
+ outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ await tick()
+ expect(events).toContain('render-1')
+
+ // Calls earlier in this list define same-turn ties. Promise reactions
+ // and the queued abort publication retain that source enqueue order.
+ fire(first)
+ if (timing === 'one microtask apart') await Promise.resolve()
+ fire(second)
+
+ if (!renderSettled) render.resolve()
+ if (!encodeSettled) encode.resolve()
+ if (!audioSettled) audio.resolve()
+
+ const error = await outcome
+ if (expected === 'abort') {
+ expect(error).toBeInstanceOf(DOMException)
+ expect((error as DOMException).name).toBe('AbortError')
+ } else {
+ expect(error).toBe(errors[expected])
+ }
+
+ await observedAudio
+ await tick()
+ expect(unhandledRejections).toEqual([])
+ expect(samples).toHaveLength(1)
+ expect(samples[0]?.closed).toBe(true)
+ expect(events).toContain('close-0')
+ expect(events.includes('abort-cancel')).toBe(controller.signal.aborted)
+ if (controller.signal.aborted) {
+ expect(indexOf(events, 'close-0')).toBeLessThan(indexOf(events, 'abort-cancel'))
+ }
+ expect(removeListener).toHaveBeenCalledWith('abort', expect.any(Function))
+ } finally {
+ controller.abort()
+ render.resolve()
+ encode.resolve()
+ audio.resolve()
+ await observedAudio
+ await outcome
+ removeListener.mockRestore()
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ },
+ )
+
+ it('preserves a render rejection boundary over queued encode-success cleanup', async () => {
+ const renderError = new Error('render source rejected first')
+ const closeError = new Error('sample close ran before the render observer')
+ let closeCount = 0
+ const sample: FakeSample = {
+ frame: 0,
+ closed: false,
+ close() {
+ closeCount++
+ this.closed = true
+ throw closeError
+ },
+ }
+
+ const outcome = runPipelinedFrameLoop({
+ totalFrames: 2,
+ renderFrame: (frame, reportFailure) => {
+ if (frame === 0) return Promise.resolve()
+
+ // The encode-success continuation is already queued, so it will run
+ // sample.close() before this rejection observer. The render rejection
+ // is nevertheless a primary source boundary and must own the result.
+ const rendering = Promise.reject(renderError)
+ void rendering.catch(reportFailure)
+ return rendering
+ },
+ captureSample: () => sample,
+ encodeSample: (_sample, _keyFrame, reportFailure) => {
+ const encoding = Promise.resolve()
+ void encoding.catch(reportFailure)
+ return encoding
+ },
+ onAbort: () => Promise.resolve(),
+ onFrameProgress: () => undefined,
+ }).then(
+ () => null,
+ (error: unknown) => error,
+ )
+
+ const error = await outcome
+ expect(error).toBe(renderError)
+ expect(closeCount).toBe(1)
+ })
+
+ it('preserves an abort boundary over a later synchronous render throw', async () => {
+ const controller = new AbortController()
+ const renderError = new Error('render threw after abort')
+ const onAbort = vi.fn(() => Promise.resolve())
+
+ const error = await runPipelinedFrameLoop({
+ totalFrames: 1,
+ signal: controller.signal,
+ renderFrame: () => {
+ controller.abort()
+ throw renderError
+ },
+ captureSample: () => {
+ throw new Error('capture must not run')
+ },
+ encodeSample: () => Promise.resolve(),
+ onAbort,
+ onFrameProgress: () => undefined,
+ }).then(
+ () => null,
+ (failure: unknown) => failure,
+ )
+
+ expect(error).toBeInstanceOf(DOMException)
+ expect((error as DOMException).name).toBe('AbortError')
+ expect(onAbort).toHaveBeenCalledOnce()
+ })
+
+ it('lets an already-queued render rejection observer beat a later abort publication', async () => {
+ const controller = new AbortController()
+ const renderError = new Error('render rejected before abort')
+
+ const error = await runPipelinedFrameLoop({
+ totalFrames: 1,
+ signal: controller.signal,
+ renderFrame: (_frame, reportFailure) => {
+ const rendering = Promise.reject(renderError)
+ void rendering.catch(reportFailure)
+ controller.abort()
+ return rendering
+ },
+ captureSample: () => {
+ throw new Error('capture must not run')
+ },
+ encodeSample: () => Promise.resolve(),
+ onAbort: () => Promise.resolve(),
+ onFrameProgress: () => undefined,
+ }).then(
+ () => null,
+ (failure: unknown) => failure,
+ )
+
+ expect(error).toBe(renderError)
+ })
+
+ it('preserves an established primary when listener removal throws', async () => {
+ const controller = new AbortController()
+ const renderError = new Error('primary render failure')
+ const listenerError = new Error('listener removal failed')
+ const removeListener = vi
+ .spyOn(controller.signal, 'removeEventListener')
+ .mockImplementation(() => {
+ throw listenerError
+ })
+
+ try {
+ const { run } = createHarness(1, {
+ signal: controller.signal,
+ renderImpl: () => {
+ throw renderError
+ },
+ })
+
+ await expect(run()).rejects.toBe(renderError)
+ expect(removeListener).toHaveBeenCalledOnce()
+ } finally {
+ removeListener.mockRestore()
+ }
+ })
+
+ it('surfaces listener-removal failure when there is no primary failure', async () => {
+ const controller = new AbortController()
+ const listenerError = new Error('listener removal failed')
+ const removeListener = vi
+ .spyOn(controller.signal, 'removeEventListener')
+ .mockImplementation(() => {
+ throw listenerError
+ })
+
+ try {
+ const { run } = createHarness(1, { signal: controller.signal })
+
+ await expect(run()).rejects.toBe(listenerError)
+ expect(removeListener).toHaveBeenCalledOnce()
+ } finally {
+ removeListener.mockRestore()
+ }
+ })
+
it('encodes all frames in order and closes every sample', async () => {
const { events, samples, run } = createHarness(5)
await run()
@@ -182,6 +473,253 @@ describe('runPipelinedFrameLoop', () => {
expect(samples[1]?.closed).toBe(true)
})
+ it('observes an immediate encode rejection while the next render stays pending', async () => {
+ const encoderError = new Error('encoder rejected immediately')
+ const nextRender = deferred()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ let outcome: Promise | undefined
+
+ try {
+ const { events, samples, run } = createHarness(2, {
+ renderImpl: (frame) => (frame === 1 ? nextRender.promise : undefined),
+ encodeImpl: (sample) =>
+ sample.frame === 0 ? Promise.reject(encoderError) : Promise.resolve(),
+ })
+
+ outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ await tick()
+ await tick()
+
+ expect(events).toContain('render-1')
+ expect(unhandledRejections).toEqual([])
+
+ nextRender.resolve()
+ expect(await outcome).toBe(encoderError)
+ expect(samples[0]?.closed).toBe(true)
+ } finally {
+ nextRender.resolve()
+ await outcome
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
+ it('preserves an earlier audio error when video rejects during a pending render', async () => {
+ const audioError = new Error('audio task failed first')
+ const encoderError = new Error('video encoder failed later')
+ const encode = deferred()
+ const nextRender = deferred()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ let outcome: Promise | undefined
+
+ try {
+ const { events, samples, failureState, run } = createHarness(2, {
+ renderImpl: (frame) => (frame === 1 ? nextRender.promise : undefined),
+ encodeImpl: () => encode.promise,
+ })
+
+ outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ await tick()
+ expect(events).toContain('render-1')
+
+ failureState.reportFailure(audioError)
+ encode.reject(encoderError)
+ await tick()
+ expect(unhandledRejections).toEqual([])
+
+ nextRender.resolve()
+ expect(await outcome).toBe(audioError)
+ expect(samples[0]?.closed).toBe(true)
+ } finally {
+ nextRender.resolve()
+ encode.resolve()
+ await outcome
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
+ it('preserves earlier audio over abort and a rejecting render before encode drains', async () => {
+ const controller = new AbortController()
+ const audioError = new Error('audio task failed first')
+ const renderError = new Error('render failed later')
+ const cleanupError = new Error('sample cleanup failed last')
+ const encode = deferred()
+ const nextRender = deferred()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ let outcome: Promise | undefined
+
+ try {
+ const { events, samples, failureState, run } = createHarness(2, {
+ signal: controller.signal,
+ renderImpl: (frame) => (frame === 1 ? nextRender.promise : undefined),
+ encodeImpl: () => encode.promise,
+ closeImpl: () => {
+ throw cleanupError
+ },
+ })
+
+ let settled = false
+ outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ void outcome.finally(() => {
+ settled = true
+ })
+ await tick()
+ expect(events).toContain('render-1')
+
+ failureState.reportFailure(audioError)
+ controller.abort()
+ nextRender.reject(renderError)
+ await tick()
+ expect(settled).toBe(false)
+ expect(unhandledRejections).toEqual([])
+
+ encode.resolve()
+ expect(await outcome).toBe(audioError)
+ expect(events).toContain('abort-cancel')
+ expect(samples[0]?.closed).toBe(true)
+ await tick()
+ expect(unhandledRejections).toEqual([])
+ } finally {
+ controller.abort()
+ nextRender.resolve()
+ encode.resolve()
+ await outcome
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
+ it('preserves the video error when sample cleanup and rendering fail later', async () => {
+ const encoderError = new Error('video encoder failed first')
+ const cleanupError = new Error('sample cleanup failed later')
+ const renderError = new Error('render failed last')
+ const encode = deferred()
+ const nextRender = deferred()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ let outcome: Promise | undefined
+
+ try {
+ const { events, samples, run } = createHarness(2, {
+ renderImpl: (frame) => (frame === 1 ? nextRender.promise : undefined),
+ encodeImpl: () => encode.promise,
+ closeImpl: () => {
+ throw cleanupError
+ },
+ })
+
+ outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ await tick()
+ expect(events).toContain('render-1')
+
+ encode.reject(encoderError)
+ await tick()
+ nextRender.reject(renderError)
+
+ expect(await outcome).toBe(encoderError)
+ await tick()
+ expect(unhandledRejections).toEqual([])
+ expect(samples[0]?.closed).toBe(true)
+ } finally {
+ encode.resolve()
+ nextRender.resolve()
+ await outcome
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
+ it('preserves a render error while observing a late encoder rejection', async () => {
+ const renderError = new Error('render failed')
+ const encoderError = new Error('encoder failed after render')
+ const encode = deferred()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+
+ try {
+ const { events, samples, run } = createHarness(3, {
+ renderImpl: (frame) => {
+ if (frame === 1) throw renderError
+ },
+ encodeImpl: () => encode.promise,
+ })
+
+ const outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ await tick()
+ expect(events).toContain('render-1')
+
+ encode.reject(encoderError)
+ expect(await outcome).toBe(renderError)
+ await tick()
+ expect(unhandledRejections).toEqual([])
+ expect(samples[0]?.closed).toBe(true)
+ } finally {
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
+ it('preserves a pending error while observing a late encoder rejection', async () => {
+ const pendingError = new Error('audio task failed')
+ const encoderError = new Error('encoder failed after pending error')
+ const encodes: Deferred[] = []
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ const failureState = createPipelinedFrameLoopFailureState()
+
+ try {
+ const { events, samples, run } = createHarness(4, {
+ failureState,
+ renderImpl: (frame) => {
+ if (frame === 1) failureState.reportFailure(pendingError)
+ },
+ encodeImpl: () => {
+ const encode = deferred()
+ encodes.push(encode)
+ return encode.promise
+ },
+ })
+
+ const outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ await tick()
+ expect(events).toContain('render-1')
+ encodes[0]?.resolve()
+ await tick()
+ expect(events).toContain('encode-start-1')
+
+ encodes[1]?.reject(encoderError)
+ expect(await outcome).toBe(pendingError)
+ await tick()
+ expect(unhandledRejections).toEqual([])
+ expect(samples[1]?.closed).toBe(true)
+ } finally {
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
it('honours an abort signalled before the loop starts', async () => {
const controller = new AbortController()
controller.abort()
@@ -236,13 +774,121 @@ describe('runPipelinedFrameLoop', () => {
expect(events).not.toContain('capture-2')
})
+ it('observes and drains a pending encode when abort wins during rendering', async () => {
+ const controller = new AbortController()
+ const encoderError = new Error('encoder failed after abort')
+ const encode = deferred()
+ const nextRender = deferred()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ let outcome: Promise | undefined
+
+ try {
+ const { events, samples, run } = createHarness(2, {
+ signal: controller.signal,
+ renderImpl: (frame) => (frame === 1 ? nextRender.promise : undefined),
+ encodeImpl: () => encode.promise,
+ })
+
+ outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ await tick()
+ expect(events).toContain('render-1')
+
+ controller.abort()
+ encode.reject(encoderError)
+ await tick()
+ expect(unhandledRejections).toEqual([])
+
+ nextRender.resolve()
+ const error = await outcome
+ expect(error).toBeInstanceOf(DOMException)
+ expect((error as DOMException).name).toBe('AbortError')
+ expect(events).toContain('abort-cancel')
+ expect(samples[0]?.closed).toBe(true)
+ } finally {
+ controller.abort()
+ encode.resolve()
+ nextRender.resolve()
+ await outcome
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
+ it('preserves earlier abort over audio and a rejecting render before encode drains', async () => {
+ const controller = new AbortController()
+ const audioError = new Error('audio task failed later')
+ const renderError = new Error('render failed later')
+ const abortCleanupError = new Error('abort cleanup failed last')
+ const encode = deferred()
+ const nextRender = deferred()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ let outcome: Promise | undefined
+
+ try {
+ const audio = deferred()
+ const failureState = createPipelinedFrameLoopFailureState()
+ const observedAudio = audio.promise.catch((error: unknown) => {
+ failureState.reportFailure(error)
+ })
+ const { events, samples, run } = createHarness(2, {
+ signal: controller.signal,
+ failureState,
+ renderImpl: (frame) => (frame === 1 ? nextRender.promise : undefined),
+ encodeImpl: () => encode.promise,
+ onAbortImpl: () => {
+ throw abortCleanupError
+ },
+ })
+
+ let settled = false
+ outcome = run().then(
+ () => null,
+ (error: unknown) => error,
+ )
+ void outcome.finally(() => {
+ settled = true
+ })
+ await tick()
+ expect(events).toContain('render-1')
+
+ controller.abort()
+ audio.reject(audioError)
+ nextRender.reject(renderError)
+ await tick()
+ expect(settled).toBe(false)
+ expect(unhandledRejections).toEqual([])
+
+ encode.resolve()
+ const error = await outcome
+ expect(error).toBeInstanceOf(DOMException)
+ expect((error as DOMException).name).toBe('AbortError')
+ expect(events).toContain('abort-cancel')
+ expect(samples[0]?.closed).toBe(true)
+ await observedAudio
+ await tick()
+ expect(unhandledRejections).toEqual([])
+ } finally {
+ controller.abort()
+ nextRender.resolve()
+ encode.resolve()
+ await outcome
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
it('throws a pending error at the top of the next iteration', async () => {
const pendingError = new Error('audio task failed')
- let raised: unknown
+ const failureState = createPipelinedFrameLoopFailureState()
const { events, run } = createHarness(5, {
- getPendingError: () => raised,
+ failureState,
renderImpl: (frame) => {
- if (frame === 1) raised = pendingError
+ if (frame === 1) failureState.reportFailure(pendingError)
},
})
@@ -251,20 +897,20 @@ describe('runPipelinedFrameLoop', () => {
expect(events).not.toContain('render-2')
})
- it('ignores falsy pending errors (truthiness semantics)', async () => {
- for (const falsy of [undefined, '', 0, null]) {
- const { samples, run } = createHarness(2, { getPendingError: () => falsy })
- await run()
- expect(samples).toHaveLength(2)
- }
+ it('continues until an external source publishes a failure', async () => {
+ const { samples, run } = createHarness(2)
+ await run()
+ expect(samples).toHaveLength(2)
})
it('resolves immediately for zero frames without touching any callback', async () => {
const controller = new AbortController()
controller.abort()
+ const failureState = createPipelinedFrameLoopFailureState()
+ failureState.reportFailure(new Error('never checked'))
const { events, run } = createHarness(0, {
signal: controller.signal,
- getPendingError: () => new Error('never checked'),
+ failureState,
})
await run()
// Pre-loop abort/error checks are the caller's responsibility.
diff --git a/src/features/export/utils/pipelined-frame-loop.ts b/src/features/export/utils/pipelined-frame-loop.ts
index 583a5fb36..e13a5c245 100644
--- a/src/features/export/utils/pipelined-frame-loop.ts
+++ b/src/features/export/utils/pipelined-frame-loop.ts
@@ -7,29 +7,76 @@
* previous encode has drained, so frames reach the encoder in order.
*
* Behavior must stay bit-identical to the original inline loop — this is the
- * export hot path. Known pre-existing hole kept on purpose: when the loop
- * exits via a non-abort error (renderFrame throw or pending error) while an
- * encode is in flight, that encode promise is never awaited; only the abort
- * path drains it.
+ * export hot path. Every exit drains an in-flight encode so its sample closes
+ * and its rejection is observed. Primary render, encode, audio, and abort
+ * failures retain their source-boundary order. Cleanup failures are tracked
+ * separately and surface only when no primary operation failed.
*/
export interface CloseableSample {
close(): void
}
+interface RecordedFailure {
+ error: unknown
+}
+
+export interface PipelinedFrameLoopFailureState {
+ readonly firstFailure: RecordedFailure | null
+ readonly firstPrimaryFailure: RecordedFailure | null
+ readonly firstCleanupFailure: RecordedFailure | null
+ reportFailure(error: unknown): void
+ reportCleanupFailure(error: unknown): void
+}
+
+/**
+ * Shared failure ownership for concurrently running export sources.
+ *
+ * Sources publish when their failure becomes observable. Promise sources must
+ * attach their rejection observer immediately; abort publication is queued as
+ * a microtask so same-turn promise rejection and abort events are ordered by
+ * the source events that queued their observers, not by a synchronous abort
+ * listener racing ahead of already-fired promise rejections. Cleanup has its
+ * own first-error latch so continuation order cannot let cleanup mask a
+ * primary source failure.
+ */
+export function createPipelinedFrameLoopFailureState(): PipelinedFrameLoopFailureState {
+ let firstPrimaryFailure: RecordedFailure | null = null
+ let firstCleanupFailure: RecordedFailure | null = null
+ return {
+ get firstFailure() {
+ return firstPrimaryFailure ?? firstCleanupFailure
+ },
+ get firstPrimaryFailure() {
+ return firstPrimaryFailure
+ },
+ get firstCleanupFailure() {
+ return firstCleanupFailure
+ },
+ reportFailure(error) {
+ firstPrimaryFailure ??= { error }
+ },
+ reportCleanupFailure(error) {
+ firstCleanupFailure ??= { error }
+ },
+ }
+}
+
export interface PipelinedFrameLoopDeps {
totalFrames: number
signal?: AbortSignal
/**
- * Read (not throw) a pending async error, e.g. a failed audio task.
- * Checked with a truthiness test at the top of every iteration.
+ * Shared source-event latch. An independently running source such as audio
+ * must attach a rejection observer immediately and publish into this state.
*/
- getPendingError?: () => unknown
+ failureState?: PipelinedFrameLoopFailureState
/**
* Render the frame to the capture surface, including any scale-to-output
- * blit. Overlaps with the previous frame's in-flight encode.
+ * blit. Overlaps with the previous frame's in-flight encode. The callback
+ * must be invoked by the rejection observer attached directly to the source
+ * promise, before rethrowing through any async wrapper.
*/
- renderFrame: (frame: number) => Promise
+ renderFrame: (frame: number, reportFailure: (error: unknown) => void) => Promise
/**
* Snapshot the capture surface (e.g. VideoSample construction). Called
* strictly after the previous encode has drained; must stay synchronous.
@@ -37,25 +84,84 @@ export interface PipelinedFrameLoopDeps {
captureSample: (frame: number) => S
/**
* Feed the sample to the encoder. `keyFrame` is true only for frame 0.
- * The loop closes the sample when the returned promise settles.
+ * The loop closes the sample when the returned promise settles. As with
+ * renderFrame, report a rejection from an observer on the source promise.
*/
- encodeSample: (sample: S, keyFrame: boolean) => Promise
+ encodeSample: (
+ sample: S,
+ keyFrame: boolean,
+ reportFailure: (error: unknown) => void,
+ ) => Promise
/**
* Abort path: called after the in-flight encode has been drained (its
- * errors discarded), before the AbortError is thrown.
+ * errors observed), before the selected failure is thrown.
*/
onAbort: () => Promise
/** Called once per frame, synchronously after its encode is kicked off. */
onFrameProgress: (frame: number) => void
}
+interface OperationSettlement {
+ status: 'fulfilled' | 'rejected'
+ reason?: unknown
+}
+
+async function encodeAndCloseSample(
+ sample: S,
+ keyFrame: boolean,
+ encodeSample: (
+ sample: S,
+ keyFrame: boolean,
+ reportFailure: (error: unknown) => void,
+ ) => Promise,
+ recordSettledFailure: (error: unknown) => void,
+ recordSynchronousFailure: (error: unknown) => Promise,
+ recordCleanupFailure: (error: unknown) => void,
+): Promise {
+ let failure: RecordedFailure | null = null
+ let encoding: Promise | null = null
+ try {
+ encoding = encodeSample(sample, keyFrame, recordSettledFailure)
+ } catch (error) {
+ failure = { error }
+ await recordSynchronousFailure(error)
+ }
+
+ if (encoding) {
+ const settlement: OperationSettlement = await encoding.then(
+ (): OperationSettlement => ({ status: 'fulfilled' }),
+ (error: unknown): OperationSettlement => {
+ recordSettledFailure(error)
+ return { status: 'rejected', reason: error }
+ },
+ )
+ if (settlement.status === 'rejected') failure = { error: settlement.reason }
+ }
+
+ try {
+ // The encoder does NOT close samples. We must close to release the
+ // underlying frame's GPU memory, otherwise the browser throttles after
+ // ~8-16 outstanding frames.
+ sample.close()
+ } catch (error) {
+ // If encoding already failed, it happened before cleanup and remains the
+ // failure represented by this settlement.
+ if (!failure) {
+ failure = { error }
+ recordCleanupFailure(error)
+ }
+ }
+
+ return failure ? { status: 'rejected', reason: failure.error } : { status: 'fulfilled' }
+}
+
export async function runPipelinedFrameLoop(
deps: PipelinedFrameLoopDeps,
): Promise {
const {
totalFrames,
signal,
- getPendingError,
+ failureState = createPipelinedFrameLoopFailureState(),
renderFrame,
captureSample,
encodeSample,
@@ -63,58 +169,180 @@ export async function runPipelinedFrameLoop(
onFrameProgress,
} = deps
- let pendingEncode: Promise | null = null
-
- for (let frame = 0; frame < totalFrames; frame++) {
- const pendingError = getPendingError?.()
- if (pendingError) throw pendingError
-
- // Check for abort — drain any in-flight encode first so the encoder
- // is idle before we cancel the output. Discard encoder errors since
- // we are aborting anyway and must always surface AbortError.
- if (signal?.aborted) {
- if (pendingEncode) {
- try {
- await pendingEncode
- } catch {
- /* discarded — aborting */
- }
- }
+ // The promise stored here never rejects. Encode and sample-cleanup failures
+ // are reflected into a settlement immediately, so an encoder rejection is
+ // observed even while renderFrame remains pending for another event turn.
+ let pendingEncode: Promise | null = null
+ let abortError: DOMException | null = null
+ let abortCleanupStarted = false
+ let abortPublicationQueued = false
+ let listenerActive = true
+
+ const recordFailure = (error: unknown) => {
+ failureState.reportFailure(error)
+ }
+
+ const recordCleanupFailure = (error: unknown) => {
+ failureState.reportCleanupFailure(error)
+ }
+
+ const getAbortError = () => {
+ abortError ??= new DOMException('Render cancelled', 'AbortError')
+ return abortError
+ }
+
+ const publishAbort = () => {
+ if (abortPublicationQueued) return
+ abortPublicationQueued = true
+ queueMicrotask(() => {
+ if (listenerActive) recordFailure(getAbortError())
+ })
+ }
+
+ const recordSynchronousFailure = async (error: unknown) => {
+ if (abortPublicationQueued) {
+ // Abort reserves its boundary synchronously but publishes in a
+ // microtask. Yield once so an observer queued before the abort can
+ // publish first, while the abort itself stays ahead of this later
+ // synchronous throw.
+ await Promise.resolve()
+ }
+ recordFailure(error)
+ }
+
+ const drainPendingEncode = async (): Promise => {
+ if (!pendingEncode) return null
+ const encode = pendingEncode
+ try {
+ return await encode
+ } finally {
+ pendingEncode = null
+ }
+ }
+
+ const runAbortCleanup = async () => {
+ if (abortCleanupStarted) return
+ abortCleanupStarted = true
+ try {
await onAbort()
- throw new DOMException('Render cancelled', 'AbortError')
+ } catch (error) {
+ recordCleanupFailure(error)
}
+ }
+
+ const throwRecordedFailureAfterDrain = async () => {
+ if (signal?.aborted) await runAbortCleanup()
+ const failure = failureState.firstFailure
+ if (!failure) return
+ throw failure.error
+ }
+
+ const renderAndObserve = async (frame: number) => {
+ let rendering: Promise
+ try {
+ rendering = renderFrame(frame, recordFailure)
+ } catch (error) {
+ await recordSynchronousFailure(error)
+ throw error
+ }
+ const settlement: OperationSettlement = await rendering.then(
+ (): OperationSettlement => ({ status: 'fulfilled' }),
+ (error: unknown): OperationSettlement => {
+ recordFailure(error)
+ return { status: 'rejected', reason: error }
+ },
+ )
+ if (settlement.status === 'rejected') throw settlement.reason
+ }
+
+ const isRecordedFailure = (error: unknown) =>
+ failureState.firstPrimaryFailure?.error === error ||
+ failureState.firstCleanupFailure?.error === error
+
+ const drainFinalEncode = async () => {
+ await drainPendingEncode()
+ if (totalFrames > 0) await throwRecordedFailureAfterDrain()
+ }
+
+ signal?.addEventListener('abort', publishAbort, { once: true })
+
+ const runLoop = async () => {
+ try {
+ for (let frame = 0; frame < totalFrames; frame++) {
+ const pendingFailure = failureState.firstFailure
+ if (pendingFailure) throw pendingFailure.error
+
+ // Check for abort — drain any in-flight encode first so the encoder is
+ // idle before we cancel the output. The first recorded failure wins, so
+ // this AbortError is preserved over an encoder failure during the drain.
+ if (signal?.aborted) {
+ publishAbort()
+ // Let reactions queued by source failures that fired before abort run
+ // before the queued abort publication. If abort fired first, its
+ // publication was queued first and remains primary.
+ await Promise.resolve()
+ await drainPendingEncode()
+ await throwRecordedFailureAfterDrain()
+ }
+
+ // Render frame first — this overlaps with the previous frame's encode
+ // that is still in flight. The previous sample already copied its
+ // pixels, so writing to the capture surface here cannot corrupt it.
+ await renderAndObserve(frame)
+
+ // Now wait for the previous encode to finish before capturing a new
+ // sample. This ensures at most one encode is in flight and that frames
+ // are fed to the encoder in order.
+ const previousEncode = await drainPendingEncode()
+ if (previousEncode?.status === 'rejected') await throwRecordedFailureAfterDrain()
+
+ // Snapshot pixels into a sample. The capture copies pixel data
+ // immediately — the surface is free for the next render.
+ const sample = captureSample(frame)
- // Render frame first — this overlaps with the previous frame's encode
- // that is still in flight. The previous sample already copied its
- // pixels, so writing to the capture surface here cannot corrupt it.
- await renderFrame(frame)
-
- // Now wait for the previous encode to finish before capturing a new
- // sample. This ensures at most one encode is in flight and that frames
- // are fed to the encoder in order.
- if (pendingEncode) await pendingEncode
-
- // Snapshot pixels into a sample. The capture copies pixel data
- // immediately — the surface is free for the next render.
- const sample = captureSample(frame)
-
- // Kick off encoding in the background. NOT awaited here — it runs
- // concurrently with the next iteration's renderFrame().
- const isKeyFrame = frame === 0
- pendingEncode = (async () => {
- try {
- await encodeSample(sample, isKeyFrame)
- } finally {
- // The encoder does NOT close samples. We must close to release the
- // underlying frame's GPU memory, otherwise the browser throttles
- // after ~8-16 outstanding frames.
- sample.close()
+ // Kick off encoding in the background. NOT awaited here — it runs
+ // concurrently with the next iteration's renderFrame().
+ const isKeyFrame = frame === 0
+ pendingEncode = encodeAndCloseSample(
+ sample,
+ isKeyFrame,
+ encodeSample,
+ recordFailure,
+ recordSynchronousFailure,
+ recordCleanupFailure,
+ )
+
+ onFrameProgress(frame)
}
- })()
- onFrameProgress(frame)
+ // Drain the final in-flight encode before finalizing
+ await drainFinalEncode()
+ } catch (primaryError) {
+ if (!isRecordedFailure(primaryError)) await recordSynchronousFailure(primaryError)
+ await drainPendingEncode()
+ await throwRecordedFailureAfterDrain()
+ throw primaryError
+ }
}
- // Drain the final in-flight encode before finalizing
- if (pendingEncode) await pendingEncode
+ const loopSettlement: OperationSettlement = await runLoop().then(
+ (): OperationSettlement => ({ status: 'fulfilled' }),
+ (error: unknown): OperationSettlement => ({ status: 'rejected', reason: error }),
+ )
+
+ listenerActive = false
+ let listenerRemovalFailure: RecordedFailure | null = null
+ try {
+ signal?.removeEventListener('abort', publishAbort)
+ } catch (error) {
+ listenerRemovalFailure = { error }
+ recordCleanupFailure(error)
+ }
+
+ if (loopSettlement.status === 'rejected') {
+ throw failureState.firstFailure?.error ?? loopSettlement.reason
+ }
+ if (listenerRemovalFailure) {
+ throw failureState.firstFailure?.error ?? listenerRemovalFailure.error
+ }
}
diff --git a/src/features/export/utils/render-pipeline.test.ts b/src/features/export/utils/render-pipeline.test.ts
new file mode 100644
index 000000000..b4dc44e4e
--- /dev/null
+++ b/src/features/export/utils/render-pipeline.test.ts
@@ -0,0 +1,229 @@
+// @vitest-environment node
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+const renderMocks = vi.hoisted(() => ({
+ renderAudioOnly: vi.fn(),
+ renderComposition: vi.fn(),
+}))
+
+vi.mock('./canvas-render-orchestrator', () => renderMocks)
+
+import { runRender } from './render-pipeline'
+import type { ClientExportSettings, ClientRenderResult } from './client-renderer'
+import type { CompositionInputProps } from '@/types/export'
+
+const result: ClientRenderResult = {
+ blob: new Blob(['rendered']),
+ fileSize: 8,
+ duration: 1,
+ mimeType: 'video/mp4',
+}
+
+const settings = {
+ mode: 'video',
+ codec: 'avc',
+ container: 'mp4',
+ resolution: { width: 640, height: 360 },
+} as ClientExportSettings
+
+function compositionWithAudio(): CompositionInputProps {
+ return {
+ fps: 30,
+ durationInFrames: 30,
+ width: 640,
+ height: 360,
+ tracks: [
+ {
+ id: 'a1',
+ name: 'A1',
+ order: 0,
+ height: 80,
+ locked: false,
+ visible: true,
+ muted: false,
+ solo: false,
+ items: [
+ {
+ id: 'audio-1',
+ trackId: 'a1',
+ type: 'audio',
+ from: 0,
+ durationInFrames: 30,
+ label: 'generated.wav',
+ src: 'blob:generated',
+ },
+ ],
+ },
+ ],
+ }
+}
+
+type WorkerBehavior = 'no-audio-context' | 'render-error' | 'runtime-error' | 'deferred-probe'
+
+function installWorker(behavior: WorkerBehavior) {
+ const messages: string[] = []
+ const instances: FakeWorker[] = []
+
+ class FakeWorker {
+ onmessage: ((event: MessageEvent) => void) | null = null
+ onerror: ((event: ErrorEvent) => void) | null = null
+ terminate = vi.fn()
+
+ constructor() {
+ instances.push(this)
+ }
+
+ postMessage(message: { type: string; requestId: string }) {
+ messages.push(message.type)
+ queueMicrotask(() => {
+ if (message.type === 'probe') {
+ if (behavior === 'deferred-probe') return
+ this.onmessage?.({
+ data: {
+ type: 'capabilities',
+ requestId: message.requestId,
+ capabilities: { offlineAudioContext: behavior !== 'no-audio-context' },
+ },
+ } as MessageEvent)
+ return
+ }
+ if (message.type !== 'start') return
+ if (behavior === 'runtime-error') {
+ this.onerror?.({
+ message: 'worker crashed',
+ filename: 'export-render.worker.ts',
+ lineno: 12,
+ colno: 3,
+ } as ErrorEvent)
+ return
+ }
+ this.onmessage?.({
+ data: { type: 'error', requestId: message.requestId, error: 'ENCODER_FAILED:primary' },
+ } as MessageEvent)
+ })
+ }
+ }
+
+ vi.stubGlobal('Worker', FakeWorker as unknown as typeof Worker)
+ return { messages, instances }
+}
+
+describe('runRender worker capability routing', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ renderMocks.renderComposition.mockResolvedValue(result)
+ renderMocks.renderAudioOnly.mockResolvedValue(result)
+ })
+
+ afterEach(() => {
+ vi.unstubAllGlobals()
+ })
+
+ it('preflights worker audio capability and routes normally to the main thread without errors', async () => {
+ const { messages, instances } = installWorker('no-audio-context')
+ const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+ const outcome = await runRender({
+ clientSettings: settings,
+ exportMode: 'video',
+ composition: compositionWithAudio(),
+ signal: new AbortController().signal,
+ onProgress: vi.fn(),
+ })
+
+ expect(messages).toEqual(['probe'])
+ expect(outcome).toEqual({
+ result,
+ renderPath: 'main-thread',
+ fallbackReason: 'WORKER_REQUIRES_MAIN_THREAD:audio-context',
+ })
+ expect(renderMocks.renderComposition).toHaveBeenCalledTimes(1)
+ expect(instances[0]?.terminate).toHaveBeenCalledTimes(1)
+ expect(consoleError).not.toHaveBeenCalled()
+ expect(consoleWarn).not.toHaveBeenCalled()
+ })
+
+ it('preserves a genuine worker render failure as the primary error', async () => {
+ const { messages, instances } = installWorker('render-error')
+
+ await expect(
+ runRender({
+ clientSettings: settings,
+ exportMode: 'video',
+ composition: compositionWithAudio(),
+ signal: new AbortController().signal,
+ onProgress: vi.fn(),
+ }),
+ ).rejects.toThrow('ENCODER_FAILED:primary')
+
+ expect(messages).toEqual(['probe', 'start'])
+ expect(renderMocks.renderComposition).not.toHaveBeenCalled()
+ expect(instances[0]?.terminate).toHaveBeenCalledTimes(1)
+ })
+
+ it('does not disguise an actual worker runtime crash as a capability fallback', async () => {
+ installWorker('runtime-error')
+
+ await expect(
+ runRender({
+ clientSettings: settings,
+ exportMode: 'video',
+ composition: compositionWithAudio(),
+ signal: new AbortController().signal,
+ onProgress: vi.fn(),
+ }),
+ ).rejects.toThrow('EXPORT_WORKER_RUNTIME_ERROR:worker crashed @export-render.worker.ts:12:3')
+ expect(renderMocks.renderComposition).not.toHaveBeenCalled()
+ })
+
+ it('settles cancellation during the capability probe without starting render work', async () => {
+ const { messages, instances } = installWorker('deferred-probe')
+ const controller = new AbortController()
+ const unhandledRejections: unknown[] = []
+ const onUnhandledRejection = (reason: unknown) => unhandledRejections.push(reason)
+ process.on('unhandledRejection', onUnhandledRejection)
+ const pending = runRender({
+ clientSettings: settings,
+ exportMode: 'video',
+ composition: compositionWithAudio(),
+ signal: controller.signal,
+ onProgress: vi.fn(),
+ })
+ const rejection = expect(pending).rejects.toMatchObject({ name: 'AbortError' })
+
+ await vi.waitFor(() => expect(messages).toEqual(['probe']))
+ controller.abort()
+
+ try {
+ await rejection
+ await new Promise((resolve) => setTimeout(resolve, 0))
+ expect(messages).toEqual(['probe', 'cancel'])
+ expect(renderMocks.renderComposition).not.toHaveBeenCalled()
+ expect(instances[0]?.terminate).toHaveBeenCalledTimes(1)
+ expect(unhandledRejections).toEqual([])
+ } finally {
+ process.off('unhandledRejection', onUnhandledRejection)
+ }
+ })
+
+ it('routes a missing Worker capability directly to the main thread', async () => {
+ vi.stubGlobal('Worker', undefined)
+
+ const outcome = await runRender({
+ clientSettings: settings,
+ exportMode: 'video',
+ composition: compositionWithAudio(),
+ signal: new AbortController().signal,
+ onProgress: vi.fn(),
+ })
+
+ expect(outcome).toEqual({
+ result,
+ renderPath: 'main-thread',
+ fallbackReason: 'WORKER_UNAVAILABLE',
+ })
+ expect(renderMocks.renderComposition).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/src/features/export/utils/render-pipeline.ts b/src/features/export/utils/render-pipeline.ts
index dcfd3bc0e..a91b50ca7 100644
--- a/src/features/export/utils/render-pipeline.ts
+++ b/src/features/export/utils/render-pipeline.ts
@@ -165,18 +165,33 @@ export interface RunRenderOutcome {
type ExportWorkerManager = ReturnType>
+type WorkerRenderOutcome =
+ | { kind: 'complete'; result: ClientRenderResult }
+ | { kind: 'requires-main-thread'; reason: string }
+
+function itemHasAudibleMedia(item: CompositionInputProps['tracks'][number]['items'][number]) {
+ if (item.type !== 'audio' && item.type !== 'video') return false
+ return !('muted' in item) || item.muted !== true
+}
+
+function compositionHasAudibleMedia(composition: CompositionInputProps): boolean {
+ return (composition.tracks ?? []).some(
+ (track) => !track.muted && (track.items ?? []).some(itemHasAudibleMedia),
+ )
+}
+
function renderInWorker(
workerManager: ExportWorkerManager,
clientSettings: ClientExportSettings,
composition: CompositionInputProps,
signal: AbortSignal,
onProgress: (progress: RenderProgress) => void,
-): Promise {
+): Promise {
if (typeof Worker === 'undefined') {
return Promise.reject(new Error('WORKER_UNAVAILABLE'))
}
- return new Promise((resolve, reject) => {
+ return new Promise((resolve, reject) => {
if (signal.aborted) {
reject(new DOMException('Render cancelled', 'AbortError'))
return
@@ -184,51 +199,90 @@ function renderInWorker(
const requestId = `export-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
const worker = workerManager.getWorker()
+ let startPosted = false
+ let settled = false
+
+ const cleanup = () => signal.removeEventListener('abort', onAbort)
+ const resolveOnce = (outcome: WorkerRenderOutcome) => {
+ if (settled) return
+ settled = true
+ cleanup()
+ resolve(outcome)
+ }
+ const rejectOnce = (error: Error) => {
+ if (settled) return
+ settled = true
+ cleanup()
+ reject(error)
+ }
const onAbort = () => {
const cancelMessage: ExportRenderWorkerRequest = { type: 'cancel', requestId }
worker.postMessage(cancelMessage)
+ rejectOnce(new DOMException('Render cancelled', 'AbortError'))
}
- const cleanup = () => signal.removeEventListener('abort', onAbort)
signal.addEventListener('abort', onAbort, { once: true })
- worker.onmessage = (event: MessageEvent) => {
+ const startRender = () => {
+ if (startPosted) return
+ startPosted = true
+ const startMessage: ExportRenderWorkerRequest = {
+ type: 'start',
+ requestId,
+ settings: clientSettings,
+ composition,
+ }
+ worker.postMessage(startMessage)
+ }
+
+ const handleCapabilities = (
+ response: Extract,
+ ) => {
+ if (compositionHasAudibleMedia(composition) && !response.capabilities.offlineAudioContext) {
+ resolveOnce({
+ kind: 'requires-main-thread',
+ reason: 'WORKER_REQUIRES_MAIN_THREAD:audio-context',
+ })
+ return
+ }
+ startRender()
+ }
+
+ const handleWorkerMessage = (event: MessageEvent) => {
+ if (settled || event.data.requestId !== requestId) return
const response = event.data
- if (response.requestId !== requestId) return
switch (response.type) {
+ case 'capabilities':
+ handleCapabilities(response)
+ return
case 'progress':
onProgress(response.progress)
- break
+ return
case 'complete':
- cleanup()
- resolve(response.result)
- break
+ resolveOnce({ kind: 'complete', result: response.result })
+ return
case 'cancelled':
- cleanup()
- reject(new DOMException('Render cancelled', 'AbortError'))
- break
+ rejectOnce(new DOMException('Render cancelled', 'AbortError'))
+ return
case 'error':
- cleanup()
- reject(new Error(response.error))
- break
+ if (response.error.startsWith('WORKER_REQUIRES_MAIN_THREAD:')) {
+ resolveOnce({ kind: 'requires-main-thread', reason: response.error })
+ } else {
+ rejectOnce(new Error(response.error))
+ }
}
}
+ worker.onmessage = handleWorkerMessage
worker.onerror = (event: ErrorEvent) => {
- cleanup()
const location = event.filename ? ` @${event.filename}:${event.lineno}:${event.colno}` : ''
- reject(new Error(`EXPORT_WORKER_RUNTIME_ERROR:${event.message}${location}`))
+ rejectOnce(new Error(`EXPORT_WORKER_RUNTIME_ERROR:${event.message}${location}`))
}
- const startMessage: ExportRenderWorkerRequest = {
- type: 'start',
- requestId,
- settings: clientSettings,
- composition,
- }
- worker.postMessage(startMessage)
+ const capabilityMessage: ExportRenderWorkerRequest = { type: 'probe', requestId }
+ worker.postMessage(capabilityMessage)
})
}
@@ -257,6 +311,17 @@ export async function runRender({
signal,
onProgress,
}: RunRenderArgs): Promise {
+ if (typeof Worker === 'undefined') {
+ const result = await renderOnMainThread(
+ exportMode,
+ clientSettings,
+ composition,
+ signal,
+ onProgress,
+ )
+ return { result, renderPath: 'main-thread', fallbackReason: 'WORKER_UNAVAILABLE' }
+ }
+
const workerManager = createManagedWorker({
createWorker: () =>
new Worker(new URL('../workers/export-render.worker.ts', import.meta.url), {
@@ -269,27 +334,17 @@ export async function runRender({
})
try {
- const result = await renderInWorker(
+ const workerOutcome = await renderInWorker(
workerManager,
clientSettings,
composition,
signal,
onProgress,
)
- return { result, renderPath: 'worker' }
- } catch (workerError) {
- if (workerError instanceof DOMException && workerError.name === 'AbortError') {
- throw workerError
+ if (workerOutcome.kind === 'complete') {
+ return { result: workerOutcome.result, renderPath: 'worker' }
}
- const workerMessage = workerError instanceof Error ? workerError.message : String(workerError)
- const shouldFallbackToMainThread =
- workerMessage.startsWith('WORKER_REQUIRES_MAIN_THREAD:') ||
- workerMessage.startsWith('WORKER_UNAVAILABLE') ||
- workerMessage.startsWith('EXPORT_WORKER_RUNTIME_ERROR:')
-
- if (!shouldFallbackToMainThread) throw workerError
-
const result = await renderOnMainThread(
exportMode,
clientSettings,
@@ -297,7 +352,11 @@ export async function runRender({
signal,
onProgress,
)
- return { result, renderPath: 'main-thread', fallbackReason: workerMessage }
+ return {
+ result,
+ renderPath: 'main-thread',
+ fallbackReason: workerOutcome.reason,
+ }
} finally {
workerManager.terminate()
}
diff --git a/src/features/export/workers/export-render-worker.types.ts b/src/features/export/workers/export-render-worker.types.ts
index 01f7af43c..bd863c1cc 100644
--- a/src/features/export/workers/export-render-worker.types.ts
+++ b/src/features/export/workers/export-render-worker.types.ts
@@ -17,7 +17,23 @@ export interface ExportRenderCancelRequest {
requestId: string
}
-export type ExportRenderWorkerRequest = ExportRenderStartRequest | ExportRenderCancelRequest
+export interface ExportRenderCapabilityRequest {
+ type: 'probe'
+ requestId: string
+}
+
+export type ExportRenderWorkerRequest =
+ | ExportRenderStartRequest
+ | ExportRenderCancelRequest
+ | ExportRenderCapabilityRequest
+
+export interface ExportRenderCapabilityResponse {
+ type: 'capabilities'
+ requestId: string
+ capabilities: {
+ offlineAudioContext: boolean
+ }
+}
export interface ExportRenderProgressResponse {
type: 'progress'
@@ -43,6 +59,7 @@ export interface ExportRenderErrorResponse {
}
export type ExportRenderWorkerResponse =
+ | ExportRenderCapabilityResponse
| ExportRenderProgressResponse
| ExportRenderCompleteResponse
| ExportRenderCancelledResponse
diff --git a/src/features/export/workers/export-render.worker.ts b/src/features/export/workers/export-render.worker.ts
index 9d779d411..c0f15d631 100644
--- a/src/features/export/workers/export-render.worker.ts
+++ b/src/features/export/workers/export-render.worker.ts
@@ -86,6 +86,18 @@ function compositionHasAudio(
self.onmessage = async (event: MessageEvent) => {
const message = event.data
+ if (message.type === 'probe') {
+ const capabilities: ExportRenderWorkerResponse = {
+ type: 'capabilities',
+ requestId: message.requestId,
+ capabilities: {
+ offlineAudioContext: typeof OfflineAudioContext !== 'undefined',
+ },
+ }
+ self.postMessage(capabilities)
+ return
+ }
+
if (message.type === 'cancel') {
const controller = activeRequests.get(message.requestId)
if (controller) {
@@ -156,9 +168,14 @@ self.onmessage = async (event: MessageEvent) => {
const messageText = error instanceof Error ? error.message : String(error)
const stack = error instanceof Error ? error.stack : undefined
- // Surface the stack: bare mediabunny asserts report only "Assertion failed",
- // so without the stack the failing call site is invisible on the main thread.
- log.error('Export worker failed', { requestId, error: messageText, stack })
+ const isExpectedMainThreadRequirement = messageText.startsWith('WORKER_REQUIRES_MAIN_THREAD:')
+ if (isExpectedMainThreadRequirement) {
+ log.debug('Export worker capability fallback', { requestId, reason: messageText })
+ } else {
+ // Surface the stack: bare mediabunny asserts report only "Assertion failed",
+ // so without the stack the failing call site is invisible on the main thread.
+ log.error('Export worker failed', { requestId, error: messageText, stack })
+ }
// A DOM global reaching worker code is a bug in that code, not something the
// user can act on — and it used to fail the whole export. Report it as a
// main-thread fallback instead: the render still completes, and the reason
diff --git a/src/features/keyframes/components/dopesheet-editor/index.tsx b/src/features/keyframes/components/dopesheet-editor/index.tsx
index 57b347873..e91e5e375 100644
--- a/src/features/keyframes/components/dopesheet-editor/index.tsx
+++ b/src/features/keyframes/components/dopesheet-editor/index.tsx
@@ -17,7 +17,7 @@ import {
} from 'react'
import { flushSync } from 'react-dom'
import { useTranslation } from 'react-i18next'
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey, useLocalHotkey } from '@/hooks/use-hotkey-registration'
import {
ChevronDown,
ChevronLeft,
@@ -477,14 +477,6 @@ interface DopesheetEditorProps {
shortcutsEnabled?: boolean
/** Keep the Edit add-keyframe shortcut active while its dock is open. */
addKeyframeShortcutEnabled?: boolean
- /** User-configurable bindings for high-frequency keyframe actions. */
- shortcuts?: {
- addKeyframe: string
- previousKeyframe: string
- nextKeyframe: string
- toggleAutoKey: string
- fitKeyframes: string
- }
/** Additional class name */
className?: string
}
@@ -913,7 +905,6 @@ export const DopesheetEditor = memo(function DopesheetEditor({
showPlayhead = true,
shortcutsEnabled = false,
addKeyframeShortcutEnabled = false,
- shortcuts,
className,
}: DopesheetEditorProps) {
perfMarkRender('DopesheetEditor')
@@ -1583,13 +1574,7 @@ export const DopesheetEditor = memo(function DopesheetEditor({
linkedTimelineViewportWidth !== undefined &&
linkedTimelineViewportWidth > 0
const timelineCellBorderWidth =
- presentation === 'classic'
- ? hasLinkedTimelineAxis
- ? 0
- : 1
- : presentation === 'lanes'
- ? 1
- : 0
+ presentation === 'classic' ? (hasLinkedTimelineAxis ? 0 : 1) : presentation === 'lanes' ? 1 : 0
const effectiveTimelineWidth = Math.max(
hasLinkedTimelineAxis
? linkedTimelineViewportWidth
@@ -1692,12 +1677,8 @@ export const DopesheetEditor = memo(function DopesheetEditor({
}, [affectedFrameRange, effectiveTimelineWidth, frameToX])
const sharedGridFrameToX = useCallback(
(frame: number) =>
- getFrameAxisX(
- frame,
- viewport,
- effectiveTimelineWidth + timelineCellBorderWidth,
- 0,
- ) - timelineCellBorderWidth,
+ getFrameAxisX(frame, viewport, effectiveTimelineWidth + timelineCellBorderWidth, 0) -
+ timelineCellBorderWidth,
[effectiveTimelineWidth, timelineCellBorderWidth, viewport],
)
const getRenderedKeyframeX = useCallback(
@@ -1947,8 +1928,7 @@ export const DopesheetEditor = memo(function DopesheetEditor({
if (timelineGridDivisions && timelineGridDivisions > 0) {
return Array.from(
{ length: timelineGridDivisions + 1 },
- (_, index) =>
- viewport.startFrame + (index / timelineGridDivisions) * frameRange,
+ (_, index) => viewport.startFrame + (index / timelineGridDivisions) * frameRange,
)
}
const step = getNiceTickStep(frameRange)
@@ -2557,8 +2537,8 @@ export const DopesheetEditor = memo(function DopesheetEditor({
? propertyRowByProperty.get(selectedProperty)
: undefined
- useHotkeys(
- shortcuts?.addKeyframe ?? '',
+ useCommandHotkey(
+ 'EDIT_KEYFRAME_ADD',
(event) => {
event.preventDefault()
if (activePropertyRow) {
@@ -2571,9 +2551,7 @@ export const DopesheetEditor = memo(function DopesheetEditor({
{
...HOTKEY_OPTIONS,
enabled:
- (shortcutsEnabled || addKeyframeShortcutEnabled) &&
- !disabled &&
- Boolean(shortcuts?.addKeyframe && activePropertyRow),
+ (shortcutsEnabled || addKeyframeShortcutEnabled) && !disabled && Boolean(activePropertyRow),
},
[
activePropertyRow,
@@ -2584,8 +2562,8 @@ export const DopesheetEditor = memo(function DopesheetEditor({
],
)
- useHotkeys(
- shortcuts?.previousKeyframe ?? '',
+ useCommandHotkey(
+ 'KEYFRAME_PREVIOUS',
(event) => {
event.preventDefault()
if (activePropertyRow) {
@@ -2594,14 +2572,13 @@ export const DopesheetEditor = memo(function DopesheetEditor({
},
{
...HOTKEY_OPTIONS,
- enabled:
- shortcutsEnabled && !disabled && Boolean(shortcuts?.previousKeyframe && activePropertyRow),
+ enabled: shortcutsEnabled && !disabled && Boolean(activePropertyRow),
},
[activePropertyRow, disabled, handleRowNavigate, shortcutsEnabled],
)
- useHotkeys(
- shortcuts?.nextKeyframe ?? '',
+ useCommandHotkey(
+ 'KEYFRAME_NEXT',
(event) => {
event.preventDefault()
if (activePropertyRow) {
@@ -2610,14 +2587,13 @@ export const DopesheetEditor = memo(function DopesheetEditor({
},
{
...HOTKEY_OPTIONS,
- enabled:
- shortcutsEnabled && !disabled && Boolean(shortcuts?.nextKeyframe && activePropertyRow),
+ enabled: shortcutsEnabled && !disabled && Boolean(activePropertyRow),
},
[activePropertyRow, disabled, handleRowNavigate, shortcutsEnabled],
)
- useHotkeys(
- shortcuts?.toggleAutoKey ?? '',
+ useCommandHotkey(
+ 'KEYFRAME_TOGGLE_AUTO',
(event) => {
event.preventDefault()
if (activePropertyRow) {
@@ -2626,29 +2602,26 @@ export const DopesheetEditor = memo(function DopesheetEditor({
},
{
...HOTKEY_OPTIONS,
- enabled:
- shortcutsEnabled &&
- !disabled &&
- Boolean(shortcuts?.toggleAutoKey && activePropertyRow && onPropertyValueCommit),
+ enabled: shortcutsEnabled && !disabled && Boolean(activePropertyRow && onPropertyValueCommit),
},
[activePropertyRow, disabled, handleRowAutoKeyToggle, onPropertyValueCommit, shortcutsEnabled],
)
- useHotkeys(
- shortcuts?.fitKeyframes ?? '',
+ useCommandHotkey(
+ 'KEYFRAME_FIT',
(event) => {
event.preventDefault()
fitKeyframesInView()
},
{
...HOTKEY_OPTIONS,
- enabled: shortcutsEnabled && !disabled && Boolean(shortcuts?.fitKeyframes),
+ enabled: shortcutsEnabled && !disabled,
},
[disabled, fitKeyframesInView, shortcutsEnabled],
)
- useHotkeys(
- 'delete,backspace',
+ useLocalHotkey(
+ 'DOPESHEET_DELETE',
(event) => {
event.preventDefault()
if (selectedRefs.length > 0) {
@@ -2659,8 +2632,8 @@ export const DopesheetEditor = memo(function DopesheetEditor({
[disabled, selectedRefs, onRemoveKeyframes],
)
- useHotkeys(
- 'left',
+ useLocalHotkey(
+ 'DOPESHEET_NUDGE_LEFT',
(event) => {
event.preventDefault()
nudgeSelectedKeyframes(-1)
@@ -2669,8 +2642,8 @@ export const DopesheetEditor = memo(function DopesheetEditor({
[disabled, selectedRefs.length, nudgeSelectedKeyframes],
)
- useHotkeys(
- 'right',
+ useLocalHotkey(
+ 'DOPESHEET_NUDGE_RIGHT',
(event) => {
event.preventDefault()
nudgeSelectedKeyframes(1)
@@ -2679,8 +2652,8 @@ export const DopesheetEditor = memo(function DopesheetEditor({
[disabled, selectedRefs.length, nudgeSelectedKeyframes],
)
- useHotkeys(
- 'shift+left',
+ useLocalHotkey(
+ 'DOPESHEET_NUDGE_LEFT_LARGE',
(event) => {
event.preventDefault()
nudgeSelectedKeyframes(-10)
@@ -2689,8 +2662,8 @@ export const DopesheetEditor = memo(function DopesheetEditor({
[disabled, selectedRefs.length, nudgeSelectedKeyframes],
)
- useHotkeys(
- 'shift+right',
+ useLocalHotkey(
+ 'DOPESHEET_NUDGE_RIGHT_LARGE',
(event) => {
event.preventDefault()
nudgeSelectedKeyframes(10)
diff --git a/src/features/keyframes/components/dopesheet-editor/shortcuts.test.tsx b/src/features/keyframes/components/dopesheet-editor/shortcuts.test.tsx
index f3b1f2b92..96528bb66 100644
--- a/src/features/keyframes/components/dopesheet-editor/shortcuts.test.tsx
+++ b/src/features/keyframes/components/dopesheet-editor/shortcuts.test.tsx
@@ -1,19 +1,19 @@
-import { fireEvent, render } from "@testing-library/react";
-import { beforeAll, describe, expect, it, vi } from "vite-plus/test";
-import { DopesheetEditor } from "./index";
+import { fireEvent, render } from '@testing-library/react'
+import { beforeAll, describe, expect, it, vi } from 'vite-plus/test'
+import { DopesheetEditor } from './index'
-describe("DopesheetEditor shortcuts", () => {
+describe('DopesheetEditor shortcuts', () => {
beforeAll(() => {
class ResizeObserverMock {
observe() {}
unobserve() {}
disconnect() {}
}
- vi.stubGlobal("ResizeObserver", ResizeObserverMock);
- });
+ vi.stubGlobal('ResizeObserver', ResizeObserverMock)
+ })
- it("adds a keyframe through the active property handler", () => {
- const onAddKeyframe = vi.fn();
+ it('adds a keyframe through the active property handler', () => {
+ const onAddKeyframe = vi.fn()
render(
{
height={240}
onAddKeyframe={onAddKeyframe}
shortcutsEnabled
- shortcuts={{
- addKeyframe: "k",
- previousKeyframe: "alt+bracketleft",
- nextKeyframe: "alt+bracketright",
- toggleAutoKey: "a",
- fitKeyframes: "f",
- }}
/>,
- );
+ )
- fireEvent.keyDown(document, { key: "k", code: "KeyK" });
+ fireEvent.keyDown(document, { key: 'K', code: 'KeyK', shiftKey: true })
- expect(onAddKeyframe).toHaveBeenCalledWith("x", 24);
- });
+ expect(onAddKeyframe).toHaveBeenCalledWith('x', 24)
+ })
- it("does not remove an existing keyframe when adding with the shortcut", () => {
- const onAddKeyframe = vi.fn();
- const onRemoveKeyframes = vi.fn();
+ it('does not remove an existing keyframe when adding with the shortcut', () => {
+ const onAddKeyframe = vi.fn()
+ const onRemoveKeyframes = vi.fn()
render(
{
onAddKeyframe={onAddKeyframe}
onRemoveKeyframes={onRemoveKeyframes}
shortcutsEnabled
- shortcuts={{
- addKeyframe: "k",
- previousKeyframe: "alt+bracketleft",
- nextKeyframe: "alt+bracketright",
- toggleAutoKey: "a",
- fitKeyframes: "f",
- }}
/>,
- );
+ )
- fireEvent.keyDown(document, { key: "k", code: "KeyK" });
+ fireEvent.keyDown(document, { key: 'K', code: 'KeyK', shiftKey: true })
- expect(onAddKeyframe).not.toHaveBeenCalled();
- expect(onRemoveKeyframes).not.toHaveBeenCalled();
- });
+ expect(onAddKeyframe).not.toHaveBeenCalled()
+ expect(onRemoveKeyframes).not.toHaveBeenCalled()
+ })
- it("does not fire editor shortcuts while they are out of scope", () => {
- const onAddKeyframe = vi.fn();
+ it('does not fire editor shortcuts while they are out of scope', () => {
+ const onAddKeyframe = vi.fn()
render(
{
height={240}
onAddKeyframe={onAddKeyframe}
shortcutsEnabled={false}
- shortcuts={{
- addKeyframe: "k",
- previousKeyframe: "alt+bracketleft",
- nextKeyframe: "alt+bracketright",
- toggleAutoKey: "a",
- fitKeyframes: "f",
- }}
/>,
- );
+ )
- fireEvent.keyDown(document, { key: "k", code: "KeyK" });
+ fireEvent.keyDown(document, { key: 'K', code: 'KeyK', shiftKey: true })
- expect(onAddKeyframe).not.toHaveBeenCalled();
- });
+ expect(onAddKeyframe).not.toHaveBeenCalled()
+ })
- it("keeps only the Edit add shortcut active outside editor focus", () => {
- const onAddKeyframe = vi.fn();
- const onNavigateToKeyframe = vi.fn();
+ it('keeps only the Edit add shortcut active outside editor focus', () => {
+ const onAddKeyframe = vi.fn()
+ const onNavigateToKeyframe = vi.fn()
render(
{
onNavigateToKeyframe={onNavigateToKeyframe}
shortcutsEnabled={false}
addKeyframeShortcutEnabled
- shortcuts={{
- addKeyframe: "k",
- previousKeyframe: "alt+bracketleft",
- nextKeyframe: "alt+bracketright",
- toggleAutoKey: "a",
- fitKeyframes: "f",
- }}
/>,
- );
+ )
- fireEvent.keyDown(document, { key: "k", code: "KeyK" });
+ fireEvent.keyDown(document, { key: 'K', code: 'KeyK', shiftKey: true })
fireEvent.keyDown(document, {
- key: "[",
- code: "BracketLeft",
+ key: '[',
+ code: 'BracketLeft',
altKey: true,
- });
+ })
+
+ expect(onAddKeyframe).toHaveBeenCalledWith('x', 24)
+ expect(onNavigateToKeyframe).not.toHaveBeenCalled()
+ })
+
+ it('does not add a keyframe on plain K', () => {
+ const onAddKeyframe = vi.fn()
+
+ render(
+ ,
+ )
+
+ fireEvent.keyDown(document, { key: 'k', code: 'KeyK' })
- expect(onAddKeyframe).toHaveBeenCalledWith("x", 24);
- expect(onNavigateToKeyframe).not.toHaveBeenCalled();
- });
-});
+ expect(onAddKeyframe).not.toHaveBeenCalled()
+ })
+})
diff --git a/src/features/media-library/stores/media-delete-actions.test.ts b/src/features/media-library/stores/media-delete-actions.test.ts
index cef929c77..5e2465433 100644
--- a/src/features/media-library/stores/media-delete-actions.test.ts
+++ b/src/features/media-library/stores/media-delete-actions.test.ts
@@ -17,7 +17,7 @@ const proxyServiceMocks = vi.hoisted(() => ({
}))
const blobUrlManagerMocks = vi.hoisted(() => ({
- release: vi.fn(),
+ invalidate: vi.fn(),
}))
vi.mock('../services/media-library-service', () => ({
@@ -139,7 +139,7 @@ describe('createDeleteActions', () => {
)
expect(currentState.mediaItems.map((item) => item.id)).toEqual(['media-2'])
expect(currentState.selectedMediaIds).toEqual([])
- expect(blobUrlManagerMocks.release).toHaveBeenCalledWith('media-1')
+ expect(blobUrlManagerMocks.invalidate).toHaveBeenCalledWith('media-1')
expect(proxyServiceMocks.clearProxyKey).toHaveBeenCalledWith('media-1')
})
@@ -161,7 +161,7 @@ describe('createDeleteActions', () => {
expect(currentState.mediaItems.map((item) => item.id)).toEqual(['media-1', 'media-2'])
expect(currentState.selectedMediaIds).toEqual(['media-1'])
expect(currentState.error).toBe('Delete failed hard')
- expect(blobUrlManagerMocks.release).not.toHaveBeenCalled()
+ expect(blobUrlManagerMocks.invalidate).not.toHaveBeenCalled()
})
it('uses the legacy batch delete path when no project is selected', async () => {
@@ -183,7 +183,7 @@ describe('createDeleteActions', () => {
expect(mediaLibraryServiceMocks.deleteMediaBatch).toHaveBeenCalledWith(['media-1', 'media-2'])
expect(currentState.mediaItems).toEqual([])
expect(currentState.selectedMediaIds).toEqual([])
- expect(blobUrlManagerMocks.release).toHaveBeenCalledTimes(2)
+ expect(blobUrlManagerMocks.invalidate).toHaveBeenCalledTimes(2)
expect(proxyServiceMocks.clearProxyKey).toHaveBeenCalledTimes(2)
})
})
diff --git a/src/features/media-library/stores/media-delete-actions.ts b/src/features/media-library/stores/media-delete-actions.ts
index 53bffdfa9..caf487875 100644
--- a/src/features/media-library/stores/media-delete-actions.ts
+++ b/src/features/media-library/stores/media-delete-actions.ts
@@ -31,7 +31,10 @@ function releaseDeletedMediaResources(
const previousMediaById = new Map(previousItems.map((item) => [item.id, item]))
for (const id of ids) {
- blobUrlManager.release(id)
+ // Deletion is a source retirement, not a consumer release. Advance the
+ // media epoch even when no URL has settled yet so a pending storage read
+ // cannot resurrect the deleted source.
+ blobUrlManager.invalidate(id)
proxyService.clearProxyKey(id)
// Drop every Scene Browser cache tied to this media — thumbnail blob
// URLs (which otherwise pin the JPEG in memory forever), lazy-thumb
diff --git a/src/features/media-library/utils/media-resolver.ts b/src/features/media-library/utils/media-resolver.ts
index a90c96756..8e1a1a54e 100644
--- a/src/features/media-library/utils/media-resolver.ts
+++ b/src/features/media-library/utils/media-resolver.ts
@@ -12,7 +12,113 @@ const logger = createLogger('MediaResolver')
* Pending requests to prevent concurrent OPFS access to the same file
* This prevents multiple sync access handle creation for the same OPFS file
*/
-const pendingRequests = new Map>()
+interface PendingMediaRequest {
+ epoch: string
+ promise: Promise
+}
+
+const pendingRequests = new Map()
+
+type MediaLibraryServiceModule =
+ typeof import('@/features/media-library/services/media-library-service')
+type MediaLibraryService = MediaLibraryServiceModule['mediaLibraryService']
+type ResolvedMedia = NonNullable>>
+
+function isCurrentMediaEpoch(mediaId: string, epoch: string): boolean {
+ return blobUrlManager.getEpoch(mediaId) === epoch
+}
+
+function acquireResolvedMediaUrl(mediaId: string, blob: Blob, media: ResolvedMedia): string {
+ const blobUrl = blobUrlManager.acquire(mediaId, blob, {
+ mediaId,
+ storageType: media.storageType,
+ fileHandle: media.storageType === 'handle' ? media.fileHandle : undefined,
+ opfsPath: media.storageType === 'opfs' ? media.opfsPath : undefined,
+ fileSize: media.fileSize,
+ })
+
+ if (media.keyframeTimestamps && media.keyframeTimestamps.length > 0) {
+ registerKeyframeIndex(blobUrl, media.keyframeTimestamps)
+ }
+ return blobUrl
+}
+
+async function resolveCurrentMediaUrl(
+ mediaId: string,
+ requestEpoch: string,
+ mediaLibraryService: MediaLibraryService,
+): Promise {
+ const media = await mediaLibraryService.getMedia(mediaId)
+ if (!isCurrentMediaEpoch(mediaId, requestEpoch)) return ''
+
+ if (!media) {
+ logger.warn(`Media not found: ${mediaId}`)
+ return ''
+ }
+
+ // Get the source blob without an extra validation pass; getMediaFile
+ // surfaces permission/missing-file errors with the same relink UI.
+ const blob = await mediaLibraryService.getMediaFile(media)
+ if (!isCurrentMediaEpoch(mediaId, requestEpoch)) return ''
+
+ if (!blob) {
+ // The media record exists but its bytes can't be resolved (no valid
+ // storage path — e.g. opened on an origin whose OPFS lacks it and the
+ // workspace folder has no copy). getMediaFile returns null WITHOUT a
+ // FileAccessError, so surface it into the broken-media system here so
+ // the clip shows a relink state and the missing-media dialog lights up.
+ logger.warn(`Media blob not found: ${mediaId}`)
+ useMediaLibraryStore.getState().markMediaBroken(mediaId, {
+ mediaId,
+ fileName: media.fileName ?? 'Unknown file',
+ errorType: 'file_missing',
+ })
+ return ''
+ }
+
+ const blobUrl = acquireResolvedMediaUrl(mediaId, blob, media)
+ useMediaLibraryStore.getState().markMediaHealthy(mediaId)
+ return blobUrl
+}
+
+async function markMediaBrokenFromAccessError(
+ mediaId: string,
+ requestEpoch: string,
+ error: unknown,
+ mediaLibraryService: MediaLibraryService,
+ FileAccessError: MediaLibraryServiceModule['FileAccessError'],
+): Promise {
+ if (!(error instanceof FileAccessError)) return
+
+ const media = await mediaLibraryService.getMedia(mediaId)
+ if (!isCurrentMediaEpoch(mediaId, requestEpoch)) return
+ useMediaLibraryStore.getState().markMediaBroken(mediaId, {
+ mediaId,
+ fileName: media?.fileName ?? 'Unknown file',
+ errorType: error.type === 'permission_denied' ? 'permission_denied' : 'file_missing',
+ })
+}
+
+async function loadMediaRequest(mediaId: string, requestEpoch: string): Promise {
+ const { mediaLibraryService, FileAccessError } =
+ await import('@/features/media-library/services/media-library-service')
+ if (!isCurrentMediaEpoch(mediaId, requestEpoch)) return ''
+
+ try {
+ return await resolveCurrentMediaUrl(mediaId, requestEpoch, mediaLibraryService)
+ } catch (error) {
+ if (!isCurrentMediaEpoch(mediaId, requestEpoch)) return ''
+ logger.error(`Failed to resolve media ${mediaId}:`, error)
+ await markMediaBrokenFromAccessError(
+ mediaId,
+ requestEpoch,
+ error,
+ mediaLibraryService,
+ FileAccessError,
+ )
+ return ''
+ }
+}
type RuntimeMediaResolver = (mediaId: string) => Promise | string | null
@@ -71,86 +177,28 @@ export async function resolveMediaUrl(mediaId: string): Promise {
return cached
}
- // Check if there's already a pending request for this media
- if (pendingRequests.has(mediaId)) {
- return pendingRequests.get(mediaId)!
+ const requestEpoch = blobUrlManager.getEpoch(mediaId)
+
+ // Deduplicate only within the currently valid source generation. Relinking
+ // can invalidate an ID while an old storage read is still pending; that old
+ // promise must not block or populate the replacement generation.
+ const pendingRequest = pendingRequests.get(mediaId)
+ if (pendingRequest?.epoch === requestEpoch) {
+ return pendingRequest.promise
}
// Create the request promise
- const requestPromise = (async () => {
- const { mediaLibraryService, FileAccessError } =
- await import('@/features/media-library/services/media-library-service')
-
- try {
- // Get media metadata from library
- const media = await mediaLibraryService.getMedia(mediaId)
-
- if (!media) {
- logger.warn(`Media not found: ${mediaId}`)
- return '' // Fallback: empty string (Composition will skip)
- }
-
- // Get the source blob without an extra validation pass; getMediaFile
- // surfaces permission/missing-file errors with the same relink UI.
- const blob = await mediaLibraryService.getMediaFile(media)
-
- if (!blob) {
- // The media record exists but its bytes can't be resolved (no valid
- // storage path — e.g. opened on an origin whose OPFS lacks it and the
- // workspace folder has no copy). getMediaFile returns null WITHOUT a
- // FileAccessError, so surface it into the broken-media system here so
- // the clip shows a relink state and the missing-media dialog lights up.
- logger.warn(`Media blob not found: ${mediaId}`)
- useMediaLibraryStore.getState().markMediaBroken(mediaId, {
- mediaId,
- fileName: media.fileName ?? 'Unknown file',
- errorType: 'file_missing',
- })
- return ''
- }
-
- // Acquire blob URL through centralized manager (handles caching + ref counting)
- const blobUrl = blobUrlManager.acquire(mediaId, blob, {
- mediaId,
- storageType: media.storageType,
- fileHandle: media.storageType === 'handle' ? media.fileHandle : undefined,
- opfsPath: media.storageType === 'opfs' ? media.opfsPath : undefined,
- fileSize: media.fileSize,
- })
-
- // Register keyframe index for adaptive seek backtracking
- if (media.keyframeTimestamps && media.keyframeTimestamps.length > 0) {
- registerKeyframeIndex(blobUrl, media.keyframeTimestamps)
- }
-
- // Resolved successfully — clear any stale broken flag (e.g. the repair
- // sweep just restored the workspace copy) so the clip stops showing the
- // offline state without needing a reload.
- useMediaLibraryStore.getState().markMediaHealthy(mediaId)
-
- return blobUrl
- } catch (error) {
- logger.error(`Failed to resolve media ${mediaId}:`, error)
-
- // Mark media as broken if it's a file access error
- if (error instanceof FileAccessError) {
- const media = await mediaLibraryService.getMedia(mediaId)
- useMediaLibraryStore.getState().markMediaBroken(mediaId, {
- mediaId,
- fileName: media?.fileName ?? 'Unknown file',
- errorType: error.type === 'permission_denied' ? 'permission_denied' : 'file_missing',
- })
- }
-
- return '' // Fallback: empty string
- } finally {
- // Clean up pending request
+ let requestPromise!: Promise
+ requestPromise = loadMediaRequest(mediaId, requestEpoch).finally(() => {
+ // A later source generation may already own this mediaId's slot. Only
+ // the exact request that installed an entry may remove it.
+ if (pendingRequests.get(mediaId)?.promise === requestPromise) {
pendingRequests.delete(mediaId)
}
- })()
+ })
// Store the pending request
- pendingRequests.set(mediaId, requestPromise)
+ pendingRequests.set(mediaId, { epoch: requestEpoch, promise: requestPromise })
return requestPromise
}
@@ -190,6 +238,11 @@ export async function resolveMediaUrls(
const useProxy = options?.useProxy ?? true
const signal = options?.signal
+ const throwIfAborted = () => {
+ if (signal?.aborted) throw new DOMException('Media resolution aborted', 'AbortError')
+ }
+ throwIfAborted()
+
// Deep clone tracks to avoid mutating original
const resolvedTracks: TimelineTrack[] = structuredClone(tracks)
@@ -206,7 +259,8 @@ export async function resolveMediaUrls(
item.type === 'image' ||
item.type === 'lottie')
) {
- const promise = resolveMediaUrl(item.mediaId).then((blobUrl) => {
+ const resolution = resolveMediaUrl(item.mediaId).then((blobUrl) => {
+ throwIfAborted()
// For video items in preview mode, prefer proxy URL if available
if (useProxy && item.type === 'video') {
const proxyUrl = resolveProxyUrl(item.mediaId!)
@@ -219,7 +273,30 @@ export async function resolveMediaUrls(
}
}
})
- resolutionPromises.push(promise)
+ if (signal) {
+ resolutionPromises.push(
+ new Promise((resolve, reject) => {
+ const onAbort = () => {
+ signal.removeEventListener('abort', onAbort)
+ reject(new DOMException('Media resolution aborted', 'AbortError'))
+ }
+ signal.addEventListener('abort', onAbort, { once: true })
+ resolution.then(
+ () => {
+ signal.removeEventListener('abort', onAbort)
+ resolve()
+ },
+ (error) => {
+ signal.removeEventListener('abort', onAbort)
+ reject(error)
+ },
+ )
+ if (signal.aborted) onAbort()
+ }),
+ )
+ } else {
+ resolutionPromises.push(resolution)
+ }
}
}
}
@@ -228,9 +305,7 @@ export async function resolveMediaUrls(
await Promise.all(resolutionPromises)
// Check if aborted after resolution
- if (signal?.aborted) {
- throw new DOMException('Media resolution aborted', 'AbortError')
- }
+ throwIfAborted()
return resolvedTracks
}
diff --git a/src/features/preview/components/inline-source-preview.test.tsx b/src/features/preview/components/inline-source-preview.test.tsx
new file mode 100644
index 000000000..cacc4cf90
--- /dev/null
+++ b/src/features/preview/components/inline-source-preview.test.tsx
@@ -0,0 +1,166 @@
+import { useEffect, useSyncExternalStore, type ReactNode } from 'react'
+import { act, render, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+const harness = vi.hoisted(() => ({
+ globalVersion: 0,
+ epochs: new Map(),
+ resolveMediaUrl: vi.fn<(mediaId: string) => Promise>(),
+ mounts: 0,
+ unmounts: 0,
+ listeners: new Set<() => void>(),
+ publish: () => {
+ for (const listener of harness.listeners) listener()
+ },
+}))
+
+vi.mock('@/features/preview/deps/player-context', () => ({
+ PlayerEmitterProvider: ({ children }: { children: ReactNode }) => <>{children},
+ ClockBridgeProvider: ({ children }: { children: ReactNode }) => <>{children},
+ VideoConfigProvider: ({ children }: { children: ReactNode }) => <>{children},
+ useClock: () => ({ seekToFrame: vi.fn() }),
+}))
+
+vi.mock('@/features/preview/deps/media-library', () => ({
+ useMediaLibraryStore: (selector: (state: Record) => unknown) =>
+ selector({
+ mediaById: {
+ 'media-1': {
+ id: 'media-1',
+ fileName: 'clip.mp4',
+ mimeType: 'video/mp4',
+ duration: 5,
+ width: 1920,
+ height: 1080,
+ fps: 30,
+ },
+ },
+ }),
+ getMediaType: () => 'video',
+}))
+
+vi.mock('@/shared/state/playback', () => ({
+ usePlaybackStore: (selector: (state: { zoom: number }) => unknown) => selector({ zoom: -1 }),
+}))
+
+vi.mock('@/infrastructure/browser/blob-url-manager', () => ({
+ useBlobUrlVersion: () =>
+ useSyncExternalStore(
+ (listener) => {
+ harness.listeners.add(listener)
+ return () => harness.listeners.delete(listener)
+ },
+ () => harness.globalVersion,
+ ),
+ useBlobUrlEpoch: (mediaId: string) =>
+ useSyncExternalStore(
+ (listener) => {
+ harness.listeners.add(listener)
+ return () => harness.listeners.delete(listener)
+ },
+ () => String(harness.epochs.get(mediaId) ?? 0),
+ ),
+}))
+
+vi.mock('../utils/media-resolver', () => ({
+ resolveMediaUrl: harness.resolveMediaUrl,
+}))
+
+vi.mock('./source-composition', () => ({
+ SourceComposition: ({ src }: { src: string }) => {
+ useEffect(() => {
+ harness.mounts += 1
+ return () => {
+ harness.unmounts += 1
+ }
+ }, [])
+ return
+ },
+}))
+
+import { InlineSourcePreview } from './inline-source-preview'
+
+describe('InlineSourcePreview source binding ownership', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ harness.globalVersion = 0
+ harness.epochs.clear()
+ harness.resolveMediaUrl.mockResolvedValue('blob:media-1')
+ harness.mounts = 0
+ harness.unmounts = 0
+ harness.listeners.clear()
+ })
+
+ it('preserves the current frame generation across unrelated blob URL activity', async () => {
+ const rendered = render(
+ ,
+ )
+
+ await waitFor(() => {
+ expect(rendered.getByTestId('inline-source-composition')).toHaveAttribute(
+ 'data-source',
+ 'blob:media-1',
+ )
+ })
+ expect(harness.resolveMediaUrl).toHaveBeenCalledTimes(1)
+
+ act(() => {
+ harness.globalVersion += 1
+ harness.publish()
+ })
+ await act(async () => {
+ await Promise.resolve()
+ })
+
+ expect(harness.resolveMediaUrl).toHaveBeenCalledTimes(1)
+ expect(harness.mounts).toBe(1)
+ expect(harness.unmounts).toBe(0)
+ })
+
+ it('retires the relevant frame generation before resolving its replacement once', async () => {
+ let resolveReplacement!: (url: string) => void
+ const replacement = new Promise((resolve) => {
+ resolveReplacement = resolve
+ })
+ harness.resolveMediaUrl.mockResolvedValueOnce('blob:old').mockReturnValueOnce(replacement)
+ const rendered = render(
+ ,
+ )
+
+ await waitFor(() => {
+ expect(rendered.getByTestId('inline-source-composition')).toHaveAttribute(
+ 'data-source',
+ 'blob:old',
+ )
+ })
+
+ act(() => {
+ harness.epochs.set('media-1', 1)
+ harness.globalVersion += 1
+ harness.publish()
+ })
+
+ expect(rendered.queryByTestId('inline-source-composition')).toBeNull()
+ await waitFor(() => expect(harness.resolveMediaUrl).toHaveBeenCalledTimes(2))
+
+ await act(async () => {
+ resolveReplacement('blob:new')
+ await replacement
+ })
+
+ expect(rendered.getByTestId('inline-source-composition')).toHaveAttribute(
+ 'data-source',
+ 'blob:new',
+ )
+ expect(harness.resolveMediaUrl).toHaveBeenCalledTimes(2)
+ expect(harness.unmounts).toBe(1)
+ })
+})
diff --git a/src/features/preview/components/inline-source-preview.tsx b/src/features/preview/components/inline-source-preview.tsx
index be9e1e115..05b7ca6c3 100644
--- a/src/features/preview/components/inline-source-preview.tsx
+++ b/src/features/preview/components/inline-source-preview.tsx
@@ -1,4 +1,4 @@
-import { memo, useEffect, useMemo, useState } from 'react'
+import { memo, useEffect, useLayoutEffect, useMemo, useState } from 'react'
import {
PlayerEmitterProvider,
ClockBridgeProvider,
@@ -11,6 +11,7 @@ import { SourceComposition } from './source-composition'
import { usePlaybackStore } from '@/shared/state/playback'
import { EDITOR_LAYOUT_CSS_VALUES } from '@/config/editor-layout'
import { getPreviewNeedsOverflow, getPreviewPlayerSize } from '../utils/preview-pixel-snap'
+import { useBlobUrlEpoch } from '@/infrastructure/browser/blob-url-manager'
interface InlineSourcePreviewProps {
mediaId: string
@@ -53,14 +54,17 @@ const InlineSourcePreviewContent = memo(function InlineSourcePreviewContent({
}: InlineSourcePreviewProps) {
const [blobUrl, setBlobUrl] = useState('')
const media = useMediaLibraryStore((s) => s.mediaById[mediaId])
+ const blobUrlEpoch = useBlobUrlEpoch(mediaId)
const zoom = usePlaybackStore((s) => s.zoom)
const mediaWidth = media?.width || 640
const mediaHeight = media?.height || 360
- useEffect(() => {
- let cancelled = false
+ useLayoutEffect(() => {
setBlobUrl('')
+ }, [blobUrlEpoch, mediaId])
+ useEffect(() => {
+ let cancelled = false
resolveMediaUrl(mediaId)
.then((url) => {
if (!cancelled) {
@@ -74,7 +78,7 @@ const InlineSourcePreviewContent = memo(function InlineSourcePreviewContent({
return () => {
cancelled = true
}
- }, [mediaId])
+ }, [blobUrlEpoch, mediaId])
const containerWidth = containerSize.width
const containerHeight = containerSize.height
diff --git a/src/features/preview/components/source-composition.generation.test.tsx b/src/features/preview/components/source-composition.generation.test.tsx
new file mode 100644
index 000000000..80ede9aec
--- /dev/null
+++ b/src/features/preview/components/source-composition.generation.test.tsx
@@ -0,0 +1,342 @@
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+type Deferred = {
+ promise: Promise
+ resolve: (value: T) => void
+}
+
+function deferred(): Deferred {
+ let resolve!: (value: T) => void
+ const promise = new Promise((done) => {
+ resolve = done
+ })
+ return { promise, resolve }
+}
+
+const decoderHarness = vi.hoisted(() => ({
+ extractors: new Map<
+ string,
+ {
+ init: ReturnType
+ drawFrame: ReturnType
+ getDimensions: ReturnType
+ getDuration: ReturnType
+ getLastFailureKind: ReturnType
+ }
+ >(),
+ waitForInflightPredecodedBitmap: vi.fn(),
+ createImageBitmap: vi.fn(),
+}))
+
+const clockHarness = vi.hoisted(() => ({
+ clock: {
+ currentFrame: 0,
+ onFrameChange: vi.fn(() => () => {}),
+ },
+}))
+
+vi.mock('@/features/preview/deps/player-core', () => ({
+ AbsoluteFill: ({ children }: { children?: React.ReactNode }) => {children}
,
+}))
+
+vi.mock('@/features/preview/deps/player-context', () => ({
+ useClock: () => clockHarness.clock,
+ useClockIsPlaying: () => false,
+ useClockPlaybackRate: () => 1,
+ usePlayer: () => ({ seek: vi.fn() }),
+ useVideoConfig: () => ({ fps: 30, durationInFrames: 30 }),
+}))
+
+vi.mock('@/features/preview/deps/player-pool', () => ({
+ getGlobalVideoSourcePool: () => ({
+ preloadSource: vi.fn(async () => {}),
+ acquireForClip: vi.fn(() => null),
+ releaseClip: vi.fn(),
+ seekClip: vi.fn(),
+ }),
+}))
+
+vi.mock('@/features/preview/deps/export', () => ({
+ SharedVideoExtractorPool: class SharedVideoExtractorPool {
+ getOrCreateItemExtractor(_itemId: string, src: string) {
+ const extractor = decoderHarness.extractors.get(src)
+ if (!extractor) throw new Error(`Missing extractor for ${src}`)
+ return extractor
+ }
+
+ releaseItem() {}
+ },
+}))
+
+vi.mock('../utils/media-resolver', () => ({ resolveProxyUrl: () => null }))
+vi.mock('../utils/decoder-prewarm', () => ({
+ backgroundBatchPreseek: vi.fn(async () => {}),
+ getCachedPredecodedBitmap: vi.fn(() => null),
+ waitForInflightPredecodedBitmap: decoderHarness.waitForInflightPredecodedBitmap,
+}))
+vi.mock('../utils/fast-scrub-prewarm', () => ({ getDirectionalPrewarmOffsets: () => [] }))
+vi.mock('../utils/source-media-sync', () => ({ shouldSeekPlayingMedia: () => false }))
+vi.mock('./source-audio-waveform', () => ({ SourceAudioWaveform: () => null }))
+vi.mock('@/infrastructure/lottie/lottie-frame-provider', () => ({ LottieRenderer: class {} }))
+
+vi.mock('@/shared/state/playback', () => {
+ const state = { useProxy: false }
+ const usePlaybackStore = Object.assign(
+ (selector: (value: typeof state) => unknown) => selector(state),
+ { getState: () => state },
+ )
+ return { usePlaybackStore }
+})
+
+vi.mock('@/shared/state/source-player', () => {
+ const state = {
+ currentSourceFrame: 0,
+ previewSourceFrame: null as number | null,
+ setCurrentSourceFrame: vi.fn(),
+ }
+ const useSourcePlayerStore = Object.assign(
+ (selector: (value: typeof state) => unknown) => selector(state),
+ {
+ getState: () => state,
+ subscribe: () => () => {},
+ },
+ )
+ return { useSourcePlayerStore }
+})
+
+vi.mock('@/features/preview/deps/media-library', () => ({
+ useMediaLibraryStore: (selector: (state: { proxyStatus: Map }) => unknown) =>
+ selector({ proxyStatus: new Map() }),
+}))
+
+import { SourceComposition } from './source-composition'
+
+type MockCanvasContext = CanvasRenderingContext2D & {
+ clearRect: ReturnType
+ drawImage: ReturnType
+}
+
+const canvasContexts = new WeakMap()
+
+function getCanvasContext(canvas: HTMLCanvasElement): MockCanvasContext {
+ const existing = canvasContexts.get(canvas)
+ if (existing) return existing
+ const context = {
+ canvas,
+ clearRect: vi.fn(),
+ drawImage: vi.fn(),
+ } as unknown as MockCanvasContext
+ canvasContexts.set(canvas, context)
+ return context
+}
+
+function makeExtractor(init: Promise = Promise.resolve(true)) {
+ return {
+ init: vi.fn(() => init),
+ drawFrame: vi.fn(async () => true),
+ getDimensions: vi.fn(() => ({ width: 4, height: 4 })),
+ getDuration: vi.fn(() => 1),
+ getLastFailureKind: vi.fn(() => null),
+ }
+}
+
+async function flushDeferredWork(): Promise {
+ await act(async () => {
+ await Promise.resolve()
+ await Promise.resolve()
+ })
+}
+
+describe('SourceComposition source generations', () => {
+ beforeEach(() => {
+ decoderHarness.extractors.clear()
+ decoderHarness.waitForInflightPredecodedBitmap.mockReset()
+ decoderHarness.waitForInflightPredecodedBitmap.mockResolvedValue(null)
+ decoderHarness.createImageBitmap.mockReset()
+ decoderHarness.createImageBitmap.mockResolvedValue({ close: vi.fn() })
+ vi.stubGlobal('createImageBitmap', decoderHarness.createImageBitmap)
+ const getContextSpy = vi.spyOn(HTMLCanvasElement.prototype, 'getContext')
+ ;(
+ getContextSpy as unknown as {
+ mockImplementation: (
+ implementation: (
+ this: HTMLCanvasElement,
+ contextId: string,
+ ) => CanvasRenderingContext2D | null,
+ ) => void
+ }
+ ).mockImplementation(function (this: HTMLCanvasElement, contextId) {
+ return contextId === '2d' ? getCanvasContext(this) : null
+ })
+ vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => {})
+ vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue(undefined)
+ })
+
+ afterEach(() => {
+ cleanup()
+ vi.restoreAllMocks()
+ vi.unstubAllGlobals()
+ })
+
+ it('keeps a deferred old extractor draw off the visible canvas after a same-id src change', async () => {
+ const oldDraw = deferred()
+ const oldExtractor = makeExtractor()
+ oldExtractor.drawFrame.mockReturnValue(oldDraw.promise)
+ decoderHarness.extractors.set('blob:old', oldExtractor)
+ decoderHarness.extractors.set('blob:new', makeExtractor(Promise.resolve(false)))
+
+ const rendered = render(
+ ,
+ )
+ await waitFor(() => expect(oldExtractor.drawFrame).toHaveBeenCalledOnce())
+ const visibleCanvas = rendered.container.querySelector('canvas')!
+ const visibleContext = getCanvasContext(visibleCanvas)
+ visibleContext.clearRect.mockClear()
+ visibleContext.drawImage.mockClear()
+
+ rendered.rerender()
+ expect(visibleContext.clearRect).toHaveBeenCalled()
+
+ oldDraw.resolve(true)
+ await flushDeferredWork()
+
+ expect(visibleContext.drawImage).not.toHaveBeenCalled()
+ expect(visibleCanvas.style.display).toBe('none')
+ expect(decoderHarness.createImageBitmap).not.toHaveBeenCalled()
+ })
+
+ it('hands the decode pump to the replacement generation after an old draw drains', async () => {
+ const oldDraw = deferred()
+ const oldExtractor = makeExtractor()
+ oldExtractor.drawFrame.mockReturnValue(oldDraw.promise)
+ const newExtractor = makeExtractor()
+ decoderHarness.extractors.set('blob:old', oldExtractor)
+ decoderHarness.extractors.set('blob:new', newExtractor)
+
+ const rendered = render(
+ ,
+ )
+ await waitFor(() => expect(oldExtractor.drawFrame).toHaveBeenCalledOnce())
+ const visibleCanvas = rendered.container.querySelector('canvas')!
+ const visibleContext = getCanvasContext(visibleCanvas)
+ visibleContext.drawImage.mockClear()
+
+ rendered.rerender()
+ await waitFor(() => expect(newExtractor.init).toHaveBeenCalledOnce())
+ expect(newExtractor.drawFrame).not.toHaveBeenCalled()
+
+ oldDraw.resolve(true)
+ await flushDeferredWork()
+
+ await waitFor(() => expect(newExtractor.drawFrame).toHaveBeenCalled())
+ await waitFor(() => expect(visibleCanvas.style.display).toBe('block'))
+ expect(visibleContext.drawImage).toHaveBeenCalled()
+ expect(decoderHarness.createImageBitmap).toHaveBeenCalled()
+ })
+
+ it('closes a stale bitmap completion without marking the replacement decoded', async () => {
+ const staleBitmap = { close: vi.fn() }
+ const bitmapCompletion = deferred()
+ const replacementDraw = deferred()
+ decoderHarness.createImageBitmap.mockReturnValueOnce(bitmapCompletion.promise)
+ decoderHarness.extractors.set('blob:old', makeExtractor())
+ const replacementExtractor = makeExtractor()
+ replacementExtractor.drawFrame.mockReturnValue(replacementDraw.promise)
+ decoderHarness.extractors.set('blob:new', replacementExtractor)
+
+ const rendered = render(
+ ,
+ )
+ await waitFor(() => expect(decoderHarness.createImageBitmap).toHaveBeenCalledOnce())
+ const visibleCanvas = rendered.container.querySelector('canvas')!
+ const visibleContext = getCanvasContext(visibleCanvas)
+ const drawCountBeforeReset = visibleContext.drawImage.mock.calls.length
+
+ rendered.rerender()
+ bitmapCompletion.resolve(staleBitmap)
+ await flushDeferredWork()
+
+ expect(staleBitmap.close).toHaveBeenCalledOnce()
+ expect(visibleContext.drawImage).toHaveBeenCalledTimes(drawCountBeforeReset)
+ expect(visibleCanvas.style.display).toBe('none')
+ await waitFor(() => expect(replacementExtractor.drawFrame).toHaveBeenCalledOnce())
+ expect(visibleCanvas.style.display).toBe('none')
+
+ replacementDraw.resolve(false)
+ await flushDeferredWork()
+ })
+
+ it('closes a deferred bitmap after unmount without repainting the retired canvas', async () => {
+ const staleBitmap = { close: vi.fn() }
+ const bitmapCompletion = deferred()
+ decoderHarness.createImageBitmap.mockReturnValueOnce(bitmapCompletion.promise)
+ decoderHarness.extractors.set('blob:old', makeExtractor())
+
+ const rendered = render(
+ ,
+ )
+ await waitFor(() => expect(decoderHarness.createImageBitmap).toHaveBeenCalledOnce())
+ const visibleCanvas = rendered.container.querySelector('canvas')!
+ const visibleContext = getCanvasContext(visibleCanvas)
+ const drawCountBeforeUnmount = visibleContext.drawImage.mock.calls.length
+ const clearCountBeforeUnmount = visibleContext.clearRect.mock.calls.length
+
+ rendered.unmount()
+ expect(visibleContext.clearRect.mock.calls.length).toBeGreaterThan(clearCountBeforeUnmount)
+
+ bitmapCompletion.resolve(staleBitmap)
+ await flushDeferredWork()
+
+ expect(staleBitmap.close).toHaveBeenCalledOnce()
+ expect(visibleContext.drawImage).toHaveBeenCalledTimes(drawCountBeforeUnmount)
+ })
+
+ it('ignores an in-flight shared-cache completion from the old source', async () => {
+ const sharedCompletion = deferred<{ close: ReturnType } | null>()
+ decoderHarness.waitForInflightPredecodedBitmap.mockReturnValueOnce(sharedCompletion.promise)
+ const oldExtractor = makeExtractor()
+ decoderHarness.extractors.set('blob:old', oldExtractor)
+ decoderHarness.extractors.set('blob:new', makeExtractor(Promise.resolve(false)))
+
+ const rendered = render(
+ ,
+ )
+ await waitFor(() =>
+ expect(decoderHarness.waitForInflightPredecodedBitmap).toHaveBeenCalledOnce(),
+ )
+ const visibleCanvas = rendered.container.querySelector('canvas')!
+ const visibleContext = getCanvasContext(visibleCanvas)
+ visibleContext.drawImage.mockClear()
+
+ rendered.rerender()
+ sharedCompletion.resolve({ close: vi.fn() })
+ await flushDeferredWork()
+
+ expect(oldExtractor.drawFrame).not.toHaveBeenCalled()
+ expect(visibleContext.drawImage).not.toHaveBeenCalled()
+ expect(visibleCanvas.style.display).toBe('none')
+ })
+
+ it('ignores old extractor initialization after unmount and remount', async () => {
+ const oldInit = deferred()
+ const oldExtractor = makeExtractor(oldInit.promise)
+ decoderHarness.extractors.set('blob:old', oldExtractor)
+ decoderHarness.extractors.set('blob:new', makeExtractor(Promise.resolve(false)))
+
+ const oldRender = render(
+ ,
+ )
+ await waitFor(() => expect(oldExtractor.init).toHaveBeenCalledOnce())
+ oldRender.unmount()
+
+ const newRender = render(
+ ,
+ )
+ oldInit.resolve(true)
+ await flushDeferredWork()
+
+ expect(oldExtractor.drawFrame).not.toHaveBeenCalled()
+ expect(newRender.container.querySelector('canvas')?.style.display).toBe('none')
+ })
+})
diff --git a/src/features/preview/components/source-composition.tsx b/src/features/preview/components/source-composition.tsx
index 8fcc5cfb7..d1328f21d 100644
--- a/src/features/preview/components/source-composition.tsx
+++ b/src/features/preview/components/source-composition.tsx
@@ -1,4 +1,4 @@
-import { useRef, useEffect, useState, useMemo, useCallback } from 'react'
+import { useRef, useEffect, useLayoutEffect, useState, useMemo, useCallback } from 'react'
import { AbsoluteFill } from '@/features/preview/deps/player-core'
import {
useClock,
@@ -101,26 +101,45 @@ export function SourceComposition({
function LottieSource({ src }: { src: string }) {
const canvasRef = useRef(null)
+ const sourceGenerationRef = useRef(0)
const clock = useClock()
+ useLayoutEffect(() => {
+ const generation = ++sourceGenerationRef.current
+ const canvas = canvasRef.current
+ canvas?.getContext('2d')?.clearRect(0, 0, canvas.width, canvas.height)
+ if (canvas) canvas.style.display = 'none'
+ return () => {
+ if (sourceGenerationRef.current !== generation) return
+ sourceGenerationRef.current += 1
+ canvas?.getContext('2d')?.clearRect(0, 0, canvas.width, canvas.height)
+ if (canvas) canvas.style.display = 'none'
+ }
+ }, [src])
+
useEffect(() => {
const canvas = canvasRef.current
if (!canvas || !src) return
+ const generation = sourceGenerationRef.current
+ const isCurrent = () => sourceGenerationRef.current === generation
const renderer = new LottieRenderer({ canvas, src, autoResize: true })
let raf = 0
let lastFrame = -1
let loaded = false
renderer.ready.then(() => {
- loaded = renderer.isLoaded
+ if (isCurrent()) loaded = renderer.isLoaded
})
// Drive frames from the source clock imperatively (no per-frame React render).
const tick = () => {
+ if (!isCurrent()) return
if (loaded) {
const total = renderer.totalFrames
const frame =
total > 0 ? Math.max(0, Math.min(Math.round(clock.currentFrame), total - 1)) : 0
if (frame !== lastFrame) {
renderer.renderFrame(frame)
+ if (!isCurrent()) return
+ canvas.style.display = 'block'
lastFrame = frame
}
}
@@ -135,7 +154,7 @@ function LottieSource({ src }: { src: string }) {
return (
-
+
)
}
@@ -175,8 +194,10 @@ function VideoSource({
const canvasRef = useRef(null)
const contextRef = useRef(null)
const mountedRef = useRef(true)
+ const sourceGenerationRef = useRef(0)
const decoderReadyRef = useRef(false)
- const renderInFlightRef = useRef(false)
+ const renderInFlightGenerationRef = useRef(null)
+ const pumpLatestDecodedFrameRef = useRef<() => void>(() => {})
const pendingTimeRef = useRef(null)
const latestTargetTimeRef = useRef(0)
const consecutiveDecodeFailuresRef = useRef(0)
@@ -246,7 +267,23 @@ function VideoSource({
}
}, [])
- useEffect(() => {
+ useLayoutEffect(() => {
+ const generation = ++sourceGenerationRef.current
+ mountedRef.current = true
+ decoderReadyRef.current = false
+ extractorRef.current = null
+ pendingTimeRef.current = null
+ contextRef.current = null
+ prewarmInFlightRef.current = false
+ queuedPrewarmTimesRef.current = []
+ prewarmAnchorFrameRef.current = null
+ for (const bitmap of frameCacheRef.current.values()) bitmap.close()
+ frameCacheRef.current.clear()
+ frameCacheOrderRef.current = []
+ const canvas = canvasRef.current
+ const context = canvas?.getContext('2d')
+ if (canvas && context) context.clearRect(0, 0, canvas.width, canvas.height)
+ const resetCanvas = canvas
setUseLegacyPausedSeek(false)
setHasDecodedFrame(false)
setDecodedFrameKey(null)
@@ -254,6 +291,16 @@ function VideoSource({
prewarmInFlightRef.current = false
queuedPrewarmTimesRef.current = []
prewarmAnchorFrameRef.current = null
+ return () => {
+ if (sourceGenerationRef.current === generation) {
+ sourceGenerationRef.current += 1
+ const currentCanvas = resetCanvas
+ const currentContext = currentCanvas?.getContext('2d')
+ if (currentCanvas && currentContext) {
+ currentContext.clearRect(0, 0, currentCanvas.width, currentCanvas.height)
+ }
+ }
+ }
}, [activeSrc, mediaId])
const pumpDirectionalPrewarm = useCallback(() => {
@@ -365,6 +412,11 @@ function VideoSource({
const extractor = extractorRef.current
const canvas = canvasRef.current
if (!extractor || !canvas) return false
+ const generation = sourceGenerationRef.current
+ const isCurrent = () =>
+ mountedRef.current &&
+ sourceGenerationRef.current === generation &&
+ extractorRef.current === extractor
let ctx = contextRef.current
if (!ctx) {
@@ -382,10 +434,21 @@ function VideoSource({
canvas.height = targetHeight
}
+ // Keep deferred extractor work away from the visible presentation. A
+ // decoder can paint before its promise settles, so only commit staged
+ // pixels after validating the source generation.
+ const stagingCanvas = document.createElement('canvas')
+ stagingCanvas.width = targetWidth
+ stagingCanvas.height = targetHeight
+ const stagingContext = stagingCanvas.getContext('2d')
+ if (!stagingContext) return false
+
const cacheKey = quantizeSourceMonitorTime(targetTime)
const markDecodedFrame = () => {
+ if (!isCurrent()) return false
setHasDecodedFrame(true)
setDecodedFrameKey((prev) => (prev === cacheKey ? prev : cacheKey))
+ return true
}
const cache = frameCacheRef.current
const cacheOrder = frameCacheOrderRef.current
@@ -398,8 +461,7 @@ function VideoSource({
cacheOrder.splice(cacheIndex, 1)
cacheOrder.push(cacheKey)
}
- markDecodedFrame()
- return true
+ return markDecodedFrame()
}
const drawSharedBitmap = (bitmap: ImageBitmap): boolean => {
@@ -425,24 +487,36 @@ function VideoSource({
SOURCE_MONITOR_CACHE_TIME_QUANTUM,
SOURCE_MONITOR_SHARED_CACHE_WAIT_MS,
).catch(() => null)
- if (inflightBitmap && drawSharedBitmap(inflightBitmap)) {
- markDecodedFrame()
- return true
+ if (inflightBitmap && isCurrent() && drawSharedBitmap(inflightBitmap)) {
+ return markDecodedFrame()
}
}
+ if (!isCurrent()) return false
+
const didDraw = await extractor.drawFrame(
- ctx,
+ stagingContext,
Math.max(0, targetTime),
0,
0,
- canvas.width,
- canvas.height,
+ stagingCanvas.width,
+ stagingCanvas.height,
)
+ if (!isCurrent()) {
+ ctx.clearRect(0, 0, canvas.width, canvas.height)
+ return false
+ }
if (!didDraw) return false
+ ctx.clearRect(0, 0, canvas.width, canvas.height)
+ ctx.drawImage(stagingCanvas, 0, 0, canvas.width, canvas.height)
+
try {
- const bitmap = await createImageBitmap(canvas)
+ const bitmap = await createImageBitmap(stagingCanvas)
+ if (!isCurrent()) {
+ bitmap.close()
+ return false
+ }
cache.set(cacheKey, bitmap)
cacheOrder.push(cacheKey)
while (cacheOrder.length > SOURCE_MONITOR_FRAME_CACHE_MAX) {
@@ -457,19 +531,42 @@ function VideoSource({
// Cache population is best-effort only.
}
- markDecodedFrame()
- return true
+ return markDecodedFrame()
},
[activeSrc],
)
+ const commitDecodedFrameResult = useCallback(
+ (didDraw: boolean, targetTime: number): boolean => {
+ if (didDraw) {
+ consecutiveDecodeFailuresRef.current = 0
+ queueDirectionalPrewarm(targetTime)
+ return true
+ }
+
+ if (extractorRef.current?.getLastFailureKind() !== 'decode-error') return true
+ consecutiveDecodeFailuresRef.current += 1
+ if (consecutiveDecodeFailuresRef.current < SOURCE_MONITOR_STRICT_DECODE_FALLBACK_FAILURES) {
+ return true
+ }
+
+ decoderReadyRef.current = false
+ setStrictDecodeReady(false)
+ setUseLegacyPausedSeek((prev) => (prev ? prev : true))
+ return false
+ },
+ [queueDirectionalPrewarm],
+ )
+
const pumpLatestDecodedFrame = useCallback(() => {
- if (renderInFlightRef.current) return
- renderInFlightRef.current = true
+ if (renderInFlightGenerationRef.current !== null) return
+ const generation = sourceGenerationRef.current
+ renderInFlightGenerationRef.current = generation
const run = async () => {
try {
while (
+ sourceGenerationRef.current === generation &&
decoderReadyRef.current &&
pendingTimeRef.current !== null &&
mountedRef.current &&
@@ -479,28 +576,17 @@ function VideoSource({
pendingTimeRef.current = null
const didDraw = await drawDecodedFrame(targetTime).catch(() => false)
- if (didDraw) {
- consecutiveDecodeFailuresRef.current = 0
- queueDirectionalPrewarm(targetTime)
- continue
- }
-
- const failureKind = extractorRef.current?.getLastFailureKind() ?? 'decode-error'
- if (failureKind === 'decode-error') {
- consecutiveDecodeFailuresRef.current += 1
- if (
- consecutiveDecodeFailuresRef.current >= SOURCE_MONITOR_STRICT_DECODE_FALLBACK_FAILURES
- ) {
- decoderReadyRef.current = false
- setStrictDecodeReady(false)
- setUseLegacyPausedSeek((prev) => (prev ? prev : true))
- return
- }
+ if (!mountedRef.current || sourceGenerationRef.current !== generation) {
+ return
}
+ if (!commitDecodedFrameResult(didDraw, targetTime)) return
}
} finally {
- renderInFlightRef.current = false
+ if (renderInFlightGenerationRef.current === generation) {
+ renderInFlightGenerationRef.current = null
+ }
if (
+ renderInFlightGenerationRef.current === null &&
decoderReadyRef.current &&
pendingTimeRef.current !== null &&
mountedRef.current &&
@@ -508,14 +594,15 @@ function VideoSource({
) {
queueMicrotask(() => {
if (!mountedRef.current) return
- pumpLatestDecodedFrame()
+ pumpLatestDecodedFrameRef.current()
})
}
}
}
void run()
- }, [drawDecodedFrame, queueDirectionalPrewarm])
+ }, [commitDecodedFrameResult, drawDecodedFrame])
+ pumpLatestDecodedFrameRef.current = pumpLatestDecodedFrame
// Acquire/release pooled element when source changes.
useEffect(() => {
@@ -579,12 +666,19 @@ function VideoSource({
const pool = decoderPoolRef.current
const extractor = pool.getOrCreateItemExtractor(decoderItemId, activeSrc)
extractorRef.current = extractor
+ const generation = sourceGenerationRef.current
let cancelled = false
void extractor
.init()
.then((ready) => {
- if (cancelled || !mountedRef.current) return
+ if (
+ cancelled ||
+ !mountedRef.current ||
+ sourceGenerationRef.current !== generation ||
+ extractorRef.current !== extractor
+ )
+ return
if (!ready) {
setUseLegacyPausedSeek((prev) => (prev ? prev : true))
return
@@ -597,7 +691,13 @@ function VideoSource({
}
})
.catch(() => {
- if (cancelled || !mountedRef.current) return
+ if (
+ cancelled ||
+ !mountedRef.current ||
+ sourceGenerationRef.current !== generation ||
+ extractorRef.current !== extractor
+ )
+ return
setUseLegacyPausedSeek((prev) => (prev ? prev : true))
})
@@ -826,6 +926,7 @@ function ImageSource({ src }: { src: string }) {
return (
({
+ globalVersion: 0,
+ epochs: new Map(),
+ resolveMediaUrl: vi.fn<(mediaId: string) => Promise>(),
+ compositionMounts: 0,
+ compositionUnmounts: 0,
+ listeners: new Set<() => void>(),
+ publish: () => {
+ for (const listener of sourceBindingState.listeners) listener()
+ },
+}))
const editorStoreState = vi.hoisted(() => ({
sourcePreviewMediaId: 'media-1' as string | null,
@@ -63,6 +75,30 @@ const clockState = vi.hoisted(() => ({
playbackRate: 1,
}))
+const resolvedHotkeysState = vi.hoisted(() => ({
+ hotkeys: {
+ MARK_IN: 'i',
+ MARK_OUT: 'o',
+ CLEAR_IN_OUT: 'alt+x',
+ GO_TO_START: 'home',
+ PREVIOUS_FRAME: 'left',
+ PLAY_PAUSE: 'space',
+ NEXT_FRAME: 'right',
+ GO_TO_END: 'end',
+ INSERT_EDIT: 'comma',
+ OVERWRITE_EDIT: 'period',
+ },
+}))
+
+const runtimeHotkeysState = vi.hoisted(() => ({
+ hotkeys: { ...resolvedHotkeysState.hotkeys },
+}))
+
+vi.mock('@/hooks/use-runtime-hotkey-binding', () => ({
+ useRuntimeHotkeyBinding: (command: keyof typeof runtimeHotkeysState.hotkeys) =>
+ runtimeHotkeysState.hotkeys[command] ?? '',
+}))
+
vi.mock('@/features/preview/deps/player-context', () => ({
PlayerEmitterProvider: ({ children }: { children: ReactNode }) => <>{children},
ClockBridgeProvider: ({ children }: { children: ReactNode }) => <>{children},
@@ -78,7 +114,15 @@ vi.mock('@/features/preview/deps/player-context', () => ({
}))
vi.mock('./source-composition', () => ({
- SourceComposition: () => ,
+ SourceComposition: ({ src }: { src: string }) => {
+ useEffect(() => {
+ sourceBindingState.compositionMounts += 1
+ return () => {
+ sourceBindingState.compositionUnmounts += 1
+ }
+ }, [])
+ return
+ },
}))
vi.mock('@/components/ui/tooltip', () => ({
@@ -97,7 +141,26 @@ vi.mock('@/components/ui/dropdown-menu', () => ({
}))
vi.mock('../utils/media-resolver', () => ({
- resolveMediaUrl: vi.fn().mockResolvedValue('blob:media-1'),
+ resolveMediaUrl: sourceBindingState.resolveMediaUrl,
+}))
+
+vi.mock('@/infrastructure/browser/blob-url-manager', () => ({
+ useBlobUrlVersion: () =>
+ useSyncExternalStore(
+ (listener) => {
+ sourceBindingState.listeners.add(listener)
+ return () => sourceBindingState.listeners.delete(listener)
+ },
+ () => sourceBindingState.globalVersion,
+ ),
+ useBlobUrlEpoch: (mediaId: string) =>
+ useSyncExternalStore(
+ (listener) => {
+ sourceBindingState.listeners.add(listener)
+ return () => sourceBindingState.listeners.delete(listener)
+ },
+ () => String(sourceBindingState.epochs.get(mediaId) ?? 0),
+ ),
}))
vi.mock('@/features/preview/deps/media-library', () => {
@@ -133,7 +196,11 @@ vi.mock('@/features/preview/deps/settings', () => {
{ getState: () => settingsState },
)
- return { useSettingsStore }
+ return {
+ useSettingsStore,
+ useResolvedHotkeys: () => resolvedHotkeysState.hotkeys,
+ useRuntimeHotkeys: () => runtimeHotkeysState.hotkeys,
+ }
})
vi.mock('@/shared/state/editor', () => {
@@ -192,9 +259,108 @@ describe('SourceMonitor current media ownership', () => {
beforeEach(() => {
vi.clearAllMocks()
+ sourceBindingState.globalVersion = 0
+ sourceBindingState.epochs.clear()
+ sourceBindingState.resolveMediaUrl.mockResolvedValue('blob:media-1')
+ sourceBindingState.compositionMounts = 0
+ sourceBindingState.compositionUnmounts = 0
+ sourceBindingState.listeners.clear()
editorStoreState.sourcePreviewMediaId = 'media-1'
clockState.currentFrame = 0
clockState.isPlaying = false
+ resolvedHotkeysState.hotkeys = {
+ MARK_IN: 'i',
+ MARK_OUT: 'o',
+ CLEAR_IN_OUT: 'alt+x',
+ GO_TO_START: 'home',
+ PREVIOUS_FRAME: 'left',
+ PLAY_PAUSE: 'space',
+ NEXT_FRAME: 'right',
+ GO_TO_END: 'end',
+ INSERT_EDIT: 'comma',
+ OVERWRITE_EDIT: 'period',
+ }
+ runtimeHotkeysState.hotkeys = { ...resolvedHotkeysState.hotkeys }
+ })
+
+ it('updates visible shortcut labels after remap and reset', async () => {
+ const rendered = render()
+
+ await waitFor(() => expect(rendered.getByLabelText('Mark In (I)')).toBeInTheDocument())
+
+ resolvedHotkeysState.hotkeys = {
+ ...resolvedHotkeysState.hotkeys,
+ MARK_IN: 'shift+f',
+ }
+ runtimeHotkeysState.hotkeys = { ...resolvedHotkeysState.hotkeys }
+ rendered.rerender()
+ expect(rendered.getByLabelText('Mark In (Shift + F)')).toBeInTheDocument()
+
+ resolvedHotkeysState.hotkeys = {
+ ...resolvedHotkeysState.hotkeys,
+ MARK_IN: 'i',
+ }
+ rendered.rerender()
+ expect(rendered.getByLabelText('Mark In (I)')).toBeInTheDocument()
+ })
+
+ it('keeps the raw local label while a losing runtime binding is disabled', async () => {
+ resolvedHotkeysState.hotkeys = {
+ ...resolvedHotkeysState.hotkeys,
+ MARK_IN: 'meta+f10',
+ }
+ runtimeHotkeysState.hotkeys = {
+ ...resolvedHotkeysState.hotkeys,
+ MARK_IN: '',
+ }
+ sourcePlayerStoreState.currentSourceFrame = 42
+ const rendered = render()
+ await waitFor(() => expect(rendered.getByLabelText(/Mark In \(.+f10\)/i)).toBeInTheDocument())
+
+ fireEvent.keyDown(rendered.container.firstElementChild!, {
+ key: 'F10',
+ code: 'F10',
+ metaKey: true,
+ })
+
+ expect(sourcePlayerStoreState.setInPoint).not.toHaveBeenCalled()
+ expect(resolvedHotkeysState.hotkeys.MARK_IN).toBe('meta+f10')
+ })
+
+ it('uses the same reactive binding for local source-monitor actions', async () => {
+ resolvedHotkeysState.hotkeys = {
+ ...resolvedHotkeysState.hotkeys,
+ MARK_IN: 'shift+f',
+ }
+ runtimeHotkeysState.hotkeys = { ...resolvedHotkeysState.hotkeys }
+ sourcePlayerStoreState.currentSourceFrame = 42
+ const rendered = render()
+ await waitFor(() => expect(rendered.getByLabelText('Mark In (Shift + F)')).toBeInTheDocument())
+ const monitor = rendered.container.firstElementChild!
+
+ fireEvent.keyDown(monitor, { key: 'i', code: 'KeyI' })
+ expect(sourcePlayerStoreState.setInPoint).not.toHaveBeenCalled()
+
+ fireEvent.keyDown(monitor, { key: 'F', code: 'KeyF', shiftKey: true })
+ expect(sourcePlayerStoreState.setInPoint).toHaveBeenCalledWith(42)
+ })
+
+ it('uses macOS modifier names in visible shortcut labels', async () => {
+ const originalPlatform = navigator.platform
+ Object.defineProperty(navigator, 'platform', { configurable: true, value: 'MacIntel' })
+ resolvedHotkeysState.hotkeys = {
+ ...resolvedHotkeysState.hotkeys,
+ CLEAR_IN_OUT: 'alt+x',
+ }
+
+ try {
+ const rendered = render()
+ await waitFor(() =>
+ expect(rendered.getByLabelText('Clear In/Out (Option + X)')).toBeInTheDocument(),
+ )
+ } finally {
+ Object.defineProperty(navigator, 'platform', { configurable: true, value: originalPlatform })
+ }
})
it('does not release the current media during the initial Strict Mode remount', async () => {
@@ -283,4 +449,66 @@ describe('SourceMonitor current media ownership', () => {
expect(playerMethodsState.pause).toHaveBeenCalledTimes(1)
})
+
+ it('keeps the current source generation mounted across unrelated blob URL activity', async () => {
+ const rendered = render()
+
+ await waitFor(() => {
+ expect(rendered.getByTestId('source-composition')).toHaveAttribute(
+ 'data-source',
+ 'blob:media-1',
+ )
+ })
+ expect(sourceBindingState.resolveMediaUrl).toHaveBeenCalledTimes(1)
+ expect(sourceBindingState.compositionMounts).toBe(1)
+
+ act(() => {
+ sourceBindingState.globalVersion += 1
+ sourceBindingState.publish()
+ })
+ await act(async () => {
+ await Promise.resolve()
+ })
+
+ expect(sourceBindingState.resolveMediaUrl).toHaveBeenCalledTimes(1)
+ expect(sourceBindingState.compositionMounts).toBe(1)
+ expect(sourceBindingState.compositionUnmounts).toBe(0)
+ expect(rendered.getByTestId('source-composition')).toHaveAttribute(
+ 'data-source',
+ 'blob:media-1',
+ )
+ })
+
+ it('retires and resolves a relevant source epoch exactly once', async () => {
+ let resolveReplacement!: (url: string) => void
+ const replacement = new Promise((resolve) => {
+ resolveReplacement = resolve
+ })
+ sourceBindingState.resolveMediaUrl
+ .mockResolvedValueOnce('blob:old')
+ .mockReturnValueOnce(replacement)
+ const rendered = render()
+
+ await waitFor(() => {
+ expect(rendered.getByTestId('source-composition')).toHaveAttribute('data-source', 'blob:old')
+ })
+
+ act(() => {
+ sourceBindingState.epochs.set('media-1', 1)
+ sourceBindingState.globalVersion += 1
+ sourceBindingState.publish()
+ })
+
+ expect(rendered.queryByTestId('source-composition')).toBeNull()
+ await waitFor(() => expect(sourceBindingState.resolveMediaUrl).toHaveBeenCalledTimes(2))
+ expect(sourceBindingState.compositionUnmounts).toBe(1)
+
+ await act(async () => {
+ resolveReplacement('blob:new')
+ await replacement
+ })
+
+ expect(rendered.getByTestId('source-composition')).toHaveAttribute('data-source', 'blob:new')
+ expect(sourceBindingState.resolveMediaUrl).toHaveBeenCalledTimes(2)
+ })
})
diff --git a/src/features/preview/components/source-monitor.tsx b/src/features/preview/components/source-monitor.tsx
index 1063dcd78..578c5ae7c 100644
--- a/src/features/preview/components/source-monitor.tsx
+++ b/src/features/preview/components/source-monitor.tsx
@@ -1,4 +1,4 @@
-import { useState, useEffect, useRef, useCallback, useMemo, memo } from 'react'
+import { useState, useEffect, useLayoutEffect, useRef, useCallback, useMemo, memo } from 'react'
import {
X,
Play,
@@ -53,7 +53,7 @@ import {
} from '../utils/source-io'
import { useMediaLibraryStore, getMediaType } from '@/features/preview/deps/media-library'
import { useItemsStore } from '@/features/preview/deps/timeline-store'
-import { useSettingsStore } from '@/features/preview/deps/settings'
+import { useResolvedHotkeys, useSettingsStore } from '@/features/preview/deps/settings'
import { useEditorStore } from '@/shared/state/editor'
import { useSourcePlayerStore } from '@/shared/state/source-player'
import { getNextShuttleRate } from '@/shared/state/playback/shuttle'
@@ -70,6 +70,9 @@ import {
import { formatTimecodeCompact } from '@/shared/utils/time-utils'
import { getPreviewPixelSnapSize } from '../utils/preview-pixel-snap'
import type { TimelineTrack } from '@/types/timeline'
+import { useBlobUrlEpoch } from '@/infrastructure/browser/blob-url-manager'
+import { doesHotkeyEventMatchBinding, formatHotkeyBinding } from '@/config/hotkeys'
+import { useCommandHotkeyBinding } from '@/hooks/use-hotkey-registration'
interface SourceMonitorProps {
mediaId: string
@@ -205,6 +208,8 @@ const SourceMonitorContent = memo(function SourceMonitorContent({
}: SourceMonitorProps) {
const [blobUrl, setBlobUrl] = useState('')
const media = useMediaLibraryStore((s) => s.mediaById[mediaId])
+ const blobUrlEpoch = useBlobUrlEpoch(mediaId)
+ const hotkeys = useResolvedHotkeys()
// Sync current media ID into source player store for I/O points
useEffect(() => {
@@ -228,8 +233,14 @@ const SourceMonitorContent = memo(function SourceMonitorContent({
}
}, [media, onClose])
- // Resolve the original source URL once. SourceComposition can swap to a
- // ready proxy for video preview without losing the original fallback URL.
+ // Blank the retired source in layout so a same-ID relink cannot leave its
+ // canvas visible while the replacement URL resolves.
+ useLayoutEffect(() => {
+ setBlobUrl('')
+ }, [blobUrlEpoch, mediaId])
+
+ // SourceComposition can swap to a ready proxy for video preview without
+ // losing the original fallback URL. Blob invalidation retries the same ID.
useEffect(() => {
let cancelled = false
resolveMediaUrl(mediaId)
@@ -242,7 +253,7 @@ const SourceMonitorContent = memo(function SourceMonitorContent({
return () => {
cancelled = true
}
- }, [mediaId])
+ }, [blobUrlEpoch, mediaId])
if (!media) return null
@@ -253,7 +264,6 @@ const SourceMonitorContent = memo(function SourceMonitorContent({
const mediaWidth = media.width || 640
const mediaHeight = media.height || 360
const durationInFrames = mediaType === 'image' ? 1 : Math.max(1, Math.round(media.duration * fps))
-
return (
{}}>
@@ -277,6 +287,7 @@ const SourceMonitorContent = memo(function SourceMonitorContent({
interactive={interactive}
seekFrame={seekFrame}
onClose={onClose}
+ hotkeys={hotkeys}
/>
@@ -300,6 +311,7 @@ interface SourceMonitorInnerProps {
interactive: boolean
seekFrame: number | null
onClose?: () => void
+ hotkeys: ReturnType
}
function SourceMonitorInner({
@@ -316,6 +328,7 @@ function SourceMonitorInner({
interactive,
seekFrame,
onClose,
+ hotkeys,
}: SourceMonitorInnerProps) {
const containerRef = useRef(null)
const contentHostRef = useRef(null)
@@ -440,6 +453,9 @@ function SourceMonitorInner({
}, [interactive, setHoveredPanel, setPlayerMethods])
// Handle I/O shortcuts locally on this element (not global useHotkeys)
+ const markInHotkey = useCommandHotkeyBinding('MARK_IN')
+ const markOutHotkey = useCommandHotkeyBinding('MARK_OUT')
+ const clearInOutHotkey = useCommandHotkeyBinding('CLEAR_IN_OUT')
const wrapperRef = useRef(null)
const hadFocusRef = useRef(false)
const handleKeyDown = useCallback(
@@ -448,21 +464,21 @@ function SourceMonitorInner({
if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return
const { currentSourceFrame, setInPoint, setOutPoint, clearInOutPoints } =
useSourcePlayerStore.getState()
- if (e.key === 'i' || e.key === 'I') {
+ if (doesHotkeyEventMatchBinding(e, markInHotkey)) {
e.preventDefault()
e.stopPropagation()
setInPoint(currentSourceFrame)
- } else if (e.key === 'o' || e.key === 'O') {
+ } else if (doesHotkeyEventMatchBinding(e, markOutHotkey)) {
e.preventDefault()
e.stopPropagation()
setOutPoint(getExclusiveSourceOutPoint(currentSourceFrame, durationInFrames))
- } else if (e.altKey && (e.key === 'x' || e.key === 'X')) {
+ } else if (doesHotkeyEventMatchBinding(e, clearInOutHotkey)) {
e.preventDefault()
e.stopPropagation()
clearInOutPoints()
}
},
- [durationInFrames, interactive],
+ [clearInOutHotkey, durationInFrames, interactive, markInHotkey, markOutHotkey],
)
const handleMouseEnter = useCallback(() => {
@@ -544,6 +560,7 @@ function SourceMonitorInner({
hasAudio={hasAudio}
interactive={interactive}
seekFrame={seekFrame}
+ hotkeys={hotkeys}
/>
)
@@ -558,6 +575,7 @@ function SourcePlaybackControls({
hasAudio,
interactive,
seekFrame,
+ hotkeys,
}: {
durationInFrames: number
fps: number
@@ -565,6 +583,7 @@ function SourcePlaybackControls({
hasAudio: boolean
interactive: boolean
seekFrame: number | null
+ hotkeys: ReturnType
}) {
const clock = useClock()
const player = usePlayer(durationInFrames)
@@ -587,6 +606,7 @@ function SourcePlaybackControls({
const currentTimeRef = useRef(null)
const outPointRef = useRef(useSourcePlayerStore.getState().outPoint)
const [showFrames, setShowFrames] = useState(false)
+ const shortcutLabel = (binding: string) => formatHotkeyBinding(binding)
const showFramesRef = useRef(showFrames)
showFramesRef.current = showFrames
@@ -1289,12 +1309,12 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleMarkIn}
- aria-label="Mark In (I)"
+ aria-label={`Mark In (${shortcutLabel(hotkeys.MARK_IN)})`}
>
- Mark In (I)
+ Mark In ({shortcutLabel(hotkeys.MARK_IN)})
@@ -1306,12 +1326,14 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleMarkOut}
- aria-label="Mark Out (O)"
+ aria-label={`Mark Out (${shortcutLabel(hotkeys.MARK_OUT)})`}
>
- Mark Out (O)
+
+ Mark Out ({shortcutLabel(hotkeys.MARK_OUT)})
+
@@ -1323,12 +1345,14 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleClearIO}
- aria-label="Clear In/Out (Alt+X)"
+ aria-label={`Clear In/Out (${shortcutLabel(hotkeys.CLEAR_IN_OUT)})`}
>
- Clear In/Out (Alt+X)
+
+ Clear In/Out ({shortcutLabel(hotkeys.CLEAR_IN_OUT)})
+
)}
@@ -1371,12 +1395,14 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleGoToStart}
- aria-label="Go to start (Home)"
+ aria-label={`Go to start (${shortcutLabel(hotkeys.GO_TO_START)})`}
>
-
Go to start (Home)
+
+ Go to start ({shortcutLabel(hotkeys.GO_TO_START)})
+
@@ -1388,12 +1414,14 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleStepBack}
- aria-label="Previous frame (Left Arrow)"
+ aria-label={`Previous frame (${shortcutLabel(hotkeys.PREVIOUS_FRAME)})`}
>
- Previous frame (Left Arrow)
+
+ Previous frame ({shortcutLabel(hotkeys.PREVIOUS_FRAME)})
+
@@ -1404,7 +1432,7 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleTogglePlayback}
- aria-label={playing ? 'Pause (Space)' : 'Play (Space)'}
+ aria-label={`${playing ? 'Pause' : 'Play'} (${shortcutLabel(hotkeys.PLAY_PAUSE)})`}
>
{playing ? (
@@ -1413,7 +1441,9 @@ function SourcePlaybackControls({
)}
- {playing ? 'Pause' : 'Play'} (Space)
+
+ {playing ? 'Pause' : 'Play'} ({shortcutLabel(hotkeys.PLAY_PAUSE)})
+
@@ -1425,12 +1455,14 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleStepForward}
- aria-label="Next frame (Right Arrow)"
+ aria-label={`Next frame (${shortcutLabel(hotkeys.NEXT_FRAME)})`}
>
- Next frame (Right Arrow)
+
+ Next frame ({shortcutLabel(hotkeys.NEXT_FRAME)})
+
@@ -1442,12 +1474,14 @@ function SourcePlaybackControls({
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
}}
onClick={handleGoToEnd}
- aria-label="Go to end (End)"
+ aria-label={`Go to end (${shortcutLabel(hotkeys.GO_TO_END)})`}
>
- Go to end (End)
+
+ Go to end ({shortcutLabel(hotkeys.GO_TO_END)})
+
+
{
+ event.stopPropagation()
+ usePlaybackStore.getState().finishScrub(1)
+ }}
+ />
)
},
@@ -173,6 +183,7 @@ function resetStores() {
})
resetPlaybackPreviewState()
+ useMicRecordingStore.getState().reset()
useTimelineStore.setState({
fps: 30,
@@ -651,6 +662,66 @@ describe('TimelineContent playback selection behavior', () => {
cancelAnimationFrameSpy.mockRestore()
})
+ it('cancels a queued hover preview when playhead scrubbing starts', () => {
+ let nextFrameId = 1
+ const scheduledFrames = new Map
()
+ const animationFrameSpy = vi
+ .spyOn(window, 'requestAnimationFrame')
+ .mockImplementation((callback) => {
+ const id = nextFrameId++
+ scheduledFrames.set(id, callback)
+ return id
+ })
+ const cancelAnimationFrameSpy = vi
+ .spyOn(window, 'cancelAnimationFrame')
+ .mockImplementation((id) => {
+ scheduledFrames.delete(id)
+ })
+
+ const { container, getByTestId, unmount } = render(
+ ,
+ )
+ const scrollContainer = container.querySelector('[data-timeline-scroll-container]')
+ if (!(scrollContainer instanceof HTMLDivElement)) {
+ throw new Error('Expected timeline scroll container')
+ }
+
+ Object.defineProperty(scrollContainer, 'getBoundingClientRect', {
+ configurable: true,
+ value: () => ({
+ left: 0,
+ top: 0,
+ right: 400,
+ bottom: 200,
+ width: 400,
+ height: 200,
+ x: 0,
+ y: 0,
+ toJSON: () => ({}),
+ }),
+ })
+ scheduledFrames.clear()
+
+ fireEvent.mouseMove(scrollContainer, { clientX: 180, clientY: 48 })
+ const previewFrameId = [...scheduledFrames.keys()].at(-1)
+ expect(previewFrameId).toBeDefined()
+
+ fireEvent.mouseDown(getByTestId('unified-timeline-playhead'), { button: 0 })
+
+ expect(cancelAnimationFrameSpy).toHaveBeenCalledWith(previewFrameId)
+ act(() => {
+ for (const [id, callback] of [...scheduledFrames]) {
+ scheduledFrames.delete(id)
+ callback(performance.now())
+ }
+ })
+ expect(usePlaybackStore.getState().previewFrame).toBeNull()
+
+ unmount()
+ animationFrameSpy.mockRestore()
+ cancelAnimationFrameSpy.mockRestore()
+ })
+
it('gives dense timelines a short window to cancel hover preview before zoom', () => {
vi.useFakeTimers()
const denseItems = Array.from({ length: 80 }, (_, index) => ({
@@ -992,43 +1063,57 @@ describe('TimelineContent playback selection behavior', () => {
expect(usePlaybackStore.getState().previewFrame).toBe(24)
})
- it('moves the playhead to the click coordinate and clears the gray hover skimmer', () => {
+ it('commits the hover preview when the timeline body is clicked', () => {
const { container } = render()
act(() => {
usePlaybackStore.getState().setCurrentFrame(90)
usePlaybackStore.getState().setPreviewFrame(24)
+ usePlaybackStore.getState().play()
})
const track = container.querySelector(`[data-track-id="${VIDEO_TRACK.id}"]`)
- const scrollContainer = container.querySelector('[data-timeline-scroll-container]')
expect(track).toBeTruthy()
- expect(scrollContainer).toBeTruthy()
- vi.spyOn(scrollContainer!, 'getBoundingClientRect').mockReturnValue({
- x: 0,
- y: 0,
- left: 0,
- top: 0,
- right: 400,
- bottom: 200,
- width: 400,
- height: 200,
- toJSON: () => ({}),
- } as DOMRect)
fireEvent.click(track!, { button: 0, clientX: 80, clientY: 100 })
expect(usePlaybackStore.getState().currentFrame).toBe(24)
expect(usePlaybackStore.getState().previewFrame).toBeNull()
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
})
- it('seeks from a clip-body click even when the clip stops bubble propagation', () => {
- const { container } = render()
- const track = container.querySelector(`[data-track-id="${VIDEO_TRACK.id}"]`)
+ it('rejects a deferred hover from the click interaction but allows a new move', () => {
+ vi.useFakeTimers()
+ const denseItems = Array.from({ length: 80 }, (_, index) => ({
+ ...VIDEO_ITEM,
+ id: `clip-video-${index}`,
+ from: index * VIDEO_ITEM.durationInFrames,
+ }))
+ act(() => {
+ useItemsStore.getState().setItems(denseItems)
+ })
+
+ const frameCallbacks: FrameRequestCallback[] = []
+ const animationFrameSpy = vi
+ .spyOn(window, 'requestAnimationFrame')
+ .mockImplementation((callback) => {
+ frameCallbacks.push(callback)
+ return frameCallbacks.length
+ })
+ const cancelAnimationFrameSpy = vi
+ .spyOn(window, 'cancelAnimationFrame')
+ .mockImplementation(() => {
+ // Model a callback that was already dequeued when cancellation arrived.
+ })
+
+ const { container, getByTestId, unmount } = render(
+ ,
+ )
const scrollContainer = container.querySelector('[data-timeline-scroll-container]')
- expect(track).toBeTruthy()
- expect(scrollContainer).toBeTruthy()
- vi.spyOn(scrollContainer!, 'getBoundingClientRect').mockReturnValue({
+ if (!(scrollContainer instanceof HTMLDivElement)) {
+ throw new Error('Expected timeline scroll container')
+ }
+ vi.spyOn(scrollContainer, 'getBoundingClientRect').mockReturnValue({
x: 0,
y: 0,
left: 0,
@@ -1039,23 +1124,130 @@ describe('TimelineContent playback selection behavior', () => {
height: 200,
toJSON: () => ({}),
} as DOMRect)
- const clip = document.createElement('div')
- clip.dataset.itemId = VIDEO_ITEM.id
- clip.addEventListener('click', (event) => event.stopPropagation())
- track!.appendChild(clip)
+ frameCallbacks.length = 0
- fireEvent.click(clip, { button: 0, clientX: 120, clientY: 100 })
+ const item = getByTestId('mock-timeline-item')
+ act(() => {
+ usePlaybackStore.getState().setCurrentFrame(91)
+ usePlaybackStore.getState().setPreviewFrame(91, VIDEO_ITEM.id)
+ })
- expect(usePlaybackStore.getState().currentFrame).toBe(36)
- })
+ fireEvent.mouseMove(item, { clientX: 7, clientY: 48 })
+ act(() => vi.advanceTimersByTime(150))
+ const staleClickPreview = frameCallbacks.at(-1)
+ expect(staleClickPreview).toBeDefined()
+ frameCallbacks.length = 0
- it('clears transient timeline preview state when the timeline unmounts', () => {
- const { unmount } = render()
- act(() => usePlaybackStore.getState().setPreviewFrame(24))
+ fireEvent.mouseDown(item, { button: 0, clientX: 3, clientY: 48 })
+ fireEvent.click(item, { button: 0, clientX: 3, clientY: 48 })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ currentFrame: 1,
+ previewFrame: null,
+ previewItemId: null,
+ })
+
+ act(() => staleClickPreview?.(performance.now()))
+ expect(usePlaybackStore.getState()).toMatchObject({
+ currentFrame: 1,
+ previewFrame: null,
+ previewItemId: null,
+ })
+
+ fireEvent.mouseMove(item, { clientX: 7, clientY: 48 })
+ act(() => vi.advanceTimersByTime(150))
+ const freshPreview = frameCallbacks.at(-1)
+ expect(freshPreview).toBeDefined()
+ frameCallbacks.length = 0
+ act(() => freshPreview?.(performance.now()))
+ expect(usePlaybackStore.getState()).toMatchObject({
+ currentFrame: 1,
+ previewFrame: 2,
+ previewItemId: VIDEO_ITEM.id,
+ })
+ fireEvent.mouseMove(item, { clientX: 10, clientY: 48 })
+ act(() => vi.advanceTimersByTime(150))
+ const cancelledPreview = frameCallbacks.at(-1)
+ expect(cancelledPreview).toBeDefined()
+ frameCallbacks.length = 0
+ fireEvent.mouseLeave(scrollContainer)
+ act(() => cancelledPreview?.(performance.now()))
+ expect(usePlaybackStore.getState().previewFrame).toBeNull()
+
+ fireEvent.mouseMove(item, { clientX: 7, clientY: 48 })
+ act(() => vi.advanceTimersByTime(150))
+ const unmountedPreview = frameCallbacks.at(-1)
+ expect(unmountedPreview).toBeDefined()
unmount()
+ act(() => unmountedPreview?.(performance.now()))
+ expect(usePlaybackStore.getState().previewFrame).toBeNull()
+
+ animationFrameSpy.mockRestore()
+ cancelAnimationFrameSpy.mockRestore()
+ vi.useRealTimers()
+ })
+
+ it('does not pause or seek when the timeline body is clicked during a microphone take', () => {
+ const { container } = render()
+ const pause = vi.spyOn(usePlaybackStore.getState(), 'pause')
+
+ act(() => {
+ usePlaybackStore.setState({ currentFrame: 90, isPlaying: true })
+ useMicRecordingStore.setState({ status: 'recording' })
+ })
+ act(() => {
+ usePlaybackStore.setState({ previewFrame: 24 })
+ })
+
+ const track = container.querySelector(`[data-track-id="${VIDEO_TRACK.id}"]`)
+ expect(track).toBeTruthy()
+
+ fireEvent.mouseDown(track!, { button: 0, clientX: 80, clientY: 100 })
+ fireEvent.click(track!, { button: 0, clientX: 80, clientY: 100 })
+
+ expect(pause).not.toHaveBeenCalled()
+ expect(usePlaybackStore.getState()).toMatchObject({
+ currentFrame: 90,
+ previewFrame: 24,
+ isPlaying: true,
+ })
+ })
+ it('does not restore the marquee release preview after a timeline body click', () => {
+ const { container } = render()
+ const frameCallbacks: FrameRequestCallback[] = []
+ const animationFrameSpy = vi
+ .spyOn(window, 'requestAnimationFrame')
+ .mockImplementation((callback) => {
+ frameCallbacks.push(callback)
+ return frameCallbacks.length
+ })
+
+ act(() => {
+ usePlaybackStore.getState().setCurrentFrame(90)
+ usePlaybackStore.getState().setPreviewFrame(24)
+ })
+
+ const track = container.querySelector(`[data-track-id="${VIDEO_TRACK.id}"]`)
+ expect(track).toBeTruthy()
+
+ fireEvent.mouseDown(track!, { button: 0, clientX: 80, clientY: 100 })
+ act(() => {
+ marqueeMocks.onGestureEnd?.(
+ new MouseEvent('mouseup', { button: 0, clientX: 80, clientY: 100 }),
+ false,
+ )
+ })
+ expect(frameCallbacks).toHaveLength(1)
+
+ fireEvent.click(track!, { button: 0, clientX: 80, clientY: 100 })
+ act(() => {
+ frameCallbacks.splice(0).forEach((callback) => callback(performance.now()))
+ })
+
+ expect(usePlaybackStore.getState().currentFrame).toBe(24)
expect(usePlaybackStore.getState().previewFrame).toBeNull()
+ animationFrameSpy.mockRestore()
})
it('locks the skim preview from track mousedown until the marquee gesture ends', () => {
@@ -1127,4 +1319,129 @@ describe('TimelineContent playback selection behavior', () => {
expect(usePlaybackStore.getState().previewFrame).not.toBe(releaseFrame)
animationFrameSpy.mockRestore()
})
+
+ it.each([
+ ['video only', 300, 100, ['Video track section scrollbar']],
+ ['audio only', 100, 300, ['Audio track section scrollbar']],
+ ['both sections', 300, 300, ['Video track section scrollbar', 'Audio track section scrollbar']],
+ ['neither section', 100, 100, []],
+ ])(
+ 'renders focusable custom scrollbars for %s overflow',
+ (_name, videoScrollHeight, audioScrollHeight, expectedLabels) => {
+ const tracks: TimelineTrack[] = [
+ VIDEO_TRACK,
+ { ...VIDEO_TRACK, id: 'track-audio-1', name: 'A1', kind: 'audio', order: 1 },
+ ]
+ useTimelineStore.setState({ tracks, items: [] })
+ const clientHeightSpy = vi
+ .spyOn(HTMLElement.prototype, 'clientHeight', 'get')
+ .mockImplementation(function (this: HTMLElement) {
+ return this.hasAttribute('data-track-section-scroll') ? 100 : 12
+ })
+ const scrollHeightSpy = vi
+ .spyOn(HTMLElement.prototype, 'scrollHeight', 'get')
+ .mockImplementation(function (this: HTMLElement) {
+ const section = this.getAttribute('data-track-section-scroll')
+ if (section === 'video') return videoScrollHeight
+ if (section === 'audio') return audioScrollHeight
+ return 12
+ })
+ const videoTracksScrollRef = createRef()
+ const audioTracksScrollRef = createRef()
+
+ const { queryAllByRole, unmount } = render(
+ ,
+ )
+ const scrollbars = queryAllByRole('scrollbar')
+
+ expect(scrollbars.map((scrollbar) => scrollbar.getAttribute('aria-label'))).toEqual(
+ expectedLabels,
+ )
+ for (const scrollbar of scrollbars) {
+ expect(scrollbar).toHaveAttribute('tabindex', '0')
+ expect(scrollbar).toHaveAttribute('aria-orientation', 'vertical')
+ expect(scrollbar).toHaveAttribute('aria-valuemin', '0')
+ expect(scrollbar).toHaveAttribute('aria-valuemax', '100')
+ scrollbar.focus()
+ expect(scrollbar).toHaveFocus()
+ }
+
+ unmount()
+ clientHeightSpy.mockRestore()
+ scrollHeightSpy.mockRestore()
+ },
+ )
+
+ it('bounds each overflowing split scrollbar for Arrow, Page, Home, and End keys', () => {
+ const tracks: TimelineTrack[] = [
+ VIDEO_TRACK,
+ { ...VIDEO_TRACK, id: 'track-audio-1', name: 'A1', kind: 'audio', order: 1 },
+ ]
+ useTimelineStore.setState({ tracks, items: [] })
+ const clientHeightSpy = vi
+ .spyOn(HTMLElement.prototype, 'clientHeight', 'get')
+ .mockImplementation(function (this: HTMLElement) {
+ return this.hasAttribute('data-track-section-scroll') ? 100 : 12
+ })
+ const scrollHeightSpy = vi
+ .spyOn(HTMLElement.prototype, 'scrollHeight', 'get')
+ .mockImplementation(function (this: HTMLElement) {
+ return this.hasAttribute('data-track-section-scroll') ? 300 : 12
+ })
+ const videoTracksScrollRef = createRef()
+ const audioTracksScrollRef = createRef()
+
+ const { container, getByRole, unmount } = render(
+ ,
+ )
+ const videoContainer = container.querySelector(
+ '[data-track-section-scroll="video"]',
+ )!
+ const audioContainer = container.querySelector(
+ '[data-track-section-scroll="audio"]',
+ )!
+ const videoScrollbar = getByRole('scrollbar', {
+ name: 'Video track section scrollbar',
+ })
+ const audioScrollbar = getByRole('scrollbar', {
+ name: 'Audio track section scrollbar',
+ })
+
+ fireEvent.keyDown(videoScrollbar, { key: 'ArrowDown' })
+ expect(videoContainer.scrollTop).toBe(40)
+ expect(audioContainer.scrollTop).toBe(0)
+ fireEvent.keyDown(videoScrollbar, { key: 'PageDown' })
+ expect(videoContainer.scrollTop).toBe(130)
+ fireEvent.keyDown(videoScrollbar, { key: 'End' })
+ expect(videoContainer.scrollTop).toBe(200)
+ expect(videoScrollbar).toHaveAttribute('aria-valuenow', '100')
+ fireEvent.keyDown(videoScrollbar, { key: 'ArrowDown' })
+ expect(videoContainer.scrollTop).toBe(200)
+ fireEvent.keyDown(videoScrollbar, { key: 'Home' })
+ expect(videoContainer.scrollTop).toBe(0)
+ fireEvent.keyDown(videoScrollbar, { key: 'PageUp' })
+ expect(videoContainer.scrollTop).toBe(0)
+
+ fireEvent.keyDown(audioScrollbar, { key: 'ArrowDown' })
+ expect(audioContainer.scrollTop).toBe(40)
+ expect(videoContainer.scrollTop).toBe(0)
+
+ unmount()
+ clientHeightSpy.mockRestore()
+ scrollHeightSpy.mockRestore()
+ })
})
diff --git a/src/features/timeline/components/timeline-content.tsx b/src/features/timeline/components/timeline-content.tsx
index c21ac4050..5b7d71092 100644
--- a/src/features/timeline/components/timeline-content.tsx
+++ b/src/features/timeline/components/timeline-content.tsx
@@ -9,6 +9,7 @@ import { useTimelineSettingsStore } from '../stores/timeline-settings-store'
import { useTimelineViewportStore } from '../stores/timeline-viewport-store'
import { registerZoomTo100, useZoomStore } from '../stores/zoom-store'
import { usePlaybackStore } from '@/shared/state/playback'
+import { isMicRecordingActive, useMicRecordingStore } from '@/shared/state/mic-recording-store'
import { useEditorStore } from '@/shared/state/editor'
import { useSelectionStore } from '@/shared/state/selection'
@@ -90,6 +91,64 @@ const DENSE_TIMELINE_HOVER_PREVIEW_DELAY_MS = 150
type TrackScrollbarSection = 'video' | 'audio' | 'single'
+function shouldIgnoreTimelineContainerClick(
+ target: HTMLElement,
+ interactionJustFinished: boolean,
+): boolean {
+ return (
+ interactionJustFinished ||
+ Boolean(target.closest('[role="menu"]')) ||
+ isMicRecordingActive(useMicRecordingStore.getState().status)
+ )
+}
+
+function shouldIgnoreTimelineMouseDownCapture(button: number): boolean {
+ return button !== 0 || isMicRecordingActive(useMicRecordingStore.getState().status)
+}
+
+function resolveTimelineContainerClickFrame(
+ clientX: number,
+ container: HTMLDivElement | null,
+ pixelsToFrame: (pixels: number) => number,
+ maxTimelineFrame: number,
+): number {
+ const playback = usePlaybackStore.getState()
+ if (playback.previewFrame !== null) return playback.previewFrame
+ if (!container) return playback.currentFrame
+
+ const localX = clientX - container.getBoundingClientRect().left + container.scrollLeft
+ return Math.max(0, Math.min(Math.round(pixelsToFrame(localX)), maxTimelineFrame))
+}
+
+function seekTimelineTrackAtPointer({
+ target,
+ clientX,
+ container,
+ pixelsToFrame,
+ maxTimelineFrame,
+}: {
+ target: HTMLElement
+ clientX: number
+ container: HTMLDivElement | null
+ pixelsToFrame: (pixels: number) => number
+ maxTimelineFrame: number
+}): void {
+ if (!target.closest('[data-track-id]')) return
+ if (useSelectionStore.getState().activeTool === 'razor') return
+ if (isMicRecordingActive(useMicRecordingStore.getState().status)) return
+
+ const playback = usePlaybackStore.getState()
+ const frame = resolveTimelineContainerClickFrame(
+ clientX,
+ container,
+ pixelsToFrame,
+ maxTimelineFrame,
+ )
+ playback.pause()
+ playback.setPreviewFrame(null)
+ playback.setCurrentFrame(frame)
+}
+
function revealTrackInScrollContainer(container: HTMLDivElement | null, trackId: string): boolean {
if (!container) {
return false
@@ -183,6 +242,7 @@ function TrackSectionScrollbarOverlay({
height: number
scrollRef?: React.RefObject
}) {
+ const scrollbarRef = useRef(null)
const railRef = useRef(null)
const thumbRef = useRef(null)
const dragOffsetRef = useRef(0)
@@ -192,6 +252,19 @@ function TrackSectionScrollbarOverlay({
const layoutRef = useRef({ railHeight: 0, thumbHeight: 0, maxThumbTravel: 0, overflowHeight: 0 })
const railInset = 4
+ const updateAriaValue = useCallback(() => {
+ const element = scrollRef?.current
+ const scrollbar = scrollbarRef.current
+ if (!element || !scrollbar) return
+
+ const overflowHeight = Math.max(0, element.scrollHeight - element.clientHeight)
+ const value =
+ overflowHeight > 0
+ ? Math.round(Math.max(0, Math.min(1, element.scrollTop / overflowHeight)) * 100)
+ : 0
+ scrollbar.setAttribute('aria-valuenow', String(value))
+ }, [scrollRef])
+
// Compute layout metrics and update thumb size/position imperatively
const updateThumbLayout = useCallback(() => {
const element = scrollRef?.current
@@ -215,7 +288,8 @@ function TrackSectionScrollbarOverlay({
thumb.style.height = `${thumbHeight}px`
thumb.style.top = `${railInset + thumbTop}px`
thumb.style.display = thumbHeight > 0 ? '' : 'none'
- }, [height, scrollRef])
+ updateAriaValue()
+ }, [height, scrollRef, updateAriaValue])
// Update thumb position only (cheaper — called on scroll)
const updateThumbPosition = useCallback(() => {
@@ -224,11 +298,12 @@ function TrackSectionScrollbarOverlay({
if (!element || !thumb) return
const { maxThumbTravel, overflowHeight } = layoutRef.current
+ updateAriaValue()
if (overflowHeight <= 0 || maxThumbTravel <= 0) return
const thumbTop = (element.scrollTop / overflowHeight) * maxThumbTravel
thumb.style.top = `${railInset + thumbTop}px`
- }, [scrollRef])
+ }, [scrollRef, updateAriaValue])
// Listen for scroll + resize, update thumb imperatively (no setState)
useEffect(() => {
@@ -285,8 +360,9 @@ function TrackSectionScrollbarOverlay({
)
scrollElement.scrollTop = (nextThumbTop / maxThumbTravel) * overflowHeight
+ updateThumbPosition()
},
- [scrollRef],
+ [scrollRef, updateThumbPosition],
)
const stopDragging = useCallback(() => {
@@ -340,12 +416,54 @@ function TrackSectionScrollbarOverlay({
[stopDragging, syncScrollFromClientY],
)
+ const handleKeyDown = useCallback(
+ (event: React.KeyboardEvent) => {
+ const scrollElement = scrollRef?.current
+ if (!scrollElement) return
+
+ const overflowHeight = Math.max(0, scrollElement.scrollHeight - scrollElement.clientHeight)
+ const lineStep = 40
+ const pageStep = Math.max(1, scrollElement.clientHeight * 0.9)
+ let nextScrollTop: number
+
+ switch (event.key) {
+ case 'ArrowUp':
+ nextScrollTop = scrollElement.scrollTop - lineStep
+ break
+ case 'ArrowDown':
+ nextScrollTop = scrollElement.scrollTop + lineStep
+ break
+ case 'PageUp':
+ nextScrollTop = scrollElement.scrollTop - pageStep
+ break
+ case 'PageDown':
+ nextScrollTop = scrollElement.scrollTop + pageStep
+ break
+ case 'Home':
+ nextScrollTop = 0
+ break
+ case 'End':
+ nextScrollTop = overflowHeight
+ break
+ default:
+ return
+ }
+
+ event.preventDefault()
+ event.stopPropagation()
+ scrollElement.scrollTop = Math.max(0, Math.min(overflowHeight, nextScrollTop))
+ updateThumbPosition()
+ },
+ [scrollRef, updateThumbPosition],
+ )
+
if (height <= 0) {
return null
}
return (
+ audioTracksScrollRef?: React.RefObject
+ allTracksScrollRef?: React.RefObject
+}) {
+ if (!anyOverflow) return null
+
+ return (
+
+
+ {hasTrackSections ? (
+ <>
+ {videoSectionHasOverflow ? (
+
+ ) : (
+
+ )}
+
+ {audioSectionHasOverflow ? (
+
+ ) : (
+
+ )}
+
+ ) : (
+
+ )}
+
- {anyOverflow && (
-
- {/* Ruler spacer */}
-
- {hasTrackSections ? (
- <>
-
-
-
-
- ) : (
-
- )}
-
- )}
+
)
})
diff --git a/src/features/timeline/components/timeline-header.test.tsx b/src/features/timeline/components/timeline-header.test.tsx
index edf6e090b..5aefc9e84 100644
--- a/src/features/timeline/components/timeline-header.test.tsx
+++ b/src/features/timeline/components/timeline-header.test.tsx
@@ -5,6 +5,7 @@ import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
import { ZOOM_MAX, ZOOM_MIN } from '../constants'
import { useZoomStore } from '../stores/zoom-store'
import { useSelectionStore } from '@/shared/state/selection'
+import { useSettingsStore } from '@/features/timeline/deps/settings'
import { TimelineHeader } from './timeline-header'
const { micRenderSpy, sliderRenderSpy, sliderInput } = vi.hoisted(() => ({
@@ -91,6 +92,7 @@ describe('TimelineHeader zoom slider', () => {
micRenderSpy.mockClear()
sliderRenderSpy.mockClear()
sliderInput.value = 0.75
+ useSettingsStore.getState().resetHotkeys()
useZoomStore.getState().setZoomLevelSynchronized(1)
useSelectionStore.setState({
selectedItemIds: [],
@@ -327,4 +329,37 @@ describe('TimelineHeader zoom slider', () => {
'true',
)
})
+
+ it('shows resolved tool, split, ripple-trim, and rolling-trim shortcuts', () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({
+ SELECTION_TOOL: 'q',
+ TRIM_EDIT_TOOL: 'w',
+ RAZOR_TOOL: 'e',
+ SPLIT_AT_PLAYHEAD: 'shift+x',
+ RATE_STRETCH_TOOL: 'd',
+ })
+
+ render(
)
+
+ expect(screen.getByRole('button', { name: 'Select Tool (Q)' })).toHaveAttribute(
+ 'data-tooltip',
+ 'Select Tool (Q)',
+ )
+ expect(
+ screen.getByRole('button', {
+ name: 'Trim Edit Tool (W) · Ripple: Shift-drag · Roll: Alt-drag',
+ }),
+ ).toHaveAttribute('data-tooltip', 'Trim Edit Tool (W) · Ripple: Shift-drag · Roll: Alt-drag')
+ const razor = screen.getByRole('button', {
+ name: /Razor Tool \(E\).*Shift \+ X.*Alt \+ C/,
+ })
+ expect(razor).toHaveAttribute(
+ 'data-tooltip',
+ expect.stringMatching(/Razor Tool \(E\).*Shift \+ X.*Alt \+ C/),
+ )
+ expect(screen.getByRole('button', { name: 'Rate Stretch Tool (D)' })).toHaveAttribute(
+ 'data-tooltip',
+ 'Rate Stretch Tool (D)',
+ )
+ })
})
diff --git a/src/features/timeline/components/timeline-header.tsx b/src/features/timeline/components/timeline-header.tsx
index f2a704279..d9d460a7c 100644
--- a/src/features/timeline/components/timeline-header.tsx
+++ b/src/features/timeline/components/timeline-header.tsx
@@ -13,6 +13,7 @@ import {
ZoomIn,
ZoomOut,
Maximize2,
+ MoreHorizontal,
Magnet,
Scissors,
Gauge,
@@ -43,6 +44,7 @@ import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
import { MicRecordControl } from './mic-record-control'
interface TimelineHeaderProps {
+ compact?: boolean
onZoomChange?: (newZoom: number) => void
onZoomIn?: () => void
onZoomOut?: () => void
@@ -59,6 +61,11 @@ function TrimEditIcon({ className }: { className?: string }) {
)
}
+function labelWithShortcut(label: string, binding: string): string {
+ const shortcut = formatHotkeyBinding(binding)
+ return shortcut ? `${label} (${shortcut})` : label
+}
+
const InlineKeyframesToggle = memo(function InlineKeyframesToggle({
isOpen,
onToggle,
@@ -441,6 +448,7 @@ const TimelineZoomControls = memo(function TimelineZoomControls({
*/
// fallow-ignore-next-line complexity
export const TimelineHeader = memo(function TimelineHeader({
+ compact = false,
onZoomChange,
onZoomIn,
onZoomOut,
@@ -449,9 +457,6 @@ export const TimelineHeader = memo(function TimelineHeader({
const { t } = useTranslation()
const hostMode = useEditorStore((s) => s.hostMode)
const hotkeys = useResolvedHotkeys()
- const razorShortcut = formatHotkeyBinding(hotkeys.RAZOR_TOOL)
- const splitAtPlayheadShortcut = formatHotkeyBinding(hotkeys.SPLIT_AT_PLAYHEAD_ALT)
- const razorTooltip = `${t('timeline.header.razorToolTooltip')} (${razorShortcut}) · ${t('projects.settings.hotkeys.items.splitAtPlayhead')} (${splitAtPlayheadShortcut})`
const snapEnabled = useTimelineStore((s) => s.snapEnabled)
const toggleSnap = useTimelineStore((s) => s.toggleSnap)
const audioSkimmingEnabled = useTimelineStore((s) => s.audioSkimmingEnabled)
@@ -486,6 +491,36 @@ export const TimelineHeader = memo(function TimelineHeader({
width: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
height: EDITOR_LAYOUT_CSS_VALUES.toolbarButtonSize,
} as const
+ const selectToolTooltip = labelWithShortcut(
+ t('timeline.header.selectToolTooltip'),
+ hotkeys.SELECTION_TOOL,
+ )
+ const trimEditToolTooltip = [
+ labelWithShortcut(t('timeline.header.trimEditToolTooltip'), hotkeys.TRIM_EDIT_TOOL),
+ t('timeline.header.rippleTrimHint', { modifier: formatHotkeyBinding('shift') }),
+ t('timeline.header.rollingTrimHint', { modifier: formatHotkeyBinding('alt') }),
+ ].join(' · ')
+ const razorToolTooltipParts = [
+ labelWithShortcut(t('timeline.header.razorToolTooltip'), hotkeys.RAZOR_TOOL),
+ ]
+ const razorShortcut = formatHotkeyBinding(hotkeys.RAZOR_TOOL)
+ const splitAtPlayheadShortcut = formatHotkeyBinding(hotkeys.SPLIT_AT_PLAYHEAD)
+ if (splitAtPlayheadShortcut) {
+ razorToolTooltipParts.push(
+ t('timeline.header.splitAtPlayheadHint', { shortcut: splitAtPlayheadShortcut }),
+ )
+ }
+ const splitAtPlayheadAlternateShortcut = formatHotkeyBinding(hotkeys.SPLIT_AT_PLAYHEAD_ALT)
+ if (splitAtPlayheadAlternateShortcut) {
+ razorToolTooltipParts.push(
+ `${t('projects.settings.hotkeys.items.splitAtPlayhead')} (${splitAtPlayheadAlternateShortcut})`,
+ )
+ }
+ const razorToolTooltip = razorToolTooltipParts.join(' · ')
+ const rateStretchToolTooltip = labelWithShortcut(
+ t('timeline.header.rateStretchToolTooltip'),
+ hotkeys.RATE_STRETCH_TOOL,
+ )
const handleUndo = () => {
useTimelineStore.temporal.getState().undo()
@@ -497,13 +532,17 @@ export const TimelineHeader = memo(function TimelineHeader({
return (
{/* Left: Title */}
-
+
{t('timeline.header.title')}
@@ -511,7 +550,12 @@ export const TimelineHeader = memo(function TimelineHeader({
{/* Middle: Timeline Controls */}
-
+
{/* Timeline Tools */}
@@ -525,8 +569,8 @@ export const TimelineHeader = memo(function TimelineHeader({
: ''
}
onClick={() => setActiveTool('select')}
- aria-label={t('timeline.header.selectTool')}
- data-tooltip={t('timeline.header.selectToolTooltip')}
+ aria-label={selectToolTooltip}
+ data-tooltip={selectToolTooltip}
>
@@ -541,8 +585,8 @@ export const TimelineHeader = memo(function TimelineHeader({
: ''
}
onClick={() => setActiveTool(activeTool === 'trim-edit' ? 'select' : 'trim-edit')}
- aria-label={t('timeline.header.trimEditTool')}
- data-tooltip={t('timeline.header.trimEditToolTooltip')}
+ aria-label={trimEditToolTooltip}
+ data-tooltip={trimEditToolTooltip}
>
@@ -557,9 +601,9 @@ export const TimelineHeader = memo(function TimelineHeader({
: ''
}
onClick={() => setActiveTool(activeTool === 'razor' ? 'select' : 'razor')}
- aria-label={`${t('timeline.header.razorTool')} (${razorShortcut})`}
+ aria-label={razorToolTooltip}
aria-keyshortcuts={razorShortcut}
- data-tooltip={razorTooltip}
+ data-tooltip={razorToolTooltip}
>
@@ -577,8 +621,8 @@ export const TimelineHeader = memo(function TimelineHeader({
onClick={() =>
setActiveTool(activeTool === 'rate-stretch' ? 'select' : 'rate-stretch')
}
- aria-label={t('timeline.header.rateStretchTool')}
- data-tooltip={t('timeline.header.rateStretchToolTooltip')}
+ aria-label={rateStretchToolTooltip}
+ data-tooltip={rateStretchToolTooltip}
>
@@ -864,6 +908,58 @@ export const TimelineHeader = memo(function TimelineHeader({
onZoomOut={onZoomOut}
onZoomToFit={onZoomToFit}
/>
+
+ {compact && (
+
+
+
+
+
+ {!hostMode && (
+ <>
+
+
+ {t('timeline.header.undo')}
+
+
+
+ {t('timeline.header.redo')}
+
+
+ )}
+
+
+ {snapEnabled
+ ? t('timeline.header.disableSnapping')
+ : t('timeline.header.enableSnapping')}
+
+
+
+ {audioSkimmingEnabled
+ ? t('timeline.header.disableAudioSkimming')
+ : t('timeline.header.enableAudioSkimming')}
+
+ {!hostMode && (
+
+
+ {t(
+ inlineKeyframesOpen
+ ? 'timeline.keyframeEditor.editLane.hide'
+ : 'timeline.keyframeEditor.editLane.show',
+ )}
+
+ )}
+ setLinkedSelectionEnabled(!linkedSelectionEnabled)}>
+
+ {linkedSelectionEnabled
+ ? t('timeline.header.disableLinkedSelection')
+ : t('timeline.header.enableLinkedSelection')}
+
+
+
+ )}
)
})
diff --git a/src/features/timeline/components/timeline-item-hit-target.tsx b/src/features/timeline/components/timeline-item-hit-target.tsx
index 6466d316f..be4d913fd 100644
--- a/src/features/timeline/components/timeline-item-hit-target.tsx
+++ b/src/features/timeline/components/timeline-item-hit-target.tsx
@@ -20,7 +20,7 @@ export const TimelineItemHitTarget = memo(function TimelineItemHitTarget({
({
+ ClipContent: ({ item }: { item: TimelineItemType }) => (
+
{item.label}
+ ),
+}))
+
+const FPS = 30
+const CLIP_FRAMES = 60
+let rafCallbacks: FrameRequestCallback[] = []
+
+function makeTracks(audioParentId?: string): TimelineTrack[] {
+ const tracks: TimelineTrack[] = [
+ makeTimelineTrack({ id: 'track-v1', name: 'V1', kind: 'video', order: 0 }),
+ makeTimelineTrack({
+ id: 'track-a1',
+ name: 'A1',
+ kind: 'audio',
+ order: audioParentId ? 2 : 1,
+ parentTrackId: audioParentId,
+ }),
+ ]
+ if (audioParentId) {
+ tracks.splice(
+ 1,
+ 0,
+ makeTimelineTrack({
+ id: audioParentId,
+ name: 'Locked audio group',
+ order: 1,
+ isGroup: true,
+ locked: true,
+ }),
+ )
+ }
+ return tracks
+}
+
+function makeVideoPair() {
+ return [
+ makeTimelineVideoItem({
+ id: 'video-left',
+ label: 'red.mp4',
+ linkedGroupId: 'left-cohort',
+ }),
+ makeTimelineVideoItem({
+ id: 'video-right',
+ label: 'blue.mp4',
+ mediaId: 'media-2',
+ from: CLIP_FRAMES,
+ linkedGroupId: 'right-cohort',
+ }),
+ ] as const
+}
+
+function makeLinkedFixtureItems() {
+ const [videoLeft, videoRight] = makeVideoPair()
+ return [
+ videoLeft,
+ videoRight,
+ makeTimelineAudioItem({
+ id: 'audio-left',
+ label: 'red.wav',
+ linkedGroupId: 'left-cohort',
+ }),
+ makeTimelineAudioItem({
+ id: 'audio-right',
+ label: 'blue.wav',
+ mediaId: 'media-2',
+ from: CLIP_FRAMES,
+ linkedGroupId: 'right-cohort',
+ }),
+ ]
+}
+
+function resetStores(tracks: TimelineTrack[], items: TimelineItemType[]): void {
+ useEditorStore.setState({ hostMode: false, linkedSelectionEnabled: true })
+ useItemsStore.getState().setTracks(tracks)
+ useItemsStore.getState().setItems(items)
+ useTransitionsStore.getState().setTransitions([])
+ useKeyframesStore.getState().setKeyframes([])
+ useTimelineCommandStore.getState().clearHistory()
+ useTimelineSettingsStore.setState({ fps: FPS, isDirty: false, snapEnabled: false })
+ useZoomStore.setState({
+ level: 0.3,
+ pixelsPerSecond: FPS,
+ contentLevel: 0.3,
+ contentPixelsPerSecond: FPS,
+ isZoomInteracting: false,
+ })
+ useSelectionStore.getState().clearSelection()
+ useSelectionStore.getState().setActiveTool('select')
+ useSelectionStore.getState().setDragState(null)
+ useSelectionStore.getState().setActiveSnapTarget(null)
+ usePlaybackStore.setState({ currentFrame: 0, previewFrame: null, isPlaying: false })
+}
+
+function renderItems(
+ items: readonly TimelineItemType[],
+ lockedTrackIds = new Set
(),
+ isCompactWidth = false,
+) {
+ const view = render(
+
+ {items.map((item) => (
+
+ ))}
+
,
+ )
+
+ for (const item of items) {
+ const root = view.container.querySelector(`[data-item-id="${item.id}"]`)
+ expect(root).toBeTruthy()
+ const left = item.from
+ const width = item.durationInFrames
+ vi.spyOn(root!, 'getBoundingClientRect').mockReturnValue({
+ x: left,
+ y: 0,
+ left,
+ top: 0,
+ right: left + width,
+ bottom: 80,
+ width,
+ height: 80,
+ toJSON: () => ({}),
+ })
+ }
+
+ return view
+}
+
+function flushAnimationFrame(): void {
+ act(() => {
+ const callbacks = rafCallbacks
+ rafCallbacks = []
+ for (const callback of callbacks) callback(performance.now())
+ })
+}
+
+function dragOneFrame(handle: HTMLElement): void {
+ fireEvent.mouseDown(handle, { button: 0, clientX: CLIP_FRAMES })
+ fireEvent.mouseMove(window, { clientX: CLIP_FRAMES + 1 })
+ flushAnimationFrame()
+ fireEvent.mouseUp(window, { clientX: CLIP_FRAMES + 1 })
+}
+
+function itemSnapshot() {
+ return structuredClone(useItemsStore.getState().items)
+}
+
+describe('TimelineItem contiguous rolling trim affordance', () => {
+ beforeEach(() => {
+ rafCallbacks = []
+ vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+ rafCallbacks.push(callback)
+ return rafCallbacks.length
+ })
+ vi.stubGlobal('cancelAnimationFrame', (id: number) => {
+ rafCallbacks[id - 1] = () => {}
+ })
+ })
+
+ afterEach(() => {
+ vi.unstubAllGlobals()
+ vi.restoreAllMocks()
+ })
+
+ it('mounts one visible, hit-testable shared-edge handle when either neighbor is selected or the cut is hovered', () => {
+ const items = makeVideoPair()
+ resetStores(makeTracks(), [...items])
+ const view = renderItems(items, new Set(), true)
+
+ act(() => useSelectionStore.getState().selectItems(['video-left']))
+ const leftRoot = view.container.querySelector('[data-item-id="video-left"]')!
+ expect(leftRoot).toHaveAttribute('data-compact-clip', 'true')
+ const leftOwnedHandle = within(leftRoot).getByRole('slider', { name: /rolling trim/i })
+ expect(leftOwnedHandle).toHaveAttribute('data-rolling-trim-handle', 'end')
+ expect(leftOwnedHandle).not.toHaveClass('pointer-events-none')
+
+ act(() => useSelectionStore.getState().selectItems(['video-right']))
+ expect(within(leftRoot).queryByRole('slider', { name: /rolling trim/i })).toBeNull()
+ const rightRoot = view.container.querySelector('[data-item-id="video-right"]')!
+ const rightOwnedHandle = within(rightRoot).getByRole('slider', { name: /rolling trim/i })
+ expect(rightOwnedHandle).toHaveAttribute('data-rolling-trim-handle', 'start')
+
+ act(() => useSelectionStore.getState().clearSelection())
+ fireEvent.mouseMove(leftRoot, { clientX: CLIP_FRAMES, clientY: 40 })
+ expect(within(leftRoot).getByRole('slider', { name: /rolling trim/i })).toBeVisible()
+
+ act(() => useSelectionStore.getState().setActiveTool('razor'))
+ expect(view.container.querySelector('[data-rolling-trim-handle]')).toBeNull()
+ })
+
+ it('drags a linked A/V cut by one frame as one command and undo restores all four clips', () => {
+ const items = makeLinkedFixtureItems()
+ resetStores(makeTracks(), items)
+ useSelectionStore.getState().selectItems(['video-right', 'audio-right'])
+ const view = renderItems(items)
+ const videoRight = view.container.querySelector('[data-item-id="video-right"]')!
+ const handle = within(videoRight).getByRole('slider', { name: /rolling trim/i })
+ const undoDepthBefore = useTimelineCommandStore.getState().undoStack.length
+
+ dragOneFrame(handle)
+
+ expect(useItemsStore.getState().itemById).toMatchObject({
+ 'video-left': { durationInFrames: 61, sourceEnd: 61 },
+ 'video-right': { from: 61, durationInFrames: 59, sourceStart: 1 },
+ 'audio-left': { durationInFrames: 61, sourceEnd: 61 },
+ 'audio-right': { from: 61, durationInFrames: 59, sourceStart: 1 },
+ })
+ expect(useTimelineCommandStore.getState().undoStack).toHaveLength(undoDepthBefore + 1)
+
+ act(() => useTimelineCommandStore.getState().undo())
+
+ expect(useItemsStore.getState().itemById).toMatchObject({
+ 'video-left': { durationInFrames: 60, sourceEnd: 60 },
+ 'video-right': { from: 60, durationInFrames: 60, sourceStart: 0 },
+ 'audio-left': { durationInFrames: 60, sourceEnd: 60 },
+ 'audio-right': { from: 60, durationInFrames: 60, sourceStart: 0 },
+ })
+ })
+
+ it('exposes slider semantics without nesting a button and supports one-frame arrow nudges', () => {
+ const items = makeVideoPair()
+ resetStores(makeTracks(), [...items])
+ useSelectionStore.getState().selectItems(['video-right'])
+ const view = renderItems(items)
+ const videoRight = view.container.querySelector('[data-item-id="video-right"]')!
+ const handle = within(videoRight).getByRole('slider', { name: /rolling trim/i })
+
+ expect(handle).toHaveAttribute('tabindex', '0')
+ expect(handle).toHaveAttribute('aria-valuenow', '60')
+ expect(handle.closest('button')).toBeNull()
+
+ fireEvent.keyDown(handle, { key: 'ArrowRight' })
+
+ expect(useItemsStore.getState().itemById).toMatchObject({
+ 'video-left': { durationInFrames: 61 },
+ 'video-right': { from: 61, durationInFrames: 59 },
+ })
+ expect(useTimelineCommandStore.getState().undoStack).toHaveLength(1)
+ })
+
+ it('rejects the whole gesture when a linked participant is effectively locked', () => {
+ const items = makeLinkedFixtureItems()
+ resetStores(makeTracks('locked-group'), items)
+ useSelectionStore.getState().selectItems(['video-right', 'audio-right'])
+ const view = renderItems(items)
+ const videoRight = view.container.querySelector('[data-item-id="video-right"]')!
+ const handle = within(videoRight).getByRole('slider', { name: /rolling trim/i })
+ const before = {
+ items: itemSnapshot(),
+ selection: [...useSelectionStore.getState().selectedItemIds],
+ undoDepth: useTimelineCommandStore.getState().undoStack.length,
+ redoDepth: useTimelineCommandStore.getState().redoStack.length,
+ dirty: useTimelineSettingsStore.getState().isDirty,
+ }
+
+ dragOneFrame(handle)
+
+ expect(useItemsStore.getState().items).toEqual(before.items)
+ expect(useSelectionStore.getState().selectedItemIds).toEqual(before.selection)
+ expect(useTimelineCommandStore.getState().undoStack).toHaveLength(before.undoDepth)
+ expect(useTimelineCommandStore.getState().redoStack).toHaveLength(before.redoDepth)
+ expect(useTimelineSettingsStore.getState().isDirty).toBe(before.dirty)
+ })
+
+ it('keeps the ordinary isolated edge trim handle hit-testable and commits only that edge', () => {
+ const clip = makeTimelineVideoItem({ id: 'isolated' })
+ resetStores(makeTracks(), [clip])
+ useSelectionStore.getState().selectItems(['isolated'])
+ const view = renderItems([clip])
+ const root = view.container.querySelector('[data-item-id="isolated"]')!
+
+ expect(within(root).queryByRole('slider', { name: /rolling trim/i })).toBeNull()
+ fireEvent.mouseMove(root, { clientX: CLIP_FRAMES, clientY: 40 })
+ const ordinaryHandle = root.querySelector('[data-trim-handle="end"]')!
+ expect(ordinaryHandle).toBeTruthy()
+ expect(ordinaryHandle).not.toHaveClass('pointer-events-none')
+
+ dragOneFrame(ordinaryHandle)
+
+ expect(useItemsStore.getState().itemById.isolated).toMatchObject({
+ from: 0,
+ durationInFrames: 61,
+ sourceStart: 0,
+ sourceEnd: 61,
+ })
+ expect(useTimelineCommandStore.getState().undoStack).toHaveLength(1)
+ })
+})
diff --git a/src/features/timeline/components/timeline-item/index.tsx b/src/features/timeline/components/timeline-item/index.tsx
index 9d883da6b..870c58fa9 100644
--- a/src/features/timeline/components/timeline-item/index.tsx
+++ b/src/features/timeline/components/timeline-item/index.tsx
@@ -3,6 +3,7 @@ import type { TimelineItem as TimelineItemType } from '@/types/timeline'
import { useShallow } from 'zustand/react/shallow'
import { useTimelineStore } from '../../stores/timeline-store'
import { useItemsStore } from '../../stores/items-store'
+import { rollingTrimItems } from '../../stores/actions/item-actions'
import { selectReplaceableCaptionClipIds } from '../../stores/items-store-indexes'
import { useKeyframesStore } from '../../stores/keyframes-store'
import { useEffectDropPreviewStore } from '../../stores/effect-drop-preview-store'
@@ -62,6 +63,10 @@ import { useLinkedSyncPreview } from './use-linked-sync-preview'
import { useClipReadoutLabels } from './use-clip-readout-labels'
import { useTimelineItemPointerHandlers } from './use-timeline-item-pointer-handlers'
import { ClipFloatingLayer } from './clip-floating-layer'
+import { SharedRollingTrimHandle } from './shared-rolling-trim-handle'
+import { getLinkedItemIds } from '../../utils/linked-items'
+import { partitionItemMutationIdsByLock } from '../../utils/track-lock-invariants'
+import { formatTimecode } from '@/shared/utils/time-utils'
const EMPTY_SEGMENT_OVERLAYS = [] as const
const EMPTY_LINKED_ITEMS: TimelineItemType[] = []
@@ -148,6 +153,18 @@ export const TimelineItem = memo(function TimelineItem({
const linkedItemsForCaptionOwnership = useItemsStore(
useCallback((s) => s.linkedItemsByItemId[item.id] ?? EMPTY_LINKED_ITEMS, [item.id]),
)
+ const isEffectivelyLocked = useItemsStore(
+ useCallback(
+ (state) =>
+ trackLocked ||
+ partitionItemMutationIdsByLock({
+ items: state.items,
+ tracks: state.tracks,
+ itemIds: [item.id],
+ }).blockedIds.length > 0,
+ [item.id, trackLocked],
+ ),
+ )
// Lazy, items-keyed memo: legacy generated-caption detection rebuilds only
// when the items array identity changes (not on every store mutation).
const hasGeneratedCaptions = useItemsStore(
@@ -342,7 +359,6 @@ export const TimelineItem = memo(function TimelineItem({
const {
dragAffectsJoin,
isAnyDragActiveRef,
- dragWasActiveRef,
isAltDrag,
isPartOfDrag,
isBeingDragged,
@@ -602,7 +618,6 @@ export const TimelineItem = memo(function TimelineItem({
activeToolRef,
smartTrimIntentRef,
smartBodyIntent,
- dragWasActiveRef,
isTrimming,
isStretching,
isSlipSlideActive,
@@ -613,6 +628,27 @@ export const TimelineItem = memo(function TimelineItem({
handleTrimStart,
setPointerHint,
})
+ const accessibleName = useMemo(() => {
+ const endFrame = Math.max(item.from, item.from + item.durationInFrames - 1)
+ return `Media ${item.label}, ${item.type} clip on track ${item.trackId}, time range ${formatTimecode(item.from, fps)} to ${formatTimecode(endFrame, fps)}`
+ }, [fps, item.durationInFrames, item.from, item.label, item.trackId, item.type])
+ const handleKeyDown = useCallback(
+ (event: React.KeyboardEvent) => {
+ if (event.target !== event.currentTarget) return
+ if (event.key !== 'Enter' && event.key !== ' ' && event.code !== 'Space') return
+
+ event.preventDefault()
+ event.stopPropagation()
+ if (isEffectivelyLocked) return
+
+ const timelineItems = useItemsStore.getState().items
+ const targetIds = useEditorStore.getState().linkedSelectionEnabled
+ ? getLinkedItemIds(timelineItems, item.id)
+ : [item.id]
+ useSelectionStore.getState().selectItems(targetIds)
+ },
+ [isEffectivelyLocked, item.id],
+ )
// Cursor class based on state
const cursorClass = getClipCursorClass({
@@ -636,6 +672,46 @@ export const TimelineItem = memo(function TimelineItem({
hasGapBefore,
gapBeforeFrames,
} = useClipNeighbors(item)
+ const rightNeighborId = rightNeighbor?.id ?? null
+ const rightNeighborSelected = useSelectionStore(
+ useCallback(
+ (state) => rightNeighborId !== null && state.selectedItemIdSet.has(rightNeighborId),
+ [rightNeighborId],
+ ),
+ )
+ const canExposeSharedRollingHandle =
+ !trackLocked &&
+ (activeTool === 'select' || activeTool === 'trim-edit') &&
+ (!isAnyDragActiveRef.current || isTrimming)
+ // The clip under the pointer owns a hovered cut. For selection-only display,
+ // the incoming/right clip owns the cut when both neighbors are selected so
+ // one physical edit point never gets duplicate hit targets.
+ const showSharedRollingStart =
+ canExposeSharedRollingHandle &&
+ leftNeighbor !== null &&
+ (smartTrimIntent === 'roll-start' || (isSelected && rollHoverEdge !== 'start'))
+ const showSharedRollingEnd =
+ canExposeSharedRollingHandle &&
+ rightNeighbor !== null &&
+ (smartTrimIntent === 'roll-end' ||
+ (isSelected && !rightNeighborSelected && rollHoverEdge !== 'end'))
+ const hasSharedRollingHandle = showSharedRollingStart || showSharedRollingEnd
+
+ const handleSharedRollingTrimStart = useCallback(
+ (event: React.MouseEvent, handle: 'start' | 'end') => {
+ handleTrimStart(event, handle, { forcedMode: 'rolling' })
+ },
+ [handleTrimStart],
+ )
+ const handleSharedRollingKeyboardStep = useCallback(
+ (handle: 'start' | 'end', deltaFrames: number) => {
+ const left = handle === 'start' ? leftNeighbor : item
+ const right = handle === 'start' ? item : rightNeighbor
+ if (!left || !right) return
+ rollingTrimItems(left.id, right.id, deltaFrames)
+ },
+ [item, leftNeighbor, rightNeighbor],
+ )
const {
getCanJoinSelected,
@@ -919,14 +995,7 @@ export const TimelineItem = memo(function TimelineItem({
>
- {/* Keep selection visible throughout drag so the moving cohort stays legible. */}
- {isSelected && !trackLocked && (
-
- )}
-
- {isEffectDropTarget && (
-
- {multiEffectDropTargetCount > 1 && (
-
- {multiEffectDropTargetCount} clips
-
- )}
-
- )}
+
+ {/* Keep selection visible throughout drag so the moving cohort stays legible. */}
+ {isSelected && !trackLocked && (
+
+ )}
-
- {!useCompactClipShell && (
- <>
-
-
- {isVisualFadeItem && (
-
-
+ {isEffectDropTarget && (
+
+ {multiEffectDropTargetCount > 1 && (
+
+ {multiEffectDropTargetCount} clips
)}
+
+ )}
- {item.type === 'audio' && (
-
+
+ {!useCompactClipShell && (
+ <>
+
+
+ {isVisualFadeItem && (
-
-
- )}
-
- )}
+
+
+ )}
-
+ {item.type === 'audio' && (
+
+
+
+
+ )}
+
+ )}
- {!useCompactClipShell && (
- /* Status indicators */
-
{
- useSelectionStore.getState().toggleKeyframeLanes(item.id)
- }}
- onMotionOpen={() => {
- useSelectionStore.getState().selectItems([item.id])
- useEditorStore.getState().setRightSidebarOpen(true)
- useEditorStore.getState().setClipInspectorTab('motion')
- }}
+
- )}
+
+ {!useCompactClipShell && (
+ /* Status indicators stay outside the clip's button semantics. */
+
{
+ useSelectionStore.getState().toggleKeyframeLanes(item.id)
+ }}
+ onMotionOpen={() => {
+ useSelectionStore.getState().selectItems([item.id])
+ useEditorStore.getState().setRightSidebarOpen(true)
+ useEditorStore.getState().setClipInspectorTab('motion')
+ }}
+ />
+ )}
+
{!useCompactClipShell && isVisualFadeItem && (
)}
+ {showSharedRollingStart && leftNeighbor && (
+
+ )}
+ {showSharedRollingEnd && rightNeighbor && (
+
+ )}
+
{/* Rate stretch handles */}
{!useCompactClipShell && (
({
}))
vi.mock('@/features/timeline/deps/settings', () => ({
- useResolvedHotkeys: () => ({}),
+ useResolvedHotkeys: () => ({
+ JOIN_ITEMS: 'shift+j',
+ FREEZE_FRAME: 'shift+f',
+ DELETE_SELECTED: 'delete',
+ RIPPLE_DELETE: 'mod+backspace',
+ }),
}))
vi.mock('@/config/hotkeys', () => ({
- formatHotkeyBinding: () => '',
+ formatHotkeyBinding: (binding: string) =>
+ ({
+ 'mod+backspace': 'Ctrl + Backspace',
+ 'shift+j': 'Shift + J',
+ 'shift+f': 'Shift + F',
+ delete: 'Delete',
+ })[binding] ?? '',
}))
function renderContextMenu(overrides: Partial> = {}) {
@@ -121,6 +132,12 @@ describe('ItemContextMenu scene detection', () => {
expect(screen.getByRole('button', { name: 'AI (Liquid Vision)' })).toBeInTheDocument()
})
+ it('shows the resolved ripple-delete keycap', () => {
+ renderContextMenu()
+
+ expect(screen.getByText('Ctrl + Backspace')).toBeInTheDocument()
+ })
+
it('dispatches the selected verification model when a scene detection option is clicked', () => {
const { onDetectScenes } = renderContextMenu()
diff --git a/src/features/timeline/components/timeline-item/item-context-menu.tsx b/src/features/timeline/components/timeline-item/item-context-menu.tsx
index 8c087f571..71c11c0b2 100644
--- a/src/features/timeline/components/timeline-item/item-context-menu.tsx
+++ b/src/features/timeline/components/timeline-item/item-context-menu.tsx
@@ -395,6 +395,7 @@ function GradeActions({ t }: { t: ReturnType['t'] }) {
function JoinActions({
t,
+ hotkeys,
canJoinSelected,
hasJoinableLeft,
hasJoinableRight,
@@ -414,19 +415,19 @@ function JoinActions({
{showJoinLeft && (
{t('timeline.contextMenu.joinWithPrevious')}
- J
+ {formatHotkeyBinding(hotkeys.JOIN_ITEMS)}
)}
{showJoinRight && (
{t('timeline.contextMenu.joinWithNext')}
- J
+ {formatHotkeyBinding(hotkeys.JOIN_ITEMS)}
)}
{canJoinSelected && (
{t('timeline.contextMenu.joinSelected')}
- J
+ {formatHotkeyBinding(hotkeys.JOIN_ITEMS)}
)}
@@ -513,6 +514,7 @@ function LayoutActions({ t, selectedCount, onBentoLayout }: LayoutActionsProps)
function MediaActions({
t,
+ hotkeys,
canReverse,
isReversed,
isVideoItem,
@@ -542,7 +544,7 @@ function MediaActions({
<>
{t('timeline.contextMenu.insertFreezeFrame')}
- Shift+F
+ {formatHotkeyBinding(hotkeys.FREEZE_FRAME)}
@@ -705,6 +707,7 @@ function CompositionActions({
function DestructiveActions({
t,
+ hotkeys,
isSelected,
canRippleDelete = true,
canDelete = true,
@@ -720,7 +723,7 @@ function DestructiveActions({
className="text-destructive focus:text-destructive"
>
{t('timeline.contextMenu.rippleDelete')}
- Ctrl+Del
+ {formatHotkeyBinding(hotkeys.RIPPLE_DELETE)}
)}
{canDelete && (
@@ -730,7 +733,7 @@ function DestructiveActions({
className="text-destructive focus:text-destructive"
>
{t('common.delete')}
- Del
+ {formatHotkeyBinding(hotkeys.DELETE_SELECTED)}
)}
diff --git a/src/features/timeline/components/timeline-item/post-drag-click-guard.test.ts b/src/features/timeline/components/timeline-item/post-drag-click-guard.test.ts
index d4f805a3c..e2f089c5b 100644
--- a/src/features/timeline/components/timeline-item/post-drag-click-guard.test.ts
+++ b/src/features/timeline/components/timeline-item/post-drag-click-guard.test.ts
@@ -1,23 +1,51 @@
-// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from 'vite-plus/test'
+import {
+ resetPostTimelineGestureClickForTest,
+ suppressPostTimelineGestureClick,
+} from './post-drag-click-guard'
-import { describe, expect, it } from 'vite-plus/test'
-import { shouldSuppressTimelineItemClickAfterDrag } from './post-drag-click-guard'
+function dispatchMouseEvent(target: EventTarget, type: 'mousedown' | 'click', detail = 1) {
+ target.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, detail }))
+}
-describe('shouldSuppressTimelineItemClickAfterDrag', () => {
- it('suppresses post-drag clicks for selection tools', () => {
- expect(shouldSuppressTimelineItemClickAfterDrag('select', true)).toBe(true)
- expect(shouldSuppressTimelineItemClickAfterDrag('trim-edit', true)).toBe(true)
+describe('post timeline gesture click ownership', () => {
+ afterEach(() => resetPostTimelineGestureClickForTest())
+
+ it('suppresses exactly one browser-generated click', () => {
+ const element = document.createElement('button')
+ const onClick = vi.fn()
+ element.addEventListener('click', onClick)
+ document.body.appendChild(element)
+
+ suppressPostTimelineGestureClick()
+ dispatchMouseEvent(element, 'click')
+ dispatchMouseEvent(element, 'click')
+
+ expect(onClick).toHaveBeenCalledTimes(1)
})
- it('allows post-drag clicks for non-selection tools so razor and edit tools still work', () => {
- expect(shouldSuppressTimelineItemClickAfterDrag('razor', true)).toBe(false)
- expect(shouldSuppressTimelineItemClickAfterDrag('rate-stretch', true)).toBe(false)
- expect(shouldSuppressTimelineItemClickAfterDrag('slip', true)).toBe(false)
- expect(shouldSuppressTimelineItemClickAfterDrag('slide', true)).toBe(false)
+ it('releases ownership when a later independent mouse gesture starts', () => {
+ const element = document.createElement('button')
+ const onClick = vi.fn()
+ element.addEventListener('click', onClick)
+ document.body.appendChild(element)
+
+ suppressPostTimelineGestureClick()
+ dispatchMouseEvent(element, 'mousedown')
+ dispatchMouseEvent(element, 'click')
+
+ expect(onClick).toHaveBeenCalledTimes(1)
})
- it('never suppresses when no drag just finished', () => {
- expect(shouldSuppressTimelineItemClickAfterDrag('select', false)).toBe(false)
- expect(shouldSuppressTimelineItemClickAfterDrag('razor', false)).toBe(false)
+ it('does not suppress keyboard or programmatic activation', () => {
+ const element = document.createElement('button')
+ const onClick = vi.fn()
+ element.addEventListener('click', onClick)
+ document.body.appendChild(element)
+
+ suppressPostTimelineGestureClick()
+ dispatchMouseEvent(element, 'click', 0)
+
+ expect(onClick).toHaveBeenCalledTimes(1)
})
})
diff --git a/src/features/timeline/components/timeline-item/post-drag-click-guard.ts b/src/features/timeline/components/timeline-item/post-drag-click-guard.ts
index c6e9549c9..afc7d7edf 100644
--- a/src/features/timeline/components/timeline-item/post-drag-click-guard.ts
+++ b/src/features/timeline/components/timeline-item/post-drag-click-guard.ts
@@ -1,12 +1,41 @@
-import type { SelectionState } from '@/shared/state/selection/types'
-
-export function shouldSuppressTimelineItemClickAfterDrag(
- activeTool: SelectionState['activeTool'],
- dragWasActive: boolean,
-): boolean {
- if (!dragWasActive) {
- return false
+let removePendingClickOwnership: (() => void) | null = null
+
+function clearPendingClickOwnership() {
+ removePendingClickOwnership?.()
+ removePendingClickOwnership = null
+}
+
+/**
+ * Own the browser-generated click that immediately follows a completed mouse
+ * gesture. A later independent click always starts with another mousedown,
+ * which clears the ownership before that click can be dispatched.
+ */
+export function suppressPostTimelineGestureClick(): void {
+ clearPendingClickOwnership()
+ if (typeof document === 'undefined') return
+
+ const handleIndependentMouseDown = () => {
+ clearPendingClickOwnership()
}
+ const handleClick = (event: MouseEvent) => {
+ // Keyboard activation and HTMLElement.click() do not belong to the mouse
+ // gesture and must remain available.
+ if (event.detail === 0) return
+
+ clearPendingClickOwnership()
+ event.preventDefault()
+ event.stopPropagation()
+ event.stopImmediatePropagation()
+ }
+
+ removePendingClickOwnership = () => {
+ document.removeEventListener('mousedown', handleIndependentMouseDown, true)
+ document.removeEventListener('click', handleClick, true)
+ }
+ document.addEventListener('mousedown', handleIndependentMouseDown, true)
+ document.addEventListener('click', handleClick, true)
+}
- return activeTool === 'select' || activeTool === 'trim-edit'
+export function resetPostTimelineGestureClickForTest(): void {
+ clearPendingClickOwnership()
}
diff --git a/src/features/timeline/components/timeline-item/shared-rolling-trim-handle.tsx b/src/features/timeline/components/timeline-item/shared-rolling-trim-handle.tsx
new file mode 100644
index 000000000..4f157c2b3
--- /dev/null
+++ b/src/features/timeline/components/timeline-item/shared-rolling-trim-handle.tsx
@@ -0,0 +1,66 @@
+import { memo } from 'react'
+import { cn } from '@/shared/ui/cn'
+
+interface SharedRollingTrimHandleProps {
+ edge: 'start' | 'end'
+ editPointFrame: number
+ minFrame: number
+ maxFrame: number
+ leftLabel: string
+ rightLabel: string
+ onMouseDown: (event: React.MouseEvent, handle: 'start' | 'end') => void
+ onKeyboardStep: (handle: 'start' | 'end', deltaFrames: number) => void
+}
+
+/**
+ * A compact rolling-edit target centered on a real cut. It occupies only the
+ * middle of the clip edge so the ordinary full-height trim target remains
+ * available above and below it.
+ */
+export const SharedRollingTrimHandle = memo(function SharedRollingTrimHandle({
+ edge,
+ editPointFrame,
+ minFrame,
+ maxFrame,
+ leftLabel,
+ rightLabel,
+ onMouseDown,
+ onKeyboardStep,
+}: SharedRollingTrimHandleProps) {
+ const label = `Rolling trim between ${leftLabel} and ${rightLabel}`
+
+ return (
+ onMouseDown(event, edge)}
+ onClick={(event) => {
+ event.preventDefault()
+ event.stopPropagation()
+ }}
+ onDoubleClick={(event) => event.stopPropagation()}
+ onKeyDown={(event) => {
+ if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return
+ event.preventDefault()
+ event.stopPropagation()
+ onKeyboardStep(edge, event.key === 'ArrowLeft' ? -1 : 1)
+ }}
+ >
+
+
+
+ )
+})
diff --git a/src/features/timeline/components/timeline-item/timeline-item-accessibility.test.tsx b/src/features/timeline/components/timeline-item/timeline-item-accessibility.test.tsx
new file mode 100644
index 000000000..f775b8f3b
--- /dev/null
+++ b/src/features/timeline/components/timeline-item/timeline-item-accessibility.test.tsx
@@ -0,0 +1,288 @@
+import { act, fireEvent, render } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+import { useEditorStore } from '@/shared/state/editor'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useSelectionStore } from '@/shared/state/selection'
+import type { TimelineItem as TimelineItemType, TimelineTrack, VideoItem } from '@/types/timeline'
+
+import { usePlaybackShortcuts } from '../../hooks/shortcuts/use-playback-shortcuts'
+import { useItemsStore } from '../../stores/items-store'
+import { useTimelineStore } from '../../stores/timeline-store'
+import { TimelineItemHitTarget } from '../timeline-item-hit-target'
+import { TimelineItem } from '.'
+
+const dragMocks = vi.hoisted(() => ({
+ handleDragStart: vi.fn(),
+}))
+
+vi.mock('../../hooks/use-timeline-drag', () => ({
+ dragOffsetRef: { current: { x: 0, y: 0 } },
+ dragPreviewOffsetByItemRef: { current: {} },
+ useTimelineDrag: () => ({
+ isDragging: false,
+ dragOffset: { x: 0, y: 0 },
+ handleDragStart: dragMocks.handleDragStart,
+ }),
+}))
+
+vi.mock('./item-context-menu', () => ({
+ ItemContextMenu: ({ children }: { children: React.ReactNode }) => children,
+}))
+vi.mock('./clip-content', () => ({ ClipContent: () => Clip picture }))
+vi.mock('./clip-indicators', () => ({
+ ClipIndicators: ({ onKeyframesToggle }: { onKeyframesToggle?: () => void }) => (
+
+ ),
+}))
+vi.mock('./trim-handles', () => ({ TrimHandles: () => null }))
+vi.mock('./stretch-handles', () => ({ StretchHandles: () => null }))
+vi.mock('./audio-fade-handles', () => ({ AudioFadeHandles: () => null }))
+vi.mock('./video-fade-handles', () => ({ VideoFadeHandles: () => null }))
+vi.mock('./audio-volume-control', () => ({ AudioVolumeControl: () => null }))
+vi.mock('./join-indicators', () => ({ ZoomGatedJoinIndicators: () => null }))
+vi.mock('./segment-status-overlays', () => ({ SegmentStatusOverlays: () => null }))
+vi.mock('./clip-floating-layer', () => ({ ClipFloatingLayer: () => null }))
+
+const VIDEO_TRACK: TimelineTrack = {
+ id: 'track-video-1',
+ name: 'V1',
+ kind: 'video',
+ height: 72,
+ locked: false,
+ visible: true,
+ muted: false,
+ solo: false,
+ order: 0,
+ items: [],
+}
+
+const AUDIO_TRACK: TimelineTrack = {
+ ...VIDEO_TRACK,
+ id: 'track-audio-1',
+ name: 'A1',
+ kind: 'audio',
+ locked: true,
+ order: 1,
+}
+
+const ITEM: VideoItem = {
+ id: 'clip-video-1',
+ type: 'video',
+ trackId: VIDEO_TRACK.id,
+ from: 30,
+ durationInFrames: 60,
+ label: 'Interview close-up.mp4',
+ src: 'blob:clip-video-1',
+ mediaId: 'media-video-1',
+ sourceStart: 0,
+ sourceEnd: 60,
+}
+
+function setTimeline(items: TimelineItemType[], tracks: TimelineTrack[]) {
+ useItemsStore.getState().setItems(items)
+ useItemsStore.getState().setTracks(tracks)
+ useTimelineStore.setState({ fps: 30, items, tracks })
+}
+
+function renderItem(item: TimelineItemType = ITEM, trackLocked = false) {
+ return render(
+ <>
+
+
+ ,
+ )
+}
+
+function PlaybackShortcutHarness({ children }: { children: React.ReactNode }) {
+ usePlaybackShortcuts({})
+ return children
+}
+
+function dispatchKey(target: HTMLElement, key: string, code: string): KeyboardEvent {
+ const event = new KeyboardEvent('keydown', {
+ key,
+ code,
+ bubbles: true,
+ cancelable: true,
+ })
+ act(() => target.dispatchEvent(event))
+ return event
+}
+
+describe('TimelineItem keyboard accessibility', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ useEditorStore.getState().setLinkedSelectionEnabled(false)
+ useSelectionStore.getState().clearSelection()
+ useSelectionStore.getState().setActiveTool('select')
+ usePlaybackStore.setState({ isPlaying: false, currentFrame: 0 })
+ setTimeline([ITEM], [{ ...VIDEO_TRACK, items: [ITEM] }])
+ })
+
+ it('exposes one named clip focus target with media, type, time range, and selected state', () => {
+ const { container } = renderItem()
+ const semanticRoots = container.querySelectorAll(
+ '[data-timeline-item][role="button"][tabindex="0"]',
+ )
+ expect(semanticRoots).toHaveLength(1)
+
+ const clip = semanticRoots[0]!
+ expect(clip).toHaveAccessibleName(/Interview close-up\.mp4/i)
+ expect(clip).toHaveAccessibleName(/video/i)
+ expect(clip).toHaveAccessibleName(/00:00:01:00/i)
+ expect(clip).toHaveAccessibleName(/00:00:02:29/i)
+ expect(clip).toHaveAttribute('aria-pressed', 'false')
+
+ act(() => useSelectionStore.getState().selectItems([ITEM.id]))
+ expect(clip).toHaveAttribute('aria-pressed', 'true')
+
+ clip.focus()
+ expect(clip).toHaveFocus()
+ expect(container.querySelector('[data-timeline-hit-target]')).toHaveAttribute(
+ 'aria-hidden',
+ 'true',
+ )
+ expect(container.querySelector('[data-timeline-hit-target]')).not.toHaveAttribute('tabindex')
+ })
+
+ it.each([
+ ['Enter', 'Enter'],
+ [' ', 'Space'],
+ ])('activates exactly once with %s after global capture declines it', (key, code) => {
+ const selectItems = vi.spyOn(useSelectionStore.getState(), 'selectItems')
+ const togglePlayPause = vi.spyOn(usePlaybackStore.getState(), 'togglePlayPause')
+ const captureListener = vi.fn()
+ document.addEventListener('keydown', captureListener, { capture: true })
+
+ const { container } = render(
+
+
+ ,
+ )
+ const clip = container.querySelector('[data-timeline-item]')!
+ const event = dispatchKey(clip, key, code)
+
+ document.removeEventListener('keydown', captureListener, { capture: true })
+ expect(captureListener).toHaveBeenCalledTimes(1)
+ expect(event.defaultPrevented).toBe(true)
+ expect(selectItems).toHaveBeenCalledTimes(1)
+ expect(selectItems).toHaveBeenLastCalledWith([ITEM.id])
+ expect(togglePlayPause).not.toHaveBeenCalled()
+ })
+
+ it('keeps native clip controls outside button semantics and lets them own keyboard events', () => {
+ const selectItems = vi.spyOn(useSelectionStore.getState(), 'selectItems')
+ const { container, getByRole } = renderItem()
+ const clip = container.querySelector('[data-timeline-item]')!
+ const control = getByRole('button', { name: 'Show keyframe panel' })
+ const controlKeyDown = vi.fn()
+ control.addEventListener('keydown', controlKeyDown)
+
+ expect(clip.contains(control)).toBe(false)
+ control.focus()
+ expect(control).toHaveFocus()
+ dispatchKey(control, ' ', 'Space')
+
+ expect(controlKeyDown).toHaveBeenCalledTimes(1)
+ expect(selectItems).not.toHaveBeenCalled()
+ })
+
+ it('semantically declines J, K, and L transport while the clip root is focused', () => {
+ const { container } = render(
+
+
+ ,
+ )
+ const clip = container.querySelector('[data-timeline-item]')!
+ clip.focus()
+
+ dispatchKey(clip, 'j', 'KeyJ')
+ dispatchKey(clip, 'k', 'KeyK')
+ dispatchKey(clip, 'l', 'KeyL')
+
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: false,
+ playbackRate: 1,
+ transportMode: 'normal',
+ })
+ })
+
+ it('keeps direct and linked-cohort locked clips focusable but mutation-inert', () => {
+ const linkedItem = { ...ITEM, linkedGroupId: 'av-1' }
+ const linkedAudio = {
+ ...ITEM,
+ id: 'clip-audio-1',
+ type: 'audio' as const,
+ trackId: AUDIO_TRACK.id,
+ linkedGroupId: 'av-1',
+ }
+ setTimeline(
+ [linkedItem, linkedAudio],
+ [
+ { ...VIDEO_TRACK, items: [linkedItem] },
+ { ...AUDIO_TRACK, items: [linkedAudio] },
+ ],
+ )
+ const selectItems = vi.spyOn(useSelectionStore.getState(), 'selectItems')
+ const togglePlayPause = vi.spyOn(usePlaybackStore.getState(), 'togglePlayPause')
+ const { container, rerender } = renderItem(linkedItem)
+ const linkedLockedClip = container.querySelector('[data-timeline-item]')!
+
+ expect(linkedLockedClip).toHaveAttribute('aria-disabled', 'true')
+ linkedLockedClip.focus()
+ expect(linkedLockedClip).toHaveFocus()
+ dispatchKey(linkedLockedClip, ' ', 'Space')
+ dispatchKey(linkedLockedClip, 'Enter', 'Enter')
+ expect(selectItems).not.toHaveBeenCalled()
+ expect(togglePlayPause).not.toHaveBeenCalled()
+
+ rerender(
+ ,
+ )
+ const directlyLockedClip = container.querySelector('[data-timeline-item]')!
+ expect(directlyLockedClip).toHaveAttribute('aria-disabled', 'true')
+ dispatchKey(directlyLockedClip, ' ', 'Space')
+ expect(selectItems).not.toHaveBeenCalled()
+ expect(togglePlayPause).not.toHaveBeenCalled()
+ })
+
+ it('preserves click, drag, and Razor ownership on the semantic surface', () => {
+ const splitItem = vi.spyOn(useTimelineStore.getState(), 'splitItem')
+ const { container } = renderItem()
+ const clip = container.querySelector('[data-timeline-item]')!
+
+ fireEvent.mouseDown(clip, { button: 0, clientX: 20, clientY: 10 })
+ expect(dragMocks.handleDragStart).toHaveBeenCalledTimes(1)
+
+ act(() => useSelectionStore.getState().setActiveTool('razor'))
+ fireEvent.click(clip, { button: 0, clientX: 20, clientY: 10 })
+ expect(splitItem).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/src/features/timeline/components/timeline-item/trim-handles.test.tsx b/src/features/timeline/components/timeline-item/trim-handles.test.tsx
index 4ab108638..a30618976 100644
--- a/src/features/timeline/components/timeline-item/trim-handles.test.tsx
+++ b/src/features/timeline/components/timeline-item/trim-handles.test.tsx
@@ -1,5 +1,6 @@
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vite-plus/test'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { useSettingsStore } from '@/features/timeline/deps/settings'
import { TrimHandles } from './trim-handles'
import { VideoFadeHandles } from './video-fade-handles'
import { AudioFadeHandles } from './audio-fade-handles'
@@ -27,6 +28,20 @@ describe('TrimHandles', () => {
onJoinRight: vi.fn(),
}
+ const originalPlatform = Object.getOwnPropertyDescriptor(window.navigator, 'platform')
+
+ beforeEach(() => {
+ useSettingsStore.getState().resetHotkeys()
+ })
+
+ afterEach(() => {
+ if (originalPlatform) {
+ Object.defineProperty(window.navigator, 'platform', originalPlatform)
+ } else {
+ delete (window.navigator as { platform?: string }).platform
+ }
+ })
+
it('fires onTrimStart on mousedown when the left handle is visible', () => {
const onTrimStart = vi.fn()
render()
@@ -52,6 +67,34 @@ describe('TrimHandles', () => {
fireEvent.mouseDown(rightHandle!)
expect(onTrimStart).toHaveBeenCalledWith(expect.any(Object), 'end')
})
+
+ it('updates the trim join menu from the live Windows shortcut binding', async () => {
+ Object.defineProperty(window.navigator, 'platform', { configurable: true, value: 'Win32' })
+ const { container } = render(
+ ,
+ )
+ const leftHandle = container.querySelector('[class*="left-0"]')
+ expect(leftHandle).toBeTruthy()
+ fireEvent.contextMenu(leftHandle!)
+ expect(await screen.findByText('Shift + J')).toBeInTheDocument()
+
+ useSettingsStore.getState().setHotkeyBinding('JOIN_ITEMS', 'mod+alt+j')
+
+ await waitFor(() => expect(screen.getByText('Ctrl + Alt + J')).toBeInTheDocument())
+ })
+
+ it('formats a remapped trim join shortcut for macOS', async () => {
+ Object.defineProperty(window.navigator, 'platform', { configurable: true, value: 'MacIntel' })
+ useSettingsStore.getState().setHotkeyBinding('JOIN_ITEMS', 'mod+alt+j')
+ const { container } = render(
+ ,
+ )
+ const rightHandle = container.querySelector('[class*="right-0"]')
+ expect(rightHandle).toBeTruthy()
+ fireEvent.contextMenu(rightHandle!)
+
+ expect(await screen.findByText('Cmd + Option + J')).toBeInTheDocument()
+ })
})
/**
diff --git a/src/features/timeline/components/timeline-item/trim-handles.tsx b/src/features/timeline/components/timeline-item/trim-handles.tsx
index 0fc43bd31..62b23fc92 100644
--- a/src/features/timeline/components/timeline-item/trim-handles.tsx
+++ b/src/features/timeline/components/timeline-item/trim-handles.tsx
@@ -7,6 +7,8 @@ import {
ContextMenuTrigger,
} from '@/components/ui/context-menu'
import { cn } from '@/shared/ui/cn'
+import { formatHotkeyBinding } from '@/config/hotkeys'
+import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
import type { SmartTrimIntent } from '../../utils/smart-trim-zones'
import {
CONSTRAINED_COLORS,
@@ -93,6 +95,8 @@ export const TrimHandles = memo(function TrimHandles({
onJoinLeft,
onJoinRight,
}: TrimHandlesProps) {
+ const hotkeys = useResolvedHotkeys()
+ const joinShortcutLabel = formatHotkeyBinding(hotkeys.JOIN_ITEMS)
const isRollingStart = smartTrimIntent === 'roll-start'
const isRollingEnd = smartTrimIntent === 'roll-end'
const isNeighborRollStart = rollHoverEdge === 'start'
@@ -146,6 +150,7 @@ export const TrimHandles = memo(function TrimHandles({
Join
- J
+ {joinShortcutLabel}
@@ -205,6 +210,7 @@ export const TrimHandles = memo(function TrimHandles({
Join
- J
+ {joinShortcutLabel}
diff --git a/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.test.tsx b/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.test.tsx
index 0f35021e6..f64d34e0c 100644
--- a/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.test.tsx
+++ b/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.test.tsx
@@ -3,6 +3,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
import type { CompositionItem, TextItem, VideoItem } from '@/types/timeline'
import { useSelectionStore } from '@/shared/state/selection'
import { useEditorStore } from '@/shared/state/editor'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useMicRecordingStore } from '@/shared/state/mic-recording-store'
import { useSourcePlayerStore } from '@/shared/state/source-player'
import { useTimelineStore } from '../../stores/timeline-store'
import { useCompositionNavigationStore } from '../../stores/composition-navigation-store'
@@ -89,7 +91,6 @@ function makeInput(
activeToolRef: { current: activeTool },
smartTrimIntentRef: { current: null },
smartBodyIntent: null,
- dragWasActiveRef: { current: false },
isTrimming: false,
isStretching: false,
isSlipSlideActive: false,
@@ -114,6 +115,13 @@ describe('useTimelineItemPointerHandlers', () => {
vi.clearAllMocks()
// Deterministic single-item selection (linked selection expands target ids)
useEditorStore.getState().setLinkedSelectionEnabled(false)
+ usePlaybackStore.setState({
+ currentFrame: 0,
+ previewFrame: null,
+ previewItemId: null,
+ isPlaying: false,
+ })
+ useMicRecordingStore.setState({ status: 'idle' })
})
afterEach(() => {
@@ -141,6 +149,37 @@ describe('useTimelineItemPointerHandlers', () => {
expect(selectItems).toHaveBeenCalledWith(['item-1'])
})
+ it('seeks from click geometry when the hover preview is stale at the next boundary', () => {
+ usePlaybackStore.setState({
+ currentFrame: 0,
+ previewFrame: 50,
+ previewItemId: 'item-1',
+ isPlaying: true,
+ })
+ const handlers = renderHandlers(makeInput({ activeTool: 'select' }))
+
+ handlers.handleClick(makeMouseEvent({ clientX: 2 }))
+
+ expect(usePlaybackStore.getState().currentFrame).toBe(20)
+ expect(usePlaybackStore.getState().previewFrame).toBeNull()
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+ })
+
+ it('selects without seeking or pausing while a microphone take is active', () => {
+ usePlaybackStore.setState({ currentFrame: 12, previewFrame: 34, isPlaying: true })
+ useMicRecordingStore.setState({ status: 'recording' })
+ const handlers = renderHandlers(makeInput({ activeTool: 'select' }))
+
+ handlers.handleClick(makeMouseEvent())
+
+ expect(useSelectionStore.getState().selectedItemIds).toEqual(['item-1'])
+ expect(usePlaybackStore.getState()).toMatchObject({
+ currentFrame: 12,
+ previewFrame: 34,
+ isPlaying: true,
+ })
+ })
+
it('splits the item at the cursor with the razor tool', () => {
const splitItem = vi.spyOn(useTimelineStore.getState(), 'splitItem')
const handlers = renderHandlers(makeInput({ activeTool: 'razor' }))
@@ -240,4 +279,20 @@ describe('useTimelineItemPointerHandlers', () => {
expect(input.handleSlipSlideStart).not.toHaveBeenCalled()
})
})
+
+ it('preserves smart edge trim routing', () => {
+ const input = makeInput({
+ smartTrimIntentRef: { current: 'ripple-start' },
+ })
+ const handlers = renderHandlers(input)
+ const event = makeMouseEvent()
+
+ handlers.handleSmartTrimStart(event, 'start')
+
+ expect(input.handleTrimStart).toHaveBeenCalledWith(event, 'start', {
+ forcedMode: 'ripple',
+ destroyTransitionAtHandle: false,
+ })
+ expect(input.handleDragStart).not.toHaveBeenCalled()
+ })
})
diff --git a/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.ts b/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.ts
index 173d19663..09055a2d0 100644
--- a/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.ts
+++ b/src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.ts
@@ -2,6 +2,7 @@ import { useCallback, type Dispatch, type RefObject, type SetStateAction } from
import type { TimelineItem as TimelineItemType } from '@/types/timeline'
import type { SelectionState } from '@/shared/state/selection'
import { usePlaybackStore } from '@/shared/state/playback'
+import { isMicRecordingActive, useMicRecordingStore } from '@/shared/state/mic-recording-store'
import { useEditorStore } from '@/shared/state/editor'
import { useSourcePlayerStore } from '@/shared/state/source-player'
import { useSelectionStore } from '@/shared/state/selection'
@@ -31,14 +32,12 @@ import {
} from '../../utils/smart-trim-zones'
import { isRateStretchableItem } from '../../hooks/use-rate-stretch'
import { getTimelineClipLabelRowHeightPx } from './hover-layout'
-import { shouldSuppressTimelineItemClickAfterDrag } from './post-drag-click-guard'
import { emitUiSound } from '@/shared/ui/ui-sound'
import type { useTimelineDrag } from '../../hooks/use-timeline-drag'
import type { useTimelineTrim } from '../../hooks/use-timeline-trim'
import type { useRateStretch } from '../../hooks/use-rate-stretch'
import type { useTimelineSlipSlide } from '../../hooks/use-timeline-slip-slide'
import type { useSmartTrimHover } from './use-smart-trim-hover'
-import type { useDragVisualState } from './use-drag-visual-state'
export interface TimelineItemPointerHint {
x: number
@@ -54,7 +53,6 @@ export interface TimelineItemPointerHandlersInput {
activeToolRef: RefObject
smartTrimIntentRef: ReturnType['smartTrimIntentRef']
smartBodyIntent: SmartBodyIntent
- dragWasActiveRef: ReturnType['dragWasActiveRef']
isTrimming: boolean
isStretching: boolean
isSlipSlideActive: boolean
@@ -90,7 +88,6 @@ export function useTimelineItemPointerHandlers({
activeToolRef,
smartTrimIntentRef,
smartBodyIntent,
- dragWasActiveRef,
isTrimming,
isStretching,
isSlipSlideActive,
@@ -109,9 +106,6 @@ export function useTimelineItemPointerHandlers({
emitUiSound('error')
return
}
- if (shouldSuppressTimelineItemClickAfterDrag(activeToolRef.current, dragWasActiveRef.current))
- return
-
// Razor tool: split item at click position
if (activeToolRef.current === 'razor') {
const tracksContainer = e.currentTarget.closest('.timeline-tracks') as HTMLElement | null
@@ -156,6 +150,26 @@ export function useTimelineItemPointerHandlers({
return
}
+ // Clip clicks stop propagation for selection, so they must explicitly
+ // seek from this click's own geometry. The hover skimmer can still hold
+ // the previous pointer event (including the next clip boundary), so it
+ // must never own the committed click frame.
+ if (!isMicRecordingActive(useMicRecordingStore.getState().status)) {
+ const playback = usePlaybackStore.getState()
+ const rect = e.currentTarget.getBoundingClientRect()
+ const relativeX = Math.max(0, Math.min(e.clientX - rect.left, rect.width))
+ const frameOffset =
+ rect.width > 0
+ ? Math.min(
+ Math.max(0, item.durationInFrames - 1),
+ Math.floor((relativeX / rect.width) * item.durationInFrames),
+ )
+ : 0
+ const clickedFrame = Math.max(0, item.from + frameOffset)
+ playback.pause()
+ playback.finishScrub(clickedFrame)
+ }
+
if (activeToolRef.current === 'select' || activeToolRef.current === 'trim-edit') {
const bridgedHandle = smartTrimIntentToHandle(smartTrimIntentRef.current)
if (bridgedHandle) {
@@ -193,7 +207,7 @@ export function useTimelineItemPointerHandlers({
selectItems(targetIds)
}
},
- [activeToolRef, dragWasActiveRef, trackLocked, item.from, item.id, smartTrimIntentRef],
+ [activeToolRef, trackLocked, item.durationInFrames, item.from, item.id, smartTrimIntentRef],
)
// Double-click: open media in source monitor with clip's source range as I/O
diff --git a/src/features/timeline/components/timeline-markers.test.tsx b/src/features/timeline/components/timeline-markers.test.tsx
index bbe6783a6..e6699c419 100644
--- a/src/features/timeline/components/timeline-markers.test.tsx
+++ b/src/features/timeline/components/timeline-markers.test.tsx
@@ -219,6 +219,37 @@ describe('TimelineMarkers ruler scrub cancellation', () => {
expect(usePlaybackStore.getState().previewFrame).toBe(30)
})
+ it('does not restore a queued ruler hover after click-seek release', () => {
+ const frameCallbacks: FrameRequestCallback[] = []
+ vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
+ frameCallbacks.push(callback)
+ return frameCallbacks.length
+ })
+ const { container } = render(
+
+
+
,
+ )
+ const ruler = container.querySelector('[style*="cursor: ew-resize"]') as HTMLDivElement
+ ruler.getBoundingClientRect = () =>
+ ({
+ left: 0,
+ right: 1000,
+ top: 0,
+ bottom: 34,
+ width: 1000,
+ height: 34,
+ }) as DOMRect
+
+ fireEvent.mouseMove(ruler, { clientX: 100 })
+ fireEvent.mouseDown(ruler, { button: 0, clientX: 260 })
+ fireEvent.mouseUp(document, { clientX: 260 })
+ act(() => frameCallbacks.splice(0).forEach((callback) => callback(performance.now())))
+
+ expect(usePlaybackStore.getState().currentFrame).toBe(78)
+ expect(usePlaybackStore.getState().previewFrame).toBeNull()
+ })
+
it('keeps the IO strip in its own lane above the viewport ruler canvas', () => {
useTimelineStore.setState({ inPoint: 15, outPoint: 45 })
diff --git a/src/features/timeline/components/timeline-markers.tsx b/src/features/timeline/components/timeline-markers.tsx
index 9fa308c0c..2991b4895 100644
--- a/src/features/timeline/components/timeline-markers.tsx
+++ b/src/features/timeline/components/timeline-markers.tsx
@@ -18,6 +18,7 @@ import {
beginTimelineSkimmerScrub,
endTimelineSkimmerScrub,
mainTimelineScrubActiveRef,
+ timelineSkimmerScrubSignal,
} from '@/shared/timeline/main-timeline-scrub'
import {
getTimelineScrubViewportProgress,
@@ -912,6 +913,19 @@ export const TimelineMarkers = memo(function TimelineMarkers({
[],
)
+ useEffect(
+ () =>
+ timelineSkimmerScrubSignal.subscribe(() => {
+ if (!timelineSkimmerScrubSignal.current) return
+ if (hoverPreviewRafRef.current !== null) {
+ cancelAnimationFrame(hoverPreviewRafRef.current)
+ hoverPreviewRafRef.current = null
+ }
+ pendingHoverPreviewFrameRef.current = null
+ }),
+ [],
+ )
+
const handleRangeMouseDown = useCallback(
(e: React.PointerEvent) => {
const startIn = inPointRef.current
@@ -997,6 +1011,16 @@ export const TimelineMarkers = memo(function TimelineMarkers({
// without moving the mic audio would desync the recording irreparably.
if (isMicRecordingActive(useMicRecordingStore.getState().status)) return
+ // A pointer move immediately before mousedown may still have a hover
+ // publication queued for the next animation frame. The click scrub now
+ // owns this pointer sample, so cancel that older preview before it can
+ // resurrect transient state after mouseup clears the scrub preview.
+ if (hoverPreviewRafRef.current !== null) {
+ cancelAnimationFrame(hoverPreviewRafRef.current)
+ hoverPreviewRafRef.current = null
+ }
+ pendingHoverPreviewFrameRef.current = null
+
// Clear marker selection when clicking on ruler (only if a marker is selected)
const { selectedMarkerId } = useSelectionStore.getState()
if (selectedMarkerId) {
diff --git a/src/features/timeline/components/timeline.tsx b/src/features/timeline/components/timeline.tsx
index d6bd0b2c0..7c1258fab 100644
--- a/src/features/timeline/components/timeline.tsx
+++ b/src/features/timeline/components/timeline.tsx
@@ -71,6 +71,7 @@ const TRACK_SIZE_OPTIONS = [
interface TimelineProps {
duration: number // Total timeline duration in seconds
+ compact?: boolean
}
/**
@@ -83,7 +84,7 @@ interface TimelineProps {
*
* Follows modular architecture with granular Zustand selectors
*/
-export const Timeline = memo(function Timeline({ duration }: TimelineProps) {
+export const Timeline = memo(function Timeline({ duration, compact = false }: TimelineProps) {
const { t } = useTranslation()
const hostMode = useEditorStore((s) => s.hostMode)
const canAddTrack = useEditorCapability('timeline.track')
@@ -856,6 +857,7 @@ export const Timeline = memo(function Timeline({ duration }: TimelineProps) {
resizeHandlePosition={getTrackKind(track) === 'video' ? 'top' : 'bottom'}
>
{/* Timeline Header */}
{/* Tracks label with controls */}
setKeyframePanelOpen(false)}
/>
diff --git a/src/features/timeline/components/track-header.tsx b/src/features/timeline/components/track-header.tsx
index 05816e3cc..32aec0288 100644
--- a/src/features/timeline/components/track-header.tsx
+++ b/src/features/timeline/components/track-header.tsx
@@ -19,6 +19,7 @@ import { isTrackSyncLockActive } from '../utils/track-sync-lock'
import { useEditorStore } from '@/shared/state/editor'
interface TrackHeaderProps {
+ compact?: boolean
track: TimelineTrack
isActive: boolean
isSelected: boolean
@@ -43,6 +44,7 @@ interface TrackHeaderProps {
function areTrackHeaderPropsEqual(prev: TrackHeaderProps, next: TrackHeaderProps): boolean {
return (
prev.track === next.track &&
+ prev.compact === next.compact &&
prev.isActive === next.isActive &&
prev.isSelected === next.isSelected &&
prev.canAddTrack === next.canAddTrack &&
@@ -63,6 +65,7 @@ function areTrackHeaderPropsEqual(prev: TrackHeaderProps, next: TrackHeaderProps
*/
// fallow-ignore-next-line complexity
export const TrackHeader = memo(function TrackHeader({
+ compact = false,
track,
isActive,
isSelected,
@@ -98,8 +101,9 @@ export const TrackHeader = memo(function TrackHeader({
style={{
height: `${track.height}px`,
contentVisibility: 'auto',
- containIntrinsicSize: `${TIMELINE_SIDEBAR_WIDTH}px ${track.height}px`,
+ containIntrinsicSize: `${compact ? 80 : TIMELINE_SIDEBAR_WIDTH}px ${track.height}px`,
}}
+ data-track-control-strip={compact ? 'compact' : 'desktop'}
data-track-id={track.id}
data-track-disabled={trackDisabled ? 'true' : undefined}
>
@@ -154,33 +158,35 @@ export const TrackHeader = memo(function TrackHeader({
{/* Solo Button */}
-
+ {!compact && (
+
+ )}
{/* Lock Button */}
-
+ {!compact && (
+
+ )}
-
+ {!compact && (
+
+ )}
{track.name}
-
- {itemCountLabel}
-
+ {!compact && (
+
+ {itemCountLabel}
+
+ )}
diff --git a/src/features/timeline/hooks/shortcuts/runtime-conflicts.test.tsx b/src/features/timeline/hooks/shortcuts/runtime-conflicts.test.tsx
new file mode 100644
index 000000000..7a3e15c79
--- /dev/null
+++ b/src/features/timeline/hooks/shortcuts/runtime-conflicts.test.tsx
@@ -0,0 +1,283 @@
+import { fireEvent, render } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { useHotkeys } from 'react-hotkeys-hook'
+import {
+ HOTKEY_OPTIONS,
+ getRuntimeHotkeyBinding,
+ resolveHotkeys,
+ type HotkeyBindingMap,
+ type HotkeyKey,
+} from '@/config/hotkeys'
+import { useResolvedHotkeys, useSettingsStore } from '@/features/timeline/deps/settings'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useSelectionStore } from '@/shared/state/selection'
+import { useTimelineStore } from '../../stores/timeline-store'
+import type { TimelineTrack, VideoItem } from '@/types/timeline'
+import { useEditingShortcuts } from './use-editing-shortcuts'
+import { useInOutShortcuts } from './use-in-out-shortcuts'
+import { usePlaybackShortcuts } from './use-playback-shortcuts'
+
+const runtimeHotkeysOverride = vi.hoisted(() => ({
+ current: null as HotkeyBindingMap | null,
+}))
+
+const originalPlaybackActions = {
+ togglePlayPause: usePlaybackStore.getState().togglePlayPause,
+ shuttleForward: usePlaybackStore.getState().shuttleForward,
+ shuttleReverse: usePlaybackStore.getState().shuttleReverse,
+}
+
+vi.mock('@/features/timeline/deps/settings', async (importOriginal) => {
+ const actual = await importOriginal()
+ return {
+ ...actual,
+ useResolvedHotkeys: () => runtimeHotkeysOverride.current ?? actual.useResolvedHotkeys(),
+ }
+})
+
+vi.mock('@/hooks/use-runtime-hotkey-binding', () => {
+ const getBindings = () =>
+ runtimeHotkeysOverride.current ?? resolveHotkeys(useSettingsStore.getState().hotkeyOverrides)
+ return {
+ useRuntimeHotkeyBinding: (command: HotkeyKey, variant: 'primary' | 'preview' = 'primary') =>
+ getRuntimeHotkeyBinding(getBindings(), command, variant) ?? '',
+ }
+})
+
+function RuntimeConflictHarness({ onJoin }: { onJoin: () => void }) {
+ const hotkeys = useResolvedHotkeys()
+ const joinBinding = getRuntimeHotkeyBinding(hotkeys, 'JOIN_ITEMS')
+ usePlaybackShortcuts({})
+ useInOutShortcuts()
+ useHotkeys(joinBinding ?? [], onJoin, HOTKEY_OPTIONS, [onJoin, joinBinding])
+ return null
+}
+
+function FullRuntimeConflictHarness() {
+ usePlaybackShortcuts({})
+ useEditingShortcuts({})
+ useInOutShortcuts()
+ return null
+}
+
+const TRACK: TimelineTrack = {
+ id: 'track-1',
+ name: 'V1',
+ kind: 'video',
+ order: 0,
+ height: 80,
+ locked: false,
+ visible: true,
+ muted: false,
+ solo: false,
+ items: [],
+}
+
+const ITEM: VideoItem = {
+ id: 'clip-1',
+ type: 'video',
+ trackId: TRACK.id,
+ from: 0,
+ durationInFrames: 100,
+ label: 'Clip 1',
+ src: 'clip.mp4',
+}
+
+describe('runtime shortcut ownership', () => {
+ beforeEach(() => {
+ runtimeHotkeysOverride.current = null
+ useSettingsStore.getState().resetHotkeys()
+ usePlaybackStore.setState({
+ currentFrame: 48,
+ previewFrame: 120,
+ previewItemId: null,
+ isPlaying: false,
+ playbackRate: 1,
+ transportMode: 'normal',
+ ...originalPlaybackActions,
+ })
+ useTimelineStore.setState({ inPoint: null, outPoint: null })
+ useSelectionStore.setState({ selectedItemIds: [] })
+ })
+
+ it('executes only JOIN_ITEMS after rejecting the exact derived-chord swap', () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({
+ MARK_IN: 'j',
+ SHUTTLE_REVERSE: 'i',
+ })
+ expect(useSettingsStore.getState().hotkeyOverrides).toEqual({})
+ const onJoin = vi.fn()
+ render()
+
+ fireEvent.keyDown(document, { key: 'J', code: 'KeyJ', shiftKey: true })
+
+ expect(onJoin).toHaveBeenCalledTimes(1)
+ expect(useTimelineStore.getState().inPoint).toBeNull()
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+ })
+
+ it('keeps ordinary remaps distinct across capture and bubble handlers', () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({
+ MARK_IN: 'q',
+ SHUTTLE_REVERSE: 'g',
+ })
+ const onJoin = vi.fn()
+ render()
+
+ fireEvent.keyDown(document, { key: 'Q', code: 'KeyQ', shiftKey: true })
+ expect(useTimelineStore.getState().inPoint).toBe(120)
+ expect(onJoin).not.toHaveBeenCalled()
+
+ fireEvent.keyDown(document, { key: 'g', code: 'KeyG' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ playbackRate: -1,
+ transportMode: 'shuttle',
+ })
+
+ fireEvent.keyDown(document, { key: 'J', code: 'KeyJ', shiftKey: true })
+ expect(onJoin).toHaveBeenCalledTimes(1)
+ })
+
+ it('executes one deterministic handler for a legacy meta versus mod collision', () => {
+ const legacyHotkeys = {
+ ...resolveHotkeys(),
+ MARK_IN: 'meta+j',
+ JOIN_ITEMS: 'mod+shift+j',
+ }
+ runtimeHotkeysOverride.current = legacyHotkeys
+ const onJoin = vi.fn()
+ render()
+
+ fireEvent.keyDown(document, { key: 'J', code: 'KeyJ', metaKey: true, shiftKey: true })
+
+ expect(onJoin).toHaveBeenCalledTimes(1)
+ expect(useTimelineStore.getState().inPoint).toBeNull()
+ })
+
+ it('gives PLAY_PAUSE sole ownership of a legacy meta versus mod transport collision', () => {
+ runtimeHotkeysOverride.current = {
+ ...resolveHotkeys(),
+ PLAY_PAUSE: 'meta+f10',
+ SHUTTLE_REVERSE: 'mod+f10',
+ }
+ const togglePlayPause = vi.fn(originalPlaybackActions.togglePlayPause)
+ const shuttleReverse = vi.fn(originalPlaybackActions.shuttleReverse)
+ usePlaybackStore.setState({ togglePlayPause, shuttleReverse })
+ render()
+
+ fireEvent.keyDown(document, { key: 'F10', code: 'F10', metaKey: true })
+
+ expect(togglePlayPause).toHaveBeenCalledTimes(1)
+ expect(shuttleReverse).not.toHaveBeenCalled()
+ })
+
+ it('executes exactly one action through a dead-claimant platform bridge', () => {
+ runtimeHotkeysOverride.current = {
+ ...resolveHotkeys(),
+ PLAY_PAUSE: 'meta+f10',
+ SHUTTLE_REVERSE: 'mod+f10',
+ SHUTTLE_PAUSE: 'ctrl+f10',
+ }
+ const togglePlayPause = vi.fn(originalPlaybackActions.togglePlayPause)
+ const shuttleReverse = vi.fn(originalPlaybackActions.shuttleReverse)
+ const pause = vi.fn()
+ usePlaybackStore.setState({ togglePlayPause, shuttleReverse, pause })
+ render()
+
+ const event = new KeyboardEvent('keydown', {
+ key: 'F10',
+ code: 'F10',
+ ctrlKey: true,
+ bubbles: true,
+ cancelable: true,
+ })
+ const preventDefault = vi.spyOn(event, 'preventDefault')
+ const stopPropagation = vi.spyOn(event, 'stopPropagation')
+ document.dispatchEvent(event)
+
+ expect(pause).toHaveBeenCalledTimes(1)
+ expect(shuttleReverse).not.toHaveBeenCalled()
+ expect(togglePlayPause).not.toHaveBeenCalled()
+ // react-hotkeys-hook applies preventDefault from HOTKEY_OPTIONS before the
+ // preserved winner callback applies it; the dead claimant adds no calls.
+ expect(preventDefault).toHaveBeenCalledTimes(2)
+ expect(stopPropagation).toHaveBeenCalledTimes(1)
+ })
+
+ it('gives playback sole ownership across playback and split shortcut hooks', () => {
+ runtimeHotkeysOverride.current = {
+ ...resolveHotkeys(),
+ SHUTTLE_FORWARD: 'mod+f9',
+ SPLIT_AT_PLAYHEAD_ALT: 'meta+f9',
+ }
+ usePlaybackStore.setState({ currentFrame: 50 })
+ useTimelineStore.setState({ tracks: [TRACK], items: [ITEM] })
+ const shuttleForward = vi.fn(originalPlaybackActions.shuttleForward)
+ usePlaybackStore.setState({ shuttleForward })
+ render()
+
+ fireEvent.keyDown(document, { key: 'F9', code: 'F9', metaKey: true })
+
+ expect(shuttleForward).toHaveBeenCalledTimes(1)
+ expect(useTimelineStore.getState().items).toEqual([ITEM])
+ })
+
+ it('keeps physically distinct explicit meta and ctrl bindings reachable', () => {
+ runtimeHotkeysOverride.current = {
+ ...resolveHotkeys(),
+ PLAY_PAUSE: 'meta+f8',
+ SHUTTLE_REVERSE: 'ctrl+f8',
+ }
+ const togglePlayPause = vi.fn(originalPlaybackActions.togglePlayPause)
+ const shuttleReverse = vi.fn(originalPlaybackActions.shuttleReverse)
+ usePlaybackStore.setState({ togglePlayPause, shuttleReverse })
+ render()
+
+ fireEvent.keyDown(document, { key: 'F8', code: 'F8', metaKey: true })
+ fireEvent.keyDown(document, { key: 'F8', code: 'F8', ctrlKey: true })
+
+ expect(togglePlayPause).toHaveBeenCalledTimes(1)
+ expect(shuttleReverse).toHaveBeenCalledTimes(1)
+ })
+
+ it('does not let a bubble registration duplicate a capture-owned event', () => {
+ runtimeHotkeysOverride.current = {
+ ...resolveHotkeys(),
+ PLAY_PAUSE: 'meta+f7',
+ CLEAR_IN_OUT: 'mod+f7',
+ }
+ useTimelineStore.setState({ inPoint: 10, outPoint: 20 })
+ const togglePlayPause = vi.fn(originalPlaybackActions.togglePlayPause)
+ usePlaybackStore.setState({ togglePlayPause })
+ render()
+
+ fireEvent.keyDown(document, { key: 'F7', code: 'F7', metaKey: true })
+
+ expect(togglePlayPause).toHaveBeenCalledTimes(1)
+ expect(useTimelineStore.getState()).toMatchObject({ inPoint: 10, outPoint: 20 })
+ })
+
+ it('filters only runtime ownership without rewriting raw bindings or labels', () => {
+ const persistedOverrides = {
+ PLAY_PAUSE: 'meta+f10',
+ SHUTTLE_REVERSE: 'mod+f10',
+ } as const
+ const displayHotkeys = { ...resolveHotkeys(), ...persistedOverrides }
+ runtimeHotkeysOverride.current = displayHotkeys
+ const togglePlayPause = vi.fn(originalPlaybackActions.togglePlayPause)
+ const shuttleReverse = vi.fn(originalPlaybackActions.shuttleReverse)
+ usePlaybackStore.setState({ togglePlayPause, shuttleReverse })
+ render()
+
+ fireEvent.keyDown(document, { key: 'F10', code: 'F10', metaKey: true })
+
+ expect(togglePlayPause).toHaveBeenCalledTimes(1)
+ expect(shuttleReverse).not.toHaveBeenCalled()
+ expect(persistedOverrides).toEqual({
+ PLAY_PAUSE: 'meta+f10',
+ SHUTTLE_REVERSE: 'mod+f10',
+ })
+ expect(displayHotkeys).toMatchObject(persistedOverrides)
+ })
+})
diff --git a/src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.test.tsx b/src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.test.tsx
new file mode 100644
index 000000000..7bac058d4
--- /dev/null
+++ b/src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.test.tsx
@@ -0,0 +1,458 @@
+import { act, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { HOTKEYS } from '@/config/hotkeys'
+import { useClipboardStore } from '@/shared/state/clipboard'
+import { useSelectionStore } from '@/shared/state/selection'
+import type { AudioItem, TextItem, TimelineItem, TimelineTrack, VideoItem } from '@/types/timeline'
+import { useCompositionNavigationStore } from '../../stores/composition-navigation-store'
+import { useKeyframeSelectionStore } from '../../stores/keyframe-selection-store'
+import { useTimelineStore } from '../../stores/timeline-store'
+import { useTimelineCommandStore } from '../../stores/timeline-command-store'
+import { useClipboardShortcuts } from './use-clipboard-shortcuts'
+
+const { addItemsMock, playbackState, useHotkeysMock } = vi.hoisted(() => ({
+ addItemsMock: vi.fn(),
+ playbackState: {
+ currentFrame: 200,
+ setCurrentFrame: vi.fn(),
+ setBusAudioEq: vi.fn(),
+ setMasterBusDb: vi.fn(),
+ },
+ useHotkeysMock: vi.fn(),
+}))
+
+vi.mock('react-hotkeys-hook', () => ({
+ useHotkeys: useHotkeysMock,
+}))
+
+vi.mock('@/shared/state/playback', () => ({
+ usePlaybackStore: {
+ getState: () => playbackState,
+ },
+}))
+
+vi.mock('sonner', () => ({
+ toast: {
+ success: vi.fn(),
+ },
+}))
+
+vi.mock('../../stores/timeline-actions', async (importOriginal) => {
+ const actual = await importOriginal()
+ return {
+ ...actual,
+ addItems: addItemsMock,
+ }
+})
+
+const TARGET_TRACK: TimelineTrack = {
+ id: 'target-track',
+ name: 'V1',
+ kind: 'video',
+ order: 0,
+ height: 80,
+ locked: false,
+ visible: true,
+ muted: false,
+ solo: false,
+ items: [],
+}
+
+const AUDIO_TRACK: TimelineTrack = {
+ ...TARGET_TRACK,
+ id: 'target-audio',
+ name: 'A1',
+ kind: 'audio',
+ order: 1,
+}
+
+const SECOND_VIDEO_TRACK: TimelineTrack = {
+ ...TARGET_TRACK,
+ id: 'target-video-2',
+ name: 'V2',
+ order: 1,
+}
+const SECOND_AUDIO_TRACK: TimelineTrack = {
+ ...AUDIO_TRACK,
+ id: 'target-audio-2',
+ name: 'A2',
+ order: 3,
+}
+
+function makeVideoItem(overrides: Partial = {}): VideoItem {
+ return {
+ id: 'clip-1',
+ type: 'video',
+ trackId: TARGET_TRACK.id,
+ from: 0,
+ durationInFrames: 10,
+ label: 'Clip',
+ src: 'clip.mp4',
+ ...overrides,
+ }
+}
+
+function makeAudioItem(overrides: Partial = {}): AudioItem {
+ return {
+ id: 'audio-1',
+ type: 'audio',
+ trackId: AUDIO_TRACK.id,
+ from: 0,
+ durationInFrames: 10,
+ label: 'Audio',
+ src: 'clip.mp4',
+ ...overrides,
+ }
+}
+
+function makeCaptionItem(overrides: Partial = {}): TextItem {
+ return {
+ id: 'caption-1',
+ type: 'text',
+ trackId: 'missing-caption-track',
+ from: 0,
+ durationInFrames: 10,
+ label: 'Caption',
+ text: 'Caption',
+ color: '#fff',
+ textRole: 'caption',
+ ...overrides,
+ }
+}
+
+function ShortcutHarness() {
+ useClipboardShortcuts()
+ return null
+}
+
+type HotkeyCallback = (event: { preventDefault: () => void }) => void
+
+function getPasteCallback(): HotkeyCallback {
+ const registration = useHotkeysMock.mock.calls.find(([keys]) => keys === HOTKEYS.PASTE)
+ expect(registration).toBeDefined()
+ return registration?.[1] as HotkeyCallback
+}
+
+function getPlannedItems(): TimelineItem[] {
+ expect(addItemsMock).toHaveBeenCalledTimes(1)
+ return addItemsMock.mock.calls[0]?.[0] as TimelineItem[]
+}
+
+describe('useClipboardShortcuts paste placement', () => {
+ beforeEach(() => {
+ addItemsMock.mockClear()
+ useHotkeysMock.mockClear()
+ vi.spyOn(window, 'requestAnimationFrame').mockImplementation(() => 0)
+
+ useTimelineStore.setState({
+ tracks: [TARGET_TRACK],
+ items: [],
+ transitions: [],
+ keyframes: [],
+ markers: [],
+ })
+ useSelectionStore.setState({
+ selectedItemIds: [],
+ selectedItemIdSet: new Set(),
+ selectedTransitionId: null,
+ activeTrackId: TARGET_TRACK.id,
+ })
+ useKeyframeSelectionStore.setState({
+ selectedKeyframes: [],
+ clipboard: null,
+ isCut: false,
+ })
+ useCompositionNavigationStore.setState({ activeCompositionId: null })
+ useClipboardStore.setState({ itemsClipboard: null, transitionClipboard: null })
+ playbackState.currentFrame = 200
+ useTimelineCommandStore.getState().clearHistory()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ it('anchors the earliest copied item at the playhead and preserves relative offsets', () => {
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'early', label: 'Early', from: 40 }),
+ makeVideoItem({ id: 'late', label: 'Late', from: 70 }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ expect(getPlannedItems().map((item) => ({ label: item.label, from: item.from }))).toEqual([
+ { label: 'Early', from: 200 },
+ { label: 'Late', from: 230 },
+ ])
+ })
+
+ it('checks already-planned pasted items when source tracks map to one target track', () => {
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'first', label: 'First', trackId: 'missing-v1', from: 40 }),
+ makeVideoItem({ id: 'second', label: 'Second', trackId: 'missing-v1', from: 45 }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ const plannedItems = getPlannedItems()
+ expect(plannedItems.map((item) => item.trackId)).toEqual([TARGET_TRACK.id, TARGET_TRACK.id])
+ expect(plannedItems.map((item) => item.from)).toEqual([200, 210])
+ expect(plannedItems[0]!.from + plannedItems[0]!.durationInFrames).toBeLessThanOrEqual(
+ plannedItems[1]!.from,
+ )
+ })
+
+ it('moves a linked video/audio pair together when one target track collides', () => {
+ useTimelineStore.setState({
+ tracks: [TARGET_TRACK, AUDIO_TRACK],
+ items: [makeVideoItem({ id: 'occupied', from: 200 })],
+ })
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'video', from: 40, linkedGroupId: 'linked-source' }),
+ makeAudioItem({ id: 'audio', from: 40, linkedGroupId: 'linked-source' }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ const plannedItems = getPlannedItems()
+ expect(plannedItems.map((item) => item.from)).toEqual([210, 210])
+ expect(plannedItems[0]!.linkedGroupId).toBeTruthy()
+ expect(plannedItems[1]!.linkedGroupId).toBe(plannedItems[0]!.linkedGroupId)
+ })
+
+ it('maps linked A/V items with absent source IDs to separate compatible lanes', () => {
+ useTimelineStore.setState({ tracks: [TARGET_TRACK, AUDIO_TRACK] })
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'missing-video', trackId: 'source-v', linkedGroupId: 'pair' }),
+ makeAudioItem({ id: 'missing-audio', trackId: 'source-a', linkedGroupId: 'pair' }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ expect(getPlannedItems().map((item) => item.trackId)).toEqual([TARGET_TRACK.id, AUDIO_TRACK.id])
+ })
+
+ it('preserves lane ordinals for multiple linked pairs and keeps captions on video lanes', () => {
+ useTimelineStore.setState({
+ tracks: [TARGET_TRACK, SECOND_VIDEO_TRACK, AUDIO_TRACK, SECOND_AUDIO_TRACK],
+ })
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'v1', trackId: 'source-v1', linkedGroupId: 'pair-1' }),
+ makeAudioItem({ id: 'a1', trackId: 'source-a1', linkedGroupId: 'pair-1' }),
+ makeVideoItem({ id: 'v2', trackId: 'source-v2', from: 20, linkedGroupId: 'pair-2' }),
+ makeAudioItem({ id: 'a2', trackId: 'source-a2', from: 20, linkedGroupId: 'pair-2' }),
+ makeCaptionItem({ id: 'caption', trackId: 'source-v2', from: 20 }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ const plannedItems = getPlannedItems()
+ expect(plannedItems.map((item) => item.trackId)).toEqual([
+ TARGET_TRACK.id,
+ AUDIO_TRACK.id,
+ SECOND_VIDEO_TRACK.id,
+ SECOND_AUDIO_TRACK.id,
+ SECOND_VIDEO_TRACK.id,
+ ])
+ expect(plannedItems.filter((item) => item.type === 'text')[0]?.trackId).toBe(
+ SECOND_VIDEO_TRACK.id,
+ )
+ })
+
+ it('uses surviving IDs while resolving missing linked members by kind', () => {
+ useTimelineStore.setState({ tracks: [TARGET_TRACK, AUDIO_TRACK] })
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'surviving-video', trackId: TARGET_TRACK.id, linkedGroupId: 'pair' }),
+ makeAudioItem({ id: 'missing-audio', trackId: 'source-a', linkedGroupId: 'pair' }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ expect(getPlannedItems().map((item) => item.trackId)).toEqual([TARGET_TRACK.id, AUDIO_TRACK.id])
+ })
+
+ it('keeps source ordinals separate when malformed A/V lanes reuse an id', () => {
+ useTimelineStore.setState({
+ tracks: [TARGET_TRACK, AUDIO_TRACK, SECOND_AUDIO_TRACK],
+ })
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'shared-video', trackId: 'shared-missing', linkedGroupId: 'pair' }),
+ makeAudioItem({ id: 'shared-audio', trackId: 'shared-missing', linkedGroupId: 'pair' }),
+ makeAudioItem({ id: 'second-audio', trackId: 'second-missing', from: 20 }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ expect(getPlannedItems().map((item) => item.trackId)).toEqual([
+ TARGET_TRACK.id,
+ AUDIO_TRACK.id,
+ SECOND_AUDIO_TRACK.id,
+ ])
+ })
+
+ it('reserves a later surviving lane before assigning an earlier missing source', () => {
+ useTimelineStore.setState({ tracks: [TARGET_TRACK] })
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'missing-first', label: 'Missing', trackId: 'missing-video' }),
+ makeVideoItem({ id: 'surviving-second', label: 'Surviving', trackId: TARGET_TRACK.id }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ const pastedItems = useTimelineStore.getState().items
+ expect(pastedItems.find((item) => item.label === 'Surviving')?.trackId).toBe(TARGET_TRACK.id)
+ expect(new Set(pastedItems.map((item) => item.trackId)).size).toBe(2)
+ expect(useTimelineStore.getState().tracks).toHaveLength(2)
+ })
+
+ it('splits malformed overlapping members of one linked group safely', () => {
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'overlap-1', trackId: 'same-source', linkedGroupId: 'bad-group' }),
+ makeVideoItem({ id: 'overlap-2', trackId: 'same-source', linkedGroupId: 'bad-group' }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ const plannedItems = getPlannedItems()
+ expect(plannedItems.map((item) => item.from)).toEqual([200, 210])
+ expect(plannedItems[0]!.from + plannedItems[0]!.durationInFrames).toBeLessThanOrEqual(
+ plannedItems[1]!.from,
+ )
+ })
+
+ it('creates deterministic compatible lanes and undoes tracks and items together', () => {
+ useClipboardStore
+ .getState()
+ .copyItems(
+ [
+ makeVideoItem({ id: 'lane-1', trackId: 'missing-v1', from: 0 }),
+ makeVideoItem({ id: 'lane-2', trackId: 'missing-v2', from: 0 }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ expect(useTimelineStore.getState().tracks.map((track) => track.kind)).toEqual([
+ 'video',
+ 'video',
+ ])
+ expect(useTimelineStore.getState().items).toHaveLength(2)
+ expect(useTimelineCommandStore.getState().undoStack).toHaveLength(1)
+
+ act(() => useTimelineCommandStore.getState().undo())
+ expect(useTimelineStore.getState().tracks).toHaveLength(1)
+ expect(useTimelineStore.getState().tracks[0]?.id).toBe(TARGET_TRACK.id)
+ expect(useTimelineStore.getState().items).toEqual([])
+ })
+
+ it('creates and atomically undoes a missing linked audio lane after a video collision', () => {
+ useTimelineStore.setState({
+ tracks: [TARGET_TRACK],
+ items: [makeVideoItem({ id: 'occupied-video', from: 200 })],
+ })
+ useClipboardStore.getState().copyItems(
+ [
+ makeVideoItem({
+ id: 'linked-video',
+ trackId: 'missing-video',
+ linkedGroupId: 'source-pair',
+ }),
+ makeAudioItem({
+ id: 'linked-audio',
+ trackId: 'missing-audio',
+ linkedGroupId: 'source-pair',
+ }),
+ ],
+ 0,
+ 'copy',
+ )
+
+ render()
+ act(() => getPasteCallback()({ preventDefault: vi.fn() }))
+
+ const pasted = useTimelineStore.getState().items.filter((item) => item.id !== 'occupied-video')
+ expect(pasted).toHaveLength(2)
+ expect(pasted.map((item) => item.from)).toEqual([210, 210])
+ expect(pasted[0]!.linkedGroupId).toBeTruthy()
+ expect(pasted[1]!.linkedGroupId).toBe(pasted[0]!.linkedGroupId)
+ expect(useTimelineStore.getState().tracks.map((track) => track.kind)).toEqual([
+ 'video',
+ 'audio',
+ ])
+ expect(useTimelineCommandStore.getState().undoStack).toHaveLength(1)
+
+ act(() => useTimelineCommandStore.getState().undo())
+ expect(useTimelineStore.getState().tracks).toHaveLength(1)
+ expect(useTimelineStore.getState().tracks[0]).toMatchObject({
+ id: TARGET_TRACK.id,
+ kind: 'video',
+ })
+ expect(useTimelineStore.getState().items.map((item) => item.id)).toEqual(['occupied-video'])
+ })
+})
diff --git a/src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.ts
index d0f05df13..a6af20cf6 100644
--- a/src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.ts
@@ -2,7 +2,7 @@
* Clipboard shortcuts: Ctrl+C (copy), Ctrl+X (cut), Ctrl+V (paste).
*/
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { toast } from 'sonner'
import { usePlaybackStore } from '@/shared/state/playback'
import { useTimelineStore } from '../../stores/timeline-store'
@@ -14,13 +14,254 @@ import { useCompositionsStore } from '../../stores/compositions-store'
import { useKeyframeSelectionStore } from '../../stores/keyframe-selection-store'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
import type { Transition } from '@/types/transition'
-import type { TimelineItem } from '@/types/timeline'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
+import type { TimelineItem, TimelineTrack } from '@/types/timeline'
import {
isCompositionWrapperItem,
wouldCreateCompositionCycle,
} from '../../utils/composition-graph'
import { handleTranscriptClipboardCopy } from '../../utils/transcript-copy-bridge'
+import { createClassicTrack, getTrackKind } from '../../utils/classic-tracks'
+
+interface PastePlacementPlan {
+ itemData: Omit
+ targetTrackId: string
+ desiredFrom: number
+ sourceIndex: number
+}
+
+function placementsOverlap(
+ left: { trackId: string; from: number; durationInFrames: number },
+ right: { trackId: string; from: number; durationInFrames: number },
+): boolean {
+ return (
+ left.trackId === right.trackId &&
+ left.from < right.from + right.durationInFrames &&
+ left.from + left.durationInFrames > right.from
+ )
+}
+
+function hasInternalPlacementOverlap(plans: PastePlacementPlan[]): boolean {
+ return plans.some((plan, index) =>
+ plans.slice(index + 1).some((candidate) =>
+ placementsOverlap(
+ {
+ trackId: plan.targetTrackId,
+ from: plan.desiredFrom,
+ durationInFrames: plan.itemData.durationInFrames,
+ },
+ {
+ trackId: candidate.targetTrackId,
+ from: candidate.desiredFrom,
+ durationInFrames: candidate.itemData.durationInFrames,
+ },
+ ),
+ ),
+ )
+}
+
+type PasteTrackKind = 'video' | 'audio'
+
+interface PasteSourceLane {
+ key: string
+ kind: PasteTrackKind
+ sourceTrackId: string
+ ordinal: number
+}
+
+function getPasteTrackKind(item: Omit): PasteTrackKind {
+ return item.type === 'audio' ? 'audio' : 'video'
+}
+
+function isCompatiblePasteTrack(track: TimelineTrack, kind: PasteTrackKind): boolean {
+ const trackKind = getTrackKind(track)
+ return kind === 'audio' ? trackKind === 'audio' : trackKind !== 'audio'
+}
+
+function getPasteDestinationTrackIds(tracks: TimelineTrack[], kind: PasteTrackKind): string[] {
+ return tracks
+ .filter((track) => !track.isGroup && isCompatiblePasteTrack(track, kind))
+ .sort((left, right) => left.order - right.order)
+ .map((track) => track.id)
+}
+
+function collectPasteSourceLanes(pasteItems: Array>) {
+ const lanesByKind: Record = { video: [], audio: [] }
+ const laneByKey = new Map()
+ const laneKeyByItemIndex = new Map()
+
+ for (const [sourceIndex, itemData] of pasteItems.entries()) {
+ const kind = getPasteTrackKind(itemData)
+ const key = `${kind}:${itemData.trackId}`
+ let lane = laneByKey.get(key)
+ if (!lane) {
+ lane = {
+ key,
+ kind,
+ sourceTrackId: itemData.trackId,
+ ordinal: lanesByKind[kind].length,
+ }
+ laneByKey.set(key, lane)
+ lanesByKind[kind].push(lane)
+ }
+ laneKeyByItemIndex.set(sourceIndex, key)
+ }
+
+ return { lanesByKind, laneKeyByItemIndex }
+}
+
+function findExactPasteTrack(
+ lane: PasteSourceLane,
+ tracks: TimelineTrack[],
+): TimelineTrack | undefined {
+ return tracks.find(
+ (track) => track.id === lane.sourceTrackId && isCompatiblePasteTrack(track, lane.kind),
+ )
+}
+
+function appendPasteDestinationTrack(
+ tracks: TimelineTrack[],
+ kind: PasteTrackKind,
+): { trackId: string; tracks: TimelineTrack[] } {
+ const minOrder = Math.min(...tracks.map((track) => track.order), 0)
+ const maxOrder = Math.max(...tracks.map((track) => track.order), 0)
+ const newTrack = createClassicTrack({
+ tracks,
+ kind,
+ order: kind === 'video' ? minOrder - 1 : maxOrder + 1,
+ })
+ return { trackId: newTrack.id, tracks: [...tracks, newTrack] }
+}
+
+function planSingleSourceSection(params: {
+ activeTrackId: string | null
+ kind: PasteTrackKind
+ lanes: PasteSourceLane[]
+ tracks: TimelineTrack[]
+}): { assignments: Map; tracks: TimelineTrack[] } {
+ const { activeTrackId, kind, lanes } = params
+ let plannedTracks = params.tracks
+ const assignments = new Map()
+ const candidates = getPasteDestinationTrackIds(plannedTracks, kind)
+ const activeTrack = plannedTracks.find(
+ (track) => track.id === activeTrackId && isCompatiblePasteTrack(track, kind),
+ )
+
+ for (const lane of lanes) {
+ let targetTrackId =
+ activeTrack?.id ?? findExactPasteTrack(lane, plannedTracks)?.id ?? candidates[0]
+ if (!targetTrackId) {
+ const created = appendPasteDestinationTrack(plannedTracks, kind)
+ plannedTracks = created.tracks
+ targetTrackId = created.trackId
+ candidates.push(created.trackId)
+ }
+ assignments.set(lane.key, targetTrackId)
+ }
+
+ return { assignments, tracks: plannedTracks }
+}
+
+function planPreservedSourceSection(params: {
+ kind: PasteTrackKind
+ lanes: PasteSourceLane[]
+ tracks: TimelineTrack[]
+}): { assignments: Map; tracks: TimelineTrack[] } {
+ const { kind, lanes } = params
+ let plannedTracks = params.tracks
+ const assignments = new Map()
+ const candidates = getPasteDestinationTrackIds(plannedTracks, kind)
+ const usedTrackIds = new Set()
+
+ for (const lane of lanes) {
+ const exactTrack = findExactPasteTrack(lane, plannedTracks)
+ if (!exactTrack) continue
+ assignments.set(lane.key, exactTrack.id)
+ usedTrackIds.add(exactTrack.id)
+ }
+
+ for (const lane of lanes) {
+ if (assignments.has(lane.key)) continue
+ const ordinalCandidate = candidates[lane.ordinal]
+ const availableCandidate =
+ ordinalCandidate && !usedTrackIds.has(ordinalCandidate)
+ ? ordinalCandidate
+ : candidates.find((candidate) => !usedTrackIds.has(candidate))
+ let targetTrackId = availableCandidate
+ if (!targetTrackId) {
+ const created = appendPasteDestinationTrack(plannedTracks, kind)
+ plannedTracks = created.tracks
+ targetTrackId = created.trackId
+ candidates.push(created.trackId)
+ }
+ assignments.set(lane.key, targetTrackId)
+ usedTrackIds.add(targetTrackId)
+ }
+
+ return { assignments, tracks: plannedTracks }
+}
+
+function buildPasteTrackPlan(
+ pasteItems: Array>,
+ tracks: TimelineTrack[],
+ activeTrackId: string | null,
+): { plan: Map; tracks: TimelineTrack[] } {
+ let plannedTracks = tracks
+ const { lanesByKind, laneKeyByItemIndex } = collectPasteSourceLanes(pasteItems)
+ const preserveSourceTracks = new Set(pasteItems.map((item) => item.trackId)).size > 1
+ const plan = new Map()
+ const assignedTrackBySourceLane = new Map()
+
+ for (const kind of ['video', 'audio'] as const) {
+ const sectionPlan = preserveSourceTracks
+ ? planPreservedSourceSection({ kind, lanes: lanesByKind[kind], tracks: plannedTracks })
+ : planSingleSourceSection({
+ activeTrackId,
+ kind,
+ lanes: lanesByKind[kind],
+ tracks: plannedTracks,
+ })
+ plannedTracks = sectionPlan.tracks
+ for (const [laneKey, trackId] of sectionPlan.assignments) {
+ assignedTrackBySourceLane.set(laneKey, trackId)
+ }
+ }
+
+ for (const [sourceIndex, laneKey] of laneKeyByItemIndex) {
+ const targetTrackId = assignedTrackBySourceLane.get(laneKey)
+ if (targetTrackId) plan.set(sourceIndex, targetTrackId)
+ }
+
+ return { plan, tracks: plannedTracks }
+}
+
+function findSharedPlacementShift(
+ plans: PastePlacementPlan[],
+ occupiedItems: TimelineItem[],
+): number {
+ let shift = 0
+ while (true) {
+ let requiredShift = 0
+ for (const plan of plans) {
+ const from = plan.desiredFrom + shift
+ for (const occupied of occupiedItems) {
+ if (
+ placementsOverlap(
+ {
+ trackId: plan.targetTrackId,
+ from,
+ durationInFrames: plan.itemData.durationInFrames,
+ },
+ occupied,
+ )
+ ) {
+ requiredShift = Math.max(requiredShift, occupied.from + occupied.durationInFrames - from)
+ }
+ }
+ }
+ if (requiredShift <= 0) return shift
+ shift += requiredShift
+ }
+}
function revealPastedItems(itemIds: readonly string[]): void {
if (itemIds.length === 0) {
@@ -64,7 +305,6 @@ function revealPastedItems(itemIds: readonly string[]): void {
}
export function useClipboardShortcuts() {
- const hotkeys = useResolvedHotkeys()
const selectedItemIds = useSelectionStore((s) => s.selectedItemIds)
const selectedTransitionId = useSelectionStore((s) => s.selectedTransitionId)
const selectedKeyframes = useKeyframeSelectionStore((s) => s.selectedKeyframes)
@@ -75,6 +315,7 @@ export function useClipboardShortcuts() {
const transitions = useTimelineStore((s) => s.transitions)
const tracks = useTimelineStore((s) => s.tracks)
const addItems = useTimelineStore((s) => s.addItems)
+ const addItemsOnNewTracks = useTimelineStore((s) => s.addItemsOnNewTracks)
const removeItems = useTimelineStore((s) => s.removeItems)
const updateTransition = useTimelineStore((s) => s.updateTransition)
const copyTransition = useClipboardStore((s) => s.copyTransition)
@@ -87,8 +328,8 @@ export function useClipboardShortcuts() {
}
// Clipboard: Ctrl+C - Copy selected transition properties or timeline items
- useHotkeys(
- hotkeys.COPY,
+ useCommandHotkey(
+ 'COPY',
(event) => {
// Transcript editor copies the selected words instead of the clip.
if (handleTranscriptClipboardCopy(false)) {
@@ -134,8 +375,8 @@ export function useClipboardShortcuts() {
)
// Clipboard: Ctrl+X - Cut selected items immediately
- useHotkeys(
- hotkeys.CUT,
+ useCommandHotkey(
+ 'CUT',
(event) => {
// Transcript editor cuts the selected words instead of the clip.
if (handleTranscriptClipboardCopy(true)) {
@@ -161,8 +402,8 @@ export function useClipboardShortcuts() {
)
// Clipboard: Ctrl+V - Paste transition properties or timeline items
- useHotkeys(
- hotkeys.PASTE,
+ useCommandHotkey(
+ 'PASTE',
(event) => {
if (selectedTransitionId && transitionClipboard) {
event.preventDefault()
@@ -200,89 +441,84 @@ export function useClipboardShortcuts() {
)
if (pasteItems.length === 0) return
- // When the clipboard spans more than one source track (e.g. a linked
- // video+audio pair copied from the transcript), preserve each item's own
- // track so the pair lands on video/audio tracks separately. A
- // single-track copy still pastes onto the active track as before.
- const preserveSourceTracks = new Set(pasteItems.map((item) => item.trackId)).size > 1
-
- const findNextAvailableSpace = (
- trackId: string,
- startFrame: number,
- duration: number,
- ): number => {
- const trackItems = storeItems
- .filter((item) => item.trackId === trackId)
- .sort((a, b) => a.from - b.from)
-
- let candidateFrame = startFrame
-
- for (const item of trackItems) {
- const itemEnd = item.from + item.durationInFrames
- if (candidateFrame < itemEnd && candidateFrame + duration > item.from) {
- candidateFrame = itemEnd
- }
- }
-
- return candidateFrame
- }
+ // Resolve every source lane by media section/kind. Exact IDs win when
+ // they survive in this sequence; otherwise the source lane ordinal is
+ // mapped to the corresponding destination lane. This keeps linked A/V
+ // members in separate sections even when both source IDs are absent.
+ const { plan: trackPlan, tracks: plannedTracks } = buildPasteTrackPlan(
+ pasteItems,
+ tracks,
+ activeTrackId,
+ )
+ const placementPlans = pasteItems.flatMap((itemData, sourceIndex) => {
+ const targetTrackId = trackPlan.get(sourceIndex)
+ return targetTrackId
+ ? [
+ {
+ itemData,
+ targetTrackId,
+ desiredFrom: currentFrame + itemData.from,
+ sourceIndex,
+ },
+ ]
+ : []
+ })
- const hasSpaceAt = (trackId: string, startFrame: number, duration: number): boolean => {
- const trackItems = storeItems.filter((item) => item.trackId === trackId)
- for (const item of trackItems) {
- const itemEnd = item.from + item.durationInFrames
- if (startFrame < itemEnd && startFrame + duration > item.from) {
- return false
- }
+ // Keep an ordinary multi-item paste as one rigid block. If invalid or
+ // missing source tracks collapse overlapping items onto one target,
+ // fall back to linked groups/singletons so placement can still make
+ // progress without separating a valid linked A/V pair.
+ let placementGroups: PastePlacementPlan[][] = [placementPlans]
+ if (hasInternalPlacementOverlap(placementPlans)) {
+ const grouped = new Map()
+ for (const plan of placementPlans) {
+ const key = plan.itemData.linkedGroupId
+ ? `linked:${plan.itemData.linkedGroupId}`
+ : `item:${plan.sourceIndex}`
+ const group = grouped.get(key) ?? []
+ group.push(plan)
+ grouped.set(key, group)
}
- return true
+ placementGroups = [...grouped.values()].flatMap((group) =>
+ hasInternalPlacementOverlap(group) ? group.map((plan) => [plan]) : [group],
+ )
}
- for (const itemData of pasteItems) {
- const newId = crypto.randomUUID()
- newItemIds.push(newId)
+ const occupiedItems = [...storeItems]
+ for (const group of placementGroups) {
+ const sharedShift = findSharedPlacementShift(group, occupiedItems)
+ for (const plan of group) {
+ const { itemData, targetTrackId, desiredFrom } = plan
+ const newId = crypto.randomUUID()
+ newItemIds.push(newId)
+ const newItem = {
+ ...itemData,
+ id: newId,
+ from: desiredFrom + sharedShift,
+ trackId: targetTrackId,
+ originId: newId,
+ linkedGroupId: itemData.linkedGroupId
+ ? (linkedGroupMap.get(itemData.linkedGroupId) ??
+ linkedGroupMap
+ .set(itemData.linkedGroupId, crypto.randomUUID())
+ .get(itemData.linkedGroupId))
+ : undefined,
+ } as TimelineItem
- let targetTrackId = preserveSourceTracks ? itemData.trackId : activeTrackId
- if (!targetTrackId || !tracks.some((t) => t.id === targetTrackId)) {
- targetTrackId = itemData.trackId
- }
- const trackExists = tracks.some((t) => t.id === targetTrackId)
- if (!trackExists && tracks.length > 0) {
- targetTrackId = tracks[0]!.id
+ newItems.push(newItem)
+ occupiedItems.push(newItem)
+ usedTrackIds.add(targetTrackId)
}
-
- const desiredFrom = currentFrame
- const duration = itemData.durationInFrames
-
- let newFrom: number
- if (hasSpaceAt(targetTrackId, desiredFrom, duration)) {
- newFrom = desiredFrom
- } else {
- newFrom = findNextAvailableSpace(targetTrackId, desiredFrom, duration)
- }
-
- const newItem = {
- ...itemData,
- id: newId,
- from: newFrom,
- trackId: targetTrackId,
- originId: newId,
- linkedGroupId: itemData.linkedGroupId
- ? (linkedGroupMap.get(itemData.linkedGroupId) ??
- linkedGroupMap
- .set(itemData.linkedGroupId, crypto.randomUUID())
- .get(itemData.linkedGroupId))
- : undefined,
- }
-
- newItems.push(newItem as TimelineItem)
- usedTrackIds.add(targetTrackId)
}
// Add every pasted item in a single ADD_ITEMS command so one Ctrl+Z
// undoes the whole paste (including a linked A/V pair), not item-by-item.
if (newItems.length > 0) {
- addItems(newItems)
+ if (plannedTracks.length > tracks.length) {
+ addItemsOnNewTracks(newItems, plannedTracks)
+ } else {
+ addItems(newItems)
+ }
}
if (newItemIds.length > 0) {
@@ -321,6 +557,7 @@ export function useClipboardShortcuts() {
itemsClipboard,
tracks,
addItems,
+ addItemsOnNewTracks,
selectItems,
activeTrackId,
selectedKeyframes.length,
diff --git a/src/features/timeline/hooks/shortcuts/use-delete-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-delete-shortcuts.ts
index fa4d0ddfa..9ef20b096 100644
--- a/src/features/timeline/hooks/shortcuts/use-delete-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-delete-shortcuts.ts
@@ -8,17 +8,15 @@
*/
import { useCallback } from 'react'
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { useEditorStore } from '@/shared/state/editor'
import { useTimelineStore } from '../../stores/timeline-store'
import { useSelectionStore } from '@/shared/state/selection'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
import type { TimelineShortcutCallbacks } from '../use-timeline-shortcuts'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
import { useKeyframeSelectionStore } from '../../stores/keyframe-selection-store'
export function useDeleteShortcuts(callbacks: TimelineShortcutCallbacks) {
- const hotkeys = useResolvedHotkeys()
const selectedItemIds = useSelectionStore((s) => s.selectedItemIds)
const selectedMarkerId = useSelectionStore((s) => s.selectedMarkerId)
const selectedTransitionId = useSelectionStore((s) => s.selectedTransitionId)
@@ -82,8 +80,8 @@ export function useDeleteShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Editing: Delete - Delete selected items, marker, or transition
- useHotkeys(hotkeys.DELETE_SELECTED, deleteSelection, HOTKEY_OPTIONS, [deleteSelection])
+ useCommandHotkey('DELETE_SELECTED', deleteSelection, HOTKEY_OPTIONS, [deleteSelection])
// Editing: Backspace - Delete selected items, marker, or transition (alternative)
- useHotkeys(hotkeys.DELETE_SELECTED_ALT, deleteSelection, HOTKEY_OPTIONS, [deleteSelection])
+ useCommandHotkey('DELETE_SELECTED_ALT', deleteSelection, HOTKEY_OPTIONS, [deleteSelection])
}
diff --git a/src/features/timeline/hooks/shortcuts/use-editing-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-editing-shortcuts.ts
index 276c038c8..f541c0efa 100644
--- a/src/features/timeline/hooks/shortcuts/use-editing-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-editing-shortcuts.ts
@@ -3,7 +3,7 @@
*/
import { useCallback } from 'react'
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { usePlaybackStore } from '@/shared/state/playback'
import { useEditorStore } from '@/shared/state/editor'
import { useTimelineStore } from '../../stores/timeline-store'
@@ -20,12 +20,10 @@ import {
import type { TransformProperties } from '@/types/transform'
import type { TimelineShortcutCallbacks } from '../use-timeline-shortcuts'
import { useClearKeyframesDialogStore } from '@/shared/state/clear-keyframes-dialog'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
import { useKeyframeSelectionStore } from '../../stores/keyframe-selection-store'
import { useDeleteShortcuts } from './use-delete-shortcuts'
export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
- const hotkeys = useResolvedHotkeys()
const selectedItemIds = useSelectionStore((s) => s.selectedItemIds)
const editKeyframePanelOpen = useSelectionStore((s) => s.editKeyframePanelOpen)
const clearSelection = useSelectionStore((s) => s.clearSelection)
@@ -79,8 +77,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Editing: Ctrl+Delete - Ripple delete selected items (delete + close gap)
- useHotkeys(
- hotkeys.RIPPLE_DELETE,
+ useCommandHotkey(
+ 'RIPPLE_DELETE',
(event) => {
if (deleteOwnedByPanel) {
event.preventDefault()
@@ -101,8 +99,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Editing: Ctrl+Backspace - Ripple delete selected items (alternative)
- useHotkeys(
- hotkeys.RIPPLE_DELETE_ALT,
+ useCommandHotkey(
+ 'RIPPLE_DELETE_ALT',
(event) => {
if (deleteOwnedByPanel) {
event.preventDefault()
@@ -123,8 +121,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Editing: Shift+Arrow keys - nudge selected visual items by 1px
- useHotkeys(
- hotkeys.NUDGE_LEFT,
+ useCommandHotkey(
+ 'NUDGE_LEFT',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(-1, 0)
@@ -133,8 +131,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[nudgeSelectedVisualItems],
)
- useHotkeys(
- hotkeys.NUDGE_RIGHT,
+ useCommandHotkey(
+ 'NUDGE_RIGHT',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(1, 0)
@@ -143,8 +141,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[nudgeSelectedVisualItems],
)
- useHotkeys(
- hotkeys.NUDGE_UP,
+ useCommandHotkey(
+ 'NUDGE_UP',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(0, -1)
@@ -153,8 +151,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[nudgeSelectedVisualItems],
)
- useHotkeys(
- hotkeys.NUDGE_DOWN,
+ useCommandHotkey(
+ 'NUDGE_DOWN',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(0, 1)
@@ -164,8 +162,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Editing: Cmd/Ctrl+Shift+Arrow keys - nudge selected visual items by 10px
- useHotkeys(
- hotkeys.NUDGE_LEFT_LARGE,
+ useCommandHotkey(
+ 'NUDGE_LEFT_LARGE',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(-10, 0)
@@ -174,8 +172,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[nudgeSelectedVisualItems],
)
- useHotkeys(
- hotkeys.NUDGE_RIGHT_LARGE,
+ useCommandHotkey(
+ 'NUDGE_RIGHT_LARGE',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(10, 0)
@@ -184,8 +182,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[nudgeSelectedVisualItems],
)
- useHotkeys(
- hotkeys.NUDGE_UP_LARGE,
+ useCommandHotkey(
+ 'NUDGE_UP_LARGE',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(0, -10)
@@ -194,8 +192,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[nudgeSelectedVisualItems],
)
- useHotkeys(
- hotkeys.NUDGE_DOWN_LARGE,
+ useCommandHotkey(
+ 'NUDGE_DOWN_LARGE',
(event) => {
event.preventDefault()
nudgeSelectedVisualItems(0, 10)
@@ -205,8 +203,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Editing: Shift+J - Join selected clips
- useHotkeys(
- hotkeys.JOIN_ITEMS,
+ useCommandHotkey(
+ 'JOIN_ITEMS',
(event) => {
if (selectedItemIds.length < 2) return
@@ -225,8 +223,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[selectedItemIds, items, joinItems],
)
- useHotkeys(
- hotkeys.LINK_AUDIO_VIDEO,
+ useCommandHotkey(
+ 'LINK_AUDIO_VIDEO',
(event) => {
if (selectedItemIds.length < 2) return
if (!canLinkSelection(items, selectedItemIds)) return
@@ -238,8 +236,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[selectedItemIds, items],
)
- useHotkeys(
- hotkeys.UNLINK_AUDIO_VIDEO,
+ useCommandHotkey(
+ 'UNLINK_AUDIO_VIDEO',
(event) => {
if (selectedItemIds.length === 0) return
if (!selectedItemIds.some((id) => hasLinkedItems(items, id))) return
@@ -251,8 +249,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
[selectedItemIds, items],
)
- useHotkeys(
- hotkeys.TOGGLE_LINKED_SELECTION,
+ useCommandHotkey(
+ 'TOGGLE_LINKED_SELECTION',
(event) => {
event.preventDefault()
toggleLinkedSelectionEnabled()
@@ -269,16 +267,16 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
}, [])
// Editing: Alt+C - Split all items at gray playhead (or main playhead)
- useHotkeys(
- hotkeys.SPLIT_AT_PLAYHEAD_ALT,
+ useCommandHotkey(
+ 'SPLIT_AT_PLAYHEAD_ALT',
splitAtPlayhead,
{ ...HOTKEY_OPTIONS, eventListenerOptions: { capture: true } },
[splitAtPlayhead],
)
// Editing: Shift+F - Insert freeze frame at playhead
- useHotkeys(
- hotkeys.FREEZE_FRAME,
+ useCommandHotkey(
+ 'FREEZE_FRAME',
(event) => {
if (selectedItemIds.length !== 1) return
const currentFrame = usePlaybackStore.getState().currentFrame
@@ -300,8 +298,8 @@ export function useEditingShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Keyframes: Shift+A - Clear all keyframes for selected items (with confirmation)
- useHotkeys(
- hotkeys.CLEAR_KEYFRAMES,
+ useCommandHotkey(
+ 'CLEAR_KEYFRAMES',
(event) => {
if (selectedItemIds.length === 0) return
diff --git a/src/features/timeline/hooks/shortcuts/use-in-out-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-in-out-shortcuts.ts
index 7c1c75e0e..eaba4bb38 100644
--- a/src/features/timeline/hooks/shortcuts/use-in-out-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-in-out-shortcuts.ts
@@ -2,34 +2,14 @@
* Timeline in/out shortcuts: I, O, Shift+I/O, Alt+X.
*/
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey, useDerivedCommandHotkey } from '@/hooks/use-hotkey-registration'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
import { usePlaybackStore } from '@/shared/state/playback'
import { useTimelineStore } from '../../stores/timeline-store'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
-
-function addShiftModifier(binding: string): string {
- const parts = binding
- .split('+')
- .map((part) => part.trim())
- .filter(Boolean)
-
- if (parts.some((part) => part.toLowerCase() === 'shift')) {
- return binding
- }
-
- const key = parts.pop()
- if (!key) return `shift+${binding}`
- return [...parts, 'shift', key].join('+')
-}
export function useInOutShortcuts() {
- const hotkeys = useResolvedHotkeys()
- const markInAtPreview = addShiftModifier(hotkeys.MARK_IN)
- const markOutAtPreview = addShiftModifier(hotkeys.MARK_OUT)
-
- useHotkeys(
- hotkeys.MARK_IN,
+ useCommandHotkey(
+ 'MARK_IN',
(event) => {
event.preventDefault()
const { currentFrame } = usePlaybackStore.getState()
@@ -39,19 +19,20 @@ export function useInOutShortcuts() {
[],
)
- useHotkeys(
- markInAtPreview,
+ useDerivedCommandHotkey(
+ 'MARK_IN',
+ 'preview',
(event) => {
event.preventDefault()
const { previewFrame, currentFrame } = usePlaybackStore.getState()
useTimelineStore.getState().setInPoint(previewFrame ?? currentFrame)
},
HOTKEY_OPTIONS,
- [markInAtPreview],
+ [],
)
- useHotkeys(
- hotkeys.MARK_OUT,
+ useCommandHotkey(
+ 'MARK_OUT',
(event) => {
event.preventDefault()
const { currentFrame } = usePlaybackStore.getState()
@@ -61,19 +42,20 @@ export function useInOutShortcuts() {
[],
)
- useHotkeys(
- markOutAtPreview,
+ useDerivedCommandHotkey(
+ 'MARK_OUT',
+ 'preview',
(event) => {
event.preventDefault()
const { previewFrame, currentFrame } = usePlaybackStore.getState()
useTimelineStore.getState().setOutPoint(previewFrame ?? currentFrame)
},
HOTKEY_OPTIONS,
- [markOutAtPreview],
+ [],
)
- useHotkeys(
- hotkeys.CLEAR_IN_OUT,
+ useCommandHotkey(
+ 'CLEAR_IN_OUT',
(event) => {
event.preventDefault()
useTimelineStore.getState().clearInOutPoints()
diff --git a/src/features/timeline/hooks/shortcuts/use-marker-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-marker-shortcuts.ts
index cd6881792..e5073feb0 100644
--- a/src/features/timeline/hooks/shortcuts/use-marker-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-marker-shortcuts.ts
@@ -2,22 +2,20 @@
* Marker shortcuts: M (add), Shift+M (remove), [ ] (navigate).
*/
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { usePlaybackStore } from '@/shared/state/playback'
import { useMarkersStore } from '../../stores/markers-store'
import { useSelectionStore } from '@/shared/state/selection'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
import { addMarker, removeMarker } from '../../stores/actions/marker-actions'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
export function useMarkerShortcuts() {
- const hotkeys = useResolvedHotkeys()
const setCurrentFrame = usePlaybackStore((s) => s.setCurrentFrame)
const clearSelection = useSelectionStore((s) => s.clearSelection)
// Markers: M - Add marker at playhead
- useHotkeys(
- hotkeys.ADD_MARKER,
+ useCommandHotkey(
+ 'ADD_MARKER',
(event) => {
event.preventDefault()
const { previewFrame, currentFrame } = usePlaybackStore.getState()
@@ -28,8 +26,8 @@ export function useMarkerShortcuts() {
)
// Markers: Shift+M - Remove selected marker
- useHotkeys(
- hotkeys.REMOVE_MARKER,
+ useCommandHotkey(
+ 'REMOVE_MARKER',
(event) => {
event.preventDefault()
const id = useSelectionStore.getState().selectedMarkerId
@@ -43,8 +41,8 @@ export function useMarkerShortcuts() {
)
// Markers: [ - Jump to previous marker
- useHotkeys(
- hotkeys.PREVIOUS_MARKER,
+ useCommandHotkey(
+ 'PREVIOUS_MARKER',
(event) => {
event.preventDefault()
const currentMarkers = useMarkersStore.getState().markers
@@ -67,8 +65,8 @@ export function useMarkerShortcuts() {
)
// Markers: ] - Jump to next marker
- useHotkeys(
- hotkeys.NEXT_MARKER,
+ useCommandHotkey(
+ 'NEXT_MARKER',
(event) => {
event.preventDefault()
const currentMarkers = useMarkersStore.getState().markers
diff --git a/src/features/timeline/hooks/shortcuts/use-playback-shortcuts.test.tsx b/src/features/timeline/hooks/shortcuts/use-playback-shortcuts.test.tsx
new file mode 100644
index 000000000..17109afbc
--- /dev/null
+++ b/src/features/timeline/hooks/shortcuts/use-playback-shortcuts.test.tsx
@@ -0,0 +1,210 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { useSettingsStore } from '@/features/timeline/deps/settings'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useSourcePlayerStore } from '@/shared/state/source-player'
+import type { SourcePlayerMethods } from '@/shared/state/source-player/types'
+import type { VideoItem } from '@/types/timeline'
+import { useItemsStore } from '../../stores/items-store'
+import { usePlaybackShortcuts } from './use-playback-shortcuts'
+
+function PlaybackShortcutHarness() {
+ usePlaybackShortcuts({})
+ return
+}
+
+function PlaybackShortcutTargetHarness({ children }: { children: React.ReactNode }) {
+ usePlaybackShortcuts({})
+ return children
+}
+
+function sourcePlayerMethods(durationInFrames = 300): SourcePlayerMethods {
+ return {
+ toggle: vi.fn(),
+ pause: vi.fn(),
+ isPlaying: vi.fn(() => true),
+ shuttleForward: vi.fn(),
+ shuttleReverse: vi.fn(),
+ seek: vi.fn(),
+ frameBack: vi.fn(),
+ frameForward: vi.fn(),
+ getDurationInFrames: vi.fn(() => durationInFrames),
+ }
+}
+
+function videoItem(overrides: Partial = {}): VideoItem {
+ return {
+ id: 'clip-1',
+ type: 'video',
+ trackId: 'track-1',
+ from: 10,
+ durationInFrames: 5,
+ label: 'Clip',
+ src: 'clip.mp4',
+ ...overrides,
+ }
+}
+
+describe('usePlaybackShortcuts transport routing', () => {
+ beforeEach(() => {
+ useSettingsStore.getState().resetHotkeys()
+ usePlaybackStore.setState({
+ isPlaying: false,
+ playbackRate: 1,
+ transportMode: 'normal',
+ currentFrame: 0,
+ previewFrame: null,
+ previewItemId: null,
+ })
+ useSourcePlayerStore.setState({
+ hoveredPanel: null,
+ playerMethods: null,
+ })
+ useItemsStore
+ .getState()
+ .setItems([videoItem(), videoItem({ id: 'clip-2', from: 0, durationInFrames: 7 })])
+ })
+
+ it('routes J, K, and L to reverse, pause, and forward program transport', () => {
+ render()
+
+ fireEvent.keyDown(document, { key: 'l', code: 'KeyL' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ playbackRate: 1,
+ transportMode: 'shuttle',
+ })
+
+ fireEvent.keyDown(document, { key: 'k', code: 'KeyK' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: false,
+ playbackRate: 1,
+ transportMode: 'normal',
+ })
+
+ fireEvent.keyDown(document, { key: 'j', code: 'KeyJ' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ playbackRate: -1,
+ transportMode: 'shuttle',
+ })
+ })
+
+ it('claims K as pause even when program transport is already paused', () => {
+ render()
+
+ expect(fireEvent.keyDown(document, { key: 'k', code: 'KeyK' })).toBe(false)
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+ })
+
+ it('routes J, K, and L to the source monitor while it is hovered', () => {
+ const playerMethods = sourcePlayerMethods()
+ useSourcePlayerStore.setState({ hoveredPanel: 'source', playerMethods })
+ render()
+
+ fireEvent.keyDown(document, { key: 'j', code: 'KeyJ' })
+ fireEvent.keyDown(document, { key: 'k', code: 'KeyK' })
+ fireEvent.keyDown(document, { key: 'l', code: 'KeyL' })
+
+ expect(playerMethods.shuttleReverse).toHaveBeenCalledTimes(1)
+ expect(playerMethods.pause).toHaveBeenCalledTimes(1)
+ expect(playerMethods.shuttleForward).toHaveBeenCalledTimes(1)
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+ })
+
+ it('protects editable fields from transport shortcuts', () => {
+ render()
+ const input = screen.getByRole('textbox', { name: 'Editable title' })
+
+ fireEvent.keyDown(input, { key: 'j', code: 'KeyJ' })
+ fireEvent.keyDown(input, { key: 'k', code: 'KeyK' })
+ fireEvent.keyDown(input, { key: 'l', code: 'KeyL' })
+
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: false,
+ playbackRate: 1,
+ transportMode: 'normal',
+ })
+ })
+
+ it('does not trust spoofed timeline data attributes to suppress transport', () => {
+ const togglePlayPause = vi.spyOn(usePlaybackStore.getState(), 'togglePlayPause')
+ const { getByTestId } = render(
+
+
+ ,
+ )
+ const spoof = getByTestId('spoof')
+
+ fireEvent.keyDown(spoof, { key: ' ', code: 'Space' })
+ expect(togglePlayPause).toHaveBeenCalledTimes(1)
+
+ fireEvent.keyDown(spoof, { key: 'l', code: 'KeyL' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ transportMode: 'shuttle',
+ })
+ expect(usePlaybackStore.getState().playbackRate).toBeGreaterThan(0)
+ })
+
+ it('routes customized transport bindings instead of the defaults', () => {
+ useSettingsStore.getState().replaceHotkeyOverrides({
+ SHUTTLE_REVERSE: 'q',
+ SHUTTLE_PAUSE: 'w',
+ SHUTTLE_FORWARD: 'e',
+ })
+ render()
+
+ fireEvent.keyDown(document, { key: 'l', code: 'KeyL' })
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+
+ fireEvent.keyDown(document, { key: 'e', code: 'KeyE' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ playbackRate: 1,
+ transportMode: 'shuttle',
+ })
+
+ fireEvent.keyDown(document, { key: 'w', code: 'KeyW' })
+ expect(usePlaybackStore.getState().isPlaying).toBe(false)
+
+ fireEvent.keyDown(document, { key: 'q', code: 'KeyQ' })
+ expect(usePlaybackStore.getState()).toMatchObject({
+ isPlaying: true,
+ playbackRate: -1,
+ transportMode: 'shuttle',
+ })
+ })
+
+ it('clamps timeline ArrowRight to the final valid frame', () => {
+ usePlaybackStore.setState({ currentFrame: 13 })
+ render()
+
+ fireEvent.keyDown(document, { key: 'ArrowRight', code: 'ArrowRight' })
+ expect(usePlaybackStore.getState().currentFrame).toBe(14)
+
+ fireEvent.keyDown(document, { key: 'ArrowRight', code: 'ArrowRight' })
+ expect(usePlaybackStore.getState().currentFrame).toBe(14)
+ })
+
+ it('seeks timeline End to the maximum inclusive item frame, or zero when empty', () => {
+ render()
+
+ fireEvent.keyDown(document, { key: 'End', code: 'End' })
+ expect(usePlaybackStore.getState().currentFrame).toBe(14)
+
+ useItemsStore.getState().setItems([])
+ fireEvent.keyDown(document, { key: 'End', code: 'End' })
+ expect(usePlaybackStore.getState().currentFrame).toBe(0)
+ })
+
+ it('clamps source-player End to a nonnegative frame', () => {
+ const playerMethods = sourcePlayerMethods(0)
+ useSourcePlayerStore.setState({ hoveredPanel: 'source', playerMethods })
+ render()
+
+ fireEvent.keyDown(document, { key: 'End', code: 'End' })
+
+ expect(playerMethods.seek).toHaveBeenCalledWith(0)
+ })
+})
diff --git a/src/features/timeline/hooks/shortcuts/use-playback-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-playback-shortcuts.ts
index aaa25969f..bfe302e47 100644
--- a/src/features/timeline/hooks/shortcuts/use-playback-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-playback-shortcuts.ts
@@ -3,7 +3,7 @@
*/
import { useCallback } from 'react'
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { usePlaybackStore } from '@/shared/state/playback'
import { usePreviewBridgeStore } from '@/shared/state/preview-bridge'
import { useItemsStore } from '../../stores/items-store'
@@ -14,7 +14,6 @@ import type { TimelineShortcutCallbacks } from '../use-timeline-shortcuts'
import { useSourcePlayerStore } from '@/shared/state/source-player'
import { getFilteredItemSnapEdges } from '../../utils/timeline-snap-utils'
import { getVisibleTrackIds } from '../../utils/group-utils'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
/** Compute snap points on-demand from current store state (avoids reactive subscriptions). */
function getSnapPoints(): number[] {
@@ -34,8 +33,13 @@ function getSnapPoints(): number[] {
return Array.from(points).sort((a, b) => a - b)
}
+function getFinalTimelineFrame(): number {
+ return useItemsStore
+ .getState()
+ .items.reduce((maxFrame, item) => Math.max(maxFrame, item.from + item.durationInFrames - 1), 0)
+}
+
export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
- const hotkeys = useResolvedHotkeys()
const togglePlayPause = usePlaybackStore((s) => s.togglePlayPause)
const shuttleForward = usePlaybackStore((s) => s.shuttleForward)
const shuttleReverse = usePlaybackStore((s) => s.shuttleReverse)
@@ -54,8 +58,8 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Playback: Space - Play/Pause
- useHotkeys(
- hotkeys.PLAY_PAUSE,
+ useCommandHotkey(
+ 'PLAY_PAUSE',
(event) => {
event.preventDefault()
const { hoveredPanel, playerMethods } = useSourcePlayerStore.getState()
@@ -74,10 +78,10 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
[togglePlayPause, isPlaying, callbacks],
)
- // Shuttle: L advances forward through 1x, 2x, and 4x. Ignore browser key
+ // Shuttle forward advances through 1x, 2x, and 4x. Ignore browser key
// repeat so one physical press produces one transport transition.
- useHotkeys(
- 'l',
+ useCommandHotkey(
+ 'SHUTTLE_FORWARD',
(event) => {
if (event.repeat) return
event.preventDefault()
@@ -96,10 +100,10 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
[callbacks, shuttleForward],
)
- // Shuttle: J mirrors L in reverse. Browser media stays on a paused visual
+ // Shuttle reverse mirrors forward playback. Browser media stays on a paused visual
// seek path for negative rates; the Clock still advances at display cadence.
- useHotkeys(
- 'j',
+ useCommandHotkey(
+ 'SHUTTLE_REVERSE',
(event) => {
if (event.repeat) return
event.preventDefault()
@@ -118,33 +122,32 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
[callbacks, shuttleReverse],
)
- // K owns pause only while a transport is active. When already paused it
- // yields to the existing Edit keyframe shortcut.
- useHotkeys(
- 'k',
+ // Pause always owns its binding, including while already paused, so transport
+ // routing cannot fall through to another command.
+ useCommandHotkey(
+ 'SHUTTLE_PAUSE',
(event) => {
if (event.repeat) return
+ event.preventDefault()
+ event.stopPropagation()
const { hoveredPanel, playerMethods } = useSourcePlayerStore.getState()
if (hoveredPanel === 'source' && playerMethods) {
- if (!playerMethods.isPlaying()) return
- event.preventDefault()
- event.stopPropagation()
playerMethods.pause()
return
}
- if (!usePlaybackStore.getState().isPlaying) return
- event.preventDefault()
- event.stopPropagation()
+ const wasPlaying = usePlaybackStore.getState().isPlaying
pause()
- callbacks.onPause?.()
+ if (wasPlaying) {
+ callbacks.onPause?.()
+ }
},
{ ...HOTKEY_OPTIONS, eventListenerOptions: { capture: true } },
[callbacks, pause],
)
// Navigation: Arrow Left - Previous frame
- useHotkeys(
- hotkeys.PREVIOUS_FRAME,
+ useCommandHotkey(
+ 'PREVIOUS_FRAME',
(event) => {
event.preventDefault()
const { hoveredPanel, playerMethods } = useSourcePlayerStore.getState()
@@ -160,8 +163,8 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Navigation: Arrow Right - Next frame
- useHotkeys(
- hotkeys.NEXT_FRAME,
+ useCommandHotkey(
+ 'NEXT_FRAME',
(event) => {
event.preventDefault()
const { hoveredPanel, playerMethods } = useSourcePlayerStore.getState()
@@ -170,15 +173,15 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
return
}
const currentFrame = usePlaybackStore.getState().currentFrame
- commitTimelineSeek(currentFrame + 1)
+ commitTimelineSeek(Math.min(currentFrame + 1, getFinalTimelineFrame()))
},
HOTKEY_OPTIONS,
[commitTimelineSeek],
)
// Navigation: Home - Go to start
- useHotkeys(
- hotkeys.GO_TO_START,
+ useCommandHotkey(
+ 'GO_TO_START',
(event) => {
event.preventDefault()
const { hoveredPanel, playerMethods } = useSourcePlayerStore.getState()
@@ -193,29 +196,24 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Navigation: End - Go to end of timeline (last frame of last item)
- useHotkeys(
- hotkeys.GO_TO_END,
+ useCommandHotkey(
+ 'GO_TO_END',
(event) => {
event.preventDefault()
const { hoveredPanel, playerMethods } = useSourcePlayerStore.getState()
if (hoveredPanel === 'source' && playerMethods) {
- playerMethods.seek(playerMethods.getDurationInFrames() - 1)
+ playerMethods.seek(Math.max(0, playerMethods.getDurationInFrames() - 1))
return
}
- const currentItems = useItemsStore.getState().items
- const lastFrame = currentItems.reduce((max, item) => {
- const itemEnd = item.from + item.durationInFrames
- return Math.max(max, itemEnd)
- }, 0)
- commitTimelineSeek(lastFrame)
+ commitTimelineSeek(getFinalTimelineFrame())
},
HOTKEY_OPTIONS,
[commitTimelineSeek],
)
// Navigation: Down - Jump to next snap point (clip edge or marker)
- useHotkeys(
- hotkeys.NEXT_SNAP_POINT,
+ useCommandHotkey(
+ 'NEXT_SNAP_POINT',
(event) => {
event.preventDefault()
const currentFrame = usePlaybackStore.getState().currentFrame
@@ -229,8 +227,8 @@ export function usePlaybackShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Navigation: Up - Jump to previous snap point (clip edge or marker)
- useHotkeys(
- hotkeys.PREVIOUS_SNAP_POINT,
+ useCommandHotkey(
+ 'PREVIOUS_SNAP_POINT',
(event) => {
event.preventDefault()
const currentFrame = usePlaybackStore.getState().currentFrame
diff --git a/src/features/timeline/hooks/shortcuts/use-source-monitor-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-source-monitor-shortcuts.ts
index 0cabacc2c..0adde7a38 100644
--- a/src/features/timeline/hooks/shortcuts/use-source-monitor-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-source-monitor-shortcuts.ts
@@ -9,18 +9,15 @@
* source monitor is hovered/focused.
*/
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
import { useEditorStore } from '@/shared/state/editor'
import { performInsertEdit, performOverwriteEdit } from '../../stores/actions/source-edit-actions'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
export function useSourceMonitorShortcuts() {
- const hotkeys = useResolvedHotkeys()
-
// Insert Edit: , (comma) — works globally when source monitor is open
- useHotkeys(
- hotkeys.INSERT_EDIT,
+ useCommandHotkey(
+ 'INSERT_EDIT',
(event) => {
event.preventDefault()
const sourceMediaId = useEditorStore.getState().sourcePreviewMediaId
@@ -32,8 +29,8 @@ export function useSourceMonitorShortcuts() {
)
// Overwrite Edit: . (period) — works globally when source monitor is open
- useHotkeys(
- hotkeys.OVERWRITE_EDIT,
+ useCommandHotkey(
+ 'OVERWRITE_EDIT',
(event) => {
event.preventDefault()
const sourceMediaId = useEditorStore.getState().sourcePreviewMediaId
diff --git a/src/features/timeline/hooks/shortcuts/use-tool-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-tool-shortcuts.ts
index 9dc5a4c1c..4e8ac7d94 100644
--- a/src/features/timeline/hooks/shortcuts/use-tool-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-tool-shortcuts.ts
@@ -1,24 +1,22 @@
/**
- * Tool shortcuts: V (Select), T (Trim Edit), C (Razor), Shift+C (Split at cursor), R (Rate Stretch).
+ * Tool shortcuts: V (Select), T (Trim Edit), C (Razor), Shift+C (Split at playhead), R (Rate Stretch).
*/
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { usePlaybackStore } from '@/shared/state/playback'
import { useTimelineStore } from '../../stores/timeline-store'
import { useSelectionStore } from '@/shared/state/selection'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
import type { TimelineShortcutCallbacks } from '../use-timeline-shortcuts'
-import { useResolvedHotkeys } from '@/features/timeline/deps/settings'
import { SLIP_SLIDE_TOOLS_ENABLED } from '../../constants'
export function useToolShortcuts(callbacks: TimelineShortcutCallbacks) {
- const hotkeys = useResolvedHotkeys()
const activeTool = useSelectionStore((s) => s.activeTool)
const setActiveTool = useSelectionStore((s) => s.setActiveTool)
// Tool: V - Selection Tool
- useHotkeys(
- hotkeys.SELECTION_TOOL,
+ useCommandHotkey(
+ 'SELECTION_TOOL',
(event) => {
event.preventDefault()
setActiveTool('select')
@@ -28,8 +26,8 @@ export function useToolShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Tool: T - Toggle Trim Edit Tool
- useHotkeys(
- hotkeys.TRIM_EDIT_TOOL,
+ useCommandHotkey(
+ 'TRIM_EDIT_TOOL',
(event) => {
event.preventDefault()
setActiveTool(activeTool === 'trim-edit' ? 'select' : 'trim-edit')
@@ -39,8 +37,8 @@ export function useToolShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Tool: C - Toggle Razor/Cut Mode
- useHotkeys(
- hotkeys.RAZOR_TOOL,
+ useCommandHotkey(
+ 'RAZOR_TOOL',
(event) => {
event.preventDefault()
setActiveTool(activeTool === 'razor' ? 'select' : 'razor')
@@ -50,8 +48,8 @@ export function useToolShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Tool: Shift+C - Split hovered item at gray playhead (or main playhead)
- useHotkeys(
- hotkeys.SPLIT_AT_CURSOR,
+ useCommandHotkey(
+ 'SPLIT_AT_PLAYHEAD',
(event) => {
event.preventDefault()
const { previewFrame, previewItemId, currentFrame } = usePlaybackStore.getState()
@@ -74,8 +72,8 @@ export function useToolShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Tool: R - Toggle Rate Stretch Tool
- useHotkeys(
- hotkeys.RATE_STRETCH_TOOL,
+ useCommandHotkey(
+ 'RATE_STRETCH_TOOL',
(event) => {
event.preventDefault()
setActiveTool(activeTool === 'rate-stretch' ? 'select' : 'rate-stretch')
@@ -85,8 +83,8 @@ export function useToolShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Tool: Y - Toggle Slip Tool
- useHotkeys(
- hotkeys.SLIP_TOOL,
+ useCommandHotkey(
+ 'SLIP_TOOL',
(event) => {
event.preventDefault()
setActiveTool(activeTool === 'slip' ? 'select' : 'slip')
@@ -96,8 +94,8 @@ export function useToolShortcuts(callbacks: TimelineShortcutCallbacks) {
)
// Tool: U - Toggle Slide Tool
- useHotkeys(
- hotkeys.SLIDE_TOOL,
+ useCommandHotkey(
+ 'SLIDE_TOOL',
(event) => {
event.preventDefault()
setActiveTool(activeTool === 'slide' ? 'select' : 'slide')
diff --git a/src/features/timeline/hooks/shortcuts/use-ui-shortcuts.ts b/src/features/timeline/hooks/shortcuts/use-ui-shortcuts.ts
index cffd9cbc7..1bd43ab02 100644
--- a/src/features/timeline/hooks/shortcuts/use-ui-shortcuts.ts
+++ b/src/features/timeline/hooks/shortcuts/use-ui-shortcuts.ts
@@ -2,13 +2,13 @@
* UI shortcuts: S (snap toggle), Cmd/Ctrl+=/- (zoom), \\ (zoom to fit), Shift+\\ or Cmd/Ctrl+0 (zoom to 100%), Undo/Redo.
*/
-import { useHotkeys } from 'react-hotkeys-hook'
+import { useCommandHotkey } from '@/hooks/use-hotkey-registration'
import { useTimelineStore } from '../../stores/timeline-store'
import { useZoomStore, getZoomTo100Handler } from '../../stores/zoom-store'
import { usePlaybackStore } from '@/shared/state/playback'
import { HOTKEY_OPTIONS } from '@/config/hotkeys'
import type { TimelineShortcutCallbacks } from '../use-timeline-shortcuts'
-import { useResolvedHotkeys, useSettingsStore } from '@/features/timeline/deps/settings'
+import { useSettingsStore } from '@/features/timeline/deps/settings'
export interface UIShortcutOptions {
/**
@@ -23,14 +23,13 @@ export function useUIShortcuts(
options: UIShortcutOptions = {},
) {
const { enableHistory = true } = options
- const hotkeys = useResolvedHotkeys()
const toggleSnap = useTimelineStore((s) => s.toggleSnap)
const zoomIn = useZoomStore((s) => s.zoomIn)
const zoomOut = useZoomStore((s) => s.zoomOut)
// History: Cmd/Ctrl+Z - Undo
- useHotkeys(
- hotkeys.UNDO,
+ useCommandHotkey(
+ 'UNDO',
(event) => {
event.preventDefault()
useTimelineStore.temporal.getState().undo()
@@ -47,8 +46,8 @@ export function useUIShortcuts(
)
// History: Cmd/Ctrl+Shift+Z - Redo
- useHotkeys(
- hotkeys.REDO,
+ useCommandHotkey(
+ 'REDO',
(event) => {
event.preventDefault()
useTimelineStore.temporal.getState().redo()
@@ -65,8 +64,8 @@ export function useUIShortcuts(
)
// UI: S - Toggle Snap
- useHotkeys(
- hotkeys.TOGGLE_SNAP,
+ useCommandHotkey(
+ 'TOGGLE_SNAP',
(event) => {
event.preventDefault()
toggleSnap()
@@ -76,8 +75,8 @@ export function useUIShortcuts(
)
// UI: Shift+S - Toggle Canvas (gizmo) Snap — independent from timeline snap.
- useHotkeys(
- hotkeys.TOGGLE_CANVAS_SNAP,
+ useCommandHotkey(
+ 'TOGGLE_CANVAS_SNAP',
(event) => {
event.preventDefault()
const s = useSettingsStore.getState()
@@ -90,8 +89,8 @@ export function useUIShortcuts(
const zoomHotkeyOptions = { ...HOTKEY_OPTIONS, eventListenerOptions: { capture: true } }
// Zoom: Cmd/Ctrl+Equals - Zoom in
- useHotkeys(
- hotkeys.ZOOM_IN,
+ useCommandHotkey(
+ 'ZOOM_IN',
(event) => {
event.preventDefault()
zoomIn()
@@ -101,8 +100,8 @@ export function useUIShortcuts(
)
// Zoom: Cmd/Ctrl+Minus - Zoom out
- useHotkeys(
- hotkeys.ZOOM_OUT,
+ useCommandHotkey(
+ 'ZOOM_OUT',
(event) => {
event.preventDefault()
zoomOut()
@@ -112,8 +111,8 @@ export function useUIShortcuts(
)
// Zoom: Backslash - Zoom to Fit
- useHotkeys(
- hotkeys.ZOOM_TO_FIT,
+ useCommandHotkey(
+ 'ZOOM_TO_FIT',
(event) => {
event.preventDefault()
if (callbacks.onZoomToFit) {
@@ -144,8 +143,8 @@ export function useUIShortcuts(
)
// Zoom: Shift+Backslash - Zoom to 100% centered on cursor (or playhead if cursor not on timeline)
- useHotkeys(
- hotkeys.ZOOM_TO_100,
+ useCommandHotkey(
+ 'ZOOM_TO_100',
(event) => {
event.preventDefault()
const { currentFrame, previewFrame } = usePlaybackStore.getState()
@@ -161,8 +160,8 @@ export function useUIShortcuts(
)
// Zoom: Cmd/Ctrl+0 - Reset timeline zoom to 100%
- useHotkeys(
- hotkeys.ZOOM_TO_100_ALT,
+ useCommandHotkey(
+ 'ZOOM_TO_100_ALT',
(event) => {
event.preventDefault()
const { currentFrame, previewFrame } = usePlaybackStore.getState()
diff --git a/src/features/timeline/hooks/use-host-timeline-shortcuts.test.tsx b/src/features/timeline/hooks/use-host-timeline-shortcuts.test.tsx
index 3e2518986..cc5bee457 100644
--- a/src/features/timeline/hooks/use-host-timeline-shortcuts.test.tsx
+++ b/src/features/timeline/hooks/use-host-timeline-shortcuts.test.tsx
@@ -130,6 +130,25 @@ describe('useHostTimelineShortcuts', () => {
expect(useTimelineStore.getState().items).toHaveLength(0)
})
+ it('splits the hovered clip at the playhead on Shift+C', () => {
+ usePlaybackStore.setState({
+ currentFrame: 15,
+ previewFrame: null,
+ previewItemId: 'clip-1',
+ })
+ render()
+
+ fireEvent.keyDown(document, { key: 'C', code: 'KeyC', shiftKey: true })
+
+ expect(useTimelineStore.getState().items).toHaveLength(2)
+ expect(useTimelineStore.getState().items).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ id: 'clip-1', from: 0, durationInFrames: 15 }),
+ expect.objectContaining({ from: 15, durationInFrames: 15 }),
+ ]),
+ )
+ })
+
it('does not undo timeline edits on Mod+Z in host mode', () => {
useTimelineStore.getState().moveItem('clip-1', 30)
expect(useTimelineCommandStore.getState().undoStack).toHaveLength(1)
diff --git a/src/features/timeline/hooks/use-timeline-drag.dom.test.tsx b/src/features/timeline/hooks/use-timeline-drag.dom.test.tsx
new file mode 100644
index 000000000..b01682bd4
--- /dev/null
+++ b/src/features/timeline/hooks/use-timeline-drag.dom.test.tsx
@@ -0,0 +1,711 @@
+import { useState } from 'react'
+import { act, fireEvent, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import type { TimelineItem, TimelineTrack } from '@/types/timeline'
+import { useEditorStore } from '@/shared/state/editor'
+import { useSelectionStore } from '@/shared/state/selection'
+import {
+ makeTimelineAudioItem,
+ makeTimelineTrack,
+ makeTimelineVideoItem,
+ resetTimelineCompositionTestState,
+} from '../test-helpers'
+import { useItemsStore } from '../stores/items-store'
+import { useLinkedEditPreviewStore } from '../stores/linked-edit-preview-store'
+import { useTimelineCommandStore } from '../stores/timeline-command-store'
+import { useTimelineSettingsStore } from '../stores/timeline-settings-store'
+import { useTimelineStore } from '../stores/timeline-store'
+import { useTransitionsStore } from '../stores/transitions-store'
+import { useZoomStore } from '../stores/zoom-store'
+import { getLinkedItemIds } from '../utils/linked-items'
+import { resetPostTimelineGestureClickForTest } from '../components/timeline-item/post-drag-click-guard'
+import { useTimelineDrag } from './use-timeline-drag'
+
+const TIMELINE_DURATION = 600
+const TRACK_HEIGHT = 80
+let rafCallbacks = new Map()
+let nextRafId = 1
+
+function makeRect(top: number, bottom: number): DOMRect {
+ return {
+ x: 0,
+ y: top,
+ top,
+ left: 0,
+ right: 1000,
+ bottom,
+ width: 1000,
+ height: bottom - top,
+ toJSON: () => ({}),
+ }
+}
+
+function setupStores(tracks: TimelineTrack[], items: TimelineItem[]) {
+ resetTimelineCompositionTestState()
+ useTimelineSettingsStore.setState({ fps: 30, isDirty: false, snapEnabled: false })
+ useZoomStore.setState({ level: 0.3, pixelsPerSecond: 30 })
+ useItemsStore.getState().setTracks(tracks)
+ useItemsStore.getState().setItems(items)
+ useTransitionsStore.getState().setTransitions([])
+ useEditorStore.setState({ linkedSelectionEnabled: true })
+ useSelectionStore.getState().clearSelection()
+ useSelectionStore.getState().setDragState(null)
+ useSelectionStore.getState().setActiveSnapTarget(null)
+ useSelectionStore.getState().setActiveLinkedDropTarget(null)
+ useLinkedEditPreviewStore.getState().clear()
+}
+
+function captureSelectionMetadata() {
+ const state = useSelectionStore.getState()
+ return {
+ selectedItemIds: [...state.selectedItemIds],
+ selectedItemIdSet: new Set(state.selectedItemIdSet),
+ selectedMarkerId: state.selectedMarkerId,
+ selectedTransitionId: state.selectedTransitionId,
+ selectedTrackId: state.selectedTrackId,
+ selectedTrackIds: [...state.selectedTrackIds],
+ activeTrackId: state.activeTrackId,
+ selectionType: state.selectionType,
+ activeTool: state.activeTool,
+ activeSnapTarget: state.activeSnapTarget,
+ activeLinkedDropTarget: state.activeLinkedDropTarget,
+ dragState: state.dragState,
+ editKeyframePanelOpen: state.editKeyframePanelOpen,
+ expandedKeyframeLanes: new Set(state.expandedKeyframeLanes),
+ }
+}
+
+function captureMutationState() {
+ const history = useTimelineCommandStore.getState()
+ return {
+ items: structuredClone(useItemsStore.getState().items),
+ tracks: structuredClone(useItemsStore.getState().tracks),
+ isDirty: useTimelineSettingsStore.getState().isDirty,
+ undoStack: structuredClone(history.undoStack),
+ redoStack: structuredClone(history.redoStack),
+ canUndo: history.canUndo,
+ canRedo: history.canRedo,
+ }
+}
+
+function RenderedDragSurface({
+ item,
+ tracks,
+ onClipClick,
+ onBackgroundClick,
+}: {
+ item: TimelineItem
+ tracks: TimelineTrack[]
+ onClipClick?: () => void
+ onBackgroundClick?: () => void
+}) {
+ const { handleDragStart } = useTimelineDrag(item, TIMELINE_DURATION)
+ const [, rerender] = useState(0)
+
+ return (
+ {
+ onBackgroundClick?.()
+ const selection = useSelectionStore.getState()
+ selection.clearItemSelection()
+ selection.selectMarker(null)
+ rerender((value) => value + 1)
+ }}
+ >
+
+ {[...tracks]
+ .sort((left, right) => left.order - right.order)
+ .map((track) => (
+
+ {track.id === item.trackId && (
+
+ )}
+
+ ))}
+
+