fix(wgc): capture per-step stop timing, bump timeout, add diagnostic tool

.github/workflows/diagnostic-artifact.yml

@@ -0,0 +1,118 @@
+name: Diagnostic artifact
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-windows:
+    name: Windows x64 diagnostic bundle
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build native helper
+        run: npm run build:native:win
+
+      - name: Bundle diagnostic tool
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $bundle = "openscreen-diagnostic-windows-x64"
+          $staging = New-Item -ItemType Directory -Path "$bundle"
+          Copy-Item scripts/diagnostic-tool/diagnostic.mjs -Destination $staging
+          Copy-Item scripts/diagnostic-tool/diagnostic.bat -Destination $staging
+          Copy-Item scripts/diagnostic-tool/README.md -Destination $staging
+          New-Item -ItemType Directory -Path "$staging/helpers/win32-x64" | Out-Null
+          Copy-Item electron/native/bin/win32-x64/wgc-capture.exe -Destination "$staging/helpers/win32-x64/"
+          Compress-Archive -Path "$staging" -DestinationPath "$bundle.zip"
+
+      - name: Smoke-test the bundle
+        shell: pwsh
+        # The actual capture path is exercised by users with a real desktop
+        # session. A non-interactive runner has no display, so WGC cannot
+        # capture frames and the helper exits before emitting [stop-timing].
+        # Validate bundle structure + CLI parser instead of running capture.
+        run: |
+          $ErrorActionPreference = "Stop"
+          Expand-Archive -Path openscreen-diagnostic-windows-x64.zip -DestinationPath smoke
+          $smoke = Resolve-Path "smoke/openscreen-diagnostic-windows-x64"
+          foreach ($rel in @(
+            "diagnostic.mjs",
+            "diagnostic.bat",
+            "README.md",
+            "helpers/win32-x64/wgc-capture.exe"
+          )) {
+            $p = Join-Path $smoke $rel
+            if (-not (Test-Path $p)) { throw "Smoke test: missing $rel" }
+          }
+          & "$smoke/diagnostic.bat" --help | Out-Null
+          if ($LASTEXITCODE -ne 0) { throw "diagnostic.bat --help exited $LASTEXITCODE" }
+
+      - name: Upload Windows diagnostic bundle
+        uses: actions/upload-artifact@v4
+        with:
+          name: openscreen-diagnostic-windows-x64
+          path: openscreen-diagnostic-windows-x64.zip
+          if-no-files-found: error
+          retention-days: 14
+
+  build-macos:
+    name: macOS ${{ matrix.arch }} diagnostic bundle
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [arm64, x64]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build native helper
+        run: npm run build:native:mac
+        env:
+          OPENSCREEN_MAC_HELPER_ARCHS: ${{ matrix.arch }}
+
+      - name: Bundle diagnostic tool
+        run: |
+          set -euo pipefail
+          arch="${{ matrix.arch }}"
+          arch_tag="darwin-$([ "$arch" = "x64" ] && echo x64 || echo arm64)"
+          bundle="openscreen-diagnostic-macos-$arch"
+          rm -rf "$bundle" "$bundle.tar.gz"
+          mkdir -p "$bundle/helpers/$arch_tag"
+          cp scripts/diagnostic-tool/diagnostic.mjs "$bundle/"
+          cp scripts/diagnostic-tool/diagnostic.sh "$bundle/"
+          cp scripts/diagnostic-tool/README.md "$bundle/"
+          cp "electron/native/bin/$arch_tag/openscreen-screencapturekit-helper" "$bundle/helpers/$arch_tag/"
+          chmod +x "$bundle/diagnostic.sh" "$bundle/helpers/$arch_tag/openscreen-screencapturekit-helper"
+          tar -czf "$bundle.tar.gz" "$bundle"
+
+      - name: Upload macOS diagnostic bundle
+        uses: actions/upload-artifact@v4
+        with:
+          name: openscreen-diagnostic-macos-${{ matrix.arch }}
+          path: openscreen-diagnostic-macos-${{ matrix.arch }}.tar.gz
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Docs
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [main]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Cancel in-flight runs on the same ref so fast follow-up pushes
+# don't queue stale builds.
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+      - name: Install dependencies
+        working-directory: website
+        run: npm ci
+      - name: Type-check
+        working-directory: website
+        run: npm run typecheck
+      - name: Build
+        working-directory: website
+        run: npm run build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: website/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

electron/diagnostics/main-log-buffer.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { MainLogBuffer } from "./main-log-buffer";
+
+describe("MainLogBuffer", () => {
+	const buffers: MainLogBuffer[] = [];
+
+	function make(capacity: number) {
+		const b = new MainLogBuffer(capacity);
+		buffers.push(b);
+		return b;
+	}
+
+	afterEach(() => {
+		for (const b of buffers) b.uninstall();
+		buffers.length = 0;
+	});
+
+	it("captures every console level and routes to original", () => {
+		const buf = make(10);
+		const captured: string[] = [];
+		const original = {
+			log: (...args: unknown[]) => captured.push(`log:${args.join(",")}`),
+			info: (...args: unknown[]) => captured.push(`info:${args.join(",")}`),
+			warn: (...args: unknown[]) => captured.push(`warn:${args.join(",")}`),
+			error: (...args: unknown[]) => captured.push(`error:${args.join(",")}`),
+		};
+		Object.assign(console, original);
+		buf.install();
+		console.log("hello");
+		console.info("world");
+		console.warn("watch");
+		console.error("bad");
+		const snap = buf.snapshot();
+		expect(snap.map((e) => e.level)).toEqual(["log", "info", "warn", "error"]);
+		expect(snap.map((e) => e.text)).toEqual(["hello", "world", "watch", "bad"]);
+		expect(captured).toEqual(["log:hello", "info:world", "warn:watch", "error:bad"]);
+	});
+
+	it("stringifies non-string args", () => {
+		const buf = make(5);
+		buf.install();
+		console.info({ a: 1 });
+		const snap = buf.snapshot();
+		expect(snap[0].text).toBe('{"a":1}');
+	});
+
+	it("drops oldest entries past capacity", () => {
+		const buf = make(3);
+		buf.install();
+		for (let i = 0; i < 5; i += 1) console.info(`line ${i}`);
+		const snap = buf.snapshot();
+		expect(snap.map((e) => e.text)).toEqual(["line 2", "line 3", "line 4"]);
+	});
+
+	it("uninstall restores originals", () => {
+		const buf = make(5);
+		buf.install();
+		console.info("captured");
+		buf.uninstall();
+		console.info("after-uninstall");
+		const snap = buf.snapshot();
+		expect(snap.map((e) => e.text)).toEqual(["captured"]);
+	});
+
+	it("clear empties the buffer", () => {
+		const buf = make(5);
+		buf.install();
+		console.info("one");
+		console.info("two");
+		buf.clear();
+		expect(buf.snapshot()).toEqual([]);
+	});
+
+	it("install is idempotent", () => {
+		const buf = make(5);
+		buf.install();
+		buf.install();
+		console.info("once");
+		const snap = buf.snapshot();
+		expect(snap.map((e) => e.text)).toEqual(["once"]);
+	});
+});

electron/diagnostics/main-log-buffer.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+const DEFAULT_CAPACITY = 500;
+
+export interface MainLogEntry {
+	timestampMs: number;
+	level: "info" | "warn" | "error" | "log";
+	text: string;
+}
+
+export class MainLogBuffer {
+	private readonly capacity: number;
+	private readonly entries: MainLogEntry[] = [];
+	private installed = false;
+	private readonly originals: Partial<
+		Record<"log" | "info" | "warn" | "error", (...args: unknown[]) => void>
+	> = {};
+
+	constructor(capacity = DEFAULT_CAPACITY) {
+		this.capacity = Math.max(1, capacity);
+	}
+
+	install(): void {
+		if (this.installed) return;
+		this.installed = true;
+		const console_ = console as unknown as Record<
+			"log" | "info" | "warn" | "error",
+			(...args: unknown[]) => void
+		>;
+		for (const level of ["log", "info", "warn", "error"] as const) {
+			this.originals[level] = console_[level].bind(console);
+			console_[level] = (...args: unknown[]) => {
+				this.push(level, args);
+				this.originals[level]?.(...args);
+			};
+		}
+	}
+
+	uninstall(): void {
+		if (!this.installed) return;
+		this.installed = false;
+		const console_ = console as unknown as Record<
+			"log" | "info" | "warn" | "error",
+			(...args: unknown[]) => void
+		>;
+		for (const level of ["log", "info", "warn", "error"] as const) {
+			if (this.originals[level]) {
+				console_[level] = this.originals[level] as (...args: unknown[]) => void;
+			}
+		}
+		this.originals.log = undefined;
+		this.originals.info = undefined;
+		this.originals.warn = undefined;
+		this.originals.error = undefined;
+	}
+
+	snapshot(): MainLogEntry[] {
+		return this.entries.slice();
+	}
+
+	clear(): void {
+		this.entries.length = 0;
+	}
+
+	private push(level: MainLogEntry["level"], args: unknown[]): void {
+		const text = args
+			.map((arg) => {
+				if (typeof arg === "string") return arg;
+				try {
+					return JSON.stringify(arg);
+				} catch {
+					return String(arg);
+				}
+			})
+			.join(" ");
+		this.entries.push({ timestampMs: Date.now(), level, text });
+		if (this.entries.length > this.capacity) {
+			this.entries.splice(0, this.entries.length - this.capacity);
+		}
+	}
+}
+
+export const mainLogBuffer = new MainLogBuffer();
+
+export function isDiagnosticModeEnabled(): boolean {
+	const raw = process.env.OPENSCREEN_DIAGNOSTIC;
+	if (!raw) return false;
+	const lowered = raw.trim().toLowerCase();
+	return lowered === "1" || lowered === "true" || lowered === "yes";
+}