Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(map): a System / Light / Dark theme switch

Eren8fa2b937eb25
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Changed
diff --git a/docs/guide/map.md b/docs/guide/map.md
index 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 shows
where 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.png
index b901357..fee0d93 100644
Binary files a/docs/images/map-dark.png and b/docs/images/map-dark.png differ
diff --git a/docs/images/map-light.png b/docs/images/map-light.png
index c8554ee..0964449 100644
Binary files a/docs/images/map-light.png and b/docs/images/map-light.png differ
diff --git a/packages/template/src/App.tsx b/packages/template/src/App.tsx
index 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.tsx
index 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" />
<MiniMap
diff --git a/packages/template/src/Panel.tsx b/packages/template/src/Panel.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.css
index 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 in
both 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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();
+ });
+});