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(diagnostics): fill the Save Diagnostics bundle from the tray and menus

Etienne Lescotd166a98905f7
diff --git a/electron/diagnostics/main-log-buffer.test.ts b/electron/diagnostics/main-log-buffer.test.ts
index b83511826..488d4cb32 100644
--- a/electron/diagnostics/main-log-buffer.test.ts
+++ b/electron/diagnostics/main-log-buffer.test.ts
@@ -44,6 +44,21 @@ describe("MainLogBuffer", () => {
expect(snap[0].text).toBe('{"a":1}');
});
+ it("keeps an Error's message and stack rather than JSON's {}", () => {
+ const buf = make(5);
+ Object.assign(console, {
+ error: () => {
+ // The stack this logs would only clutter the test output.
+ },
+ });
+ buf.install();
+ const error = new Error("helper exited (code=1)");
+ console.error("Failed to stop native Linux recording:", error);
+ const [entry] = buf.snapshot();
+ expect(entry.text).toBe(`Failed to stop native Linux recording: ${error.stack}`);
+ expect(entry.text).toContain("Error: helper exited (code=1)");
+ });
+
it("drops oldest entries past capacity", () => {
const buf = make(3);
buf.install();
diff --git a/electron/diagnostics/main-log-buffer.ts b/electron/diagnostics/main-log-buffer.ts
index ba12ffefe..8a9c8b5d6 100644
--- a/electron/diagnostics/main-log-buffer.ts
+++ b/electron/diagnostics/main-log-buffer.ts
@@ -2,14 +2,15 @@
* Ring buffer for main-process console output.
*
* Captures the last `capacity` lines written via console.info / console.warn /
- * console.error / console.log into a single in-memory buffer. Disabled by
- * default — install only when verbose diagnostics are wanted, e.g. when
- * OPENSCREEN_DIAGNOSTIC=1 is set or when a developer wants a more complete
- * "Save Diagnostics" payload for an upstream bug report.
+ * console.error / console.log into a single in-memory buffer, which "Save
+ * Diagnostics" writes as `mainProcessLogs`. main.ts installs it on every app
+ * launch: the users who save a bundle start the app from a desktop entry, the
+ * Dock or the Start menu, where no OPENSCREEN_DIAGNOSTIC can be set, and gating
+ * it on that flag left every one of their bundles with no log at all.
*
- * Cost when enabled: one array.push + occasional shift per console call,
- * negligible against the rest of the app. Cost when disabled: zero, the
- * original console methods are kept untouched.
+ * Cost when installed: one array.push + occasional shift per console call,
+ * negligible against the rest of the app. Cost when not installed (the CLI):
+ * zero, the original console methods are kept untouched.
*/
const DEFAULT_CAPACITY = 500;
@@ -78,6 +79,10 @@ export class MainLogBuffer {
const text = args
.map((arg) => {
if (typeof arg === "string") return arg;
+ // An Error's message and stack are not enumerable, so JSON.stringify
+ // writes `{}`: every `console.error("…failed:", error)` lost its cause.
+ // The stack is what the terminal shows for it.
+ if (arg instanceof Error) return arg.stack ?? `${arg.name}: ${arg.message}`;
try {
return JSON.stringify(arg);
} catch {
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 3a179dbcd..8da84bc8c 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -882,6 +882,13 @@ let nativeMacStopInFlight = false;
// Global frame of the region captured by the SCK helper (see getSelectedSourceBounds).
let activeMacCaptureBounds: Rectangle | null = null;
let linuxNativeCaptureSession: LinuxNativeCaptureSession | null = null;
+/**
+ * The Linux capture helper spawned last, kept after its take ends for Save Diagnostics'
+ * `helperOutput.linux`: the same "until the next take starts" lifetime as
+ * `nativeWindowsCaptureOutput`. A prepare that was cancelled counts, since its picker
+ * answer is what a report about it needs.
+ */
+let lastLinuxCaptureSession: LinuxNativeCaptureSession | null = null;
let linuxNativeCaptureRecordingId: number | null = null;
let linuxNativeCaptureCursorMode: CursorCaptureMode = "editable-overlay";
/** What the portal granted for the running capture, for the tray's label. */
@@ -1916,13 +1923,26 @@ async function resolveMediaLinksForVideo(videoPath: string): Promise<{
return { resolvedVia: "none" };
}
+/**
+ * The open editor's live document, for a bundle saved from the tray or a menu, which
+ * has no renderer state to pass. The host the MCP server reads it through, set by
+ * registerIpcHandlers.
+ */
+let editorDocumentHost: EditorDocumentHost | null = null;
+/**
+ * How long Save Diagnostics waits for the editor's document. A hung editor is exactly
+ * when a bundle is wanted, so it must not hold the save for an MCP call's 30 s.
+ */
+const DIAGNOSTIC_PROJECT_STATE_TIMEOUT_MS = 5_000;
+
/**
* Writes the diagnostic bundle a bug report needs: app/OS facts, the native
* helpers' raw stdout/stderr (which is where `[stop-timing]` and
* `encoder-selection` land — see nativeWindowsCaptureStop.ts), and the main
* process's own recent console output. Shared by the renderer's IPC call and
* the menu/tray "Save Diagnostics" entry point in main.ts, which has no
- * renderer-side `projectState`/`logs` to offer and does not need to.
+ * renderer-side `projectState`/`logs` to offer: the open editor's document is
+ * asked for instead.
*/
export async function exportDiagnosticFile(payload: {
error: string;
@@ -1940,6 +1960,10 @@ export async function exportDiagnosticFile(payload: {
const HELPER_OUTPUT_MAX_BYTES = 64 * 1024;
const tail = (s: string, max: number) => (s.length <= max ? s : s.slice(s.length - max));
+ const projectState =
+ payload.projectState ??
+ (await editorDocumentHost?.snapshot(DIAGNOSTIC_PROJECT_STATE_TIMEOUT_MS)) ??
+ null;
const diagnostic = {
timestamp: new Date().toISOString(),
@@ -1958,11 +1982,12 @@ export async function exportDiagnosticFile(payload: {
chromeVersion: process.versions.chrome,
error: payload.error,
stack: payload.stack,
- projectState: payload.projectState,
+ projectState,
recentLogs: payload.logs,
helperOutput: {
windows: tail(nativeWindowsCaptureOutput, HELPER_OUTPUT_MAX_BYTES),
mac: tail(nativeMacCaptureOutput, HELPER_OUTPUT_MAX_BYTES),
+ linux: tail(lastLinuxCaptureSession?.helperOutput ?? "", HELPER_OUTPUT_MAX_BYTES),
},
mainProcessLogs: mainLogBuffer.snapshot(),
};
@@ -2672,6 +2697,7 @@ export function registerIpcHandlers(
maxCursorSamples: MAX_CURSOR_SAMPLES,
deferStart: true,
});
+ lastLinuxCaptureSession = session;
await session.start();
// The picker is up now. No timeout: a human is reading a dialog.
@@ -2756,6 +2782,7 @@ export function registerIpcHandlers(
},
maxCursorSamples: MAX_CURSOR_SAMPLES,
});
+ lastLinuxCaptureSession = session;
console.info("[native-linux] starting capture", {
outputPath,
@@ -5065,9 +5092,11 @@ export function registerIpcHandlers(
// read on every call: "MCP edits", separate from the in-app agent's "Agent edits",
// so turning the server on grants a client read access and nothing more.
const mcpSettings = new McpSettingsStore(app.getPath("userData"), safeStorage);
+ const documentHost = new EditorDocumentHost(ipcMain);
+ editorDocumentHost = documentHost;
const mcpToolDeps: McpToolDeps = {
transport: "http",
- host: new EditorDocumentHost(ipcMain),
+ host: documentHost,
projects: aiEditionDocuments,
editsAllowed: () => mcpSettings.getSettings().allowEdits,
cursor: agentCursorTelemetryReader,
diff --git a/electron/main.ts b/electron/main.ts
index 3da06d985..64f5cd76c 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -39,7 +39,7 @@ import {
import { parseCliArgs } from "./cli/args";
import { runCli } from "./cli/cliMain";
import { disableHttpCacheForDevServer } from "./dev-http-cache";
-import { isDiagnosticModeEnabled, mainLogBuffer } from "./diagnostics/main-log-buffer";
+import { mainLogBuffer } from "./diagnostics/main-log-buffer";
import { buildEditMenuSubmenu, type EditorUndoRedoChannel, routeEditorUndoRedo } from "./edit-menu";
import {
loadAndRegisterGlobalShortcut,
@@ -609,10 +609,10 @@ function runUpdateCheck() {
* in folder" gives, so there is no need for a second dialog on top of the
* native Save dialog the user already went through.
*
- * No renderer `projectState`/`logs` to attach from here, unlike the in-app
- * crash path this shares a payload shape with — the diagnostic value for a
- * capture bug is almost entirely `helperOutput`/`mainProcessLogs`, which
- * `exportDiagnosticFile` reads straight from the main process regardless.
+ * No renderer `projectState`/`logs` to pass from here, unlike the in-app crash
+ * path this shares a payload shape with. `exportDiagnosticFile` asks the open
+ * editor for its document instead, and reads `helperOutput`/`mainProcessLogs`,
+ * where most of a capture bug's diagnostic value is, from the main process.
*/
function runSaveDiagnostics() {
exportDiagnosticFile({ error: "Manual diagnostic export", projectState: null, logs: [] })
@@ -1227,10 +1227,10 @@ app.on("will-quit", () => {
const appReady = !cliCommand && hasSingleInstanceLock ? app.whenReady() : null;
appReady?.then(async () => {
- if (isDiagnosticModeEnabled()) {
- mainLogBuffer.install();
- console.info("[diagnostic] OPENSCREEN_DIAGNOSTIC=1, capturing console.* into ring buffer");
- }
+ // On every launch, not only under OPENSCREEN_DIAGNOSTIC: these lines are the
+ // `mainProcessLogs` of "Save Diagnostics", and a user who saves a bundle from the
+ // tray started the app where no such variable can be set.
+ mainLogBuffer.install();
// Force "regular" activation policy so the Dock icon appears. The HUD overlay
// (transparent, frameless, skipTaskbar) is the first window, and AppKit would
diff --git a/electron/mcp/editor-document-host.test.ts b/electron/mcp/editor-document-host.test.ts
index 4777b6440..08635ec85 100644
--- a/electron/mcp/editor-document-host.test.ts
+++ b/electron/mcp/editor-document-host.test.ts
@@ -100,6 +100,22 @@ describe("EditorDocumentHost", () => {
await expect(pending).resolves.toBeNull();
});
+ it("gives up on a snapshot after the bound it is given, not the usual 30 s", async () => {
+ vi.useFakeTimers();
+ const { host, fromRenderer } = setup();
+ const editor = new FakeWebContents();
+ fromRenderer(editor, AI_EDITION_MCP_HOST_CHANNEL, true);
+ let settled = false;
+ const pending = host.snapshot(5_000).then((snapshot) => {
+ settled = true;
+ return snapshot;
+ });
+ await vi.advanceTimersByTimeAsync(4_999);
+ expect(settled).toBe(false);
+ await vi.advanceTimersByTimeAsync(1);
+ await expect(pending).resolves.toBeNull();
+ });
+
it("forgets an editor that unregisters or is destroyed", async () => {
const { host, fromRenderer } = setup();
const first = new FakeWebContents();
diff --git a/electron/mcp/editor-document-host.ts b/electron/mcp/editor-document-host.ts
index 4a3be27dd..973fb04cb 100644
--- a/electron/mcp/editor-document-host.ts
+++ b/electron/mcp/editor-document-host.ts
@@ -102,8 +102,9 @@ export class EditorDocumentHost implements McpDocumentHost {
});
}
- async snapshot(): Promise<AiEditionMcpHostSnapshot | null> {
- const result = await this.request({ op: "snapshot" });
+ /** `timeoutMs`: Save Diagnostics waits less than an MCP call, see exportDiagnosticFile. */
+ async snapshot(timeoutMs = REQUEST_TIMEOUT_MS): Promise<AiEditionMcpHostSnapshot | null> {
+ const result = await this.request({ op: "snapshot" }, timeoutMs);
if (!result || result === TIMED_OUT || typeof result !== "object") return null;
// The revision is the apply guard: one that is missing or not a number would
// reach `applyAgentDocumentIfCurrent` as `undefined`, which skips the
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
index 51050943b..e19dba5ff 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
@@ -581,4 +581,58 @@ describe("LinuxNativeCaptureSession", () => {
expect(helper.killed).toBe(false);
});
});
+
+ /**
+ * Save Diagnostics' `helperOutput.linux`. Before it, a Linux bundle had no entry for
+ * the helper at all, where Windows and macOS keep their helper's raw output.
+ */
+ describe("helper output", () => {
+ it("keeps the helper's stderr and events past its exit, without cursor samples", async () => {
+ const session = newSession();
+ await startReady(session);
+ helper.stderr.write("pipewire: format negotiated\n");
+ helper.emitEvent({ event: "encoder-selection", video: "h264_vaapi" });
+ helper.emitEvent({
+ event: "cursor-sample",
+ timestampMs: 1_150,
+ x: 10,
+ y: 20,
+ width: 1280,
+ height: 720,
+ visible: true,
+ });
+ helper.emitEvent({ event: "warning", code: "dmabuf", message: "falling back to shm" });
+ await flushStdout();
+ helper.emit("exit", 1, null);
+
+ const output = session.helperOutput;
+ expect(output).toContain('"event":"ready"');
+ expect(output).toContain("pipewire: format negotiated\n");
+ expect(output).toContain('"video":"h264_vaapi"');
+ expect(output).toContain('"message":"falling back to shm"');
+ expect(output).not.toContain("cursor-sample");
+ });
+
+ it("keeps a line the helper wrote that is not JSON", async () => {
+ const session = newSession();
+ await startReady(session);
+ helper.stdout.write("thread 'main' panicked at src/main.rs:12\n");
+ await flushStdout();
+
+ expect(session.helperOutput).toContain("thread 'main' panicked at src/main.rs:12\n");
+ });
+
+ it("keeps the newest 64 KiB of a helper that keeps talking", async () => {
+ const session = newSession();
+ await startReady(session);
+ for (let i = 0; i < 1_000; i += 1) {
+ helper.stderr.write(`warning ${i} ${"x".repeat(100)}\n`);
+ }
+ await flushStdout();
+
+ expect(session.helperOutput.length).toBe(64 * 1024);
+ expect(session.helperOutput).toContain("warning 999 ");
+ expect(session.helperOutput).not.toContain('"event":"ready"');
+ });
+ });
});
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
index 2c2a74766..0ccffd467 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
@@ -43,6 +43,11 @@ const STOP_TIMEOUT_MS = 15_000;
* delivers leave the HUD waiting forever, with nothing on screen to say so.
*/
const FIRST_FRAME_TIMEOUT_MS = 10_000;
+/**
+ * The most of the helper's output [`helperOutput`] keeps, the 64 KiB Save Diagnostics
+ * writes of each helper. Only the newest is kept, as on Windows and macOS.
+ */
+const HELPER_OUTPUT_MAX_CHARS = 64 * 1024;
export interface LinuxCaptureConfig {
outputPath: string;
@@ -107,6 +112,7 @@ export class LinuxNativeCaptureSession {
private videoEncoder: string | undefined;
private lastError: string | null = null;
private paused = false;
+ private helperOutputText = "";
constructor(private readonly config: LinuxCaptureConfig) {
this.cursor = new PipeWireCursorAccumulator(config.maxCursorSamples);
@@ -148,6 +154,7 @@ export class LinuxNativeCaptureSession {
child.stdout.on("data", (chunk: string) => this.handleStdout(chunk));
child.stderr.setEncoding("utf8");
child.stderr.on("data", (chunk: string) => {
+ this.appendHelperOutput(chunk);
const message = chunk.trim();
if (message) {
console.error("[capture-linux]", message);
@@ -325,6 +332,23 @@ export class LinuxNativeCaptureSession {
return this.sourceKind;
}
+ /**
+ * What the helper said in this session, for Save Diagnostics' `helperOutput.linux`:
+ * its stderr as written and every stdout line except `cursor-sample`, which comes
+ * at the capture rate and would push everything else out. Still readable after the
+ * helper exits, which is when a bug report asks for it.
+ */
+ get helperOutput(): string {
+ return this.helperOutputText;
+ }
+
+ private appendHelperOutput(text: string) {
+ this.helperOutputText += text;
+ if (this.helperOutputText.length > HELPER_OUTPUT_MAX_CHARS) {
+ this.helperOutputText = this.helperOutputText.slice(-HELPER_OUTPUT_MAX_CHARS);
+ }
+ }
+
/**
* Asks the helper to write the trailer and exit, then returns what it made.
*
@@ -401,9 +425,13 @@ export class LinuxNativeCaptureSession {
try {
payload = JSON.parse(line) as PipeWireHelperEvent;
} catch (error) {
+ this.appendHelperOutput(`${line}\n`);
console.error("Failed to parse Linux capture helper output:", error, line);
return;
}
+ if (payload.event !== "cursor-sample") {
+ this.appendHelperOutput(`${line}\n`);
+ }
this.handleEvent(payload);
});
}
diff --git a/technical-documentation/testing/manual-e2e-checklist.md b/technical-documentation/testing/manual-e2e-checklist.md
index b761e00ec..c392835d2 100644
--- a/technical-documentation/testing/manual-e2e-checklist.md
+++ b/technical-documentation/testing/manual-e2e-checklist.md
@@ -97,7 +97,7 @@ gh run download <run-id> -R getopenscreen/openscreen -n openscreen-windows-x64
- AppImage: `chmod +x Openscreen-Linux-<version>.AppImage`, then run it; add `--no-sandbox` if Chromium's sandbox cannot start. A package: install it with the distribution's tool (`sudo apt install ./Openscreen-Linux-<version>.deb`, `sudo dnf install ./Openscreen-Linux-<version>.rpm`, `sudo pacman -U Openscreen-Linux-<version>.pacman`), then run `openscreen`.
- No flag is needed. Which name to grant is **to confirm on the first run**: a package installs a desktop entry, an AppImage has none until it is integrated.
-**Logs of a packaged build.** OpenScreen writes no log file. The main process logs to its standard output, so a launch from a terminal shows it there, `[content-protection] OFF for the HUD window` included; whether the Windows executable prints into the PowerShell that started it is **to confirm on the first run**. Launched with `OPENSCREEN_DIAGNOSTIC=1` as well, the app keeps the last 500 main-process lines, and tray → *Save Diagnostics* writes them to a JSON file of your choice, with the capture helper's recent output. The renderer's `console` calls are stripped from packaged builds. Recordings and their `.cursor.json` and `.session.json` sidecars are in the `recordings` folder of `%APPDATA%\Openscreen`, `~/Library/Application Support/Openscreen` or `~/.config/Openscreen`.
+**Logs of a packaged build.** OpenScreen writes no log file. The main process logs to its standard output, so a launch from a terminal shows it there, `[content-protection] OFF for the HUD window` included; whether the Windows executable prints into the PowerShell that started it is **to confirm on the first run**. However it was launched, the app keeps the last 500 main-process lines, and tray → *Save Diagnostics* writes them to a JSON file of your choice (`mainProcessLogs`), with the capture helper's recent output (`helperOutput.windows`, `.mac` or `.linux`) and, while the editor is open, its project (`projectState`). The renderer's `console` calls are stripped from packaged builds. Recordings and their `.cursor.json` and `.session.json` sidecars are in the `recordings` folder of `%APPDATA%\Openscreen`, `~/Library/Application Support/Openscreen` or `~/.config/Openscreen`.
## Launch and HUD