Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
feat(map): a System / Light / Dark theme switch
Eren8fa2b937eb25
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3db21d9..1d37eb1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).## [Unreleased]+### Added+- A theme switch next to Settings on the map and the panel: System (follow the system's light or dark mode), Light or Dark, remembered in the browser.## [0.17.3] - 2026-10-28### Changeddiff --git a/docs/guide/map.md b/docs/guide/map.mdindex be4fe47..c62f600 100644--- a/docs/guide/map.md+++ b/docs/guide/map.md@@ -84,6 +84,11 @@ Under the project's name, a strip of the most recently active projects and**Switch project** (Ctrl+K, Cmd+K on macOS) search every project on this machine. Each showswhere it left off. "← All projects" goes to the panel.+## Theme++The button next to Settings switches between **System** (follow your system's light or dark+mode), **Light** and **Dark**. The choice is remembered in this browser.+## Settings**Settings** in the top bar changes the global settings. A "?" next to each one explains it;diff --git a/docs/images/map-dark.png b/docs/images/map-dark.pngindex b901357..fee0d93 100644Binary files a/docs/images/map-dark.png and b/docs/images/map-dark.png differdiff --git a/docs/images/map-light.png b/docs/images/map-light.pngindex c8554ee..0964449 100644Binary files a/docs/images/map-light.png and b/docs/images/map-light.png differdiff --git a/packages/template/src/App.tsx b/packages/template/src/App.tsxindex 12f1c57..77db8dc 100644--- a/packages/template/src/App.tsx+++ b/packages/template/src/App.tsx@@ -14,6 +14,7 @@ import { Inbox } from "./Inbox.js";import { type MapSearchState, SearchBox } from "./MapSearch.js";import { ProjectSwitcher } from "./ProjectSwitcher.js";import { SettingsButton } from "./SettingsModal.js";+import { ThemeButton } from "./ThemeButton.js";export function App({ model }: { model: LineageViewModel }) {const sessionCount =@@ -64,6 +65,7 @@ export function App({ model }: { model: LineageViewModel }) {onStep={move}onClear={clear}/>+ <ThemeButton /><SettingsButton settings={model.settings} /></div></div>diff --git a/packages/template/src/Graph.tsx b/packages/template/src/Graph.tsxindex 9b25463..02d938d 100644--- a/packages/template/src/Graph.tsx+++ b/packages/template/src/Graph.tsx@@ -26,6 +26,7 @@ import { OPEN_LINK_DROP, SessionMap } from "./SessionMap.js";import { DrillDown, type Selection } from "./SidePanel.js";import { usePageWheel } from "./scroll.js";import { layoutSessionGraph, type SessionGraph } from "./sessionLayout.js";+import { useTheme } from "./ThemeButton.js";import { UnreadView } from "./UnreadView.js";/**@@ -795,6 +796,7 @@ function MapCanvas({fit: number;}) {const { fitView, setViewport } = useReactFlow();+ const theme = useTheme();/** Centres the view on a canvas point; does nothing before the canvas exists. */function centre(point: MapPoint): void {@@ -862,7 +864,7 @@ function MapCanvas({nodesDraggable={false}nodesConnectable={false}elementsSelectable={false}- colorMode="system"+ colorMode={theme}><Background gap={24} size={1} color="#242a36" /><MiniMapdiff --git a/packages/template/src/Panel.tsx b/packages/template/src/Panel.tsxindex a0c0cfe..c7a9d6a 100644--- a/packages/template/src/Panel.tsx+++ b/packages/template/src/Panel.tsx@@ -4,6 +4,7 @@ import { isLivePage } from "./data.js";import { formatTime } from "./format.js";import { Inbox } from "./Inbox.js";import { SettingsButton } from "./SettingsModal.js";+import { ThemeButton } from "./ThemeButton.js";/*** From the local server, maps open as pages of that server so they refresh too;@@ -28,6 +29,7 @@ export function Panel({ model }: { model: PanelViewModel }) {<p className="muted">Every project cogit knows about.</p></div><div className="page-actions">+ <ThemeButton /><SettingsButton settings={model.settings} /><div className="meta"><span>diff --git a/packages/template/src/ThemeButton.tsx b/packages/template/src/ThemeButton.tsxnew file mode 100644index 0000000..1b6c3fc--- /dev/null+++ b/packages/template/src/ThemeButton.tsx@@ -0,0 +1,31 @@+import { useSyncExternalStore } from "react";+import {+ getTheme,+ nextTheme,+ setTheme,+ subscribeTheme,+ type ThemeMode,+ themeLabel,+} from "./theme.js";++/** The current theme choice, re-rendering when it changes. */+export function useTheme(): ThemeMode {+ return useSyncExternalStore(subscribeTheme, getTheme, getTheme);+}++/** The top bar's System → Light → Dark switch, next to Settings. */+export function ThemeButton() {+ const mode = useTheme();+ const next = nextTheme(mode);+ return (+ <button+ type="button"+ className="settings-button theme-button"+ title={`Theme: ${mode}. Click for ${next}.`}+ aria-label={`Theme: ${mode}. Switch to ${next}.`}+ onClick={() => setTheme(next)}+ >+ {themeLabel(mode)}+ </button>+ );+}diff --git a/packages/template/src/main.tsx b/packages/template/src/main.tsxindex 0695c83..a54de62 100644--- a/packages/template/src/main.tsx+++ b/packages/template/src/main.tsx@@ -5,6 +5,9 @@ import { App } from "./App.js";import { isLivePage, loadViewModel, parseViewModel } from "./data.js";import { Panel } from "./Panel.js";import "./styles.css";+import { initTheme } from "./theme.js";++initTheme();/** Re-reads the served page and takes its embedded model; null on any failure. */async function fetchLatestModel(): Promise<PageModel | null> {diff --git a/packages/template/src/styles.css b/packages/template/src/styles.cssindex 6cb27f6..8fb1ffe 100644--- a/packages/template/src/styles.css+++ b/packages/template/src/styles.css@@ -46,7 +46,7 @@/* The same map in a light browser (Story 9.2). Small text keeps WCAG AA inboth palettes; `layout.test.ts` computes the ratios. */@media (prefers-color-scheme: light) {- :root {+ :root:not([data-theme="dark"]) {color-scheme: light;--bg: #fbfbfd;--panel: #f2f4f8;@@ -89,6 +89,49 @@}}+/* The same palette when the theme switch picks Light on a dark system. */+:root[data-theme="light"] {+ color-scheme: light;+ --bg: #fbfbfd;+ --panel: #f2f4f8;+ --line: #d5dae4;+ --text: #1b2230;+ --muted: #545e72;+ --accent: #2957c8;+ --warn: #8a5300;+ --l0: #2957c8;+ --l1: #2f7d32;+ --l2: #8a5300;+ --l3: #6f42c1;+ --l4: #0b6e99;+ --l5: #b3261e;+ --raised: #e9edf5;+ --raised-2: #eef1f7;+ --row-bg: #f4f6fa;+ --hover: #e6ebf5;+ --active: #d9e3f7;+ --chip-bg: #e8edf5;+ --chip-line: #c2cbdb;+ --kind-bg: #e4e8f0;+ --kind-decision-bg: #ece4ff;+ --kind-decision-text: #5b3aa8;+ --kind-question-bg: #fbf0dc;+ --kind-message-bg: #e7f3e1;+ --kind-message-text: #2a7430;+ --missing: #4f586b;+ --search-hit-bg: #e7e2dc;+ --search-active-bg: #e1d9cd;+ --diff-add-bg: #e2f5e4;+ --diff-add-text: #145c22;+ --diff-remove-bg: #fbe4e6;+ --diff-remove-text: #8a1c26;+ --on-lane: #ffffff;+ --translucent-panel: rgba(255, 255, 255, 0.97);+ --translucent-outline: rgba(246, 248, 251, 0.96);+ --overlay: rgba(20, 26, 38, 0.35);+ --shadow: rgba(20, 30, 50, 0.18);+}+* {box-sizing: border-box;}@@ -346,6 +389,10 @@ main.map-page {cursor: pointer;}+.theme-button {+ margin-right: 8px;+}+.settings-button:hover {color: var(--text);border-color: var(--accent);diff --git a/packages/template/src/theme.ts b/packages/template/src/theme.tsnew file mode 100644index 0000000..875335b--- /dev/null+++ b/packages/template/src/theme.ts@@ -0,0 +1,80 @@+/**+ * The theme switch: System (follow the browser), Light or Dark. The choice is a+ * per-viewer convenience, kept in localStorage, and shown as `data-theme` on+ * `<html>`; the stylesheet keys the light palette off it and off the system+ * preference. Storage can be missing or throw (private windows, `file://` in+ * some browsers), so every access is guarded and System is the fallback.+ */++export type ThemeMode = "system" | "light" | "dark";++export const THEME_KEY = "cogit-theme";+const ORDER: readonly ThemeMode[] = ["system", "light", "dark"];++/** The mode after `mode` in the button's cycle. */+export function nextTheme(mode: ThemeMode): ThemeMode {+ return ORDER[(ORDER.indexOf(mode) + 1) % ORDER.length] as ThemeMode;+}++/** What the button says for a mode. */+export function themeLabel(mode: ThemeMode): string {+ return mode === "system" ? "◐ System" : mode === "light" ? "☀ Light" : "☾ Dark";+}++type Store = Pick<Storage, "getItem" | "setItem" | "removeItem">;++export function readTheme(storage: Store | undefined): ThemeMode {+ try {+ const value = storage?.getItem(THEME_KEY);+ return value === "light" || value === "dark" ? value : "system";+ } catch {+ return "system";+ }+}++export function storeTheme(storage: Store | undefined, mode: ThemeMode): void {+ try {+ if (mode === "system") storage?.removeItem(THEME_KEY);+ else storage?.setItem(THEME_KEY, mode);+ } catch {+ // Not remembered; the page still switches.+ }+}++/** Marks `<html>`; System clears the mark so the media query decides. */+export function applyTheme(root: Pick<HTMLElement, "dataset">, mode: ThemeMode): void {+ if (mode === "system") delete root.dataset.theme;+ else root.dataset.theme = mode;+}++function browserStorage(): Store | undefined {+ try {+ return typeof window === "undefined" ? undefined : window.localStorage;+ } catch {+ return undefined;+ }+}++let current: ThemeMode = readTheme(browserStorage());+const listeners = new Set<() => void>();++export function getTheme(): ThemeMode {+ return current;+}++export function setTheme(mode: ThemeMode): void {+ current = mode;+ storeTheme(browserStorage(), mode);+ if (typeof document !== "undefined") applyTheme(document.documentElement, mode);+ for (const listener of listeners) listener();+}++export function subscribeTheme(listener: () => void): () => void {+ listeners.add(listener);+ return () => listeners.delete(listener);+}++/** Applies the remembered choice before the first paint. */+export function initTheme(): void {+ if (typeof document !== "undefined") applyTheme(document.documentElement, current);+}diff --git a/packages/template/test/layout.test.ts b/packages/template/test/layout.test.tsindex 86bd349..f5c0ec3 100644--- a/packages/template/test/layout.test.ts+++ b/packages/template/test/layout.test.ts@@ -47,9 +47,11 @@ function variables(block: string): Record<string, string> {const darkVars = variables(css.match(/:root\s*\{([\s\S]*?)\}/)?.[1] ?? "");const lightBlock = css.match(- /@media \(prefers-color-scheme: light\)\s*\{\s*:root\s*\{([\s\S]*?)\}\s*\}/,+ /@media \(prefers-color-scheme: light\)\s*\{\s*:root:not\(\[data-theme="dark"\]\)\s*\{([\s\S]*?)\}\s*\}/,);const lightVars = { ...darkVars, ...variables(lightBlock?.[1] ?? "") };+// The theme switch's Light repeats the system palette exactly.+const switchLight = css.match(/:root\[data-theme="light"\]\s*\{([\s\S]*?)\}/);/** WCAG relative luminance of a `#rrggbb` colour. */function luminance(hex: string): number {@@ -149,6 +151,7 @@ describe("small text contrast (Story 9.2)", () => {it("declares a light theme besides the dark default", () => {expect(lightBlock).not.toBeNull();+ expect(variables(switchLight?.[1] ?? "")).toEqual(variables(lightBlock?.[1] ?? ""));});for (const [name, theme] of [diff --git a/packages/template/test/theme.test.ts b/packages/template/test/theme.test.tsnew file mode 100644index 0000000..283970c--- /dev/null+++ b/packages/template/test/theme.test.ts@@ -0,0 +1,67 @@+import { describe, expect, it } from "vitest";+import {+ applyTheme,+ nextTheme,+ readTheme,+ storeTheme,+ THEME_KEY,+ themeLabel,+} from "../src/theme.js";++function memory(): Storage {+ const data = new Map<string, string>();+ return {+ getItem: (k: string) => data.get(k) ?? null,+ setItem: (k: string, v: string) => void data.set(k, v),+ removeItem: (k: string) => void data.delete(k),+ } as Storage;+}++const broken = {+ getItem: () => {+ throw new Error("denied");+ },+ setItem: () => {+ throw new Error("denied");+ },+ removeItem: () => {+ throw new Error("denied");+ },+} as unknown as Storage;++describe("the theme switch", () => {+ it("cycles System → Light → Dark and labels each", () => {+ expect(nextTheme("system")).toBe("light");+ expect(nextTheme("light")).toBe("dark");+ expect(nextTheme("dark")).toBe("system");+ expect(themeLabel("system")).toContain("System");+ expect(themeLabel("light")).toContain("Light");+ expect(themeLabel("dark")).toContain("Dark");+ });++ it("remembers a choice and forgets System", () => {+ const storage = memory();+ expect(readTheme(storage)).toBe("system");+ storeTheme(storage, "dark");+ expect(storage.getItem(THEME_KEY)).toBe("dark");+ expect(readTheme(storage)).toBe("dark");+ storeTheme(storage, "system");+ expect(storage.getItem(THEME_KEY)).toBeNull();+ storage.setItem(THEME_KEY, "purple");+ expect(readTheme(storage)).toBe("system");+ });++ it("falls back to System when storage is missing or throws", () => {+ expect(readTheme(undefined)).toBe("system");+ expect(readTheme(broken)).toBe("system");+ expect(() => storeTheme(broken, "light")).not.toThrow();+ });++ it("marks the page for Light and Dark and clears the mark for System", () => {+ const root = { dataset: {} as DOMStringMap };+ applyTheme(root, "light");+ expect(root.dataset.theme).toBe("light");+ applyTheme(root, "system");+ expect(root.dataset.theme).toBeUndefined();+ });+});