feat: keystroke overlay (record keys + built-in "Keystrokes" extension)

electron-builder.json5

@@ -36,6 +36,10 @@
     {
       "from": "public/wallpapers",
       "to": "assets/wallpapers"
+    },
+    {
+      "from": "public/builtin-extensions",
+      "to": "builtin-extensions"
     }
   ],
   "publish": [

electron/electron-env.d.ts

@@ -581,6 +581,11 @@ interface Window {
 			message?: string;
 			error?: string;
 		}>;
+		getKeystrokeTelemetry: (videoPath?: string) => Promise<{
+			success: boolean;
+			events: Array<{ timeMs: number; key: string; modifiers: string[] }>;
+			error?: string;
+		}>;
 		getSystemCursorAssets: () => Promise<{
 			success: boolean;
 			cursors: Record<string, SystemCursorAsset>;

electron/ipc/constants.ts

@@ -29,3 +29,4 @@ export const COMPANION_AUDIO_LAYOUTS = [
 export const CURSOR_TELEMETRY_VERSION = 2;
 export const CURSOR_SAMPLE_INTERVAL_MS = 33;
 export const MAX_CURSOR_SAMPLES = 60 * 60 * 30; // 1 hour @ 30Hz
+export const KEYSTROKE_TELEMETRY_VERSION = 1;

electron/ipc/cursor/interaction.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
-import type { HookMouseEvent, UiohookLike, UiohookModuleNamespace, CursorInteractionType } from "../types";
+import type { HookKeyboardEvent, HookMouseEvent, UiohookLike, UiohookModuleNamespace, CursorInteractionType } from "../types";
 import {
 	isCursorCaptureActive,
 	interactionCaptureCleanup,
@@ -18,8 +18,35 @@ import {
 	getHookCursorScreenPoint,
 	isCursorCapturePaused,
 	pushCursorSample,
+	pushKeystroke,
 } from "./telemetry";
 
+// Maps uiohook-napi keycodes to Web KeyboardEvent.key values. Values match
+// uiohook-napi's UiohookKey constants. Modifier keys are intentionally absent —
+// modifiers come from the event's shiftKey/ctrlKey/altKey/metaKey booleans, and
+// bare modifier presses map to null here so they aren't emitted on their own.
+const KEYCODE_MAP: Record<number, string> = {
+	1: "Escape", 2: "1", 3: "2", 4: "3", 5: "4", 6: "5", 7: "6", 8: "7", 9: "8", 10: "9",
+	11: "0", 12: "-", 13: "=", 14: "Backspace", 15: "Tab",
+	16: "q", 17: "w", 18: "e", 19: "r", 20: "t", 21: "y", 22: "u", 23: "i", 24: "o", 25: "p",
+	26: "[", 27: "]", 28: "Enter",
+	30: "a", 31: "s", 32: "d", 33: "f", 34: "g", 35: "h", 36: "j", 37: "k", 38: "l",
+	39: ";", 40: "'", 41: "`", 43: "\\",
+	44: "z", 45: "x", 46: "c", 47: "v", 48: "b", 49: "n", 50: "m",
+	51: ",", 52: ".", 53: "/", 57: " ",
+	58: "CapsLock",
+	59: "F1", 60: "F2", 61: "F3", 62: "F4", 63: "F5", 64: "F6",
+	65: "F7", 66: "F8", 67: "F9", 68: "F10", 87: "F11", 88: "F12",
+	71: "7", 72: "8", 73: "9", 75: "4", 76: "5", 77: "6", 79: "1", 80: "2", 81: "3", 82: "0",
+	3655: "Home", 3657: "PageUp", 3663: "End", 3665: "PageDown", 3666: "Insert", 3667: "Delete",
+	57416: "ArrowUp", 57419: "ArrowLeft", 57421: "ArrowRight", 57424: "ArrowDown",
+};
+
+function keycodeToKey(keycode: number | undefined): string | null {
+	if (keycode === undefined) return null;
+	return KEYCODE_MAP[keycode] ?? null;
+}
+
 const nodeRequire = createRequire(import.meta.url);
 
 export function normalizeHookMouseButton(rawButton: unknown): 1 | 2 | 3 {
@@ -271,8 +298,22 @@ export async function startInteractionCapture() {
 			setLinuxCursorScreenPoint({ x: point.x, y: point.y, updatedAt: Date.now() });
 		};
 
+		const onKeyDown = (event: HookKeyboardEvent) => {
+			if (!isCursorCaptureActive || isCursorCapturePaused()) return;
+			const key = keycodeToKey(event.keycode);
+			if (!key) return; // bare modifiers map to null and are skipped
+			const modifiers: string[] = [];
+			if (event.ctrlKey) modifiers.push("Control");
+			if (event.altKey) modifiers.push("Alt");
+			if (event.shiftKey) modifiers.push("Shift");
+			if (event.metaKey) modifiers.push("Meta");
+			const timeMs = getCursorCaptureElapsedMs();
+			pushKeystroke({ timeMs, key, modifiers });
+		};
+
 		hook.on("mousedown", onMouseDown);
 		hook.on("mouseup", onMouseUp);
+		hook.on("keydown", onKeyDown);
 		if (process.platform === "linux") {
 			hook.on("mousemove", onMouseMove);
 		}
@@ -282,12 +323,14 @@ export async function startInteractionCapture() {
 				if (typeof hook.off === "function") {
 					hook.off("mousedown", onMouseDown);
 					hook.off("mouseup", onMouseUp);
+					hook.off("keydown", onKeyDown);
 					if (process.platform === "linux") {
 						hook.off("mousemove", onMouseMove);
 					}
 				} else if (typeof hook.removeListener === "function") {
 					hook.removeListener("mousedown", onMouseDown);
 					hook.removeListener("mouseup", onMouseUp);
+					hook.removeListener("keydown", onKeyDown);
 					if (process.platform === "linux") {
 						hook.removeListener("mousemove", onMouseMove);
 					}

electron/ipc/cursor/telemetry.ts

@@ -326,3 +326,60 @@ export function startCursorSampling() {
 export { CURSOR_SAMPLE_INTERVAL_MS } from "../constants";
 // Re-export for consumers that use it from this module
 export { getTelemetryPathForVideo } from "../utils";
+
+// ── Keystroke telemetry ───────────────────────────────────────────────────────
+
+import { KEYSTROKE_TELEMETRY_VERSION } from "../constants";
+import { activeKeystrokeEvents, setActiveKeystrokeEvents } from "../state";
+import type { KeystrokeEvent } from "../types";
+import { getKeystrokePathForVideo } from "../utils";
+
+export function pushKeystroke(event: KeystrokeEvent): void {
+	setActiveKeystrokeEvents([...activeKeystrokeEvents, event]);
+}
+
+export function getActiveKeystrokes(): KeystrokeEvent[] {
+	return activeKeystrokeEvents;
+}
+
+export async function saveKeystrokeTelemetry(videoPath: string): Promise<void> {
+	const events = activeKeystrokeEvents;
+	const sidecarPath = getKeystrokePathForVideo(videoPath);
+
+	if (events.length === 0) {
+		await fs.rm(sidecarPath, { force: true });
+		return;
+	}
+
+	await fs.writeFile(
+		sidecarPath,
+		JSON.stringify({ version: KEYSTROKE_TELEMETRY_VERSION, events }, null, 2),
+		"utf-8",
+	);
+}
+
+export async function loadKeystrokeTelemetry(videoPath: string): Promise<KeystrokeEvent[]> {
+	const sidecarPath = getKeystrokePathForVideo(videoPath);
+
+	try {
+		const raw = await fs.readFile(sidecarPath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!parsed || parsed.version !== KEYSTROKE_TELEMETRY_VERSION || !Array.isArray(parsed.events)) {
+			return [];
+		}
+		return parsed.events.filter(
+			(e: unknown): e is KeystrokeEvent =>
+				e !== null &&
+				typeof e === "object" &&
+				typeof (e as KeystrokeEvent).timeMs === "number" &&
+				typeof (e as KeystrokeEvent).key === "string" &&
+				Array.isArray((e as KeystrokeEvent).modifiers),
+		);
+	} catch {
+		return [];
+	}
+}
+
+export function resetKeystrokeTelemetry(): void {
+	setActiveKeystrokeEvents([]);
+}

electron/ipc/recording/mac.ts

@@ -3,6 +3,8 @@ import fs from "node:fs/promises";
 import { BrowserWindow } from "electron";
 import {
 	persistPendingCursorTelemetry,
+	resetKeystrokeTelemetry,
+	saveKeystrokeTelemetry,
 	snapshotCursorTelemetryForPersistence,
 } from "../cursor/telemetry";
 import {
@@ -227,6 +229,12 @@ export async function finalizeStoredVideo(videoPath: string) {
 	} catch (error) {
 		console.warn("[mac-stop] Failed to persist cursor telemetry:", error);
 	}
+	try {
+		await saveKeystrokeTelemetry(videoPath);
+	} catch (error) {
+		console.warn("[mac-stop] Failed to persist keystroke telemetry:", error);
+	}
+	resetKeystrokeTelemetry();
 	if (isAutoRecordingPath(videoPath)) {
 		await pruneAutoRecordings([videoPath]);
 	}

electron/ipc/register/recording.ts

@@ -29,6 +29,9 @@ import {
 	startCursorSampling,
 	stopCursorCapture,
 	writeCursorTelemetry,
+	loadKeystrokeTelemetry,
+	saveKeystrokeTelemetry,
+	resetKeystrokeTelemetry,
 } from "../cursor/telemetry";
 import { getFfmpegBinaryPath } from "../ffmpeg/binary";
 import {
@@ -997,6 +1000,12 @@ export function registerRecordingHandlers(
 				} catch (error) {
 					console.warn("Failed to persist cursor telemetry during native stop:", error);
 				}
+				try {
+					await saveKeystrokeTelemetry(finalVideoPath);
+				} catch (error) {
+					console.warn("Failed to persist keystroke telemetry during native stop:", error);
+				}
+				resetKeystrokeTelemetry();
 
 				return { success: true, path: finalVideoPath };
 			} catch (error) {
@@ -1893,6 +1902,20 @@ export function registerRecordingHandlers(
 		}
 	});
 
+	ipcMain.handle("get-keystroke-telemetry", async (_, videoPath?: string) => {
+		const targetVideoPath = normalizeVideoSourcePath(videoPath ?? currentVideoPath);
+		if (!targetVideoPath) {
+			return { success: true, events: [] };
+		}
+		try {
+			const events = await loadKeystrokeTelemetry(targetVideoPath);
+			return { success: true, events };
+		} catch (error) {
+			console.error("Failed to load keystroke telemetry:", error);
+			return { success: false, events: [], error: String(error) };
+		}
+	});
+
 	ipcMain.handle(
 		"set-cursor-telemetry",
 		async (_, videoPath: string | undefined, samples: CursorTelemetryPoint[]) => {

electron/ipc/state.ts

@@ -3,6 +3,7 @@ import type {
 	CursorInteractionType,
 	CursorTelemetryPoint,
 	CursorVisualType,
+	KeystrokeEvent,
 	NativeCaptureDiagnostics,
 	RecordingSessionData,
 	SelectedSource,
@@ -291,3 +292,10 @@ export function setCachedNativeVideoEncoder(
 export function setNativeHelperMigrationPromise(v: Promise<void> | null) {
 	nativeHelperMigrationPromise = v;
 }
+
+// ── Keystroke telemetry ───────────────────────────────────────────────────────
+export let activeKeystrokeEvents: KeystrokeEvent[] = [];
+
+export function setActiveKeystrokeEvents(v: KeystrokeEvent[]) {
+	activeKeystrokeEvents = v;
+}

electron/ipc/types.ts

@@ -141,10 +141,30 @@ export type HookMouseEvent = {
 
 export type HookEventListener = (event: HookMouseEvent) => void;
 
+export type HookKeyboardEvent = {
+	keycode?: number;
+	rawcode?: number;
+	type?: "keydown" | "keyup";
+	shiftKey?: boolean;
+	ctrlKey?: boolean;
+	altKey?: boolean;
+	metaKey?: boolean;
+};
+
+export type HookKeyboardEventName = "keydown" | "keyup";
+
+export type HookKeyboardListener = (event: HookKeyboardEvent) => void;
+
+export type KeystrokeEvent = {
+	timeMs: number;
+	key: string;
+	modifiers: string[];
+};
+
 export type UiohookLike = {
-	on: (eventName: HookEventName, listener: HookEventListener) => void;
-	off?: (eventName: HookEventName, listener: HookEventListener) => void;
-	removeListener?: (eventName: HookEventName, listener: HookEventListener) => void;
+	on: (eventName: HookEventName | HookKeyboardEventName, listener: HookEventListener | HookKeyboardListener) => void;
+	off?: (eventName: HookEventName | HookKeyboardEventName, listener: HookEventListener | HookKeyboardListener) => void;
+	removeListener?: (eventName: HookEventName | HookKeyboardEventName, listener: HookEventListener | HookKeyboardListener) => void;
 	start: () => void;
 	stop?: () => void;
 };

electron/ipc/utils.ts

@@ -67,6 +67,10 @@ export function getTelemetryPathForVideo(videoPath: string) {
 	return `${videoPath}.cursor.json`;
 }
 
+export function getKeystrokePathForVideo(videoPath: string) {
+	return `${videoPath}.keys.json`;
+}
+
 export function isAutoRecordingPath(filePath: string) {
 	return path.basename(filePath).startsWith(AUTO_RECORDING_PREFIX);
 }

electron/preload.ts

@@ -584,6 +584,9 @@ contextBridge.exposeInMainWorld("electronAPI", {
 	setCursorTelemetry: (videoPath: string | undefined, samples: CursorTelemetryPoint[]) => {
 		return ipcRenderer.invoke("set-cursor-telemetry", videoPath, samples);
 	},
+	getKeystrokeTelemetry: (videoPath?: string) => {
+		return ipcRenderer.invoke("get-keystroke-telemetry", videoPath);
+	},
 	getSystemCursorAssets: () => {
 		return ipcRenderer.invoke("get-system-cursor-assets");
 	},