Make Transport Shortcuts Canonical and Discoverable

packages/freecut-editor/README.md

@@ -38,6 +38,12 @@ provider details, URLs, paths, and media bytes remain host-owned.
 The same 0.3.0 surface retains the host-backed caption tracks, bounded cues,
 caption styles, and display toggles from 0.2.0.
 
+Hosts can also provide the optional `EditorHost.shortcuts` port. Its versioned
+`HostShortcutSettings` payload carries the same override map used by FreeCut's
+shortcut editor, including J/K/L transport. UI changes call `setSettings`, and
+host or agent changes can flow back through `subscribe`, so embedded shortcut
+configuration never becomes a UI-only setting.
+
 This package is built from a specific FreeCut commit. To create the local
 consumer artifact from a clean checkout, run:
 

packages/freecut-editor/consumer-smoke.test.tsx

@@ -1,12 +1,15 @@
 // @vitest-environment jsdom
+/// <reference path="./consumer-smoke-style.d.ts" />
 
 import '@testing-library/jest-dom'
 import '@quantfive/freecut-editor-surface/style.css'
 import { render, screen, waitFor } from '@testing-library/react'
 import { beforeAll, describe, expect, it, vi } from 'vite-plus/test'
 import {
   FreeCutEditorSurface,
+  HOTKEYS,
   capabilityForCommand,
+  createHostShortcutSettings,
   isHostCapabilityEnabled,
   type EditorHost,
   type EmbeddedEditorSnapshot,
@@ -44,6 +47,15 @@ function fakeHost(): EditorHost {
     submitEdit: vi.fn(() => {
       throw new Error('consumer smoke does not submit an edit')
     }),
+    shortcuts: {
+      getSettings: () =>
+        createHostShortcutSettings({
+          SHUTTLE_REVERSE: 'q',
+          SHUTTLE_PAUSE: 'w',
+          SHUTTLE_FORWARD: 'e',
+        }),
+      setSettings: vi.fn(),
+    },
   }
 }
 
@@ -89,6 +101,12 @@ describe('published FreeCut browser entry', () => {
 
     expect(screen.getByTestId('properties-clip-panel-host')).toBeInTheDocument()
     expect(await screen.findByTestId('caption-editor')).toBeInTheDocument()
+    expect(HOTKEYS).toMatchObject({
+      SHUTTLE_REVERSE: 'j',
+      SHUTTLE_PAUSE: 'k',
+      SHUTTLE_FORWARD: 'l',
+      EDIT_KEYFRAME_ADD: 'shift+k',
+    })
     expect(host.load).toHaveBeenCalledTimes(1)
     expect(capabilityForCommand('move_item')).toBe('timeline.move')
     expect(capabilityForCommand('set_caption_style')).toBe('timeline.caption')

packages/freecut-editor/src/index.d.ts

@@ -1,5 +1,82 @@
 import type { ComponentType, ReactNode } from 'react'
 
+export type HotkeyKey =
+  | 'PLAY_PAUSE'
+  | 'SHUTTLE_REVERSE'
+  | 'SHUTTLE_PAUSE'
+  | 'SHUTTLE_FORWARD'
+  | 'PREVIOUS_FRAME'
+  | 'NEXT_FRAME'
+  | 'GO_TO_START'
+  | 'GO_TO_END'
+  | 'NEXT_SNAP_POINT'
+  | 'PREVIOUS_SNAP_POINT'
+  | 'SPLIT_AT_PLAYHEAD'
+  | 'SPLIT_AT_PLAYHEAD_ALT'
+  | 'JOIN_ITEMS'
+  | 'DELETE_SELECTED'
+  | 'DELETE_SELECTED_ALT'
+  | 'RIPPLE_DELETE'
+  | 'RIPPLE_DELETE_ALT'
+  | 'FREEZE_FRAME'
+  | 'LINK_AUDIO_VIDEO'
+  | 'UNLINK_AUDIO_VIDEO'
+  | 'TOGGLE_LINKED_SELECTION'
+  | 'NUDGE_LEFT'
+  | 'NUDGE_RIGHT'
+  | 'NUDGE_UP'
+  | 'NUDGE_DOWN'
+  | 'NUDGE_LEFT_LARGE'
+  | 'NUDGE_RIGHT_LARGE'
+  | 'NUDGE_UP_LARGE'
+  | 'NUDGE_DOWN_LARGE'
+  | 'UNDO'
+  | 'REDO'
+  | 'ZOOM_IN'
+  | 'ZOOM_OUT'
+  | 'ZOOM_TO_FIT'
+  | 'ZOOM_TO_100'
+  | 'ZOOM_TO_100_ALT'
+  | 'COPY'
+  | 'CUT'
+  | 'PASTE'
+  | 'SELECTION_TOOL'
+  | 'TRIM_EDIT_TOOL'
+  | 'RAZOR_TOOL'
+  | 'RATE_STRETCH_TOOL'
+  | 'SLIP_TOOL'
+  | 'SLIDE_TOOL'
+  | 'SAVE'
+  | 'EXPORT'
+  | 'TOGGLE_SNAP'
+  | 'TOGGLE_CANVAS_SNAP'
+  | 'OPEN_SCENE_BROWSER'
+  | 'WORKSPACE_EDIT'
+  | 'WORKSPACE_COLOR'
+  | 'WORKSPACE_ANIMATE'
+  | 'ADD_MARKER'
+  | 'REMOVE_MARKER'
+  | 'PREVIOUS_MARKER'
+  | 'NEXT_MARKER'
+  | 'CLEAR_KEYFRAMES'
+  | 'KEYFRAME_EDITOR_GRAPH'
+  | 'KEYFRAME_EDITOR_DOPESHEET'
+  | 'KEYFRAME_EDITOR_SPLIT'
+  | 'EDIT_KEYFRAME_ADD'
+  | 'KEYFRAME_PREVIOUS'
+  | 'KEYFRAME_NEXT'
+  | 'KEYFRAME_TOGGLE_AUTO'
+  | 'KEYFRAME_FIT'
+  | 'MARK_IN'
+  | 'MARK_OUT'
+  | 'CLEAR_IN_OUT'
+  | 'INSERT_EDIT'
+  | 'OVERWRITE_EDIT'
+
+export type HotkeyOverrideMap = Partial<Record<HotkeyKey, string>>
+
+export declare const HOTKEYS: Readonly<Record<HotkeyKey, string>>
+
 export type EditorCapability =
   | 'project.navigate'
   | 'project.save'
@@ -333,13 +410,33 @@ export interface EditorHostNavigation {
   back(): void
 }
 
+export declare const HOST_SHORTCUTS_SCHEMA: 'freecut-host-shortcuts'
+export declare const HOST_SHORTCUTS_VERSION: 1
+
+export interface HostShortcutSettings {
+  schema: typeof HOST_SHORTCUTS_SCHEMA
+  version: typeof HOST_SHORTCUTS_VERSION
+  overrides: HotkeyOverrideMap
+}
+
+export interface EditorShortcutPort {
+  getSettings(): Promise<HostShortcutSettings> | HostShortcutSettings
+  setSettings(settings: HostShortcutSettings): Promise<void> | void
+  subscribe?(listener: (settings: HostShortcutSettings) => void): () => void
+}
+
+export declare function createHostShortcutSettings(
+  overrides?: HotkeyOverrideMap,
+): HostShortcutSettings
+
 export interface EditorHost {
   readonly capabilities: EditorCapabilityMap
   load(): Promise<EmbeddedEditorSnapshot> | EmbeddedEditorSnapshot
   resolveMedia(
     locator: MediaLocator,
   ): Promise<ResolvedMediaLocator | null> | ResolvedMediaLocator | null
   submitEdit(batch: EditCommandBatch): Promise<HostEditResult> | HostEditResult
+  shortcuts?: EditorShortcutPort
   transcript?: EditorTranscriptPort
   navigation?: EditorHostNavigation
   notify?(notice: HostNotice): void

packages/freecut-editor/src/index.ts

@@ -1,7 +1,11 @@
 export { FreeCutEditorSurface } from '@/features/editor/host/editor-surface'
 export { EditorHostProvider } from '@/features/editor/host/context-provider'
+export { HOTKEYS } from '@/config/hotkeys'
+export type { HotkeyKey, HotkeyOverrideMap } from '@/config/hotkeys'
 export {
   DEFAULT_HOST_CAPABILITIES,
+  HOST_SHORTCUTS_SCHEMA,
+  HOST_SHORTCUTS_VERSION,
   MAX_TRANSCRIPT_COMMAND_TEXT_BYTES,
   MAX_TRANSCRIPT_CURSOR_LENGTH,
   MAX_TRANSCRIPT_DURATION_US,
@@ -11,6 +15,7 @@ export {
   MAX_TRANSCRIPT_SELECTIONS,
   SUPPORTED_HOST_COMMANDS,
   capabilityForCommand,
+  createHostShortcutSettings,
   createLocalEditorHost,
   isHostCapabilityEnabled,
 } from '@/features/editor/host/contract'
@@ -21,6 +26,7 @@ export type {
   EditorCapabilityMap,
   EditorHost,
   EditorHostNavigation,
+  EditorShortcutPort,
   EmbeddedEditorAsset,
   EmbeddedEditorProject,
   EmbeddedEditorSnapshot,
@@ -30,6 +36,7 @@ export type {
   HostEditResult,
   HostMediaKind,
   HostNotice,
+  HostShortcutSettings,
   HostTranscriptCommandAction,
   HostTranscriptCommandPreview,
   HostTranscriptCommandPreviewRequest,

scripts/runtime-hotkey-import-boundary.d.mts

@@ -0,0 +1,19 @@
+export interface RuntimeHotkeyBoundarySource {
+  path: string
+  source: string
+}
+
+export interface RuntimeHotkeyImportViolation {
+  path: string
+  line: number
+  column: number
+  allowedPath: string
+  message: string
+}
+
+export declare const RUNTIME_HOTKEY_ADAPTER_PATH: 'src/hooks/use-hotkey-registration.ts'
+
+export declare function findReactHotkeysHookImportViolations(
+  sources: RuntimeHotkeyBoundarySource[],
+  allowedPath?: string,
+): RuntimeHotkeyImportViolation[]