token-larper 1.6.1 → 1.8.1

package/README.md

@@ -24,7 +24,7 @@ It consolidates all sessions into a real-time, interactive local dashboard runni
 * **100% Private & Offline**: No API keys required, no external proxies to configure, and zero analytics or telemetry sent to the cloud. The one outbound request is an optional update check that asks npm for the latest version number; turn it off in **Settings → Updates**.
 * **Cross-Platform Core**: The telemetry engine, 18 harness scrapers, and React dashboard run identically across Windows, macOS (Apple Silicon & Intel), and Linux.
 * **Gamified Hall of Larp**: Track your lifetime token burn, unlock 14 achievements, climb an 11-tier ranking ladder past rival personas, and export a shareable 1200×630 flex badge.
-* **Six Styles, Any Accent**: Grove, Terminal, Paper, Brutal, Soft, and Mono each change fonts, corner radius, spacing, borders, and shadows, not just colors. Pair any of them with a preset or custom accent, or import a tweakcn/shadcn CSS theme on top.
+* **Six Styles, Your Colors**: Grove, Terminal, Paper, Brutal, Soft, and Mono each change fonts, corner radius, spacing, borders, and shadows, not just colors. Pick a base color that tints backgrounds, borders, and text, and an accent for highlights, from presets or any custom color. Or import a tweakcn/shadcn CSS theme on top.
 * **Subscription-Aware**: Distinguishes between strict verified API billing and estimated **"LARP Value"** (the theoretical API cost of tokens consumed through flat-rate subscriptions like Claude Pro/Max, Copilot, or Antigravity).
 
 ---
@@ -99,8 +99,15 @@ You can run Token Larper instantly without cloning:
 ```bash
 npx token-larper
 # or
-bunx tokenlarper
+bunx token-larper
 ```
+It starts in the background, opens the dashboard, and keeps running after you close the terminal. On Windows, quit it from the tray icon. On any platform:
+```bash
+bunx token-larper stop          # stop it
+bunx token-larper --foreground  # run in the terminal with logs instead
+bunx token-larper --help        # all options
+```
+The background server writes its output to `server.log` in the data folder.
 
 ---
 
@@ -132,7 +139,7 @@ bun run tray
 ```
 > **Shortcut**: You can also simply **double-click** `Start-TokenLarper.vbs` in File Explorer!
 
-* A green **`t.`** monogram icon will appear in your notification tray.
+* The **Burning t.** icon will appear in your notification tray.
 * Hover over the icon to see your real-time token count and cost estimate.
 * Left-click the icon for a compact usage popup with an **Open dashboard** button. Right-click it to sync or configure boot auto-start.
 

package/bin/cli.js

@@ -1,36 +1,155 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const rootDir = join(__dirname, "..");
 const serverScript = join(rootDir, "src", "server.ts");
+const port = Number(process.env.PORT || 4269);
+const args = process.argv.slice(2);
 
-// server.ts handles a copy that is already running (and replaces it if older).
+const HELP = `Token Larper: a local dashboard for AI coding token usage.
 
-// If executed directly inside Bun runtime
-if (typeof Bun !== "undefined") {
-  await import(serverScript);
-} else {
-  // If executed via Node / npx, check for Bun and hand over
-  const bunCheck = spawnSync("bun", ["--version"], { stdio: "ignore" });
-  if (bunCheck.status === 0) {
-    const child = spawnSync("bun", [serverScript, ...process.argv.slice(2)], {
-      stdio: "inherit",
-      cwd: rootDir,
-    });
-    process.exit(child.status ?? 0);
+Usage:
+  token-larper                Start in the background and open the dashboard
+  token-larper --foreground   Run in this terminal and show logs (Ctrl+C stops it)
+  token-larper --no-open      Start without opening the browser
+  token-larper stop           Stop the running copy
+
+Environment: PORT (default 4269), TOKEN_LARPER_DATA_DIR, NO_TRAY=1`;
+
+// Same folder as src/paths.ts; the background server's log goes there.
+function dataDir() {
+  if (process.env.TOKEN_LARPER_DATA_DIR) return resolve(process.env.TOKEN_LARPER_DATA_DIR);
+  const home = homedir();
+  if (process.platform === "win32") return join(process.env.LOCALAPPDATA || join(home, "AppData", "Local"), "TokenLarper");
+  if (process.platform === "darwin") return join(home, "Library", "Application Support", "TokenLarper");
+  return join(process.env.XDG_DATA_HOME || join(home, ".local", "share"), "token-larper");
+}
+
+function bunPath() {
+  if (typeof Bun !== "undefined") return process.execPath;
+  if (spawnSync("bun", ["--version"], { stdio: "ignore" }).status === 0) return "bun";
+  console.error("🔥 Token Larper requires Bun (v1.1+) to run.");
+  console.error("\nInstall Bun with one command:");
+  if (process.platform === "win32") {
+    console.error('  powershell -c "irm bun.sh/install.ps1 | iex"');
   } else {
-    console.error("🔥 Token Larper requires Bun (v1.1+) to run.");
-    console.error("\nInstall Bun with one command:");
-    if (process.platform === "win32") {
-      console.error('  powershell -c "irm bun.sh/install.ps1 | iex"');
-    } else {
-      console.error("  curl -fsSL https://bun.sh/install | bash");
+    console.error("  curl -fsSL https://bun.sh/install | bash");
+  }
+  console.error("\nMore info: https://github.com/YarooqH/token-larper\n");
+  process.exit(1);
+}
+
+async function isRunning(p) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${p}/api/tray-status`, { signal: AbortSignal.timeout(800) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  const [cmd, cmdArgs] =
+    process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : process.platform === "darwin" ? ["open", [url]]
+    : ["xdg-open", [url]];
+  spawn(cmd, cmdArgs, { stdio: "ignore", detached: true, windowsHide: true }).unref();
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function stop() {
+  try {
+    await fetch(`http://127.0.0.1:${port}/api/shutdown`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(2000),
+    });
+  } catch {
+    console.log(`Token Larper isn't running on port ${port}.`);
+    return;
+  }
+  for (let i = 0; i < 20 && (await isRunning(port)); i++) await sleep(250);
+  console.log("Stopped Token Larper.");
+}
+
+async function foreground() {
+  if (typeof Bun !== "undefined") return import(serverScript);
+  const child = spawnSync("bun", [serverScript], { stdio: "inherit", cwd: rootDir });
+  process.exit(child.status ?? 0);
+}
+
+async function background(open) {
+  const bun = bunPath();
+  const dir = dataDir();
+  mkdirSync(dir, { recursive: true });
+  const logFile = join(dir, "server.log");
+  const log = openSync(logFile, "w");
+
+  // The server moves to the next free port if another program has this one, and takes
+  // over from an older Token Larper on the same port (see src/server.ts).
+  const child = spawn(bun, [serverScript], {
+    cwd: rootDir,
+    detached: true,
+    windowsHide: true,
+    stdio: ["ignore", log, log],
+    env: { ...process.env, TOKEN_LARPER_NO_BROWSER: "1" },
+  });
+  let exited = false;
+  child.on("exit", () => (exited = true));
+  child.unref();
+  closeSync(log);
+
+  const readLog = () => {
+    try {
+      return readFileSync(logFile, "utf8");
+    } catch {
+      return "";
     }
-    console.error("\nMore info: https://github.com/YarooqH/token-larper\n");
+  };
+
+  // Ready once the server says where it is listening. A copy of the same version that
+  // is already running says so too ("already running at ..."), then the new one exits.
+  let url = null;
+  for (let i = 0; i < 120 && !url; i++) {
+    await sleep(250);
+    url = readLog().match(/running at (http:\/\/localhost:\d+)/)?.[1] ?? null;
+    if (!url && exited) break;
+  }
+
+  if (!url) {
+    console.error("🔥 Token Larper didn't start.");
+    const tail = readLog().trim().split(/\r?\n/).slice(-15).join("\n");
+    if (tail) console.error(`\n${tail}\n`);
+    console.error(`Full log: ${logFile}`);
+    console.error("Run with --foreground to see the server output live.");
     process.exit(1);
   }
+
+  console.log(`🔥 Token Larper is running at ${url}`);
+  console.log("   It keeps running after you close this window.");
+  console.log(
+    process.platform === "win32"
+      ? "   Quit it from the tray icon, or run: bunx token-larper stop"
+      : "   Stop it with: bunx token-larper stop"
+  );
+  if (open) openBrowser(url);
+  process.exit(0);
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+} else if (args[0] === "stop") {
+  await stop();
+} else if (args.includes("--foreground") || args.includes("-f")) {
+  bunPath();
+  await foreground();
+} else {
+  await background(!args.includes("--no-open") && process.env.TOKEN_LARPER_NO_BROWSER !== "1");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-larper",
-  "version": "1.6.1",
+  "version": "1.8.1",
   "description": "Token Larper — Multi-Harness AI Coding Usage & Cost Telemetry Dashboard powered by ccusage",
   "type": "module",
   "license": "MIT",

package/src/client/components/SettingsDialog.tsx

@@ -94,7 +94,7 @@ export function SettingsDialog({
         <header className="modal-header">
           <div>
             <h3 id="settings-title">Settings</h3>
-            <p>Appearance, dashboard, updates, and startup</p>
+            <p>Appearance, dashboard, startup, and updates</p>
           </div>
           <button ref={closeRef} className="icon-btn" aria-label="Close settings" onClick={onClose}>
             <X size={17} />
@@ -133,78 +133,77 @@ export function SettingsDialog({
               </button>
             </div>
           </section>
-          <UpdateSettings updates={updates} autoCheck={checkUpdates} onAutoCheckChange={onCheckUpdatesChange} />
           {startup ? (
-            <>
-              <section className="settings-section" aria-labelledby="settings-startup-heading">
-                <div className="settings-section-heading">
-                  <h4 id="settings-startup-heading">Startup</h4>
-                  <span>{startup.enabled ? "Starts with Windows" : "Manual launch"}</span>
-                </div>
-                <div className="setting-row">
-                  <div className="setting-copy">
-                    <strong id="setting-autostart-label">Start with Windows</strong>
-                    <p>Launch Token Larper when you sign in.</p>
-                  </div>
-                  <button
-                    disabled={saving}
-                    className={`toggle ${startup.enabled ? "on" : ""}`}
-                    role="switch"
-                    aria-labelledby="setting-autostart-label"
-                    aria-checked={startup.enabled}
-                    onClick={() => onToggleStartup(!startup.enabled)}
-                  >
-                    <span className="toggle-knob" />
-                  </button>
+            <section className="settings-section" aria-labelledby="settings-startup-heading">
+              <div className="settings-section-heading">
+                <h4 id="settings-startup-heading">Startup</h4>
+                <span>{startup.enabled ? "Starts with Windows" : "Manual launch"}</span>
+              </div>
+              <div className="setting-row">
+                <div className="setting-copy">
+                  <strong id="setting-autostart-label">Start with Windows</strong>
+                  <p>Launch Token Larper when you sign in.</p>
                 </div>
-                <div className="setting-row">
-                  <div className="setting-copy">
-                    <strong id="setting-browser-label">Open dashboard at sign-in</strong>
-                    <p>
-                      {startup.enabled
-                        ? "Open the dashboard in your browser after launch."
-                        : "Takes effect when Start with Windows is on."}
-                    </p>
-                  </div>
-                  <button
-                    disabled={saving}
-                    className={`toggle ${startup.openBrowserOnBoot ? "on" : ""}`}
-                    role="switch"
-                    aria-labelledby="setting-browser-label"
-                    aria-checked={startup.openBrowserOnBoot}
-                    onClick={() => onToggleStartup(startup.enabled, !startup.openBrowserOnBoot)}
-                  >
-                    <span className="toggle-knob" />
-                  </button>
+                <button
+                  disabled={saving}
+                  className={`toggle ${startup.enabled ? "on" : ""}`}
+                  role="switch"
+                  aria-labelledby="setting-autostart-label"
+                  aria-checked={startup.enabled}
+                  onClick={() => onToggleStartup(!startup.enabled)}
+                >
+                  <span className="toggle-knob" />
+                </button>
+              </div>
+              <div className="setting-row">
+                <div className="setting-copy">
+                  <strong id="setting-browser-label">Open dashboard at sign-in</strong>
+                  <p>
+                    {startup.enabled
+                      ? "Open the dashboard in your browser after launch."
+                      : "Takes effect when Start with Windows is on."}
+                  </p>
                 </div>
-              </section>
-
-              <details className="settings-details">
-                <summary>
-                  Technical details <ChevronDown size={14} aria-hidden="true" />
-                </summary>
-                <dl>
-                  <div>
-                    <dt>Dashboard</dt>
-                    <dd><code>http://127.0.0.1:{startup.port}</code></dd>
-                  </div>
-                  <div>
-                    <dt>Windows startup</dt>
-                    <dd><code>{startup.registryValue || "Not registered"}</code></dd>
-                  </div>
-                  <div>
-                    <dt>Launcher</dt>
-                    <dd><code>{startup.launcherPath}</code></dd>
-                  </div>
-                </dl>
-              </details>
-            </>
+                <button
+                  disabled={saving}
+                  className={`toggle ${startup.openBrowserOnBoot ? "on" : ""}`}
+                  role="switch"
+                  aria-labelledby="setting-browser-label"
+                  aria-checked={startup.openBrowserOnBoot}
+                  onClick={() => onToggleStartup(startup.enabled, !startup.openBrowserOnBoot)}
+                >
+                  <span className="toggle-knob" />
+                </button>
+              </div>
+            </section>
           ) : (
             <div className="settings-empty">
               <p>Startup settings are unavailable.</p>
               <button className="btn" onClick={onRetry}>Try again</button>
             </div>
           )}
+          <UpdateSettings updates={updates} autoCheck={checkUpdates} onAutoCheckChange={onCheckUpdatesChange} />
+          {startup && (
+            <details className="settings-details">
+              <summary>
+                Technical details <ChevronDown size={14} aria-hidden="true" />
+              </summary>
+              <dl>
+                <div>
+                  <dt>Dashboard</dt>
+                  <dd><code>http://127.0.0.1:{startup.port}</code></dd>
+                </div>
+                <div>
+                  <dt>Windows startup</dt>
+                  <dd><code>{startup.registryValue || "Not registered"}</code></dd>
+                </div>
+                <div>
+                  <dt>Launcher</dt>
+                  <dd><code>{startup.launcherPath}</code></dd>
+                </div>
+              </dl>
+            </details>
+          )}
         </div>
 
         <footer className="settings-footer">

package/src/client/components/ThemeSettings.tsx

@@ -2,6 +2,7 @@ import React, { useState } from "react";
 import { Check, ChevronDown, Pipette } from "lucide-react";
 import {
   ACCENT_PRESETS,
+  BASE_PRESETS,
   importThemeCss,
   STYLE_PRESETS,
   type Appearance,
@@ -39,8 +40,6 @@ export function ThemeSettings({ mode, followsSystem, appearance, importedTheme,
   const [css, setCss] = useState("");
   const [error, setError] = useState<string | null>(null);
   const [message, setMessage] = useState<string | null>(null);
-  const accent = appearance.accent;
-  const customColor = accent.kind === "custom" ? accent.color : "#6d5bd0";
 
   function applyPastedTheme() {
     try {
@@ -109,42 +108,26 @@ export function ThemeSettings({ mode, followsSystem, appearance, importedTheme,
         </div>
       </div>
 
-      <div className="theme-block">
-        <span className="theme-row-label" id="theme-accent-label">Accent</span>
-        <div className="accent-row" role="radiogroup" aria-labelledby="theme-accent-label">
-          <button
-            type="button"
-            role="radio"
-            aria-checked={accent.kind === "style"}
-            className="accent-default"
-            onClick={() => onAppearanceChange({ ...appearance, accent: { kind: "style" } })}
-          >
-            Style default
-          </button>
-          {ACCENT_PRESETS.map((preset) => (
-            <button
-              key={preset.id}
-              type="button"
-              role="radio"
-              aria-checked={accent.kind === "preset" && accent.id === preset.id}
-              aria-label={preset.name}
-              title={preset.name}
-              className="accent-swatch"
-              style={{ background: mode === "dark" ? preset.dark : preset.light }}
-              onClick={() => onAppearanceChange({ ...appearance, accent: { kind: "preset", id: preset.id } })}
-            />
-          ))}
-          <label className={`accent-custom ${accent.kind === "custom" ? "is-selected" : ""}`} title="Pick any color">
-            <Pipette size={14} aria-hidden="true" />
-            <span className="sr-only">Custom accent color</span>
-            <input
-              type="color"
-              value={customColor}
-              onChange={(event) => onAppearanceChange({ ...appearance, accent: { kind: "custom", color: event.target.value } })}
-            />
-          </label>
-        </div>
-      </div>
+      <ColorChoices
+        id="theme-base"
+        label="Base"
+        hint={appearance.imported ? "Set by your imported colors" : "Backgrounds, borders and text"}
+        disabled={appearance.imported}
+        choice={appearance.base}
+        presets={BASE_PRESETS}
+        fallbackCustom="#5f7390"
+        onChange={(base) => onAppearanceChange({ ...appearance, base })}
+      />
+
+      <ColorChoices
+        id="theme-accent"
+        label="Accent"
+        hint="Buttons, links and highlights"
+        choice={appearance.accent}
+        presets={ACCENT_PRESETS.map((preset) => ({ ...preset, color: mode === "dark" ? preset.dark : preset.light }))}
+        fallbackCustom="#6d5bd0"
+        onChange={(accent) => onAppearanceChange({ ...appearance, accent })}
+      />
 
       {importedTheme && (
         <div className="theme-row">
@@ -204,3 +187,67 @@ export function ThemeSettings({ mode, followsSystem, appearance, importedTheme,
     </section>
   );
 }
+
+type ColorChoice<Id extends string> = { kind: "style" } | { kind: "preset"; id: Id } | { kind: "custom"; color: string };
+
+/** "Style default", a row of preset swatches, and a picker for any color. */
+function ColorChoices<Id extends string>({ id, label, hint, disabled = false, choice, presets, fallbackCustom, onChange }: {
+  id: string;
+  label: string;
+  hint: string;
+  disabled?: boolean;
+  choice: ColorChoice<Id>;
+  presets: { id: Id; name: string; color: string }[];
+  fallbackCustom: string;
+  onChange: (choice: ColorChoice<Id>) => void;
+}) {
+  const labelId = `${id}-label`;
+  return (
+    <div className="theme-block">
+      <div className="theme-block-heading">
+        <span className="theme-row-label" id={labelId}>{label}</span>
+        <span className="theme-row-hint">{hint}</span>
+      </div>
+      <div className="accent-row" role="radiogroup" aria-labelledby={labelId} aria-disabled={disabled || undefined}>
+        <button
+          type="button"
+          role="radio"
+          aria-checked={choice.kind === "style"}
+          className="accent-default"
+          disabled={disabled}
+          onClick={() => onChange({ kind: "style" })}
+        >
+          Style default
+        </button>
+        {presets.map((preset) => (
+          <button
+            key={preset.id}
+            type="button"
+            role="radio"
+            aria-checked={choice.kind === "preset" && choice.id === preset.id}
+            aria-label={preset.name}
+            title={preset.name}
+            className="accent-swatch"
+            disabled={disabled}
+            style={{ background: preset.color }}
+            onClick={() => onChange({ kind: "preset", id: preset.id })}
+          />
+        ))}
+        <label
+          className={`accent-custom ${choice.kind === "custom" ? "is-selected" : ""}`}
+          style={choice.kind === "custom" ? { background: choice.color } : undefined}
+          title="Pick any color"
+        >
+          <Pipette size={14} aria-hidden="true" />
+          <span className="sr-only">Custom {label.toLowerCase()} color</span>
+          <input
+            type="color"
+            disabled={disabled}
+            value={choice.kind === "custom" ? choice.color : fallbackCustom}
+            onChange={(event) => onChange({ kind: "custom", color: event.target.value })}
+          />
+        </label>
+      </div>
+    </div>
+  );
+}

package/src/client/index.html

@@ -35,7 +35,9 @@
     </script>
     <meta name="theme-color" content="#f8f9f7" />
     <title>Token Larper — Usage overview</title>
+    <link rel="icon" href="/favicon.ico" sizes="32x32" />
     <link rel="icon" type="image/svg+xml" href="/logo.svg" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <link rel="stylesheet" href="/styles.css" />
   </head>
   <body>

package/src/client/lib/cssColor.ts

@@ -0,0 +1,32 @@
+// Themes can use any CSS color syntax (oklch, color-mix, var() chains). To get a plain
+// #rrggbb, a hidden probe element resolves the expression to a computed color, which is
+// painted onto a 1×1 canvas and read back.
+
+export interface ColorReader {
+  /** Resolve a CSS color expression, e.g. "var(--bg)", to #rrggbb. */
+  read(expression: string): string;
+  dispose(): void;
+}
+
+export function createColorReader(): ColorReader | null {
+  const ctx = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+  if (!ctx || !document.body) return null;
+  const probe = document.createElement("span");
+  probe.style.display = "none";
+  document.body.appendChild(probe);
+  return {
+    read(expression) {
+      probe.style.color = "";
+      probe.style.color = expression;
+      ctx.clearRect(0, 0, 1, 1);
+      ctx.fillStyle = "#000";
+      ctx.fillStyle = getComputedStyle(probe).color;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+      return `#${[r, g, b].map((v) => (v ?? 0).toString(16).padStart(2, "0")).join("")}`;
+    },
+    dispose() {
+      probe.remove();
+    },
+  };
+}

package/src/client/lib/trayTheme.ts

@@ -1,6 +1,7 @@
-// Keeps the Windows tray popup in the same colors as the dashboard. Themes can use any CSS
-// color syntax (oklch, color-mix, …), which the tray can't parse, so each token is painted
-// onto a 1×1 canvas and read back as #rrggbb.
+// Keeps the Windows tray popup in the same colors as the dashboard. The tray only
+// understands #rrggbb, so each token is resolved to hex first.
+
+import { createColorReader } from "./cssColor.ts";
 
 const TOKENS = {
   surface: "--surface",
@@ -13,28 +14,12 @@ const TOKENS = {
   gold: "--gold",
 } as const;
 
-function toHex(color: string, ctx: CanvasRenderingContext2D): string {
-  ctx.clearRect(0, 0, 1, 1);
-  ctx.fillStyle = "#000";
-  ctx.fillStyle = color;
-  ctx.fillRect(0, 0, 1, 1);
-  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
-  return `#${[r, g, b].map((v) => (v ?? 0).toString(16).padStart(2, "0")).join("")}`;
-}
-
 function readTheme(): Record<string, string> | null {
-  const ctx = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
-  if (!ctx) return null;
-  // A probe element resolves var() chains and color-mix() to a computed color.
-  const probe = document.createElement("span");
-  probe.style.display = "none";
-  document.body.appendChild(probe);
+  const reader = createColorReader();
+  if (!reader) return null;
   const out: Record<string, string> = { mode: document.documentElement.dataset.theme === "light" ? "light" : "dark" };
-  for (const [key, token] of Object.entries(TOKENS)) {
-    probe.style.color = `var(${token})`;
-    out[key] = toHex(getComputedStyle(probe).color, ctx);
-  }
-  probe.remove();
+  for (const [key, token] of Object.entries(TOKENS)) out[key] = reader.read(`var(${token})`);
+  reader.dispose();
   return out;
 }
 
@@ -61,7 +46,7 @@ export function startTrayThemeSync(): () => void {
   // data-palette is today's theme switch; data-style and data-accent come with style presets.
   observer.observe(document.documentElement, {
     attributes: true,
-    attributeFilter: ["data-theme", "data-palette", "data-style", "data-accent", "style", "class"],
+    attributeFilter: ["data-theme", "data-palette", "data-style", "data-accent", "data-base", "style", "class"],
   });
   schedule();
   return () => {

package/src/client/styles.css

@@ -435,7 +435,7 @@ img { display: block; }
 .update-link { color: var(--text-2); font-weight: 500; padding: 0 6px; text-decoration: none; }
 .update-link:hover { color: var(--text); text-decoration: underline; }
 .setting-copy code { font-size: 11.5px; }
-.setting-copy a { color: inherit; }
+.setting-copy a { color: inherit; white-space: nowrap; }
 
 /* ---------- Filters ---------- */
 
@@ -1312,6 +1312,11 @@ html[data-theme="dark"] .toggle.on .toggle-knob { background: var(--accent-ink);
 .accent-custom input { position: absolute; inset: 0; width: 100%; height: 100%; opacity: 0; cursor: pointer; }
 .accent-custom:focus-within { outline: 2px solid var(--focus); outline-offset: 2px; }
 
+.theme-block-heading { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; }
+.theme-row-hint { color: var(--text-3); font-size: 12px; }
+.accent-row[aria-disabled="true"] { opacity: 0.45; }
+.accent-row[aria-disabled="true"] .accent-custom { cursor: not-allowed; }
+
 /* ---------- Responsive ---------- */
 
 @media (max-width: 1020px) {

package/src/client/themes.ts

@@ -1,10 +1,13 @@
+import { createColorReader } from "./lib/cssColor.ts";
+
 export type ThemeMode = "light" | "dark";
 
-// A theme is two independent choices. The style is the whole look and feel: fonts,
+// A theme is three independent choices. The style is the whole look and feel: fonts,
 // radius, spacing, borders, shadows, label casing, and its own light and dark colors
-// (all defined in styles.css under html[data-style]). The accent is either the style's
-// own, one of the preset colors below, or any color the user picks. An imported CSS
-// theme can replace the colors of whichever style is active.
+// (all defined in styles.css under html[data-style]). The base color tints the style's
+// backgrounds, borders and text, keeping their lightness. The accent colors highlights.
+// Base and accent are each the style's own, a preset below, or any color the user picks.
+// An imported CSS theme can replace the colors of whichever style is active.
 
 export type StyleId = "grove" | "terminal" | "paper" | "brutal" | "soft" | "mono";
 
@@ -39,14 +42,29 @@ export const ACCENT_PRESETS: { id: AccentId; name: string; light: string; dark:
 
 export type AccentChoice = { kind: "style" } | { kind: "preset"; id: AccentId } | { kind: "custom"; color: string };
 
+export type BaseId = "neutral" | "slate" | "stone" | "sage" | "plum" | "sand";
+
+/** Only the hue and saturation of these are used; lightness comes from the style. */
+export const BASE_PRESETS: { id: BaseId; name: string; color: string }[] = [
+  { id: "neutral", name: "Neutral", color: "#808080" },
+  { id: "slate", name: "Slate", color: "#5f7390" },
+  { id: "stone", name: "Stone", color: "#8a7b6d" },
+  { id: "sage", name: "Sage", color: "#6d8a72" },
+  { id: "plum", name: "Plum", color: "#86688a" },
+  { id: "sand", name: "Sand", color: "#a08a5c" },
+];
+
+export type BaseChoice = { kind: "style" } | { kind: "preset"; id: BaseId } | { kind: "custom"; color: string };
+
 export interface Appearance {
   style: StyleId;
+  base: BaseChoice;
   accent: AccentChoice;
   /** Use the imported CSS theme's colors on top of the style. */
   imported: boolean;
 }
 
-export const DEFAULT_APPEARANCE: Appearance = { style: "grove", accent: { kind: "style" }, imported: false };
+export const DEFAULT_APPEARANCE: Appearance = { style: "grove", base: { kind: "style" }, accent: { kind: "style" }, imported: false };
 
 export const THEME_MODE_STORAGE_KEY = "token-larper-theme";
 export const APPEARANCE_STORAGE_KEY = "token-larper-appearance";
@@ -118,6 +136,7 @@ export function readImportedTheme(): ImportedTheme | null {
 
 const isStyle = (value: unknown): value is StyleId => STYLE_PRESETS.some((s) => s.id === value);
 const isAccentId = (value: unknown): value is AccentId => ACCENT_PRESETS.some((a) => a.id === value);
+const isBaseId = (value: unknown): value is BaseId => BASE_PRESETS.some((b) => b.id === value);
 const isHex = (value: unknown): value is string => typeof value === "string" && /^#[0-9a-f]{6}$/i.test(value);
 
 function sanitizeAppearance(value: unknown): Appearance | null {
@@ -130,7 +149,14 @@ function sanitizeAppearance(value: unknown): Appearance | null {
       : a.kind === "custom" && isHex(a.color)
         ? { kind: "custom", color: a.color.toLowerCase() }
         : { kind: "style" };
-  return { style: isStyle(v.style) ? v.style : "grove", accent, imported: v.imported === true };
+  const b = (v.base ?? {}) as Record<string, unknown>;
+  const base: BaseChoice =
+    b.kind === "preset" && isBaseId(b.id)
+      ? { kind: "preset", id: b.id }
+      : b.kind === "custom" && isHex(b.color)
+        ? { kind: "custom", color: b.color.toLowerCase() }
+        : { kind: "style" };
+  return { style: isStyle(v.style) ? v.style : "grove", base, accent, imported: v.imported === true };
 }
 
 export function readAppearance(): Appearance {
@@ -199,17 +225,97 @@ function accentFor(choice: AccentChoice, mode: ThemeMode): string | null {
   return null;
 }
 
+function rgbToHsl(hex: string): [number, number, number] {
+  const [r, g, b] = hexToRgb(hex).map((v) => v / 255) as [number, number, number];
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  const h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+  return [h * 60, s, l];
+}
+
+function hslToHex(h: number, s: number, l: number): string {
+  const k = (n: number) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return rgbToHex([f(0) * 255, f(8) * 255, f(4) * 255]);
+}
+
+/** The style colors a base color retints. */
+export const BASE_PROPERTIES = [
+  "--bg", "--surface", "--surface-2", "--surface-3", "--border", "--border-strong", "--text", "--text-2", "--text-3",
+] as const;
+type BaseProperty = (typeof BASE_PROPERTIES)[number];
+export type StyleNeutrals = Record<ThemeMode, Record<BaseProperty, string>>;
+
+// How much of the base color's saturation each role takes, and the most it may take.
+const TINT: Record<BaseProperty, [factor: number, cap: number]> = {
+  "--bg": [0.8, 0.6], "--surface": [0.8, 0.6], "--surface-2": [0.8, 0.6], "--surface-3": [0.8, 0.6],
+  "--border": [0.6, 0.45], "--border-strong": [0.6, 0.45],
+  "--text": [0.35, 0.3], "--text-2": [0.4, 0.35], "--text-3": [0.4, 0.35],
+};
+const TEXT_CONTRAST: Partial<Record<BaseProperty, number>> = { "--text": 7, "--text-2": 4.5, "--text-3": 4.5 };
+
+function baseColor(choice: BaseChoice): string | null {
+  if (choice.kind === "preset") return BASE_PRESETS.find((b) => b.id === choice.id)!.color;
+  return choice.kind === "custom" ? choice.color : null;
+}
+
+/**
+ * Give the style's neutrals the base color's hue and saturation while keeping each one's
+ * lightness, so the style's structure (pale paper, black brutal outlines) survives.
+ * Near-white surfaces come down slightly so the tint shows, and text is nudged until it
+ * reads at least as well as the contrast targets above.
+ */
+function tintNeutrals(neutrals: Record<BaseProperty, string>, base: string, mode: ThemeMode): Record<string, string> {
+  const [hue, saturation] = rgbToHsl(base);
+  const out = {} as Record<BaseProperty, string>;
+  for (const property of BASE_PROPERTIES) {
+    const [factor, cap] = TINT[property];
+    let l = rgbToHsl(neutrals[property])[2];
+    if (mode === "light" && !TEXT_CONTRAST[property] && l > 0.93) l = 0.93 + (l - 0.93) * 0.7;
+    if (mode === "dark" && !TEXT_CONTRAST[property]) l = Math.max(l, 0.07); // Pure black can't take a tint.
+    // Saturation barely shows on near-black, so dark backgrounds and borders take more.
+    const boost = mode === "dark" && !TEXT_CONTRAST[property] ? 2 : 1;
+    out[property] = hslToHex(hue, Math.min(saturation * factor * boost, cap), l);
+  }
+  for (const [property, target] of Object.entries(TEXT_CONTRAST) as [BaseProperty, number][]) {
+    const [h, s, start] = rgbToHsl(out[property]);
+    let l = start;
+    for (let step = 0; step < 25; step++) {
+      const color = hslToHex(h, s, l);
+      out[property] = color;
+      if (Math.min(contrast(color, out["--bg"]), contrast(color, out["--surface"])) >= target) break;
+      l = Math.max(0, Math.min(1, l + (mode === "light" ? -0.02 : 0.02)));
+    }
+  }
+  return out;
+}
+
 export type ThemeVars = Record<ThemeMode, Record<string, string>>;
 
-/** Inline variables for an accent override or an imported theme, for both modes. */
-export function resolveThemeVars(appearance: Appearance, importedTheme: ImportedTheme | null): ThemeVars {
+/**
+ * Inline variables for the base, accent, or imported colors, for both modes. A base
+ * color needs the style's own neutrals as hex (read from the page by applyTheme).
+ */
+export function resolveThemeVars(
+  appearance: Appearance,
+  importedTheme: ImportedTheme | null,
+  styleNeutrals: StyleNeutrals | null = null
+): ThemeVars {
   const vars: ThemeVars = { light: {}, dark: {} };
+  const base = baseColor(appearance.base);
   for (const mode of ["light", "dark"] as const) {
     const out = vars[mode];
     if (appearance.imported && importedTheme) {
       const tokens = importedTheme[mode];
       for (const property of APP_COLOR_PROPERTIES) if (validColor(tokens[property])) out[property] = tokens[property]!;
       for (const property of APP_RADIUS_PROPERTIES) if (validRadius(tokens[property])) out[property] = tokens[property]!;
+    } else if (base && styleNeutrals) {
+      Object.assign(out, tintNeutrals(styleNeutrals[mode], base, mode));
     }
     const accent = accentFor(appearance.accent, mode);
     if (accent) {
@@ -224,16 +330,34 @@ export function resolveThemeVars(appearance: Appearance, importedTheme: Imported
 
 let appliedProperties: string[] = [];
 
+/** The active style's neutrals in both modes, read from styles.css with no overrides applied. */
+function readStyleNeutrals(): StyleNeutrals | null {
+  const reader = createColorReader();
+  if (!reader) return null;
+  const root = document.documentElement;
+  const current = root.dataset.theme;
+  const out = { light: {}, dark: {} } as StyleNeutrals;
+  for (const mode of ["light", "dark"] as const) {
+    root.dataset.theme = mode;
+    for (const property of BASE_PROPERTIES) out[mode][property] = reader.read(`var(${property})`);
+  }
+  root.dataset.theme = current;
+  reader.dispose();
+  return out;
+}
+
 export function applyTheme(mode: ThemeMode, appearance: Appearance, importedTheme: ImportedTheme | null): void {
   const root = document.documentElement;
   root.dataset.theme = mode;
   root.dataset.style = appearance.style;
   root.dataset.accent = appearance.accent.kind === "style" && !appearance.imported ? "style" : "custom";
+  root.dataset.base = appearance.base.kind === "style" || appearance.imported ? "style" : "custom";
   // Clear what an earlier call (or index.html) set before applying the new values.
   for (const property of new Set([...appliedProperties, ...APP_COLOR_PROPERTIES, ...APP_RADIUS_PROPERTIES])) {
     root.style.removeProperty(property);
   }
-  const vars = resolveThemeVars(appearance, importedTheme);
+  const neutrals = root.dataset.base === "custom" ? readStyleNeutrals() : null;
+  const vars = resolveThemeVars(appearance, importedTheme, neutrals);
   for (const [property, value] of Object.entries(vars[mode])) root.style.setProperty(property, value);
   appliedProperties = Object.keys(vars[mode]);
   try {

package/src/icons.ts

@@ -0,0 +1,147 @@
+import { deflateSync } from "node:zlib";
+import { flattenPath, LOGO_PATHS } from "./client/logoMark.ts";
+
+// PNG and ICO versions of the logo for places that can't use the SVG favicon: /favicon.ico
+// (requested by some browsers and tools on their own) and the Apple touch icon. They are
+// rasterized here from the same paths, so no image files or image libraries are needed.
+// Both put the white mark on a dark tile, which reads on light and dark tab strips alike;
+// iOS fills transparency with black anyway.
+
+const INK = [0xf5, 0xf5, 0xf5] as const;
+const TILE = [0x14, 0x14, 0x14] as const;
+const SUPERSAMPLE = 4;
+
+// The mark's polygons in 64-unit logo space. Filled even-odd, which also cuts out the flame's core.
+const POLYGONS = [LOGO_PATHS.t, LOGO_PATHS.flame].flatMap((d) => flattenPath(d));
+
+/** Fraction of each pixel covered, from SUPERSAMPLE² samples per pixel. */
+function coverage(size: number, inside: (x: number, y: number) => boolean): Float32Array {
+  const out = new Float32Array(size * size);
+  const step = 1 / SUPERSAMPLE;
+  for (let py = 0; py < size; py++) {
+    for (let px = 0; px < size; px++) {
+      let hits = 0;
+      for (let sy = 0; sy < SUPERSAMPLE; sy++) {
+        for (let sx = 0; sx < SUPERSAMPLE; sx++) {
+          if (inside(px + (sx + 0.5) * step, py + (sy + 0.5) * step)) hits++;
+        }
+      }
+      out[py * size + px] = hits / (SUPERSAMPLE * SUPERSAMPLE);
+    }
+  }
+  return out;
+}
+
+function insideMark(x: number, y: number): boolean {
+  let inside = false;
+  for (const polygon of POLYGONS) {
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+      const [xi, yi] = polygon[i]!;
+      const [xj, yj] = polygon[j]!;
+      if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
+    }
+  }
+  return inside;
+}
+
+function insideRoundedSquare(x: number, y: number, size: number, radius: number): boolean {
+  const cx = Math.min(Math.max(x, radius), size - radius);
+  const cy = Math.min(Math.max(y, radius), size - radius);
+  return (x - cx) ** 2 + (y - cy) ** 2 <= radius ** 2;
+}
+
+/**
+ * RGBA pixels: the mark centered at markScale of the icon, on a tile with the given
+ * corner radius (as a fraction of the size; 0 for a full square).
+ */
+function renderIcon(size: number, markScale: number, cornerRadius: number): Uint8Array {
+  const markSize = size * markScale;
+  const offset = (size - markSize) / 2;
+  const unit = 64 / markSize;
+  const radius = size * cornerRadius;
+  const tile = cornerRadius > 0 ? coverage(size, (x, y) => insideRoundedSquare(x, y, size, radius)) : null;
+  const mark = coverage(size, (x, y) => insideMark((x - offset) * unit, (y - offset) * unit));
+  const rgba = new Uint8Array(size * size * 4);
+  for (let i = 0; i < size * size; i++) {
+    const t = tile ? tile[i]! : 1;
+    const m = Math.min(mark[i]!, t);
+    // The mark over the tile, then the tile's own edge over transparency.
+    for (let c = 0; c < 3; c++) rgba[i * 4 + c] = Math.round(INK[c]! * m + TILE[c]! * (1 - m));
+    rgba[i * 4 + 3] = Math.round(t * 255);
+  }
+  return rgba;
+}
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (const byte of bytes) c = CRC_TABLE[(c ^ byte) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Uint8Array): Buffer {
+  const out = Buffer.alloc(12 + data.length);
+  out.writeUInt32BE(data.length, 0);
+  out.write(type, 4, "ascii");
+  Buffer.from(data).copy(out, 8);
+  out.writeUInt32BE(crc32(out.subarray(4, 8 + data.length)), 8 + data.length);
+  return out;
+}
+
+function encodePng(size: number, rgba: Uint8Array): Buffer {
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(size, 0);
+  header.writeUInt32BE(size, 4);
+  header[8] = 8; // bits per channel
+  header[9] = 6; // RGBA
+  const rows = Buffer.alloc(size * (size * 4 + 1));
+  for (let y = 0; y < size; y++) {
+    rows[y * (size * 4 + 1)] = 0; // no filter
+    Buffer.from(rgba.buffer, y * size * 4, size * 4).copy(rows, y * (size * 4 + 1) + 1);
+  }
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", header),
+    chunk("IDAT", deflateSync(rows)),
+    chunk("IEND", new Uint8Array()),
+  ]);
+}
+
+/** An ICO file holding PNG images, which every browser since IE 9 and Windows Vista reads. */
+function encodeIco(images: { size: number; png: Buffer }[]): Buffer {
+  const header = Buffer.alloc(6 + images.length * 16);
+  header.writeUInt16LE(1, 2); // icon
+  header.writeUInt16LE(images.length, 4);
+  let offset = header.length;
+  images.forEach(({ size, png }, i) => {
+    const entry = 6 + i * 16;
+    header[entry] = size >= 256 ? 0 : size;
+    header[entry + 1] = size >= 256 ? 0 : size;
+    header.writeUInt16LE(1, entry + 4); // planes
+    header.writeUInt16LE(32, entry + 6); // bits per pixel
+    header.writeUInt32LE(png.length, entry + 8);
+    header.writeUInt32LE(offset, entry + 12);
+    offset += png.length;
+  });
+  return Buffer.concat([header, ...images.map((image) => image.png)]);
+}
+
+// At 16px the flame is a few pixels, so the mark fills more of the tile there.
+const tilePng = (size: number) => encodePng(size, renderIcon(size, size <= 16 ? 0.9 : 0.78, size <= 16 ? 0.16 : 0.22));
+
+let favicon: Uint8Array<ArrayBuffer> | null = null;
+let touchIcon: Uint8Array<ArrayBuffer> | null = null;
+
+export function faviconIco(): Uint8Array<ArrayBuffer> {
+  return (favicon ??= new Uint8Array(encodeIco([16, 32, 48].map((size) => ({ size, png: tilePng(size) })))));
+}
+
+/** 180×180, full-bleed: iOS rounds the corners itself. */
+export function appleTouchIconPng(): Uint8Array<ArrayBuffer> {
+  return (touchIcon ??= new Uint8Array(encodePng(180, renderIcon(180, 0.62, 0))));
+}

package/src/server.ts

@@ -4,6 +4,7 @@ import { getStartupStatus, repointStartupIfStale, setStartupStatus } from "./sta
 import { startSystemTray, stopSystemTray } from "./tray.ts";
 import { buildTrayStatus, parseTheme, saveTheme } from "./trayStatus.ts";
 import { logoSvgFile } from "./client/logoMark.ts";
+import { appleTouchIconPng, faviconIco } from "./icons.ts";
 import { APP_VERSION, RUNNING_FROM_SOURCE } from "./paths.ts";
 import { checkForUpdates, compareVersions, localStatus, startUpdate } from "./updates.ts";
 
@@ -64,18 +65,20 @@ function openDashboard(port: number) {
 
 /** The version of a Token Larper already on the port, "0.0.0" for one too old to say, or null if none. */
 async function runningVersion(port: number): Promise<string | null> {
+  // /api/version answers instantly; versions before 1.5.0 don't have it, so fall back to
+  // /api/tray-status, which can take a few seconds while usage data loads.
   try {
-    const status = await fetch(`http://127.0.0.1:${port}/api/tray-status`, { signal: AbortSignal.timeout(600) });
-    if (!status.ok) return null;
+    const res = await fetch(`http://127.0.0.1:${port}/api/version`, { signal: AbortSignal.timeout(1500) });
+    const body = (await res.json().catch(() => null)) as { current?: unknown } | null;
+    if (res.ok && typeof body?.current === "string") return body.current;
   } catch {
-    return null;
+    // Nothing on the port, or it is busy; the next check decides.
   }
   try {
-    const res = await fetch(`http://127.0.0.1:${port}/api/version`, { signal: AbortSignal.timeout(600) });
-    const body = (await res.json()) as { current?: unknown };
-    return typeof body.current === "string" ? body.current : "0.0.0";
+    const status = await fetch(`http://127.0.0.1:${port}/api/tray-status`, { signal: AbortSignal.timeout(5000) });
+    return status.ok ? "0.0.0" : null;
   } catch {
-    return "0.0.0";
+    return null;
   }
 }
 
@@ -143,6 +146,18 @@ function startServer(preferredPort: number) {
       });
     }
 
+    if (url.pathname === "/favicon.ico") {
+      return new Response(faviconIco(), {
+        headers: { "Content-Type": "image/x-icon", "Cache-Control": "public, max-age=86400" },
+      });
+    }
+
+    if (url.pathname === "/apple-touch-icon.png" || url.pathname === "/apple-touch-icon-precomposed.png") {
+      return new Response(appleTouchIconPng(), {
+        headers: { "Content-Type": "image/png", "Cache-Control": "public, max-age=86400" },
+      });
+    }
+
     if (url.pathname === "/app.js") {
       const code = process.env.NODE_ENV === "production" ? await clientBundle : await buildClientBundle();
       return new Response(code, {