@bakapiano/ccsm 0.16.0 → 0.17.2

package/bin/ccsm.js

@@ -39,6 +39,15 @@ function loadPreferredPort() {
   }
 }
 
+// Cheap "is this pid still alive" check using kill(pid, 0). Returns
+// true for live pids we own, also true for pids in other security
+// contexts (EPERM means it exists, we just can't signal it).
+function pidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === 'EPERM'; }
+}
+
 function probe(port, timeoutMs = 800) {
   return new Promise((resolve) => {
     const req = http.get(`http://localhost:${port}/api/health`, { timeout: timeoutMs }, (res) => {
@@ -106,6 +115,30 @@ function isSameVersion(running) {
   const SILENT = !!protocol;  // ccsm:// invocations should not open a new browser
   const port = loadPreferredPort();
 
+  // Upgrade-in-progress guard. The updater helper writes
+  // ~/.ccsm/.upgrade.lock at start. If a ccsm:// click (or any other
+  // launcher trigger) races during an in-flight install, spawning a
+  // new server would: (a) fight npm for the package dir, EBUSY; or
+  // (b) bind port 7777 before the helper's own respawn does. Either
+  // way the upgrade derails. Bail out instead — the helper's UI on
+  // 7779 is already showing the user what's happening.
+  const lockPath = path.join(HOME, '.upgrade.lock');
+  try {
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    const lock = JSON.parse(raw);
+    const ageMs = Date.now() - (lock.startedAt || 0);
+    const ownerAlive = lock.pid ? pidAlive(lock.pid) : false;
+    if (ownerAlive && ageMs < 10 * 60_000) {
+      console.log(`ccsm: upgrade in progress (helper pid=${lock.pid}, ${Math.round(ageMs/1000)}s ago, target=${lock.target || '?'})`);
+      console.log(`  see http://localhost:${lock.helperPort || 7779}/ for live progress`);
+      process.exit(0);
+    }
+    // Stale lock (pid dead OR > 10min) — clean up and continue.
+    try { fs.unlinkSync(lockPath); } catch {}
+  } catch {
+    // ENOENT or parse error → no lock, proceed.
+  }
+
   // Case 1: existing instance on the preferred port
   let existing = await probe(port);
 

package/lib/config.js

@@ -152,7 +152,7 @@ function mergeWithDefaults(partial) {
   // Normalize per-CLI fields.
   out.clis = out.clis.map((c) => {
     const { installed, installPath, resumeArgs, ...rest } = c;  // strip computed probe fields + v0.x resumeArgs
-    return {
+    const normalized = {
       ...rest,
       args: Array.isArray(rest.args) ? rest.args : [],
       resumeIdArgs: Array.isArray(rest.resumeIdArgs) ? rest.resumeIdArgs : [],
@@ -161,6 +161,25 @@ function mergeWithDefaults(partial) {
       type: ['claude', 'codex', 'copilot', 'other'].includes(rest.type) ? rest.type : 'other',
       builtin: !!rest.builtin,
     };
+    // Type-based fallback for non-builtin CLIs (wrappers like `ccp`
+    // that just call claude under the hood). If user picked
+    // type='claude' but left newSessionIdArgs / resumeIdArgs blank,
+    // assume they want the same args claude / copilot / codex use
+    // canonically — without this the wrapped CLI gets spawned with
+    // no UUID and ccsm can never recapture the upstream session.
+    // Builtins are already handled by the loop above with `def`.
+    if (!normalized.builtin && normalized.type !== 'other') {
+      const template = DEFAULT_CLIS.find((d) => d.type === normalized.type);
+      if (template) {
+        if (normalized.newSessionIdArgs.length === 0) {
+          normalized.newSessionIdArgs = [...template.newSessionIdArgs];
+        }
+        if (normalized.resumeIdArgs.length === 0) {
+          normalized.resumeIdArgs = [...template.resumeIdArgs];
+        }
+      }
+    }
+    return normalized;
   });
   // Make sure defaultCliId points at an actual CLI; fall back to first.
   if (!out.clis.find((c) => c.id === out.defaultCliId)) {

package/lib/folders.js

@@ -16,15 +16,30 @@ const { atomicWriteJson, withFileLock } = require('./atomicJson');
 
 const FILE = path.join(DATA_DIR, 'folders.json');
 
+// Sentinel for the synthetic "Unsorted" folder. Sessions with
+// folderId === null render under it. We always materialize it in the
+// returned list so the sidebar can drag-reorder it like a real folder,
+// but create/update/delete refuse to touch it.
+const UNSORTED_ID = 'unsorted';
+function unsortedDefault(order) {
+  return { id: UNSORTED_ID, name: 'Unsorted', order, builtin: true };
+}
+
 async function loadAll() {
+  let list = [];
   try {
     const raw = await fs.readFile(FILE, 'utf8');
     const j = JSON.parse(raw);
-    return Array.isArray(j) ? j : [];
+    if (Array.isArray(j)) list = j;
   } catch (e) {
-    if (e.code === 'ENOENT') return [];
-    throw e;
+    if (e.code !== 'ENOENT') throw e;
   }
+  // Ensure the synthetic Unsorted entry is present. New install: append
+  // at the end. Existing install pre-Unsorted-draggable: same.
+  if (!list.find((f) => f.id === UNSORTED_ID)) {
+    list = list.concat(unsortedDefault(list.length));
+  }
+  return list;
 }
 
 async function saveAll(list) {
@@ -52,13 +67,16 @@ async function create({ name }) {
 }
 
 async function update(id, patch) {
+  if (id === UNSORTED_ID && typeof patch.name === 'string') {
+    throw new Error('cannot rename the Unsorted bucket');
+  }
   return withFileLock(FILE, async () => {
     const list = await loadAll();
     const idx = list.findIndex((f) => f.id === id);
     if (idx < 0) return null;
     // Allow rename + reorder, ignore other keys.
     const allowed = {};
-    if (typeof patch.name === 'string') allowed.name = patch.name.trim();
+    if (id !== UNSORTED_ID && typeof patch.name === 'string') allowed.name = patch.name.trim();
     if (typeof patch.order === 'number') allowed.order = patch.order;
     list[idx] = { ...list[idx], ...allowed };
     await saveAll(list);
@@ -67,6 +85,7 @@ async function update(id, patch) {
 }
 
 async function remove(id) {
+  if (id === UNSORTED_ID) throw new Error('cannot delete the Unsorted bucket');
   return withFileLock(FILE, async () => {
     const list = await loadAll();
     const idx = list.findIndex((f) => f.id === id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakapiano/ccsm",
-  "version": "0.16.0",
+  "version": "0.17.2",
   "description": "Claude Code Session Manager — Windows web UI to manage many concurrent claude sessions: live list, snapshot/restore, focus existing window, new session in an isolated workspace with repo clones",
   "license": "MIT",
   "main": "server.js",

package/public/css/feedback.css

@@ -301,3 +301,118 @@
   0%, 100% { box-shadow: 0 0 0 0 rgba(26, 24, 21, 0.25); }
   50%      { box-shadow: 0 0 0 4px rgba(26, 24, 21, 0); }
 }
+
+/* HealthOverlay reuses .offline-overlay / .offline-card above. The
+   only extra is the spinner shown during the "Checking…" phase — sized
+   to fill the .offline-brand slot in place of the BrandMark logo. */
+.health-spinner {
+  width: 36px;
+  height: 36px;
+  border: 3px solid var(--border);
+  border-top-color: var(--ink);
+  border-radius: 50%;
+  animation: health-spin 0.8s linear infinite;
+}
+@keyframes health-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* ── Keybinding recorder modal ───────────────────────────────────── */
+.kbd-recorder-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  background: rgba(26, 24, 21, 0.5);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  animation: kbd-rec-fade-in 0.16s ease-out;
+}
+@keyframes kbd-rec-fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+.kbd-recorder-card {
+  background: var(--bg-elev);
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  padding: 32px 40px;
+  min-width: 380px;
+  max-width: 520px;
+  text-align: center;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.18);
+  font-family: var(--body);
+}
+.kbd-recorder-label {
+  font-size: 12.5px;
+  color: var(--ink-mid);
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  margin-bottom: 6px;
+}
+.kbd-recorder-action {
+  font-size: 18px;
+  font-weight: 500;
+  letter-spacing: -0.01em;
+  color: var(--ink);
+  margin-bottom: 24px;
+}
+.kbd-recorder-keys {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  min-height: 48px;
+  margin-bottom: 20px;
+  flex-wrap: wrap;
+}
+.kbd-recorder-key {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 36px;
+  height: 36px;
+  padding: 0 10px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-bottom-width: 2px;
+  border-radius: 6px;
+  font-family: var(--mono);
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--ink);
+  animation: kbd-rec-pop 0.12s ease-out;
+}
+@keyframes kbd-rec-pop {
+  from { transform: scale(0.85); opacity: 0.4; }
+  to   { transform: scale(1);    opacity: 1; }
+}
+.kbd-recorder-plus {
+  color: var(--ink-muted);
+  font-size: 14px;
+  font-weight: 300;
+}
+.kbd-recorder-placeholder {
+  color: var(--ink-muted);
+  font-size: 13px;
+}
+.kbd-recorder-actions {
+  display: flex;
+  justify-content: center;
+  gap: 8px;
+  margin-bottom: 14px;
+}
+.kbd-recorder-hint {
+  font-size: 11.5px;
+  color: var(--ink-muted);
+}
+.kbd-recorder-hint kbd {
+  font-family: var(--mono);
+  font-size: 11px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 3px;
+  padding: 1px 5px;
+}

package/public/css/sidebar.css

@@ -545,6 +545,23 @@ body.is-resizing-sidebar * {
   background: var(--sidebar-active);
   font-weight: 500;
 }
+/* Drop-line shown above the row when a sibling session is being
+   dragged over it for within-folder reorder. Top-only inset shadow
+   reads as a 2px insertion mark without shifting layout. */
+.tree-session.is-reorder-target {
+  position: relative;
+}
+.tree-session.is-reorder-target::before {
+  content: "";
+  position: absolute;
+  top: -1px;
+  left: 4px;
+  right: 4px;
+  height: 2px;
+  background: var(--ink-mid);
+  border-radius: 1px;
+  pointer-events: none;
+}
 /* Status dot · deliberately understated. The earlier version had a
    green dot + soft glow + expanding halo pulse; in a sidebar with
    eight running sessions it read as a row of strobing alerts. Now:

package/public/js/api.js

@@ -187,6 +187,11 @@ export async function setSessionFolder(sessionId, folderId) {
   await loadSessions();
 }
 
+export async function reorderSessions(folderId, ids) {
+  await api('POST', '/api/sessions/reorder', { folderId: folderId || null, ids });
+  await loadSessions();
+}
+
 export async function setSessionTitle(sessionId, title) {
   await api('PUT', `/api/sessions/${sessionId}`, { title });
   await loadSessions();
@@ -280,6 +285,7 @@ export async function restartBackend() {
   return api('POST', '/api/restart');
 }
 
+let consecutiveOffline = 0;
 export async function pollHealth() {
   const ctrl = new AbortController();
   const t = setTimeout(() => ctrl.abort(), 3000);
@@ -287,9 +293,16 @@ export async function pollHealth() {
     const r = await fetch(httpBase() + '/api/health', { signal: ctrl.signal });
     if (!r.ok) throw new Error(`HTTP ${r.status}`);
     const j = await r.json();
-    S.serverHealth.value = { state: 'online', version: j.version, pid: j.pid };
+    consecutiveOffline = 0;
+    S.serverHealth.value = { state: 'online', version: j.version, pid: j.pid, failureCount: 0 };
+    if (!S.hasBootedOnline.value) S.hasBootedOnline.value = true;
   } catch (e) {
-    S.serverHealth.value = { state: 'offline', error: String(e.message || e) };
+    consecutiveOffline++;
+    S.serverHealth.value = {
+      state: 'offline',
+      error: String(e.message || e),
+      failureCount: consecutiveOffline,
+    };
   } finally {
     clearTimeout(t);
   }

package/public/js/components/App.js

@@ -3,7 +3,7 @@ import { activeTab } from '../state.js';
 import { Sidebar } from './Sidebar.js';
 import { Toast } from './Toast.js';
 import { DialogHost } from './DialogHost.js';
-import { OfflineBanner } from './OfflineBanner.js';
+import { HealthOverlay } from './HealthOverlay.js';
 import { SessionsPage } from '../pages/SessionsPage.js';
 import { LaunchPage } from '../pages/LaunchPage.js';
 import { ConfigurePage } from '../pages/ConfigurePage.js';
@@ -28,8 +28,8 @@ export function App() {
           ${tab === 'about'     ? html`<${Panel} name="about"><${AboutPage}     /></${Panel}>` : null}
         </div>
       </main>
-      <${OfflineBanner} />
       <${Toast} />
       <${DialogHost} />
+      <${HealthOverlay} />
     </div>`;
 }

package/public/js/components/EntityFormModal.js

@@ -26,7 +26,19 @@ export function EntityFormModal({
   const [testing, setTesting] = useState(false);
   const [testResult, setTestResult] = useState(null);
 
-  const isReadOnly = (key) => readOnlyKeys.includes(key);
+  // A field is read-only if its key is in the static `readOnlyKeys`
+  // prop OR its own `readOnly` predicate (called with the current
+  // draft) returns true. The predicate lets a field react to other
+  // fields' values — e.g. lock newSessionIdArgs once a known `type`
+  // is picked, since those args are an integration contract with the
+  // upstream CLI, not a user knob.
+  const isReadOnly = (field) => {
+    if (readOnlyKeys.includes(field.key)) return true;
+    if (typeof field.readOnly === 'function') {
+      try { return !!field.readOnly(draft); } catch { return false; }
+    }
+    return !!field.readOnly;
+  };
 
   const submit = async (ev) => {
     ev?.preventDefault?.();
@@ -61,7 +73,7 @@ export function EntityFormModal({
             <span class="entity-field-label">${f.label}</span>
             ${f.type === 'select' ? html`
               <select class="input" value=${draft[f.key] || ''}
-                      disabled=${isReadOnly(f.key)}
+                      disabled=${isReadOnly(f)}
                       onChange=${(e) => {
                         const next = { ...draft, [f.key]: e.target.value };
                         const sideEffects = f.onChange?.(e.target.value, next);
@@ -71,13 +83,13 @@ export function EntityFormModal({
                   <option value=${opt.value}>${opt.label}</option>`)}
               </select>
             ` : f.type === 'iconRadio' ? html`
-              <div class=${`icon-radio${isReadOnly(f.key) ? ' is-disabled' : ''}`}>
+              <div class=${`icon-radio${isReadOnly(f) ? ' is-disabled' : ''}`}>
                 ${(f.options || []).map((opt) => html`
                   <button type="button" key=${opt.value}
                           class=${`icon-radio-opt${draft[f.key] === opt.value ? ' is-active' : ''}`}
-                          disabled=${isReadOnly(f.key)}
+                          disabled=${isReadOnly(f)}
                           onClick=${() => {
-                            if (isReadOnly(f.key)) return;
+                            if (isReadOnly(f)) return;
                             const next = { ...draft, [f.key]: opt.value };
                             const sideEffects = f.onChange?.(opt.value, next);
                             setDraft(sideEffects ? { ...next, ...sideEffects } : next);
@@ -89,20 +101,20 @@ export function EntityFormModal({
             ` : f.type === 'checkbox' ? html`
               <span class="entity-checkbox-row">
                 <input type="checkbox" checked=${!!draft[f.key]}
-                       disabled=${isReadOnly(f.key)}
+                       disabled=${isReadOnly(f)}
                        onChange=${(e) => setDraft({ ...draft, [f.key]: e.target.checked })} />
-                ${f.hint ? html`<span class="entity-field-hint">${f.hint}</span>` : null}
+                ${f.hint ? html`<span class="entity-field-hint">${typeof f.hint === 'function' ? f.hint(draft) : f.hint}</span>` : null}
               </span>
             ` : html`
               <input type=${f.type || 'text'}
                      class=${`input${f.mono ? ' mono' : ''}`}
                      placeholder=${f.placeholder || ''}
                      value=${draft[f.key] || ''}
-                     readonly=${isReadOnly(f.key)}
+                     readonly=${isReadOnly(f)}
                      onInput=${(e) => setDraft({ ...draft, [f.key]: e.target.value })}
-                     autoFocus=${f.autoFocus && !isReadOnly(f.key)} />`}
+                     autoFocus=${f.autoFocus && !isReadOnly(f)} />`}
             ${f.hint && f.type !== 'checkbox' ? html`
-              <span class="entity-field-hint">${f.hint}</span>` : null}
+              <span class="entity-field-hint">${typeof f.hint === 'function' ? f.hint(draft) : f.hint}</span>` : null}
           </label>`)}
         ${testResult ? html`
           <div class=${`entity-test-result ${testResult.ok ? 'is-ok' : 'is-fail'}`}>

package/public/js/components/HealthOverlay.js

@@ -0,0 +1,91 @@
+// Full-screen modal shown while the backend is unreachable.
+//
+// Two phases:
+//   - Early (failureCount < THRESHOLD): "Checking backend health…" with
+//     a spinner. Most outages resolve in one or two ticks — no need to
+//     scare the user.
+//   - Persistent (failureCount >= THRESHOLD): "Backend not running.
+//     Start backend" with a button that fires the ccsm:// protocol so
+//     Windows' registered launcher.vbs spawns ccsm.
+//
+// We never auto-resume. The user has to click the button — protects
+// against repeated wake attempts during an in-flight upgrade or a
+// crash loop.
+//
+// While offline we drive a faster (1.5s) poll loop directly so the
+// modal dismisses promptly when the backend comes back, without
+// waiting for the main 5s refresh interval.
+
+import { html } from '../html.js';
+import { useEffect } from 'preact/hooks';
+import { serverHealth, hasBootedOnline } from '../state.js';
+import { pollHealth, refreshAll } from '../api.js';
+import { BrandMark } from '../icons.js';
+
+const THRESHOLD = 3;     // failures before we switch from "checking" to "not running"
+const FAST_POLL_MS = 1500;
+
+export function HealthOverlay() {
+  const h = serverHealth.value;
+  const offline = h.state === 'offline';
+  const count = h.failureCount || 0;
+  const everSeen = hasBootedOnline.value;
+
+  useEffect(() => {
+    if (!offline) return;
+    const id = setInterval(() => { pollHealth(); }, FAST_POLL_MS);
+    return () => clearInterval(id);
+  }, [offline]);
+
+  useEffect(() => {
+    if (!offline && everSeen) {
+      refreshAll().catch(() => {});
+    }
+  }, [offline]);
+
+  if (!offline || !everSeen) return null;
+
+  const showStart = count >= THRESHOLD;
+
+  // Reuses the .offline-overlay / .offline-card classes so the card
+  // layout (brand mark, big title, copy, primary action button,
+  // collapsible npm-install fallback) matches what the OfflineBanner
+  // used to render. HealthOverlay differs only in the two states:
+  // early polls show a spinner + "Checking…" instead of the static
+  // "Backend not running" card.
+  return html`
+    <div class="offline-overlay" role="dialog" aria-modal="true" aria-live="polite">
+      <div class="offline-card">
+        <div class="offline-brand">${
+          showStart
+            ? html`<${BrandMark} />`
+            : html`<div class="health-spinner" aria-hidden="true"></div>`
+        }</div>
+        ${!showStart ? html`
+          <h1 class="offline-title">Checking backend health…</h1>
+          <p class="offline-copy">
+            ${count === 0 ? 'Probing localhost:7777.' : `${count} attempt${count > 1 ? 's' : ''}. Hang tight.`}
+          </p>
+        ` : html`
+          <h1 class="offline-title">Backend not running</h1>
+          <p class="offline-copy">
+            ccsm's local backend isn't reachable. Wake it manually below — we won't
+            auto-restart. Windows may ask once for permission; tick <em>Always allow</em>
+            to silence future prompts.
+          </p>
+          <div class="offline-actions">
+            <a class="action primary big" href="ccsm://start">Start backend</a>
+          </div>
+          <details class="offline-fallback">
+            <summary>Don't have ccsm installed?</summary>
+            <div class="offline-fallback-body">
+              <p>Install once via npm, then come back here:</p>
+              <pre><code>npm i -g @bakapiano/ccsm</code></pre>
+              <p>Or run a one-shot trial without installing:</p>
+              <pre><code>npx @bakapiano/ccsm</code></pre>
+            </div>
+          </details>
+        `}
+      </div>
+    </div>`;
+}

package/public/js/components/KeybindingRecorder.js

@@ -0,0 +1,138 @@
+// Full-screen modal that captures a key combo with a live preview of
+// what the user is currently holding. Click to record → push modifiers
+// in real time → release / press a non-modifier key to commit → close.
+// Esc with no modifiers cancels.
+
+import { html } from '../html.js';
+import { useEffect, useState } from 'preact/hooks';
+
+const MODIFIER_KEYS = new Set(['Control', 'Alt', 'Shift', 'Meta']);
+
+function modsFromEvent(ev) {
+  const out = [];
+  if (ev.ctrlKey)  out.push('Ctrl');
+  if (ev.altKey)   out.push('Alt');
+  if (ev.shiftKey) out.push('Shift');
+  if (ev.metaKey)  out.push('Meta');
+  return out;
+}
+
+function prettyKey(k) {
+  if (k === 'ArrowUp')    return '↑';
+  if (k === 'ArrowDown')  return '↓';
+  if (k === 'ArrowLeft')  return '←';
+  if (k === 'ArrowRight') return '→';
+  if (k === ' ')          return 'Space';
+  if (k === 'Escape')     return 'Esc';
+  if (/^[a-z]$/.test(k))  return k.toUpperCase();
+  return k;
+}
+
+export function KeybindingRecorder({ actionLabel, onCommit, onCancel }) {
+  // While `captured` is null, we're listening — display reflects whatever
+  // is currently held. Once a non-modifier key lands, we freeze that
+  // combo into `captured` and surface explicit Confirm / Try again
+  // buttons. Pressing another non-modifier key replaces the captured
+  // combo (useful when the user mis-pressed and wants to retry without
+  // clicking).
+  const [mods, setMods] = useState([]);
+  const [captured, setCaptured] = useState(null);
+
+  useEffect(() => {
+    const onDown = (ev) => {
+      ev.preventDefault();
+      ev.stopPropagation();
+
+      // Esc with no modifiers = cancel. Esc-as-shortcut is allowed when
+      // any modifier is also held.
+      if (ev.key === 'Escape' && !ev.ctrlKey && !ev.altKey && !ev.shiftKey && !ev.metaKey) {
+        onCancel();
+        return;
+      }
+
+      // Enter while a combo is captured = confirm (so the user can finish
+      // with a single hand on the keyboard, no mouse round-trip).
+      if (ev.key === 'Enter' && captured && !ev.ctrlKey && !ev.altKey && !ev.shiftKey && !ev.metaKey) {
+        onCommit(captured);
+        return;
+      }
+
+      const currentMods = modsFromEvent(ev);
+      if (MODIFIER_KEYS.has(ev.key)) {
+        setMods(currentMods);
+        return;
+      }
+
+      // Real key landed — freeze it; user still has to confirm.
+      let k = ev.key;
+      if (/^[a-z]$/.test(k)) k = k.toUpperCase();
+      const combo = [...currentMods, k].join('+');
+      setCaptured(combo);
+    };
+
+    const onUp = (ev) => {
+      setMods(modsFromEvent(ev));
+    };
+
+    window.addEventListener('keydown', onDown, true);
+    window.addEventListener('keyup', onUp, true);
+    return () => {
+      window.removeEventListener('keydown', onDown, true);
+      window.removeEventListener('keyup', onUp, true);
+    };
+  }, [onCommit, onCancel, captured]);
+
+  // The keys shown in the keycap row. While listening: live modifier
+  // state + last-pressed key (if captured replaced live state). When
+  // captured: parse the frozen combo back into parts so we show the
+  // exact thing about to be saved.
+  let parts;
+  if (captured) {
+    parts = captured.split('+');
+  } else {
+    parts = [...mods];
+  }
+
+  return html`
+    <div class="kbd-recorder-overlay" role="dialog" aria-modal="true"
+         onClick=${onCancel}>
+      <div class="kbd-recorder-card" onClick=${(ev) => ev.stopPropagation()}>
+        <div class="kbd-recorder-label">
+          ${captured ? 'Captured shortcut for' : 'Press a shortcut for'}
+        </div>
+        <div class="kbd-recorder-action">${actionLabel}</div>
+
+        <div class="kbd-recorder-keys">
+          ${parts.length === 0
+            ? html`<span class="kbd-recorder-placeholder">Press any key combo…</span>`
+            : parts.map((p, i) => html`
+                <span class="kbd-recorder-key" key=${i}>${prettyKey(p)}</span>
+                ${i < parts.length - 1
+                  ? html`<span class="kbd-recorder-plus">+</span>`
+                  : null}
+              `)}
+        </div>
+
+        ${captured ? html`
+          <div class="kbd-recorder-actions">
+            <button class="action small subtle" onClick=${() => setCaptured(null)}>
+              Try again
+            </button>
+            <button class="action small subtle" onClick=${onCancel}>
+              Cancel
+            </button>
+            <button class="action small primary" onClick=${() => onCommit(captured)}>
+              Confirm
+            </button>
+          </div>
+          <div class="kbd-recorder-hint">
+            <kbd>Enter</kbd> to confirm · <kbd>Esc</kbd> to cancel · press another combo to replace
+          </div>
+        ` : html`
+          <div class="kbd-recorder-hint">
+            <kbd>Esc</kbd> to cancel · click outside to dismiss
+          </div>
+        `}
+      </div>
+    </div>`;
+}