diff --git a/de_shell/js/main/index.ts b/de_shell/js/main/index.ts index 9c370ad..b27f12c 100644 --- a/de_shell/js/main/index.ts +++ b/de_shell/js/main/index.ts @@ -64,6 +64,7 @@ export { } from './updaterErrors' export { registerUpdaterIpc, registerProblemReportIpc } from './shellIpc' +export { registerScreenRecorder } from './screenRecorder' export { runEnvSetup, EnvSetupQuitError } from './envSetup' export type { EnvSetupAnswer, EnvSetupWireMessage } from './envSetup' diff --git a/de_shell/js/main/screenRecorder.ts b/de_shell/js/main/screenRecorder.ts new file mode 100644 index 0000000..4804769 --- /dev/null +++ b/de_shell/js/main/screenRecorder.ts @@ -0,0 +1,43 @@ +/** + * screenRecorder.ts — capturing the app's own window to a video file (a demo, a + * bug report, a scrub someone else needs to see), registered with one call. + * + * What is captured is the window's own web contents, not a display: the + * display-media request is answered with the asking frame, so no source picker + * appears, nothing outside the app can end up in the file, and macOS never asks + * for Screen Recording permission. The trade-off is that anything the OS draws + * on top — a native menu, a file dialog — is not in the recording. + * + * The renderer half is `` from @de/shell-renderer, over the + * preload bridge's `recorder`. + */ +import { BrowserWindow, app, dialog, ipcMain } from 'electron' +import { appendFile, rm, writeFile } from 'fs/promises' +import { join } from 'path' + +import { channel, shellConfig } from './config' +import { bindRecorderIpc, recordingName } from './screenRecorderCore' + +/** Let `win` record itself, and wire the save-and-append channels. Call once + * the window exists. Safe to call again for a new window: the handlers are + * replaced, not stacked. */ +export function registerScreenRecorder(win: BrowserWindow): void { + win.webContents.session.setDisplayMediaRequestHandler((request, callback) => + callback({ video: request.frame ?? win.webContents.mainFrame }), + ) + + bindRecorderIpc(ipcMain, { + channel, + choosePath: async (format, sender) => { + const parent = BrowserWindow.fromWebContents(sender as Electron.WebContents) ?? win + const result = await dialog.showSaveDialog(parent, { + defaultPath: join(app.getPath('videos'), recordingName(shellConfig().appId, new Date(), format)), + filters: [{ name: 'Video', extensions: [format] }], + }) + return result.canceled || !result.filePath ? null : result.filePath + }, + create: (path) => writeFile(path, new Uint8Array(0)), + append: (path, bytes) => appendFile(path, bytes), + remove: (path) => rm(path, { force: true }), + }) +} diff --git a/de_shell/js/main/screenRecorderCore.test.ts b/de_shell/js/main/screenRecorderCore.test.ts new file mode 100644 index 0000000..69f47d8 --- /dev/null +++ b/de_shell/js/main/screenRecorderCore.test.ts @@ -0,0 +1,108 @@ +/** + * screenRecorderCore.test.ts — channel names, input validation, chunk order and + * the empty-file cleanup of the screen recorder's IPC, against a fake ipcMain. + */ +import { test } from 'node:test' +import assert from 'node:assert/strict' + +import { bindRecorderIpc, recordingName, RECORDER_CHANNELS } from './screenRecorderCore.ts' +import type { RecorderDeps } from './screenRecorderCore.ts' +import type { IpcLike } from './shellIpcCore.ts' + +function fakeIpc() { + const handlers = new Map unknown>() + const ipc: IpcLike = { + handle(ch, fn) { + if (handlers.has(ch)) throw new Error(`second handler for ${ch}`) // Electron does this + handlers.set(ch, fn) + }, + on() { throw new Error('the recorder only uses invoke') }, + removeHandler(ch) { handlers.delete(ch) }, + removeAllListeners() {}, + } + const invoke = (name: string, ...a: unknown[]) => handlers.get(`app:${name}`)!({ sender: 'wc' }, ...a) + return { ipc, handlers, invoke } +} + +function fakeDisk(chosen: string | null = 'C:/v/app.mp4') { + const files = new Map() + const asked: unknown[] = [] + const deps: RecorderDeps = { + channel: n => `app:${n}`, + choosePath: async (format, sender) => { asked.push([format, sender]); return chosen }, + create: async p => { files.set(p, []) }, + append: async (p, b) => { files.get(p)!.push(...b) }, + remove: async p => { files.delete(p) }, + } + return { deps, files, asked } +} + +test('the channels are the ones the preload spells', () => { + const { ipc, handlers } = fakeIpc() + bindRecorderIpc(ipc, fakeDisk().deps) + assert.deepEqual([...handlers.keys()].sort(), + Object.values(RECORDER_CHANNELS).map(n => `app:${n}`).sort()) +}) + +test('registering twice replaces the handlers instead of throwing', () => { + const { ipc } = fakeIpc() + bindRecorderIpc(ipc, fakeDisk().deps) + assert.doesNotThrow(() => bindRecorderIpc(ipc, fakeDisk().deps)) +}) + +test('chunks land in the named file, in order, and stop counts them', async () => { + const { ipc, invoke } = fakeIpc() + const disk = fakeDisk() + bindRecorderIpc(ipc, disk.deps) + assert.equal(await invoke(RECORDER_CHANNELS.start, 'mp4'), 'C:/v/app.mp4') + assert.deepEqual(disk.asked, [['mp4', 'wc']]) + await invoke(RECORDER_CHANNELS.chunk, new Uint8Array([1, 2])) + await invoke(RECORDER_CHANNELS.chunk, new Uint8Array([3])) + assert.equal(await invoke(RECORDER_CHANNELS.stop), 3) + assert.deepEqual(disk.files.get('C:/v/app.mp4'), [1, 2, 3]) + // Closed: a late chunk is dropped rather than appended. + await invoke(RECORDER_CHANNELS.chunk, new Uint8Array([9])) + assert.deepEqual(disk.files.get('C:/v/app.mp4'), [1, 2, 3]) +}) + +test('an unknown format is refused without asking the user', async () => { + const { ipc, invoke } = fakeIpc() + const disk = fakeDisk() + bindRecorderIpc(ipc, disk.deps) + assert.equal(await invoke(RECORDER_CHANNELS.start, '../../evil.exe'), null) + assert.deepEqual(disk.asked, []) +}) + +test('a cancelled dialog opens nothing, and chunks are dropped', async () => { + const { ipc, invoke } = fakeIpc() + const disk = fakeDisk(null) + bindRecorderIpc(ipc, disk.deps) + assert.equal(await invoke(RECORDER_CHANNELS.start, 'webm'), null) + await invoke(RECORDER_CHANNELS.chunk, new Uint8Array([1])) + assert.equal(disk.files.size, 0) +}) + +test('a recording that never got a byte leaves no empty file', async () => { + const { ipc, invoke } = fakeIpc() + const disk = fakeDisk() + bindRecorderIpc(ipc, disk.deps) + await invoke(RECORDER_CHANNELS.start, 'webm') + assert.ok(disk.files.has('C:/v/app.mp4')) + assert.equal(await invoke(RECORDER_CHANNELS.stop), 0) + assert.equal(disk.files.size, 0) +}) + +test('a chunk that is not bytes is ignored', async () => { + const { ipc, invoke } = fakeIpc() + const disk = fakeDisk() + bindRecorderIpc(ipc, disk.deps) + await invoke(RECORDER_CHANNELS.start, 'mp4') + await invoke(RECORDER_CHANNELS.chunk, 'not bytes') + await invoke(RECORDER_CHANNELS.chunk, [1, 2]) + assert.deepEqual(disk.files.get('C:/v/app.mp4'), []) +}) + +test('the file name is the app, the local time and the format', () => { + assert.equal(recordingName('autopilot', new Date(2026, 10, 5, 9, 3, 7), 'mp4'), + 'autopilot-2026-11-05-09-03-07.mp4') +}) diff --git a/de_shell/js/main/screenRecorderCore.ts b/de_shell/js/main/screenRecorderCore.ts new file mode 100644 index 0000000..f0f9c4e --- /dev/null +++ b/de_shell/js/main/screenRecorderCore.ts @@ -0,0 +1,84 @@ +/** + * screenRecorderCore.ts — the screen recorder's IPC with the Electron and file + * system pieces injected, so it runs under node --test. screenRecorder.ts binds + * it to the real `ipcMain`, the save dialog and the disk. + * + * The file is named BEFORE the recording starts and each chunk is appended as + * it arrives: a few minutes of video is hundreds of MB and must never cross IPC + * as one message. The path lives here, in main, rather than coming from the + * renderer with each chunk, so the bytes can only ever land in the file the + * user named in the dialog. + */ +import type { IpcLike } from './shellIpcCore' + +/** Channel suffixes, joined to `:` by the caller. preload/index.ts + * spells the same names; screenRecorderCore.test.ts pins them. */ +export const RECORDER_CHANNELS = { + start: 'record-start', + chunk: 'record-chunk', + stop: 'record-stop', +} as const + +export type RecordingFormat = 'mp4' | 'webm' + +export interface RecorderDeps { + channel: (name: string) => string + /** Ask the user where to save; null when they cancel. `sender` is the + * asking webContents, so the dialog can be parented to its window. */ + choosePath: (format: RecordingFormat, sender: unknown) => Promise + /** Create (or truncate) the file. */ + create: (path: string) => Promise + append: (path: string, bytes: Uint8Array) => Promise + remove: (path: string) => Promise +} + +/** `-2026-11-15-14-03-22.`, local time, safe on every OS. */ +export function recordingName(appId: string, when: Date, format: RecordingFormat): string { + const two = (n: number) => String(n).padStart(2, '0') + const stamp = [ + when.getFullYear(), two(when.getMonth() + 1), two(when.getDate()), + two(when.getHours()), two(when.getMinutes()), two(when.getSeconds()), + ].join('-') + return `${appId}-${stamp}.${format}` +} + +function replaceHandle(ipc: IpcLike, ch: string, fn: (e: unknown, ...a: any[]) => unknown) { + ipc.removeHandler(ch) + ipc.handle(ch, fn) +} + +export function bindRecorderIpc(ipc: IpcLike, d: RecorderDeps): void { + let path: string | null = null + let written = 0 + + // RETURNS the path, or null when the user cancelled. + replaceHandle(ipc, d.channel(RECORDER_CHANNELS.start), async (event, format: unknown) => { + // The renderer is untrusted input: anything but the two containers is refused. + if (format !== 'mp4' && format !== 'webm') return null + const chosen = await d.choosePath(format, (event as { sender?: unknown } | null)?.sender) + if (!chosen) return null + await d.create(chosen) + path = chosen + written = 0 + return chosen + }) + + // Awaited by the renderer, which chains the chunks, so the file is written in + // recording order. A chunk with no recording open is dropped, not written. + replaceHandle(ipc, d.channel(RECORDER_CHANNELS.chunk), async (_e, bytes: unknown) => { + if (!path || !(bytes instanceof Uint8Array) || !bytes.length) return + await d.append(path, bytes) + written += bytes.length + }) + + // Closes the recording. One that never got a byte (the capture failed after + // the file was named) leaves no empty file behind. RETURNS the bytes written. + replaceHandle(ipc, d.channel(RECORDER_CHANNELS.stop), async () => { + const closing = path + const bytes = written + path = null + written = 0 + if (closing && bytes === 0) await d.remove(closing) + return bytes + }) +} diff --git a/de_shell/js/preload/index.ts b/de_shell/js/preload/index.ts index 11d2622..269e608 100644 --- a/de_shell/js/preload/index.ts +++ b/de_shell/js/preload/index.ts @@ -161,6 +161,19 @@ export function createShellBridge(opts: ShellBridgeOptions) { ipcRenderer.invoke(channel('report-submit'), input), }, + /** Recording the window to a video file. Needs `registerScreenRecorder(win)` + * in main; `` in the renderer drives it. */ + recorder: { + /** Name the file in a save dialog and open it. Resolves to its path, or + * null if the user cancelled. */ + start: (format: 'mp4' | 'webm'): Promise => + ipcRenderer.invoke(channel('record-start'), format), + /** Append one chunk; await it before sending the next, to keep order. */ + chunk: (bytes: Uint8Array): Promise => ipcRenderer.invoke(channel('record-chunk'), bytes), + /** Close the file. Resolves to the bytes written; a file that got none is removed. */ + stop: (): Promise => ipcRenderer.invoke(channel('record-stop')), + }, + /** First-run environment setup. The progress/error messages themselves * arrive as `{type: 'env_setup'}` on `onMessage` (route them with * `toShellAction`); this is only the answer path back to `runEnvSetup`. */ diff --git a/de_shell/js/renderer/ScreenRecorder.tsx b/de_shell/js/renderer/ScreenRecorder.tsx new file mode 100644 index 0000000..fe64eae --- /dev/null +++ b/de_shell/js/renderer/ScreenRecorder.tsx @@ -0,0 +1,129 @@ +/** + * ScreenRecorder.tsx — records the app's window to a video file, and shows a + * "● REC 0:42 — stop" pill while it does. + * + * Mount it once, near the root, with the preload bridge's `recorder`. Start + * and stop it with `toggleScreenRecording()` from a menu item's click handler, + * or by clicking the pill. It has to start from a real click: Chromium only + * grants `getDisplayMedia` with user activation, which a native menu item + * routed through the main process does not carry — so the entry point is an + * in-app menu. Main must have called `registerScreenRecorder(win)`, which is + * what makes the capture this window and nothing else, with no picker. + * + * Renders nothing when idle. + */ +import React, { useEffect, useRef, useState } from 'react' + +import type { RecorderApi } from './bridgeTypes' +import { + CHUNK_MS, TOGGLE_RECORDING_EVENT, fileName, pickRecordingType, recordingClock, +} from './screenRecorderModel' +import { colors, font } from './theme' + +/** Start a recording, or stop the one going. Call from a click handler. */ +export function toggleScreenRecording(): void { + window.dispatchEvent(new CustomEvent(TOGGLE_RECORDING_EVENT)) +} + +export interface ScreenRecorderProps { + recorder: RecorderApi + /** Where the pill sits; by default the middle of the title bar, out of the + * way of whatever is being demonstrated. */ + style?: React.CSSProperties +} + +export function ScreenRecorder({ recorder, style }: ScreenRecorderProps) { + const active = useRef<{ stop: () => void } | null>(null) + const [seconds, setSeconds] = useState(null) + const [note, setNote] = useState(null) + + useEffect(() => { + const start = async () => { + setNote(null) + const { mimeType, format } = pickRecordingType(t => MediaRecorder.isTypeSupported(t)) + const path = await recorder.start(format) + if (!path) return + let stream: MediaStream + try { + stream = await navigator.mediaDevices.getDisplayMedia({ video: { frameRate: 30 } }) + } catch (error) { + await recorder.stop() // removes the still-empty file + throw error + } + const media = new MediaRecorder(stream, { mimeType, videoBitsPerSecond: 8_000_000 }) + // Chained rather than fired and forgotten: chunks must reach the file in + // recording order, and awaiting each write is the backpressure too. + let written: Promise = Promise.resolve() + media.ondataavailable = (e) => { + if (!e.data.size) return + written = written.then(async () => recorder.chunk(new Uint8Array(await e.data.arrayBuffer()))) + } + media.onstop = async () => { + stream.getTracks().forEach(t => t.stop()) + try { + await written + const bytes = await recorder.stop() + setNote(bytes ? `Saved ${fileName(path)}` : 'Nothing was recorded') + } catch (error) { + await recorder.stop().catch(() => 0) + setNote(`Recording failed — ${(error as Error)?.message ?? error}`) + } + } + const stop = () => { + if (active.current?.stop !== stop) return + active.current = null + setSeconds(null) + if (media.state !== 'inactive') media.stop() + } + // The capture can end on its own (the window closed, the GPU reset). + stream.getVideoTracks().forEach(t => t.addEventListener('ended', stop)) + media.start(CHUNK_MS) + active.current = { stop } + setSeconds(0) + } + + const toggle = () => { + if (active.current) active.current.stop() + else start().catch(e => setNote(`Recording failed — ${(e as Error)?.message ?? e}`)) + } + window.addEventListener(TOGGLE_RECORDING_EVENT, toggle) + return () => { + window.removeEventListener(TOGGLE_RECORDING_EVENT, toggle) + active.current?.stop() + } + }, [recorder]) + + // One timeout per tick rather than an interval, so the clock can never + // outlive the recording it is counting. + useEffect(() => { + if (seconds === null) return + const id = setTimeout(() => setSeconds(seconds + 1), 1000) + return () => clearTimeout(id) + }, [seconds]) + + useEffect(() => { + if (!note) return + const id = setTimeout(() => setNote(null), 6000) + return () => clearTimeout(id) + }, [note]) + + if (seconds === null && !note) return null + return ( + + ) +} + +const S: Record = { + // no-drag so a title bar's drag region does not swallow the click. High, but + // below the 9000 band apps use for guided-tour overlays, which must never be + // covered. + pill: { + position: 'fixed', top: 8, left: '50%', transform: 'translateX(-50%)', zIndex: 8999, + background: colors.inset, color: colors.danger, border: `1px solid ${colors.danger}`, + borderRadius: 999, padding: '2px 10px', fontFamily: font, fontSize: 11, cursor: 'pointer', + WebkitAppRegion: 'no-drag', + } as React.CSSProperties, +} diff --git a/de_shell/js/renderer/bridgeTypes.ts b/de_shell/js/renderer/bridgeTypes.ts index 4b76f02..9db7710 100644 --- a/de_shell/js/renderer/bridgeTypes.ts +++ b/de_shell/js/renderer/bridgeTypes.ts @@ -38,6 +38,12 @@ export interface ReportApi { submit(input: { message: string; contact?: string }): Promise } +export interface RecorderApi { + start(format: 'mp4' | 'webm'): Promise + chunk(bytes: Uint8Array): Promise + stop(): Promise +} + export interface EnvSetupApi { answer(choice: 'retry' | 'use-wheelhouse' | 'quit'): void } diff --git a/de_shell/js/renderer/index.ts b/de_shell/js/renderer/index.ts index 35344e0..bdb5a35 100644 --- a/de_shell/js/renderer/index.ts +++ b/de_shell/js/renderer/index.ts @@ -46,10 +46,15 @@ export { ReportProblemDialog } from './ReportProblemDialog' export type { ReportProblemDialogProps } from './ReportProblemDialog' export { useUpdateStatus } from './useUpdateStatus.react' export type { UpdateSnapshot } from './useUpdateStatus.react' +export { ScreenRecorder, toggleScreenRecording } from './ScreenRecorder' +export type { ScreenRecorderProps } from './ScreenRecorder' +export { + pickRecordingType, recordingClock, RECORDING_TYPES, TOGGLE_RECORDING_EVENT, +} from './screenRecorderModel' export { updateCardModel, updateDialogModel } from './updateModel' export type { UpdateStatus, UpdateAction, UpdateCardModel, UpdateDialogModel } from './updateModel' export { canSubmit, submitLabel, countProblems, outcomeModel } from './reportModel' export type { ReportPhase } from './reportModel' export { phasePills, stepText, logTail, ENV_PHASES } from './envSetupView' -export type { UpdaterApi, ReportApi, EnvSetupApi, UpdateInfo, ReportResult } from './bridgeTypes' +export type { UpdaterApi, ReportApi, RecorderApi, EnvSetupApi, UpdateInfo, ReportResult } from './bridgeTypes' diff --git a/de_shell/js/renderer/screenRecorderModel.test.ts b/de_shell/js/renderer/screenRecorderModel.test.ts new file mode 100644 index 0000000..0edd12d --- /dev/null +++ b/de_shell/js/renderer/screenRecorderModel.test.ts @@ -0,0 +1,27 @@ +import { test } from 'node:test' +import assert from 'node:assert/strict' + +import { fileName, pickRecordingType, recordingClock } from './screenRecorderModel.ts' + +test('mp4 is preferred where it can be recorded', () => { + assert.deepEqual(pickRecordingType(() => true), + { mimeType: 'video/mp4;codecs=avc1', format: 'mp4' }) +}) + +test('webm is the fallback, and its file is .webm', () => { + assert.deepEqual(pickRecordingType(t => t.startsWith('video/webm')), + { mimeType: 'video/webm;codecs=vp9', format: 'webm' }) + // Nothing listed: let MediaRecorder pick, which is webm in Chromium. + assert.deepEqual(pickRecordingType(() => false), { mimeType: '', format: 'webm' }) +}) + +test('the clock reads m:ss', () => { + assert.equal(recordingClock(0), '0:00') + assert.equal(recordingClock(65), '1:05') + assert.equal(recordingClock(600), '10:00') +}) + +test('the file name is the last path segment on either separator', () => { + assert.equal(fileName('C:\\Users\\a\\Videos\\x.mp4'), 'x.mp4') + assert.equal(fileName('/home/a/x.webm'), 'x.webm') +}) diff --git a/de_shell/js/renderer/screenRecorderModel.ts b/de_shell/js/renderer/screenRecorderModel.ts new file mode 100644 index 0000000..adb50a2 --- /dev/null +++ b/de_shell/js/renderer/screenRecorderModel.ts @@ -0,0 +1,34 @@ +/** + * screenRecorderModel.ts — the screen recorder's decisions, free of React and + * of the browser, so they run under node --test. + */ + +/** mp4 where Chromium can mux it, webm everywhere else; best first. */ +export const RECORDING_TYPES = ['video/mp4;codecs=avc1', 'video/webm;codecs=vp9', 'video/webm'] as const + +/** Long enough that the per-chunk IPC is negligible, short enough that a crash + * costs seconds of video rather than the whole clip. */ +export const CHUNK_MS = 3000 + +/** The window event that starts or stops a recording. It must be dispatched + * from a real click handler: Chromium only grants `getDisplayMedia` with user + * activation, which a native menu item routed through main does not carry. */ +export const TOGGLE_RECORDING_EVENT = 'de-shell:toggle-recording' + +/** The best type this browser can record, and the file extension it needs. */ +export function pickRecordingType( + supported: (mimeType: string) => boolean, +): { mimeType: string; format: 'mp4' | 'webm' } { + const mimeType = RECORDING_TYPES.find(supported) ?? '' + return { mimeType, format: mimeType.startsWith('video/mp4') ? 'mp4' : 'webm' } +} + +/** Elapsed seconds as m:ss. */ +export function recordingClock(seconds: number): string { + return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}` +} + +/** The last segment of a path, on either separator. */ +export function fileName(path: string): string { + return path.split(/[\\/]/).pop() ?? path +} diff --git a/upcoming_changes/+screen-recorder.new_feature.rst b/upcoming_changes/+screen-recorder.new_feature.rst new file mode 100644 index 0000000..a7cd7c7 --- /dev/null +++ b/upcoming_changes/+screen-recorder.new_feature.rst @@ -0,0 +1 @@ +Apps can record their own window to a video file: ``registerScreenRecorder(win)`` in main, the preload bridge's ``recorder``, and ```` with ``toggleScreenRecording()`` in the renderer, moved here from SpyDE so every app gets it.