From 368390666c78bae39bcb3551609b9726af0a5541 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 07:47:53 -0400
Subject: [PATCH 01/29] fix: apply graceful shutdown to HTTP stop path

The /api/server/stop handler was calling httpServer.close()
immediately, racing against WS close frame delivery. Apply the
same pattern as SIGINT: let httpServer.close() drain connections
with a 1s fallback timeout.
---
 src/server/index.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/server/index.ts b/src/server/index.ts
index 68ded18..40cf9b1 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -15,7 +15,12 @@ const httpServer = http.createServer((req, res) => {
       for (const client of session.clients) client.close(1001, 'server stopped');
     }
     wss.close();
-    httpServer.close(() => process.exit(0));
+    const exit = () => process.exit(0);
+    const shutdownTimeout = setTimeout(exit, 1000);
+    httpServer.close(() => {
+      clearTimeout(shutdownTimeout);
+      exit();
+    });
   });
 });
 

From c00048f9a77ed640b3b2c2d49947ca57bde4d9b2 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 08:23:32 -0400
Subject: [PATCH 02/29] fix: update session close behavior and document browser
 restrictions

---
 docs/adrs/007.webtty.session-client.md | 10 +++++++++-
 docs/specs/client.md                   | 15 ++++++++++++++-
 docs/specs/webtty.md                   |  2 +-
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/adrs/007.webtty.session-client.md b/docs/adrs/007.webtty.session-client.md
index 74ef5f9..2a7ae2d 100644
--- a/docs/adrs/007.webtty.session-client.md
+++ b/docs/adrs/007.webtty.session-client.md
@@ -39,7 +39,15 @@ When the PTY exits (e.g. user types `exit`), the server:
 1. Deletes the session from the registry immediately
 2. Closes all connected WebSockets with code `4001`
 
-The client's existing `4001` handler (introduced in ADR 005 for deleted sessions) writes "Session removed." and calls `window.close()` after 2s. No delay is added before closing — the user explicitly typed `exit`, so immediate closure is the right behaviour. All open tabs for that session close together.
+The client's existing `4001` handler (introduced in ADR 005 for deleted sessions) writes "Session removed." and calls `window.close()` after 500ms. No delay is added before closing — the user explicitly typed `exit`, so immediate closure is the right behaviour. All open tabs for that session close together.
+
+Server stop (`webtty stop` or SIGINT) sends close code `1001` instead. The client writes "Server stopped." and also calls `window.close()` after 500ms.
+
+**`window.close()` browser restriction**: browsers only permit `window.close()` on tabs that were opened via `window.open()` or duplicated from such a tab. Tabs opened by the OS `open`/`xdg-open` command or by the user typing a URL directly are treated as unowned — `window.close()` is silently ignored with a console warning. In practice this means:
+- Tabs opened by `webtty run` and tabs duplicated from them → close automatically ✅
+- Tabs opened by manually navigating to `localhost:2346` → show "Server stopped." / "Session removed." but remain open ⚠️
+
+There is no JS workaround for this restriction. It is browser-enforced by design.
 
 **Multi-tab: fanout to all connected clients**
 
diff --git a/docs/specs/client.md b/docs/specs/client.md
index f3a2ae0..92dbb70 100644
--- a/docs/specs/client.md
+++ b/docs/specs/client.md
@@ -1,7 +1,7 @@
 # SPEC: Client
 
 **Author:** jesse23
-**Last Updated:** 2026-03-22
+**Last Updated:** 2026-03-23
 
 ---
 
@@ -15,6 +15,19 @@ The client has no build step in the initial slices — plain HTML + `<script typ
 
 **Why no framework (React/Vue) yet?** The session manager is simple enough (a table + buttons) that a framework adds more complexity than it removes. Revisit when the client grows.
 
+## Behavior Notes
+
+### Tab close on session end
+
+When a session ends (shell exits → WS close code `4001`) or the server stops (`webtty stop` / SIGINT → WS close code `1001`), the client calls `window.close()` after 500 ms to close the tab automatically.
+
+**Browser restriction**: `window.close()` is only permitted on tabs that were opened programmatically via `window.open()`, or duplicated from such a tab. Tabs opened by the OS (`open`/`xdg-open`) or by the user typing a URL directly are treated as unowned — `window.close()` is silently ignored. In practice:
+
+- Tabs opened by `webtty run` and tabs duplicated from them → close automatically ✅
+- Tabs opened by manually navigating to the server URL → display "Session removed." or "Server stopped." but remain open ⚠️
+
+This is a browser-enforced security restriction with no JS workaround.
+
 ## Features
 
 | Feature | Description | ADR | Done? |
diff --git a/docs/specs/webtty.md b/docs/specs/webtty.md
index e9ab318..4c2841c 100644
--- a/docs/specs/webtty.md
+++ b/docs/specs/webtty.md
@@ -83,9 +83,9 @@ Session IDs appear directly in the URL path (`/s/:id`), so they must be valid UR
 | Feature | Description | ADR | Done? |
 |---------|-------------|-----|-------|
 | Bootstrap | Port `ghostty-web` demo into webtty — full-screen terminal in a browser tab, single server, hardcoded config | [001](../adrs/001.webtty.bootstrap.md) | ⬜ |
-| Config file | Load shell, port, font, theme from a config file (`~/.webtty/config.json`) | — | ⬜ |
 | In-memory registry | Server-side map of `id → { session, pty }`; sessions survive WS disconnect, not server restart | — | ✅ |
 | Default session | `GET /` redirects to last-used session, or creates `main` and redirects if none exists | — | ✅ |
 | Session URL | `GET /s/:id` — serves browser client for the named session; reconnects if session already has a PTY | — | ✅ |
 | Session management | CRUD + rename over HTTP — see REST API above | [ADR 004](../adrs/004.webtty.session-api.md) | ✅ |
+| Config file | Load shell, port, font, theme from a config file (`~/.webtty/config.json`) | — | ⬜ |
 | Session client | Multiple browser tabs can attach to the same session simultaneously; reload replays scrollback; typing `exit` closes all tabs | [ADR 007](../adrs/007.webtty.session-client.md) | ✅ |

From 49065008615b12c694422ef0f70d2fde5ab6a59c Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 10:30:01 -0400
Subject: [PATCH 03/29] feat: implement configuration management with loading
 and saving functionality

---
 docs/specs/config.md | 59 ++++++++++++++++++++++++++++++++++++++++++++
 docs/specs/webtty.md |  2 +-
 src/config.ts        | 51 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 111 insertions(+), 1 deletion(-)
 create mode 100644 docs/specs/config.md
 create mode 100644 src/config.ts

diff --git a/docs/specs/config.md b/docs/specs/config.md
new file mode 100644
index 0000000..29e061d
--- /dev/null
+++ b/docs/specs/config.md
@@ -0,0 +1,59 @@
+# SPEC: Config
+
+**Author:** jesse23
+**Last Updated:** 2026-03-23
+
+---
+
+## Description
+
+webtty reads configuration from `~/.config/webtty/config.json`. The file is the single source of truth for persistent user preferences. Environment variables override config file values at runtime but never modify the file.
+
+## File location
+
+| Platform | Path |
+|----------|------|
+| macOS / Linux | `~/.config/webtty/config.json` |
+| Windows | `%USERPROFILE%\.config\webtty\config.json` |
+
+## Lifecycle
+
+```
+webtty server starts
+        │
+        ▼
+config file exists? ──────────────────────┐
+   │                                      │
+  yes                                     no
+   │                                      │
+   ▼                                      ▼
+read + parse JSON ◄──────── write defaults to file
+   │
+   ▼
+valid JSON? ──────────────────────┐
+   │                              │
+  yes                             no
+   │                              │
+   ▼                              ▼
+merge with defaults          error: print
+(unknown keys ignored)       path, exit
+   │
+   ▼
+apply env overrides
+(PORT > config.port, etc.)
+   │
+   ▼
+config ready
+```
+
+- **First run**: defaults are written to disk so the user has a file to edit.
+- **Subsequent runs**: file is read and merged with defaults — missing keys fall back to defaults, so adding new config keys in future versions is non-breaking.
+- **Invalid JSON**: hard error with a clear message pointing to the file path. webtty does not attempt to repair or overwrite a corrupt file.
+- **Unknown keys**: silently ignored (forward-compatibility — a config written by a newer version works with an older binary).
+- **Env overrides**: applied after the file is loaded, never written back to the file.
+
+## Features
+
+| Feature | Description | ADR | Done? |
+|---------|-------------|-----|-------|
+| Config lifecycle | First-run write + subsequent load, as described above | — | ⬜ |
diff --git a/docs/specs/webtty.md b/docs/specs/webtty.md
index 4c2841c..37e0ec8 100644
--- a/docs/specs/webtty.md
+++ b/docs/specs/webtty.md
@@ -87,5 +87,5 @@ Session IDs appear directly in the URL path (`/s/:id`), so they must be valid UR
 | Default session | `GET /` redirects to last-used session, or creates `main` and redirects if none exists | — | ✅ |
 | Session URL | `GET /s/:id` — serves browser client for the named session; reconnects if session already has a PTY | — | ✅ |
 | Session management | CRUD + rename over HTTP — see REST API above | [ADR 004](../adrs/004.webtty.session-api.md) | ✅ |
-| Config file | Load shell, port, font, theme from a config file (`~/.webtty/config.json`) | — | ⬜ |
+| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.json`) | — | ⬜ | → [config spec](config.md) |
 | Session client | Multiple browser tabs can attach to the same session simultaneously; reload replays scrollback; typing `exit` closes all tabs | [ADR 007](../adrs/007.webtty.session-client.md) | ✅ |
diff --git a/src/config.ts b/src/config.ts
new file mode 100644
index 0000000..5a5f48c
--- /dev/null
+++ b/src/config.ts
@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export interface Config {
+  port: number;
+  shell: string;
+}
+
+export const CONFIG_DIR = path.join(os.homedir(), '.config', 'webtty');
+export const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+
+export const DEFAULTS: Config = {
+  port: 2346,
+  shell:
+    process.platform === 'win32'
+      ? (process.env.COMSPEC ?? 'cmd.exe')
+      : (process.env.SHELL ?? '/bin/bash'),
+};
+
+export function loadConfig(): Config {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    saveConfig(DEFAULTS);
+    return { ...DEFAULTS };
+  }
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+  } catch (err) {
+    throw new Error(`webtty: failed to read config at ${CONFIG_PATH}: ${(err as Error).message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`webtty: invalid JSON in config file ${CONFIG_PATH}`);
+  }
+
+  const partial = parsed as Partial<Config>;
+  return {
+    port: typeof partial.port === 'number' ? partial.port : DEFAULTS.port,
+    shell: typeof partial.shell === 'string' ? partial.shell : DEFAULTS.shell,
+  };
+}
+
+export function saveConfig(config: Config): void {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}

From 050e9768e259a3054a4735399fbc7dd48fe20e5c Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 10:43:16 -0400
Subject: [PATCH 04/29] feat: add scrollbackBuffer to configuration schema and
 loading logic

---
 docs/specs/config.md | 73 +++++++++++++++++++++++++++++++++++---------
 src/config.ts        |  6 ++++
 2 files changed, 65 insertions(+), 14 deletions(-)

diff --git a/docs/specs/config.md b/docs/specs/config.md
index 29e061d..07412ba 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -20,23 +20,23 @@ webtty reads configuration from `~/.config/webtty/config.json`. The file is the
 
 ```
 webtty server starts
-        │
-        ▼
-config file exists? ──────────────────────┐
-   │                                      │
-  yes                                     no
-   │                                      │
-   ▼                                      ▼
+   │
+   ▼
+config file exists? ────────────────────┐
+   │                                    │
+  yes                                   no
+   │                                    │
+   ▼                                    ▼
 read + parse JSON ◄──────── write defaults to file
    │
    ▼
-valid JSON? ──────────────────────┐
-   │                              │
-  yes                             no
-   │                              │
-   ▼                              ▼
-merge with defaults          error: print
-(unknown keys ignored)       path, exit
+valid JSON? ────────────────────────────┐
+   │                                    │
+  yes                                   no
+   │                                    │
+   ▼                                    ▼
+merge with defaults                error: print
+(unknown keys ignored)             path, exit
    │
    ▼
 apply env overrides
@@ -52,6 +52,51 @@ config ready
 - **Unknown keys**: silently ignored (forward-compatibility — a config written by a newer version works with an older binary).
 - **Env overrides**: applied after the file is loaded, never written back to the file.
 
+## Schema
+
+```jsonc
+{
+  // Server
+  "port": 2346,
+
+  // Shell
+  "shell": "/bin/zsh",        // default: $SHELL on Unix, %COMSPEC% on Windows
+
+  // Terminal
+  "cols": 80,
+  "rows": 24,
+  "scrollback": 10000,        // lines in the terminal UI display buffer
+  "scrollbackBuffer": 262144, // server-side PTY replay buffer in bytes (256 KB default)
+  "cursorBlink": true,
+  "fontSize": 14,
+  "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
+
+  // Theme (Dracula defaults)
+  "theme": {
+    "background":   "#282A36",
+    "foreground":   "#F8F8F2",
+    "cursor":       "#F8F8F2",
+    "selection":    "#44475A",
+    "black":        "#21222C",
+    "red":          "#FF5555",
+    "green":        "#50FA7B",
+    "yellow":       "#F1FA8C",
+    "blue":         "#BD93F9",
+    "purple":       "#FF79C6",
+    "cyan":         "#8BE9FD",
+    "white":        "#F8F8F2",
+    "brightBlack":  "#6272A4",
+    "brightRed":    "#FF6E6E",
+    "brightGreen":  "#69FF94",
+    "brightYellow": "#FFFFA5",
+    "brightBlue":   "#D6ACFF",
+    "brightPurple": "#FF92DF",
+    "brightCyan":   "#A4FFFF",
+    "brightWhite":  "#FFFFFF"
+  }
+}
+```
+
 ## Features
 
 | Feature | Description | ADR | Done? |
diff --git a/src/config.ts b/src/config.ts
index 5a5f48c..6e027db 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -5,6 +5,7 @@ import path from 'node:path';
 export interface Config {
   port: number;
   shell: string;
+  scrollbackBuffer: number;
 }
 
 export const CONFIG_DIR = path.join(os.homedir(), '.config', 'webtty');
@@ -16,6 +17,7 @@ export const DEFAULTS: Config = {
     process.platform === 'win32'
       ? (process.env.COMSPEC ?? 'cmd.exe')
       : (process.env.SHELL ?? '/bin/bash'),
+  scrollbackBuffer: 256 * 1024,
 };
 
 export function loadConfig(): Config {
@@ -42,6 +44,10 @@ export function loadConfig(): Config {
   return {
     port: typeof partial.port === 'number' ? partial.port : DEFAULTS.port,
     shell: typeof partial.shell === 'string' ? partial.shell : DEFAULTS.shell,
+    scrollbackBuffer:
+      typeof partial.scrollbackBuffer === 'number'
+        ? partial.scrollbackBuffer
+        : DEFAULTS.scrollbackBuffer,
   };
 }
 

From 566e07b7a8be308bd37d1487959d17c56e6c8369 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 11:49:00 -0400
Subject: [PATCH 05/29] fix: rename scrollbackBuffer to scrollback in config
 interface and defaults

---
 docs/specs/config.md | 40 +++++++++++-----------------------------
 src/config.ts        |  9 +++------
 2 files changed, 14 insertions(+), 35 deletions(-)

diff --git a/docs/specs/config.md b/docs/specs/config.md
index 07412ba..192f95d 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -57,42 +57,24 @@ config ready
 ```jsonc
 {
   // Server
-  "port": 2346,
+  "port": 2346,                 // HTTP listen port; env PORT takes precedence
 
   // Shell
-  "shell": "/bin/zsh",        // default: $SHELL on Unix, %COMSPEC% on Windows
+  "shell": "/bin/zsh",          // shell for new sessions; default: $SHELL on Unix, %COMSPEC% on Windows
 
   // Terminal
-  "cols": 80,
-  "rows": 24,
-  "scrollback": 10000,        // lines in the terminal UI display buffer
-  "scrollbackBuffer": 262144, // server-side PTY replay buffer in bytes (256 KB default)
-  "cursorBlink": true,
-  "fontSize": 14,
-  "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
-
-  // Theme (Dracula defaults)
+  "cols": 80,                   // initial terminal width in columns
+  "rows": 24,                   // initial terminal height in rows
+  "scrollback": 262144,         // PTY history buffer in bytes (256 KB); used for server-side replay on reload/reconnect
+  "cursorBlink": true,          // whether the cursor blinks
+  "fontSize": 14,               // font size in px
+  "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",  // CSS font-family stack
+
+  // Theme — Dracula by default; any hex color values accepted
   "theme": {
     "background":   "#282A36",
     "foreground":   "#F8F8F2",
-    "cursor":       "#F8F8F2",
-    "selection":    "#44475A",
-    "black":        "#21222C",
-    "red":          "#FF5555",
-    "green":        "#50FA7B",
-    "yellow":       "#F1FA8C",
-    "blue":         "#BD93F9",
-    "purple":       "#FF79C6",
-    "cyan":         "#8BE9FD",
-    "white":        "#F8F8F2",
-    "brightBlack":  "#6272A4",
-    "brightRed":    "#FF6E6E",
-    "brightGreen":  "#69FF94",
-    "brightYellow": "#FFFFA5",
-    "brightBlue":   "#D6ACFF",
-    "brightPurple": "#FF92DF",
-    "brightCyan":   "#A4FFFF",
-    "brightWhite":  "#FFFFFF"
+    // ... all 16 ANSI colors + cursor + selection
   }
 }
 ```
diff --git a/src/config.ts b/src/config.ts
index 6e027db..a5f2616 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -5,7 +5,7 @@ import path from 'node:path';
 export interface Config {
   port: number;
   shell: string;
-  scrollbackBuffer: number;
+  scrollback: number;
 }
 
 export const CONFIG_DIR = path.join(os.homedir(), '.config', 'webtty');
@@ -17,7 +17,7 @@ export const DEFAULTS: Config = {
     process.platform === 'win32'
       ? (process.env.COMSPEC ?? 'cmd.exe')
       : (process.env.SHELL ?? '/bin/bash'),
-  scrollbackBuffer: 256 * 1024,
+  scrollback: 256 * 1024,
 };
 
 export function loadConfig(): Config {
@@ -44,10 +44,7 @@ export function loadConfig(): Config {
   return {
     port: typeof partial.port === 'number' ? partial.port : DEFAULTS.port,
     shell: typeof partial.shell === 'string' ? partial.shell : DEFAULTS.shell,
-    scrollbackBuffer:
-      typeof partial.scrollbackBuffer === 'number'
-        ? partial.scrollbackBuffer
-        : DEFAULTS.scrollbackBuffer,
+    scrollback: typeof partial.scrollback === 'number' ? partial.scrollback : DEFAULTS.scrollback,
   };
 }
 

From 629fd6edd7d948513d7ad526eecc53db68e35452 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 12:17:10 -0400
Subject: [PATCH 06/29] feat: update configuration to support JSONC format with
 comments

---
 bun.lock             |  8 ++++++-
 docs/specs/config.md | 44 +++++++++++++++++++++++--------------
 docs/specs/webtty.md |  2 +-
 package.json         |  2 ++
 src/config.ts        | 52 ++++++++++++++++++++++++++++++++++++++++----
 5 files changed, 86 insertions(+), 22 deletions(-)

diff --git a/bun.lock b/bun.lock
index 80b7d72..413e998 100644
--- a/bun.lock
+++ b/bun.lock
@@ -8,11 +8,13 @@
         "@lydell/node-pty": "1.2.0-beta.3",
         "commander": "14.0.0",
         "ghostty-web": "0.4.0-next.14.g6a1a50d",
+        "strip-json-comments": "3.1.1",
         "ws": "8.20.0",
       },
       "devDependencies": {
         "@biomejs/biome": "2.4.8",
         "@types/bun": "1.3.11",
+        "@types/strip-json-comments": "^3.0.0",
         "@types/ws": "8.18.1",
         "rimraf": "6.1.3",
         "semantic-release": "24.2.9",
@@ -164,6 +166,8 @@
 
     "@types/normalize-package-data": ["@types/normalize-package-data@2.4.4", "", {}, "sha512-37i+OaWTh9qeK4LSHPsyRC7NahnGotNuZvjLSgcPzblpHB3rrCJxAOgI5gCdKm7coonsaX1Of0ILiTcnZjbfxA=="],
 
+    "@types/strip-json-comments": ["@types/strip-json-comments@3.0.0", "", { "dependencies": { "strip-json-comments": "*" } }, "sha512-+vSlZeCCGm/1Q3WwBJDUSGHvADTQjRl4Fve0AG9H+A4+xgJ7yAkWKoc4g7I9UoVqtwCzjv2g/GZn4xipokMYyQ=="],
+
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
     "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
@@ -552,7 +556,7 @@
 
     "strip-final-newline": ["strip-final-newline@4.0.0", "", {}, "sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw=="],
 
-    "strip-json-comments": ["strip-json-comments@2.0.1", "", {}, "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ=="],
+    "strip-json-comments": ["strip-json-comments@3.1.1", "", {}, "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig=="],
 
     "super-regex": ["super-regex@1.1.0", "", { "dependencies": { "function-timeout": "^1.0.1", "make-asynchronous": "^1.0.1", "time-span": "^5.1.0" } }, "sha512-WHkws2ZflZe41zj6AolvvmaTrWds/VuyeYr9iPVv/oQeaIoVxMKaushfFWpOGDT+GuBrM/sVqF8KUCYQlSSTdQ=="],
 
@@ -1006,6 +1010,8 @@
 
     "path-scurry/lru-cache": ["lru-cache@11.2.7", "", {}, "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA=="],
 
+    "rc/strip-json-comments": ["strip-json-comments@2.0.1", "", {}, "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ=="],
+
     "read-pkg/parse-json": ["parse-json@8.3.0", "", { "dependencies": { "@babel/code-frame": "^7.26.2", "index-to-position": "^1.1.0", "type-fest": "^4.39.1" } }, "sha512-ybiGyvspI+fAoRQbIPRddCcSTV9/LsJbf0e/S85VLowVGzRmokfneg2kwVW/KU5rOXrPSbF1qAKPMgNTqqROQQ=="],
 
     "signale/chalk": ["chalk@2.4.2", "", { "dependencies": { "ansi-styles": "^3.2.1", "escape-string-regexp": "^1.0.5", "supports-color": "^5.3.0" } }, "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ=="],
diff --git a/docs/specs/config.md b/docs/specs/config.md
index 192f95d..ec22fcf 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -7,14 +7,14 @@
 
 ## Description
 
-webtty reads configuration from `~/.config/webtty/config.json`. The file is the single source of truth for persistent user preferences. Environment variables override config file values at runtime but never modify the file.
+webtty reads configuration from `~/.config/webtty/config.jsonc`. The file supports comments (JSONC format via `strip-json-comments`). It is the single source of truth for persistent user preferences. Environment variables override config file values at runtime but never modify the file.
 
 ## File location
 
 | Platform | Path |
 |----------|------|
-| macOS / Linux | `~/.config/webtty/config.json` |
-| Windows | `%USERPROFILE%\.config\webtty\config.json` |
+| macOS / Linux | `~/.config/webtty/config.jsonc` |
+| Windows | `%USERPROFILE%\.config\webtty\config.jsonc` |
 
 ## Lifecycle
 
@@ -57,25 +57,37 @@ config ready
 ```jsonc
 {
   // Server
-  "port": 2346,                 // HTTP listen port; env PORT takes precedence
+  // HTTP listen port; env PORT takes precedence
+  "port": 2346,
+  // Bind address; use "0.0.0.0" for remote access
+  "host": "127.0.0.1",
 
   // Shell
-  "shell": "/bin/zsh",          // shell for new sessions; default: $SHELL on Unix, %COMSPEC% on Windows
+  // Shell for new sessions; defaults to $SHELL / %COMSPEC% if omitted
+  // "shell": "/bin/zsh",
+  // $TERM env var passed to the shell
+  // "term": "xterm-256color",
 
   // Terminal
-  "cols": 80,                   // initial terminal width in columns
-  "rows": 24,                   // initial terminal height in rows
-  "scrollback": 262144,         // PTY history buffer in bytes (256 KB); used for server-side replay on reload/reconnect
-  "cursorBlink": true,          // whether the cursor blinks
-  "fontSize": 14,               // font size in px
-  "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",  // CSS font-family stack
+  // PTY history buffer in bytes (256 KB); used for server-side replay on reload/reconnect
+  // "scrollback": 262144,
+  // Initial terminal width in columns
+  // "cols": 80,
+  // Initial terminal height in rows
+  // "rows": 24,
+  // Whether the cursor blinks
+  // "cursorBlink": true,
+  // Font size in px
+  // "fontSize": 14,
+  // CSS font-family stack
+  // "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
 
   // Theme — Dracula by default; any hex color values accepted
-  "theme": {
-    "background":   "#282A36",
-    "foreground":   "#F8F8F2",
-    // ... all 16 ANSI colors + cursor + selection
-  }
+  // "theme": {
+  //   "background": "#282A36",
+  //   "foreground": "#F8F8F2",
+  //   // ... all 16 ANSI colors + cursor + selection
+  // }
 }
 ```
 
diff --git a/docs/specs/webtty.md b/docs/specs/webtty.md
index 37e0ec8..20cf9d4 100644
--- a/docs/specs/webtty.md
+++ b/docs/specs/webtty.md
@@ -87,5 +87,5 @@ Session IDs appear directly in the URL path (`/s/:id`), so they must be valid UR
 | Default session | `GET /` redirects to last-used session, or creates `main` and redirects if none exists | — | ✅ |
 | Session URL | `GET /s/:id` — serves browser client for the named session; reconnects if session already has a PTY | — | ✅ |
 | Session management | CRUD + rename over HTTP — see REST API above | [ADR 004](../adrs/004.webtty.session-api.md) | ✅ |
-| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.json`) | — | ⬜ | → [config spec](config.md) |
+| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.jsonc`) | — | ⬜ | → [config spec](config.md) |
 | Session client | Multiple browser tabs can attach to the same session simultaneously; reload replays scrollback; typing `exit` closes all tabs | [ADR 007](../adrs/007.webtty.session-client.md) | ✅ |
diff --git a/package.json b/package.json
index 08b7036..6ea5dd3 100644
--- a/package.json
+++ b/package.json
@@ -30,11 +30,13 @@
     "@lydell/node-pty": "1.2.0-beta.3",
     "commander": "14.0.0",
     "ghostty-web": "0.4.0-next.14.g6a1a50d",
+    "strip-json-comments": "3.1.1",
     "ws": "8.20.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.8",
     "@types/bun": "1.3.11",
+    "@types/strip-json-comments": "^3.0.0",
     "@types/ws": "8.18.1",
     "rimraf": "6.1.3",
     "semantic-release": "24.2.9",
diff --git a/src/config.ts b/src/config.ts
index a5f2616..ccf5c2b 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,22 +1,27 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import stripJsonComments from 'strip-json-comments';
 
 export interface Config {
   port: number;
+  host: string;
   shell: string;
+  term: string;
   scrollback: number;
 }
 
 export const CONFIG_DIR = path.join(os.homedir(), '.config', 'webtty');
-export const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+export const CONFIG_PATH = path.join(CONFIG_DIR, 'config.jsonc');
 
 export const DEFAULTS: Config = {
   port: 2346,
+  host: '127.0.0.1',
   shell:
     process.platform === 'win32'
       ? (process.env.COMSPEC ?? 'cmd.exe')
       : (process.env.SHELL ?? '/bin/bash'),
+  term: 'xterm-256color',
   scrollback: 256 * 1024,
 };
 
@@ -35,7 +40,7 @@ export function loadConfig(): Config {
 
   let parsed: unknown;
   try {
-    parsed = JSON.parse(raw);
+    parsed = JSON.parse(stripJsonComments(raw));
   } catch {
     throw new Error(`webtty: invalid JSON in config file ${CONFIG_PATH}`);
   }
@@ -43,12 +48,51 @@ export function loadConfig(): Config {
   const partial = parsed as Partial<Config>;
   return {
     port: typeof partial.port === 'number' ? partial.port : DEFAULTS.port,
+    host: typeof partial.host === 'string' ? partial.host : DEFAULTS.host,
     shell: typeof partial.shell === 'string' ? partial.shell : DEFAULTS.shell,
+    term: typeof partial.term === 'string' ? partial.term : DEFAULTS.term,
     scrollback: typeof partial.scrollback === 'number' ? partial.scrollback : DEFAULTS.scrollback,
   };
 }
 
-export function saveConfig(config: Config): void {
+export function saveConfig(_config: Config): void {
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  const template = [
+    '{',
+    '  // Server',
+    '  // HTTP listen port; env PORT takes precedence',
+    '  "port": 2346,',
+    '  // Bind address; use "0.0.0.0" for remote access',
+    '  "host": "127.0.0.1",',
+    '',
+    '  // Shell',
+    '  // Shell for new sessions; defaults to $SHELL / %COMSPEC% if omitted',
+    '  // "shell": "/bin/zsh",',
+    '  // $TERM env var passed to the shell',
+    '  // "term": "xterm-256color",',
+    '',
+    '  // Terminal',
+    '  // PTY history buffer in bytes (256 KB); used for server-side replay on reload/reconnect',
+    '  // "scrollback": 262144,',
+    '  // Initial terminal width in columns',
+    '  // "cols": 80,',
+    '  // Initial terminal height in rows',
+    '  // "rows": 24,',
+    '  // Whether the cursor blinks',
+    '  // "cursorBlink": true,',
+    '  // Font size in px',
+    '  // "fontSize": 14,',
+    '  // CSS font-family stack',
+    '  // "fontFamily": "\'FiraMono Nerd Font\', Menlo, Monaco, \'Courier New\', monospace",',
+    '',
+    '  // Theme — Dracula by default; any hex color values accepted',
+    '  // "theme": {',
+    '  //   "background": "#282A36",',
+    '  //   "foreground": "#F8F8F2",',
+    '  //   // ... all 16 ANSI colors + cursor + selection',
+    '  // }',
+    '}',
+    '',
+  ].join('\n');
+  fs.writeFileSync(CONFIG_PATH, template, 'utf8');
 }

From b9bc62ac0846fbd563d168182e37e3825b209a9f Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 12:29:24 -0400
Subject: [PATCH 07/29] fix: update theme comments in configuration to clarify
 terminal color palette

---
 docs/specs/config.md | 25 +++++++++++++++++++++----
 src/config.ts        | 25 +++++++++++++++++++++----
 2 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/docs/specs/config.md b/docs/specs/config.md
index ec22fcf..d446ca5 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -82,11 +82,28 @@ config ready
   // CSS font-family stack
   // "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
 
-  // Theme — Dracula by default; any hex color values accepted
+  // Theme — terminal color palette, Dracula by default
   // "theme": {
-  //   "background": "#282A36",
-  //   "foreground": "#F8F8F2",
-  //   // ... all 16 ANSI colors + cursor + selection
+  //   "background":   "#282A36",  // terminal background
+  //   "foreground":   "#F8F8F2",  // default text color
+  //   "cursor":       "#F8F8F2",  // cursor color
+  //   "selection":    "#44475A",  // selection highlight
+  //   "black":        "#21222C",  // ANSI 0
+  //   "red":          "#FF5555",  // ANSI 1
+  //   "green":        "#50FA7B",  // ANSI 2
+  //   "yellow":       "#F1FA8C",  // ANSI 3
+  //   "blue":         "#BD93F9",  // ANSI 4
+  //   "purple":       "#FF79C6",  // ANSI 5
+  //   "cyan":         "#8BE9FD",  // ANSI 6
+  //   "white":        "#F8F8F2",  // ANSI 7
+  //   "brightBlack":  "#6272A4",  // ANSI 8
+  //   "brightRed":    "#FF6E6E",  // ANSI 9
+  //   "brightGreen":  "#69FF94",  // ANSI 10
+  //   "brightYellow": "#FFFFA5",  // ANSI 11
+  //   "brightBlue":   "#D6ACFF",  // ANSI 12
+  //   "brightPurple": "#FF92DF",  // ANSI 13
+  //   "brightCyan":   "#A4FFFF",  // ANSI 14
+  //   "brightWhite":  "#FFFFFF"   // ANSI 15
   // }
 }
 ```
diff --git a/src/config.ts b/src/config.ts
index ccf5c2b..9dc2fcd 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -85,11 +85,28 @@ export function saveConfig(_config: Config): void {
     '  // CSS font-family stack',
     '  // "fontFamily": "\'FiraMono Nerd Font\', Menlo, Monaco, \'Courier New\', monospace",',
     '',
-    '  // Theme — Dracula by default; any hex color values accepted',
+    '  // Theme — terminal color palette, Dracula by default',
     '  // "theme": {',
-    '  //   "background": "#282A36",',
-    '  //   "foreground": "#F8F8F2",',
-    '  //   // ... all 16 ANSI colors + cursor + selection',
+    '  //   "background":   "#282A36",  // terminal background',
+    '  //   "foreground":   "#F8F8F2",  // default text color',
+    '  //   "cursor":       "#F8F8F2",  // cursor color',
+    '  //   "selection":    "#44475A",  // selection highlight',
+    '  //   "black":        "#21222C",  // ANSI 0',
+    '  //   "red":          "#FF5555",  // ANSI 1',
+    '  //   "green":        "#50FA7B",  // ANSI 2',
+    '  //   "yellow":       "#F1FA8C",  // ANSI 3',
+    '  //   "blue":         "#BD93F9",  // ANSI 4',
+    '  //   "purple":       "#FF79C6",  // ANSI 5',
+    '  //   "cyan":         "#8BE9FD",  // ANSI 6',
+    '  //   "white":        "#F8F8F2",  // ANSI 7',
+    '  //   "brightBlack":  "#6272A4",  // ANSI 8',
+    '  //   "brightRed":    "#FF6E6E",  // ANSI 9',
+    '  //   "brightGreen":  "#69FF94",  // ANSI 10',
+    '  //   "brightYellow": "#FFFFA5",  // ANSI 11',
+    '  //   "brightBlue":   "#D6ACFF",  // ANSI 12',
+    '  //   "brightPurple": "#FF92DF",  // ANSI 13',
+    '  //   "brightCyan":   "#A4FFFF",  // ANSI 14',
+    '  //   "brightWhite":  "#FFFFFF"   // ANSI 15',
     '  // }',
     '}',
     '',

From 8d07db897f3211193073d850e7c58b2d0a2730fb Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 15:04:28 -0400
Subject: [PATCH 08/29] feat: implement configuration file support with
 user-defined settings for terminal and server options

---
 docs/adrs/008.webtty.config.md |  66 +++++++++++++++
 docs/specs/config.md           |   7 +-
 docs/specs/webtty.md           |   2 +-
 src/config.ts                  | 145 ++++++++++++++++++++++++---------
 src/pty/bun.ts                 |  10 ++-
 src/pty/index.ts               |  14 ++--
 src/pty/node.ts                |  12 ++-
 src/server/client.test.ts      |  11 +--
 src/server/client.ts           |  43 +++-------
 src/server/index.ts            |  13 +--
 src/server/routes.ts           |   4 +-
 src/server/session.ts          |   2 -
 src/server/websocket.ts        |   9 +-
 13 files changed, 239 insertions(+), 99 deletions(-)
 create mode 100644 docs/adrs/008.webtty.config.md

diff --git a/docs/adrs/008.webtty.config.md b/docs/adrs/008.webtty.config.md
new file mode 100644
index 0000000..e206921
--- /dev/null
+++ b/docs/adrs/008.webtty.config.md
@@ -0,0 +1,66 @@
+# ADR 008: webtty — Config File
+
+**SPEC:** [config](../specs/config.md)
+**Status:** Accepted
+**Date:** 2026-03-23
+
+---
+
+## Context
+
+All webtty settings are currently hardcoded or read from environment variables only. Users have no persistent way to change port, shell, terminal appearance, or theme without modifying source or wrapping the binary in a shell script. ADR 002 explicitly deferred this: "Port is hardcoded at 2346 — will become configurable when the config file slice lands."
+
+Three concerns drive the design:
+
+1. **Where is the file?** It must follow platform conventions and be easy to find.
+2. **What format?** Must be human-editable; comments are essential for a config file users edit directly.
+3. **What is the load/merge strategy?** Adding new keys in future versions must not break existing configs.
+
+## Decision
+
+**File location**: `~/.config/webtty/config.jsonc` — follows the XDG Base Directory convention used by most modern CLI tools (opencode, lazygit, starship, etc.). Created automatically on first run with commented-out defaults.
+
+**Format**: JSONC (JSON with comments) via `strip-json-comments`. Native JSON is hostile to config files — users cannot annotate their choices. `strip-json-comments` is 8.2 KB, 128M weekly downloads, zero dependencies. Bun has native `Bun.JSONC` since v1.3.6 but using the npm package keeps the code path identical on Node and Bun.
+
+**Load strategy**: Merge partial config over defaults — unknown keys are ignored, missing keys fall back to built-in defaults. This means adding new config keys in future versions is non-breaking: an old `config.jsonc` with only `port` still works correctly with a binary that added `theme`.
+
+**Env overrides**: `PORT` overrides `config.port` at runtime. Applied after file load, never written back to the file.
+
+**Terminal config delivery**: Server-side config values that affect the browser terminal (cols, rows, fontSize, fontFamily, cursorBlink, scrollback lines, theme) are injected into the HTML template returned by `GET /s/:id`. The client reads them from the rendered page — no separate API endpoint needed.
+
+**`scrollback`**: A single value in bytes (`256 * 1024` default). Controls both the server-side PTY replay ring buffer (`session.ts`) and the client-side terminal line buffer (derived as `Math.ceil(scrollback / 80)` — assumes ~80 bytes/line average). One knob, one mental model.
+
+## Considered Options
+
+**Option A: `.webtty/config.json` in home directory**
+
+- **Pros**: Simple, familiar to Node.js users.
+- **Cons**: Clutters `~` with a dot-directory. XDG convention (`~/.config/`) is now the standard for CLI tools.
+
+**Option B: TOML format**
+
+- **Pros**: More readable for nested structures (theme colors).
+- **Cons**: Requires a TOML parser dependency (~50 KB). JSONC is sufficient and consistent with the existing JSON surface (REST API, `package.json`).
+
+**Option C: Separate env var for every setting**
+
+- **Pros**: No new file format.
+- **Cons**: Env vars are session-scoped, not persistent. Unwieldy for nested settings like theme colors. Users expect a config file for terminal emulators.
+
+**Option D: Bun-native JSONC only**
+
+- **Pros**: Zero bytes added to bundle.
+- **Cons**: Breaks Node.js compatibility. webtty explicitly supports both runtimes.
+
+## Consequences
+
+- First run creates `~/.config/webtty/config.jsonc` with commented defaults — users have a ready-to-edit file immediately
+- `port`, `host`, `shell`, `term`, `scrollback`, `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, and `theme` are all user-configurable
+- Adding new config keys in future versions is non-breaking
+- `strip-json-comments` added as a production dependency (8.2 KB unpacked)
+- Terminal appearance config is injected server-side into the HTML — no client-side config fetch needed
+
+## Related Decisions
+
+- [ADR 002 — CLI start/stop](002.cli.start-stop.md): explicitly deferred config file; port hardcoded at 2346
+- [ADR 007 — Session client](007.webtty.session-client.md): terminal defaults (cols, rows, theme) previously hardcoded in `client.ts`
diff --git a/docs/specs/config.md b/docs/specs/config.md
index d446ca5..1bab8f0 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -112,4 +112,9 @@ config ready
 
 | Feature | Description | ADR | Done? |
 |---------|-------------|-----|-------|
-| Config lifecycle | First-run write + subsequent load, as described above | — | ⬜ |
+| Config lifecycle | First-run write + subsequent load, merge with defaults, env overrides | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `port` / `host` | Override HTTP listen port and bind address | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
+| `shell` / `term` | Override shell and `$TERM` env var for new sessions | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
+| `scrollback` | PTY history buffer size in bytes | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
+| Terminal appearance | `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink` injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
+| `theme` | Terminal color palette injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
diff --git a/docs/specs/webtty.md b/docs/specs/webtty.md
index 20cf9d4..bf6ee14 100644
--- a/docs/specs/webtty.md
+++ b/docs/specs/webtty.md
@@ -87,5 +87,5 @@ Session IDs appear directly in the URL path (`/s/:id`), so they must be valid UR
 | Default session | `GET /` redirects to last-used session, or creates `main` and redirects if none exists | — | ✅ |
 | Session URL | `GET /s/:id` — serves browser client for the named session; reconnects if session already has a PTY | — | ✅ |
 | Session management | CRUD + rename over HTTP — see REST API above | [ADR 004](../adrs/004.webtty.session-api.md) | ✅ |
-| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.jsonc`) | — | ⬜ | → [config spec](config.md) |
+| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.jsonc`) | [ADR 008](../adrs/008.webtty.config.md) | ⬜ | → [config spec](config.md) |
 | Session client | Multiple browser tabs can attach to the same session simultaneously; reload replays scrollback; typing `exit` closes all tabs | [ADR 007](../adrs/007.webtty.session-client.md) | ✅ |
diff --git a/src/config.ts b/src/config.ts
index 9dc2fcd..1ffef8e 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -3,32 +3,91 @@ import os from 'node:os';
 import path from 'node:path';
 import stripJsonComments from 'strip-json-comments';
 
+export interface Theme {
+  background?: string;
+  foreground?: string;
+  cursor?: string;
+  selection?: string;
+  black?: string;
+  red?: string;
+  green?: string;
+  yellow?: string;
+  blue?: string;
+  purple?: string;
+  cyan?: string;
+  white?: string;
+  brightBlack?: string;
+  brightRed?: string;
+  brightGreen?: string;
+  brightYellow?: string;
+  brightBlue?: string;
+  brightPurple?: string;
+  brightCyan?: string;
+  brightWhite?: string;
+}
+
 export interface Config {
   port: number;
   host: string;
   shell: string;
   term: string;
+  colorTerm: string;
   scrollback: number;
+  cols: number;
+  rows: number;
+  fontSize: number;
+  fontFamily: string;
+  cursorBlink: boolean;
+  theme: Theme;
 }
 
-export const CONFIG_DIR = path.join(os.homedir(), '.config', 'webtty');
-export const CONFIG_PATH = path.join(CONFIG_DIR, 'config.jsonc');
+const CONFIG_PATH = path.join(os.homedir(), '.config', 'webtty', 'config.jsonc');
+
+export const DEFAULT_THEME: Theme = {
+  background: '#282A36',
+  foreground: '#F8F8F2',
+  cursor: '#F8F8F2',
+  selection: '#44475A',
+  black: '#21222C',
+  red: '#FF5555',
+  green: '#50FA7B',
+  yellow: '#F1FA8C',
+  blue: '#BD93F9',
+  purple: '#FF79C6',
+  cyan: '#8BE9FD',
+  white: '#F8F8F2',
+  brightBlack: '#6272A4',
+  brightRed: '#FF6E6E',
+  brightGreen: '#69FF94',
+  brightYellow: '#FFFFA5',
+  brightBlue: '#D6ACFF',
+  brightPurple: '#FF92DF',
+  brightCyan: '#A4FFFF',
+  brightWhite: '#FFFFFF',
+};
 
-export const DEFAULTS: Config = {
+export const DEFAULT_CONFIG: Config = {
   port: 2346,
   host: '127.0.0.1',
   shell:
     process.platform === 'win32'
       ? (process.env.COMSPEC ?? 'cmd.exe')
       : (process.env.SHELL ?? '/bin/bash'),
-  term: 'xterm-256color',
+  term: process.env.TERM ?? 'xterm-256color',
+  colorTerm: 'truecolor',
   scrollback: 256 * 1024,
+  cols: 80,
+  rows: 24,
+  fontSize: 14,
+  fontFamily: "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
+  cursorBlink: true,
+  theme: DEFAULT_THEME,
 };
 
 export function loadConfig(): Config {
   if (!fs.existsSync(CONFIG_PATH)) {
-    saveConfig(DEFAULTS);
-    return { ...DEFAULTS };
+    saveConfig(DEFAULT_CONFIG);
+    return { ...DEFAULT_CONFIG };
   }
 
   let raw: string;
@@ -45,34 +104,42 @@ export function loadConfig(): Config {
     throw new Error(`webtty: invalid JSON in config file ${CONFIG_PATH}`);
   }
 
-  const partial = parsed as Partial<Config>;
+  const p = parsed as Partial<Config>;
   return {
-    port: typeof partial.port === 'number' ? partial.port : DEFAULTS.port,
-    host: typeof partial.host === 'string' ? partial.host : DEFAULTS.host,
-    shell: typeof partial.shell === 'string' ? partial.shell : DEFAULTS.shell,
-    term: typeof partial.term === 'string' ? partial.term : DEFAULTS.term,
-    scrollback: typeof partial.scrollback === 'number' ? partial.scrollback : DEFAULTS.scrollback,
+    ...DEFAULT_CONFIG,
+    ...(typeof p.port === 'number' && { port: p.port }),
+    ...(typeof p.host === 'string' && { host: p.host }),
+    ...(typeof p.shell === 'string' && { shell: p.shell }),
+    ...(typeof p.term === 'string' && { term: p.term }),
+    ...(typeof p.scrollback === 'number' && { scrollback: p.scrollback }),
+    ...(typeof p.cols === 'number' && { cols: p.cols }),
+    ...(typeof p.rows === 'number' && { rows: p.rows }),
+    ...(typeof p.fontSize === 'number' && { fontSize: p.fontSize }),
+    ...(typeof p.fontFamily === 'string' && { fontFamily: p.fontFamily }),
+    ...(typeof p.cursorBlink === 'boolean' && { cursorBlink: p.cursorBlink }),
+    ...(p.theme && typeof p.theme === 'object' && { theme: { ...DEFAULT_THEME, ...p.theme } }),
   };
 }
 
 export function saveConfig(_config: Config): void {
-  fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  const template = [
+  const th = DEFAULT_THEME;
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  const content = [
     '{',
     '  // Server',
     '  // HTTP listen port; env PORT takes precedence',
     '  "port": 2346,',
     '  // Bind address; use "0.0.0.0" for remote access',
-    '  "host": "127.0.0.1",',
+    '  "host": "127.0.0.1"',
     '',
     '  // Shell',
-    '  // Shell for new sessions; defaults to $SHELL / %COMSPEC% if omitted',
+    '  // Shell for new sessions; defaults to $COMSPEC / cmd.exe on Windows, $SHELL / /bin/bash on Unix',
     '  // "shell": "/bin/zsh",',
-    '  // $TERM env var passed to the shell',
+    '  // $TERM env var passed to the shell; defaults to $TERM from environment',
     '  // "term": "xterm-256color",',
     '',
     '  // Terminal',
-    '  // PTY history buffer in bytes (256 KB); used for server-side replay on reload/reconnect',
+    '  // PTY history buffer in bytes; used for server-side replay on reload/reconnect',
     '  // "scrollback": 262144,',
     '  // Initial terminal width in columns',
     '  // "cols": 80,',
@@ -87,29 +154,29 @@ export function saveConfig(_config: Config): void {
     '',
     '  // Theme — terminal color palette, Dracula by default',
     '  // "theme": {',
-    '  //   "background":   "#282A36",  // terminal background',
-    '  //   "foreground":   "#F8F8F2",  // default text color',
-    '  //   "cursor":       "#F8F8F2",  // cursor color',
-    '  //   "selection":    "#44475A",  // selection highlight',
-    '  //   "black":        "#21222C",  // ANSI 0',
-    '  //   "red":          "#FF5555",  // ANSI 1',
-    '  //   "green":        "#50FA7B",  // ANSI 2',
-    '  //   "yellow":       "#F1FA8C",  // ANSI 3',
-    '  //   "blue":         "#BD93F9",  // ANSI 4',
-    '  //   "purple":       "#FF79C6",  // ANSI 5',
-    '  //   "cyan":         "#8BE9FD",  // ANSI 6',
-    '  //   "white":        "#F8F8F2",  // ANSI 7',
-    '  //   "brightBlack":  "#6272A4",  // ANSI 8',
-    '  //   "brightRed":    "#FF6E6E",  // ANSI 9',
-    '  //   "brightGreen":  "#69FF94",  // ANSI 10',
-    '  //   "brightYellow": "#FFFFA5",  // ANSI 11',
-    '  //   "brightBlue":   "#D6ACFF",  // ANSI 12',
-    '  //   "brightPurple": "#FF92DF",  // ANSI 13',
-    '  //   "brightCyan":   "#A4FFFF",  // ANSI 14',
-    '  //   "brightWhite":  "#FFFFFF"   // ANSI 15',
+    `  //   "background":   "${th.background}",  // terminal background`,
+    `  //   "foreground":   "${th.foreground}",  // default text color`,
+    `  //   "cursor":       "${th.cursor}",  // cursor color`,
+    `  //   "selection":    "${th.selection}",  // selection highlight`,
+    `  //   "black":        "${th.black}",  // ANSI 0`,
+    `  //   "red":          "${th.red}",  // ANSI 1`,
+    `  //   "green":        "${th.green}",  // ANSI 2`,
+    `  //   "yellow":       "${th.yellow}",  // ANSI 3`,
+    `  //   "blue":         "${th.blue}",  // ANSI 4`,
+    `  //   "purple":       "${th.purple}",  // ANSI 5`,
+    `  //   "cyan":         "${th.cyan}",  // ANSI 6`,
+    `  //   "white":        "${th.white}",  // ANSI 7`,
+    `  //   "brightBlack":  "${th.brightBlack}",  // ANSI 8`,
+    `  //   "brightRed":    "${th.brightRed}",  // ANSI 9`,
+    `  //   "brightGreen":  "${th.brightGreen}",  // ANSI 10`,
+    `  //   "brightYellow": "${th.brightYellow}",  // ANSI 11`,
+    `  //   "brightBlue":   "${th.brightBlue}",  // ANSI 12`,
+    `  //   "brightPurple": "${th.brightPurple}",  // ANSI 13`,
+    `  //   "brightCyan":   "${th.brightCyan}",  // ANSI 14`,
+    `  //   "brightWhite":  "${th.brightWhite}"   // ANSI 15`,
     '  // }',
     '}',
     '',
   ].join('\n');
-  fs.writeFileSync(CONFIG_PATH, template, 'utf8');
+  fs.writeFileSync(CONFIG_PATH, content, 'utf8');
 }
diff --git a/src/pty/bun.ts b/src/pty/bun.ts
index 31df2eb..de9c75e 100644
--- a/src/pty/bun.ts
+++ b/src/pty/bun.ts
@@ -1,7 +1,13 @@
 import { homedir } from 'node:os';
 import type { PtyProcess } from './types';
 
-export function spawn(shell: string, cols: number, rows: number): PtyProcess {
+export function spawn(
+  shell: string,
+  cols: number,
+  rows: number,
+  term: string,
+  colorTerm: string,
+): PtyProcess {
   let onDataCb: ((data: string) => void) | undefined;
   let onExitCb: ((e: { exitCode: number }) => void) | undefined;
 
@@ -14,7 +20,7 @@ export function spawn(shell: string, cols: number, rows: number): PtyProcess {
       },
     },
     cwd: homedir(),
-    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+    env: { ...process.env, TERM: term, COLORTERM: colorTerm },
   });
 
   proc.exited.then((exitCode) => {
diff --git a/src/pty/index.ts b/src/pty/index.ts
index ae2bb65..4d35d91 100644
--- a/src/pty/index.ts
+++ b/src/pty/index.ts
@@ -7,10 +7,12 @@ const { spawn: _spawn } = await (isBun ? import('./bun') : import('./node'));
 
 export const spawn = _spawn;
 
-export function spawnForSession(cols: number, rows: number) {
-  const shell =
-    process.platform === 'win32'
-      ? (process.env.COMSPEC ?? 'cmd.exe')
-      : (process.env.SHELL ?? '/bin/bash');
-  return _spawn(shell, cols, rows);
+export function spawnForSession(
+  cols: number,
+  rows: number,
+  shell: string,
+  term: string,
+  colorTerm: string,
+) {
+  return _spawn(shell, cols, rows, term, colorTerm);
 }
diff --git a/src/pty/node.ts b/src/pty/node.ts
index 8eae6db..4dbaf01 100644
--- a/src/pty/node.ts
+++ b/src/pty/node.ts
@@ -2,13 +2,19 @@ import { homedir } from 'node:os';
 import nodePty from '@lydell/node-pty';
 import type { PtyProcess } from './types';
 
-export function spawn(shell: string, cols: number, rows: number): PtyProcess {
+export function spawn(
+  shell: string,
+  cols: number,
+  rows: number,
+  term: string,
+  colorTerm: string,
+): PtyProcess {
   const ptyProc = nodePty.spawn(shell, [], {
-    name: 'xterm-256color',
+    name: term,
     cols,
     rows,
     cwd: homedir(),
-    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+    env: { ...process.env, TERM: term, COLORTERM: colorTerm },
   });
 
   return {
diff --git a/src/server/client.test.ts b/src/server/client.test.ts
index a4a15ea..db341db 100644
--- a/src/server/client.test.ts
+++ b/src/server/client.test.ts
@@ -1,31 +1,32 @@
 import { describe, expect, test } from 'bun:test';
+import { DEFAULT_CONFIG } from '../config';
 import { render } from './client';
 
 describe('clientShell', () => {
   test('returns valid HTML document', () => {
-    const html = render('my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('<!doctype html>');
     expect(html).toContain('<html');
     expect(html).toContain('</html>');
   });
 
   test('injects session id into title', () => {
-    const html = render('my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('webtty — my-session');
   });
 
   test('injects session id as JS string literal', () => {
-    const html = render('my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('"my-session"');
   });
 
   test('JS string literal uses JSON.stringify so special chars are escaped', () => {
-    const html = render('my"session');
+    const html = render('my"session', DEFAULT_CONFIG);
     expect(html).toContain('"my\\"session"');
   });
 
   test('ws path uses session id', () => {
-    const html = render('my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('/ws/');
   });
 });
diff --git a/src/server/client.ts b/src/server/client.ts
index 2553df0..c68c3d6 100644
--- a/src/server/client.ts
+++ b/src/server/client.ts
@@ -1,4 +1,8 @@
-export function render(sessionId: string): string {
+import type { Config } from '../config';
+
+export function render(sessionId: string, config: Config): string {
+  const theme = config.theme;
+  const themeJson = JSON.stringify(theme, null, 8).replace(/^/gm, '        ').trimStart();
   return `<!doctype html>
 <html lang="en">
   <head>
@@ -8,7 +12,7 @@ export function render(sessionId: string): string {
     <style>
       * { margin: 0; padding: 0; box-sizing: border-box; }
 
-      html, body, #terminal { width: 100%; height: 100%; overflow: hidden; background: #282A36; }
+      html, body, #terminal { width: 100%; height: 100%; overflow: hidden; background: ${theme.background ?? '#282A36'}; }
 
       #terminal canvas { display: block; }
     </style>
@@ -21,34 +25,13 @@ export function render(sessionId: string): string {
 
       await init();
       const term = new Terminal({
-        cols: 80,
-        rows: 24,
-        cursorBlink: true,
-        fontSize: 14,
-        fontFamily: "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
-        scrollback: 10000,
-        theme: {
-          background:   '#282A36',
-          foreground:   '#F8F8F2',
-          cursor:       '#F8F8F2',
-          selection:    '#44475A',
-          black:        '#21222C',
-          red:          '#FF5555',
-          green:        '#50FA7B',
-          yellow:       '#F1FA8C',
-          blue:         '#BD93F9',
-          purple:       '#FF79C6',
-          cyan:         '#8BE9FD',
-          white:        '#F8F8F2',
-          brightBlack:  '#6272A4',
-          brightRed:    '#FF6E6E',
-          brightGreen:  '#69FF94',
-          brightYellow: '#FFFFA5',
-          brightBlue:   '#D6ACFF',
-          brightPurple: '#FF92DF',
-          brightCyan:   '#A4FFFF',
-          brightWhite:  '#FFFFFF',
-        },
+        cols: ${config.cols},
+        rows: ${config.rows},
+        cursorBlink: ${config.cursorBlink},
+        fontSize: ${config.fontSize},
+        fontFamily: ${JSON.stringify(config.fontFamily)},
+        scrollback: ${Math.ceil(config.scrollback / 80)},
+        theme: ${themeJson},
       });
 
       const fitAddon = new FitAddon();
diff --git a/src/server/index.ts b/src/server/index.ts
index 40cf9b1..c2efcb9 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -1,15 +1,18 @@
 import http from 'node:http';
+import { loadConfig } from '../config';
 import { handleRequest } from './routes';
 import { sessionRegistry } from './session';
 import { findGhosttyWeb } from './static';
 import { createWebSocketServer } from './websocket';
 
-const HTTP_PORT = Number(process.env.PORT) || 2346;
+const config = loadConfig();
+const HTTP_PORT = Number(process.env.PORT) || config.port;
+const HTTP_HOST = config.host;
 
 const { distPath, wasmPath } = findGhosttyWeb();
 
 const httpServer = http.createServer((req, res) => {
-  handleRequest(req, res, distPath, wasmPath, () => {
+  handleRequest(req, res, distPath, wasmPath, config, () => {
     for (const session of sessionRegistry.values()) {
       session.pty?.kill();
       for (const client of session.clients) client.close(1001, 'server stopped');
@@ -24,7 +27,7 @@ const httpServer = http.createServer((req, res) => {
   });
 });
 
-const wss = createWebSocketServer(httpServer);
+const wss = createWebSocketServer(httpServer, config);
 
 process.on('SIGINT', () => {
   console.log('\n\nShutting down...');
@@ -41,6 +44,6 @@ process.on('SIGINT', () => {
   });
 });
 
-httpServer.listen(HTTP_PORT, '127.0.0.1', () => {
-  console.log(`listening on http://127.0.0.1:${HTTP_PORT}`);
+httpServer.listen(HTTP_PORT, HTTP_HOST, () => {
+  console.log(`listening on http://${HTTP_HOST}:${HTTP_PORT}`);
 });
diff --git a/src/server/routes.ts b/src/server/routes.ts
index c24676a..08cbf1c 100644
--- a/src/server/routes.ts
+++ b/src/server/routes.ts
@@ -1,5 +1,6 @@
 import type http from 'node:http';
 import path from 'node:path';
+import type { Config } from '../config';
 import { render } from './client';
 import {
   createSession,
@@ -48,6 +49,7 @@ export async function handleRequest(
   res: http.ServerResponse,
   distPath: string,
   wasmPath: string,
+  config: Config,
   onStop: () => void,
 ): Promise<void> {
   const url = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
@@ -198,7 +200,7 @@ export async function handleRequest(
       return;
     }
     res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end(render(id));
+    res.end(render(id, config));
     return;
   }
 
diff --git a/src/server/session.ts b/src/server/session.ts
index 61e6c55..d03d7d4 100644
--- a/src/server/session.ts
+++ b/src/server/session.ts
@@ -1,8 +1,6 @@
 import type { WebSocket as WS } from 'ws';
 import type { PtyProcess } from '../pty';
 
-export const SCROLLBACK_MAX = 256 * 1024;
-
 export interface Session {
   id: string;
   createdAt: number;
diff --git a/src/server/websocket.ts b/src/server/websocket.ts
index 4932743..a89fb02 100644
--- a/src/server/websocket.ts
+++ b/src/server/websocket.ts
@@ -1,10 +1,11 @@
 import type http from 'node:http';
 import type { WebSocket as WS } from 'ws';
 import { WebSocketServer } from 'ws';
+import type { Config } from '../config';
 import { spawnForSession } from '../pty';
-import { SCROLLBACK_MAX, sessionRegistry, setLastUsedId } from './session';
+import { sessionRegistry, setLastUsedId } from './session';
 
-export function createWebSocketServer(httpServer: http.Server): WebSocketServer {
+export function createWebSocketServer(httpServer: http.Server, config: Config): WebSocketServer {
   const wss = new WebSocketServer({ noServer: true });
 
   httpServer.on('upgrade', (req, socket, head) => {
@@ -54,10 +55,10 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
     setLastUsedId(id);
 
     if (!session.pty) {
-      session.pty = spawnForSession(cols, rows);
+      session.pty = spawnForSession(cols, rows, config.shell, config.term, config.colorTerm);
 
       session.pty.onData((data: string) => {
-        session.scrollback = (session.scrollback + data).slice(-SCROLLBACK_MAX);
+        session.scrollback = (session.scrollback + data).slice(-config.scrollback);
         for (const client of session.clients) {
           if (client.readyState === client.OPEN) {
             client.send(data, { binary: false });

From f4dcc9e9fe7c76ae7f2e9da4c936972db2fc205e Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 17:53:55 -0400
Subject: [PATCH 09/29] fix: handle error when saving default config in
 loadConfig function

---
 src/config.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/config.ts b/src/config.ts
index 1ffef8e..fec287e 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -86,8 +86,14 @@ export const DEFAULT_CONFIG: Config = {
 
 export function loadConfig(): Config {
   if (!fs.existsSync(CONFIG_PATH)) {
-    saveConfig(DEFAULT_CONFIG);
-    return { ...DEFAULT_CONFIG };
+    try {
+      saveConfig(DEFAULT_CONFIG);
+    } catch (err) {
+      console.warn(
+        `webtty: failed to write default config to ${CONFIG_PATH}: ${(err as Error).message}`,
+      );
+      return { ...DEFAULT_CONFIG };
+    }
   }
 
   let raw: string;

From 1360530b78460e6bd5de7e142fe5da349a0748a6 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 17:58:25 -0400
Subject: [PATCH 10/29] feat: implement hot config reload for appearance
 settings on tab reload

---
 docs/adrs/009.webtty.config-hot-reload.md | 50 +++++++++++++++++++++++
 docs/specs/config.md                      | 28 +++++++++----
 src/server/routes.ts                      |  4 +-
 3 files changed, 72 insertions(+), 10 deletions(-)
 create mode 100644 docs/adrs/009.webtty.config-hot-reload.md

diff --git a/docs/adrs/009.webtty.config-hot-reload.md b/docs/adrs/009.webtty.config-hot-reload.md
new file mode 100644
index 0000000..0baf641
--- /dev/null
+++ b/docs/adrs/009.webtty.config-hot-reload.md
@@ -0,0 +1,50 @@
+# ADR 009: webtty — Config Hot Reload
+
+**SPEC:** [config](../specs/config.md)
+**Status:** Accepted
+**Date:** 2026-03-23
+
+---
+
+## Context
+
+Config is currently loaded once at server startup and held in memory for the lifetime of the process. Users who edit `~/.config/webtty/config.jsonc` must restart the server to see their changes — even for purely cosmetic settings like font size or theme colors.
+
+A full hot-reload (e.g. `fs.watch` triggering a live update mid-session) is impractical: the terminal is already initialized in the browser with the old values, and pushing new font/theme settings to a live xterm instance requires non-trivial client-side logic. However, a tab reload already reconstructs the terminal from scratch — the browser fetches `GET /s/:id`, the server renders fresh HTML with config injected, and the client re-initializes xterm. This is a natural reload boundary.
+
+## Decision
+
+**Re-read `config.jsonc` on every `GET /s/:id` request** instead of using the startup-cached value. No file watcher, no WebSocket push, no client changes.
+
+- `loadConfig()` is called inside the `GET /s/:id` handler, not at module load time.
+- `port` and `host` remain read once at startup — they are bound to the OS socket and cannot change without a restart.
+- `shell` and `term` are re-read on tab reload; they apply to *new* PTY processes only. An already-running session is unaffected.
+- All appearance settings (`cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, `scrollback`, `theme`) take effect immediately on the next tab reload.
+
+## Considered Options
+
+**Option A: `fs.watch` + WebSocket push to live terminal**
+
+- **Pros**: Truly live — no reload needed.
+- **Cons**: Requires client-side logic to apply new theme/font to a running xterm instance. xterm's `Terminal.options` setter works for some properties but not all (e.g. `fontFamily` requires a full re-render). Significant complexity for marginal benefit — users editing config will naturally reload anyway.
+
+**Option B: Re-read on every request (chosen)**
+
+- **Pros**: Zero client changes. Zero file watcher infrastructure. Works with the existing reload boundary. The extra `fs.readFileSync` per page load is negligible (config file is ~3 KB, loaded once per tab open).
+- **Cons**: Config changes don't apply to a live tab without a reload — acceptable given the use case.
+
+**Option C: Keep startup-only load, add `POST /api/config/reload` endpoint**
+
+- **Pros**: Explicit reload, avoids per-request I/O.
+- **Cons**: Requires the user to manually hit an endpoint or use a CLI command. Tab reload is already the natural trigger; adding an extra step is worse UX.
+
+## Consequences
+
+- Editing `~/.config/webtty/config.jsonc` and reloading the browser tab picks up all appearance changes immediately — no server restart needed.
+- `port` / `host` changes still require a server restart (expected; the socket is already bound).
+- `loadConfig()` adds one `fs.readFileSync` + JSON parse per tab load — negligible cost.
+- The startup-cached `config` in `index.ts` is retained only for `port`/`host` (server bind) and passed to the WebSocket handler for PTY defaults; the `GET /s/:id` route calls `loadConfig()` fresh.
+
+## Related Decisions
+
+- [ADR 008 — Config file](008.webtty.config.md): established config file location, format, and load strategy
diff --git a/docs/specs/config.md b/docs/specs/config.md
index 1bab8f0..b7ea167 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -28,29 +28,40 @@ config file exists? ────────────────────
    │                                    │
    ▼                                    ▼
 read + parse JSON ◄──────── write defaults to file
+   │                              │ write fails?
+   ▼                              ▼
+valid JSON? ──────── no ──► warn + use defaults in memory
    │
    ▼
-valid JSON? ────────────────────────────┐
-   │                                    │
-  yes                                   no
-   │                                    │
-   ▼                                    ▼
-merge with defaults                error: print
-(unknown keys ignored)             path, exit
+merge with defaults
+(unknown keys ignored)
    │
    ▼
 apply env overrides
 (PORT > config.port, etc.)
    │
    ▼
-config ready
+config ready (port/host locked for server lifetime)
+```
+
+```
+browser tab reloads  (GET /s/:id)
+   │
+   ▼
+loadConfig() — re-read file from disk
+   │
+   ▼
+render HTML with fresh appearance settings
+(cols, rows, fontSize, fontFamily, cursorBlink, scrollback, theme)
 ```
 
 - **First run**: defaults are written to disk so the user has a file to edit.
 - **Subsequent runs**: file is read and merged with defaults — missing keys fall back to defaults, so adding new config keys in future versions is non-breaking.
+- **Write failure on first run**: warns to stderr, continues with in-memory defaults (no crash).
 - **Invalid JSON**: hard error with a clear message pointing to the file path. webtty does not attempt to repair or overwrite a corrupt file.
 - **Unknown keys**: silently ignored (forward-compatibility — a config written by a newer version works with an older binary).
 - **Env overrides**: applied after the file is loaded, never written back to the file.
+- **Hot config reload**: `port` and `host` are locked for the server lifetime (changing them requires a restart). All appearance settings (`cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, `scrollback`, `theme`) and `shell`/`term` for *new* sessions take effect on the next browser tab reload — no server restart needed.
 
 ## Schema
 
@@ -118,3 +129,4 @@ config ready
 | `scrollback` | PTY history buffer size in bytes | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
 | Terminal appearance | `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink` injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
 | `theme` | Terminal color palette injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
+| Hot config reload | Appearance settings re-read from disk on every tab reload; `port`/`host` locked for server lifetime | [ADR 009](../adrs/009.webtty.config-hot-reload.md) | ⬜ |
diff --git a/src/server/routes.ts b/src/server/routes.ts
index 08cbf1c..38a9060 100644
--- a/src/server/routes.ts
+++ b/src/server/routes.ts
@@ -1,6 +1,6 @@
 import type http from 'node:http';
 import path from 'node:path';
-import type { Config } from '../config';
+import { type Config, loadConfig } from '../config';
 import { render } from './client';
 import {
   createSession,
@@ -200,7 +200,7 @@ export async function handleRequest(
       return;
     }
     res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end(render(id, config));
+    res.end(render(id, loadConfig()));
     return;
   }
 

From ede68b54220517697eccd048b405390c26e727ed Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 18:12:09 -0400
Subject: [PATCH 11/29] refactor: remove config parameter from
 createWebSocketServer function

---
 src/server/index.ts     | 2 +-
 src/server/websocket.ts | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/server/index.ts b/src/server/index.ts
index c2efcb9..05cc85b 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -27,7 +27,7 @@ const httpServer = http.createServer((req, res) => {
   });
 });
 
-const wss = createWebSocketServer(httpServer, config);
+const wss = createWebSocketServer(httpServer);
 
 process.on('SIGINT', () => {
   console.log('\n\nShutting down...');
diff --git a/src/server/websocket.ts b/src/server/websocket.ts
index a89fb02..de6134a 100644
--- a/src/server/websocket.ts
+++ b/src/server/websocket.ts
@@ -1,11 +1,11 @@
 import type http from 'node:http';
 import type { WebSocket as WS } from 'ws';
 import { WebSocketServer } from 'ws';
-import type { Config } from '../config';
+import { loadConfig } from '../config';
 import { spawnForSession } from '../pty';
 import { sessionRegistry, setLastUsedId } from './session';
 
-export function createWebSocketServer(httpServer: http.Server, config: Config): WebSocketServer {
+export function createWebSocketServer(httpServer: http.Server): WebSocketServer {
   const wss = new WebSocketServer({ noServer: true });
 
   httpServer.on('upgrade', (req, socket, head) => {
@@ -55,6 +55,7 @@ export function createWebSocketServer(httpServer: http.Server, config: Config):
     setLastUsedId(id);
 
     if (!session.pty) {
+      const config = loadConfig();
       session.pty = spawnForSession(cols, rows, config.shell, config.term, config.colorTerm);
 
       session.pty.onData((data: string) => {

From 208e4e78608108038ed2b310547fee458384edc6 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 19:23:36 -0400
Subject: [PATCH 12/29] feat: enhance configuration handling with hot reload
 support and improved error handling

---
 docs/adrs/009.webtty.config-hot-reload.md |   7 +-
 docs/specs/config.md                      |  69 ++++++--
 src/config.test.ts                        | 190 ++++++++++++++++++++++
 src/config.ts                             |  18 +-
 src/server/client.test.ts                 |  43 +++++
 5 files changed, 298 insertions(+), 29 deletions(-)
 create mode 100644 src/config.test.ts

diff --git a/docs/adrs/009.webtty.config-hot-reload.md b/docs/adrs/009.webtty.config-hot-reload.md
index 0baf641..46cffcd 100644
--- a/docs/adrs/009.webtty.config-hot-reload.md
+++ b/docs/adrs/009.webtty.config-hot-reload.md
@@ -18,7 +18,7 @@ A full hot-reload (e.g. `fs.watch` triggering a live update mid-session) is impr
 
 - `loadConfig()` is called inside the `GET /s/:id` handler, not at module load time.
 - `port` and `host` remain read once at startup — they are bound to the OS socket and cannot change without a restart.
-- `shell` and `term` are re-read on tab reload; they apply to *new* PTY processes only. An already-running session is unaffected.
+- `shell` and `term` are re-read when a new PTY is spawned (first WebSocket connection to a session that has no running shell). An already-running session is unaffected.
 - All appearance settings (`cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, `scrollback`, `theme`) take effect immediately on the next tab reload.
 
 ## Considered Options
@@ -41,9 +41,10 @@ A full hot-reload (e.g. `fs.watch` triggering a live update mid-session) is impr
 ## Consequences
 
 - Editing `~/.config/webtty/config.jsonc` and reloading the browser tab picks up all appearance changes immediately — no server restart needed.
+- `shell`, `term`, `colorTerm`, and `scrollback` are re-read when a new PTY is spawned — no server restart needed for shell changes either.
 - `port` / `host` changes still require a server restart (expected; the socket is already bound).
-- `loadConfig()` adds one `fs.readFileSync` + JSON parse per tab load — negligible cost.
-- The startup-cached `config` in `index.ts` is retained only for `port`/`host` (server bind) and passed to the WebSocket handler for PTY defaults; the `GET /s/:id` route calls `loadConfig()` fresh.
+- `loadConfig()` adds one `fs.readFileSync` + JSON parse per tab load and per new PTY spawn — negligible cost.
+- `createWebSocketServer` no longer accepts a `config` parameter — it calls `loadConfig()` itself at PTY spawn time. `index.ts` retains a startup-cached config only for `port`/`host` (server bind).
 
 ## Related Decisions
 
diff --git a/docs/specs/config.md b/docs/specs/config.md
index b7ea167..a42be16 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -18,6 +18,8 @@ webtty reads configuration from `~/.config/webtty/config.jsonc`. The file suppor
 
 ## Lifecycle
 
+### Server startup
+
 ```
 webtty server starts
    │
@@ -27,11 +29,18 @@ config file exists? ────────────────────
   yes                                   no
    │                                    │
    ▼                                    ▼
-read + parse JSON ◄──────── write defaults to file
-   │                              │ write fails?
-   ▼                              ▼
-valid JSON? ──────── no ──► warn + use defaults in memory
+read + parse JSONC              write defaults to file
+   │                                    │
+   │                              write fails?
+   │                                    │
+   │                            warn to stderr +
+   │                            use defaults in memory ──► port/host locked
+   ▼
+valid JSON?
+   │
+  no ──► hard error: print path, exit
    │
+  yes
    ▼
 merge with defaults
 (unknown keys ignored)
@@ -41,27 +50,51 @@ apply env overrides
 (PORT > config.port, etc.)
    │
    ▼
-config ready (port/host locked for server lifetime)
+port/host locked for server lifetime
+```
+
+### Browser tab load / reload  (`GET /s/:id`)
+
+```
+browser requests /s/:id
+   │
+   ▼
+loadConfig() — re-read file from disk
+   │
+   ▼
+render HTML with fresh appearance settings injected:
+cols, rows, fontSize, fontFamily, cursorBlink, scrollback, theme
 ```
 
+### New PTY spawn  (first WebSocket connection to a session)
+
 ```
-browser tab reloads  (GET /s/:id)
+WebSocket connects to /ws/:id
+   │
+   ▼
+session has no running PTY?
    │
+  yes
    ▼
 loadConfig() — re-read file from disk
    │
    ▼
-render HTML with fresh appearance settings
-(cols, rows, fontSize, fontFamily, cursorBlink, scrollback, theme)
+spawn PTY with fresh: shell, term, colorTerm, scrollback
 ```
 
+### Rules
+
 - **First run**: defaults are written to disk so the user has a file to edit.
 - **Subsequent runs**: file is read and merged with defaults — missing keys fall back to defaults, so adding new config keys in future versions is non-breaking.
 - **Write failure on first run**: warns to stderr, continues with in-memory defaults (no crash).
 - **Invalid JSON**: hard error with a clear message pointing to the file path. webtty does not attempt to repair or overwrite a corrupt file.
 - **Unknown keys**: silently ignored (forward-compatibility — a config written by a newer version works with an older binary).
-- **Env overrides**: applied after the file is loaded, never written back to the file.
-- **Hot config reload**: `port` and `host` are locked for the server lifetime (changing them requires a restart). All appearance settings (`cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, `scrollback`, `theme`) and `shell`/`term` for *new* sessions take effect on the next browser tab reload — no server restart needed.
+- **Env overrides**: `PORT` overrides `config.port` at runtime. Applied after file load, never written back.
+- **Hot config reload**:
+  - `port` / `host` — locked at startup (server socket already bound; restart required).
+  - `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, `scrollback`, `theme` — re-read on every tab reload.
+  - `shell`, `term`, `colorTerm`, `scrollback` — re-read when a new PTY is spawned (i.e. first connection to a session that has no running shell).
+  - An already-running session is never affected mid-flight.
 
 ## Schema
 
@@ -74,9 +107,9 @@ render HTML with fresh appearance settings
   "host": "127.0.0.1",
 
   // Shell
-  // Shell for new sessions; defaults to $SHELL / %COMSPEC% if omitted
+  // Shell for new sessions; defaults to $COMSPEC / cmd.exe on Windows, $SHELL / /bin/bash on Unix
   // "shell": "/bin/zsh",
-  // $TERM env var passed to the shell
+  // $TERM env var passed to the shell; defaults to $TERM from environment
   // "term": "xterm-256color",
 
   // Terminal
@@ -124,9 +157,9 @@ render HTML with fresh appearance settings
 | Feature | Description | ADR | Done? |
 |---------|-------------|-----|-------|
 | Config lifecycle | First-run write + subsequent load, merge with defaults, env overrides | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
-| `port` / `host` | Override HTTP listen port and bind address | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
-| `shell` / `term` | Override shell and `$TERM` env var for new sessions | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
-| `scrollback` | PTY history buffer size in bytes | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
-| Terminal appearance | `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink` injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
-| `theme` | Terminal color palette injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ⬜ |
-| Hot config reload | Appearance settings re-read from disk on every tab reload; `port`/`host` locked for server lifetime | [ADR 009](../adrs/009.webtty.config-hot-reload.md) | ⬜ |
+| `port` / `host` | Override HTTP listen port and bind address | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `shell` / `term` / `colorTerm` | Override shell and `$TERM` / `$COLORTERM` env vars for new PTY sessions | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `scrollback` | PTY history buffer size in bytes; shared between server-side replay and client-side line buffer | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| Terminal appearance | `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink` injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `theme` | Terminal color palette injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| Hot config reload | Appearance re-read on tab reload; shell/PTY settings re-read on new PTY spawn; `port`/`host` locked for server lifetime | [ADR 009](../adrs/009.webtty.config-hot-reload.md) | ✅ |
diff --git a/src/config.test.ts b/src/config.test.ts
new file mode 100644
index 0000000..a281d6d
--- /dev/null
+++ b/src/config.test.ts
@@ -0,0 +1,190 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_CONFIG, DEFAULT_THEME, loadConfig, saveConfig } from './config';
+
+let tmpDir: string;
+let configPath: string;
+
+const origHome = os.homedir();
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webtty-config-test-'));
+  configPath = path.join(tmpDir, '.config', 'webtty', 'config.jsonc');
+  spyOn(os, 'homedir').mockReturnValue(tmpDir);
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+  spyOn(os, 'homedir').mockReturnValue(origHome);
+});
+
+describe('saveConfig', () => {
+  test('creates the config directory if it does not exist', () => {
+    saveConfig(DEFAULT_CONFIG);
+    expect(fs.existsSync(path.dirname(configPath))).toBe(true);
+  });
+
+  test('writes a file that is valid JSON after stripping comments', () => {
+    saveConfig(DEFAULT_CONFIG);
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const stripped = raw.replace(/\/\/[^\n]*/g, '');
+    expect(() => JSON.parse(stripped)).not.toThrow();
+  });
+
+  test('written file contains expected port and host values', () => {
+    saveConfig(DEFAULT_CONFIG);
+    const raw = fs.readFileSync(configPath, 'utf8');
+    expect(raw).toContain('"port": 2346');
+    expect(raw).toContain('"host": "127.0.0.1"');
+  });
+
+  test('written file contains Dracula theme colors as comments', () => {
+    saveConfig(DEFAULT_CONFIG);
+    const raw = fs.readFileSync(configPath, 'utf8');
+    expect(raw).toContain('#282A36');
+    expect(raw).toContain('#F8F8F2');
+  });
+});
+
+describe('loadConfig — first run', () => {
+  test('creates the config file when it does not exist', () => {
+    expect(fs.existsSync(configPath)).toBe(false);
+    loadConfig();
+    expect(fs.existsSync(configPath)).toBe(true);
+  });
+
+  test('returns config that equals DEFAULT_CONFIG after first run', () => {
+    const config = loadConfig();
+    expect(config.port).toBe(DEFAULT_CONFIG.port);
+    expect(config.host).toBe(DEFAULT_CONFIG.host);
+    expect(config.cols).toBe(DEFAULT_CONFIG.cols);
+    expect(config.rows).toBe(DEFAULT_CONFIG.rows);
+    expect(config.fontSize).toBe(DEFAULT_CONFIG.fontSize);
+    expect(config.cursorBlink).toBe(DEFAULT_CONFIG.cursorBlink);
+    expect(config.scrollback).toBe(DEFAULT_CONFIG.scrollback);
+    expect(config.theme).toEqual(DEFAULT_CONFIG.theme);
+  });
+
+  test('warns and returns defaults when write fails', () => {
+    const configDir = path.dirname(configPath);
+    fs.mkdirSync(path.dirname(configDir), { recursive: true });
+    fs.writeFileSync(configDir, 'not-a-dir');
+
+    const warned: string[] = [];
+    const origWarn = console.warn;
+    console.warn = (...args: unknown[]) => warned.push(args.join(' '));
+
+    let config: ReturnType<typeof loadConfig> | undefined;
+    expect(() => {
+      config = loadConfig();
+    }).not.toThrow();
+
+    console.warn = origWarn;
+
+    expect(warned.some((w) => w.includes('webtty:'))).toBe(true);
+    expect(config?.port).toBe(DEFAULT_CONFIG.port);
+  });
+});
+
+describe('loadConfig — reads and merges', () => {
+  function writeConfig(content: string) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, 'utf8');
+  }
+
+  test('returns full defaults when file has no overrides', () => {
+    writeConfig('{}');
+    const config = loadConfig();
+    expect(config.port).toBe(DEFAULT_CONFIG.port);
+    expect(config.cols).toBe(DEFAULT_CONFIG.cols);
+    expect(config.theme).toEqual(DEFAULT_THEME);
+  });
+
+  test('overrides port when set in file', () => {
+    writeConfig(JSON.stringify({ port: 9999 }));
+    const config = loadConfig();
+    expect(config.port).toBe(9999);
+  });
+
+  test('overrides host when set in file', () => {
+    writeConfig(JSON.stringify({ host: '0.0.0.0' }));
+    const config = loadConfig();
+    expect(config.host).toBe('0.0.0.0');
+  });
+
+  test('overrides shell when set in file', () => {
+    writeConfig(JSON.stringify({ shell: '/bin/zsh' }));
+    const config = loadConfig();
+    expect(config.shell).toBe('/bin/zsh');
+  });
+
+  test('overrides fontSize and fontFamily when set in file', () => {
+    writeConfig(JSON.stringify({ fontSize: 18, fontFamily: 'Menlo' }));
+    const config = loadConfig();
+    expect(config.fontSize).toBe(18);
+    expect(config.fontFamily).toBe('Menlo');
+  });
+
+  test('overrides cursorBlink when set to false', () => {
+    writeConfig(JSON.stringify({ cursorBlink: false }));
+    const config = loadConfig();
+    expect(config.cursorBlink).toBe(false);
+  });
+
+  test('overrides cols and rows when set in file', () => {
+    writeConfig(JSON.stringify({ cols: 120, rows: 40 }));
+    const config = loadConfig();
+    expect(config.cols).toBe(120);
+    expect(config.rows).toBe(40);
+  });
+
+  test('overrides scrollback when set in file', () => {
+    writeConfig(JSON.stringify({ scrollback: 1024 }));
+    const config = loadConfig();
+    expect(config.scrollback).toBe(1024);
+  });
+
+  test('merges partial theme over DEFAULT_THEME', () => {
+    writeConfig(JSON.stringify({ theme: { background: '#000000' } }));
+    const config = loadConfig();
+    expect(config.theme.background).toBe('#000000');
+    expect(config.theme.foreground).toBe(DEFAULT_THEME.foreground);
+    expect(config.theme.red).toBe(DEFAULT_THEME.red);
+  });
+
+  test('ignores unknown keys', () => {
+    writeConfig(JSON.stringify({ unknownKey: 'value', port: 1234 }));
+    const config = loadConfig();
+    expect(config.port).toBe(1234);
+    expect((config as unknown as Record<string, unknown>).unknownKey).toBeUndefined();
+  });
+
+  test('ignores keys with wrong types (falls back to default)', () => {
+    writeConfig(JSON.stringify({ port: 'not-a-number', cols: true, host: 42 }));
+    const config = loadConfig();
+    expect(config.port).toBe(DEFAULT_CONFIG.port);
+    expect(config.cols).toBe(DEFAULT_CONFIG.cols);
+    expect(config.host).toBe(DEFAULT_CONFIG.host);
+  });
+
+  test('strips JSONC comments before parsing', () => {
+    writeConfig(`{
+      // This is a comment
+      "port": 5000 // inline comment
+    }`);
+    const config = loadConfig();
+    expect(config.port).toBe(5000);
+  });
+
+  test('throws on invalid JSON', () => {
+    writeConfig('{ not valid json }');
+    expect(() => loadConfig()).toThrow(/invalid JSON/);
+  });
+
+  test('throws with file path in message on read error', () => {
+    fs.mkdirSync(configPath, { recursive: true });
+    expect(() => loadConfig()).toThrow(/webtty:/);
+  });
+});
diff --git a/src/config.ts b/src/config.ts
index fec287e..332e078 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -41,7 +41,9 @@ export interface Config {
   theme: Theme;
 }
 
-const CONFIG_PATH = path.join(os.homedir(), '.config', 'webtty', 'config.jsonc');
+function getConfigPath(): string {
+  return path.join(os.homedir(), '.config', 'webtty', 'config.jsonc');
+}
 
 export const DEFAULT_THEME: Theme = {
   background: '#282A36',
@@ -85,12 +87,12 @@ export const DEFAULT_CONFIG: Config = {
 };
 
 export function loadConfig(): Config {
-  if (!fs.existsSync(CONFIG_PATH)) {
+  if (!fs.existsSync(getConfigPath())) {
     try {
       saveConfig(DEFAULT_CONFIG);
     } catch (err) {
       console.warn(
-        `webtty: failed to write default config to ${CONFIG_PATH}: ${(err as Error).message}`,
+        `webtty: failed to write default config to ${getConfigPath()}: ${(err as Error).message}`,
       );
       return { ...DEFAULT_CONFIG };
     }
@@ -98,16 +100,16 @@ export function loadConfig(): Config {
 
   let raw: string;
   try {
-    raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    raw = fs.readFileSync(getConfigPath(), 'utf8');
   } catch (err) {
-    throw new Error(`webtty: failed to read config at ${CONFIG_PATH}: ${(err as Error).message}`);
+    throw new Error(`webtty: failed to read config at ${getConfigPath()}: ${(err as Error).message}`);
   }
 
   let parsed: unknown;
   try {
     parsed = JSON.parse(stripJsonComments(raw));
   } catch {
-    throw new Error(`webtty: invalid JSON in config file ${CONFIG_PATH}`);
+    throw new Error(`webtty: invalid JSON in config file ${getConfigPath()}`);
   }
 
   const p = parsed as Partial<Config>;
@@ -129,7 +131,7 @@ export function loadConfig(): Config {
 
 export function saveConfig(_config: Config): void {
   const th = DEFAULT_THEME;
-  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  fs.mkdirSync(path.dirname(getConfigPath()), { recursive: true });
   const content = [
     '{',
     '  // Server',
@@ -184,5 +186,5 @@ export function saveConfig(_config: Config): void {
     '}',
     '',
   ].join('\n');
-  fs.writeFileSync(CONFIG_PATH, content, 'utf8');
+  fs.writeFileSync(getConfigPath(), content, 'utf8');
 }
diff --git a/src/server/client.test.ts b/src/server/client.test.ts
index db341db..6a5c2e5 100644
--- a/src/server/client.test.ts
+++ b/src/server/client.test.ts
@@ -29,4 +29,47 @@ describe('clientShell', () => {
     const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('/ws/');
   });
+
+  test('injects fontSize into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, fontSize: 20 });
+    expect(html).toContain('fontSize: 20');
+  });
+
+  test('injects fontFamily into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, fontFamily: 'Menlo' });
+    expect(html).toContain('fontFamily: "Menlo"');
+  });
+
+  test('injects cols and rows into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, cols: 120, rows: 40 });
+    expect(html).toContain('cols: 120');
+    expect(html).toContain('rows: 40');
+  });
+
+  test('injects cursorBlink into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, cursorBlink: false });
+    expect(html).toContain('cursorBlink: false');
+  });
+
+  test('injects scrollback as line count derived from bytes', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, scrollback: 8000 });
+    expect(html).toContain(`scrollback: ${Math.ceil(8000 / 80)}`);
+  });
+
+  test('injects theme background color into CSS', () => {
+    const html = render('s', {
+      ...DEFAULT_CONFIG,
+      theme: { ...DEFAULT_CONFIG.theme, background: '#FF0000' },
+    });
+    expect(html).toContain('#FF0000');
+  });
+
+  test('injects full theme object into terminal options', () => {
+    const html = render('s', {
+      ...DEFAULT_CONFIG,
+      theme: { ...DEFAULT_CONFIG.theme, foreground: '#AABBCC' },
+    });
+    expect(html).toContain('"foreground"');
+    expect(html).toContain('#AABBCC');
+  });
 });

From a106666d58f9dfb308298863662848b886e86828 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 19:29:07 -0400
Subject: [PATCH 13/29] feat: add coverage testing script to package.json and
 ignore lcov.info in .gitignore

---
 .gitignore   | 1 +
 package.json | 1 +
 2 files changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 0c05a21..83fb59d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ package.json.bak
 
 # Logs
 *.log
+lcov.info
 
 # AI tooling (local-only agent state)
 .agents/
diff --git a/package.json b/package.json
index 6ea5dd3..1b48ddd 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
     "lint": "tsc --noEmit -p tsconfig.lint.json && biome check .",
     "lint:fix": "tsc --noEmit -p tsconfig.lint.json && bunx biome check --write .",
     "test": "bun test",
+    "test:coverage": "bun test --coverage",
     "build": "bun run scripts/build.ts",
     "server": "bun run dist/server/index.js",
     "server:node": "node dist/server/index.js",

From 114be36c3d114030ca0a5496fd108c74ddd0d921 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 19:36:13 -0400
Subject: [PATCH 14/29] feat: add tests for setLastUsedId function and coverage
 report

---
 src/server/session.test.ts | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/src/server/session.test.ts b/src/server/session.test.ts
index a4c920e..4405594 100644
--- a/src/server/session.test.ts
+++ b/src/server/session.test.ts
@@ -1,5 +1,13 @@
 import { beforeEach, describe, expect, test } from 'bun:test';
-import { createSession, generateId, isValidId, sessionRegistry, sessionToJson } from './session';
+import {
+  createSession,
+  generateId,
+  isValidId,
+  lastUsedId,
+  sessionRegistry,
+  sessionToJson,
+  setLastUsedId,
+} from './session';
 
 beforeEach(() => {
   sessionRegistry.clear();
@@ -83,3 +91,16 @@ describe('sessionToJson', () => {
     expect(typeof json.createdAt).toBe('number');
   });
 });
+
+describe('setLastUsedId', () => {
+  test('updates lastUsedId to the given value', () => {
+    setLastUsedId('my-session');
+    expect(lastUsedId).toBe('my-session');
+  });
+
+  test('accepts null to clear lastUsedId', () => {
+    setLastUsedId('my-session');
+    setLastUsedId(null);
+    expect(lastUsedId).toBeNull();
+  });
+});

From 2f7ab153e15e159e1d4f36eb0d8d22f0b35878b7 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 19:53:20 -0400
Subject: [PATCH 15/29] feat: update configuration format to plain JSON and
 remove strip-json-comments dependency

---
 bun.lock                                  |   8 +-
 docs/adrs/008.webtty.config.md            |  15 ++-
 docs/adrs/009.webtty.config-hot-reload.md |   4 +-
 docs/specs/config.md                      | 133 +++++++++++++---------
 docs/specs/webtty.md                      |   2 +-
 package.json                              |   2 -
 src/config.test.ts                        |  48 +++-----
 src/config.ts                             |  72 +++---------
 8 files changed, 122 insertions(+), 162 deletions(-)

diff --git a/bun.lock b/bun.lock
index 413e998..80b7d72 100644
--- a/bun.lock
+++ b/bun.lock
@@ -8,13 +8,11 @@
         "@lydell/node-pty": "1.2.0-beta.3",
         "commander": "14.0.0",
         "ghostty-web": "0.4.0-next.14.g6a1a50d",
-        "strip-json-comments": "3.1.1",
         "ws": "8.20.0",
       },
       "devDependencies": {
         "@biomejs/biome": "2.4.8",
         "@types/bun": "1.3.11",
-        "@types/strip-json-comments": "^3.0.0",
         "@types/ws": "8.18.1",
         "rimraf": "6.1.3",
         "semantic-release": "24.2.9",
@@ -166,8 +164,6 @@
 
     "@types/normalize-package-data": ["@types/normalize-package-data@2.4.4", "", {}, "sha512-37i+OaWTh9qeK4LSHPsyRC7NahnGotNuZvjLSgcPzblpHB3rrCJxAOgI5gCdKm7coonsaX1Of0ILiTcnZjbfxA=="],
 
-    "@types/strip-json-comments": ["@types/strip-json-comments@3.0.0", "", { "dependencies": { "strip-json-comments": "*" } }, "sha512-+vSlZeCCGm/1Q3WwBJDUSGHvADTQjRl4Fve0AG9H+A4+xgJ7yAkWKoc4g7I9UoVqtwCzjv2g/GZn4xipokMYyQ=="],
-
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
     "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
@@ -556,7 +552,7 @@
 
     "strip-final-newline": ["strip-final-newline@4.0.0", "", {}, "sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw=="],
 
-    "strip-json-comments": ["strip-json-comments@3.1.1", "", {}, "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig=="],
+    "strip-json-comments": ["strip-json-comments@2.0.1", "", {}, "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ=="],
 
     "super-regex": ["super-regex@1.1.0", "", { "dependencies": { "function-timeout": "^1.0.1", "make-asynchronous": "^1.0.1", "time-span": "^5.1.0" } }, "sha512-WHkws2ZflZe41zj6AolvvmaTrWds/VuyeYr9iPVv/oQeaIoVxMKaushfFWpOGDT+GuBrM/sVqF8KUCYQlSSTdQ=="],
 
@@ -1010,8 +1006,6 @@
 
     "path-scurry/lru-cache": ["lru-cache@11.2.7", "", {}, "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA=="],
 
-    "rc/strip-json-comments": ["strip-json-comments@2.0.1", "", {}, "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ=="],
-
     "read-pkg/parse-json": ["parse-json@8.3.0", "", { "dependencies": { "@babel/code-frame": "^7.26.2", "index-to-position": "^1.1.0", "type-fest": "^4.39.1" } }, "sha512-ybiGyvspI+fAoRQbIPRddCcSTV9/LsJbf0e/S85VLowVGzRmokfneg2kwVW/KU5rOXrPSbF1qAKPMgNTqqROQQ=="],
 
     "signale/chalk": ["chalk@2.4.2", "", { "dependencies": { "ansi-styles": "^3.2.1", "escape-string-regexp": "^1.0.5", "supports-color": "^5.3.0" } }, "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ=="],
diff --git a/docs/adrs/008.webtty.config.md b/docs/adrs/008.webtty.config.md
index e206921..da87b7d 100644
--- a/docs/adrs/008.webtty.config.md
+++ b/docs/adrs/008.webtty.config.md
@@ -18,9 +18,9 @@ Three concerns drive the design:
 
 ## Decision
 
-**File location**: `~/.config/webtty/config.jsonc` — follows the XDG Base Directory convention used by most modern CLI tools (opencode, lazygit, starship, etc.). Created automatically on first run with commented-out defaults.
+**File location**: `~/.config/webtty/config.json` — follows the XDG Base Directory convention used by most modern CLI tools (opencode, lazygit, starship, etc.). Created automatically on first run with only `port` and `host` set.
 
-**Format**: JSONC (JSON with comments) via `strip-json-comments`. Native JSON is hostile to config files — users cannot annotate their choices. `strip-json-comments` is 8.2 KB, 128M weekly downloads, zero dependencies. Bun has native `Bun.JSONC` since v1.3.6 but using the npm package keeps the code path identical on Node and Bun.
+**Format**: Plain JSON. The file is written by `saveConfig` using `JSON.stringify` and read with `JSON.parse`. Comments are not supported — the schema table in the [config spec](../specs/config.md) serves as documentation. This removes the `strip-json-comments` dependency and keeps the parser a zero-config standard library call.
 
 **Load strategy**: Merge partial config over defaults — unknown keys are ignored, missing keys fall back to built-in defaults. This means adding new config keys in future versions is non-breaking: an old `config.jsonc` with only `port` still works correctly with a binary that added `theme`.
 
@@ -40,7 +40,7 @@ Three concerns drive the design:
 **Option B: TOML format**
 
 - **Pros**: More readable for nested structures (theme colors).
-- **Cons**: Requires a TOML parser dependency (~50 KB). JSONC is sufficient and consistent with the existing JSON surface (REST API, `package.json`).
+- **Cons**: Requires a TOML parser dependency (~50 KB). JSON is sufficient and consistent with the existing JSON surface (REST API, `package.json`).
 
 **Option C: Separate env var for every setting**
 
@@ -52,12 +52,17 @@ Three concerns drive the design:
 - **Pros**: Zero bytes added to bundle.
 - **Cons**: Breaks Node.js compatibility. webtty explicitly supports both runtimes.
 
+**Option E: JSONC via `strip-json-comments`**
+
+- **Pros**: Users can annotate their config with comments.
+- **Cons**: Adds a dependency for a cosmetic feature. The schema table in the spec is a better reference than inline comments in a generated file. Dropped in favour of plain JSON.
+
 ## Consequences
 
-- First run creates `~/.config/webtty/config.jsonc` with commented defaults — users have a ready-to-edit file immediately
+- First run creates `~/.config/webtty/config.json` with `port` and `host` set — users have a ready-to-edit file immediately
 - `port`, `host`, `shell`, `term`, `scrollback`, `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, and `theme` are all user-configurable
 - Adding new config keys in future versions is non-breaking
-- `strip-json-comments` added as a production dependency (8.2 KB unpacked)
+- No additional production dependencies — `JSON.parse` is sufficient
 - Terminal appearance config is injected server-side into the HTML — no client-side config fetch needed
 
 ## Related Decisions
diff --git a/docs/adrs/009.webtty.config-hot-reload.md b/docs/adrs/009.webtty.config-hot-reload.md
index 46cffcd..314fa07 100644
--- a/docs/adrs/009.webtty.config-hot-reload.md
+++ b/docs/adrs/009.webtty.config-hot-reload.md
@@ -8,13 +8,13 @@
 
 ## Context
 
-Config is currently loaded once at server startup and held in memory for the lifetime of the process. Users who edit `~/.config/webtty/config.jsonc` must restart the server to see their changes — even for purely cosmetic settings like font size or theme colors.
+Config is currently loaded once at server startup and held in memory for the lifetime of the process. Users who edit `~/.config/webtty/config.json` must restart the server to see their changes — even for purely cosmetic settings like font size or theme colors.
 
 A full hot-reload (e.g. `fs.watch` triggering a live update mid-session) is impractical: the terminal is already initialized in the browser with the old values, and pushing new font/theme settings to a live xterm instance requires non-trivial client-side logic. However, a tab reload already reconstructs the terminal from scratch — the browser fetches `GET /s/:id`, the server renders fresh HTML with config injected, and the client re-initializes xterm. This is a natural reload boundary.
 
 ## Decision
 
-**Re-read `config.jsonc` on every `GET /s/:id` request** instead of using the startup-cached value. No file watcher, no WebSocket push, no client changes.
+**Re-read `config.json` on every `GET /s/:id` request** instead of using the startup-cached value. No file watcher, no WebSocket push, no client changes.
 
 - `loadConfig()` is called inside the `GET /s/:id` handler, not at module load time.
 - `port` and `host` remain read once at startup — they are bound to the OS socket and cannot change without a restart.
diff --git a/docs/specs/config.md b/docs/specs/config.md
index a42be16..b6185a8 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -7,14 +7,14 @@
 
 ## Description
 
-webtty reads configuration from `~/.config/webtty/config.jsonc`. The file supports comments (JSONC format via `strip-json-comments`). It is the single source of truth for persistent user preferences. Environment variables override config file values at runtime but never modify the file.
+webtty reads configuration from `~/.config/webtty/config.json`. It is the single source of truth for persistent user preferences. Environment variables override config file values at runtime but never modify the file.
 
 ## File location
 
 | Platform | Path |
 |----------|------|
-| macOS / Linux | `~/.config/webtty/config.jsonc` |
-| Windows | `%USERPROFILE%\.config\webtty\config.jsonc` |
+| macOS / Linux | `~/.config/webtty/config.json` |
+| Windows | `%USERPROFILE%\.config\webtty\config.json` |
 
 ## Lifecycle
 
@@ -29,7 +29,7 @@ config file exists? ────────────────────
   yes                                   no
    │                                    │
    ▼                                    ▼
-read + parse JSONC              write defaults to file
+read + parse JSON               write defaults to file
    │                                    │
    │                              write fails?
    │                                    │
@@ -98,57 +98,88 @@ spawn PTY with fresh: shell, term, colorTerm, scrollback
 
 ## Schema
 
-```jsonc
+All keys are optional — omit any key to use the default value.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `port` | number | `2346` | HTTP listen port; env `PORT` takes precedence |
+| `host` | string | `"127.0.0.1"` | Bind address; use `"0.0.0.0"` for remote access |
+| `shell` | string | `$SHELL` / `%COMSPEC%` | Shell for new sessions |
+| `term` | string | `$TERM` | `$TERM` env var passed to the shell |
+| `scrollback` | number | `262144` | PTY history buffer in bytes; used for server-side replay on reload/reconnect |
+| `cols` | number | `80` | Initial terminal width in columns |
+| `rows` | number | `24` | Initial terminal height in rows |
+| `cursorBlink` | boolean | `true` | Whether the cursor blinks |
+| `fontSize` | number | `14` | Font size in px |
+| `fontFamily` | string | `"'FiraMono Nerd Font', Menlo, ..."` | CSS font-family stack |
+| `theme` | object | Dracula | Terminal color palette — see theme keys below |
+
+### Theme keys
+
+All theme keys are optional; omitted keys fall back to the Dracula defaults.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `background` | `#282A36` | Terminal background |
+| `foreground` | `#F8F8F2` | Default text color |
+| `cursor` | `#F8F8F2` | Cursor color |
+| `selection` | `#44475A` | Selection highlight |
+| `black` | `#21222C` | ANSI 0 |
+| `red` | `#FF5555` | ANSI 1 |
+| `green` | `#50FA7B` | ANSI 2 |
+| `yellow` | `#F1FA8C` | ANSI 3 |
+| `blue` | `#BD93F9` | ANSI 4 |
+| `purple` | `#FF79C6` | ANSI 5 |
+| `cyan` | `#8BE9FD` | ANSI 6 |
+| `white` | `#F8F8F2` | ANSI 7 |
+| `brightBlack` | `#6272A4` | ANSI 8 |
+| `brightRed` | `#FF6E6E` | ANSI 9 |
+| `brightGreen` | `#69FF94` | ANSI 10 |
+| `brightYellow` | `#FFFFA5` | ANSI 11 |
+| `brightBlue` | `#D6ACFF` | ANSI 12 |
+| `brightPurple` | `#FF92DF` | ANSI 13 |
+| `brightCyan` | `#A4FFFF` | ANSI 14 |
+| `brightWhite` | `#FFFFFF` | ANSI 15 |
+
+### Example
+
+```json
 {
-  // Server
-  // HTTP listen port; env PORT takes precedence
   "port": 2346,
-  // Bind address; use "0.0.0.0" for remote access
   "host": "127.0.0.1",
 
-  // Shell
-  // Shell for new sessions; defaults to $COMSPEC / cmd.exe on Windows, $SHELL / /bin/bash on Unix
-  // "shell": "/bin/zsh",
-  // $TERM env var passed to the shell; defaults to $TERM from environment
-  // "term": "xterm-256color",
-
-  // Terminal
-  // PTY history buffer in bytes (256 KB); used for server-side replay on reload/reconnect
-  // "scrollback": 262144,
-  // Initial terminal width in columns
-  // "cols": 80,
-  // Initial terminal height in rows
-  // "rows": 24,
-  // Whether the cursor blinks
-  // "cursorBlink": true,
-  // Font size in px
-  // "fontSize": 14,
-  // CSS font-family stack
-  // "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
-
-  // Theme — terminal color palette, Dracula by default
-  // "theme": {
-  //   "background":   "#282A36",  // terminal background
-  //   "foreground":   "#F8F8F2",  // default text color
-  //   "cursor":       "#F8F8F2",  // cursor color
-  //   "selection":    "#44475A",  // selection highlight
-  //   "black":        "#21222C",  // ANSI 0
-  //   "red":          "#FF5555",  // ANSI 1
-  //   "green":        "#50FA7B",  // ANSI 2
-  //   "yellow":       "#F1FA8C",  // ANSI 3
-  //   "blue":         "#BD93F9",  // ANSI 4
-  //   "purple":       "#FF79C6",  // ANSI 5
-  //   "cyan":         "#8BE9FD",  // ANSI 6
-  //   "white":        "#F8F8F2",  // ANSI 7
-  //   "brightBlack":  "#6272A4",  // ANSI 8
-  //   "brightRed":    "#FF6E6E",  // ANSI 9
-  //   "brightGreen":  "#69FF94",  // ANSI 10
-  //   "brightYellow": "#FFFFA5",  // ANSI 11
-  //   "brightBlue":   "#D6ACFF",  // ANSI 12
-  //   "brightPurple": "#FF92DF",  // ANSI 13
-  //   "brightCyan":   "#A4FFFF",  // ANSI 14
-  //   "brightWhite":  "#FFFFFF"   // ANSI 15
-  // }
+  "shell": "/bin/zsh",
+  "term": "xterm-256color",
+
+  "scrollback": 262144,
+  "cols": 80,
+  "rows": 24,
+  "cursorBlink": true,
+  "fontSize": 14,
+  "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
+
+  "theme": {
+    "background":   "#282A36",
+    "foreground":   "#F8F8F2",
+    "cursor":       "#F8F8F2",
+    "selection":    "#44475A",
+    "black":        "#21222C",
+    "red":          "#FF5555",
+    "green":        "#50FA7B",
+    "yellow":       "#F1FA8C",
+    "blue":         "#BD93F9",
+    "purple":       "#FF79C6",
+    "cyan":         "#8BE9FD",
+    "white":        "#F8F8F2",
+    "brightBlack":  "#6272A4",
+    "brightRed":    "#FF6E6E",
+    "brightGreen":  "#69FF94",
+    "brightYellow": "#FFFFA5",
+    "brightBlue":   "#D6ACFF",
+    "brightPurple": "#FF92DF",
+    "brightCyan":   "#A4FFFF",
+    "brightWhite":  "#FFFFFF"
+  }
 }
 ```
 
diff --git a/docs/specs/webtty.md b/docs/specs/webtty.md
index bf6ee14..d34697d 100644
--- a/docs/specs/webtty.md
+++ b/docs/specs/webtty.md
@@ -87,5 +87,5 @@ Session IDs appear directly in the URL path (`/s/:id`), so they must be valid UR
 | Default session | `GET /` redirects to last-used session, or creates `main` and redirects if none exists | — | ✅ |
 | Session URL | `GET /s/:id` — serves browser client for the named session; reconnects if session already has a PTY | — | ✅ |
 | Session management | CRUD + rename over HTTP — see REST API above | [ADR 004](../adrs/004.webtty.session-api.md) | ✅ |
-| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.jsonc`) | [ADR 008](../adrs/008.webtty.config.md) | ⬜ | → [config spec](config.md) |
+| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.json`) | [ADR 008](../adrs/008.webtty.config.md) | ⬜ | → [config spec](config.md) |
 | Session client | Multiple browser tabs can attach to the same session simultaneously; reload replays scrollback; typing `exit` closes all tabs | [ADR 007](../adrs/007.webtty.session-client.md) | ✅ |
diff --git a/package.json b/package.json
index 1b48ddd..166859f 100644
--- a/package.json
+++ b/package.json
@@ -31,13 +31,11 @@
     "@lydell/node-pty": "1.2.0-beta.3",
     "commander": "14.0.0",
     "ghostty-web": "0.4.0-next.14.g6a1a50d",
-    "strip-json-comments": "3.1.1",
     "ws": "8.20.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.8",
     "@types/bun": "1.3.11",
-    "@types/strip-json-comments": "^3.0.0",
     "@types/ws": "8.18.1",
     "rimraf": "6.1.3",
     "semantic-release": "24.2.9",
diff --git a/src/config.test.ts b/src/config.test.ts
index a281d6d..9df5bd0 100644
--- a/src/config.test.ts
+++ b/src/config.test.ts
@@ -11,7 +11,7 @@ const origHome = os.homedir();
 
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webtty-config-test-'));
-  configPath = path.join(tmpDir, '.config', 'webtty', 'config.jsonc');
+  configPath = path.join(tmpDir, '.config', 'webtty', 'config.json');
   spyOn(os, 'homedir').mockReturnValue(tmpDir);
 });
 
@@ -26,25 +26,17 @@ describe('saveConfig', () => {
     expect(fs.existsSync(path.dirname(configPath))).toBe(true);
   });
 
-  test('writes a file that is valid JSON after stripping comments', () => {
+  test('writes valid JSON', () => {
     saveConfig(DEFAULT_CONFIG);
     const raw = fs.readFileSync(configPath, 'utf8');
-    const stripped = raw.replace(/\/\/[^\n]*/g, '');
-    expect(() => JSON.parse(stripped)).not.toThrow();
+    expect(() => JSON.parse(raw)).not.toThrow();
   });
 
-  test('written file contains expected port and host values', () => {
+  test('written file contains port and host', () => {
     saveConfig(DEFAULT_CONFIG);
     const raw = fs.readFileSync(configPath, 'utf8');
-    expect(raw).toContain('"port": 2346');
-    expect(raw).toContain('"host": "127.0.0.1"');
-  });
-
-  test('written file contains Dracula theme colors as comments', () => {
-    saveConfig(DEFAULT_CONFIG);
-    const raw = fs.readFileSync(configPath, 'utf8');
-    expect(raw).toContain('#282A36');
-    expect(raw).toContain('#F8F8F2');
+    expect(raw).toContain('"port"');
+    expect(raw).toContain('"host"');
   });
 });
 
@@ -104,20 +96,17 @@ describe('loadConfig — reads and merges', () => {
 
   test('overrides port when set in file', () => {
     writeConfig(JSON.stringify({ port: 9999 }));
-    const config = loadConfig();
-    expect(config.port).toBe(9999);
+    expect(loadConfig().port).toBe(9999);
   });
 
   test('overrides host when set in file', () => {
     writeConfig(JSON.stringify({ host: '0.0.0.0' }));
-    const config = loadConfig();
-    expect(config.host).toBe('0.0.0.0');
+    expect(loadConfig().host).toBe('0.0.0.0');
   });
 
   test('overrides shell when set in file', () => {
     writeConfig(JSON.stringify({ shell: '/bin/zsh' }));
-    const config = loadConfig();
-    expect(config.shell).toBe('/bin/zsh');
+    expect(loadConfig().shell).toBe('/bin/zsh');
   });
 
   test('overrides fontSize and fontFamily when set in file', () => {
@@ -129,8 +118,7 @@ describe('loadConfig — reads and merges', () => {
 
   test('overrides cursorBlink when set to false', () => {
     writeConfig(JSON.stringify({ cursorBlink: false }));
-    const config = loadConfig();
-    expect(config.cursorBlink).toBe(false);
+    expect(loadConfig().cursorBlink).toBe(false);
   });
 
   test('overrides cols and rows when set in file', () => {
@@ -142,8 +130,7 @@ describe('loadConfig — reads and merges', () => {
 
   test('overrides scrollback when set in file', () => {
     writeConfig(JSON.stringify({ scrollback: 1024 }));
-    const config = loadConfig();
-    expect(config.scrollback).toBe(1024);
+    expect(loadConfig().scrollback).toBe(1024);
   });
 
   test('merges partial theme over DEFAULT_THEME', () => {
@@ -161,7 +148,7 @@ describe('loadConfig — reads and merges', () => {
     expect((config as unknown as Record<string, unknown>).unknownKey).toBeUndefined();
   });
 
-  test('ignores keys with wrong types (falls back to default)', () => {
+  test('ignores keys with wrong types and falls back to defaults', () => {
     writeConfig(JSON.stringify({ port: 'not-a-number', cols: true, host: 42 }));
     const config = loadConfig();
     expect(config.port).toBe(DEFAULT_CONFIG.port);
@@ -169,21 +156,12 @@ describe('loadConfig — reads and merges', () => {
     expect(config.host).toBe(DEFAULT_CONFIG.host);
   });
 
-  test('strips JSONC comments before parsing', () => {
-    writeConfig(`{
-      // This is a comment
-      "port": 5000 // inline comment
-    }`);
-    const config = loadConfig();
-    expect(config.port).toBe(5000);
-  });
-
   test('throws on invalid JSON', () => {
     writeConfig('{ not valid json }');
     expect(() => loadConfig()).toThrow(/invalid JSON/);
   });
 
-  test('throws with file path in message on read error', () => {
+  test('throws with webtty: prefix in message on read error', () => {
     fs.mkdirSync(configPath, { recursive: true });
     expect(() => loadConfig()).toThrow(/webtty:/);
   });
diff --git a/src/config.ts b/src/config.ts
index 332e078..b491482 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,7 +1,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import stripJsonComments from 'strip-json-comments';
 
 export interface Theme {
   background?: string;
@@ -42,7 +41,7 @@ export interface Config {
 }
 
 function getConfigPath(): string {
-  return path.join(os.homedir(), '.config', 'webtty', 'config.jsonc');
+  return path.join(os.homedir(), '.config', 'webtty', 'config.json');
 }
 
 export const DEFAULT_THEME: Theme = {
@@ -102,12 +101,14 @@ export function loadConfig(): Config {
   try {
     raw = fs.readFileSync(getConfigPath(), 'utf8');
   } catch (err) {
-    throw new Error(`webtty: failed to read config at ${getConfigPath()}: ${(err as Error).message}`);
+    throw new Error(
+      `webtty: failed to read config at ${getConfigPath()}: ${(err as Error).message}`,
+    );
   }
 
   let parsed: unknown;
   try {
-    parsed = JSON.parse(stripJsonComments(raw));
+    parsed = JSON.parse(raw);
   } catch {
     throw new Error(`webtty: invalid JSON in config file ${getConfigPath()}`);
   }
@@ -130,61 +131,14 @@ export function loadConfig(): Config {
 }
 
 export function saveConfig(_config: Config): void {
-  const th = DEFAULT_THEME;
   fs.mkdirSync(path.dirname(getConfigPath()), { recursive: true });
-  const content = [
-    '{',
-    '  // Server',
-    '  // HTTP listen port; env PORT takes precedence',
-    '  "port": 2346,',
-    '  // Bind address; use "0.0.0.0" for remote access',
-    '  "host": "127.0.0.1"',
-    '',
-    '  // Shell',
-    '  // Shell for new sessions; defaults to $COMSPEC / cmd.exe on Windows, $SHELL / /bin/bash on Unix',
-    '  // "shell": "/bin/zsh",',
-    '  // $TERM env var passed to the shell; defaults to $TERM from environment',
-    '  // "term": "xterm-256color",',
-    '',
-    '  // Terminal',
-    '  // PTY history buffer in bytes; used for server-side replay on reload/reconnect',
-    '  // "scrollback": 262144,',
-    '  // Initial terminal width in columns',
-    '  // "cols": 80,',
-    '  // Initial terminal height in rows',
-    '  // "rows": 24,',
-    '  // Whether the cursor blinks',
-    '  // "cursorBlink": true,',
-    '  // Font size in px',
-    '  // "fontSize": 14,',
-    '  // CSS font-family stack',
-    '  // "fontFamily": "\'FiraMono Nerd Font\', Menlo, Monaco, \'Courier New\', monospace",',
-    '',
-    '  // Theme — terminal color palette, Dracula by default',
-    '  // "theme": {',
-    `  //   "background":   "${th.background}",  // terminal background`,
-    `  //   "foreground":   "${th.foreground}",  // default text color`,
-    `  //   "cursor":       "${th.cursor}",  // cursor color`,
-    `  //   "selection":    "${th.selection}",  // selection highlight`,
-    `  //   "black":        "${th.black}",  // ANSI 0`,
-    `  //   "red":          "${th.red}",  // ANSI 1`,
-    `  //   "green":        "${th.green}",  // ANSI 2`,
-    `  //   "yellow":       "${th.yellow}",  // ANSI 3`,
-    `  //   "blue":         "${th.blue}",  // ANSI 4`,
-    `  //   "purple":       "${th.purple}",  // ANSI 5`,
-    `  //   "cyan":         "${th.cyan}",  // ANSI 6`,
-    `  //   "white":        "${th.white}",  // ANSI 7`,
-    `  //   "brightBlack":  "${th.brightBlack}",  // ANSI 8`,
-    `  //   "brightRed":    "${th.brightRed}",  // ANSI 9`,
-    `  //   "brightGreen":  "${th.brightGreen}",  // ANSI 10`,
-    `  //   "brightYellow": "${th.brightYellow}",  // ANSI 11`,
-    `  //   "brightBlue":   "${th.brightBlue}",  // ANSI 12`,
-    `  //   "brightPurple": "${th.brightPurple}",  // ANSI 13`,
-    `  //   "brightCyan":   "${th.brightCyan}",  // ANSI 14`,
-    `  //   "brightWhite":  "${th.brightWhite}"   // ANSI 15`,
-    '  // }',
-    '}',
-    '',
-  ].join('\n');
+  const content = JSON.stringify(
+    {
+      port: DEFAULT_CONFIG.port,
+      host: DEFAULT_CONFIG.host,
+    },
+    null,
+    2,
+  );
   fs.writeFileSync(getConfigPath(), content, 'utf8');
 }

From 2a4a7e394889a5ec655e7edb4d66e74bd10ce1bc Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 20:03:29 -0400
Subject: [PATCH 16/29] feat: implement server restart command and enhance stop
 logic in CLI

---
 docs/adrs/002.cli.start-stop.md | 18 +++++++++++------
 docs/specs/cli.md               |  4 ++--
 docs/specs/release-process.md   |  6 +++---
 docs/specs/webtty.md            | 16 +++++++--------
 src/cli/commands.test.ts        | 17 ++++++++++++++++
 src/cli/commands.ts             | 35 +++++++++++++++++++++++----------
 src/cli/http.ts                 | 15 ++++++++++++++
 7 files changed, 81 insertions(+), 30 deletions(-)

diff --git a/docs/adrs/002.cli.start-stop.md b/docs/adrs/002.cli.start-stop.md
index 03a0100..bd9cac9 100644
--- a/docs/adrs/002.cli.start-stop.md
+++ b/docs/adrs/002.cli.start-stop.md
@@ -1,4 +1,4 @@
-# ADR 002: CLI — `webtty start` / `webtty stop`
+# ADR 002: CLI — `webtty start` / `webtty stop` / `webtty restart`
 
 **SPEC:** [cli](../specs/cli.md)
 **Status:** Accepted
@@ -26,9 +26,15 @@ Add a CLI entry point (`src/cli.ts`) and a `POST /api/server/stop` endpoint to `
 - Polls `GET /api/sessions` until it responds (or times out), then prints `webtty started`. This ensures the server is actually ready before the CLI exits.
 
 **`webtty stop`**:
-- Sends `POST http://localhost:PORT/api/server/stop`.
-- If the request succeeds: prints `webtty stopped`.
-- If the request fails (connection refused): prints `webtty is not running`.
+- Checks `GET /api/sessions` first — if connection refused, prints `webtty is not running` and exits 0.
+- Otherwise sends `POST http://localhost:PORT/api/server/stop` and polls until the server is down.
+- Prints `webtty stopped` on success, `webtty stop failed` and exits 1 if the server doesn't come down.
+
+**`webtty restart`**:
+- If the server is running, calls the same stop logic (wait for down).
+- Then calls the same start logic (spawn detached, poll until ready).
+- Prints `webtty restarted`.
+- If the server is not running, skips the stop step — restart from cold always works.
 
 **`server.ts` change**: Add `POST /api/server/stop` — kills all PTY sessions, closes the WebSocket server, and calls `process.exit(0)`. The server owns its own shutdown on all platforms.
 
@@ -64,9 +70,9 @@ A `webtty.sh` that does `node dist/server.js &`.
 
 ## Consequences
 
-**Good**: `npx webtty start` works from any directory. Server runs in background, terminal is free. `npx webtty stop` works identically on Mac, Linux, and Windows — no signals, no PID files, no platform-specific code. Server owns its cleanup. No new runtime dependencies.
+**Good**: `npx webtty start` works from any directory. Server runs in background, terminal is free. `npx webtty stop` and `npx webtty restart` work identically on Mac, Linux, and Windows — no signals, no PID files, no platform-specific code. Server owns its cleanup. `stopServer()` is extracted into `http.ts` so `stop` and `restart` share the same wait-for-down logic. No new runtime dependencies.
 
-**Bad**: If the server is hung, `webtty stop` fails silently — acceptable for this slice; hard-kill fallback deferred. Port is hardcoded at 2346 — will become configurable when the config file slice lands.
+**Bad**: If the server is hung, `webtty stop` fails — acceptable for this slice; hard-kill fallback deferred. Port is hardcoded at 2346 — will become configurable when the config file slice lands.
 
 ## Implementation Notes
 
diff --git a/docs/specs/cli.md b/docs/specs/cli.md
index 38497b1..428144c 100644
--- a/docs/specs/cli.md
+++ b/docs/specs/cli.md
@@ -27,7 +27,7 @@ The CLI communicates with the server exclusively over HTTP to localhost — no U
 | `webtty run [id]` | Start server if not running; create session (auto-generates ID if omitted) or reuse if ID exists; open session URL in the default browser |
 | `webtty rm <id>` | `DELETE /api/sessions/:id` — kill session and its PTY |
 | `webtty rename <id> <new-id>` | `PATCH /api/sessions/:id` — rename a session; session URL updates to reflect new id |
-| `webtty restart` | Stop + start | ⬜ not yet implemented |
+| `webtty restart` | Stop + start |
 
 ## Features
 
@@ -35,4 +35,4 @@ The CLI communicates with the server exclusively over HTTP to localhost — no U
 |---------|-------------|-----|-------|
 | Server lifecycle | `webtty start` / `stop` — fork, detect, and terminate the server over HTTP | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
 | Session management | `webtty run` / `ls` / `rm` / `rename` — create, list, remove, and rename sessions via the REST API | [ADR 006](../adrs/006.cli.session-management.md) | ✅ |
-| Server restart | `webtty restart` — stop then start; `POST /api/server/restart` on server side | — | ⬜ |
+| Server restart | `webtty restart` — stop then start | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
diff --git a/docs/specs/release-process.md b/docs/specs/release-process.md
index 6463b5d..64c72a0 100644
--- a/docs/specs/release-process.md
+++ b/docs/specs/release-process.md
@@ -125,6 +125,6 @@ main branch:
 
 | Feature | Status | Reference |
 |---------|--------|-----------|
-| Automated versioning via conventional commits | ⬜ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
-| npm publish on release | ⬜ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
-| GitHub Release with release notes | ⬜ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
+| Automated versioning via conventional commits | ✅ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
+| npm publish on release | ✅ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
+| GitHub Release with release notes | ✅ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
diff --git a/docs/specs/webtty.md b/docs/specs/webtty.md
index d34697d..04fc717 100644
--- a/docs/specs/webtty.md
+++ b/docs/specs/webtty.md
@@ -21,7 +21,7 @@ The goal is the same as ttyd and GoTTY: zero client-side installation, full TUI
 
 Sessions are PTY instances keyed by ID. Each session has a unique ID and a running PTY process. Sessions survive WebSocket disconnects but not server restarts (memory-only — webtty defers long-lived persistence to `tmux`/`screen`).
 
-New sessions use the user's default shell from the environment (`$SHELL` on POSIX, `%COMSPEC%` on Windows). No per-session command override.
+New sessions use the shell configured in `~/.config/webtty/config.json` (defaults to `$SHELL` on POSIX, `%COMSPEC%` on Windows). No per-session command override.
 
 ### Session data model
 
@@ -36,10 +36,10 @@ interface Session {
 ### Session lifecycle
 
 ```
-                    WS connect                   WS connect (more clients)
-                   (PTY spawns)                  (scrollback replayed)
-                       │                                │
-  POST /api/sessions   │      all clients disconnect    │
+                    WS connect                WS connect (more clients)
+                   (PTY spawns)               (scrollback replayed)
+                       │                             │
+  POST /api/sessions   │   all clients disconnect    │
   ────────────────► [idle] ◄──────────────────── [active] ──► [active]
                        │                            │         clients: 1..N
                        │                            │
@@ -51,8 +51,6 @@ interface Session {
 
 Sessions survive client disconnects — the PTY keeps running while idle. Multiple clients can attach to the same session simultaneously; PTY output is broadcast to all.
 
-
-
 Session IDs appear directly in the URL path (`/s/:id`), so they must be valid URL path segments:
 
 - Allowed characters: `a-z`, `0-9`, `-`, `_`, `.`
@@ -82,10 +80,10 @@ Session IDs appear directly in the URL path (`/s/:id`), so they must be valid UR
 
 | Feature | Description | ADR | Done? |
 |---------|-------------|-----|-------|
-| Bootstrap | Port `ghostty-web` demo into webtty — full-screen terminal in a browser tab, single server, hardcoded config | [001](../adrs/001.webtty.bootstrap.md) | ⬜ |
+| Bootstrap | Port `ghostty-web` demo into webtty — full-screen terminal in a browser tab, single server, hardcoded config | [001](../adrs/001.webtty.bootstrap.md) | ✅ |
 | In-memory registry | Server-side map of `id → { session, pty }`; sessions survive WS disconnect, not server restart | — | ✅ |
 | Default session | `GET /` redirects to last-used session, or creates `main` and redirects if none exists | — | ✅ |
 | Session URL | `GET /s/:id` — serves browser client for the named session; reconnects if session already has a PTY | — | ✅ |
 | Session management | CRUD + rename over HTTP — see REST API above | [ADR 004](../adrs/004.webtty.session-api.md) | ✅ |
-| Config file | Load shell, port, font, theme from a config file (`~/.config/webtty/config.json`) | [ADR 008](../adrs/008.webtty.config.md) | ⬜ | → [config spec](config.md) |
+| Config file | Load shell, port, font, theme from `~/.config/webtty/config.json`; hot-reload on tab reload | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
 | Session client | Multiple browser tabs can attach to the same session simultaneously; reload replays scrollback; typing `exit` closes all tabs | [ADR 007](../adrs/007.webtty.session-client.md) | ✅ |
diff --git a/src/cli/commands.test.ts b/src/cli/commands.test.ts
index 72166dc..34f32c0 100644
--- a/src/cli/commands.test.ts
+++ b/src/cli/commands.test.ts
@@ -106,6 +106,23 @@ describe('cli — lifecycle', () => {
     expect(exitCode).toBe(0);
     expect(stdout).toBe('webtty is not running');
   });
+
+  test('restart starts the server when not running', async () => {
+    const { stdout, exitCode } = await runCli(port, 'restart');
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe('webtty restarted');
+    expect(await waitForServer(baseUrl)).toBe(true);
+  });
+
+  test('restart stops and restarts a running server', async () => {
+    const resBefore = await fetch(`${baseUrl}/api/sessions`);
+    expect(resBefore.ok).toBe(true);
+
+    const { stdout, exitCode } = await runCli(port, 'restart');
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe('webtty restarted');
+    expect(await waitForServer(baseUrl)).toBe(true);
+  });
 });
 
 describe('cli — session management', () => {
diff --git a/src/cli/commands.ts b/src/cli/commands.ts
index 7807815..3972ae2 100644
--- a/src/cli/commands.ts
+++ b/src/cli/commands.ts
@@ -1,5 +1,5 @@
 import type { Command } from 'commander';
-import { BASE_URL, isServerRunning, openBrowser, startServer } from './http';
+import { BASE_URL, isServerRunning, openBrowser, startServer, stopServer } from './http';
 
 export function registerCommands(program: Command): void {
   program
@@ -18,16 +18,16 @@ export function registerCommands(program: Command): void {
     .command('stop')
     .description('Stop the webtty server')
     .action(async () => {
-      try {
-        const res = await fetch(`${BASE_URL}/api/server/stop`, { method: 'POST' });
-        if (res.ok) {
-          console.log('webtty stopped');
-        } else {
-          console.error(`webtty stop failed (status: ${res.status})`);
-          process.exit(1);
-        }
-      } catch {
+      if (!(await isServerRunning())) {
         console.log('webtty is not running');
+        return;
+      }
+      const ok = await stopServer();
+      if (ok) {
+        console.log('webtty stopped');
+      } else {
+        console.error('webtty stop failed');
+        process.exit(1);
       }
     });
 
@@ -155,4 +155,19 @@ export function registerCommands(program: Command): void {
         process.exit(1);
       }
     });
+
+  program
+    .command('restart')
+    .description('Restart the webtty server')
+    .action(async () => {
+      if (await isServerRunning()) {
+        const ok = await stopServer();
+        if (!ok) {
+          console.error('webtty: failed to stop server');
+          process.exit(1);
+        }
+      }
+      await startServer();
+      console.log('webtty restarted');
+    });
 }
diff --git a/src/cli/http.ts b/src/cli/http.ts
index 7724858..4da44b4 100644
--- a/src/cli/http.ts
+++ b/src/cli/http.ts
@@ -48,6 +48,21 @@ export async function startServer(): Promise<void> {
   process.exit(1);
 }
 
+export async function stopServer(baseUrl: string = BASE_URL): Promise<boolean> {
+  try {
+    const res = await fetch(`${baseUrl}/api/server/stop`, { method: 'POST' });
+    if (!res.ok) return false;
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+      if (!(await isServerRunning())) return true;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 export function openBrowser(url: string): void {
   if (process.env.WEBTTY_NO_OPEN === '1') return;
   if (process.platform === 'win32') {

From 1289c4b99c27fcf6d81d2ae6c55f219e16a89c9b Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 20:14:01 -0400
Subject: [PATCH 17/29] feat: add timeout parameter to stopServer function and
 implement tests for server control functions

---
 src/cli/http.test.ts | 109 +++++++++++++++++++++++++++++++++++++++++++
 src/cli/http.ts      |   4 +-
 2 files changed, 111 insertions(+), 2 deletions(-)
 create mode 100644 src/cli/http.test.ts

diff --git a/src/cli/http.test.ts b/src/cli/http.test.ts
new file mode 100644
index 0000000..09079d1
--- /dev/null
+++ b/src/cli/http.test.ts
@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test';
+import childProcess from 'node:child_process';
+import fs from 'node:fs';
+
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('isServerRunning', () => {
+  test('returns true when GET /api/sessions succeeds', async () => {
+    globalThis.fetch = mock(
+      async () => new Response('[]', { status: 200 }),
+    ) as unknown as typeof fetch;
+
+    const { isServerRunning } = await import('./http');
+    expect(await isServerRunning()).toBe(true);
+  });
+
+  test('returns false when fetch throws', async () => {
+    globalThis.fetch = mock(async () => {
+      throw new Error('connection refused');
+    }) as unknown as typeof fetch;
+
+    const { isServerRunning } = await import('./http');
+    expect(await isServerRunning()).toBe(false);
+  });
+});
+
+describe('stopServer', () => {
+  test('returns true when server stops after POST succeeds', async () => {
+    let callCount = 0;
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      if (init?.method === 'POST') return new Response('stopping', { status: 200 });
+      callCount++;
+      if (callCount >= 2) throw new Error('connection refused');
+      return new Response('[]', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer()).toBe(true);
+  });
+
+  test('returns false when POST to stop endpoint fails', async () => {
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      if (init?.method === 'POST') return new Response('error', { status: 500 });
+      return new Response('[]', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer()).toBe(false);
+  });
+
+  test('returns false when fetch throws', async () => {
+    globalThis.fetch = mock(async () => {
+      throw new Error('connection refused');
+    }) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer()).toBe(false);
+  });
+
+  test('returns false when server does not come down within timeout', async () => {
+    globalThis.fetch = mock(
+      async () => new Response('[]', { status: 200 }),
+    ) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer('http://127.0.0.1:1', 100)).toBe(false);
+  });
+});
+
+describe('startServer', () => {
+  test('exits with error when server entry not found', async () => {
+    spyOn(fs, 'existsSync').mockReturnValue(false);
+    const exitSpy = spyOn(process, 'exit').mockImplementation((() => {}) as () => never);
+    const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
+
+    const { startServer } = await import('./http');
+    await startServer();
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('server entry not found'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+    (fs.existsSync as ReturnType<typeof spyOn>).mockRestore();
+  });
+});
+
+describe('openBrowser', () => {
+  test('does nothing when WEBTTY_NO_OPEN=1', async () => {
+    const origEnv = process.env.WEBTTY_NO_OPEN;
+    process.env.WEBTTY_NO_OPEN = '1';
+    const spawnSpy = spyOn(childProcess, 'spawn');
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main');
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    process.env.WEBTTY_NO_OPEN = origEnv;
+    spawnSpy.mockRestore();
+  });
+});
diff --git a/src/cli/http.ts b/src/cli/http.ts
index 4da44b4..043e588 100644
--- a/src/cli/http.ts
+++ b/src/cli/http.ts
@@ -48,11 +48,11 @@ export async function startServer(): Promise<void> {
   process.exit(1);
 }
 
-export async function stopServer(baseUrl: string = BASE_URL): Promise<boolean> {
+export async function stopServer(baseUrl: string = BASE_URL, timeoutMs = 5000): Promise<boolean> {
   try {
     const res = await fetch(`${baseUrl}/api/server/stop`, { method: 'POST' });
     if (!res.ok) return false;
-    const deadline = Date.now() + 5000;
+    const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       if (!(await isServerRunning())) return true;
       await new Promise((r) => setTimeout(r, 100));

From 71f0a1b6c09dde57b732f985cf9b40276284bfac Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 20:23:20 -0400
Subject: [PATCH 18/29] feat: refactor shutdown logic and session management in
 server and websocket modules

---
 src/server/index.ts     | 40 ++++++++++++++--------------------------
 src/server/routes.ts    |  4 ++--
 src/server/websocket.ts | 30 ++++++++++++++++++++++++++----
 3 files changed, 42 insertions(+), 32 deletions(-)

diff --git a/src/server/index.ts b/src/server/index.ts
index 05cc85b..863642d 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -1,9 +1,8 @@
 import http from 'node:http';
 import { loadConfig } from '../config';
 import { handleRequest } from './routes';
-import { sessionRegistry } from './session';
 import { findGhosttyWeb } from './static';
-import { createWebSocketServer } from './websocket';
+import { closeAllSessions, createWebSocketServer } from './websocket';
 
 const config = loadConfig();
 const HTTP_PORT = Number(process.env.PORT) || config.port;
@@ -11,30 +10,8 @@ const HTTP_HOST = config.host;
 
 const { distPath, wasmPath } = findGhosttyWeb();
 
-const httpServer = http.createServer((req, res) => {
-  handleRequest(req, res, distPath, wasmPath, config, () => {
-    for (const session of sessionRegistry.values()) {
-      session.pty?.kill();
-      for (const client of session.clients) client.close(1001, 'server stopped');
-    }
-    wss.close();
-    const exit = () => process.exit(0);
-    const shutdownTimeout = setTimeout(exit, 1000);
-    httpServer.close(() => {
-      clearTimeout(shutdownTimeout);
-      exit();
-    });
-  });
-});
-
-const wss = createWebSocketServer(httpServer);
-
-process.on('SIGINT', () => {
-  console.log('\n\nShutting down...');
-  for (const session of sessionRegistry.values()) {
-    session.pty?.kill();
-    for (const client of session.clients) client.close(1001, 'server stopped');
-  }
+function shutdown() {
+  closeAllSessions();
   wss.close();
   const exit = () => process.exit(0);
   const shutdownTimeout = setTimeout(exit, 1000);
@@ -42,6 +19,17 @@ process.on('SIGINT', () => {
     clearTimeout(shutdownTimeout);
     exit();
   });
+}
+
+const httpServer = http.createServer((req, res) => {
+  handleRequest(req, res, distPath, wasmPath, config, shutdown);
+});
+
+const wss = createWebSocketServer(httpServer);
+
+process.on('SIGINT', () => {
+  console.log('\n\nShutting down...');
+  shutdown();
 });
 
 httpServer.listen(HTTP_PORT, HTTP_HOST, () => {
diff --git a/src/server/routes.ts b/src/server/routes.ts
index 38a9060..316faa0 100644
--- a/src/server/routes.ts
+++ b/src/server/routes.ts
@@ -12,6 +12,7 @@ import {
   setLastUsedId,
 } from './session';
 import { serveFile } from './static';
+import { closeSession } from './websocket';
 
 const MAX_BODY = 64 * 1024;
 
@@ -172,8 +173,7 @@ export async function handleRequest(
       }
       sessionRegistry.delete(id);
       if (lastUsedId === id) setLastUsedId(null);
-      for (const client of session.clients) client.close(4001, 'session deleted');
-      session.pty?.kill();
+      closeSession(session);
       res.writeHead(204);
       res.end();
       return;
diff --git a/src/server/websocket.ts b/src/server/websocket.ts
index de6134a..e898212 100644
--- a/src/server/websocket.ts
+++ b/src/server/websocket.ts
@@ -3,8 +3,30 @@ import type { WebSocket as WS } from 'ws';
 import { WebSocketServer } from 'ws';
 import { loadConfig } from '../config';
 import { spawnForSession } from '../pty';
+import type { Session } from './session';
 import { sessionRegistry, setLastUsedId } from './session';
 
+const WS_CLOSE = {
+  SERVER_STOPPED: 1001 as const, // RFC 6455: server going away
+  BAD_REQUEST: 1008 as const, // RFC 6455: policy violation / bad data
+  SESSION_GONE: 4001 as const, // app-level: session deleted or shell exited
+} as const;
+
+function closeClients(session: Session, code: number, reason: string): void {
+  session.pty?.kill();
+  for (const client of session.clients) client.close(code, reason);
+}
+
+export function closeSession(session: Session): void {
+  closeClients(session, WS_CLOSE.SESSION_GONE, 'session deleted');
+}
+
+export function closeAllSessions(): void {
+  for (const session of sessionRegistry.values()) {
+    closeClients(session, WS_CLOSE.SERVER_STOPPED, 'server stopped');
+  }
+}
+
 export function createWebSocketServer(httpServer: http.Server): WebSocketServer {
   const wss = new WebSocketServer({ noServer: true });
 
@@ -29,7 +51,7 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
     try {
       id = decodeURIComponent(wsMatch[1]);
     } catch {
-      ws.close(1008, 'Bad Request');
+      ws.close(WS_CLOSE.BAD_REQUEST, 'Bad Request');
       return;
     }
     const cols = Math.max(
@@ -42,13 +64,13 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
     );
 
     if (!sessionRegistry.has(id)) {
-      ws.close(4001, 'session deleted');
+      ws.close(WS_CLOSE.SESSION_GONE, 'session deleted');
       return;
     }
 
     const session = sessionRegistry.get(id);
     if (!session) {
-      ws.close(4001, 'session deleted');
+      ws.close(WS_CLOSE.SESSION_GONE, 'session deleted');
       return;
     }
     session.clients.add(ws);
@@ -71,7 +93,7 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
         sessionRegistry.delete(session.id);
         for (const client of session.clients) {
           if (client.readyState === client.OPEN) {
-            client.close(4001, 'shell exited');
+            client.close(WS_CLOSE.SESSION_GONE, 'shell exited');
           }
         }
         session.pty = null;

From 3ac7dfbfc60519fbefa9a2fc25f9f45b6c6d569a Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 20:40:18 -0400
Subject: [PATCH 19/29] feat: refactor server start and openBrowser functions
 to accept custom spawn method and improve timeout handling

---
 src/cli/http.test.ts | 119 +++++++++++++++++++++++++++++++++++++++++--
 src/cli/http.ts      |  20 +++-----
 2 files changed, 121 insertions(+), 18 deletions(-)

diff --git a/src/cli/http.test.ts b/src/cli/http.test.ts
index 09079d1..222615b 100644
--- a/src/cli/http.test.ts
+++ b/src/cli/http.test.ts
@@ -1,5 +1,4 @@
 import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test';
-import childProcess from 'node:child_process';
 import fs from 'node:fs';
 
 const realFetch = globalThis.fetch;
@@ -91,19 +90,129 @@ describe('startServer', () => {
     errorSpy.mockRestore();
     (fs.existsSync as ReturnType<typeof spyOn>).mockRestore();
   });
+
+  test('spawns server and resolves when it becomes reachable', async () => {
+    spyOn(fs, 'existsSync').mockReturnValue(true);
+    const fakeChild = { unref: mock(() => {}) };
+    const spawnMock = mock(() => fakeChild);
+
+    let calls = 0;
+    globalThis.fetch = mock(async () => {
+      calls++;
+      if (calls < 3) throw new Error('not yet');
+      return new Response('[]', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const { startServer } = await import('./http');
+    await startServer(10000, spawnMock as never);
+
+    expect(calls).toBeGreaterThanOrEqual(3);
+    expect(fakeChild.unref).toHaveBeenCalled();
+
+    (fs.existsSync as ReturnType<typeof spyOn>).mockRestore();
+  });
+
+  test('exits with error when server does not start within timeout', async () => {
+    spyOn(fs, 'existsSync').mockReturnValue(true);
+    const spawnMock = mock(() => ({ unref: () => {} }));
+    const exitSpy = spyOn(process, 'exit').mockImplementation((() => {}) as () => never);
+    const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
+
+    globalThis.fetch = mock(async () => {
+      throw new Error('not yet');
+    }) as unknown as typeof fetch;
+
+    const { startServer } = await import('./http');
+    await startServer(100, spawnMock as never);
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('server did not start in time'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    (fs.existsSync as ReturnType<typeof spyOn>).mockRestore();
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test('exits with error when server does not start within timeout', async () => {
+    const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(true);
+    const spawnMock = mock(() => ({ unref: () => {} }));
+    const exitSpy = spyOn(process, 'exit').mockImplementation((() => {}) as () => never);
+    const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
+
+    globalThis.fetch = mock(async () => {
+      throw new Error('not yet');
+    }) as unknown as typeof fetch;
+
+    const { startServer } = await import('./http');
+    await startServer(100, spawnMock as never);
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('server did not start in time'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    existsSpy.mockRestore();
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
 });
 
 describe('openBrowser', () => {
   test('does nothing when WEBTTY_NO_OPEN=1', async () => {
     const origEnv = process.env.WEBTTY_NO_OPEN;
     process.env.WEBTTY_NO_OPEN = '1';
-    const spawnSpy = spyOn(childProcess, 'spawn');
+    const spawnMock = mock(() => ({ unref: () => {} }));
 
     const { openBrowser } = await import('./http');
-    openBrowser('http://localhost:2346/s/main');
-    expect(spawnSpy).not.toHaveBeenCalled();
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).not.toHaveBeenCalled();
 
     process.env.WEBTTY_NO_OPEN = origEnv;
-    spawnSpy.mockRestore();
+  });
+
+  test('spawns open on darwin', async () => {
+    const origPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true });
+    const spawnMock = mock(() => ({ unref: () => {} }));
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).toHaveBeenCalledWith(
+      'open',
+      ['http://localhost:2346/s/main'],
+      expect.anything(),
+    );
+
+    Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+  });
+
+  test('spawns xdg-open on linux', async () => {
+    const origPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+    const spawnMock = mock(() => ({ unref: () => {} }));
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).toHaveBeenCalledWith(
+      'xdg-open',
+      ['http://localhost:2346/s/main'],
+      expect.anything(),
+    );
+
+    Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+  });
+
+  test('spawns cmd.exe on win32', async () => {
+    const origPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+    const spawnMock = mock(() => ({ unref: () => {} }));
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).toHaveBeenCalledWith(
+      'cmd.exe',
+      expect.arrayContaining(['start']),
+      expect.anything(),
+    );
+
+    Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
   });
 });
diff --git a/src/cli/http.ts b/src/cli/http.ts
index 043e588..2ea1c46 100644
--- a/src/cli/http.ts
+++ b/src/cli/http.ts
@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import * as childProcess from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -18,11 +18,7 @@ export async function isServerRunning(): Promise<boolean> {
   }
 }
 
-export async function startServer(): Promise<void> {
-  // When running from source (e.g. `bun run src/cli/index.ts` during development),
-  // __filename ends with .ts and Bun is the runtime, so we can point at the .ts
-  // server entry directly. Built output always lands in .js, so Node is never
-  // asked to execute TypeScript. In production isTs is always false.
+export async function startServer(timeoutMs = 10000, _spawn = childProcess.spawn): Promise<void> {
   const isBun = typeof (globalThis as Record<string, unknown>).Bun !== 'undefined';
   const isTs = isBun && __filename.endsWith('.ts');
   const serverEntry = path.resolve(__dirname, isTs ? '../server/index.ts' : '../server/index.js');
@@ -30,16 +26,14 @@ export async function startServer(): Promise<void> {
     console.error(`webtty: server entry not found at ${serverEntry}`);
     process.exit(1);
   }
-  // Reuse the current runtime (bun, node, etc.) to spawn the server so the
-  // server always runs under the same runtime as the CLI.
-  const child = spawn(process.execPath, [serverEntry], {
+  const child = _spawn(process.execPath, [serverEntry], {
     detached: true,
     stdio: 'ignore',
     env: { ...process.env, PORT: String(PORT) },
   });
   child.unref();
 
-  const deadline = Date.now() + 10000;
+  const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await isServerRunning()) return;
     await new Promise((r) => setTimeout(r, 100));
@@ -63,12 +57,12 @@ export async function stopServer(baseUrl: string = BASE_URL, timeoutMs = 5000):
   }
 }
 
-export function openBrowser(url: string): void {
+export function openBrowser(url: string, _spawn = childProcess.spawn): void {
   if (process.env.WEBTTY_NO_OPEN === '1') return;
   if (process.platform === 'win32') {
-    spawn('cmd.exe', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+    _spawn('cmd.exe', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
   } else {
     const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
-    spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
+    _spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
   }
 }

From da4c1aafcb84117d704f2ee4be42a1ce8bfa358c Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 20:49:46 -0400
Subject: [PATCH 20/29] feat: modify openBrowser function to skip opening URLs
 in test environment

---
 src/cli/http.test.ts | 9 +++++++++
 src/cli/http.ts      | 1 +
 2 files changed, 10 insertions(+)

diff --git a/src/cli/http.test.ts b/src/cli/http.test.ts
index 222615b..d1150b3 100644
--- a/src/cli/http.test.ts
+++ b/src/cli/http.test.ts
@@ -169,6 +169,8 @@ describe('openBrowser', () => {
   });
 
   test('spawns open on darwin', async () => {
+    const origNodeEnv = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
     const origPlatform = process.platform;
     Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true });
     const spawnMock = mock(() => ({ unref: () => {} }));
@@ -182,9 +184,12 @@ describe('openBrowser', () => {
     );
 
     Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+    process.env.NODE_ENV = origNodeEnv;
   });
 
   test('spawns xdg-open on linux', async () => {
+    const origNodeEnv = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
     const origPlatform = process.platform;
     Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
     const spawnMock = mock(() => ({ unref: () => {} }));
@@ -198,9 +203,12 @@ describe('openBrowser', () => {
     );
 
     Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+    process.env.NODE_ENV = origNodeEnv;
   });
 
   test('spawns cmd.exe on win32', async () => {
+    const origNodeEnv = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
     const origPlatform = process.platform;
     Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
     const spawnMock = mock(() => ({ unref: () => {} }));
@@ -214,5 +222,6 @@ describe('openBrowser', () => {
     );
 
     Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+    process.env.NODE_ENV = origNodeEnv;
   });
 });
diff --git a/src/cli/http.ts b/src/cli/http.ts
index 2ea1c46..a10e5ea 100644
--- a/src/cli/http.ts
+++ b/src/cli/http.ts
@@ -59,6 +59,7 @@ export async function stopServer(baseUrl: string = BASE_URL, timeoutMs = 5000):
 
 export function openBrowser(url: string, _spawn = childProcess.spawn): void {
   if (process.env.WEBTTY_NO_OPEN === '1') return;
+  if (process.env.NODE_ENV === 'test') return;
   if (process.platform === 'win32') {
     _spawn('cmd.exe', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
   } else {

From c08b123281b993be28a5c4492a12f04b3e27d0f9 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 20:55:36 -0400
Subject: [PATCH 21/29] feat: update default theme colors to match Campbell
 palette

---
 docs/specs/config.md | 82 ++++++++++++++++++++++----------------------
 src/config.ts        | 40 ++++++++++-----------
 2 files changed, 61 insertions(+), 61 deletions(-)

diff --git a/docs/specs/config.md b/docs/specs/config.md
index b6185a8..24f00f1 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -116,30 +116,30 @@ All keys are optional — omit any key to use the default value.
 
 ### Theme keys
 
-All theme keys are optional; omitted keys fall back to the Dracula defaults.
+All theme keys are optional; omitted keys fall back to the Campbell (Windows Terminal default) palette.
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `background` | `#282A36` | Terminal background |
-| `foreground` | `#F8F8F2` | Default text color |
-| `cursor` | `#F8F8F2` | Cursor color |
-| `selection` | `#44475A` | Selection highlight |
-| `black` | `#21222C` | ANSI 0 |
-| `red` | `#FF5555` | ANSI 1 |
-| `green` | `#50FA7B` | ANSI 2 |
-| `yellow` | `#F1FA8C` | ANSI 3 |
-| `blue` | `#BD93F9` | ANSI 4 |
-| `purple` | `#FF79C6` | ANSI 5 |
-| `cyan` | `#8BE9FD` | ANSI 6 |
-| `white` | `#F8F8F2` | ANSI 7 |
-| `brightBlack` | `#6272A4` | ANSI 8 |
-| `brightRed` | `#FF6E6E` | ANSI 9 |
-| `brightGreen` | `#69FF94` | ANSI 10 |
-| `brightYellow` | `#FFFFA5` | ANSI 11 |
-| `brightBlue` | `#D6ACFF` | ANSI 12 |
-| `brightPurple` | `#FF92DF` | ANSI 13 |
-| `brightCyan` | `#A4FFFF` | ANSI 14 |
-| `brightWhite` | `#FFFFFF` | ANSI 15 |
+| `background` | `#000000` | Terminal background |
+| `foreground` | `#CCCCCC` | Default text color |
+| `cursor` | `#FFFFFF` | Cursor color |
+| `selection` | `#FFFFFF` | Selection highlight |
+| `black` | `#0C0C0C` | ANSI 0 |
+| `red` | `#C50F1F` | ANSI 1 |
+| `green` | `#13A10E` | ANSI 2 |
+| `yellow` | `#C19C00` | ANSI 3 |
+| `blue` | `#0037DA` | ANSI 4 |
+| `purple` | `#881798` | ANSI 5 |
+| `cyan` | `#3A96DD` | ANSI 6 |
+| `white` | `#CCCCCC` | ANSI 7 |
+| `brightBlack` | `#767676` | ANSI 8 |
+| `brightRed` | `#E74856` | ANSI 9 |
+| `brightGreen` | `#16C60C` | ANSI 10 |
+| `brightYellow` | `#F9F1A5` | ANSI 11 |
+| `brightBlue` | `#3B78FF` | ANSI 12 |
+| `brightPurple` | `#B4009E` | ANSI 13 |
+| `brightCyan` | `#61D6D6` | ANSI 14 |
+| `brightWhite` | `#F2F2F2` | ANSI 15 |
 
 ### Example
 
@@ -159,26 +159,26 @@ All theme keys are optional; omitted keys fall back to the Dracula defaults.
   "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
 
   "theme": {
-    "background":   "#282A36",
-    "foreground":   "#F8F8F2",
-    "cursor":       "#F8F8F2",
-    "selection":    "#44475A",
-    "black":        "#21222C",
-    "red":          "#FF5555",
-    "green":        "#50FA7B",
-    "yellow":       "#F1FA8C",
-    "blue":         "#BD93F9",
-    "purple":       "#FF79C6",
-    "cyan":         "#8BE9FD",
-    "white":        "#F8F8F2",
-    "brightBlack":  "#6272A4",
-    "brightRed":    "#FF6E6E",
-    "brightGreen":  "#69FF94",
-    "brightYellow": "#FFFFA5",
-    "brightBlue":   "#D6ACFF",
-    "brightPurple": "#FF92DF",
-    "brightCyan":   "#A4FFFF",
-    "brightWhite":  "#FFFFFF"
+    "background":   "#000000",
+    "foreground":   "#CCCCCC",
+    "cursor":       "#FFFFFF",
+    "selection":    "#FFFFFF",
+    "black":        "#0C0C0C",
+    "red":          "#C50F1F",
+    "green":        "#13A10E",
+    "yellow":       "#C19C00",
+    "blue":         "#0037DA",
+    "purple":       "#881798",
+    "cyan":         "#3A96DD",
+    "white":        "#CCCCCC",
+    "brightBlack":  "#767676",
+    "brightRed":    "#E74856",
+    "brightGreen":  "#16C60C",
+    "brightYellow": "#F9F1A5",
+    "brightBlue":   "#3B78FF",
+    "brightPurple": "#B4009E",
+    "brightCyan":   "#61D6D6",
+    "brightWhite":  "#F2F2F2"
   }
 }
 ```
diff --git a/src/config.ts b/src/config.ts
index b491482..9b4eb3c 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -45,26 +45,26 @@ function getConfigPath(): string {
 }
 
 export const DEFAULT_THEME: Theme = {
-  background: '#282A36',
-  foreground: '#F8F8F2',
-  cursor: '#F8F8F2',
-  selection: '#44475A',
-  black: '#21222C',
-  red: '#FF5555',
-  green: '#50FA7B',
-  yellow: '#F1FA8C',
-  blue: '#BD93F9',
-  purple: '#FF79C6',
-  cyan: '#8BE9FD',
-  white: '#F8F8F2',
-  brightBlack: '#6272A4',
-  brightRed: '#FF6E6E',
-  brightGreen: '#69FF94',
-  brightYellow: '#FFFFA5',
-  brightBlue: '#D6ACFF',
-  brightPurple: '#FF92DF',
-  brightCyan: '#A4FFFF',
-  brightWhite: '#FFFFFF',
+  background: '#000000',
+  foreground: '#CCCCCC',
+  cursor: '#FFFFFF',
+  selection: '#FFFFFF',
+  black: '#0C0C0C',
+  red: '#C50F1F',
+  green: '#13A10E',
+  yellow: '#C19C00',
+  blue: '#0037DA',
+  purple: '#881798',
+  cyan: '#3A96DD',
+  white: '#CCCCCC',
+  brightBlack: '#767676',
+  brightRed: '#E74856',
+  brightGreen: '#16C60C',
+  brightYellow: '#F9F1A5',
+  brightBlue: '#3B78FF',
+  brightPurple: '#B4009E',
+  brightCyan: '#61D6D6',
+  brightWhite: '#F2F2F2',
 };
 
 export const DEFAULT_CONFIG: Config = {

From 66ac90a543a9c4691de2a37f4050516bc885a29f Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 21:04:29 -0400
Subject: [PATCH 22/29] feat: update default font size and family in
 configuration

---
 docs/specs/config.md | 8 ++++----
 src/config.ts        | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/specs/config.md b/docs/specs/config.md
index 24f00f1..9d7fb5d 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -110,8 +110,8 @@ All keys are optional — omit any key to use the default value.
 | `cols` | number | `80` | Initial terminal width in columns |
 | `rows` | number | `24` | Initial terminal height in rows |
 | `cursorBlink` | boolean | `true` | Whether the cursor blinks |
-| `fontSize` | number | `14` | Font size in px |
-| `fontFamily` | string | `"'FiraMono Nerd Font', Menlo, ..."` | CSS font-family stack |
+| `fontSize` | number | `13` | Font size in px |
+| `fontFamily` | string | `"Menlo, Consolas, 'DejaVu Sans Mono', monospace"` | CSS font-family stack |
 | `theme` | object | Dracula | Terminal color palette — see theme keys below |
 
 ### Theme keys
@@ -155,8 +155,8 @@ All theme keys are optional; omitted keys fall back to the Campbell (Windows Ter
   "cols": 80,
   "rows": 24,
   "cursorBlink": true,
-  "fontSize": 14,
-  "fontFamily": "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
+  "fontSize": 13,
+  "fontFamily": "Menlo, Consolas, 'DejaVu Sans Mono', monospace",
 
   "theme": {
     "background":   "#000000",
diff --git a/src/config.ts b/src/config.ts
index 9b4eb3c..9e1f426 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -79,8 +79,8 @@ export const DEFAULT_CONFIG: Config = {
   scrollback: 256 * 1024,
   cols: 80,
   rows: 24,
-  fontSize: 14,
-  fontFamily: "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
+  fontSize: 13,
+  fontFamily: "Menlo, Consolas, 'DejaVu Sans Mono', monospace",
   cursorBlink: true,
   theme: DEFAULT_THEME,
 };

From aee3c47d005db525514f1384a424b57246b2979b Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 22:22:04 -0400
Subject: [PATCH 23/29] feat: add no-arg entry point and help command to CLI;
 enhance websocket banner with styled session information

---
 docs/specs/cli.md            |  4 +++
 src/server/websocket.test.ts | 12 ++++++---
 src/server/websocket.ts      | 52 +++++++++++++++++++++++++++---------
 3 files changed, 52 insertions(+), 16 deletions(-)

diff --git a/docs/specs/cli.md b/docs/specs/cli.md
index 428144c..ae35c86 100644
--- a/docs/specs/cli.md
+++ b/docs/specs/cli.md
@@ -28,6 +28,8 @@ The CLI communicates with the server exclusively over HTTP to localhost — no U
 | `webtty rm <id>` | `DELETE /api/sessions/:id` — kill session and its PTY |
 | `webtty rename <id> <new-id>` | `PATCH /api/sessions/:id` — rename a session; session URL updates to reflect new id |
 | `webtty restart` | Stop + start |
+| `webtty` | No-arg entry point — start server if not running, open `main` session in browser | ⬜ |
+| `webtty help` | Alias for `--help` — print all commands | ⬜ |
 
 ## Features
 
@@ -36,3 +38,5 @@ The CLI communicates with the server exclusively over HTTP to localhost — no U
 | Server lifecycle | `webtty start` / `stop` — fork, detect, and terminate the server over HTTP | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
 | Session management | `webtty run` / `ls` / `rm` / `rename` — create, list, remove, and rename sessions via the REST API | [ADR 006](../adrs/006.cli.session-management.md) | ✅ |
 | Server restart | `webtty restart` — stop then start | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
+| No-arg entry point | `webtty` — start server + open `main` session in browser | — | ⬜ |
+| Help command | `webtty help` — alias for `--help` | — | ⬜ |
diff --git a/src/server/websocket.test.ts b/src/server/websocket.test.ts
index 8fb9aee..4cb5d14 100644
--- a/src/server/websocket.test.ts
+++ b/src/server/websocket.test.ts
@@ -3,6 +3,10 @@ import { type ChildProcess, spawn } from 'node:child_process';
 import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+
+const ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+const stripAnsi = (s: string) => s.replace(ANSI_RE, '');
+
 import { WebSocket } from 'ws';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -100,7 +104,7 @@ describe('websocket', () => {
     await waitForMessages(messages, 1);
     await closeWs(ws);
 
-    expect(messages.join('')).toContain('Welcome to webtty');
+    expect(stripAnsi(messages.join(''))).toContain('webtty');
   });
 
   test('reconnect replays scrollback without banner', async () => {
@@ -122,9 +126,9 @@ describe('websocket', () => {
     await waitForMessages(m2, 1);
     await closeWs(ws2);
 
-    const replay = m2.join('');
-    expect(replay).toContain('Welcome to webtty');
-    expect(replay.indexOf('Welcome to webtty')).toBe(replay.lastIndexOf('Welcome to webtty'));
+    const replay = stripAnsi(m2.join(''));
+    expect(replay).toContain('webtty');
+    expect(replay.indexOf('Terminal UI')).toBe(replay.lastIndexOf('Terminal UI'));
   });
 
   test('multiple clients receive same PTY output', async () => {
diff --git a/src/server/websocket.ts b/src/server/websocket.ts
index e898212..055f607 100644
--- a/src/server/websocket.ts
+++ b/src/server/websocket.ts
@@ -27,6 +27,45 @@ export function closeAllSessions(): void {
   }
 }
 
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const ITALIC = '\x1b[3m';
+const YELLOW = '\x1b[1;33m';
+const CYAN = '\x1b[1;36m';
+
+function sessionBanner(): string {
+  const W = 49;
+  const pipe = (content: string) => `${CYAN}║${RESET}${content}${CYAN}║${RESET}`;
+  const blank = pipe(' '.repeat(W));
+
+  const titleVis = ' [ webtty ]   Terminal UI in the browser';
+  const titleStr = ` ${DIM}[${RESET} ${BOLD}${YELLOW}webtty${RESET} ${DIM}]   Terminal UI in the browser${RESET}`;
+  const titleLine = pipe(titleStr + ' '.repeat(W - titleVis.length));
+
+  const helpVis = ' Run `npx webtty help` for available commands.';
+  const helpStr = ` ${DIM}Run ${ITALIC}\`npx webtty help\`${RESET}${DIM} for available commands.${RESET}`;
+  const helpLine = pipe(helpStr + ' '.repeat(W - helpVis.length));
+
+  return [
+    `${CYAN}╔${'═'.repeat(W)}╗${RESET}`,
+    '\r\n',
+    blank,
+    '\r\n',
+    titleLine,
+    '\r\n',
+    blank,
+    '\r\n',
+    helpLine,
+    '\r\n',
+    blank,
+    '\r\n',
+    `${CYAN}╚${'═'.repeat(W)}╝${RESET}`,
+    '\r\n',
+    '\r\n',
+  ].join('');
+}
+
 export function createWebSocketServer(httpServer: http.Server): WebSocketServer {
   const wss = new WebSocketServer({ noServer: true });
 
@@ -99,18 +138,7 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
         session.pty = null;
       });
 
-      const C = '\x1b[1;36m';
-      const G = '\x1b[1;32m';
-      const Y = '\x1b[1;33m';
-      const R = '\x1b[0m';
-      const banner = [
-        `${C}╔══════════════════════════════════════════════════════════════╗${R}\r\n`,
-        `${C}║${R}  ${G}Welcome to webtty!${R}                                          ${C}║${R}\r\n`,
-        `${C}║${R}                                                              ${C}║${R}\r\n`,
-        `${C}║${R}  You have a real shell session with full PTY support.        ${C}║${R}\r\n`,
-        `${C}║${R}  Try: ${Y}ls${R}, ${Y}cd${R}, ${Y}top${R}, ${Y}vim${R}, or any command!                      ${C}║${R}\r\n`,
-        `${C}╚══════════════════════════════════════════════════════════════╝${R}\r\n\r\n`,
-      ].join('');
+      const banner = sessionBanner();
       ws.send(banner);
       session.scrollback = banner;
       session.pty.write('\n');

From 6951dd5a80f0001b887ab2adcbc46b34b193a0a5 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 22:49:57 -0400
Subject: [PATCH 24/29] feat: enhance websocket messages with styled output and
 update session banner help command

---
 src/server/client.ts    | 10 ++++++----
 src/server/websocket.ts | 11 ++++++++---
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/src/server/client.ts b/src/server/client.ts
index c68c3d6..8527f58 100644
--- a/src/server/client.ts
+++ b/src/server/client.ts
@@ -60,18 +60,20 @@ export function render(sessionId: string, config: Config): string {
         };
 
         ws.onclose = (event) => {
+          const DIM = '\\x1b[2m', YELLOW = '\\x1b[1;33m', ITALIC = '\\x1b[3m', RESET = '\\x1b[0m';
+          const tag = DIM + '[' + RESET + ' ' + YELLOW + 'webtty' + RESET + ' ' + DIM + ']' + RESET;
+          const msg = (text) => '\\r\\n' + tag + ' ' + DIM + ITALIC + text + RESET + '\\r\\n';
           if (event.code === 4001) {
-            term.write('\\r\\n\\x1b[31mSession removed.\\x1b[0m\\r\\n');
+            term.write(msg('Session removed.'));
             setTimeout(() => window.close(), 500);
             return;
           }
           if (event.code === 1001) {
-            term.write('\\r\\n\\x1b[33mServer stopped.\\x1b[0m\\r\\n');
+            term.write(msg('Server stopped.'));
             setTimeout(() => window.close(), 500);
             return;
           }
-          console.log('[webtty] disconnected, reconnecting in 2s...');
-          term.write('\\r\\n\\x1b[31mConnection closed. Reconnecting in 2s...\\x1b[0m\\r\\n');
+          term.write(msg('Connection lost. Reconnecting in 2s...'));          
           setTimeout(connect, 2000);
         };
 
diff --git a/src/server/websocket.ts b/src/server/websocket.ts
index 055f607..aa720b2 100644
--- a/src/server/websocket.ts
+++ b/src/server/websocket.ts
@@ -33,9 +33,13 @@ const BOLD = '\x1b[1m';
 const ITALIC = '\x1b[3m';
 const YELLOW = '\x1b[1;33m';
 const CYAN = '\x1b[1;36m';
+const DIM_ITALIC = '\x1b[3m';
+
+const isBun = process.execPath.includes('bun');
+const PKG_RUNNER = isBun ? 'bunx' : 'npx';
 
 function sessionBanner(): string {
-  const W = 49;
+  const W = 48;
   const pipe = (content: string) => `${CYAN}║${RESET}${content}${CYAN}║${RESET}`;
   const blank = pipe(' '.repeat(W));
 
@@ -43,8 +47,9 @@ function sessionBanner(): string {
   const titleStr = ` ${DIM}[${RESET} ${BOLD}${YELLOW}webtty${RESET} ${DIM}]   Terminal UI in the browser${RESET}`;
   const titleLine = pipe(titleStr + ' '.repeat(W - titleVis.length));
 
-  const helpVis = ' Run `npx webtty help` for available commands.';
-  const helpStr = ` ${DIM}Run ${ITALIC}\`npx webtty help\`${RESET}${DIM} for available commands.${RESET}`;
+  const cmd = `${PKG_RUNNER} webtty help`;
+  const helpVis = ` Run \`${cmd}\` for more information.`;
+  const helpStr = ` ${DIM}Run \`${RESET}${ITALIC}${cmd}${RESET}${DIM}\` for more information.${RESET}`;
   const helpLine = pipe(helpStr + ' '.repeat(W - helpVis.length));
 
   return [

From a2d3d53a2fa2ccc47dc11eb40f398a73193e7062 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 22:53:01 -0400
Subject: [PATCH 25/29] feat: enhance websocket error handling with styled
 messages

---
 src/server/client.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/server/client.ts b/src/server/client.ts
index 8527f58..671fdd3 100644
--- a/src/server/client.ts
+++ b/src/server/client.ts
@@ -50,8 +50,11 @@ export function render(sessionId: string, config: Config): string {
         const wsUrl = protocol + '//' + window.location.host + '/ws/' + sessionId + '?cols=' + term.cols + '&rows=' + term.rows;
         ws = new WebSocket(wsUrl);
 
+        const DIM = '\\x1b[2m', YELLOW = '\\x1b[1;33m', ITALIC = '\\x1b[3m', RESET = '\\x1b[0m';
+        const tag = DIM + '[' + RESET + ' ' + YELLOW + 'webtty' + RESET + ' ' + DIM + ']' + RESET;
+        const msg = (text) => '\\r\\n' + tag + ' ' + DIM + ITALIC + text + RESET + '\\r\\n';
+
         ws.onopen = () => {
-          console.log('[webtty] connected to session ' + sessionId);
           ws.send(JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }));
         };
 
@@ -60,9 +63,6 @@ export function render(sessionId: string, config: Config): string {
         };
 
         ws.onclose = (event) => {
-          const DIM = '\\x1b[2m', YELLOW = '\\x1b[1;33m', ITALIC = '\\x1b[3m', RESET = '\\x1b[0m';
-          const tag = DIM + '[' + RESET + ' ' + YELLOW + 'webtty' + RESET + ' ' + DIM + ']' + RESET;
-          const msg = (text) => '\\r\\n' + tag + ' ' + DIM + ITALIC + text + RESET + '\\r\\n';
           if (event.code === 4001) {
             term.write(msg('Session removed.'));
             setTimeout(() => window.close(), 500);
@@ -78,7 +78,7 @@ export function render(sessionId: string, config: Config): string {
         };
 
         ws.onerror = () => {
-          console.error('[webtty] websocket error');
+          term.write(msg('WebSocket error.'));
         };
       }
 

From 335736913c8196963223ec8911a27568ac715c75 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 23:00:54 -0400
Subject: [PATCH 26/29] docs: add ADR 010, 011 and update client/cli specs

---
 docs/adrs/007.webtty.session-client.md |   1 +
 docs/adrs/010.client.ux-polish.md      | 103 +++++++++++++++++++++++++
 docs/adrs/011.cli.default-and-help.md  |  78 +++++++++++++++++++
 docs/specs/cli.md                      |   4 +-
 docs/specs/client.md                   |  57 ++++++++++++--
 5 files changed, 236 insertions(+), 7 deletions(-)
 create mode 100644 docs/adrs/010.client.ux-polish.md
 create mode 100644 docs/adrs/011.cli.default-and-help.md

diff --git a/docs/adrs/007.webtty.session-client.md b/docs/adrs/007.webtty.session-client.md
index 2a7ae2d..5e76e65 100644
--- a/docs/adrs/007.webtty.session-client.md
+++ b/docs/adrs/007.webtty.session-client.md
@@ -110,4 +110,5 @@ Only the first/oldest connected tab can send input; additional tabs are viewers.
 ## Related Decisions
 
 - [ADR 005 — UI Session Support](005.client.session-support.md): Established session persistence across WS disconnects and the `4001` close code
+- [ADR 010 — Client UX polish](010.client.ux-polish.md): Redesigned the welcome banner and unified status message styling
 
diff --git a/docs/adrs/010.client.ux-polish.md b/docs/adrs/010.client.ux-polish.md
new file mode 100644
index 0000000..8089a94
--- /dev/null
+++ b/docs/adrs/010.client.ux-polish.md
@@ -0,0 +1,103 @@
+# ADR 010: webtty — Client UX polish (banner, status messages)
+
+**SPEC:** [client](../specs/client.md)
+**Status:** Accepted
+**Date:** 2026-03-24
+
+---
+
+## Context
+
+The original welcome banner was ported verbatim from the `ghostty-web` demo — a colorful multi-line box with tutorial-style copy ("You have a real shell session with full PTY support. Try: ls, cd, top, vim..."). The disconnect messages used ad-hoc inline ANSI codes with inconsistent colors (red for session removal, yellow for server stop).
+
+Three problems:
+
+1. **Banner feels like a demo artifact** — the content is aimed at first-time ghostty-web users, not webtty users. It does not identify the product or give actionable guidance.
+2. **No visual identity** — nothing in the UI surfaces the `webtty` name or how to get help.
+3. **Inconsistent status messages** — each WS event had its own inline color and wording with no shared style.
+
+## Decision
+
+### Welcome banner
+
+A structured box with two content lines separated by a blank line:
+
+```
+╔══════════════════════════════════════════════════════╗
+║                                                      ║
+║ [ webtty ]   Terminal UI in the browser              ║
+║                                                      ║
+║ Run `bunx webtty help` for more information.         ║
+║                                                      ║
+╚══════════════════════════════════════════════════════╝
+```
+
+**Line 1 — identity + slogan:**
+- `[` `]` — dim (ANSI `\x1b[2m`) so they frame without competing
+- `webtty` — bold yellow (`\x1b[1;33m`), the only high-contrast element in the banner
+- slogan `Terminal UI in the browser` — dim, recedes behind the name
+
+**Line 2 — help:**
+- `Run` and `for more information.` — dim plain
+- `` `bunx webtty help` `` — foreground italic (`\x1b[3m`), the actionable part
+
+**Border:** bright cyan (`\x1b[1;36m`) double-line box.
+
+**Package runner detection:** `process.execPath.includes('bun')` at server startup — shows `bunx` under Bun, `npx` under Node.
+
+The banner is shown only on first connect (when `session.pty` is `null`) and written into `session.scrollback` so it appears on replay. Unchanged from ADR 007.
+
+### Status messages
+
+All WS lifecycle events that write to the terminal share a single helper:
+
+```
+[ webtty ] <message>
+```
+
+- `[ webtty ]` — dim brackets, bold yellow name (same identity as the banner)
+- Message text — dim italic (`\x1b[2m\x1b[3m`)
+
+| Close code | Message | Action |
+|------------|---------|--------|
+| `4001` | `Session removed.` | `window.close()` after 500ms |
+| `1001` | `Server stopped.` | `window.close()` after 500ms |
+| other | `Connection lost. Reconnecting in 2s...` | reconnect after 2s |
+| `onerror` | `WebSocket error.` | — |
+
+### `onopen` / `onerror` / `console` policy
+
+- `ws.onopen` — no terminal message, no `console.log`. The shell prompt appearing is self-evident.
+- `ws.onerror` — `term.write(msg(...))` only. No `console.error`.
+- `ws.onclose` — `term.write(msg(...))` only. No `console.log`.
+
+No user-facing event writes to both `term.write` and `console` — terminal output is the single source of truth for the user.
+
+## Considered Options
+
+**Option A: No banner (like SSH / macOS Terminal)**
+
+Rejected — webtty is a web app with a CLI. First-time users need to know where to get help. A minimal banner with the app name and a single help hint is enough.
+
+**Option B: Keep the ghostty-web demo banner**
+
+Rejected — tutorial copy ("Try: ls, cd, top, vim") is condescending for users who know what a terminal is. The product name and help command are more useful.
+
+**Option C: Session ID in the banner**
+
+Rejected — the session ID is already in the browser tab title (`webtty — <id>`). Repeating it in the terminal adds noise.
+
+**Option D: Per-event colors for status messages (red for errors, yellow for warnings)**
+
+Rejected — color-coded severity for these three events adds visual noise with little signal gain. The `[ webtty ]` prefix already distinguishes these messages from shell output. Consistent dim italic is quieter and more readable.
+
+## Consequences
+
+- The banner surfaces the product name and a single actionable help command — no tutorial noise.
+- All status messages share the same `[ webtty ]` identity pattern — consistent with the banner.
+- The package runner (`bunx` vs `npx`) is detected at server startup — correct for the user's environment without configuration.
+- `onerror` events now surface in the terminal, previously they were silent to the user (console only).
+
+## Related Decisions
+
+- [ADR 007 — Session client](007.webtty.session-client.md): established banner placement (first connect only), scrollback inclusion, and WS close code semantics
diff --git a/docs/adrs/011.cli.default-and-help.md b/docs/adrs/011.cli.default-and-help.md
new file mode 100644
index 0000000..d29e6b4
--- /dev/null
+++ b/docs/adrs/011.cli.default-and-help.md
@@ -0,0 +1,78 @@
+# ADR 011: CLI — `webtty` (no-arg entry point) and `webtty help`
+
+**SPEC:** [cli](../specs/cli.md)
+**Status:** Proposed
+**Date:** 2026-03-24
+
+---
+
+## Context
+
+Two CLI entry points are missing that users will naturally reach for:
+
+1. **`webtty`** (no arguments) — the most obvious invocation. Currently falls through to Commander's default "display help" behaviour, which is surprising: a user running `npx webtty` for the first time expects something to happen, not a help page.
+
+2. **`webtty help`** — the banner in every terminal session tells users to run `` `bunx webtty help` `` for more information. That command currently fails with "unknown command". The banner promises something that doesn't exist.
+
+## Decision
+
+### `webtty` (no args)
+
+Equivalent to `webtty run main`:
+
+1. Start the server if not already running (same logic as `webtty run`)
+2. Create or reuse the `main` session
+3. Open the session URL in the default browser
+
+This is the "just works" entry point — the one you'd put in a README quickstart:
+
+```sh
+npx webtty
+```
+
+**Why `main` and not a generated ID?** `main` is already the default session created by `GET /`. It is a stable, predictable name. Users who open a second terminal can run `webtty run` with an explicit ID without interfering with `main`.
+
+**`NODE_ENV=test` guard:** same as `openBrowser` — suppressed in test environments to avoid spawning real browser tabs during `bun test`.
+
+### `webtty help`
+
+An explicit alias for `--help` — prints the same Commander-generated help output:
+
+```
+Usage: webtty [options] [command]
+
+Web TTY — run terminal sessions in a browser tab
+...
+```
+
+This makes the banner's call-to-action (`Run \`bunx webtty help\` for more information.`) functional. It does not replace `--help`; both work.
+
+## Considered Options
+
+**Option A: `webtty` opens a new session with a generated ID (not `main`)**
+
+- **Pros**: Each invocation is a fresh session, no risk of reusing a stale session.
+- **Cons**: Multiple invocations accumulate zombie sessions. `main` is predictable and idiomatic — consistent with the server's own default redirect behaviour (`GET /` → `main`).
+
+**Option B: `webtty` only starts the server, no browser open**
+
+- **Pros**: Safer, no side effects beyond the server process.
+- **Cons**: Requires a second command to actually open a terminal. Defeats the purpose of a frictionless entry point.
+
+**Option C: `webtty help` renders a rich custom help page**
+
+- **Pros**: More control over formatting.
+- **Cons**: Maintenance burden — Commander already generates good help output and keeps it in sync with registered commands automatically.
+
+## Consequences
+
+- `npx webtty` / `bunx webtty` becomes the canonical quickstart — one command to go from zero to a browser terminal.
+- The banner's `Run \`bunx webtty help\`` call-to-action becomes functional.
+- `webtty run main` remains the explicit equivalent — no behaviour change for existing users.
+- The no-arg path reuses all existing `run` logic — minimal new code.
+
+## Related Decisions
+
+- [ADR 002 — CLI start/stop](002.cli.start-stop.md): established `startServer` and `isServerRunning` used by the no-arg path
+- [ADR 006 — CLI session management](006.cli.session-management.md): established `webtty run` which the no-arg path delegates to
+- [ADR 010 — Client UX polish](010.client.ux-polish.md): the banner that references `webtty help`
diff --git a/docs/specs/cli.md b/docs/specs/cli.md
index ae35c86..6fd8854 100644
--- a/docs/specs/cli.md
+++ b/docs/specs/cli.md
@@ -38,5 +38,5 @@ The CLI communicates with the server exclusively over HTTP to localhost — no U
 | Server lifecycle | `webtty start` / `stop` — fork, detect, and terminate the server over HTTP | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
 | Session management | `webtty run` / `ls` / `rm` / `rename` — create, list, remove, and rename sessions via the REST API | [ADR 006](../adrs/006.cli.session-management.md) | ✅ |
 | Server restart | `webtty restart` — stop then start | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
-| No-arg entry point | `webtty` — start server + open `main` session in browser | — | ⬜ |
-| Help command | `webtty help` — alias for `--help` | — | ⬜ |
+| No-arg entry point | `webtty` — start server + open `main` session in browser | [ADR 011](../adrs/011.cli.default-and-help.md) | ⬜ |
+| Help command | `webtty help` — alias for `--help` | [ADR 011](../adrs/011.cli.default-and-help.md) | ⬜ |
diff --git a/docs/specs/client.md b/docs/specs/client.md
index 92dbb70..4ae5aaf 100644
--- a/docs/specs/client.md
+++ b/docs/specs/client.md
@@ -1,7 +1,7 @@
 # SPEC: Client
 
 **Author:** jesse23
-**Last Updated:** 2026-03-23
+**Last Updated:** 2026-03-24
 
 ---
 
@@ -15,6 +15,53 @@ The client has no build step in the initial slices — plain HTML + `<script typ
 
 **Why no framework (React/Vue) yet?** The session manager is simple enough (a table + buttons) that a framework adds more complexity than it removes. Revisit when the client grows.
 
+## Page
+
+`GET /s/:id` returns a full-viewport HTML page. It:
+
+- Initialises a `ghostty-web` `Terminal` with config values (cols, rows, fontSize, fontFamily, cursorBlink, scrollback, theme) injected server-side at render time
+- Connects to `ws://<host>/ws/:id?cols=<cols>&rows=<rows>` over WebSocket
+- Fits the terminal to the viewport and observes resize events via `FitAddon`
+- Sends a `{ type: 'resize', cols, rows }` JSON message on open and on every terminal resize
+- Forwards all keystrokes to the PTY via `term.onData`
+
+## Welcome Banner
+
+On the first WebSocket connection to a session (no existing PTY), the server writes a banner to the terminal:
+
+```
+╔══════════════════════════════════════════════════════╗
+║                                                      ║
+║ [ webtty ]   Terminal UI in the browser              ║
+║                                                      ║
+║ Run `bunx webtty help` for more information.         ║
+║                                                      ║
+╚══════════════════════════════════════════════════════╝
+```
+
+- `[ webtty ]` — dim brackets, bold yellow name
+- Slogan — dim
+- Help command — dim italic surroundings, foreground italic for the command itself
+- Package runner (`bunx` or `npx`) is detected from the server's runtime at startup
+
+## Status Messages
+
+All status messages written to the terminal share a consistent style:
+
+```
+[ webtty ] <message>
+```
+
+- `[ webtty ]` — dim brackets, bold yellow name (matches banner)
+- Message — dim italic
+
+| Event | Message | Behavior |
+|-------|---------|----------|
+| WS close `4001` (session deleted / shell exited) | `Session removed.` | `window.close()` after 500ms |
+| WS close `1001` (server stopped) | `Server stopped.` | `window.close()` after 500ms |
+| WS close (unexpected) | `Connection lost. Reconnecting in 2s...` | Reconnect after 2s |
+| WS error | `WebSocket error.` | — |
+
 ## Behavior Notes
 
 ### Tab close on session end
@@ -24,7 +71,7 @@ When a session ends (shell exits → WS close code `4001`) or the server stops (
 **Browser restriction**: `window.close()` is only permitted on tabs that were opened programmatically via `window.open()`, or duplicated from such a tab. Tabs opened by the OS (`open`/`xdg-open`) or by the user typing a URL directly are treated as unowned — `window.close()` is silently ignored. In practice:
 
 - Tabs opened by `webtty run` and tabs duplicated from them → close automatically ✅
-- Tabs opened by manually navigating to the server URL → display "Session removed." or "Server stopped." but remain open ⚠️
+- Tabs opened by manually navigating to the server URL → display the status message but remain open ⚠️
 
 This is a browser-enforced security restriction with no JS workaround.
 
@@ -33,6 +80,6 @@ This is a browser-enforced security restriction with no JS workaround.
 | Feature | Description | ADR | Done? |
 |---------|-------------|-----|-------|
 | Terminal view | Full-viewport terminal using `ghostty-web`, auto-fit, reconnect on disconnect | [001](../adrs/001.webtty.bootstrap.md) | ✅ |
-| Session support | `<url>/s/:id` opens a named session; `<url>` redirects to the last-used session or creates a new one with a generated readable name (e.g. `main`) if none exists | [ADR 005](../adrs/005.client.session-support.md) | ✅ |
-| Session manager | List sessions, open in new tab, create new session, kill session | — | ⬜ |
-| Server control | Restart and stop server from the client (calls server control API) | — | ⬜ |
+| Session support | `<url>/s/:id` opens a named session; `<url>` redirects to the last-used session or creates `main` if none exists | [ADR 005](../adrs/005.client.session-support.md) | ✅ |
+| Welcome banner | Shown on first connection to a session; identifies app, slogan, and help command | [ADR 010](../adrs/010.client.ux-polish.md) | ✅ |
+| Status messages | Consistent `[ webtty ]`-prefixed dim italic messages for disconnect, error, and server stop events | [ADR 010](../adrs/010.client.ux-polish.md) | ✅ |

From a063f6ee0194cd5c7955cd4dd79d721ab1c2f8d4 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 23:08:47 -0400
Subject: [PATCH 27/29] feat: update session title format and add favicon to
 HTML output

---
 package.json              | 3 +--
 src/server/client.test.ts | 2 +-
 src/server/client.ts      | 3 ++-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/package.json b/package.json
index 166859f..397e485 100644
--- a/package.json
+++ b/package.json
@@ -3,8 +3,7 @@
   "version": "0.0.0-development",
   "description": "Web TTY for running CLI/TUI applications in a browser tab, across platforms",
   "bin": {
-    "webtty": "dist/cli/index.js",
-    "wtty": "dist/cli/index.js"
+    "webtty": "dist/cli/index.js"
   },
   "files": [
     "dist"
diff --git a/src/server/client.test.ts b/src/server/client.test.ts
index 6a5c2e5..0e8d37d 100644
--- a/src/server/client.test.ts
+++ b/src/server/client.test.ts
@@ -12,7 +12,7 @@ describe('clientShell', () => {
 
   test('injects session id into title', () => {
     const html = render('my-session', DEFAULT_CONFIG);
-    expect(html).toContain('webtty — my-session');
+    expect(html).toContain('my-session | webtty');
   });
 
   test('injects session id as JS string literal', () => {
diff --git a/src/server/client.ts b/src/server/client.ts
index 671fdd3..c6fc6c0 100644
--- a/src/server/client.ts
+++ b/src/server/client.ts
@@ -8,7 +8,8 @@ export function render(sessionId: string, config: Config): string {
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>webtty — ${sessionId}</title>
+    <title>${sessionId} | webtty</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>>_</text></svg>">
     <style>
       * { margin: 0; padding: 0; box-sizing: border-box; }
 

From fd77c9e42b4bb55c6d1907a379cb5a692c6b27f3 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 23:15:39 -0400
Subject: [PATCH 28/29] feat: update favicon SVG for improved visual appearance

---
 src/server/client.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/server/client.ts b/src/server/client.ts
index c6fc6c0..199ca0d 100644
--- a/src/server/client.ts
+++ b/src/server/client.ts
@@ -9,7 +9,7 @@ export function render(sessionId: string, config: Config): string {
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>${sessionId} | webtty</title>
-    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>>_</text></svg>">
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect x='5' y='5' width='90' height='90' rx='18' fill='white'/><text x='8' y='73' font-size='58' font-family='monospace' font-weight='bold' fill='%23161b22'>>_</text></svg>">
     <style>
       * { margin: 0; padding: 0; box-sizing: border-box; }
 

From 72d07dd9ebeb96317d782384a697654adb04cae6 Mon Sep 17 00:00:00 2001
From: jesse23 <wenjia.peng@siemens.com>
Date: Mon, 23 Mar 2026 23:30:17 -0400
Subject: [PATCH 29/29] fix: address copilot review comments

---
 README.md                                 |  10 +++++++-
 assets/icon.svg                           |   4 +++
 assets/social-preview.png                 | Bin 0 -> 16648 bytes
 docs/adrs/009.webtty.config-hot-reload.md |   2 +-
 docs/specs/config.md                      |   3 ++-
 src/cli/http.test.ts                      |  29 +++-------------------
 src/config.test.ts                        |   7 +++---
 src/config.ts                             |   1 +
 src/server/index.ts                       |   2 +-
 src/server/routes.ts                      |   3 +--
 src/server/websocket.ts                   |   1 -
 11 files changed, 26 insertions(+), 36 deletions(-)
 create mode 100644 assets/icon.svg
 create mode 100644 assets/social-preview.png

diff --git a/README.md b/README.md
index f7203c2..c087570 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,14 @@
+<img src="assets/social-preview.png" width="600">
+
 # webtty
 
-A web TTY for running CLI/TUI applications in a browser tab, across platforms.
+Terminal UI in the browser. Run CLI/TUI applications in a browser tab, across platforms.
+
+```sh
+npx webtty run        # start server + open a terminal in the browser
+npx webtty ls         # list sessions
+npx webtty help       # show all commands
+```
 
 ## Debugging
 
diff --git a/assets/icon.svg b/assets/icon.svg
new file mode 100644
index 0000000..0bc6d12
--- /dev/null
+++ b/assets/icon.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect x="5" y="5" width="90" height="90" rx="18" fill="white"/>
+  <text x="8" y="73" font-size="58" font-family="monospace" font-weight="bold" fill="#161b22">&gt;_</text>
+</svg>
diff --git a/assets/social-preview.png b/assets/social-preview.png
new file mode 100644
index 0000000000000000000000000000000000000000..a091c815afd44542313f9a5b9a91c01bef206594
GIT binary patch
literal 16648
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%0DWtHfpOqENkJo@vr7ha~G9;
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
U-APx#J|XpoS`Ui<c=6`H0B&A%i2wiq

literal 0
HcmV?d00001

diff --git a/docs/adrs/009.webtty.config-hot-reload.md b/docs/adrs/009.webtty.config-hot-reload.md
index 314fa07..992c4be 100644
--- a/docs/adrs/009.webtty.config-hot-reload.md
+++ b/docs/adrs/009.webtty.config-hot-reload.md
@@ -40,7 +40,7 @@ A full hot-reload (e.g. `fs.watch` triggering a live update mid-session) is impr
 
 ## Consequences
 
-- Editing `~/.config/webtty/config.jsonc` and reloading the browser tab picks up all appearance changes immediately — no server restart needed.
+- Editing `~/.config/webtty/config.json` and reloading the browser tab picks up all appearance changes immediately — no server restart needed.
 - `shell`, `term`, `colorTerm`, and `scrollback` are re-read when a new PTY is spawned — no server restart needed for shell changes either.
 - `port` / `host` changes still require a server restart (expected; the socket is already bound).
 - `loadConfig()` adds one `fs.readFileSync` + JSON parse per tab load and per new PTY spawn — negligible cost.
diff --git a/docs/specs/config.md b/docs/specs/config.md
index 9d7fb5d..50f0574 100644
--- a/docs/specs/config.md
+++ b/docs/specs/config.md
@@ -106,13 +106,14 @@ All keys are optional — omit any key to use the default value.
 | `host` | string | `"127.0.0.1"` | Bind address; use `"0.0.0.0"` for remote access |
 | `shell` | string | `$SHELL` / `%COMSPEC%` | Shell for new sessions |
 | `term` | string | `$TERM` | `$TERM` env var passed to the shell |
+| `colorTerm` | string | `"truecolor"` | `$COLORTERM` env var passed to the shell |
 | `scrollback` | number | `262144` | PTY history buffer in bytes; used for server-side replay on reload/reconnect |
 | `cols` | number | `80` | Initial terminal width in columns |
 | `rows` | number | `24` | Initial terminal height in rows |
 | `cursorBlink` | boolean | `true` | Whether the cursor blinks |
 | `fontSize` | number | `13` | Font size in px |
 | `fontFamily` | string | `"Menlo, Consolas, 'DejaVu Sans Mono', monospace"` | CSS font-family stack |
-| `theme` | object | Dracula | Terminal color palette — see theme keys below |
+| `theme` | object | Campbell | Terminal color palette — see theme keys below |
 
 ### Theme keys
 
diff --git a/src/cli/http.test.ts b/src/cli/http.test.ts
index d1150b3..c206969 100644
--- a/src/cli/http.test.ts
+++ b/src/cli/http.test.ts
@@ -76,7 +76,7 @@ describe('stopServer', () => {
 
 describe('startServer', () => {
   test('exits with error when server entry not found', async () => {
-    spyOn(fs, 'existsSync').mockReturnValue(false);
+    const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(false);
     const exitSpy = spyOn(process, 'exit').mockImplementation((() => {}) as () => never);
     const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
 
@@ -86,13 +86,13 @@ describe('startServer', () => {
     expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('server entry not found'));
     expect(exitSpy).toHaveBeenCalledWith(1);
 
+    existsSpy.mockRestore();
     exitSpy.mockRestore();
     errorSpy.mockRestore();
-    (fs.existsSync as ReturnType<typeof spyOn>).mockRestore();
   });
 
   test('spawns server and resolves when it becomes reachable', async () => {
-    spyOn(fs, 'existsSync').mockReturnValue(true);
+    const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(true);
     const fakeChild = { unref: mock(() => {}) };
     const spawnMock = mock(() => fakeChild);
 
@@ -109,28 +109,7 @@ describe('startServer', () => {
     expect(calls).toBeGreaterThanOrEqual(3);
     expect(fakeChild.unref).toHaveBeenCalled();
 
-    (fs.existsSync as ReturnType<typeof spyOn>).mockRestore();
-  });
-
-  test('exits with error when server does not start within timeout', async () => {
-    spyOn(fs, 'existsSync').mockReturnValue(true);
-    const spawnMock = mock(() => ({ unref: () => {} }));
-    const exitSpy = spyOn(process, 'exit').mockImplementation((() => {}) as () => never);
-    const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
-
-    globalThis.fetch = mock(async () => {
-      throw new Error('not yet');
-    }) as unknown as typeof fetch;
-
-    const { startServer } = await import('./http');
-    await startServer(100, spawnMock as never);
-
-    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('server did not start in time'));
-    expect(exitSpy).toHaveBeenCalledWith(1);
-
-    (fs.existsSync as ReturnType<typeof spyOn>).mockRestore();
-    exitSpy.mockRestore();
-    errorSpy.mockRestore();
+    existsSpy.mockRestore();
   });
 
   test('exits with error when server does not start within timeout', async () => {
diff --git a/src/config.test.ts b/src/config.test.ts
index 9df5bd0..c8aad44 100644
--- a/src/config.test.ts
+++ b/src/config.test.ts
@@ -6,18 +6,17 @@ import { DEFAULT_CONFIG, DEFAULT_THEME, loadConfig, saveConfig } from './config'
 
 let tmpDir: string;
 let configPath: string;
-
-const origHome = os.homedir();
+let homedirSpy: ReturnType<typeof spyOn>;
 
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webtty-config-test-'));
   configPath = path.join(tmpDir, '.config', 'webtty', 'config.json');
-  spyOn(os, 'homedir').mockReturnValue(tmpDir);
+  homedirSpy = spyOn(os, 'homedir').mockReturnValue(tmpDir);
 });
 
 afterEach(() => {
   fs.rmSync(tmpDir, { recursive: true, force: true });
-  spyOn(os, 'homedir').mockReturnValue(origHome);
+  homedirSpy.mockRestore();
 });
 
 describe('saveConfig', () => {
diff --git a/src/config.ts b/src/config.ts
index 9e1f426..aa1bb85 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -120,6 +120,7 @@ export function loadConfig(): Config {
     ...(typeof p.host === 'string' && { host: p.host }),
     ...(typeof p.shell === 'string' && { shell: p.shell }),
     ...(typeof p.term === 'string' && { term: p.term }),
+    ...(typeof p.colorTerm === 'string' && { colorTerm: p.colorTerm }),
     ...(typeof p.scrollback === 'number' && { scrollback: p.scrollback }),
     ...(typeof p.cols === 'number' && { cols: p.cols }),
     ...(typeof p.rows === 'number' && { rows: p.rows }),
diff --git a/src/server/index.ts b/src/server/index.ts
index 863642d..ef10085 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -22,7 +22,7 @@ function shutdown() {
 }
 
 const httpServer = http.createServer((req, res) => {
-  handleRequest(req, res, distPath, wasmPath, config, shutdown);
+  handleRequest(req, res, distPath, wasmPath, shutdown);
 });
 
 const wss = createWebSocketServer(httpServer);
diff --git a/src/server/routes.ts b/src/server/routes.ts
index 316faa0..c47fd39 100644
--- a/src/server/routes.ts
+++ b/src/server/routes.ts
@@ -1,6 +1,6 @@
 import type http from 'node:http';
 import path from 'node:path';
-import { type Config, loadConfig } from '../config';
+import { loadConfig } from '../config';
 import { render } from './client';
 import {
   createSession,
@@ -50,7 +50,6 @@ export async function handleRequest(
   res: http.ServerResponse,
   distPath: string,
   wasmPath: string,
-  config: Config,
   onStop: () => void,
 ): Promise<void> {
   const url = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
diff --git a/src/server/websocket.ts b/src/server/websocket.ts
index aa720b2..f97060b 100644
--- a/src/server/websocket.ts
+++ b/src/server/websocket.ts
@@ -33,7 +33,6 @@ const BOLD = '\x1b[1m';
 const ITALIC = '\x1b[3m';
 const YELLOW = '\x1b[1;33m';
 const CYAN = '\x1b[1;36m';
-const DIM_ITALIC = '\x1b[3m';
 
 const isBun = process.execPath.includes('bun');
 const PKG_RUNNER = isBun ? 'bunx' : 'npx';