ai-or-die 0.1.24 → 0.1.26

package/.github/workflows/ci.yml

@@ -132,6 +132,7 @@ jobs:
   test-browser-visual:
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
     steps:

package/docs/README.md

@@ -16,6 +16,9 @@ Central documentation for the ai-or-die project -- a Node.js web application tha
 - [Authentication](specs/authentication.md)
 - [Client Application](specs/client-app.md)
 - [Usage Analytics](specs/usage-analytics.md)
+- [Image Paste](specs/image-paste.md)
+- [File Browser](specs/file-browser.md)
+- [E2E Testing](specs/e2e-testing.md)
 
 ## Architecture Decision Records
 
@@ -24,6 +27,11 @@ Central documentation for the ai-or-die project -- a Node.js web application tha
 - [ADR-0002: DevTunnels over ngrok](adrs/0002-devtunnels-over-ngrok.md)
 - [ADR-0003: Multi-Tool Architecture](adrs/0003-multi-tool-architecture.md)
 - [ADR-0004: Cross-Platform Support](adrs/0004-cross-platform-support.md)
+- [ADR-0005: Single Binary Distribution](adrs/0005-single-binary-distribution.md)
+- [ADR-0006: Test-Driven Bug Fixes](adrs/0006-test-driven-bug-fixes.md)
+- [ADR-0007: Design Token System](adrs/0007-design-token-system.md)
+- [ADR-0008: E2E Parallelization](adrs/0008-e2e-parallelization.md)
+- [ADR-0008: File Browser Architecture](adrs/0008-file-browser-architecture.md)
 
 ## Agent Instructions
 
@@ -31,7 +39,13 @@ Central documentation for the ai-or-die project -- a Node.js web application tha
 - [Research & Web](agent-instructions/01-research-and-web.md)
 - [Testing & Validation](agent-instructions/02-testing-and-validation.md)
 - [Tooling & Pipelines](agent-instructions/03-tooling-and-pipelines.md)
+- [Handoff Protocol](agent-instructions/04-handoff-protocol.md)
+- [Defensive Coding](agent-instructions/05-defensive-coding.md)
+- [CI-First Testing](agent-instructions/06-ci-first-testing.md)
+- [Documentation Hygiene](agent-instructions/07-docs-hygiene.md)
+- [Multi-Agent Consultation](agent-instructions/08-multi-agent-consultation.md)
 
 ## History
 
 - [Changelog](history/README.md)
+- [File Browser Bugs](history/file-browser-bugs.md)

package/docs/history/file-browser-bugs.md

@@ -0,0 +1,111 @@
+# File Browser: Bugs Found During CI (2026-02-07)
+
+9 bugs caught during file browser implementation — 4 by E2E tests on GitHub runners, 3 by UX reviewer subagent, 2 by architect reviewer subagent. All were real code bugs, not test bugs.
+
+---
+
+## 1. Panel z-index below terminal overlay
+
+**What Happened:** E2E tests on CI could not click file browser panel items. Playwright reported the terminal overlay (`#overlay`, z-index 5000) was intercepting pointer events.
+
+**Root Cause:** The file browser panel used `z-index: var(--z-sticky)` (1100), which is below the terminal overlay at 5000. The overlay briefly appears during connection setup.
+
+**Fix:** Set panel z-index to 5001 (above overlay).
+
+**Watch For:** Any new panel or modal must check its z-index against the terminal overlay (5000) and the existing z-index scale in `tokens.css`.
+
+---
+
+## 2. Panel missing tabindex for keyboard focus
+
+**What Happened:** E2E Escape key test failed — pressing Escape did not close the panel.
+
+**Root Cause:** The panel `<div>` had no `tabindex` attribute. Without it, `element.focus()` has no effect and `keydown` events never fire on the element.
+
+**Fix:** Added `tabindex="-1"` to the panel div.
+
+**Watch For:** Any container that needs to receive keyboard focus must have `tabindex="-1"`. This includes modals, panels, dialogs, and any div with a `keydown` listener.
+
+---
+
+## 3. No document-level Escape fallback
+
+**What Happened:** Even with tabindex fix, Escape was unreliable when focus was elsewhere (e.g., terminal, body).
+
+**Root Cause:** The panel's `keydown` listener only fires when the panel or a child has focus. If the user clicks elsewhere, Escape goes to the focused element, not the panel.
+
+**Fix:** Added a `document.addEventListener('keydown', ...)` fallback that checks `if (panel._open && e.key === 'Escape')`.
+
+**Watch For:** Keyboard shortcuts that should work globally need document-level listeners, not just component-level ones. Panel-level handlers are for internal keyboard navigation; document-level handlers are for global shortcuts.
+
+---
+
+## 4. Status bar "Saving..." never visible
+
+**What Happened:** UX reviewer found that during saves, the status bar showed "Editing" instead of "Saving...".
+
+**Root Cause:** The ternary in `_updateCursorPosition` was `this._dirty ? 'Editing' : (this._saving ? 'Saving...' : 'Ready')`. Since `_dirty` is true during the save (cleared on success), the `_saving` branch was never reached.
+
+**Fix:** Swapped to `this._saving ? 'Saving...' : (this._dirty ? 'Editing' : 'Ready')`.
+
+**Watch For:** When multiple boolean flags control display state, check the evaluation order. The most important/transient state should be checked first.
+
+---
+
+## 5. Escape double-fire between panel and Ace Editor
+
+**What Happened:** UX reviewer found that pressing Escape while Ace's search bar was open would close both the search bar AND the editor simultaneously.
+
+**Root Cause:** Ace's Escape command closes its search bar, but the DOM event still propagates to the panel's `keydown` handler, which then calls `editorPanel.close()`.
+
+**Fix:** Panel-level handler now returns early when `_currentView === 'editor'` (delegates to Ace). Document-level fallback checks for visible `.ace_search` before closing.
+
+**Watch For:** When embedding a third-party editor (Ace, Monaco, CodeMirror), its keyboard handling operates independently of DOM event propagation. The outer container must check whether the editor consumed the event before acting.
+
+---
+
+## 6. Screen reader announcements defined but never called
+
+**What Happened:** UX reviewer found `FileEditorPanel._announceToScreenReader()` was defined at line 523 but never invoked anywhere in the file.
+
+**Root Cause:** The method was written but calls were not added at the key state transitions (save start, save success, save failure, conflict detected).
+
+**Fix:** Added `_announceToScreenReader()` calls at 4 points: save start ("Saving"), save success ("File saved"), save failure ("Save failed"), conflict ("File was modified externally").
+
+**Watch For:** Any method that updates visual status should also announce to screen readers. Add a grep check: every status-changing method should have a corresponding `_announceToScreenReader` call.
+
+---
+
+## 7. CSS/JS class name mismatch (30+ selectors)
+
+**What Happened:** Architect reviewer found the entire panel rendered unstyled because CSS and JS used different naming conventions.
+
+**Root Cause:** `file-browser.css` was written by one subagent using `file-browser-*` prefix, while `file-browser.js` was written by another subagent using `fb-*` prefix. Neither checked the other's naming convention.
+
+**Fix:** Rewrote CSS to use `fb-*` prefix matching the JS, and added ~30 missing selectors.
+
+**Watch For:** When CSS and JS are written by different agents (or in parallel), establish the naming convention upfront. Add a pre-merge check: grep all `className` assignments in JS and verify each has a corresponding CSS selector.
+
+---
+
+## 8. _showConflictDialog silently drops parameter
+
+**What Happened:** Architect reviewer found that the 409 conflict response data (containing `currentHash`) was passed to `_showConflictDialog(d)` but the method signature was `function ()` with no parameter.
+
+**Root Cause:** The function signature omitted the parameter. JavaScript doesn't error on extra arguments, so the data was silently discarded.
+
+**Fix:** Added `conflictData` parameter and used `conflictData.currentHash` to store the server's hash.
+
+**Watch For:** When a function is called with arguments, verify the callee's signature accepts them. This is easy to miss in vanilla JS without TypeScript.
+
+---
+
+## 9. Search bar CSS display:none vs JS style.display conflict
+
+**What Happened:** E2E search filter test failed — the search input was "hidden" despite JS toggling its display.
+
+**Root Cause:** CSS had `.fb-search-bar { display: none; }` and `.fb-search-bar.visible { display: block; }`. But JS was using `element.style.display = ''` (empty string) to show it. When inline `style.display` is empty, the CSS `display: none` rule takes precedence, so the element stays hidden.
+
+**Fix:** Changed JS to use `classList.add('visible')` / `classList.remove('visible')` instead of inline style.
+
+**Watch For:** Never mix CSS class-based visibility (`display: none` in stylesheet) with inline `style.display` toggling. Pick one mechanism. CSS classes are preferred because they keep styling in CSS.

package/docs/specs/client-app.md

@@ -13,7 +13,7 @@ The frontend is a single-page application served from `src/public/`. It runs ent
 | xterm-addon-web-links | 0.9.0 | unpkg CDN | Clickable URLs in terminal output |
 | xterm-addon-unicode11 | 0.6.0 | unpkg CDN | Unicode 11 character width support for Nerd Font / powerline glyphs |
 | JetBrains Mono | -- | Google Fonts | Monospace font for terminal (fallback) |
-| MesloLGS Nerd Font | -- | jsDelivr CDN | Primary terminal font with Nerd Font glyphs |
+| MesloLGS Nerd Font | v3.3.0 | Self-hosted WOFF2 + jsDelivr CDN fallback | Primary terminal font with Nerd Font glyphs |
 | Inter | -- | Google Fonts | UI font for headers, tabs, controls |
 | clipboard-handler.js | -- | Local | Keyboard shortcuts (Ctrl+C/V) and clipboard utility functions |
 
@@ -119,7 +119,7 @@ The main application controller. Instantiated once on page load.
     cursor: '#f0f6fc',
     // Full 16-color ANSI palette configured
   },
-  fontFamily: "reads from CSS --font-mono token; defaults to 'MesloLGS Nerd Font', 'JetBrains Mono', monospace",
+  fontFamily: "reads from CSS --font-mono token; defaults to 'MesloLGS Nerd Font', 'MesloLGS NF', 'JetBrains Mono', monospace",
   fontSize: 14,          // 13 on mobile
   lineHeight: 1.2,
   scrollback: 10000,
@@ -129,6 +129,16 @@ The main application controller. Instantiated once on page load.
 
 The terminal auto-resizes via `FitAddon` triggered by a `ResizeObserver` on the terminal container, debounced to prevent excessive resize messages.
 
+### Font Loading Strategy
+
+Font declarations live in `src/public/fonts.css` with a three-tier source strategy:
+
+1. **`local()`** — user's installed font (supports both Nerd Fonts v2 "MesloLGS NF" and v3 "MesloLGS Nerd Font" naming)
+2. **Self-hosted WOFF2** — `src/public/fonts/MesloLGSNerdFont-*.woff2` (4 variants: Regular, Bold, Italic, BoldItalic)
+3. **CDN fallback** — jsDelivr CDN pinned to `mshaugh/nerdfont-webfonts@v3.3.0`
+
+The Regular weight is preloaded via `<link rel="preload">` for fast availability. After all fonts settle (`document.fonts.ready`), the terminal is refreshed to re-render with the correct glyphs.
+
 ### Folder Browser
 
 A modal dialog for selecting working directories:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {

package/scripts/build-sea.js

@@ -56,14 +56,9 @@ async function bundle() {
 function collectAssets() {
   const assets = {};
 
-  // Static web assets
+  // Static web assets (recursive to include fonts/ and components/ subdirectories)
   const publicDir = path.join(ROOT, 'src', 'public');
-  for (const file of fs.readdirSync(publicDir)) {
-    const fullPath = path.join(publicDir, file);
-    if (fs.statSync(fullPath).isFile()) {
-      assets[`public/${file}`] = fullPath;
-    }
-  }
+  collectFilesRecursive(publicDir, 'public', assets);
 
   // Platform-specific native addon files
   const ptyPkgName = `node-pty-${PLATFORM}-${ARCH}`;

package/src/public/app.js

@@ -364,14 +364,13 @@ class ClaudeCodeWebInterface {
         this.terminal.open(document.getElementById('terminal'));
         this.fitTerminal();
 
-        // Re-render terminal when Nerd Font finishes loading (lazy-loaded via media="print")
-        if (document.fonts && document.fonts.load) {
-            document.fonts.load('14px MesloLGS Nerd Font').then(() => {
+        // Re-render terminal when fonts finish loading
+        if (document.fonts) {
+            document.fonts.ready.then(() => {
+                const loaded = document.fonts.check('14px "MesloLGS Nerd Font"');
+                console.log(loaded ? '[Font] MesloLGS Nerd Font loaded' : '[Font] Using fallback font');
                 this.terminal.refresh(0, this.terminal.rows - 1);
                 this.fitTerminal();
-            }).catch(() => {
-                // Font not available — still refresh in case fallback font loaded late
-                this.terminal.refresh(0, this.terminal.rows - 1);
             });
         }
 

package/src/public/fonts.css

@@ -0,0 +1,58 @@
+/* ============================================================
+   Nerd Font Loading — MesloLGS Nerd Font
+   Three-tier source: local install > self-hosted WOFF2 > CDN WOFF2
+   CDN pinned to v3.3.0 for reproducibility.
+   ============================================================ */
+
+@font-face {
+  font-family: 'MesloLGS Nerd Font';
+  font-style: normal;
+  font-weight: 400;
+  font-stretch: normal;
+  font-display: swap;
+  src: local('MesloLGS Nerd Font'),
+       local('MesloLGS NF'),
+       local('MesloLGSNerdFont-Regular'),
+       local('MesloLGS Nerd Font Regular'),
+       url('fonts/MesloLGSNerdFont-Regular.woff2') format('woff2'),
+       url('https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/MesloLGSNerdFont-Regular.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'MesloLGS Nerd Font';
+  font-style: italic;
+  font-weight: 400;
+  font-stretch: normal;
+  font-display: swap;
+  src: local('MesloLGS Nerd Font Italic'),
+       local('MesloLGS NF Italic'),
+       local('MesloLGSNerdFont-Italic'),
+       url('fonts/MesloLGSNerdFont-Italic.woff2') format('woff2'),
+       url('https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/MesloLGSNerdFont-Italic.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'MesloLGS Nerd Font';
+  font-style: normal;
+  font-weight: 700;
+  font-stretch: normal;
+  font-display: swap;
+  src: local('MesloLGS Nerd Font Bold'),
+       local('MesloLGS NF Bold'),
+       local('MesloLGSNerdFont-Bold'),
+       url('fonts/MesloLGSNerdFont-Bold.woff2') format('woff2'),
+       url('https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/MesloLGSNerdFont-Bold.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'MesloLGS Nerd Font';
+  font-style: italic;
+  font-weight: 700;
+  font-stretch: normal;
+  font-display: swap;
+  src: local('MesloLGS Nerd Font Bold Italic'),
+       local('MesloLGS NF Bold Italic'),
+       local('MesloLGSNerdFont-BoldItalic'),
+       url('fonts/MesloLGSNerdFont-BoldItalic.woff2') format('woff2'),
+       url('https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@v3.3.0/build/fonts/MesloLGSNerdFont-BoldItalic.woff2') format('woff2');
+}

package/src/public/index.html

@@ -39,6 +39,8 @@
         } catch (_) { /* ignore */ }
       })();
     </script>
+    <link rel="preload" href="fonts/MesloLGSNerdFont-Regular.woff2" as="font" type="font/woff2" crossorigin>
+    <link rel="stylesheet" href="fonts.css">
     <link rel="stylesheet" href="tokens.css">
     <link rel="stylesheet" href="base.css">
     <link rel="stylesheet" href="components/tabs.css">
@@ -53,9 +55,8 @@
     <link rel="stylesheet" href="style.css">
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@latest/build/meslo-nerd-font.css" media="print" onload="this.media='all'">
-    <noscript><link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/mshaugh/nerdfont-webfonts@latest/build/meslo-nerd-font.css"></noscript>
     <script src="https://unpkg.com/xterm@5.3.0/lib/xterm.js"></script>
     <script src="https://unpkg.com/xterm-addon-fit@0.8.0/lib/xterm-addon-fit.js"></script>
     <script src="https://unpkg.com/xterm-addon-web-links@0.9.0/lib/xterm-addon-web-links.js"></script>
@@ -236,7 +237,7 @@
                     <div class="setting-group">
                         <label for="fontFamily">Font:</label>
                         <select id="fontFamily">
-                            <option value="'MesloLGS Nerd Font', 'Meslo Nerd Font', monospace">Meslo Nerd Font</option>
+                            <option value="'MesloLGS Nerd Font', 'MesloLGS NF', 'Meslo Nerd Font', monospace">Meslo Nerd Font</option>
                             <option value="'JetBrains Mono', monospace">JetBrains Mono</option>
                             <option value="'Fira Code', monospace">Fira Code</option>
                             <option value="'Cascadia Code', monospace">Cascadia Code</option>

package/src/public/service-worker.js

@@ -1,7 +1,9 @@
-const CACHE_NAME = 'ai-or-die-v3';
+const CACHE_NAME = 'ai-or-die-v4';
 const urlsToCache = [
   '/',
   '/index.html',
+  '/fonts.css',
+  '/fonts/MesloLGSNerdFont-Regular.woff2',
   '/tokens.css',
   '/base.css',
   '/components/tabs.css',

package/src/public/splits.js

@@ -33,7 +33,9 @@ class Split {
         
         // Initialize xterm.js terminal
         this.terminal = new Terminal({
-            fontFamily: this.app?.terminal?.options?.fontFamily || 'JetBrains Mono, monospace',
+            fontFamily: this.app?.terminal?.options?.fontFamily
+                || getComputedStyle(document.documentElement).getPropertyValue('--font-mono').trim()
+                || "'MesloLGS Nerd Font', 'MesloLGS NF', 'JetBrains Mono', monospace",
             fontSize: this.app?.terminal?.options?.fontSize || 14,
             cursorBlink: true,
             convertEol: true,

package/src/public/tokens.css

@@ -50,7 +50,7 @@
 
   /* --- Typography --- */
   --font-sans: 'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
-  --font-mono: 'MesloLGS Nerd Font', 'Meslo Nerd Font', 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
+  --font-mono: 'MesloLGS Nerd Font', 'MesloLGS NF', 'Meslo Nerd Font', 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
 
   --text-xs: 0.6875rem;   /* 11px */
   --text-sm: 0.75rem;     /* 12px */

package/src/server.js

@@ -995,7 +995,8 @@ class ClaudeCodeWebServer {
         '.json': 'application/json',
         '.png': 'image/png',
         '.svg': 'image/svg+xml',
-        '.ico': 'image/x-icon'
+        '.ico': 'image/x-icon',
+        '.woff2': 'font/woff2'
       };
       res.setHeader('Content-Type', mimeTypes[ext] || 'application/octet-stream');
       res.send(data);