Ship FreeCut v1 Editor Hardening and Shortcut Controls

.fallowrc.json

@@ -4,6 +4,7 @@
     "src/index.{ts,tsx,js,jsx}",
     "src/main.{ts,tsx,js,jsx}",
     "src/test/setup.ts",
+    "tests/browser/host-responsive.tsx",
     "headless/probe.mjs",
     "headless/smoke.mjs",
     "headless/media-smoke.mjs"

.gitignore

@@ -34,6 +34,8 @@ out
 
 # Testing
 coverage
+playwright-report/
+test-results/
 
 # Misc
 .cache

artifacts/freecut-v1-final-integration-manifest.md

@@ -0,0 +1,68 @@
+# FreeCut v1 final integration manifest
+
+## PR #30 QA-blocker reconciliation
+
+- Superseded QA head: `925ebf37b01692c4b066407a9ee6a8563fd8028f`
+- Integration base: `origin/codepress-main` at `aedf4d70b86615a73fcb382a2843eb14606d1eb4`
+- Destination: `v1-release-integration-final`
+- Package: `@quantfive/freecut-editor-surface@0.3.9` (version unchanged)
+- Source integration head before this evidence/provenance commit: `5709e474515443fefd994507099b9cd2afc65749`
+
+### Commit inventory
+
+The four fixes were cherry-picked with `-x`, in this order, from the exact superseded QA head:
+
+| Order | Source commit | Integrated commit | Purpose |
+| --- | --- | --- | --- |
+| 1 | `f22464674582b2afe987cbb3486ddc60fd7d53ea` | `573c72f2b5ca1b7bd6020f59a3000980ed18f13f` | Contiguous shared-edge rolling trim |
+| 2 | `c9494a515e27074482bf7ba8bbd1998f4fc8ced3` | `676d6f5cde3577457d996ca5e25edfe06ad99923` | Keyboard-accessible clips and scrollbars |
+| 3 | `bec5c41eea03db70b08ec4506e2a6a72c458e37b` | `df9c0f63e82a7874333efa10a93495b6f3a41bee` | Responsive mobile editor |
+| 4 | `e0bd5e66011fdb7646c8be2b8939a172dd68bc30` | `5709e474515443fefd994507099b9cd2afc65749` | Runtime observability |
+
+All four source commits have parent `925ebf37b01692c4b066407a9ee6a8563fd8028f`.
+
+### Conflict and overlap resolution
+
+- `TimelineItem` had one textual import conflict. The resolution retains one named, focusable semantic clip root and keeps the shared rolling-trim sliders, trim/fade controls, and indicators as sibling interaction surfaces. This avoids nested native controls and keeps pointer gestures, Razor, playback shortcuts, lock rejection, and keyboard slider steps under their intended owners.
+- The responsive commit applied without textual conflicts. Focused React and real-Chrome rows verified compact standalone and embedded-host layouts while retaining keyboard scrollbars, rolling handles, Razor routing, lock invariants, linked drag, live shortcut labels, and the desktop geometry branch.
+- The observability commit auto-merged its `audio-meter-panel.tsx` overlap with the responsive layout. The result retains the compact/mobile panel contract and uses the shared media URL for waveform loading; no page-owned object URL is revoked. Export capability fallback remains preflight-only, while genuine render and worker-runtime failures remain primary errors.
+
+### Package and provenance
+
+- Two independent deterministic package builds produced byte-identical tarballs.
+- New artifact: `artifacts/freecut-editor-surface-0.3.9.tgz`
+- New SHA-256: `27855709f334dcac4eda5adc7771c9b0a1fd0b5f47e9a3844c391218ac9ba77c`
+- The prior `59012...` QA artifact is superseded by this source-derived artifact.
+- A fresh consumer installed the exact tarball and rendered `@quantfive/freecut-editor-surface@0.3.9`: 1 test file, 2 tests passed.
+- The responsive Playwright script changed root `package.json`; the supported package-manifest hash in `provenance/freecut-baseline.json` and `provenance/dependency-inventory.json` was refreshed to `7786ffe5cde5b09b6f88fc4fd13af399365ac0d6dc32f320d6f719c6f62edc89`. Lockfile, dependency inventory, asset inventory, release workflow, and package version are unchanged.
+
+### Verification results
+
+All commands ran under Node `22.20.0` and npm `11.8.0` unless the command itself launched a browser.
+
+| Gate | Result |
+| --- | --- |
+| Four-worker focused Vitest union | PASS — 17 files, 184 tests |
+| Responsive real-Chrome standalone 390 / host 390 / desktop 1440 rows | PASS — 3/3 |
+| Real Chromium QA smoke | PASS — system Chrome 151; ready, frame result, width, and PNG pixel checks |
+| LOCK49 focused matrix | PASS — 12 files, 156 tests |
+| DRAG45 focused matrix | PASS — 7 files, 90 tests |
+| Shortcut and host-settings matrix | PASS — 15 files, 182 tests |
+| Export-focused matrix | PASS — 41 files, 399 tests |
+| Full serial Vitest (`maxWorkers=1`, file parallelism disabled) | PASS — 710 files, 5,288 tests; fixed thresholds unchanged |
+| `npm run check` | PASS — 2,482 files, no warnings, lint errors, or type errors |
+| Scoped format and diff checks | PASS — 46 formatted files; `git diff --check` clean |
+| Production build | PASS |
+| Boundaries / deps contracts / legacy imports / wrapper health | PASS — 1,707 source files; 161 deps and 298 contract files; 46 wrappers, 0 unused |
+| Changed health / edge budgets | PASS — no introduced dead code, complexity, or duplication; all 8 seams within budgets |
+| Runtime hotkey import boundary | PASS — 1,735 source files |
+| Unused-export and class-member audits | Existing baseline findings only; every reported path is unchanged from the superseded QA head and both allowlists are unchanged |
+| Provenance verification | PASS — source, licenses/notices, 51 runtime and 16 development dependencies, and 5 asset roots |
+| Publish/release guards | PASS — 7/7 guard tests; package remains `0.3.9`; package manifest, lockfile, and publish workflow guards unchanged |
+| Portable headless contracts | PASS — 43 Node contracts, real-Chrome render/edit/lifecycle, 19 edit operations, and 192,044-byte media/audio contract |
+| QA redaction | PASS — 7 files scanned and 6/6 fail-closed self-tests |
+| Full pre-push hook | PASS — all 7 steps |
+
+### Hosted evidence for superseded head
+
+Before integration, live PR #30 was OPEN and DRAFT at the exact superseded head. Its hosted `Quality Checks`, `Verify and package baseline`, and `Preview Sync Stress` checks were all `SUCCESS`. This is evidence for the old head only; no PR body, state, comment, or readiness change was made.

package.json

@@ -43,6 +43,8 @@
     "routes": "tsr generate",
     "test": "vp test",
     "test:run": "vp test run",
+    "test:responsive": "playwright test --config playwright.mobile.config.ts",
+    "test:editor-hardening": "vp test run src/features/timeline/components/timeline-content.test.tsx src/features/timeline/components/timeline-item/use-timeline-item-pointer-handlers.test.tsx src/features/timeline/hooks/shortcuts/use-clipboard-shortcuts.test.tsx src/features/timeline/hooks/shortcuts/use-playback-shortcuts.test.tsx src/features/timeline/stores/export-snapshot.test.ts src/features/export/components/export-dialog.test.tsx src/features/export/hooks/client-render-source.test.ts src/features/export/hooks/use-client-render.test.tsx src/features/preview/workers/consume-video-samples.test.ts src/features/preview/utils/media-resolver.test.ts src/features/preview/hooks/use-preview-media-resolution.test.tsx src/features/preview/components/source-composition.generation.test.tsx src/features/preview/components/video-preview.sync.test.tsx src/infrastructure/browser/blob-url-manager.test.ts",
     "test:preview-sync": "vp test run src/features/preview/components/video-preview.sync.test.tsx",
     "test:preview-sync:stress": "node scripts/preview-sync-stress.mjs --runs 20",
     "test:coverage": "vp test run --coverage",

packages/freecut-editor/README.md

@@ -63,6 +63,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,15 +1,21 @@
 // @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 EditorTranscriptPort,
   type EmbeddedEditorSnapshot,
+  type HostEditPredicate,
+  type HostNotice,
 } from '@quantfive/freecut-editor-surface'
 
 const snapshot: EmbeddedEditorSnapshot = {
@@ -44,6 +50,16 @@ function fakeHost(): EditorHost {
     submitEdit: vi.fn(() => {
       throw new Error('consumer smoke does not submit an edit')
     }),
+    subscribe: vi.fn(() => () => undefined),
+    shortcuts: {
+      getSettings: () =>
+        createHostShortcutSettings({
+          SHUTTLE_REVERSE: 'q',
+          SHUTTLE_PAUSE: 'w',
+          SHUTTLE_FORWARD: 'e',
+        }),
+      setSettings: vi.fn(),
+    },
   }
 }
 
@@ -108,10 +124,28 @@ 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(host.subscribe).toHaveBeenCalledTimes(1)
     expect(capabilityForCommand('move_item')).toBe('timeline.move')
+    expect(capabilityForCommand('ripple_delete')).toBe('timeline.remove')
     expect(capabilityForCommand('set_caption_style')).toBe('timeline.caption')
     expect(isHostCapabilityEnabled(host.capabilities, 'timeline.add')).toBe(false)
+
+    const predicate: HostEditPredicate = 'sourceRange'
+    const notice: HostNotice = {
+      kind: 'unsupported',
+      message: 'Unsupported edit',
+      detail: { code: 'ambiguous_change', failedPredicates: [predicate] },
+    }
+    const requestTranscription = vi.fn<NonNullable<EditorTranscriptPort['requestTranscription']>>()
+    expect(notice.detail?.failedPredicates).toEqual(['sourceRange'])
+    expect(requestTranscription).toBeTypeOf('function')
   })
 
   it('sizes the published surface against its container, never the viewport', async () => {

packages/freecut-editor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantfive/freecut-editor-surface",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "The host-backed FreeCut browser editor surface.",
   "license": "MIT",
   "repository": {

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'
@@ -354,6 +431,25 @@ 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
@@ -362,6 +458,7 @@ export interface EditorHost {
   ): Promise<ResolvedMediaLocator | null> | ResolvedMediaLocator | null
   submitEdit(batch: EditCommandBatch): Promise<HostEditResult> | HostEditResult
   subscribe?(listener: (snapshot: EmbeddedEditorSnapshot) => void): () => void
+  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,
@@ -32,6 +38,7 @@ export type {
   HostEditResult,
   HostMediaKind,
   HostNotice,
+  HostShortcutSettings,
   HostTranscriptCommandAction,
   HostTranscriptCommandPreview,
   HostTranscriptCommandPreviewRequest,

playwright.mobile.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'playwright/test'
+
+export default defineConfig({
+  testDir: './tests/browser',
+  testMatch: 'responsive-editor.spec.ts',
+  fullyParallel: false,
+  workers: 1,
+  reporter: 'line',
+  use: {
+    baseURL: 'http://127.0.0.1:4178',
+    channel: 'chrome',
+    headless: true,
+    trace: 'retain-on-failure',
+  },
+  webServer: {
+    command: 'npm run dev -- --port 4178 --strictPort',
+    url: 'http://127.0.0.1:4178',
+    reuseExistingServer: true,
+    timeout: 120_000,
+  },
+})

provenance/dependency-inventory.json

@@ -3,7 +3,7 @@
   "generatedFrom": "package.json",
   "packageName": "freecut",
   "packageVersion": "0.0.0",
-  "packageJsonSha256": "0fcaa186e39d48d5e4e95339c0a853543aeea2a8bbbb54691a51502eb4d3bd5b",
+  "packageJsonSha256": "7786ffe5cde5b09b6f88fc4fd13af399365ac0d6dc32f320d6f719c6f62edc89",
   "lockfile": {
     "path": "package-lock.json",
     "lockfileVersion": 3,

provenance/freecut-baseline.json

@@ -34,7 +34,7 @@
   ],
   "dependencies": {
     "packageJson": "package.json",
-    "packageJsonSha256": "0fcaa186e39d48d5e4e95339c0a853543aeea2a8bbbb54691a51502eb4d3bd5b",
+    "packageJsonSha256": "7786ffe5cde5b09b6f88fc4fd13af399365ac0d6dc32f320d6f719c6f62edc89",
     "lockfile": "package-lock.json",
     "lockfileVersion": 3,
     "lockfileSha256": "b4a86741ce7891da1f63df01b6fdd4ed507e8887d5097c6a0f93fc2ea6f3420e",

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[]