bgrun 3.11.0 → 3.12.0

package/README.md

@@ -5,6 +5,7 @@
 **Production-ready process manager with dashboard and programmatic API, designed for running your containers, services, and AI agents.**
 
 [![npm](https://img.shields.io/npm/v/bgrun?color=F7A41D&label=npm&logo=npm)](https://www.npmjs.com/package/bgrun)
+[![CI](https://github.com/Mements/bgr/actions/workflows/ci.yml/badge.svg)](https://github.com/Mements/bgr/actions/workflows/ci.yml)
 [![bun](https://img.shields.io/badge/runtime-bun-F7A41D?logo=bun)](https://bun.sh/)
 [![license](https://img.shields.io/npm/l/bgrun)](./LICENSE)
 
@@ -74,11 +75,16 @@ bgrun.yourdomain.com {
 Features:
 - Real-time process status via SSE (no polling)
 - Start, stop, restart, and delete processes from the UI
-- Live stdout/stderr log viewer with search
+- Live stdout/stderr log viewer with search and virtual scrolling
 - Memory, PID, port, runtime, and guard restarts at a glance
 - Guard toggle per-process (auto-restart on crash)
-- Responsive mobile layout
+- Keyboard shortcuts — `↑/↓` or `j/k` navigate, `Enter` open, `R` restart, `S` stop, `G` guard, `D` delete, `N` new, `?` help
+- Search with debounce, result count badge, and persistence across SSE updates
+- Auto-calibrated virtual scroll for large log files (10K+ lines)
+- Dark / light theme toggle
+- Responsive mobile layout with cards view
 - Collapsible directory groups
+- Right-click context menu on process rows
 
 ---
 

package/dashboard/app/api/events/route.ts

@@ -26,7 +26,12 @@ export async function GET(req: Request) {
                 controller.enqueue(encoder.encode(`data: []\n\n`));
             }
 
-            controller.enqueue(encoder.encode(`: keepalive\n\n`));
+            // Periodic keepalive to prevent proxy/browser timeouts
+            const keepaliveInterval = setInterval(() => {
+                try {
+                    controller.enqueue(encoder.encode(`: keepalive\n\n`));
+                } catch { /* stream closed */ }
+            }, 15_000);
 
             // Then send updates every INTERVAL_MS
             const interval = setInterval(async () => {
@@ -40,7 +45,10 @@ export async function GET(req: Request) {
             }, INTERVAL_MS);
 
             // Store cleanup for when the stream is cancelled
-            (stream as any).__cleanup = () => clearInterval(interval);
+            (stream as any).__cleanup = () => {
+                clearInterval(interval);
+                clearInterval(keepaliveInterval);
+            };
         },
         cancel() {
             if ((stream as any).__cleanup) {

package/dashboard/app/globals.css

@@ -675,6 +675,22 @@ body::after {
     opacity: 0;
 }
 
+.search-count {
+    position: absolute;
+    right: 2rem;
+    top: 50%;
+    transform: translateY(-50%);
+    padding: 1px 6px;
+    font-size: 0.6rem;
+    font-family: var(--font-mono);
+    color: var(--accent);
+    border: 1px solid color-mix(in srgb, var(--accent) 30%, transparent);
+    border-radius: 8px;
+    background: color-mix(in srgb, var(--accent) 8%, transparent);
+    pointer-events: none;
+    letter-spacing: 0.3px;
+}
+
 /* ─── Buttons ─── */
 .btn {
     display: inline-flex;
@@ -2040,6 +2056,14 @@ a.port-link:hover {
     white-space: nowrap;
 }
 
+/* ─── Virtual Scroll Spacers ─── */
+.log-virtual-top,
+.log-virtual-bottom {
+    display: block;
+    width: 100%;
+    pointer-events: none;
+}
+
 /* ─── Log Lines ─── */
 .log-line {
     padding: 0.1rem 0.5rem 0.1rem 0;
@@ -2446,4 +2470,141 @@ a.port-link:hover {
 .guard-sentinel-pill.stopped .guard-sentinel-dot {
     background: var(--danger);
     box-shadow: 0 0 4px rgba(239, 68, 68, 0.3);
+}
+
+/* ─── Keyboard Navigation Focus ─── */
+tr.keyboard-focus {
+    outline: 2px solid var(--accent-primary);
+    outline-offset: -2px;
+    background: rgba(168, 85, 247, 0.08) !important;
+    border-radius: var(--radius-sm);
+}
+
+tr.keyboard-focus td:first-child .process-name span {
+    color: var(--accent-primary);
+}
+
+/* ─── Keyboard Shortcuts Overlay ─── */
+.shortcuts-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 2000;
+    background: rgba(0, 0, 0, 0.6);
+    backdrop-filter: blur(4px);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.2s ease;
+}
+
+.shortcuts-overlay.active {
+    opacity: 1;
+    pointer-events: auto;
+}
+
+.shortcuts-panel {
+    background: var(--bg-secondary);
+    border: 1px solid var(--border-glass);
+    border-radius: var(--radius-lg);
+    box-shadow: 0 24px 80px rgba(0, 0, 0, 0.5), 0 0 60px rgba(0, 0, 0, 0.3);
+    padding: 1.5rem;
+    min-width: 440px;
+    max-width: 520px;
+    animation: scaleIn 0.2s ease;
+}
+
+.shortcuts-overlay.active .shortcuts-panel {
+    animation: scaleIn 0.2s ease;
+}
+
+@keyframes scaleIn {
+    from {
+        transform: scale(0.95);
+        opacity: 0;
+    }
+
+    to {
+        transform: scale(1);
+        opacity: 1;
+    }
+}
+
+.shortcuts-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 1.25rem;
+    padding-bottom: 0.75rem;
+    border-bottom: 1px solid var(--border-glass);
+}
+
+.shortcuts-header h3 {
+    font-size: 1rem;
+    font-weight: 600;
+    color: var(--text-primary);
+    margin: 0;
+}
+
+.shortcuts-close {
+    background: none;
+    border: none;
+    color: var(--text-muted);
+    font-size: 1.1rem;
+    cursor: pointer;
+    padding: 0.25rem;
+    line-height: 1;
+    transition: color 0.15s;
+}
+
+.shortcuts-close:hover {
+    color: var(--text-primary);
+}
+
+.shortcuts-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 1.5rem;
+}
+
+.shortcut-section h4 {
+    font-size: 0.7rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--text-dim);
+    font-weight: 600;
+    margin: 0 0 0.6rem 0;
+}
+
+.shortcut-row {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.3rem 0;
+    font-size: 0.8rem;
+    color: var(--text-secondary);
+}
+
+.shortcut-row span {
+    flex: 1;
+}
+
+.shortcut-row kbd {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 24px;
+    height: 24px;
+    padding: 0 6px;
+    background: rgba(255, 255, 255, 0.06);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 5px;
+    font-family: var(--font-mono);
+    font-size: 0.68rem;
+    font-weight: 600;
+    color: var(--text-primary);
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+    line-height: 1;
+    flex-shrink: 0;
 }

package/dashboard/app/page.client.tsx

@@ -1,15 +1,10 @@
-/** @jsxImportSource melina/client */
 /**
  * bgrun Dashboard — Page Client Interactivity
  *
  * NOT a React component. A mount function that adds interactivity
- * to the server-rendered HTML. JSX here creates real DOM elements
- * (via Melina's jsx-dom runtime, not React virtual DOM).
- *
- * Log viewer uses Melina's VDOM render() with keyed reconciler
- * for efficient incremental DOM updates.
+ * to the server-rendered HTML. JSX creates real DOM elements via
+ * Melina's jsx-dom runtime (mapped from react/jsx-runtime).
  */
-import { render as melinaRender, createElement as h, setReconciler } from 'melina/client/render';
 
 interface ProcessData {
     name: string;
@@ -418,6 +413,7 @@ export default function mount(): () => void {
     let isFirstLoad = true;
     let allProcesses: ProcessData[] = [];
     let searchQuery = '';
+    let searchDebounce: ReturnType<typeof setTimeout> | null = null;
     let collapsedGroups: Set<string> = new Set(JSON.parse(localStorage.getItem('bgr_collapsed_groups') || '[]'));
     let drawerProcess: string | null = null;
     let drawerTab: 'stdout' | 'stderr' = 'stdout';
@@ -433,6 +429,28 @@ export default function mount(): () => void {
     let logLastSize = -1;         // Detect no-change polls
     let logNeedsFullRebuild = true; // Full DOM rebuild flag (on tab switch, search change)
 
+    // ─── Virtual Scrolling State ───
+    let LOG_LINE_HEIGHT = 22;       // default estimate, auto-calibrated on first render
+    let logLineHeightCalibrated = false;
+    const LOG_OVERSCAN = 10;        // extra lines rendered above/below viewport
+    const VIRTUAL_THRESHOLD = 200;  // switch to virtual mode above this many lines
+    let logVirtualActive = false;   // whether virtual scrolling is engaged
+    let logFilteredIndices: number[] = []; // indices into logLinesRaw that pass the search filter
+    let logScrollRAF: number | null = null; // rAF handle for throttled scroll
+
+    /** Measure actual log line height from DOM on first render */
+    function calibrateLogLineHeight(logsEl: HTMLElement) {
+        if (logLineHeightCalibrated) return;
+        const firstLine = logsEl.querySelector('.log-line') as HTMLElement;
+        if (firstLine) {
+            const measured = firstLine.getBoundingClientRect().height;
+            if (measured > 0) {
+                LOG_LINE_HEIGHT = Math.round(measured);
+                logLineHeightCalibrated = true;
+            }
+        }
+    }
+
     // ─── Version Badge ───
     const versionBadge = $('version-badge');
     async function loadVersion() {
@@ -457,14 +475,18 @@ export default function mount(): () => void {
             allProcesses = await res.json();
             renderFilteredProcesses();
             updateStats(allProcesses);
-        } catch {
-            // silently retry on next tick
+        } catch (err) {
+            console.error('[bgr-dashboard] loadProcesses error:', err);
         } finally {
             isFetching = false;
         }
     }
 
     function renderFilteredProcesses() {
+        // Always sync searchQuery from DOM to prevent desync
+        if (searchInput && searchInput.value.toLowerCase().trim() !== searchQuery) {
+            searchQuery = searchInput.value.toLowerCase().trim();
+        }
         const filtered = searchQuery
             ? allProcesses.filter(p =>
                 p.name.toLowerCase().includes(searchQuery) ||
@@ -473,6 +495,17 @@ export default function mount(): () => void {
             )
             : allProcesses;
         renderProcesses(filtered);
+
+        // Update search result count badge
+        const badge = $('search-count');
+        if (badge) {
+            if (searchQuery) {
+                badge.textContent = `${filtered.length}/${allProcesses.length}`;
+                badge.style.display = 'inline-block';
+            } else {
+                badge.style.display = 'none';
+            }
+        }
     }
 
     function updateStats(processes: ProcessData[]) {
@@ -526,6 +559,16 @@ export default function mount(): () => void {
         }
     }
 
+    function toggleGroup(groupDir: string) {
+        if (collapsedGroups.has(groupDir)) {
+            collapsedGroups.delete(groupDir);
+        } else {
+            collapsedGroups.add(groupDir);
+        }
+        localStorage.setItem('bgr_collapsed_groups', JSON.stringify([...collapsedGroups]));
+        renderFilteredProcesses();
+    }
+
     function renderProcesses(processes: ProcessData[]) {
         const tbody = $('processes-table');
         const cardsEl = $('mobile-cards');
@@ -553,62 +596,65 @@ export default function mount(): () => void {
             groups[key].push(p);
         });
 
-        const nodes: Node[] = [];
         const sortedGroupKeys = Object.keys(groups).sort();
 
-        // Always show group headers for every directory
+        // Build DOM nodes for table rows
+        const rows: Node[] = [];
         sortedGroupKeys.forEach(groupDir => {
             const procs = groups[groupDir];
             const running = procs.filter(p => p.running).length;
             const collapsed = collapsedGroups.has(groupDir);
-            nodes.push(<GroupHeader name={groupDir} running={running} total={procs.length} collapsed={collapsed} /> as unknown as Node);
+            rows.push(<GroupHeader name={groupDir} running={running} total={procs.length} collapsed={collapsed} /> as unknown as Node);
             if (!collapsed) {
                 procs.forEach(p => {
-                    nodes.push(<ProcessRow p={p} animate={animate} /> as unknown as Node);
+                    rows.push(<ProcessRow p={p} animate={animate} /> as unknown as Node);
                 });
             }
         });
 
-        tbody.replaceChildren(...nodes);
+        // Replace tbody contents with new DOM nodes
+        tbody.replaceChildren(...rows);
 
         // Add click handlers for group headers (toggle collapse)
         tbody.querySelectorAll('.group-header').forEach(header => {
             header.addEventListener('click', (e: Event) => {
-                // Don't collapse if clicking action buttons
                 if ((e.target as Element).closest('[data-action]')) return;
                 const groupName = (header as HTMLElement).dataset.groupName;
                 if (!groupName) return;
-                if (collapsedGroups.has(groupName)) {
-                    collapsedGroups.delete(groupName);
-                } else {
-                    collapsedGroups.add(groupName);
-                }
-                localStorage.setItem('bgr_collapsed_groups', JSON.stringify([...collapsedGroups]));
-                renderFilteredProcesses();
+                toggleGroup(groupName);
             });
         });
 
         // Render mobile cards
         if (cardsEl) {
-            const cards = processes.map(p => <ProcessCard p={p} /> as unknown as Node);
-            cardsEl.replaceChildren(...cards);
+            cardsEl.replaceChildren(...processes.map(p => <ProcessCard p={p} /> as unknown as Node));
         }
 
         if (isFirstLoad) isFirstLoad = false;
 
-        // Highlight selected row
+        // Restore selected row + keyboard focus row
         if (drawerProcess) {
-            const row = tbody.querySelector(`tr[data-process-name="${drawerProcess}"]`);
+            const finalTbody = $('processes-table') || tbody;
+            const row = finalTbody.querySelector(`tr[data-process-name="${drawerProcess}"]`);
             if (row) row.classList.add('selected');
         }
+        // Restore keyboard focus ring if user had a row focused
+        if (focusedProcessName) {
+            const finalTbody = $('processes-table') || tbody;
+            const focusRow = finalTbody.querySelector(`tr[data-process-name="${focusedProcessName}"]`);
+            if (focusRow) focusRow.classList.add('focus-ring');
+        }
     }
 
-    // ─── Search ───
+    // ─── Search (debounced 150ms) ───
 
     const searchInput = $('search-input') as HTMLInputElement;
     searchInput?.addEventListener('input', () => {
-        searchQuery = searchInput.value.toLowerCase().trim();
-        renderFilteredProcesses();
+        if (searchDebounce) clearTimeout(searchDebounce);
+        searchDebounce = setTimeout(() => {
+            searchQuery = searchInput.value.toLowerCase().trim();
+            renderFilteredProcesses();
+        }, 150);
     });
 
     /** Fetch with cache-bust to force fresh data after mutations */
@@ -925,6 +971,8 @@ export default function mount(): () => void {
         logCurrentTab = '';
         logLastSize = -1;
         logNeedsFullRebuild = true;
+        logVirtualActive = false;
+        logFilteredIndices = [];
         if (!skipRefresh) refreshDrawerLogs();
     }
 
@@ -1124,8 +1172,70 @@ export default function mount(): () => void {
         tbody?.querySelectorAll('tr.selected').forEach(r => r.classList.remove('selected'));
     }
 
-    // Use keyed reconciler for efficient log line diffing
-    setReconciler('keyed');
+
+    // ─── Build filtered indices ───
+    function rebuildFilteredIndices() {
+        const search = logSearch.toLowerCase();
+        logFilteredIndices = [];
+        for (let i = 0; i < logLinesRaw.length; i++) {
+            if (search && !logLinesRaw[i].toLowerCase().includes(search)) continue;
+            logFilteredIndices.push(i);
+        }
+    }
+
+    // ─── Render a single log line HTML string ───
+    function renderLogLineHtml(rawIndex: number): string {
+        const num = rawIndex + 1;
+        return `<div class="log-line" data-ln="${num}"><span class="log-line-num">${num}</span><span class="log-line-content">${logLinesHtml[rawIndex]}</span></div>`;
+    }
+
+    // ─── Virtual scroll: render only visible slice ───
+    function virtualRenderSlice(logsEl: HTMLElement) {
+        const count = logFilteredIndices.length;
+        if (count === 0) {
+            logsEl.innerHTML = '<em style="color: var(--text-muted)">No logs available</em>';
+            return;
+        }
+
+        const totalHeight = count * LOG_LINE_HEIGHT;
+        const scrollTop = logsEl.scrollTop;
+        const viewportH = logsEl.clientHeight;
+
+        // Calculate visible range with overscan
+        let startIdx = Math.floor(scrollTop / LOG_LINE_HEIGHT) - LOG_OVERSCAN;
+        let endIdx = Math.ceil((scrollTop + viewportH) / LOG_LINE_HEIGHT) + LOG_OVERSCAN;
+        startIdx = Math.max(0, startIdx);
+        endIdx = Math.min(count - 1, endIdx);
+
+        // Only rebuild if the visible range actually changed
+        const topSpacer = logsEl.querySelector('.log-virtual-top') as HTMLElement;
+        if (topSpacer && topSpacer.dataset.start === String(startIdx) && topSpacer.dataset.end === String(endIdx)) {
+            return; // same range, skip DOM work
+        }
+
+        const topH = startIdx * LOG_LINE_HEIGHT;
+        const bottomH = Math.max(0, (count - endIdx - 1) * LOG_LINE_HEIGHT);
+
+        // Build visible lines
+        const chunks: string[] = [];
+        chunks.push(`<div class="log-virtual-top" data-start="${startIdx}" data-end="${endIdx}" style="height:${topH}px"></div>`);
+        for (let i = startIdx; i <= endIdx; i++) {
+            chunks.push(renderLogLineHtml(logFilteredIndices[i]));
+        }
+        chunks.push(`<div class="log-virtual-bottom" style="height:${bottomH}px"></div>`);
+        logsEl.innerHTML = chunks.join('');
+    }
+
+    // ─── Scroll handler for virtual mode ───
+    function onLogScroll() {
+        if (!logVirtualActive) return;
+        if (logScrollRAF) return; // already scheduled
+        logScrollRAF = requestAnimationFrame(() => {
+            logScrollRAF = null;
+            const logsEl = $('drawer-logs') as HTMLElement;
+            if (logsEl) virtualRenderSlice(logsEl);
+        });
+    }
 
     function fullRebuildLogs(logsEl: HTMLElement) {
         const search = logSearch.toLowerCase();
@@ -1133,48 +1243,78 @@ export default function mount(): () => void {
             logsEl.innerHTML = '<em style="color: var(--text-muted)">No logs available</em>';
             updateLogCount(0);
             logNeedsFullRebuild = false;
+            logVirtualActive = false;
             return;
         }
 
-        // Build all HTML in one pass using cached ansiToHtml results
-        const chunks: string[] = [];
-        let count = 0;
-        for (let i = 0; i < logLinesRaw.length; i++) {
-            if (search && !logLinesRaw[i].toLowerCase().includes(search)) continue;
-            count++;
-            const num = i + 1;
-            chunks.push(`<div class="log-line" data-ln="${num}"><span class="log-line-num">${num}</span><span class="log-line-content">${logLinesHtml[i]}</span></div>`);
-        }
-        logsEl.innerHTML = chunks.join('');
+        // Rebuild filtered indices
+        rebuildFilteredIndices();
+        const count = logFilteredIndices.length;
         updateLogCount(count);
+
+        // Decide: virtual or direct
+        if (count >= VIRTUAL_THRESHOLD) {
+            logVirtualActive = true;
+            virtualRenderSlice(logsEl);
+        } else {
+            logVirtualActive = false;
+            // Direct render — small enough for full DOM
+            const chunks: string[] = [];
+            for (const idx of logFilteredIndices) {
+                chunks.push(renderLogLineHtml(idx));
+            }
+            logsEl.innerHTML = chunks.join('');
+        }
         logNeedsFullRebuild = false;
+
+        // Auto-calibrate line height from first rendered line
+        if (!logLineHeightCalibrated) {
+            requestAnimationFrame(() => calibrateLogLineHeight(logsEl));
+        }
     }
 
     function appendNewLogLines(logsEl: HTMLElement, startIndex: number) {
-        // Fast path: append only new lines to existing DOM
         const search = logSearch.toLowerCase();
-        const fragment = document.createDocumentFragment();
-        let count = 0;
+
+        // Append to filtered indices
         for (let i = startIndex; i < logLinesRaw.length; i++) {
             if (search && !logLinesRaw[i].toLowerCase().includes(search)) continue;
-            count++;
-            const div = document.createElement('div');
-            div.className = 'log-line';
-            div.setAttribute('data-ln', String(i + 1));
-            div.innerHTML = `<span class="log-line-num">${i + 1}</span><span class="log-line-content">${logLinesHtml[i]}</span>`;
-            fragment.appendChild(div);
-        }
-        if (count > 0) logsEl.appendChild(fragment);
-        // Update total count
-        const total = search
-            ? logLinesRaw.filter(l => l.toLowerCase().includes(search)).length
-            : logLinesRaw.length;
-        updateLogCount(total);
+            logFilteredIndices.push(i);
+        }
+        const count = logFilteredIndices.length;
+        updateLogCount(count);
+
+        // Check if we need to switch to virtual mode
+        if (count >= VIRTUAL_THRESHOLD && !logVirtualActive) {
+            logVirtualActive = true;
+            virtualRenderSlice(logsEl);
+            return;
+        }
+
+        if (logVirtualActive) {
+            // In virtual mode, re-render the current visible slice
+            virtualRenderSlice(logsEl);
+        } else {
+            // Direct DOM append for small logs
+            const fragment = document.createDocumentFragment();
+            for (let i = startIndex; i < logLinesRaw.length; i++) {
+                if (search && !logLinesRaw[i].toLowerCase().includes(search)) continue;
+                const div = document.createElement('div');
+                div.className = 'log-line';
+                div.setAttribute('data-ln', String(i + 1));
+                div.innerHTML = `<span class="log-line-num">${i + 1}</span><span class="log-line-content">${logLinesHtml[i]}</span>`;
+                fragment.appendChild(div);
+            }
+            if (fragment.childNodes.length > 0) logsEl.appendChild(fragment);
+        }
     }
 
     function updateLogCount(count: number) {
         const countEl = $('log-line-count');
-        if (countEl) countEl.textContent = `${count} line${count !== 1 ? 's' : ''}`;
+        if (countEl) {
+            const suffix = logVirtualActive ? ' (virtual)' : '';
+            countEl.textContent = `${count} line${count !== 1 ? 's' : ''}${suffix}`;
+        }
     }
 
     async function refreshDrawerLogs() {
@@ -1287,6 +1427,10 @@ export default function mount(): () => void {
 
     // Click log line → expand/collapse (word-wrap toggle)
     const logsContainer = $('drawer-logs');
+
+    // Virtual scroll handler — drives re-render on scroll in virtual mode
+    logsContainer?.addEventListener('scroll', onLogScroll, { passive: true });
+
     logsContainer?.addEventListener('click', (e: Event) => {
         const line = (e.target as Element).closest('.log-line') as HTMLElement;
         if (!line) return;
@@ -1470,6 +1614,9 @@ export default function mount(): () => void {
         if (drawerProcess) refreshDrawerLogs();
     });
 
+    // ─── Shortcuts Button ───
+    $('shortcuts-btn')?.addEventListener('click', toggleShortcutsOverlay);
+
     // ─── Guard All Button ───
     $('guard-all-btn')?.addEventListener('click', async () => {
         const guardAllBtn = $('guard-all-btn') as HTMLButtonElement;
@@ -1513,14 +1660,95 @@ export default function mount(): () => void {
     // Group toggle removed — always-on directory grouping
 
     // ─── Keyboard Shortcuts ───
+    let focusedProcessName: string | null = null;
+
+    function getFocusableRows(): HTMLElement[] {
+        const rows = tbody?.querySelectorAll('tr[data-process-name]') as NodeListOf<HTMLElement> | undefined;
+        return rows ? Array.from(rows) : [];
+    }
+
+    function setProcessFocus(name: string | null) {
+        // Remove previous focus
+        tbody?.querySelectorAll('tr.keyboard-focus').forEach(r => r.classList.remove('keyboard-focus'));
+        focusedProcessName = name;
+        if (!name) return;
+        const row = tbody?.querySelector(`tr[data-process-name="${name}"]`) as HTMLElement;
+        if (row) {
+            row.classList.add('keyboard-focus');
+            row.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+        }
+    }
+
+    function navigateProcess(direction: 'up' | 'down') {
+        const rows = getFocusableRows();
+        if (rows.length === 0) return;
+
+        if (!focusedProcessName) {
+            // Nothing focused: pick first or last
+            const target = direction === 'down' ? rows[0] : rows[rows.length - 1];
+            setProcessFocus(target.dataset.processName || null);
+            return;
+        }
+
+        const idx = rows.findIndex(r => r.dataset.processName === focusedProcessName);
+        if (idx === -1) {
+            setProcessFocus(rows[0].dataset.processName || null);
+            return;
+        }
+
+        const nextIdx = direction === 'down'
+            ? Math.min(idx + 1, rows.length - 1)
+            : Math.max(idx - 1, 0);
+        setProcessFocus(rows[nextIdx].dataset.processName || null);
+    }
+
+    /** Dispatch a process action by synthesizing a click on a virtual button */
+    function dispatchAction(actionName: string, processName: string) {
+        const fakeBtn = document.createElement('button');
+        fakeBtn.dataset.action = actionName;
+        fakeBtn.dataset.name = processName;
+        // For guard toggle, read current state
+        if (actionName === 'guard') {
+            const proc = allProcesses.find(p => p.name === processName);
+            fakeBtn.dataset.guarded = proc && isGuarded(proc) ? 'true' : 'false';
+        }
+        const fakeEvent = new MouseEvent('click');
+        Object.defineProperty(fakeEvent, 'target', { value: fakeBtn });
+        handleAction(fakeEvent);
+    }
+
+    function toggleShortcutsOverlay() {
+        const overlay = $('shortcuts-overlay');
+        if (overlay) overlay.classList.toggle('active');
+    }
+
+    $('shortcuts-close-btn')?.addEventListener('click', () => {
+        $('shortcuts-overlay')?.classList.remove('active');
+    });
+    $('shortcuts-overlay')?.addEventListener('click', (e) => {
+        if ((e.target as Element).classList.contains('shortcuts-overlay')) {
+            $('shortcuts-overlay')?.classList.remove('active');
+        }
+    });
+
     function handleKeydown(e: KeyboardEvent) {
+        // Skip all shortcuts when inside text inputs or textareas
+        const inInput = e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement;
+
         // "/" to focus search (unless already in an input)
-        if (e.key === '/' && !(e.target instanceof HTMLInputElement)) {
+        if (e.key === '/' && !inInput) {
             e.preventDefault();
             searchInput?.focus();
             return;
         }
+
+        // Escape: close overlays progressively
         if (e.key === 'Escape') {
+            const shortcutsOverlay = $('shortcuts-overlay');
+            if (shortcutsOverlay?.classList.contains('active')) {
+                shortcutsOverlay.classList.remove('active');
+                return;
+            }
             if (contextMenuEl) {
                 closeContextMenu();
                 return;
@@ -1530,10 +1758,75 @@ export default function mount(): () => void {
             } else {
                 closeModal();
             }
+            // Clear keyboard focus
+            setProcessFocus(null);
             // Blur search on escape
             if (document.activeElement === searchInput) {
                 searchInput?.blur();
             }
+            return;
+        }
+
+        // Remaining shortcuts only when NOT in inputs
+        if (inInput) return;
+
+        // Arrow navigation
+        if (e.key === 'ArrowDown' || e.key === 'j') {
+            e.preventDefault();
+            navigateProcess('down');
+            return;
+        }
+        if (e.key === 'ArrowUp' || e.key === 'k') {
+            e.preventDefault();
+            navigateProcess('up');
+            return;
+        }
+
+        // Enter: open drawer for focused process
+        if (e.key === 'Enter' && focusedProcessName) {
+            e.preventDefault();
+            openDrawer(focusedProcessName);
+            return;
+        }
+
+        // ? — help overlay
+        if (e.key === '?') {
+            e.preventDefault();
+            toggleShortcutsOverlay();
+            return;
+        }
+
+        // N — new process modal
+        if (e.key === 'n' || e.key === 'N') {
+            e.preventDefault();
+            openModal();
+            return;
+        }
+
+        // Process actions — require a focused row
+        if (!focusedProcessName) return;
+
+        if (e.key === 'r' || e.key === 'R') {
+            e.preventDefault();
+            dispatchAction('restart', focusedProcessName);
+            return;
+        }
+        if (e.key === 's' || e.key === 'S') {
+            e.preventDefault();
+            dispatchAction('stop', focusedProcessName);
+            return;
+        }
+        if (e.key === 'g' || e.key === 'G') {
+            e.preventDefault();
+            dispatchAction('guard', focusedProcessName);
+            return;
+        }
+        if (e.key === 'd' || e.key === 'D') {
+            e.preventDefault();
+            dispatchAction('delete', focusedProcessName);
+            // Clear focus since process is gone
+            setProcessFocus(null);
+            return;
         }
     }
     document.addEventListener('keydown', handleKeydown);
@@ -1542,10 +1835,17 @@ export default function mount(): () => void {
     let eventSource: EventSource | null = null;
     let logRefreshTimer: ReturnType<typeof setInterval> | null = null;
     let sseThrottleTimer: ReturnType<typeof setTimeout> | null = null;
+    let sseRetryDelay = 2_000;       // exponential backoff start
+    const SSE_MAX_RETRY = 30_000;    // max 30s between retries
+
+    // Initial data load — don't depend on SSE for first render
+    loadProcesses();
 
     function connectSSE() {
+        if (eventSource) { eventSource.close(); eventSource = null; }
         eventSource = new EventSource('/api/events');
         eventSource.onmessage = (event) => {
+            sseRetryDelay = 2_000; // reset backoff on success
             // Skip SSE updates briefly after mutations to avoid flicker
             if (Date.now() < mutationUntil) return;
             try {
@@ -1561,14 +1861,29 @@ export default function mount(): () => void {
             } catch { /* invalid data, skip */ }
         };
         eventSource.onerror = () => {
-            // SSE disconnected, reconnect after 5s
+            // SSE disconnected — exponential backoff reconnect
             eventSource?.close();
             eventSource = null;
-            setTimeout(connectSSE, 5000);
+            setTimeout(connectSSE, sseRetryDelay);
+            sseRetryDelay = Math.min(sseRetryDelay * 2, SSE_MAX_RETRY);
         };
     }
     connectSSE();
 
+    // Pause SSE when tab is hidden, resume when visible
+    function handleVisibility() {
+        if (document.hidden) {
+            eventSource?.close();
+            eventSource = null;
+        } else {
+            if (!eventSource) {
+                sseRetryDelay = 2_000; // reset on manual re-focus
+                connectSSE();
+            }
+        }
+    }
+    document.addEventListener('visibilitychange', handleVisibility);
+
     // Log drawer still needs periodic refresh (not part of SSE)
     logRefreshTimer = setInterval(() => {
         if (drawerProcess) refreshDrawerLogs();
@@ -1584,9 +1899,13 @@ export default function mount(): () => void {
         $('modal-create-btn')?.removeEventListener('click', createProcess);
         $('refresh-btn')?.removeEventListener('click', loadProcesses);
         document.removeEventListener('keydown', handleKeydown);
+        document.removeEventListener('visibilitychange', handleVisibility);
         closeContextMenu();
         if (eventSource) eventSource.close();
         if (logRefreshTimer) clearInterval(logRefreshTimer);
         if (sseThrottleTimer) clearTimeout(sseThrottleTimer);
+        if (searchDebounce) clearTimeout(searchDebounce);
+        if (logScrollRAF) cancelAnimationFrame(logScrollRAF);
+        logsContainer?.removeEventListener('scroll', onLogScroll);
     };
 }

package/dashboard/app/page.tsx

@@ -53,6 +53,7 @@ export default function DashboardPage() {
                             <line x1="21" y1="21" x2="16.65" y2="16.65" />
                         </svg>
                         <input type="text" className="search-input" id="search-input" placeholder="Filter processes..." />
+                        <span className="search-count" id="search-count" style={{ display: 'none' }}></span>
                         <span className="search-shortcut">/</span>
                     </div>
                 </div>
@@ -73,6 +74,9 @@ export default function DashboardPage() {
                         <span className="guard-sentinel-dot" id="guard-sentinel-dot" />
                         <span id="guard-sentinel-label">Guard: –</span>
                     </span>
+                    <button className="btn btn-ghost btn-icon" id="shortcuts-btn" title="Keyboard Shortcuts (?)">
+                        <span style={{ fontSize: '0.85rem', fontWeight: '700' }}>?</span>
+                    </button>
                     <button className="btn btn-primary" id="new-process-btn">
                         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
                             <line x1="12" y1="5" x2="12" y2="19" />
@@ -221,6 +225,34 @@ export default function DashboardPage() {
                     </div>
                 </div>
             </div>
+
+            {/* Keyboard Shortcuts Overlay */}
+            <div className="shortcuts-overlay" id="shortcuts-overlay">
+                <div className="shortcuts-panel">
+                    <div className="shortcuts-header">
+                        <h3>⌨️ Keyboard Shortcuts</h3>
+                        <button className="shortcuts-close" id="shortcuts-close-btn">✕</button>
+                    </div>
+                    <div className="shortcuts-grid">
+                        <div className="shortcut-section">
+                            <h4>Navigation</h4>
+                            <div className="shortcut-row"><kbd>↑</kbd><kbd>↓</kbd><span>Navigate processes</span></div>
+                            <div className="shortcut-row"><kbd>Enter</kbd><span>Open process drawer</span></div>
+                            <div className="shortcut-row"><kbd>/</kbd><span>Focus search</span></div>
+                            <div className="shortcut-row"><kbd>Esc</kbd><span>Close panel / blur</span></div>
+                        </div>
+                        <div className="shortcut-section">
+                            <h4>Actions</h4>
+                            <div className="shortcut-row"><kbd>R</kbd><span>Restart process</span></div>
+                            <div className="shortcut-row"><kbd>S</kbd><span>Stop process</span></div>
+                            <div className="shortcut-row"><kbd>G</kbd><span>Toggle guard</span></div>
+                            <div className="shortcut-row"><kbd>D</kbd><span>Delete process</span></div>
+                            <div className="shortcut-row"><kbd>N</kbd><span>New process</span></div>
+                            <div className="shortcut-row"><kbd>?</kbd><span>This help</span></div>
+                        </div>
+                    </div>
+                </div>
+            </div>
         </div>
     );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bgrun",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "bgrun — A lightweight process manager for Bun",
   "type": "module",
   "main": "./src/api.ts",
@@ -19,6 +19,7 @@
     "dist",
     "src",
     "dashboard/app",
+    "scripts",
     "README.md",
     "image.png",
     "examples/bgr-startup.sh"
@@ -50,7 +51,7 @@
     "chalk": "^5.4.1",
     "dedent": "^1.5.3",
     "measure-fn": "3.10.1",
-    "melina": "2.3.3",
+    "melina": "2.3.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "sqlite-zod-orm": "3.26.1"

package/scripts/bgr-startup.ps1

@@ -0,0 +1,118 @@
+# bgr-startup.ps1 — Auto-start bgrun guard on Windows login
+# Ensures all guarded processes (and the dashboard itself) start on boot.
+#
+# Installation:
+#   1. Run this script once with -Install flag:
+#      powershell -ExecutionPolicy Bypass -File bgr-startup.ps1 -Install
+#
+#   2. Or manually create a Task Scheduler task:
+#      - Trigger: At log on
+#      - Action: powershell -WindowStyle Hidden -ExecutionPolicy Bypass -File "C:\Code\bgr\scripts\bgr-startup.ps1"
+#      - Run whether user is logged on or not: Yes
+#
+# Usage:
+#   bgr-startup.ps1           # Start bgrun guard
+#   bgr-startup.ps1 -Install  # Register Task Scheduler entry
+
+param(
+    [switch]$Install
+)
+
+$BunPath = "$env:USERPROFILE\.bun\bin\bun.exe"
+$BgrunPath = "C:\Code\bgr"
+$LogPath = "$env:USERPROFILE\.bgr\startup.log"
+
+function Write-Log {
+    param([string]$Message)
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    $line = "[$timestamp] $Message"
+    Write-Host $line
+    Add-Content -Path $LogPath -Value $line -ErrorAction SilentlyContinue
+}
+
+# Ensure .bgr directory exists
+$bgrDir = "$env:USERPROFILE\.bgr"
+if (-not (Test-Path $bgrDir)) {
+    New-Item -ItemType Directory -Path $bgrDir -Force | Out-Null
+}
+
+if ($Install) {
+    Write-Log "Installing bgrun auto-start task..."
+
+    $scriptPath = $PSCommandPath
+    if (-not $scriptPath) {
+        $scriptPath = Join-Path $BgrunPath "scripts\bgr-startup.ps1"
+    }
+
+    # Remove existing task if present
+    $existingTask = Get-ScheduledTask -TaskName "bgrun-guard" -ErrorAction SilentlyContinue
+    if ($existingTask) {
+        Unregister-ScheduledTask -TaskName "bgrun-guard" -Confirm:$false
+        Write-Log "Removed existing bgrun-guard task"
+    }
+
+    # Create the scheduled task
+    $action = New-ScheduledTaskAction `
+        -Execute "powershell.exe" `
+        -Argument "-WindowStyle Hidden -ExecutionPolicy Bypass -File `"$scriptPath`""
+
+    $trigger = New-ScheduledTaskTrigger -AtLogon
+    $settings = New-ScheduledTaskSettingsSet `
+        -AllowStartIfOnBatteries `
+        -DontStopIfGoingOnBatteries `
+        -StartWhenAvailable `
+        -RestartInterval (New-TimeSpan -Minutes 5) `
+        -RestartCount 3
+
+    Register-ScheduledTask `
+        -TaskName "bgrun-guard" `
+        -Description "bgrun process manager — auto-starts all guarded processes on login" `
+        -Action $action `
+        -Trigger $trigger `
+        -Settings $settings `
+        -RunLevel Highest `
+        -Force
+
+    Write-Log "✓ Task 'bgrun-guard' registered. Will start on next login."
+    Write-Log "  Script: $scriptPath"
+    exit 0
+}
+
+# ── Main: Start bgrun guard ─────────────────────────────────
+Write-Log "bgrun startup initiated"
+
+# Check bun exists
+if (-not (Test-Path $BunPath)) {
+    Write-Log "ERROR: bun not found at $BunPath"
+    exit 1
+}
+
+# Check bgrun repo exists
+if (-not (Test-Path "$BgrunPath\src\guard.ts")) {
+    Write-Log "ERROR: bgrun not found at $BgrunPath"
+    exit 1
+}
+
+# Start the dashboard first (guard needs it)
+Write-Log "Starting bgrun dashboard..."
+$dashboardProc = Start-Process -FilePath $BunPath `
+    -ArgumentList "run", "$BgrunPath\src\index.ts", "--dashboard", "--port", "3000" `
+    -WindowStyle Hidden `
+    -PassThru `
+    -WorkingDirectory $BgrunPath
+
+Write-Log "Dashboard PID: $($dashboardProc.Id)"
+
+# Wait for dashboard to be ready
+Start-Sleep -Seconds 5
+
+# Start the guard (watches dashboard + all guarded processes)
+Write-Log "Starting bgrun guard..."
+$guardProc = Start-Process -FilePath $BunPath `
+    -ArgumentList "run", "$BgrunPath\src\index.ts", "--guard" `
+    -WindowStyle Hidden `
+    -PassThru `
+    -WorkingDirectory $BgrunPath
+
+Write-Log "Guard PID: $($guardProc.Id)"
+Write-Log "✓ bgrun startup complete. Dashboard: $($dashboardProc.Id), Guard: $($guardProc.Id)"

package/src/bgrun.test.ts

@@ -0,0 +1,109 @@
+/**
+ * bgrun core utility tests
+ *
+ * Tests pure logic functions: env parsing, config flattening,
+ * string truncation, and runtime calculation.
+ *
+ * Run: bun test src/bgrun.test.ts
+ */
+import { describe, expect, test } from 'bun:test'
+import { parseEnvString, calculateRuntime } from './utils'
+import { stripAnsi, truncateString, truncatePath } from './table'
+
+// ─── parseEnvString ─────────────────────────────────────
+
+describe('parseEnvString', () => {
+    test('parses comma-separated key=value pairs', () => {
+        const result = parseEnvString('PORT=3000,HOST=localhost,DEBUG=true')
+        expect(result).toEqual({
+            PORT: '3000',
+            HOST: 'localhost',
+            DEBUG: 'true',
+        })
+    })
+
+    test('handles single pair', () => {
+        expect(parseEnvString('KEY=value')).toEqual({ KEY: 'value' })
+    })
+
+    test('handles empty string', () => {
+        expect(parseEnvString('')).toEqual({})
+    })
+
+    test('ignores malformed pairs (no =)', () => {
+        const result = parseEnvString('GOOD=yes,BAD,ALSO_GOOD=ok')
+        expect(result.GOOD).toBe('yes')
+        expect(result.ALSO_GOOD).toBe('ok')
+        expect(result.BAD).toBeUndefined()
+    })
+})
+
+// ─── calculateRuntime ───────────────────────────────────
+
+describe('calculateRuntime', () => {
+    test('returns 0 minutes for recent start', () => {
+        const now = new Date().toISOString()
+        expect(calculateRuntime(now)).toBe('0 minutes')
+    })
+
+    test('returns correct minutes', () => {
+        const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString()
+        expect(calculateRuntime(fiveMinAgo)).toBe('5 minutes')
+    })
+
+    test('returns correct for 1 hour', () => {
+        const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000).toISOString()
+        expect(calculateRuntime(oneHourAgo)).toBe('60 minutes')
+    })
+})
+
+// ─── stripAnsi ──────────────────────────────────────────
+
+describe('stripAnsi', () => {
+    test('strips color codes', () => {
+        const colored = '\u001b[31mred text\u001b[0m'
+        expect(stripAnsi(colored)).toBe('red text')
+    })
+
+    test('passes through plain text', () => {
+        expect(stripAnsi('hello world')).toBe('hello world')
+    })
+
+    test('handles empty string', () => {
+        expect(stripAnsi('')).toBe('')
+    })
+})
+
+// ─── truncateString ─────────────────────────────────────
+
+describe('truncateString', () => {
+    test('returns string unchanged if within limit', () => {
+        expect(truncateString('hello', 10)).toBe('hello')
+    })
+
+    test('truncates with ellipsis', () => {
+        const result = truncateString('a very long string that exceeds limit', 15)
+        expect(result.length).toBeLessThanOrEqual(15)
+        expect(result).toContain('…')
+    })
+
+    test('handles maxLength smaller than ellipsis', () => {
+        const result = truncateString('hello world', 2)
+        expect(result.length).toBeLessThanOrEqual(2)
+    })
+})
+
+// ─── truncatePath ───────────────────────────────────────
+
+describe('truncatePath', () => {
+    test('returns path unchanged if within limit', () => {
+        expect(truncatePath('/home/user', 50)).toBe('/home/user')
+    })
+
+    test('truncates middle of long path', () => {
+        const longPath = '/home/user/projects/very/deeply/nested/directory/structure'
+        const result = truncatePath(longPath, 30)
+        expect(result.length).toBeLessThanOrEqual(30)
+        expect(result).toContain('…')
+    })
+})

package/src/table.ts

@@ -34,12 +34,12 @@ export function getTerminalWidth(): number {
 }
 
 // Strip ANSI color codes for accurate length calculation
-function stripAnsi(str: string): string {
+export function stripAnsi(str: string): string {
   return str.replace(/\u001b\[[0-9;]*m/g, "");
 }
 
 // Default truncator: trims the end of a string
-function truncateString(str: string, maxLength: number): string {
+export function truncateString(str: string, maxLength: number): string {
   const stripped = stripAnsi(str);
   if (stripped.length <= maxLength) return str;
   const ellipsis = "…";
@@ -52,7 +52,7 @@ function truncateString(str: string, maxLength: number): string {
 }
 
 // Path truncator: trims the middle of a string
-function truncatePath(str: string, maxLength: number): string {
+export function truncatePath(str: string, maxLength: number): string {
   const stripped = stripAnsi(str);
   if (stripped.length <= maxLength) return str;
   const ellipsis = "…";