Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

fix(macos): log each step of Apple's picker flow and any lost process

Etienne Lescote1fee025653f
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index cf9f4c196..15f24992d 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -2182,6 +2182,10 @@ export function registerIpcHandlers(
const hud = getMainWindow();
const hideHud = !!hud && !hud.isDestroyed() && hud.isVisible();
if (hideHud) {
+ // Logged both ways: until the picker answers, this window (the HUD, or the editor in
+ // Record mode) is off screen, and a report that stops at this line says the answer
+ // never came (#1021).
+ console.info("[mac-picker] hiding the main window until the picker answers");
hud.hide();
}
let pick: MacPickerSelection | null;
@@ -2193,6 +2197,7 @@ export function registerIpcHandlers(
} finally {
if (hideHud && !hud.isDestroyed()) {
hud.showInactive();
+ console.info("[mac-picker] showing the main window again");
}
}
if (!pick) {
diff --git a/electron/main.ts b/electron/main.ts
index 22807b8d7..bde166790 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -67,6 +67,7 @@ import {
showPermissionsWindow,
showPermissionsWindowIfNeeded,
} from "./permissions";
+import { describeChildProcessGone, describeRenderProcessGone } from "./processGoneLog";
import { setDisplaySleepBlocked } from "./recording/displaySleepBlocker";
import { RecordingsDirManager } from "./recording/recordingsDirManager";
import { offersStarPrompt, REPO_URL, storeReviewUrl } from "./star-prompt";
@@ -1101,8 +1102,20 @@ function createCountdownOverlayWindowWrapper() {
// CLI mode owns its own lifecycle (see electron/cli/cliMain.ts).
if (!cliCommand) {
app.on("window-all-closed", () => {
+ // Only when it is what starts the quit: a quit already under way closes every window too.
+ if (!sttShutdownPromise) {
+ console.info("[app] the last window closed; quitting");
+ }
app.quit();
});
+ // Printed because nothing else is: a renderer or GPU process that dies takes no window
+ // with it, and the HUD, being transparent, just vanishes (#1021).
+ app.on("render-process-gone", (_event, webContents, details) => {
+ console.error(describeRenderProcessGone(webContents.getURL(), details));
+ });
+ app.on("child-process-gone", (_event, details) => {
+ console.error(describeChildProcessGone(details));
+ });
// The countdown overlay hides between takes instead of closing, so it would keep
// `window-all-closed` from ever firing (#961). Close it with the last other window. Every
// HUD/editor switch opens the next window before the previous one's `closed` arrives, so
@@ -1150,6 +1163,11 @@ app.on("before-quit", (event) => {
if (sttShutdownFinished) return;
event.preventDefault();
if (sttShutdownPromise) return;
+ // The one line that tells a quit from a crash in a pasted Terminal log. CLI runs report
+ // their own end on their own protocol.
+ if (!cliCommand) {
+ console.info("[app] quitting");
+ }
sttShutdownPromise = shutdownStt()
.catch((error) => {
console.error("[stt] Failed to stop whisper helper during app quit:", error);
diff --git a/electron/native-bridge/screen/macPickerSession.test.ts b/electron/native-bridge/screen/macPickerSession.test.ts
index 3aba6cdb2..192f993d3 100644
--- a/electron/native-bridge/screen/macPickerSession.test.ts
+++ b/electron/native-bridge/screen/macPickerSession.test.ts
@@ -1,6 +1,6 @@
import { EventEmitter } from "node:events";
import { PassThrough } from "node:stream";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, type MockInstance, vi } from "vitest";
import {
isMacPickerSourceId,
MacPickerSession,
@@ -10,6 +10,7 @@ import {
/** The `--picker-session` helper, driven by hand: what it hears, and a way to speak. */
class FakeSessionHelper extends EventEmitter {
+ pid = 4242;
stdin = new PassThrough();
stdout = new PassThrough();
stderr = new PassThrough();
@@ -30,6 +31,27 @@ class FakeSessionHelper extends EventEmitter {
this.emit("close", null, "SIGTERM");
return true;
}
+
+ /** The helper going away on its own, as a crash or an early exit would. */
+ exit(code: number | null, signal: NodeJS.Signals | null = null) {
+ this.emit("close", code, signal);
+ }
+}
+
+// The session logs every step of the picker (#1021); keep that out of the test output, and
+// let the tests that are about the logging read it back.
+let info: MockInstance<typeof console.info>;
+let warn: MockInstance<typeof console.warn>;
+beforeEach(() => {
+ info = vi.spyOn(console, "info").mockImplementation(() => undefined);
+ warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+});
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+function logged(spy: MockInstance<typeof console.info>) {
+ return spy.mock.calls.map((args) => args.map(String).join(" "));
}
const DISPLAY_PICK = {
@@ -289,6 +311,69 @@ describe("MacPickerSession", () => {
});
});
+describe("MacPickerSession, as the Terminal output tells it (#1021)", () => {
+ it("traces a pick from the session's start to the answer", async () => {
+ const { helper, session } = await readySession();
+ const pick = session.present([7]);
+ await flush();
+ helper.say({ ...DISPLAY_PICK, kind: "window", windowId: 42, title: "Q3 layoffs.key" });
+ expect(await pick).not.toBeNull();
+
+ expect(logged(info)).toEqual([
+ "[mac-picker] picker session started (pid 4242)",
+ "[mac-picker] showing Apple's picker",
+ "[mac-picker] picked a window (1920x1080)",
+ ]);
+ // A window's title can say anything, and these lines get pasted into public issues.
+ expect(logged(info).join("\n")).not.toContain("layoffs");
+ });
+
+ it("says when the user cancelled", async () => {
+ const { helper, session } = await readySession();
+ const pick = session.present([]);
+ await flush();
+ helper.say({ event: "picker-cancelled" });
+ expect(await pick).toBeNull();
+ expect(logged(info)).toContain("[mac-picker] the picker was cancelled");
+ });
+
+ it("says the helper died while Apple's picker was up, and answers nothing", async () => {
+ const { helper, session } = await readySession();
+ const pick = session.present([]);
+ await flush();
+ helper.exit(null, "SIGSEGV");
+ expect(await pick).toBeNull();
+ expect(logged(warn)).toEqual([
+ "[mac-picker] the picker session exited (signal SIGSEGV) while Apple's picker was up",
+ ]);
+ });
+
+ it("says the helper exited during a take, with its exit code", async () => {
+ const { helper, session } = await pickDisplay();
+ session.startTake({});
+ helper.exit(1);
+ await flush();
+ expect(logged(warn)).toEqual(["[mac-picker] the picker session exited (code 1) during a take"]);
+ });
+
+ it("stays quiet when the app ended the session itself", async () => {
+ const { helper, session } = await pickDisplay();
+ session.dispose();
+ helper.exit(0);
+ await flush();
+ expect(logged(warn)).toEqual([]);
+ });
+
+ it("answers at once when the picker cannot be shown, instead of waiting on the helper", async () => {
+ const { helper, session } = await readySession();
+ helper.stdin.end();
+ expect(await session.present([])).toBeNull();
+ expect(logged(warn)).toEqual([
+ "[mac-picker] could not reach the picker session to show the picker",
+ ]);
+ });
+});
+
describe("isMacPickerSourceId", () => {
it("tells a picked source from a desktopCapturer id", () => {
expect(isMacPickerSourceId("mac-picker:display:1")).toBe(true);
diff --git a/electron/native-bridge/screen/macPickerSession.ts b/electron/native-bridge/screen/macPickerSession.ts
index e2e2f2603..b2a6b42d2 100644
--- a/electron/native-bridge/screen/macPickerSession.ts
+++ b/electron/native-bridge/screen/macPickerSession.ts
@@ -195,6 +195,8 @@ export class MacPickerSession {
private take: TakeProcess | null = null;
private pendingPick: ((selection: MacPickerSelection | null) => void) | null = null;
private lineBuffer = "";
+ /** Set by `dispose`: the helper exiting is then the app's doing, not something to report. */
+ private disposed = false;
constructor(
private readonly helperPath: string,
@@ -274,6 +276,7 @@ export class MacPickerSession {
const event = parseEvent(line);
if (event?.event === "picker-session-ready") {
this.proc = proc;
+ console.info(`[mac-picker] picker session started (pid ${proc.pid})`);
settle(true);
continue;
}
@@ -293,7 +296,8 @@ export class MacPickerSession {
console.warn("[mac-picker] helper error:", error);
settle(false);
});
- proc.once("close", (_code, signal) => {
+ proc.once("close", (code, signal) => {
+ this.reportSessionExit(code, signal);
this.onSessionGone(signal ?? "SIGTERM");
settle(false);
});
@@ -322,12 +326,20 @@ export class MacPickerSession {
};
});
this.presentedExclusions = [...excludedWindowIds];
- this.send({
+ const sent = this.send({
command: "present",
excludedWindowIds,
modes: ["display", "window"],
hideDesktopIcons,
});
+ if (sent) {
+ console.info("[mac-picker] showing Apple's picker");
+ } else {
+ // Nothing will ever answer a picker that was never shown: say so now rather than
+ // leave the caller (and the HUD it hid) waiting on the session's exit.
+ console.warn("[mac-picker] could not reach the picker session to show the picker");
+ this.resolvePick(null);
+ }
return answer;
}
@@ -350,6 +362,7 @@ export class MacPickerSession {
/** Ends the session with the app. Closing stdin makes the helper stop and exit. */
dispose() {
+ this.disposed = true;
this.proc?.stdin.end();
this.proc = null;
}
@@ -373,6 +386,12 @@ export class MacPickerSession {
this.selection = selection;
this.selectionExclusions = this.presentedExclusions;
this.selectionExcludesApp = event.excludesApp === true;
+ // Kind and size only: a window's title is the user's business, and these
+ // lines end up pasted into public bug reports.
+ const { width, height } = selection.bounds;
+ console.info(`[mac-picker] picked a ${selection.kind} (${width}x${height})`);
+ } else {
+ console.warn("[mac-picker] the picker answered with a pick that has no frame");
}
this.resolvePick(selection);
return;
@@ -381,6 +400,8 @@ export class MacPickerSession {
case "picker-failed":
if (event.event === "picker-failed") {
console.warn("[mac-picker] the picker failed:", event.message);
+ } else {
+ console.info("[mac-picker] the picker was cancelled");
}
this.resolvePick(null);
return;
@@ -402,6 +423,25 @@ export class MacPickerSession {
pending?.(selection);
}
+ /**
+ * Says how the helper went, and what it took with it. Without this a helper that dies
+ * while Apple's picker is up leaves no trace: the HUD comes back with nothing picked and
+ * the app prints nothing at all (#1021). Silent when the app ended the session itself.
+ */
+ private reportSessionExit(code: number | null, signal: NodeJS.Signals | null) {
+ if (this.disposed) {
+ return;
+ }
+ const how = signal ? `signal ${signal}` : `code ${code}`;
+ let during = "";
+ if (this.pendingPick) {
+ during = " while Apple's picker was up";
+ } else if (this.take && !this.take.ended) {
+ during = " during a take";
+ }
+ console.warn(`[mac-picker] the picker session exited (${how})${during}`);
+ }
+
private onSessionGone(signal: NodeJS.Signals) {
this.proc = null;
this.lineBuffer = "";
diff --git a/electron/processGoneLog.test.ts b/electron/processGoneLog.test.ts
new file mode 100644
index 000000000..049667299
--- /dev/null
+++ b/electron/processGoneLog.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import {
+ describeChildProcessGone,
+ describeRenderProcessGone,
+ windowTypeOf,
+} from "./processGoneLog";
+
+describe("windowTypeOf", () => {
+ it("names the window from its windowType, packaged or dev", () => {
+ expect(
+ windowTypeOf(
+ "file:///Applications/Openscreen.app/Contents/Resources/app.asar/dist/index.html?windowType=hud-overlay",
+ ),
+ ).toBe("hud-overlay");
+ expect(windowTypeOf("http://localhost:5173/?windowType=editor&project=x")).toBe("editor");
+ });
+
+ it("says unknown rather than printing a URL it cannot read", () => {
+ expect(windowTypeOf("")).toBe("unknown");
+ expect(windowTypeOf("file:///Users/someone/index.html")).toBe("unknown");
+ });
+});
+
+describe("describeRenderProcessGone", () => {
+ it("names the window and why its renderer went, never the path it was loaded from", () => {
+ const line = describeRenderProcessGone(
+ "file:///Users/someone/Openscreen.app/index.html?windowType=hud-overlay",
+ { reason: "crashed", exitCode: 11 },
+ );
+ expect(line).toBe("[app] the hud-overlay window's renderer is gone (crashed, exit code 11)");
+ expect(line).not.toContain("/Users/");
+ });
+});
+
+describe("describeChildProcessGone", () => {
+ it("names the process type, and the utility process when there is one", () => {
+ expect(describeChildProcessGone({ type: "GPU", reason: "crashed", exitCode: 5 })).toBe(
+ "[app] the GPU process is gone (crashed, exit code 5)",
+ );
+ expect(
+ describeChildProcessGone({
+ type: "Utility",
+ reason: "killed",
+ exitCode: 9,
+ name: "Audio Service",
+ }),
+ ).toBe('[app] the Utility "Audio Service" process is gone (killed, exit code 9)');
+ });
+});
diff --git a/electron/processGoneLog.ts b/electron/processGoneLog.ts
new file mode 100644
index 000000000..90e4ee846
--- /dev/null
+++ b/electron/processGoneLog.ts
@@ -0,0 +1,36 @@
+// One line for each process the app loses, in the Terminal output users paste into bug
+// reports. Electron reports these events and prints nothing by default, and the HUD is a
+// transparent window: a HUD renderer that dies leaves nothing on screen while the app keeps
+// running, which reads exactly like a crash with no crash log (#1021).
+
+/** The window a renderer drew, from its URL's `windowType`: never the URL, which can carry paths. */
+export function windowTypeOf(url: string): string {
+ try {
+ return new URL(url).searchParams.get("windowType") ?? "unknown";
+ } catch {
+ return "unknown";
+ }
+}
+
+export function describeRenderProcessGone(
+ url: string,
+ details: { reason: string; exitCode: number },
+): string {
+ return (
+ `[app] the ${windowTypeOf(url)} window's renderer is gone ` +
+ `(${details.reason}, exit code ${details.exitCode})`
+ );
+}
+
+export function describeChildProcessGone(details: {
+ type: string;
+ reason: string;
+ exitCode: number;
+ name?: string;
+}): string {
+ const name = details.name ? ` "${details.name}"` : "";
+ return (
+ `[app] the ${details.type}${name} process is gone ` +
+ `(${details.reason}, exit code ${details.exitCode})`
+ );
+}