GitStudioHQ · antonarnaudov · Aug 26, 2026 · Aug 27, 2026 · Aug 27, 2026 · Aug 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,13 @@ release/
 # Claude Code's per-repo scratch area. It holds nested git worktrees, so a single
 # `git add -A` would otherwise commit entire checkouts into this repo.
 .claude/
+
+# A literal "~" directory, created by an unquoted ~ in a shell command and
+# then swept in by `git add -A`. It held npm logs, not source.
+~/
+
+# A 584KB minified main-process bundle that `npm run package` drops beside
+# package.json. The real output is dist/main/main.js (which package.json's
+# "main" points at, and which dist/ already ignores); this copy is a build
+# side-effect and `git add -A` swept it in.
+apps/desktop/main.js
diff --git a/apps/desktop/harness/.gitignore b/apps/desktop/harness/.gitignore
@@ -0,0 +1,2 @@
+page/
+out/
diff --git a/apps/desktop/harness/README.md b/apps/desktop/harness/README.md
@@ -0,0 +1,37 @@
+# Headless render harness
+
+Runs the WHOLE desktop renderer in plain headless Chrome against realistic
+fixtures — no Electron, no GitHub, no repo. This is how UI work on the desktop
+app gets **seen** before it ships: every view, both themes, list and detail
+states, driven by scripted scenes.
+
+```sh
+cd apps/desktop
+node esbuild.js          # build the renderer bundles
+harness/gen.sh           # assemble harness/page from dist + shim.js
+harness/shot.sh issues out/issues.png            # screenshot a scene
+harness/shot.sh 'issues~open31' out/detail.png   # …with driver steps
+harness/shot.sh 'prs~open106~click:.gh-subtab%5Bdata-sub%3Dfiles%5D' out/files.png
+harness/shot.sh issues out/light.png light       # light theme
+```
+
+## Functional checks
+
+Screenshots prove a surface renders. They do not prove the count badge tracks
+the filter, that a disabled button is disabled, that a menu is dismissed on
+navigation, or that two columns share an x — those are assertions.
+
+```sh
+node harness/check.mjs                 # every case
+node harness/check.mjs count palette   # only cases matching these substrings
+```
+
+Each case names a scene and an assertion from `checks.js`, which runs INSIDE
+the page after the scene driver finishes and returns a list of failures. The
+runner exits non-zero if anything fails, so it can gate a commit. Add a case by
+writing the assertion in `checks.js` and listing `[id, scene]` in `check.mjs`.
+
+`shim.js` fakes the preload's `window.gitstudio` bridge (see `shared/ipc.ts`)
+with fixtures for the GitStudio repo itself. Unstubbed channels log
+`[shim missing] <channel>` to the console and resolve safely — add a fixture
+when a view needs one. `harness/page/` and `harness/out/` are generated.
diff --git a/apps/desktop/harness/check.mjs b/apps/desktop/harness/check.mjs
diff --git a/apps/desktop/harness/checks.js b/apps/desktop/harness/checks.js
diff --git a/apps/desktop/harness/gen.sh b/apps/desktop/harness/gen.sh
@@ -0,0 +1,45 @@
+#!/bin/sh
+# Assemble the headless-render harness page from the built renderer bundles +
+# the fixtures shim. Run `npm run build` (or `node esbuild.js`) first.
+#
+#   gen.sh [outDir]
+#
+# The optional outDir lets a second page exist alongside the default one, so a
+# verification run can use a freshly built bundle while something else is still
+# reading the old one. shot.sh and probe.mjs both honour $GS_HARNESS_PAGE.
+set -e
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+# BUILD FIRST. This script only COPIES the bundle, and forgetting the build
+# before it is the single most expensive mistake in this harness: a check runs
+# against the previous bundle, and reports a fix as not working (or, worse, a
+# reverted fix as still working, which is a negative test that lies). Set
+# GS_NO_BUILD=1 to skip it when you have just built by hand.
+if [ -z "$GS_NO_BUILD" ]; then
+  (cd "$HARNESS/.." && node esbuild.js >/dev/null)
+fi
+DIST="$(cd "$HARNESS/../dist/renderer" && pwd)"
+PAGE="${1:-$HARNESS/page}"
+rm -rf "$PAGE"
+mkdir -p "$PAGE"
+cp "$DIST/renderer.js" "$DIST/renderer.css" "$DIST/theme-boot.js" "$PAGE/"
+cp "$DIST"/brand-*.svg "$DIST"/icon*.png "$PAGE/" 2>/dev/null || true
+cp "$HARNESS/shim.js" "$PAGE/shim.js"
+cp "$HARNESS/checks.js" "$PAGE/checks.js"
+cat > "$PAGE/harness.html" <<'HTML'
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="stylesheet" href="./renderer.css" />
+    <title>GitStudio harness</title>
+  </head>
+  <body>
+    <script src="./theme-boot.js"></script>
+    <div id="root"><div id="boot">Loading GitStudio…</div></div>
+    <script src="./checks.js"></script>
+    <script src="./shim.js"></script>
+    <script src="./renderer.js"></script>
+  </body>
+</html>
+HTML
+echo "harness page at $PAGE/harness.html"
diff --git a/apps/desktop/harness/probe.mjs b/apps/desktop/harness/probe.mjs
@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Ask a rendered scene a question.
+//
+// shot.sh shows you what a surface LOOKS like; check.mjs asserts a named
+// invariant. Neither lets you simply measure something — "how wide is that
+// column", "does that button have an accessible name", "what does the focus
+// ring compute to in light theme" — without first editing the shared checks
+// file, which is impossible when several people are investigating at once.
+//
+//   node harness/probe.mjs '<scene>' '<js>' [--theme=light] [--width=1150]
+//                                            [--extra=staging=checkboxes]
+//
+// The <js> body runs INSIDE the driven page after its steps have played, with
+// `await` available; whatever it returns is JSON-printed. Helpers in scope:
+//
+//   $(sel[, root])   querySelector
+//   $$(sel[, root])  querySelectorAll as an array
+//   box(sel|el)      {x,y,w,h,right,bottom} rounded, or null
+//   css(sel|el, ...props)  computed styles as an object
+//   text(sel|el)     trimmed textContent
+//   settle(ms)       await a repaint/timeout
+//
+// Examples:
+//   node harness/probe.mjs issues 'return $$(".sec-row").length'
+//   node harness/probe.mjs 'prs~open106' 'return box(".det-title")'
+//   node harness/probe.mjs changes 'return css(".dc-file", "color", "font-size")' --theme=light
+//   node harness/probe.mjs code 'return $$("button").filter(b=>!b.textContent.trim()&&!b.title).length'
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PAGE = process.env.GS_HARNESS_PAGE
+  ? resolve(process.env.GS_HARNESS_PAGE, "harness.html")
+  : resolve(HERE, "page/harness.html");
+const CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+
+const argv = process.argv.slice(2);
+const flags = Object.fromEntries(
+  argv.filter((a) => a.startsWith("--")).map((a) => {
+    // Split on the FIRST "=" only: --extra=staging=checkboxes is one flag whose
+    // value is itself a query fragment.
+    const raw = a.slice(2);
+    const at = raw.indexOf("=");
+    return at < 0 ? [raw, "true"] : [raw.slice(0, at), raw.slice(at + 1)];
+  }),
+);
+const positional = argv.filter((a) => !a.startsWith("--"));
+const scene = positional[0];
+const body = positional[1];
+
+if (!scene || !body) {
+  console.error("usage: node harness/probe.mjs '<scene>' '<js body>' [--theme=light] [--width=N]");
+  process.exit(2);
+}
+if (!existsSync(PAGE)) {
+  console.error("harness/page is not built — run: node esbuild.js && harness/gen.sh");
+  process.exit(2);
+}
+
+const theme = flags.theme ?? "dark";
+const width = Number(flags.width ?? 1600);
+const height = Number(flags.height ?? 1000);
+
+// The helpers are prepended to the probe body so every caller has the same
+// vocabulary; keeping them here (not in the shim) means the shim stays the
+// scene DRIVER and this file owns the inspection language.
+const PRELUDE = `
+const $ = (s, r) => (r || document).querySelector(s);
+const $$ = (s, r) => [...(r || document).querySelectorAll(s)];
+const _el = (x) => (typeof x === "string" ? $(x) : x);
+const box = (x) => {
+  const n = _el(x); if (!n) return null;
+  const r = n.getBoundingClientRect();
+  return { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width),
+           h: Math.round(r.height), right: Math.round(r.right), bottom: Math.round(r.bottom) };
+};
+const css = (x, ...props) => {
+  const n = _el(x); if (!n) return null;
+  const s = getComputedStyle(n); const o = {};
+  for (const p of props) o[p] = s.getPropertyValue(p) || s[p];
+  return o;
+};
+const text = (x) => { const n = _el(x); return n ? (n.textContent || "").trim() : null; };
+const settle = (ms = 200) => new Promise((r) => setTimeout(r, ms));
+`;
+
+const probe = encodeURIComponent(PRELUDE + "\n" + body);
+// --extra=k=v[&k=v] appends the shim's own scene switches (staging=checkboxes,
+// many=1, ask=1) so a mode reachable only through a pref can still be measured.
+const extra = flags.extra ? `&${flags.extra}` : "";
+const url = `file://${PAGE}?scene=${scene}&theme=${theme}&probe=${probe}${extra}`;
+
+execFile(
+  CHROME,
+  [
+    "--headless",
+    "--disable-gpu",
+    "--hide-scrollbars",
+    `--window-size=${width},${height}`,
+    "--virtual-time-budget=12000",
+    "--dump-dom",
+    url,
+  ],
+  // Same guard check.mjs carries: a page that never lets virtual time run out
+  // hangs headless Chrome forever, and a probe that never returns is worse than
+  // one that fails — it hangs whatever asked the question.
+  { maxBuffer: 64 * 1024 * 1024, timeout: 90_000, killSignal: "SIGKILL" },
+  (err, stdout) => {
+    if (err && !stdout) {
+      console.error("chrome failed:", err.message);
+      process.exit(1);
+    }
+    const m = /<title>PROBE ([\s\S]*?)<\/title>/.exec(stdout);
+    if (!m) {
+      const t = /<title>([\s\S]*?)<\/title>/.exec(stdout);
+      console.error(`no probe result (title was ${JSON.stringify(t?.[1] ?? "")})`);
+      process.exit(1);
+    }
+    const decoded = m[1]
+      .replace(/&quot;/g, '"')
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&#39;/g, "'")
+      .replace(/&amp;/g, "&");
+    try {
+      const v = JSON.parse(decoded);
+      if (v && typeof v === "object" && v.error) {
+        console.error(v.error);
+        process.exit(1);
+      }
+      console.log(JSON.stringify(v, null, 2));
+    } catch {
+      console.log(decoded);
+    }
+  },
+);