Skip to content

Open source CapCut alternative.

TypeScript

fix(site): the editor keeps hold of its keyboard

David Lea0495ad18d82
diff --git a/site/src/cut/components/Editor.tsx b/site/src/cut/components/Editor.tsx
index 8bbdd077..fb49a10c 100644
--- a/site/src/cut/components/Editor.tsx
+++ b/site/src/cut/components/Editor.tsx
@@ -47,6 +47,16 @@ import { useOnboardingCover } from "@/cut/lib/onboarding";
import { requestSidePanel } from "@/cut/lib/panelRequest";
import { reportSwallowed } from "@/cut/lib/report";
import { resolveProjectPlacement } from "@/cut/lib/residency";
+import {
+ dialogOnTop,
+ isDeleteKey,
+ isPasteTarget,
+ isTyping,
+ noteKey,
+ reportDecline,
+ shortcutDecline,
+ shortcutReached,
+} from "@/cut/lib/shortcutGate";
import {
docAudioClips,
docClips,
@@ -652,23 +662,39 @@ export function Editor({
};
}, [projectId, viewer]);
- // Hand the keyboard back to the editor shell, unless the user is typing.
+ // Hand the keyboard back to the editor shell. Work that finishes on its own
+ // — an import landing — never interrupts a sentence, so a field being typed
+ // in keeps the keyboard here.
const shellRef = useRef<HTMLDivElement>(null);
const focusShell = useCallback(() => {
const active = document.activeElement as HTMLElement | null;
- if (active) {
- const type = (active as HTMLInputElement).type;
- const typing =
- active.tagName === "TEXTAREA" ||
- active.isContentEditable ||
- (active.tagName === "INPUT" &&
- !["checkbox", "radio", "range", "button", "file"].includes(type));
- if (typing) return;
- active.blur();
- }
+ if (isTyping(active)) return;
+ active?.blur();
shellRef.current?.focus({ preventScroll: true });
}, []);
+ // A press on the timeline is different: the editor's keys are hostage to
+ // whatever holds focus, and a field typed in once would hold space, ⌫ and ⌘B
+ // for the rest of the session — the lane gestures call preventDefault, which
+ // stops the browser moving focus on its own. Reaching for the timeline is
+ // that person leaving the field, so the shell takes the keyboard back. Only
+ // the timeline: everywhere else a press may well belong to the field it sits
+ // beside (a composer's send button, an inspector's stepper). Capture, to
+ // land before the gesture that swallows the press.
+ useEffect(() => {
+ const onDown = (e: PointerEvent) => {
+ const shell = shellRef.current;
+ const target = e.target;
+ if (!shell || !(target instanceof Element) || !target.closest("[data-tl-scroll]")) return;
+ const active = document.activeElement;
+ if (isTyping(target) || !isTyping(active) || !(active instanceof HTMLElement)) return;
+ active.blur();
+ shell.focus({ preventScroll: true });
+ };
+ window.addEventListener("pointerdown", onDown, true);
+ return () => window.removeEventListener("pointerdown", onDown, true);
+ }, []);
+
const importFiles = useCallback(
async (
files: FileList | File[],
@@ -871,14 +897,8 @@ export function Editor({
const s = useEditor.getState();
if (e.defaultPrevented || s.readOnly) return;
// A dialog on top owns the paste, the same way it owns the shortcuts.
- if (s.exportOpen || document.querySelector('[data-slot="dialog-content"]')) return;
- const target = e.target as HTMLElement | null;
- const textEntry =
- !!target &&
- (target.tagName === "TEXTAREA" ||
- target.tagName === "INPUT" ||
- target.isContentEditable);
- if (textEntry) return;
+ if (s.exportOpen || dialogOnTop()) return;
+ if (isPasteTarget(e.target)) return;
const files = Array.from(e.clipboardData?.items ?? [])
.filter((i) => i.kind === "file" && i.type.startsWith("image/"))
.map((i) => i.getAsFile())
@@ -894,28 +914,27 @@ export function Editor({
// Keyboard shortcuts.
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
- const target = e.target as HTMLElement;
- const inputType = (target as HTMLInputElement).type;
- const textEntry =
- target.tagName === "TEXTAREA" ||
- target.tagName === "SELECT" ||
- target.isContentEditable ||
- (target.tagName === "INPUT" &&
- !["checkbox", "radio", "range", "button", "file"].includes(inputType));
- if (textEntry) return;
+ noteKey();
+ const target = e.target instanceof HTMLElement ? e.target : null;
+ const inputType = (target as HTMLInputElement | null)?.type;
+ const s = useEditor.getState();
+ const declined = shortcutDecline(e, { exportOpen: s.exportOpen });
+ if (declined) {
+ reportDecline(declined, e);
+ return;
+ }
// Let native toggle/slider behavior win for focused controls.
const controlFocused =
- target.tagName === "INPUT" || target.closest('[role="switch"],[role="slider"]') !== null;
+ target?.tagName === "INPUT" ||
+ target?.closest('[role="switch"],[role="slider"]') != null;
// Space is narrower: a checkbox or a switch flips on it, so it keeps the
// key. A slider does not — it moves on the arrows — and neither does a
// scrub bar, so focus left on one of those (the transport, the zoom
// control, the seek bar the pointer last touched) must not swallow the
// one key the whole editor is played with.
const spaceTaken =
- ["checkbox", "radio"].includes(inputType) ||
- target.closest('[role="switch"],[role="checkbox"]') !== null;
- const s = useEditor.getState();
- if (s.exportOpen || document.querySelector('[data-slot="dialog-content"]')) return;
+ (!!inputType && ["checkbox", "radio"].includes(inputType)) ||
+ target?.closest('[role="switch"],[role="checkbox"]') != null;
// A read-only view keeps playback keys; everything that edits is out.
if (s.readOnly) {
@@ -927,21 +946,30 @@ export function Editor({
((e.metaKey || e.ctrlKey) &&
e.key.toLowerCase() === "j" &&
s.sharedFeatures?.chat === true);
- if (!allowed) return;
+ if (!allowed) {
+ reportDecline("read-only", e);
+ return;
+ }
}
+ shortcutReached();
+
+ // ⌘ on a Mac, Ctrl elsewhere — and never with Alt down: a Brazilian or
+ // European layout types its extra characters on AltGr, which Windows
+ // sends as ctrl+alt, so ⌘C on one of those keyboards is really ₢.
+ const mod = (e.metaKey || e.ctrlKey) && !e.altKey;
if (e.code === "Space" && !spaceTaken) {
e.preventDefault();
if (!s.playing && playheadAt() >= projectDuration(s) - 0.01) s.seek(0);
s.setPlaying(!s.playing);
- } else if (e.key === "Backspace" || e.key === "Delete") {
+ } else if (isDeleteKey(e)) {
e.preventDefault();
s.deleteSelection();
- } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "z") {
+ } else if (mod && e.key.toLowerCase() === "z") {
e.preventDefault();
if (e.shiftKey) s.redo();
else s.undo();
- } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "c") {
+ } else if (mod && e.key.toLowerCase() === "c") {
// Selected page text keeps native ⌘C. Otherwise, alongside the
// internal copy (for ⌘V back onto the timeline), the selection's
// mention tokens go to the system clipboard, so a copied clip,
@@ -961,7 +989,7 @@ export function Editor({
if (copied) clearCopiedFrame();
if (copied || token) e.preventDefault();
}
- } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "v") {
+ } else if (mod && e.key.toLowerCase() === "v") {
// The timeline clipboard first; a frame copied off the preview canvas
// lands as a still under the indicator. Where it lands is read at the
// keystroke, so a still that waits on its draw or its upload still
@@ -983,7 +1011,7 @@ export function Editor({
})
.catch((err) => reportSwallowed("[cut] paste frame failed", err));
}
- } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "g") {
+ } else if (mod && e.key.toLowerCase() === "g") {
// ⌘G groups the multi-selected elements, ⇧⌘G dissolves the primary's
// group — the panel's Group button is out of reach while a
// multi-selection keeps the inspector closed.
@@ -997,16 +1025,16 @@ export function Editor({
} else {
s.groupSelectedOverlays();
}
- } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "j") {
+ } else if (mod && e.key.toLowerCase() === "j") {
e.preventDefault();
s.setAiOpen(!s.aiOpen);
- } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "b") {
+ } else if (mod && e.key.toLowerCase() === "b") {
e.preventDefault();
// Cut at the skimmer when the mouse is over the timeline.
s.splitAtPlayhead(skimAt() ?? undefined);
- } else if (e.key.toLowerCase() === "s" && !e.metaKey && !e.ctrlKey) {
+ } else if (e.key.toLowerCase() === "s" && !e.metaKey && !e.ctrlKey && !e.altKey) {
s.splitAtPlayhead(skimAt() ?? undefined);
- } else if (e.key.toLowerCase() === "t" && !e.metaKey && !e.ctrlKey) {
+ } else if (e.key.toLowerCase() === "t" && !e.metaKey && !e.ctrlKey && !e.altKey) {
s.addOverlay();
} else if ((e.key === "ArrowLeft" || e.key === "ArrowRight") && !controlFocused) {
e.preventDefault();
diff --git a/site/src/cut/components/Timeline.tsx b/site/src/cut/components/Timeline.tsx
index 720e4b06..d1f263ca 100644
--- a/site/src/cut/components/Timeline.tsx
+++ b/site/src/cut/components/Timeline.tsx
@@ -45,6 +45,7 @@ import {
import { originalSettings, type ExportDoc } from "@/cut/lib/exportClient";
import { useExports } from "@/cut/lib/exportStore";
import { isDragActive, startDrag, subscribeDragActive } from "@/cut/lib/drag";
+import { shortcutDecline } from "@/cut/lib/shortcutGate";
import { additiveClick } from "@/cut/lib/hostKeys";
import { CLIP_GAP, laneDragFor, laneDragParts, startLaneMove, startLaneTrim, type LaneDrag, type LaneKind } from "@/cut/lib/laneTracks";
import { downloadMedia, ensurePeaks, importImage, importStockMusic, importStockVideo, peekEdgeFrame, requestEdgeFrame, revealMedia, stripFailedFor, subscribeStripStatus } from "@/cut/lib/media";
@@ -1530,16 +1531,16 @@ export function Timeline() {
// Timeline-scoped keys: = / - zoom around the playhead, Home/End jump.
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
- const target = e.target as HTMLElement;
- if (
- target.tagName === "INPUT" ||
- target.tagName === "TEXTAREA" ||
- target.tagName === "SELECT" ||
- target.isContentEditable ||
- document.querySelector('[data-slot="dialog-content"]')
- )
- return;
+ // The editor's rule decides, plus one of this row's own: Home and End
+ // belong to a slider or a scrub bar that holds the keyboard.
+ const target = e.target instanceof HTMLElement ? e.target : null;
const s = useEditor.getState();
+ if (shortcutDecline(e, { exportOpen: s.exportOpen }) || target?.tagName === "INPUT") return;
+ // All four are bare keys. Held with a modifier they are the window's own
+ // — ctrl+- and ctrl+= zoom the page, ctrl+Home and ctrl+End jump to its
+ // ends — and answering those here would move two things at once.
+ const bare = !e.metaKey && !e.ctrlKey && !e.altKey;
+ if (!bare) return;
if (e.key === "=" || e.key === "+") {
e.preventDefault();
zoomTo(s.pxPerSec * 1.3);
diff --git a/site/src/cut/lib/perfTrace.ts b/site/src/cut/lib/perfTrace.ts
index 2440e860..690ffd20 100644
--- a/site/src/cut/lib/perfTrace.ts
+++ b/site/src/cut/lib/perfTrace.ts
@@ -10,6 +10,7 @@ import {
type MemoryUsage,
} from "./memoryBudget";
import { logPerfRecord, notePerfTrouble, perfUploadReason, type PerfUploadReason } from "./perfLog";
+import { isTextEntry } from "./shortcutGate";
/**
* What the preview actually did, frame by frame.
@@ -960,17 +961,6 @@ function describeTarget(target: EventTarget | null): string {
return slots.length ? `${slots.join(">")} ${self}` : self;
}
-const isTextEntry = (target: EventTarget | null): boolean => {
- const el = target instanceof HTMLElement ? target : null;
- return (
- !!el &&
- (el.tagName === "TEXTAREA" ||
- el.isContentEditable ||
- (el.tagName === "INPUT" &&
- !["checkbox", "radio", "range", "button", "file"].includes((el as HTMLInputElement).type)))
- );
-};
-
function watchInputs(): () => void {
const onPointer = (e: PointerEvent) => {
lastInput = { at: performance.now(), what: `press ${describeTarget(e.target)}` };
diff --git a/site/src/cut/lib/shortcutGate.test.ts b/site/src/cut/lib/shortcutGate.test.ts
new file mode 100644
index 00000000..9fa8c875
--- /dev/null
+++ b/site/src/cut/lib/shortcutGate.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { isDeleteKey, tellingKey, textEntryOf, typingOf } from "./shortcutGate";
+
+const key = (k: string, code = "", mods: Partial<KeyboardEvent> = {}) =>
+ ({ key: k, code, metaKey: false, ctrlKey: false, altKey: false, shiftKey: false, ...mods }) as KeyboardEvent;
+
+describe("what holds a keystroke", () => {
+ test("text fields hold it, toggles and sliders do not", () => {
+ expect(typingOf({ tagName: "TEXTAREA" })).toBe(true);
+ expect(typingOf({ tagName: "DIV", isContentEditable: true })).toBe(true);
+ expect(typingOf({ tagName: "INPUT", type: "text" })).toBe(true);
+ expect(typingOf({ tagName: "INPUT", type: "range" })).toBe(false);
+ expect(typingOf({ tagName: "INPUT", type: "checkbox" })).toBe(false);
+ expect(typingOf({ tagName: "DIV" })).toBe(false);
+ });
+
+ test("a select keeps the keys and lets the focus go", () => {
+ // The arrows pick its value, so the shortcuts stand aside; picking is over
+ // the moment it is picked, so an import may take the keyboard back.
+ expect(textEntryOf({ tagName: "SELECT" })).toBe(true);
+ expect(typingOf({ tagName: "SELECT" })).toBe(false);
+ });
+});
+
+describe("the delete keystroke", () => {
+ test("backspace and delete both clear the selection", () => {
+ expect(isDeleteKey(key("Backspace"))).toBe(true);
+ expect(isDeleteKey(key("Delete"))).toBe(true);
+ });
+
+ test("a numeric pad's Delete key counts, Num Lock either way", () => {
+ // Num Lock off sends the name, on sends the decimal point; the keycap
+ // says Delete for both.
+ expect(isDeleteKey(key("Delete", "NumpadDecimal"))).toBe(true);
+ expect(isDeleteKey(key(".", "NumpadDecimal"))).toBe(true);
+ });
+
+ test("a decimal point typed anywhere else is a decimal point", () => {
+ expect(isDeleteKey(key(".", "Period"))).toBe(false);
+ });
+
+ test("held with a modifier the numpad chord belongs to the browser", () => {
+ expect(isDeleteKey(key(".", "NumpadDecimal", { metaKey: true }))).toBe(false);
+ expect(isDeleteKey(key(".", "NumpadDecimal", { ctrlKey: true, altKey: true }))).toBe(false);
+ });
+});
+
+describe("what a decline is worth reporting", () => {
+ test("only the chords the editor binds, which no typing holds", () => {
+ expect(tellingKey(key("b", "KeyB", { ctrlKey: true }))).toBe(true);
+ expect(tellingKey(key("j", "KeyJ", { metaKey: true }))).toBe(true);
+ expect(tellingKey(key("b", "KeyB"))).toBe(false);
+ expect(tellingKey(key("Delete"))).toBe(false);
+ expect(tellingKey(key("Backspace"))).toBe(false);
+ expect(tellingKey(key(" ", "Space"))).toBe(false);
+ });
+
+ test("AltGr is not a chord — it is how a Brazilian layout types", () => {
+ expect(tellingKey(key("b", "KeyB", { ctrlKey: true, altKey: true }))).toBe(false);
+ });
+});
diff --git a/site/src/cut/lib/shortcutGate.ts b/site/src/cut/lib/shortcutGate.ts
new file mode 100644
index 00000000..460c209b
--- /dev/null
+++ b/site/src/cut/lib/shortcutGate.ts
@@ -0,0 +1,158 @@
+"use client";
+
+import { track } from "@/lib/analytics";
+
+/**
+ * Who a keystroke belongs to.
+ *
+ * The editor is played from the keyboard — space plays, ⌫ deletes, ⌘B cuts —
+ * and every one of those keys is also a key someone types with. So the
+ * shortcut layer stands aside whenever a text field holds the keystroke, a
+ * dialog is on top, or the view refuses edits. Each of those is a silent
+ * return, and a keyboard that has quietly stopped working leaves nothing
+ * behind to read. This module is the one place that decides, and the one place
+ * that says so out loud.
+ */
+
+/** Why the editor left a keystroke alone. */
+export type ShortcutDecline = "typing" | "dialog" | "read-only";
+
+/** The part of an element that decides whether keys belong to it. */
+export interface Keyed {
+ tagName: string;
+ type?: string;
+ isContentEditable?: boolean;
+}
+
+/** Input types that hold no text, so a key over one is the editor's. */
+const NON_TEXT_INPUTS = ["checkbox", "radio", "range", "button", "file"];
+
+/** Whether someone is mid-sentence in this element. */
+export const typingOf = (el: Keyed): boolean =>
+ el.tagName === "TEXTAREA" ||
+ el.isContentEditable === true ||
+ (el.tagName === "INPUT" && !NON_TEXT_INPUTS.includes(el.type ?? ""));
+
+/** Whether the editor's keys belong to this element: typing, and a native
+ * select besides — the arrows pick its value. */
+export const textEntryOf = (el: Keyed): boolean => el.tagName === "SELECT" || typingOf(el);
+
+const keyed = (el: EventTarget | null): Keyed | null =>
+ el instanceof HTMLElement
+ ? {
+ tagName: el.tagName,
+ type: (el as HTMLInputElement).type,
+ isContentEditable: el.isContentEditable,
+ }
+ : null;
+
+/** Whether this element holds the keystroke. */
+export function isTextEntry(el: EventTarget | null): boolean {
+ const k = keyed(el);
+ return k !== null && textEntryOf(k);
+}
+
+/** Whether a sentence is being written here, so moving the focus away would
+ * interrupt it. A select is done being picked the moment it is picked. */
+export function isTyping(el: EventTarget | null): boolean {
+ const k = keyed(el);
+ return k !== null && typingOf(k);
+}
+
+/** Whether a paste belongs to this element. Broader than the keys: a control
+ * of any kind keeps its own paste. */
+export const isPasteTarget = (el: EventTarget | null): boolean =>
+ el instanceof HTMLElement &&
+ (el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.isContentEditable);
+
+/**
+ * Whether a dialog stands over the editor, which owns the keyboard while it is
+ * open. A popup keeps its element through its exit animation, and on a machine
+ * dropping frames that runs long; Base UI marks those `data-closed`, and a
+ * dialog on its way out has no claim on the keys.
+ */
+export function dialogOnTop(): boolean {
+ for (const el of document.querySelectorAll('[data-slot="dialog-content"]')) {
+ if (!el.hasAttribute("data-closed")) return true;
+ }
+ return false;
+}
+
+/** Null when the keystroke is the editor's, otherwise who took it. */
+export function shortcutDecline(
+ e: KeyboardEvent,
+ opts: { exportOpen?: boolean } = {}
+): ShortcutDecline | null {
+ if (isTextEntry(e.target)) return "typing";
+ if (opts.exportOpen || dialogOnTop()) return "dialog";
+ return null;
+}
+
+/**
+ * Whether this keystroke asks for the selection to go.
+ *
+ * A laptop numeric pad labels its own decimal key Delete and sends `.` for it
+ * while Num Lock is on. It counts on its own: with a modifier down the chord
+ * belongs to the browser or the OS.
+ */
+export const isDeleteKey = (e: KeyboardEvent): boolean =>
+ e.key === "Backspace" ||
+ e.key === "Delete" ||
+ (e.code === "NumpadDecimal" && !e.metaKey && !e.ctrlKey && !e.altKey && !e.shiftKey);
+
+/**
+ * Keys worth reporting a decline for. A chord the editor binds — ⌘B, ⌘J, ⌘G —
+ * is one no text field wants, so a run of them going nowhere is the editor's
+ * keyboard being held. Every bare key stays out: ⌫, Delete, space, the arrows
+ * and the letters are what typing is made of, and a field turns them down all
+ * day by design.
+ */
+const TELLING_MOD = "bjg";
+
+export const tellingKey = (e: KeyboardEvent): boolean => {
+ const k = e.key.toLowerCase();
+ return (e.metaKey || e.ctrlKey) && !e.altKey && k.length === 1 && TELLING_MOD.includes(k);
+};
+
+// A run of declines. One chord turned down is nothing; a run of them with not
+// one keystroke reaching the editor in between is a keyboard someone is
+// pressing at a surface that has stopped listening. The run resets the moment
+// a keystroke gets through, so a page that goes deaf halfway still reports.
+let seen = 0;
+let declined = 0;
+let said = false;
+/** Declines in a row before the keyboard is called stuck: few enough that the
+ * person is still at it wondering why nothing happens, enough that one chord
+ * over a panel stays quiet. */
+export const STUCK_AFTER = 3;
+
+/** A keydown reached the editor's handler. */
+export function noteKey(): void {
+ seen++;
+}
+
+/** A keystroke got through to the editor's shortcuts. */
+export function shortcutReached(): void {
+ declined = 0;
+}
+
+/**
+ * Record that the editor turned a bound chord down, and report a run of them
+ * once — the whole page load's one word on a keyboard going nowhere.
+ */
+export function reportDecline(reason: ShortcutDecline, e: KeyboardEvent): void {
+ // A share view refuses edits by design; its declines are the feature.
+ if (reason === "read-only" || !tellingKey(e)) return;
+ declined++;
+ if (said || declined < STUCK_AFTER) return;
+ said = true;
+ const el = e.target instanceof HTMLElement ? e.target : null;
+ track("cut_keyboard_blocked", {
+ reason,
+ seen,
+ declined,
+ key: `mod+${e.key.toLowerCase()}`,
+ tag: el?.tagName ?? "",
+ slot: el?.dataset.slot ?? "",
+ });
+}
diff --git a/site/src/lib/analytics.ts b/site/src/lib/analytics.ts
index 7a4419b7..d865a871 100644
--- a/site/src/lib/analytics.ts
+++ b/site/src/lib/analytics.ts
@@ -3,6 +3,7 @@ import { useEffect } from "react";
import type { PerfLogBatch } from "@/cut/lib/perfLog";
import type { MainThreadSample, PerfSample } from "@/cut/lib/perfTrace";
+import type { ShortcutDecline } from "@/cut/lib/shortcutGate";
import type {
OnboardingRun,
ReferralSource,
@@ -42,6 +43,16 @@ export type AnalyticsEvents = {
// The blocked frames themselves, kept locally and sent at idle, on the page
// hiding, and on the next open — see perfLog for the record.
cut_perf_log: PerfLogBatch;
+ // A page load where a chord the editor binds went nowhere three times over,
+ // held by a text field or a dialog — see shortcutGate. One report per page.
+ cut_keyboard_blocked: {
+ reason: ShortcutDecline;
+ seen: number;
+ declined: number;
+ key: string;
+ tag: string;
+ slot: string;
+ };
// Billing (settings).
pro_checkout_started: void;
billing_portal_opened: void;