From 5d2b4962077f73ffcb11e77d4d50602e0d005646 Mon Sep 17 00:00:00 2001
From: Guy J Grigsby <guy@grigsby.dev>
Date: Tue, 7 Jul 2026 14:22:43 -0600
Subject: [PATCH 1/8] Add light mode following the OS color scheme

---
 src/App.tsx    |  4 +++-
 src/styles.css | 39 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/src/App.tsx b/src/App.tsx
index 632758e..6f7f08a 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1247,7 +1247,9 @@ function DiffView() {
 
   const options = useMemo<CodeViewOptions<AnnotationMeta>>(
     () => ({
-      theme: 'github-dark-default',
+      // Dual theme: the library emits light-dark() CSS and resolves it from the
+      // page's color-scheme (see body in styles.css), so this follows the OS.
+      theme: { light: 'github-light-default', dark: 'github-dark-default' },
       diffStyle,
       // The library lays out collapsed files (and unmeasured estimates) from
       // these metrics rather than the DOM. Its diffHeaderHeight default (44)
diff --git a/src/styles.css b/src/styles.css
index 90a0516..578c152 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -59,6 +59,41 @@
     Consolas, 'Liberation Mono', monospace;
 }
 
+/* Light scheme, following the OS preference. Same token structure with the
+   elevation ramp inverted: on a light base, raised chrome steps DOWN in
+   lightness (white page, gray bars). --bg-code stays pure white to match the
+   github-light-default syntax theme background the diff bodies render with. */
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg-code: oklch(100% 0 0);
+    --bg-canvas: oklch(100% 0 0);
+    --bg-panel: oklch(97% 0.005 256);
+    --bg-muted: oklch(95.5% 0.006 256);
+    --bg-header: oklch(96% 0.006 256);
+    --bg-control: oklch(94% 0.007 256);
+    --bg-control-hover: oklch(90.5% 0.009 256);
+
+    --border: oklch(88% 0.01 256);
+    --border-soft: oklch(89.5% 0.009 256);
+    --border-strong: oklch(80% 0.013 256);
+    --border-muted: oklch(65% 0.016 256);
+
+    --fg: oklch(32% 0.02 250);
+    --fg-bright: oklch(21% 0.02 250);
+    --fg-dim: oklch(44% 0.02 250);
+    --fg-muted: oklch(52% 0.02 250);
+
+    /* Accent text/hover variants re-pinned darker for contrast on white;
+       base --blue/--green (used as fills under white text) work as-is. */
+    --blue-bright: oklch(52% 0.2 258);
+    --blue-text: oklch(47% 0.18 258);
+    --green-text: oklch(44% 0.14 146);
+    --red: oklch(53% 0.19 27);
+    --amber: oklch(58% 0.12 80);
+    --amber-deep: oklch(52% 0.11 78);
+  }
+}
+
 body {
   margin: 0;
   background: var(--bg-canvas);
@@ -67,7 +102,9 @@ body {
     -apple-system,
     sans-serif;
   color: var(--fg);
-  color-scheme: dark;
+  /* Drives both native widget rendering and the diff library's light-dark()
+     theme resolution inside its shadow roots. */
+  color-scheme: light dark;
 }
 
 /* Full-height layout so CodeView's single scroll container fills the viewport

From 57d3c49c3bb4df228868e64e813a8bcc7b2db29c Mon Sep 17 00:00:00 2001
From: Guy J Grigsby <guy@grigsby.dev>
Date: Tue, 7 Jul 2026 14:49:12 -0600
Subject: [PATCH 2/8] Add --theme flag to force light or dark regardless of OS

---
 cli.ts          |   9 ++-
 server/main.ts  |   5 +-
 shared/types.ts |   7 +++
 src/App.tsx     |  20 ++++++-
 src/styles.css  | 146 +++++++++++++++++++++++++-----------------------
 5 files changed, 111 insertions(+), 76 deletions(-)

diff --git a/cli.ts b/cli.ts
index 73ec4a4..3ca6228 100644
--- a/cli.ts
+++ b/cli.ts
@@ -10,7 +10,7 @@
 import { spawn, execFileSync } from 'child_process'
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { Command } from '@commander-js/extra-typings'
+import { Command, Option } from '@commander-js/extra-typings'
 import { startServer } from './server/main.ts'
 import type { DiffArgs, DiffEndpoints } from './shared/types.ts'
 
@@ -23,6 +23,11 @@ const program = new Command()
   .option('--git', 'force git mode (skip jj detection)')
   .option('--dev', 'run with Vite dev server for development')
   .option('--host <address>', 'address to bind the HTTP server to', 'localhost')
+  .addOption(
+    new Option('--theme <mode>', 'color scheme (e.g. light diffs on a dark desktop)')
+      .choices(['light', 'dark', 'system'] as const)
+      .default('system' as const),
+  )
   .argument('[files...]', 'Limit diff to these paths (passed through to jj/git)')
   .parse()
 
@@ -223,7 +228,7 @@ process.on('SIGINT', () => cleanup())
 process.on('SIGTERM', () => cleanup())
 
 const checkoutRoot = opts.dev ? requireCheckoutRoot() : undefined
-const apiPort = await startServer({ diffSource, cwd, hostname })
+const apiPort = await startServer({ diffSource, cwd, hostname, theme: opts.theme })
 
 function urlOpenCommand(url: string): { cmd: string; args: string[] } {
   switch (process.platform) {
diff --git a/server/main.ts b/server/main.ts
index dbe1295..5612f14 100644
--- a/server/main.ts
+++ b/server/main.ts
@@ -32,6 +32,7 @@ import type {
   FileContentsResponse,
   OkResponse,
   ErrorResponse,
+  ThemeMode,
 } from '../shared/types.ts'
 
 export async function startServer(opts: {
@@ -39,8 +40,9 @@ export async function startServer(opts: {
   port?: number
   hostname?: string
   cwd: string
+  theme?: ThemeMode
 }): Promise<number> {
-  const { diffSource, port = 0, hostname = 'localhost', cwd } = opts
+  const { diffSource, port = 0, hostname = 'localhost', cwd, theme = 'system' } = opts
   await validateDiffArgs(diffSource)
 
   const app = new Hono()
@@ -60,6 +62,7 @@ export async function startServer(opts: {
       fileHashes,
       viewed,
       commentSyntaxes,
+      theme,
     } satisfies DiffResponse)
   })
 
diff --git a/shared/types.ts b/shared/types.ts
index 8fdf925..5a2b385 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -48,6 +48,12 @@ export type ViewedRequest = z.infer<typeof viewedRequestSchema>
 export type CommentRequest = z.infer<typeof commentRequestSchema>
 export type CommentDeleteRequest = z.infer<typeof commentDeleteSchema>
 
+// --- UI types ---
+
+/** Color scheme from --theme. 'system' follows the OS preference; 'light' and
+ *  'dark' force it (e.g. light diffs on a dark desktop). */
+export type ThemeMode = 'light' | 'dark' | 'system'
+
 // --- VCS types ---
 
 /**
@@ -92,6 +98,7 @@ export interface DiffResponse {
    *  file type wasn't recognized. Both get bare review tags on insert. Always
    *  empty when comments are disabled. */
   commentSyntaxes: Record<string, CommentSyntax | null>
+  theme: ThemeMode
   error?: string
 }
 
diff --git a/src/App.tsx b/src/App.tsx
index 6f7f08a..8803c8c 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -759,6 +759,16 @@ function DiffView() {
     if (data?.revset) document.title = `skepsis | ${data.revset}`
   }, [data?.revset])
 
+  // --theme light/dark: pin color-scheme on the root, overriding the
+  // OS-following `light dark` from styles.css so our light-dark() tokens
+  // resolve to the forced side. The diff shadow roots are pinned separately
+  // via the CodeView themeType option.
+  useEffect(() => {
+    if (data?.theme && data.theme !== 'system') {
+      document.documentElement.style.colorScheme = data.theme
+    }
+  }, [data?.theme])
+
   // Seed collapse state from the first successful fetch: viewed files start collapsed
   useEffect(() => {
     if (seededFromInitialLoad.current || !data?.fileHashes) return
@@ -965,6 +975,7 @@ function DiffView() {
   ])
 
   const commentsEnabled = data?.commentsEnabled ?? false
+  const theme = data?.theme ?? 'system'
 
   const [showHelp, setShowHelp] = useState(false)
   const [showCommentsInfo, setShowCommentsInfo] = useState(false)
@@ -1247,9 +1258,12 @@ function DiffView() {
 
   const options = useMemo<CodeViewOptions<AnnotationMeta>>(
     () => ({
-      // Dual theme: the library emits light-dark() CSS and resolves it from the
-      // page's color-scheme (see body in styles.css), so this follows the OS.
+      // Dual theme: the library emits light-dark() CSS. themeType pins the
+      // shadow roots' color-scheme for forced themes — their :host base style
+      // is `color-scheme: light dark`, which re-resolves from the OS
+      // preference rather than inheriting the page's forced value.
       theme: { light: 'github-light-default', dark: 'github-dark-default' },
+      themeType: theme,
       diffStyle,
       // The library lays out collapsed files (and unmeasured estimates) from
       // these metrics rather than the DOM. Its diffHeaderHeight default (44)
@@ -1299,7 +1313,7 @@ function DiffView() {
         }
       },
     }),
-    [diffStyle, commentsEnabled, markSeen],
+    [diffStyle, commentsEnabled, markSeen, theme],
   )
 
   // Keyboard shortcuts. File navigation (n/p) and the focused-file actions
diff --git a/src/styles.css b/src/styles.css
index 578c152..94726ac 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -7,48 +7,92 @@
  */
 
 /*
- * Color tokens. Neutrals share a fixed hue (256) and chroma (.015) and vary
- * only in OKLCH lightness, so surfaces form one perceptually-even elevation
- * ramp: darker = recessed, lighter = raised. Controls (--bg-control) sit ABOVE
- * the header bar (--bg-header) so a button reads as resting on the bar rather
- * than punched into it. Borders are a separate low→high contrast ramp; accents
- * are four fixed hues with bright/text variants.
+ * Color tokens. Neutrals share a fixed hue (256) and low chroma and vary only
+ * in OKLCH lightness, so surfaces form one perceptually-even elevation ramp.
+ * Each token that differs by scheme is a light-dark(light, dark) pair; which
+ * side applies is driven by color-scheme (see :root below), so 'system'
+ * follows the OS and --theme light/dark forces it by setting an inline
+ * color-scheme on the root — the same property the diff library resolves its
+ * own light-dark() theme CSS from inside its shadow roots.
+ *
+ * Elevation runs opposite ways per scheme: dark = raised chrome steps LIGHTER
+ * (dark base, lifted bars); light = raised chrome steps DARKER (white page,
+ * gray bars, GitHub-style). Controls (--bg-control) sit one step past the
+ * header bar (--bg-header) so a button reads as resting on the bar rather
+ * than punched into it. Borders are a separate low→high contrast ramp;
+ * accents are four fixed hues with bright/text variants.
  */
 :root {
+  /* Drives light-dark() resolution here and native widget rendering, and is
+     inherited into the diff library's shadow roots. Forced themes override
+     this with an inline style (see App). */
+  color-scheme: light dark;
+
   /* Surfaces, ascending elevation. The page (--bg-canvas) matches the diff/code
-     base (--bg-code) so the code area doesn't read as an odd dark inset — the
-     whole app sits on one dark base and only chrome (header, controls) lifts off
-     it. Steps are small so raised elements stay dark rather than pasty-gray. */
-  --bg-code: oklch(17.5% 0.015 256); /* diff/code content, textarea — the base */
-  --bg-canvas: oklch(17.5% 0.015 256); /* page — same as the code base */
-  --bg-panel: oklch(22% 0.015 256); /* modal, comment form, separator band */
-  --bg-muted: oklch(24% 0.015 256); /* progress track, kbd, inline code chip */
-  --bg-header: oklch(26% 0.015 256); /* file header bar */
-  --bg-control: oklch(28.5% 0.015 256); /* buttons — just above the header */
-  --bg-control-hover: oklch(33% 0.015 256);
+     base (--bg-code) so the code area doesn't read as an odd inset — the whole
+     app sits on one base and only chrome (header, controls) steps off it.
+     Steps are small so raised elements stay close to the base rather than
+     pasty-gray. Light --bg-code is pure white to match the
+     github-light-default syntax theme background the diff bodies render with. */
+  --bg-code: light-dark(
+    oklch(100% 0 0),
+    oklch(17.5% 0.015 256)
+  ); /* diff/code, textarea — the base */
+  --bg-canvas: light-dark(
+    oklch(100% 0 0),
+    oklch(17.5% 0.015 256)
+  ); /* page — same as the code base */
+  --bg-panel: light-dark(
+    oklch(97% 0.005 256),
+    oklch(22% 0.015 256)
+  ); /* modal, comment form, separator band */
+  --bg-muted: light-dark(
+    oklch(95.5% 0.006 256),
+    oklch(24% 0.015 256)
+  ); /* progress track, kbd, inline code chip */
+  --bg-header: light-dark(oklch(96% 0.006 256), oklch(26% 0.015 256)); /* file header bar */
+  --bg-control: light-dark(
+    oklch(94% 0.007 256),
+    oklch(28.5% 0.015 256)
+  ); /* buttons — one step past the header */
+  --bg-control-hover: light-dark(oklch(90.5% 0.009 256), oklch(33% 0.015 256));
 
   /* Borders, low→high contrast against the surface they sit on. */
-  --border: oklch(33% 0.013 256); /* default, on dark surfaces */
-  --border-soft: oklch(32% 0.015 256); /* header strip — low contrast on the bar */
-  --border-strong: oklch(42% 0.016 256); /* control outlines */
-  --border-muted: oklch(56% 0.018 256); /* hover / emphasis */
+  --border: light-dark(oklch(88% 0.01 256), oklch(33% 0.013 256)); /* default */
+  --border-soft: light-dark(
+    oklch(89.5% 0.009 256),
+    oklch(32% 0.015 256)
+  ); /* header strip — low contrast on the bar */
+  --border-strong: light-dark(
+    oklch(80% 0.013 256),
+    oklch(42% 0.016 256)
+  ); /* control outlines */
+  --border-muted: light-dark(
+    oklch(65% 0.016 256),
+    oklch(56% 0.018 256)
+  ); /* hover / emphasis */
 
   /* Text, hue 250. */
-  --fg: oklch(86% 0.014 250);
-  --fg-bright: oklch(94% 0.012 250);
-  --fg-dim: oklch(77% 0.016 250); /* between muted and fg: de-emphasized but interactive */
-  --fg-muted: oklch(66% 0.018 250);
-
-  /* Accents: base / brighter (hover) / lighter (text-on-dark). */
+  --fg: light-dark(oklch(32% 0.02 250), oklch(86% 0.014 250));
+  --fg-bright: light-dark(oklch(21% 0.02 250), oklch(94% 0.012 250));
+  --fg-dim: light-dark(
+    oklch(44% 0.02 250),
+    oklch(77% 0.016 250)
+  ); /* between muted and fg: de-emphasized but interactive */
+  --fg-muted: light-dark(oklch(52% 0.02 250), oklch(66% 0.018 250));
+
+  /* Accents: base / bright (hover) / text (on the scheme's surfaces). Bases
+     used as fills under white text (--blue, --green) hold in both schemes;
+     hover and text variants swing toward the scheme's contrast direction. */
   --blue: oklch(57% 0.2 260);
-  --blue-bright: oklch(65% 0.19 257);
-  --blue-text: oklch(72% 0.15 253);
+  --blue-bright: light-dark(oklch(52% 0.2 258), oklch(65% 0.19 257));
+  --blue-text: light-dark(oklch(47% 0.18 258), oklch(72% 0.15 253));
   --green: oklch(55% 0.15 146);
   --green-bright: oklch(62% 0.17 146);
-  --green-text: oklch(69% 0.18 146);
-  --red: oklch(66% 0.2 27);
-  --amber: oklch(72% 0.14 80);
-  --amber-deep: oklch(56% 0.12 78);
+  --green-text: light-dark(oklch(44% 0.14 146), oklch(69% 0.18 146));
+  --red: light-dark(oklch(53% 0.19 27), oklch(66% 0.2 27));
+  --amber: light-dark(oklch(58% 0.12 80), oklch(72% 0.14 80));
+  --amber-deep: light-dark(oklch(52% 0.11 78), oklch(56% 0.12 78));
 
   /* Monospace stack. Berkeley Mono first for those who have it, then each OS's
      best system mono (ui-monospace → SF Mono on macOS, Consolas/Cascadia on
@@ -59,41 +103,6 @@
     Consolas, 'Liberation Mono', monospace;
 }
 
-/* Light scheme, following the OS preference. Same token structure with the
-   elevation ramp inverted: on a light base, raised chrome steps DOWN in
-   lightness (white page, gray bars). --bg-code stays pure white to match the
-   github-light-default syntax theme background the diff bodies render with. */
-@media (prefers-color-scheme: light) {
-  :root {
-    --bg-code: oklch(100% 0 0);
-    --bg-canvas: oklch(100% 0 0);
-    --bg-panel: oklch(97% 0.005 256);
-    --bg-muted: oklch(95.5% 0.006 256);
-    --bg-header: oklch(96% 0.006 256);
-    --bg-control: oklch(94% 0.007 256);
-    --bg-control-hover: oklch(90.5% 0.009 256);
-
-    --border: oklch(88% 0.01 256);
-    --border-soft: oklch(89.5% 0.009 256);
-    --border-strong: oklch(80% 0.013 256);
-    --border-muted: oklch(65% 0.016 256);
-
-    --fg: oklch(32% 0.02 250);
-    --fg-bright: oklch(21% 0.02 250);
-    --fg-dim: oklch(44% 0.02 250);
-    --fg-muted: oklch(52% 0.02 250);
-
-    /* Accent text/hover variants re-pinned darker for contrast on white;
-       base --blue/--green (used as fills under white text) work as-is. */
-    --blue-bright: oklch(52% 0.2 258);
-    --blue-text: oklch(47% 0.18 258);
-    --green-text: oklch(44% 0.14 146);
-    --red: oklch(53% 0.19 27);
-    --amber: oklch(58% 0.12 80);
-    --amber-deep: oklch(52% 0.11 78);
-  }
-}
-
 body {
   margin: 0;
   background: var(--bg-canvas);
@@ -102,9 +111,6 @@ body {
     -apple-system,
     sans-serif;
   color: var(--fg);
-  /* Drives both native widget rendering and the diff library's light-dark()
-     theme resolution inside its shadow roots. */
-  color-scheme: light dark;
 }
 
 /* Full-height layout so CodeView's single scroll container fills the viewport

From deeee18a1ba0fa8150b25a28523b7c1f770cd875 Mon Sep 17 00:00:00 2001
From: Guy J Grigsby <guy@grigsby.dev>
Date: Tue, 7 Jul 2026 14:54:45 -0600
Subject: [PATCH 3/8] Trim the token header comment per review

---
 src/styles.css | 23 +++++++++--------------
 1 file changed, 9 insertions(+), 14 deletions(-)

diff --git a/src/styles.css b/src/styles.css
index 94726ac..f8e3745 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -7,20 +7,15 @@
  */
 
 /*
- * Color tokens. Neutrals share a fixed hue (256) and low chroma and vary only
- * in OKLCH lightness, so surfaces form one perceptually-even elevation ramp.
- * Each token that differs by scheme is a light-dark(light, dark) pair; which
- * side applies is driven by color-scheme (see :root below), so 'system'
- * follows the OS and --theme light/dark forces it by setting an inline
- * color-scheme on the root — the same property the diff library resolves its
- * own light-dark() theme CSS from inside its shadow roots.
- *
- * Elevation runs opposite ways per scheme: dark = raised chrome steps LIGHTER
- * (dark base, lifted bars); light = raised chrome steps DARKER (white page,
- * gray bars, GitHub-style). Controls (--bg-control) sit one step past the
- * header bar (--bg-header) so a button reads as resting on the bar rather
- * than punched into it. Borders are a separate low→high contrast ramp;
- * accents are four fixed hues with bright/text variants.
+ * Color tokens, a light-dark(light, dark) pair per token, resolved by
+ * color-scheme on :root: 'light dark' follows the OS, and --theme pins it
+ * with an inline style (see App) — the diff library's shadow roots resolve
+ * their theme CSS from the same property. Neutrals share one hue and vary
+ * only in OKLCH lightness, so surfaces form an elevation ramp: raised chrome
+ * steps away from the page background, with controls (--bg-control) one step
+ * past the header bar (--bg-header) so a button reads as resting on the bar.
+ * Borders are a separate low→high contrast ramp; accents are four fixed hues
+ * with bright/text variants.
  */
 :root {
   /* Drives light-dark() resolution here and native widget rendering, and is

From ebde487537f3769d94b2ecf2b5bc2a37d50a36e8 Mon Sep 17 00:00:00 2001
From: Guy J Grigsby <guy@grigsby.dev>
Date: Tue, 7 Jul 2026 15:23:58 -0600
Subject: [PATCH 4/8] Deliver forced theme on the URL, not the diff response

The theme is known at server start but was riding on /api/diff, so a
forced scheme applied only after the slowest request resolved (OS-scheme
flash for the whole diff run) and never applied at all when the fetch
failed. Carry it as ?theme= on the URL the CLI opens and read it at
module load, before first paint. Deletes the server and DiffResponse
plumbing; THEME_MODES in shared/types.ts now drives the CLI choices and
the client's param validation from one list.

A forced theme now also passes a single CodeView theme instead of the
dual object: Shiki tokenizes once instead of once per theme (the dual
path runs a full grammar pass per theme and ships both themes' token
styles even though a pinned color-scheme can only ever render one).

Also reorder the error guard above the loading guard: a failed fetch
settles with data undefined, so the loading-first check showed
'Loading...' forever and the error branch was unreachable.
---
 cli.ts          | 14 ++++++++++----
 server/main.ts  |  5 +----
 shared/types.ts |  7 ++++---
 src/App.tsx     | 48 ++++++++++++++++++++++++++++++------------------
 4 files changed, 45 insertions(+), 29 deletions(-)

diff --git a/cli.ts b/cli.ts
index 3ca6228..d934c26 100644
--- a/cli.ts
+++ b/cli.ts
@@ -12,6 +12,7 @@ import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { Command, Option } from '@commander-js/extra-typings'
 import { startServer } from './server/main.ts'
+import { THEME_MODES } from './shared/types.ts'
 import type { DiffArgs, DiffEndpoints } from './shared/types.ts'
 
 const program = new Command()
@@ -25,7 +26,7 @@ const program = new Command()
   .option('--host <address>', 'address to bind the HTTP server to', 'localhost')
   .addOption(
     new Option('--theme <mode>', 'color scheme (e.g. light diffs on a dark desktop)')
-      .choices(['light', 'dark', 'system'] as const)
+      .choices(THEME_MODES)
       .default('system' as const),
   )
   .argument('[files...]', 'Limit diff to these paths (passed through to jj/git)')
@@ -228,7 +229,7 @@ process.on('SIGINT', () => cleanup())
 process.on('SIGTERM', () => cleanup())
 
 const checkoutRoot = opts.dev ? requireCheckoutRoot() : undefined
-const apiPort = await startServer({ diffSource, cwd, hostname, theme: opts.theme })
+const apiPort = await startServer({ diffSource, cwd, hostname })
 
 function urlOpenCommand(url: string): { cmd: string; args: string[] } {
   switch (process.platform) {
@@ -246,9 +247,14 @@ function urlOpenCommand(url: string): { cmd: string; args: string[] } {
 // — opening locally would just spawn an unwanted browser.
 const shouldAutoOpen = hostname === 'localhost'
 
+// A forced theme rides on the URL so the client can apply it before first
+// paint, with no dependency on the (slow, fallible) diff fetch. A hand-typed
+// bare URL falls back to the OS scheme.
+const themeQuery = opts.theme === 'system' ? '' : `/?theme=${opts.theme}`
+
 if (opts.dev) {
   const viteArgs = ['vite', '--host', hostname]
-  if (shouldAutoOpen) viteArgs.push('--open')
+  if (shouldAutoOpen) viteArgs.push('--open', themeQuery || '/')
   const vite = spawn('npx', viteArgs, {
     cwd: checkoutRoot,
     stdio: 'inherit',
@@ -256,7 +262,7 @@ if (opts.dev) {
   })
   children.push(vite)
 } else if (shouldAutoOpen) {
-  const url = `http://localhost:${apiPort}`
+  const url = `http://localhost:${apiPort}${themeQuery}`
   const { cmd, args } = urlOpenCommand(url)
   const opener = spawn(cmd, args, { detached: true, stdio: 'ignore' })
   opener.on('error', (err) => {
diff --git a/server/main.ts b/server/main.ts
index 5612f14..dbe1295 100644
--- a/server/main.ts
+++ b/server/main.ts
@@ -32,7 +32,6 @@ import type {
   FileContentsResponse,
   OkResponse,
   ErrorResponse,
-  ThemeMode,
 } from '../shared/types.ts'
 
 export async function startServer(opts: {
@@ -40,9 +39,8 @@ export async function startServer(opts: {
   port?: number
   hostname?: string
   cwd: string
-  theme?: ThemeMode
 }): Promise<number> {
-  const { diffSource, port = 0, hostname = 'localhost', cwd, theme = 'system' } = opts
+  const { diffSource, port = 0, hostname = 'localhost', cwd } = opts
   await validateDiffArgs(diffSource)
 
   const app = new Hono()
@@ -62,7 +60,6 @@ export async function startServer(opts: {
       fileHashes,
       viewed,
       commentSyntaxes,
-      theme,
     } satisfies DiffResponse)
   })
 
diff --git a/shared/types.ts b/shared/types.ts
index 5a2b385..e3e7e36 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -51,8 +51,10 @@ export type CommentDeleteRequest = z.infer<typeof commentDeleteSchema>
 // --- UI types ---
 
 /** Color scheme from --theme. 'system' follows the OS preference; 'light' and
- *  'dark' force it (e.g. light diffs on a dark desktop). */
-export type ThemeMode = 'light' | 'dark' | 'system'
+ *  'dark' force it (e.g. light diffs on a dark desktop). One list drives both
+ *  the CLI's --theme choices and the client's URL-param validation. */
+export const THEME_MODES = ['light', 'dark', 'system'] as const
+export type ThemeMode = (typeof THEME_MODES)[number]
 
 // --- VCS types ---
 
@@ -98,7 +100,6 @@ export interface DiffResponse {
    *  file type wasn't recognized. Both get bare review tags on insert. Always
    *  empty when comments are disabled. */
   commentSyntaxes: Record<string, CommentSyntax | null>
-  theme: ThemeMode
   error?: string
 }
 
diff --git a/src/App.tsx b/src/App.tsx
index 8803c8c..b6ccf49 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -37,10 +37,12 @@ import type {
   LineAnnotation,
   SelectedLineRange,
 } from '@pierre/diffs'
+import { THEME_MODES } from '../shared/types.ts'
 import type {
   DiffResponse,
   ErrorResponse,
   FileContentsResponse,
+  ThemeMode,
   ViewedMap,
   FileHashes,
 } from '../shared/types.ts'
@@ -54,6 +56,18 @@ import {
 
 const queryClient = new QueryClient()
 
+// --theme rides on the URL the CLI opens (?theme=light|dark) so a forced
+// scheme applies at module load — before first paint, and independent of the
+// diff fetch (which is slow and can fail). Pinning color-scheme on the root
+// overrides the OS-following `light dark` from styles.css so our light-dark()
+// tokens resolve to the forced side; the diff shadow roots are pinned
+// separately via the CodeView theme/themeType options.
+const themeParam = new URLSearchParams(location.search).get('theme')
+const theme: ThemeMode = (THEME_MODES as readonly (string | null)[]).includes(themeParam)
+  ? (themeParam as ThemeMode)
+  : 'system'
+if (theme !== 'system') document.documentElement.style.colorScheme = theme
+
 async function apiFetch<T = unknown>(
   url: string,
   opts: { method: string; body?: unknown } = { method: 'GET' },
@@ -759,16 +773,6 @@ function DiffView() {
     if (data?.revset) document.title = `skepsis | ${data.revset}`
   }, [data?.revset])
 
-  // --theme light/dark: pin color-scheme on the root, overriding the
-  // OS-following `light dark` from styles.css so our light-dark() tokens
-  // resolve to the forced side. The diff shadow roots are pinned separately
-  // via the CodeView themeType option.
-  useEffect(() => {
-    if (data?.theme && data.theme !== 'system') {
-      document.documentElement.style.colorScheme = data.theme
-    }
-  }, [data?.theme])
-
   // Seed collapse state from the first successful fetch: viewed files start collapsed
   useEffect(() => {
     if (seededFromInitialLoad.current || !data?.fileHashes) return
@@ -975,7 +979,6 @@ function DiffView() {
   ])
 
   const commentsEnabled = data?.commentsEnabled ?? false
-  const theme = data?.theme ?? 'system'
 
   const [showHelp, setShowHelp] = useState(false)
   const [showCommentsInfo, setShowCommentsInfo] = useState(false)
@@ -1258,11 +1261,18 @@ function DiffView() {
 
   const options = useMemo<CodeViewOptions<AnnotationMeta>>(
     () => ({
-      // Dual theme: the library emits light-dark() CSS. themeType pins the
-      // shadow roots' color-scheme for forced themes — their :host base style
-      // is `color-scheme: light dark`, which re-resolves from the OS
-      // preference rather than inheriting the page's forced value.
-      theme: { light: 'github-light-default', dark: 'github-dark-default' },
+      // In system mode the dual theme makes the library emit light-dark()
+      // CSS that follows the OS (the shadow roots' :host base style is
+      // `color-scheme: light dark`; they don't inherit the page's value). A
+      // forced theme passes a single theme instead: Shiki then tokenizes once
+      // rather than once per theme, and the theme's own type pins the shadow
+      // roots' color-scheme.
+      theme:
+        theme === 'system'
+          ? { light: 'github-light-default', dark: 'github-dark-default' }
+          : theme === 'light'
+            ? 'github-light-default'
+            : 'github-dark-default',
       themeType: theme,
       diffStyle,
       // The library lays out collapsed files (and unmeasured estimates) from
@@ -1313,7 +1323,7 @@ function DiffView() {
         }
       },
     }),
-    [diffStyle, commentsEnabled, markSeen, theme],
+    [diffStyle, commentsEnabled, markSeen],
   )
 
   // Keyboard shortcuts. File navigation (n/p) and the focused-file actions
@@ -1541,8 +1551,10 @@ function DiffView() {
     markProgrammaticScroll,
   ])
 
-  if (isLoading || !data) return <div className="empty-diff">Loading...</div>
+  // Error before loading: on a failed fetch react-query settles with `data`
+  // undefined, so a loading-first guard would show "Loading..." forever.
   if (error) return <pre style={{ color: 'red', padding: 20 }}>{String(error)}</pre>
+  if (isLoading || !data) return <div className="empty-diff">Loading...</div>
   if (data.error) return <pre style={{ color: 'red', padding: 20 }}>{data.error}</pre>
   if (!patch)
     return (

From 208064e46cf61a39aed08d8c42762a4a2b774796 Mon Sep 17 00:00:00 2001
From: Guy J Grigsby <guy@grigsby.dev>
Date: Tue, 7 Jul 2026 15:24:24 -0600
Subject: [PATCH 5/8] Give --green-bright and --amber light arms that darken

Both were left fixed at their dark values in the light-dark()
conversion. In light mode the primary button hover lightened under
white text (contrast dropping to about 3.6:1, opposite hover direction
from --blue-bright) and the stale viewed label rendered about 3.6:1 on
the control surface. Darken both light arms to 50% L, in line with the
other accent text variants.
---
 src/styles.css | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/styles.css b/src/styles.css
index f8e3745..9e3a10c 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -83,10 +83,10 @@
   --blue-bright: light-dark(oklch(52% 0.2 258), oklch(65% 0.19 257));
   --blue-text: light-dark(oklch(47% 0.18 258), oklch(72% 0.15 253));
   --green: oklch(55% 0.15 146);
-  --green-bright: oklch(62% 0.17 146);
+  --green-bright: light-dark(oklch(50% 0.15 146), oklch(62% 0.17 146));
   --green-text: light-dark(oklch(44% 0.14 146), oklch(69% 0.18 146));
   --red: light-dark(oklch(53% 0.19 27), oklch(66% 0.2 27));
-  --amber: light-dark(oklch(58% 0.12 80), oklch(72% 0.14 80));
+  --amber: light-dark(oklch(50% 0.12 80), oklch(72% 0.14 80));
   --amber-deep: light-dark(oklch(52% 0.11 78), oklch(56% 0.12 78));
 
   /* Monospace stack. Berkeley Mono first for those who have it, then each OS's

From cb56bcc1b2820b3ea64f65769b7eb0795af3e2a0 Mon Sep 17 00:00:00 2001
From: Guy J Grigsby <guy@grigsby.dev>
Date: Tue, 7 Jul 2026 18:19:19 -0600
Subject: [PATCH 6/8] Keep light-dark() untransformed in the production CSS

Vite's default cssTarget predates light-dark(), so esbuild lowered every
token pair to a prefers-color-scheme polyfill that follows the OS and
ignores the color-scheme --theme pins. Dev serves the raw CSS, which is
why the bug only showed in the built package: forced light rendered the
diff bodies light (the library generates its CSS at runtime) but left
the page chrome dark. Raise cssTarget to the first versions with
light-dark() support; not a new floor in practice, since the diff
library already emits light-dark() at runtime.
---
 vite.config.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/vite.config.ts b/vite.config.ts
index b0ffdef..f11baa7 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -19,6 +19,12 @@ export default defineConfig({
   plugins: [react()],
   build: {
     outDir: 'dist/web',
+    // Vite's default cssTarget predates light-dark(), so esbuild lowers it
+    // to a prefers-color-scheme polyfill that follows the OS and ignores the
+    // forced color-scheme --theme sets. Target the first versions with
+    // light-dark() support so it ships untransformed. Not a new floor in
+    // practice: the diff library already emits light-dark() at runtime.
+    cssTarget: ['chrome123', 'firefox120', 'safari17.5'],
   },
   server: {
     proxy: {

From 4a129b8f178801f02066556d8d3421b56d2c58e6 Mon Sep 17 00:00:00 2001
From: David Crespo <david.crespo@oxidecomputer.com>
Date: Wed, 8 Jul 2026 11:14:17 -0500
Subject: [PATCH 7/8] Theme toggle with server-side persistence (replaces
 --theme flag)

---
 CLAUDE.md               |   6 +-
 cli.ts                  |  17 +----
 index.html              |   5 ++
 server/main.ts          |  21 +++++
 server/settings.test.ts |  67 ++++++++++++++++
 server/settings.ts      |  49 ++++++++++++
 shared/types.ts         |  12 ++-
 src/App.tsx             | 165 ++++++++++++++++++++++++++++++++++------
 src/styles.css          |  75 +++++++++++++++---
 vite.config.ts          |   6 --
 10 files changed, 365 insertions(+), 58 deletions(-)
 create mode 100644 server/settings.test.ts
 create mode 100644 server/settings.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 9090721..7e84ec6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,7 +30,11 @@ cli.ts                CLI entry (commander). Detects jj/git, builds DiffArgs
                       starts the API server, spawns Vite in --dev mode.
 server/
   main.ts             Hono server. GET /api/diff; POST/DELETE /api/viewed;
-                      POST/DELETE /api/comment; serves dist/web statics.
+                      POST/DELETE /api/comment; GET/POST /api/theme;
+                      GET /api/theme.js (pre-first-paint theme boot script
+                      loaded by index.html); serves dist/web statics.
+  settings.ts         Global (not per-repo) UI settings — currently just the
+                      theme — in ~/.local/share/skepsis/settings.json.
   diff.ts             Runs `jj diff --git`/`git diff`, extracts per-file blob
                       hashes from index lines.
   viewed.ts           Viewed state, content-addressed by git blob ID — files
diff --git a/cli.ts b/cli.ts
index d934c26..73ec4a4 100644
--- a/cli.ts
+++ b/cli.ts
@@ -10,9 +10,8 @@
 import { spawn, execFileSync } from 'child_process'
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { Command, Option } from '@commander-js/extra-typings'
+import { Command } from '@commander-js/extra-typings'
 import { startServer } from './server/main.ts'
-import { THEME_MODES } from './shared/types.ts'
 import type { DiffArgs, DiffEndpoints } from './shared/types.ts'
 
 const program = new Command()
@@ -24,11 +23,6 @@ const program = new Command()
   .option('--git', 'force git mode (skip jj detection)')
   .option('--dev', 'run with Vite dev server for development')
   .option('--host <address>', 'address to bind the HTTP server to', 'localhost')
-  .addOption(
-    new Option('--theme <mode>', 'color scheme (e.g. light diffs on a dark desktop)')
-      .choices(THEME_MODES)
-      .default('system' as const),
-  )
   .argument('[files...]', 'Limit diff to these paths (passed through to jj/git)')
   .parse()
 
@@ -247,14 +241,9 @@ function urlOpenCommand(url: string): { cmd: string; args: string[] } {
 // — opening locally would just spawn an unwanted browser.
 const shouldAutoOpen = hostname === 'localhost'
 
-// A forced theme rides on the URL so the client can apply it before first
-// paint, with no dependency on the (slow, fallible) diff fetch. A hand-typed
-// bare URL falls back to the OS scheme.
-const themeQuery = opts.theme === 'system' ? '' : `/?theme=${opts.theme}`
-
 if (opts.dev) {
   const viteArgs = ['vite', '--host', hostname]
-  if (shouldAutoOpen) viteArgs.push('--open', themeQuery || '/')
+  if (shouldAutoOpen) viteArgs.push('--open')
   const vite = spawn('npx', viteArgs, {
     cwd: checkoutRoot,
     stdio: 'inherit',
@@ -262,7 +251,7 @@ if (opts.dev) {
   })
   children.push(vite)
 } else if (shouldAutoOpen) {
-  const url = `http://localhost:${apiPort}${themeQuery}`
+  const url = `http://localhost:${apiPort}`
   const { cmd, args } = urlOpenCommand(url)
   const opener = spawn(cmd, args, { detached: true, stdio: 'ignore' })
   opener.on('error', (err) => {
diff --git a/index.html b/index.html
index 38379e7..57ea737 100644
--- a/index.html
+++ b/index.html
@@ -12,6 +12,11 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>skepsis</title>
+    <!-- Sets data-theme from the stored preference. Deliberately a classic
+         (render-blocking) script so a forced theme applies before first
+         paint. Served by the API server; reaches it via the Vite proxy in
+         dev. -->
+    <script src="/api/theme.js"></script>
   </head>
   <body>
     <div id="root"></div>
diff --git a/server/main.ts b/server/main.ts
index dbe1295..36613ac 100644
--- a/server/main.ts
+++ b/server/main.ts
@@ -19,6 +19,7 @@ import { getFileContents } from './fileContents.ts'
 import { loadViewed, markViewed, unmarkViewed, unmarkViewedAll } from './viewed.ts'
 import { insertComment, removeComment } from './comment.ts'
 import { getCommentSyntaxes } from './commentSyntax.ts'
+import { loadTheme, saveTheme, themeBootScript } from './settings.ts'
 import {
   viewedRequestSchema,
   viewedDeleteSchema,
@@ -26,12 +27,14 @@ import {
   commentRequestSchema,
   commentDeleteSchema,
   fileContentsQuerySchema,
+  themeRequestSchema,
 } from '../shared/types.ts'
 import type {
   DiffResponse,
   FileContentsResponse,
   OkResponse,
   ErrorResponse,
+  ThemeResponse,
 } from '../shared/types.ts'
 
 export async function startServer(opts: {
@@ -99,6 +102,24 @@ export async function startServer(opts: {
     return c.json({ ok: true } satisfies OkResponse)
   })
 
+  app.get('/api/theme', async (c) => {
+    return c.json({ theme: await loadTheme() } satisfies ThemeResponse)
+  })
+
+  // Loaded by a render-blocking <script> in index.html (see themeBootScript).
+  // no-store: a cached copy would re-apply an old preference before React
+  // corrects it, flashing the wrong theme — the exact problem this solves.
+  app.get('/api/theme.js', async (c) => {
+    c.header('Cache-Control', 'no-store')
+    c.header('Content-Type', 'text/javascript')
+    return c.body(themeBootScript(await loadTheme()))
+  })
+
+  app.post('/api/theme', zValidator('json', themeRequestSchema), async (c) => {
+    await saveTheme(c.req.valid('json').theme)
+    return c.json({ ok: true } satisfies OkResponse)
+  })
+
   // Keep this path valid from source (`server/`) and from the published bundle
   // (`dist/cli.js`): both are one directory below the package root.
   const distDir = join(import.meta.dirname, '..', 'dist', 'web')
diff --git a/server/settings.test.ts b/server/settings.test.ts
new file mode 100644
index 0000000..6a4f64c
--- /dev/null
+++ b/server/settings.test.ts
@@ -0,0 +1,67 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, you can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright Oxide Computer Company
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+// Type-only, so it doesn't evaluate the module before HOME is stubbed.
+import type * as SettingsModule from './settings.ts'
+
+// The module derives its storage path from HOME at import time, so stub HOME
+// and import dynamically instead of statically.
+let home: string
+let settings: typeof SettingsModule
+
+beforeAll(async () => {
+  home = await mkdtemp(join(tmpdir(), 'skepsis-settings-'))
+  vi.stubEnv('HOME', home)
+  settings = await import('./settings.ts')
+})
+
+afterAll(async () => {
+  vi.unstubAllEnvs()
+  await rm(home, { recursive: true, force: true })
+})
+
+describe('loadTheme/saveTheme', () => {
+  it('defaults to system when the file is missing', async () => {
+    expect(await settings.loadTheme()).toBe('system')
+  })
+
+  it('round-trips a saved theme', async () => {
+    await settings.saveTheme('light')
+    expect(await settings.loadTheme()).toBe('light')
+    await settings.saveTheme('system')
+    expect(await settings.loadTheme()).toBe('system')
+  })
+
+  it('falls back to system on garbage', async () => {
+    const path = join(home, '.local', 'share', 'skepsis', 'settings.json')
+    await mkdir(join(home, '.local', 'share', 'skepsis'), { recursive: true })
+    await writeFile(path, 'not json')
+    expect(await settings.loadTheme()).toBe('system')
+    await writeFile(path, JSON.stringify({ theme: 'mauve' }))
+    expect(await settings.loadTheme()).toBe('system')
+  })
+})
+
+describe('themeBootScript', () => {
+  it('stamps a forced theme onto the html element', () => {
+    expect(settings.themeBootScript('light')).toBe(
+      "document.documentElement.dataset.theme = 'light'\n",
+    )
+    expect(settings.themeBootScript('dark')).toBe(
+      "document.documentElement.dataset.theme = 'dark'\n",
+    )
+  })
+
+  it('is empty for system', () => {
+    expect(settings.themeBootScript('system')).toBe('')
+  })
+})
diff --git a/server/settings.ts b/server/settings.ts
new file mode 100644
index 0000000..ee0c7f6
--- /dev/null
+++ b/server/settings.ts
@@ -0,0 +1,49 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, you can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright Oxide Computer Company
+ */
+
+/**
+ * Global UI settings at ~/.local/share/skepsis/settings.json. Unlike viewed
+ * state, settings are not per-repo (no cwd hashing): a theme preference is
+ * about the user, not the diff under review. Server-side storage is what
+ * makes the preference survive restarts at all — the ephemeral port means a
+ * fresh browser origin every run, so web storage can't.
+ */
+
+import { join } from 'path'
+import { mkdir, readFile, writeFile } from 'fs/promises'
+import { THEME_MODES } from '../shared/types.ts'
+import type { ThemeMode } from '../shared/types.ts'
+
+const BASE_DIR = join(process.env['HOME'] ?? '~', '.local', 'share', 'skepsis')
+const SETTINGS_PATH = join(BASE_DIR, 'settings.json')
+
+/** Missing file, unparseable JSON, or an unknown value → 'system'. */
+export async function loadTheme(): Promise<ThemeMode> {
+  try {
+    const raw: unknown = JSON.parse(await readFile(SETTINGS_PATH, 'utf-8'))
+    const theme = (raw as { theme?: unknown }).theme
+    if ((THEME_MODES as readonly unknown[]).includes(theme)) return theme as ThemeMode
+  } catch {
+    // fall through to the default
+  }
+  return 'system'
+}
+
+export async function saveTheme(theme: ThemeMode): Promise<void> {
+  await mkdir(BASE_DIR, { recursive: true })
+  await writeFile(SETTINGS_PATH, JSON.stringify({ theme }, null, 2) + '\n')
+}
+
+/** Body of /api/theme.js, loaded by a render-blocking <script> in index.html
+ *  so a forced theme's data-theme lands on <html> before first paint (CSS
+ *  keys color-scheme off the attribute). 'system' means no attribute: an
+ *  empty script leaves the page following the OS. */
+export function themeBootScript(theme: ThemeMode): string {
+  if (theme === 'system') return ''
+  return `document.documentElement.dataset.theme = '${theme}'\n`
+}
diff --git a/shared/types.ts b/shared/types.ts
index e3e7e36..30d8a93 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -50,12 +50,18 @@ export type CommentDeleteRequest = z.infer<typeof commentDeleteSchema>
 
 // --- UI types ---
 
-/** Color scheme from --theme. 'system' follows the OS preference; 'light' and
- *  'dark' force it (e.g. light diffs on a dark desktop). One list drives both
- *  the CLI's --theme choices and the client's URL-param validation. */
+/** Color scheme. 'system' follows the OS preference; 'light' and 'dark' force
+ *  it (e.g. light diffs on a dark desktop). One list drives the API schema,
+ *  the toggle cycle, and the client's data-theme validation. */
 export const THEME_MODES = ['light', 'dark', 'system'] as const
 export type ThemeMode = (typeof THEME_MODES)[number]
 
+export const themeRequestSchema = z.object({ theme: z.enum(THEME_MODES) })
+
+export interface ThemeResponse {
+  theme: ThemeMode
+}
+
 // --- VCS types ---
 
 /**
diff --git a/src/App.tsx b/src/App.tsx
index b6ccf49..0b99b82 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -43,6 +43,7 @@ import type {
   ErrorResponse,
   FileContentsResponse,
   ThemeMode,
+  ThemeResponse,
   ViewedMap,
   FileHashes,
 } from '../shared/types.ts'
@@ -56,17 +57,26 @@ import {
 
 const queryClient = new QueryClient()
 
-// --theme rides on the URL the CLI opens (?theme=light|dark) so a forced
-// scheme applies at module load — before first paint, and independent of the
-// diff fetch (which is slow and can fail). Pinning color-scheme on the root
-// overrides the OS-following `light dark` from styles.css so our light-dark()
-// tokens resolve to the forced side; the diff shadow roots are pinned
-// separately via the CodeView theme/themeType options.
-const themeParam = new URLSearchParams(location.search).get('theme')
-const theme: ThemeMode = (THEME_MODES as readonly (string | null)[]).includes(themeParam)
-  ? (themeParam as ThemeMode)
+// The /api/theme.js boot script in index.html stamps the stored theme
+// preference onto <html> as data-theme before this bundle loads, so CSS pins
+// color-scheme (and our light-dark() tokens resolve to the forced side)
+// before first paint. Read it back as the initial client state; /api/theme
+// is the source of truth from then on. The diff shadow roots don't inherit
+// the page's color-scheme and are pinned separately via the CodeView
+// themeType option.
+const themeAttr = document.documentElement.dataset['theme']
+const initialTheme: ThemeMode = (THEME_MODES as readonly (string | undefined)[]).includes(
+  themeAttr,
+)
+  ? (themeAttr as ThemeMode)
   : 'system'
-if (theme !== 'system') document.documentElement.style.colorScheme = theme
+
+function applyTheme(theme: ThemeMode) {
+  if (theme === 'system') delete document.documentElement.dataset['theme']
+  else document.documentElement.dataset['theme'] = theme
+}
+
+const THEME_CYCLE = { system: 'light', light: 'dark', dark: 'system' } as const
 
 async function apiFetch<T = unknown>(
   url: string,
@@ -395,7 +405,7 @@ function Tip({
   closeOnClick,
   children,
 }: {
-  text: string
+  text: React.ReactNode
   closeOnClick?: boolean
   children: ReactElement
 }) {
@@ -453,6 +463,40 @@ function ExpandAllIcon() {
   )
 }
 
+// Sun/moon/device-desktop octicons for the theme toggle, one per mode.
+function SunIcon() {
+  return (
+    <svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="M8 12a4 4 0 1 1 0-8 4 4 0 0 1 0 8Zm0-1.5a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Zm5.657-8.157a.75.75 0 0 1 0 1.061l-1.061 1.06a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734l1.06-1.06a.75.75 0 0 1 1.06 0Zm-9.193 9.193a.75.75 0 0 1 0 1.06l-1.06 1.061a.75.75 0 1 1-1.061-1.06l1.06-1.061a.75.75 0 0 1 1.061 0ZM8 0a.75.75 0 0 1 .75.75v1.5a.75.75 0 0 1-1.5 0V.75A.75.75 0 0 1 8 0ZM3 8a.75.75 0 0 1-.75.75H.75a.75.75 0 0 1 0-1.5h1.5A.75.75 0 0 1 3 8Zm13 0a.75.75 0 0 1-.75.75h-1.5a.75.75 0 0 1 0-1.5h1.5A.75.75 0 0 1 16 8Zm-8 5a.75.75 0 0 1 .75.75v1.5a.75.75 0 0 1-1.5 0v-1.5A.75.75 0 0 1 8 13Zm3.536-1.464a.75.75 0 0 1 1.06 0l1.061 1.06a.75.75 0 0 1-1.06 1.061l-1.061-1.06a.75.75 0 0 1 0-1.061ZM2.343 2.343a.75.75 0 0 1 1.061 0l1.06 1.061a.751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018l-1.06-1.06a.75.75 0 0 1 0-1.06Z"
+      />
+    </svg>
+  )
+}
+
+function MoonIcon() {
+  return (
+    <svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="M9.598 1.591a.749.749 0 0 1 .785-.175 7.001 7.001 0 1 1-8.967 8.967.75.75 0 0 1 .961-.96 5.5 5.5 0 0 0 7.046-7.046.75.75 0 0 1 .175-.786Zm1.616 1.945a7 7 0 0 1-7.678 7.678 5.499 5.499 0 1 0 7.678-7.678Z"
+      />
+    </svg>
+  )
+}
+
+function SystemThemeIcon() {
+  return (
+    <svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="M14.25 1c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 14.25 12h-3.727c.099 1.041.52 1.872 1.292 2.757A.752.752 0 0 1 11.25 16h-6.5a.75.75 0 0 1-.565-1.243c.772-.885 1.192-1.716 1.292-2.757H1.75A1.75 1.75 0 0 1 0 10.25v-7.5C0 1.784.784 1 1.75 1ZM1.75 2.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25ZM9.018 12H6.982a5.72 5.72 0 0 1-.765 2.5h3.566a5.72 5.72 0 0 1-.765-2.5Z"
+      />
+    </svg>
+  )
+}
+
 function FileHeader({
   fileDiff,
   isViewed,
@@ -569,11 +613,15 @@ function ProgressBar({
   fileHashes,
   viewed,
   onUnviewAll,
+  theme,
+  onCycleTheme,
 }: {
   command: string
   fileHashes: FileHashes
   viewed: ViewedMap
   onUnviewAll: () => void
+  theme: ThemeMode
+  onCycleTheme: () => void
 }) {
   const total = Object.keys(fileHashes).length
   const viewedCount = Object.entries(fileHashes).filter(
@@ -609,6 +657,31 @@ function ProgressBar({
           Clear
         </button>
       </Tip>
+      {/* The icon and tooltip show the current mode including "system": a
+          toggle that hides the system state leaves a user who forced a theme
+          long ago unable to see why the app ignores their OS setting. */}
+      <Tip
+        text={
+          <>
+            Theme: {theme} <kbd>t</kbd>
+          </>
+        }
+      >
+        <button
+          type="button"
+          className="theme-toggle-button"
+          aria-label={`Theme: ${theme}`}
+          onClick={onCycleTheme}
+        >
+          {theme === 'system' ? (
+            <SystemThemeIcon />
+          ) : theme === 'light' ? (
+            <SunIcon />
+          ) : (
+            <MoonIcon />
+          )}
+        </button>
+      </Tip>
     </div>
   )
 }
@@ -637,6 +710,7 @@ const SHORTCUTS: [string, string][] = [
   ['v', 'Toggle viewed'],
   ['e / E', 'Toggle collapse file / all files'],
   ['s', 'Toggle split mode (responsive / unified)'],
+  ['t', 'Cycle theme (system / light / dark)'],
   ['c', 'Comment on line'],
   ['Esc', 'Close / cancel'],
   ['?', 'Toggle this help'],
@@ -788,6 +862,41 @@ function DiffView() {
 
   const qc = useQueryClient()
 
+  // Server-persisted so the preference survives the per-run ephemeral port (a
+  // fresh browser origin every run, which defeats web storage) and reaches
+  // other running instances. initialData comes from the data-theme attribute
+  // the server stamped into the HTML; the default refetchOnWindowFocus
+  // re-applies the stored value when a stale tab regains focus — the only
+  // moment cross-instance staleness is observable.
+  const { data: themeData } = useQuery({
+    queryKey: ['theme'],
+    queryFn: () => apiFetch<ThemeResponse>('/api/theme'),
+    initialData: { theme: initialTheme },
+  })
+  const theme = themeData.theme
+
+  const themeMutation = useMutation({
+    mutationFn: (next: ThemeMode) =>
+      apiFetch('/api/theme', { method: 'POST', body: { theme: next } }),
+    // Write the cache up front so the toggle doesn't fight a stale entry.
+    onMutate: (next) => qc.setQueryData(['theme'], { theme: next } satisfies ThemeResponse),
+  })
+  const mutateTheme = themeMutation.mutate
+
+  // Shared by the header button and the t shortcut. Returns the new mode so
+  // the shortcut can toast it. Reads the current mode from the query cache
+  // rather than closing over `theme`: the theme switch re-renders every
+  // CodeView item, so a second press during that render would otherwise see
+  // a stale mode and cycle to the same place.
+  const cycleTheme = useCallback(() => {
+    const cur = qc.getQueryData<ThemeResponse>(['theme'])?.theme ?? 'system'
+    const next = THEME_CYCLE[cur]
+    mutateTheme(next)
+    return next
+  }, [qc, mutateTheme])
+
+  useEffect(() => applyTheme(theme), [theme])
+
   const markMutation = useMutation({
     mutationFn: ({ file, hash, mark }: { file: string; hash: string; mark: boolean }) =>
       apiFetch('/api/viewed', {
@@ -1261,18 +1370,12 @@ function DiffView() {
 
   const options = useMemo<CodeViewOptions<AnnotationMeta>>(
     () => ({
-      // In system mode the dual theme makes the library emit light-dark()
-      // CSS that follows the OS (the shadow roots' :host base style is
-      // `color-scheme: light dark`; they don't inherit the page's value). A
-      // forced theme passes a single theme instead: Shiki then tokenizes once
-      // rather than once per theme, and the theme's own type pins the shadow
-      // roots' color-scheme.
-      theme:
-        theme === 'system'
-          ? { light: 'github-light-default', dark: 'github-dark-default' }
-          : theme === 'light'
-            ? 'github-light-default'
-            : 'github-dark-default',
+      // Always the dual theme: Shiki tokenizes both up front and switching
+      // themes is purely a CSS flip (a single theme would retokenize on every
+      // toggle). themeType pins the shadow roots' color-scheme — they don't
+      // inherit the page's value ('system' leaves their :host default of
+      // `light dark`, following the OS).
+      theme: { light: 'github-light-default', dark: 'github-dark-default' },
       themeType: theme,
       diffStyle,
       // The library lays out collapsed files (and unmeasured estimates) from
@@ -1323,7 +1426,7 @@ function DiffView() {
         }
       },
     }),
-    [diffStyle, commentsEnabled, markSeen],
+    [theme, diffStyle, commentsEnabled, markSeen],
   )
 
   // Keyboard shortcuts. File navigation (n/p) and the focused-file actions
@@ -1528,6 +1631,17 @@ function DiffView() {
           setCollapsed(Object.fromEntries(files.map((f) => [f.name, anyExpanded])))
           break
         }
+        case 't': {
+          if (showHelp || composing) break
+          e.preventDefault()
+          const next = cycleTheme()
+          showToast(
+            <>
+              Theme: <code>{next}</code>
+            </>,
+          )
+          break
+        }
       }
     }
 
@@ -1549,6 +1663,7 @@ function DiffView() {
     commentMutation,
     setFocused,
     markProgrammaticScroll,
+    cycleTheme,
   ])
 
   // Error before loading: on a failed fetch react-query settles with `data`
@@ -1578,6 +1693,8 @@ function DiffView() {
           command={data.revset}
           fileHashes={fileHashes}
           viewed={viewed}
+          theme={theme}
+          onCycleTheme={cycleTheme}
           onUnviewAll={() => {
             const entries = Object.entries(viewed).map(([file, hash]) => ({ file, hash }))
             if (entries.length === 0) return
diff --git a/src/styles.css b/src/styles.css
index 9e3a10c..11d31ee 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -8,19 +8,20 @@
 
 /*
  * Color tokens, a light-dark(light, dark) pair per token, resolved by
- * color-scheme on :root: 'light dark' follows the OS, and --theme pins it
- * with an inline style (see App) — the diff library's shadow roots resolve
- * their theme CSS from the same property. Neutrals share one hue and vary
- * only in OKLCH lightness, so surfaces form an elevation ramp: raised chrome
- * steps away from the page background, with controls (--bg-control) one step
- * past the header bar (--bg-header) so a button reads as resting on the bar.
- * Borders are a separate low→high contrast ramp; accents are four fixed hues
- * with bright/text variants.
+ * color-scheme on :root: 'light dark' follows the OS, and a forced theme pins
+ * it via the data-theme attribute (rules below) — the diff library's shadow
+ * roots resolve their theme CSS from the same property. Neutrals share one
+ * hue and vary only in OKLCH lightness, so surfaces form an elevation ramp:
+ * raised chrome steps away from the page background, with controls
+ * (--bg-control) one step past the header bar (--bg-header) so a button reads
+ * as resting on the bar. Borders are a separate low→high contrast ramp;
+ * accents are four fixed hues with bright/text variants.
  */
 :root {
   /* Drives light-dark() resolution here and native widget rendering, and is
      inherited into the diff library's shadow roots. Forced themes override
-     this with an inline style (see App). */
+     this via data-theme, set pre-first-paint by the /api/theme.js boot
+     script in index.html and toggled at runtime by the theme button / t. */
   color-scheme: light dark;
 
   /* Surfaces, ascending elevation. The page (--bg-canvas) matches the diff/code
@@ -98,6 +99,17 @@
     Consolas, 'Liberation Mono', monospace;
 }
 
+/* Forced themes. The attribute arrives two ways: set by the /api/theme.js
+   boot script before first paint, and set/removed by the theme toggle at
+   runtime. */
+:root[data-theme='light'] {
+  color-scheme: light;
+}
+
+:root[data-theme='dark'] {
+  color-scheme: dark;
+}
+
 body {
   margin: 0;
   background: var(--bg-canvas);
@@ -253,6 +265,25 @@ body,
   animation: tooltip-in 0.09s ease;
 }
 
+/* Key-cap chip inside a tooltip (e.g. the theme toggle's shortcut), like
+   .help-modal kbd but sized down to sit inline in tooltip text. Translucent
+   background rather than a ramp token: the tooltip surface is already near
+   the top of the elevation ramp, so a fixed token would sit below it in dark
+   mode and read as a hole instead of a key. */
+.tooltip-popup kbd {
+  display: inline-block;
+  padding: 1px 4px;
+  margin-left: 2px;
+  background: light-dark(rgb(0 0 0 / 5%), rgb(255 255 255 / 10%));
+  /* One ramp step stronger in dark: the translucent fill lightens the chip
+     interior to about --border-strong's level, swallowing that border. */
+  border: 1px solid light-dark(var(--border-strong), var(--border-muted));
+  border-radius: 4px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-bright);
+}
+
 @keyframes tooltip-in {
   from {
     opacity: 0;
@@ -532,7 +563,7 @@ body,
 /* Clear-viewed-progress button next to the counter. Chrome matches
    .viewed-button so the two read as the same family of control. */
 .unview-all-button {
-  padding: 3px 6px;
+  padding: 4px 7px;
   border: 1px solid var(--border-strong);
   border-radius: 6px;
   background: var(--bg-control);
@@ -546,6 +577,30 @@ body,
   user-select: none;
 }
 
+/* Theme toggle: a plain icon rather than a bordered button — quieter than
+   the text controls, but with a hover background so it still reads as
+   clickable. */
+.theme-toggle-button {
+  display: flex;
+  align-items: center;
+  padding: 4px;
+  border: none;
+  border-radius: 4px;
+  background: none;
+  color: var(--fg-dim);
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
+.theme-toggle-button:hover {
+  background: var(--bg-control);
+  color: var(--fg);
+}
+
+.theme-toggle-button svg {
+  display: block;
+}
+
 .unview-all-button:hover {
   border-color: var(--border-muted);
   background: var(--bg-control-hover);
diff --git a/vite.config.ts b/vite.config.ts
index f11baa7..b0ffdef 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -19,12 +19,6 @@ export default defineConfig({
   plugins: [react()],
   build: {
     outDir: 'dist/web',
-    // Vite's default cssTarget predates light-dark(), so esbuild lowers it
-    // to a prefers-color-scheme polyfill that follows the OS and ignores the
-    // forced color-scheme --theme sets. Target the first versions with
-    // light-dark() support so it ships untransformed. Not a new floor in
-    // practice: the diff library already emits light-dark() at runtime.
-    cssTarget: ['chrome123', 'firefox120', 'safari17.5'],
   },
   server: {
     proxy: {

From f3f9a3da3c32ee09b85302ce33f9d926fe34cd1c Mon Sep 17 00:00:00 2001
From: David Crespo <david.crespo@oxidecomputer.com>
Date: Wed, 8 Jul 2026 13:54:48 -0500
Subject: [PATCH 8/8] color pass in both light and dark theme, fix file borders

---
 src/styles.css | 89 ++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 64 insertions(+), 25 deletions(-)

diff --git a/src/styles.css b/src/styles.css
index 11d31ee..3730890 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -12,10 +12,13 @@
  * it via the data-theme attribute (rules below) — the diff library's shadow
  * roots resolve their theme CSS from the same property. Neutrals share one
  * hue and vary only in OKLCH lightness, so surfaces form an elevation ramp:
- * raised chrome steps away from the page background, with controls
- * (--bg-control) one step past the header bar (--bg-header) so a button reads
- * as resting on the bar. Borders are a separate low→high contrast ramp;
- * accents are four fixed hues with bright/text variants.
+ * raised chrome steps away from the page background. The two schemes express
+ * elevation differently (matching GitHub's grammar): in dark, a control
+ * (--bg-control) sits a wide step ABOVE the header bar (--bg-header) so it
+ * reads as raised; in light, fills that dark against white read as pressed-in,
+ * so controls share the bar's lightness and the border carries the affordance.
+ * Borders are a separate low→high contrast ramp; accents are four fixed hues
+ * with bright/text variants.
  */
 :root {
   /* Drives light-dark() resolution here and native widget rendering, and is
@@ -39,43 +42,43 @@
     oklch(17.5% 0.015 256)
   ); /* page — same as the code base */
   --bg-panel: light-dark(
-    oklch(97% 0.005 256),
+    oklch(97.5% 0.004 256),
     oklch(22% 0.015 256)
   ); /* modal, comment form, separator band */
   --bg-muted: light-dark(
-    oklch(95.5% 0.006 256),
+    oklch(94.5% 0.007 256),
     oklch(24% 0.015 256)
   ); /* progress track, kbd, inline code chip */
-  --bg-header: light-dark(oklch(96% 0.006 256), oklch(26% 0.015 256)); /* file header bar */
+  --bg-header: light-dark(oklch(97% 0.005 256), oklch(26% 0.015 256)); /* file header bar */
   --bg-control: light-dark(
-    oklch(94% 0.007 256),
-    oklch(28.5% 0.015 256)
-  ); /* buttons — one step past the header */
-  --bg-control-hover: light-dark(oklch(90.5% 0.009 256), oklch(33% 0.015 256));
+    oklch(97% 0.005 256),
+    oklch(31% 0.016 256)
+  ); /* buttons — dark: a wide step above the header; light: level with it */
+  --bg-control-hover: light-dark(oklch(94% 0.008 256), oklch(35.5% 0.016 256));
 
   /* Borders, low→high contrast against the surface they sit on. */
-  --border: light-dark(oklch(88% 0.01 256), oklch(33% 0.013 256)); /* default */
+  --border: light-dark(oklch(88% 0.012 256), oklch(36% 0.015 256)); /* default */
   --border-soft: light-dark(
-    oklch(89.5% 0.009 256),
+    oklch(90.5% 0.01 256),
     oklch(32% 0.015 256)
   ); /* header strip — low contrast on the bar */
   --border-strong: light-dark(
-    oklch(80% 0.013 256),
-    oklch(42% 0.016 256)
+    oklch(84% 0.013 256),
+    oklch(45% 0.016 256)
   ); /* control outlines */
   --border-muted: light-dark(
     oklch(65% 0.016 256),
-    oklch(56% 0.018 256)
+    oklch(58% 0.018 256)
   ); /* hover / emphasis */
 
   /* Text, hue 250. */
-  --fg: light-dark(oklch(32% 0.02 250), oklch(86% 0.014 250));
-  --fg-bright: light-dark(oklch(21% 0.02 250), oklch(94% 0.012 250));
+  --fg: light-dark(oklch(27% 0.018 250), oklch(88% 0.013 250));
+  --fg-bright: light-dark(oklch(18% 0.018 250), oklch(96% 0.01 250));
   --fg-dim: light-dark(
-    oklch(44% 0.02 250),
-    oklch(77% 0.016 250)
+    oklch(42% 0.02 250),
+    oklch(78% 0.016 250)
   ); /* between muted and fg: de-emphasized but interactive */
-  --fg-muted: light-dark(oklch(52% 0.02 250), oklch(66% 0.018 250));
+  --fg-muted: light-dark(oklch(49% 0.021 250), oklch(68% 0.017 250));
 
   /* Accents: base / bright (hover) / text (on the scheme's surfaces). Bases
      used as fills under white text (--blue, --green) hold in both schemes;
@@ -164,6 +167,17 @@ body,
   --diffs-font-family: var(--font-mono);
   --diffs-bg-separator-override: var(--bg-panel);
   --diffs-modified-color-override: var(--blue);
+  /* Selected-line highlight. The library builds it by color-mix()ing this
+     into the line background in CIELAB, whose blue region drifts purple as it
+     lightens — feeding --blue (hue 260) directly yields a periwinkle wash
+     (hue ~282 in light mode) clashing with the solid-blue comment button
+     sitting on it. These hues are rotated so the post-mix tint lands back at
+     --blue's hue 260 in each scheme (the two mixes drift by different
+     amounts). Chroma is up a notch to keep the tint from washing out at the
+     rotated hue. */
+  --diffs-bg-selection-override: light-dark(oklch(57% 0.22 227), oklch(57% 0.22 238));
+  /* The gutter-number cells mix from this separate slot; same target. */
+  --diffs-bg-selection-number-override: var(--diffs-bg-selection-override);
 }
 
 /* The library focuses the scroll container (tabindex="-1") after programmatic
@@ -177,9 +191,30 @@ body,
    scrolls, so any top chrome would scroll off and leave the pinned sticky header
    flush and square against the scroll edge ("cut off") — fighting the library,
    whose native model has no card. Files are delineated by the header strip
-   (.file-header background + border) and inter-file spacing instead. */
+   (.file-header background + border) and inter-file spacing instead. Side
+   borders (matching the header's top border) close off the file's edges —
+   without them the header/body strips just stop mid-air. No border-radius:
+   rounding fights the sticky header. */
 .codeview-root diffs-container {
   display: block;
+  border-left: 1px solid var(--border-soft);
+  border-right: 1px solid var(--border-soft);
+  border-bottom: 1px solid var(--border-soft);
+}
+
+/* Track the focused header (which swaps to --border-strong): otherwise its
+   darkened top border visibly mismatches the file's soft side borders where
+   they meet at the corners. This also outlines the focused file's full
+   extent. */
+.codeview-root diffs-container:has(.file-header.focused) {
+  border-color: var(--border-strong);
+}
+
+/* Collapsed file: the header is the only content, so its border-bottom would
+   sit directly on the container's and read as a double line. Let the header's
+   (which tracks focus) be the file's bottom edge. */
+.codeview-root diffs-container:has(.collapse-chevron.collapsed) {
+  border-bottom: none;
 }
 
 /* Custom file header. Sticky positioning is handled by CodeView (stickyHeaders),
@@ -391,10 +426,12 @@ body,
   transform: scale(0.85);
 }
 
-/* Keep the control lit while the file is expanded so it reads as active. */
+/* Keep the control lit while the file is expanded so it reads as active.
+   The hover step, not --bg-control: in light mode the control fill is level
+   with the header bar, so it would vanish here. */
 .expand-all-button.expanded {
   color: var(--fg-bright);
-  background: var(--bg-control);
+  background: var(--bg-control-hover);
 }
 
 /* Disabled: dimmed and inert, but still hoverable so its tooltip (the reason it
@@ -592,8 +629,10 @@ body,
   flex-shrink: 0;
 }
 
+/* The hover step, not --bg-control: in light mode the control fill is level
+   with the white canvas this button sits on, so it wouldn't show. */
 .theme-toggle-button:hover {
-  background: var(--bg-control);
+  background: var(--bg-control-hover);
   color: var(--fg);
 }