better gitignore

.helder/.gitignore

@@ -1,2 +1,2 @@
-# Helder — local, machine-specific state (do not commit)
+# Helder — local, machine-specific state (do not commit).
-recent.json
+*

OVERNIGHT.md

@@ -1,75 +0,0 @@
-# Overnight work log
-
-Autonomous session continuing the Helder build while you slept. Everything kept
-compiling (`npm run build`), type-checking (`npm run typecheck`) and — new this
-session — passing tests (`npm run test`). Git left uncommitted for you to review.
-
-## Plan
-1. Packaging (electron-builder)
-2. Automated test suite (vitest)
-3. Lint + format (eslint + prettier)
-4. Robustness + feature polish
-5. Developer README
-
-## Progress
-
-### 1. Packaging — done
-- Added `electron-builder.yml` (appId `com.blijnder.helder`, mac dmg+zip / win nsis / linux AppImage, unsigned local build).
-- Scripts: `npm run pack` (`--dir`), `npm run dist`, `npm run dist:mac`.
-- Made the bundled ripgrep path asar-safe (redirect to `app.asar.unpacked`).
-- `asarUnpack` for `node-pty` + `@vscode/ripgrep` so the native `.node` and `rg` binary load at runtime.
-- Verified: `npm run pack` produced `dist/mac-arm64/Helder.app` (245 MB) with `pty.node` + `rg` correctly unpacked. Unsigned (ad-hoc), default icon. `dist/` gitignored.
-
-### 2. Automated tests — done (vitest)
-- Added vitest + `vitest.config.ts`; scripts `npm run test` / `test:watch`. **38 tests, all green.**
-- `test/diff.test.ts` — LCS diff: no-change, single change, new/deleted file, side marks, split alignment, trailing-newline.
-- `test/fuzzy.test.ts` — subsequence matcher (extracted to `src/renderer/src/fuzzy.ts`).
-- `test/highlight.test.ts` — ext/lang/label/icon/escape + Prism php highlighting (confirms markup-templating load order).
-- `test/config.test.ts` — `.helder` defaults regen, sparse deep-merge, theme.css not overwritten.
-- `test/fs.test.ts` — tree dirs-first + ignore dirs, content index skips binaries/node_modules, read/write round-trip.
-- `test/git.test.ts` — `classify` unit + real temp-repo integration (modified/untracked/staged, HEAD-vs-worktree text).
-
-### 3. Lint + format — done
-- ESLint flat config (`eslint.config.js`): typescript-eslint recommended + react-hooks, prettier-disables, sensible ignores. `npm run lint` = **0 errors** (8 intentional exhaustive-deps warnings).
-- Fixed real `no-unused-expressions` violations (short-circuit/ternary-as-statement).
-- `.prettierrc.json` added (style: no-semi, single-quote, width 140). Not auto-applied to avoid churn.
-
-### 4. Robustness + feature polish — done
-- **Fixed a real `discard` bug**: `git checkout` can't remove a new/untracked file. `discard` now reverts modified→HEAD, restores deleted, and removes new/untracked (staged or not). Covered by new git tests.
-- **Close-tab guard**: confirms before closing a tab with unsaved edits (× / middle-click / ⌘W), and clears its buffer on close. Reads fresh state via refs so the ⌘W path is correct too.
-- **ErrorBoundary** around the whole app — a render fault shows a dark, recoverable panel (with the message + Reload) instead of a blank window.
-- **`editor.tabSize` wired** into the editable buffer (textarea + highlighted pre) and the status bar — config now visibly does something.
-- **Layout persistence**: the three column widths + the terminal split fraction persist across launches via localStorage (`persist.ts`), making the README's "positions persist across launches" claim true.
-
-### 5. Developer docs + icon — done
-- `README.md` updated from "greenfield" to the real working build: getting-started, scripts table, repository layout.
-- App icon generated from Helder's spark mark → `build/icon.png` (1024²); electron-builder embeds `icon.icns` in the packaged app (verified).
-
-### 6. Renderer component tests + CI — done
-- Added jsdom + `@testing-library/react`; the terminals (xterm) are mocked so tests stay deterministic.
-- `test/app.test.tsx` — workbench renders, open changed file → diff tab, edit → dirty tab, content search returns hits.
-- `test/app-interactions.test.tsx` — **Pass-on-to-Agent** emits exactly `"<note> <path:line>"` via the `agentPaste` event; **stage → commit** toasts.
-- `test/editor-modes.test.tsx` — Updated mode is editable / Original is read-only; Split opens the two-pane overlay and Esc collapses it.
-- **49 tests total, all green.**
-- `.github/workflows/ci.yml` — runs typecheck · lint · test · build on push/PR.
-
-### 7. Finish to the DESIGN.md spec — done
-Audited `DESIGN.md` section by section and closed every remaining behavioral gap:
-- **Session restore** (`session.restoreOnLaunch`, §9) — open tabs, active tab, and per-tab view modes are restored per project (persisted in localStorage, keyed by root); splitter layout already persisted.
-- **Close-dirty tab** (§5) — now a real **Save / Don't Save / Cancel** native dialog (was discard-or-cancel). `⌘S` save unchanged.
-- **Unsaved indicator** (§5) — a **dot in place of the close control** (× returns on hover), matching the spec exactly (was a dot after the name).
-- **New config keys, all wired**: `git.confirmStage` / `git.confirmUnstage` (default off, prompt when on), `git.defaultDiffMode` (drives the starting mode), `files.exclude` + `files.followGitignore`, `session.restoreOnLaunch`.
-- **Unified file source**: `rg --files` is now the single source for the **Explorer tree + content index + search**, so **gitignore and `files.exclude` are honored consistently everywhere** (fs-walk fallback when ripgrep is absent). Dotfiles (`.env`, `.gitignore`) included via `--hidden`.
-- **⌘P** aliases the unified search — no separate Go-to-File overlay, per the resolved decision (CLAUDE.md/README).
-- Tests now **51** (added `buildTreeFromPaths`, gitignore-in-repo, updated dirty-tab class).
-
-### 8. Live-run bugfix (found by running `npm run dev`)
-- **Symptom:** the real Electron window showed mock "console" data and both terminals said "not available in browser preview" — i.e. `window.helder` was undefined in the actual app, so the renderer fell back to mock mode.
-- **Cause:** electron-vite built the preload as `out/preload/index.mjs`, but `main/index.ts` loaded `../preload/index.js` (wrong extension) → Electron silently loaded no preload → no bridge.
-- **Fix:** build the preload as **CommonJS `index.cjs`** (loads synchronously before the page, so `contextBridge` is exposed by the time React mounts) and point `main` at `../preload/index.cjs`. Verified the built `index.cjs` exposes `helder` and main references it. **Re-run `npm run dev` to confirm the live window now loads the real project + terminals.**
-
-## Final state (all green)
-- `npm run typecheck` ✓ · `npm run lint` ✓ (0 errors, 8 intentional warnings) · `npm test` ✓ (51) · `npm run build` ✓ · `npm run pack` ✓ (`Helder.app` with icon + unpacked native binaries)
-- **DESIGN.md is now fully implemented** (the only intentional exception is the separate Go-to-File overlay, replaced by ⌘P→unified-search per the resolved decision).
-- Everything left **uncommitted** for your review (laptop is read-only on git).
-- The only thing not exercisable in this headless session remains the live Electron GUI — `npm run dev` to see it.

electron-builder.yml

@@ -8,9 +8,12 @@ files:
   - out/**
   - package.json
 # Native / spawned binaries must live outside the asar to load at runtime.
+# The rg binary ships in a platform package (@vscode/ripgrep-<platform>-<arch>),
+# so that must be unpacked too — not just the @vscode/ripgrep shim.
 asarUnpack:
   - '**/node_modules/node-pty/**'
   - '**/node_modules/@vscode/ripgrep/**'
+  - '**/node_modules/@vscode/ripgrep-*/**'
 mac:
   category: public.app-category.developer-tools
   target:

src/main/config.ts

@@ -49,19 +49,22 @@ const THEME_TEMPLATE = `/* Helder theme — custom CSS applied OVER the built-in
 /** Recently-opened files, newest first. Local machine state — git-ignored. */
 const RECENT_FILE = 'recent.json'
 const MAX_RECENT = 100
-const GITIGNORE_BODY = `# Helder — local, machine-specific state (do not commit)\n${RECENT_FILE}\n`
+// The whole .helder folder is local, machine-specific state — ignore all of it.
+const GITIGNORE_BODY = `# Helder — local, machine-specific state (do not commit).\n*\n`
 
 let current: HelderConfig = DEFAULTS
 let themeCss = ''
 
-/** Create `.helder/.gitignore` (ignoring recent.json) only when it's missing. */
+/** Ensure `.helder/.gitignore` ignores the entire folder; (re)write it when the
+ * file is missing or out of date (e.g. upgrading from the old recent-only one). */
 async function ensureGitignore(dir: string): Promise<void> {
   const path = join(dir, '.gitignore')
   try {
-    await readFile(path, 'utf8')
+    if ((await readFile(path, 'utf8')) === GITIGNORE_BODY) return
   } catch {
-    await writeFile(path, GITIGNORE_BODY)
+    /* missing — fall through to write */
   }
+  await writeFile(path, GITIGNORE_BODY)
 }
 
 export async function getRecent(root: string): Promise<string[]> {

src/main/fs-service.ts

@@ -1,4 +1,4 @@
-import { readdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { readdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { join, relative, sep } from 'node:path'
 import { listFiles } from './search-service'
 
@@ -120,6 +120,13 @@ export async function writeProjectFile(root: string, rel: string, content: strin
   await writeFile(join(root, rel), content, 'utf8')
 }
 
+/** Delete a project file or folder (relative path). Stays inside the project root. */
+export async function deleteProjectFile(root: string, rel: string): Promise<void> {
+  const target = join(root, rel)
+  if (relative(root, target).startsWith('..')) return // guard against escaping the root
+  await rm(target, { recursive: true, force: true })
+}
+
 /**
  * In-memory content index of all (small, text) files — powers content viewing.
  * Primary: read the rg file list; fallback: walk. Capped for large repos.

src/main/index.ts

@@ -1,8 +1,8 @@
 import { join, sep } from 'node:path'
 import { app, dialog, shell, BrowserWindow, ipcMain, Menu } from 'electron'
 import { watch, type FSWatcher } from 'chokidar'
-import { getName, getRoot, openDialog } from './project'
+import { addRecentProject, getName, getRecentProjects, getRoot, openDialog, setRoot } from './project'
-import { readAll, readProjectFile, readTree, writeProjectFile } from './fs-service'
+import { deleteProjectFile, readAll, readProjectFile, readTree, writeProjectFile } from './fs-service'
 import { commit, discard, load, stage, unstage } from './git-service'
 import { createPty, killAllPtys, killPty, ptyAvailable, resizePty, writePty } from './pty-service'
 import { getConfig, getRecent, getThemeCss, resolveConfig, setRecent } from './config'
@@ -39,7 +39,7 @@ function startConfigWatcher(): void {
 async function openFolderFlow(win: BrowserWindow | null): Promise<boolean> {
   const next = await openDialog(win)
   if (!next) return false
-  await resolveConfig(getRoot())
+  await resolveConfig(next)
   startWatcher()
   startConfigWatcher()
   return true
@@ -91,17 +91,27 @@ function registerIpc(): void {
     await openFolderFlow(BrowserWindow.fromWebContents(e.sender))
     return { root: getRoot(), name: getName() }
   })
+  ipcMain.handle('projects:recent', () => getRecentProjects())
+  ipcMain.handle('project:openPath', async (_e, path: string) => {
+    setRoot(path)
+    const r = getRoot()
+    if (r) { await resolveConfig(r); startWatcher(); startConfigWatcher() }
+    broadcast('project:changed')
+    return { root: getRoot(), name: getName() }
+  })
 
-  ipcMain.handle('fs:tree', () => readTree(getRoot()))
+  ipcMain.handle('fs:tree', () => { const r = getRoot(); return r ? readTree(r) : null })
-  ipcMain.handle('fs:files', () => readAll(getRoot()))
+  ipcMain.handle('fs:files', () => { const r = getRoot(); return r ? readAll(r) : {} })
-  ipcMain.handle('fs:read', (_e, rel: string) => readProjectFile(getRoot(), rel))
+  ipcMain.handle('fs:read', (_e, rel: string) => { const r = getRoot(); return r ? readProjectFile(r, rel) : '' })
-  ipcMain.handle('fs:write', (_e, rel: string, content: string) => writeProjectFile(getRoot(), rel, content))
+  ipcMain.handle('fs:write', (_e, rel: string, content: string) => { const r = getRoot(); if (r) return writeProjectFile(r, rel, content) })
+  ipcMain.handle('fs:delete', (_e, rel: string) => { const r = getRoot(); if (r) return deleteProjectFile(r, rel) })
+  ipcMain.handle('shell:reveal', (_e, rel: string) => { const r = getRoot(); if (r) shell.showItemInFolder(join(r, rel)) })
 
-  ipcMain.handle('git:load', () => load(getRoot()))
+  ipcMain.handle('git:load', () => { const r = getRoot(); return r ? load(r) : null })
-  ipcMain.handle('git:stage', (_e, paths: string[]) => stage(getRoot(), paths))
+  ipcMain.handle('git:stage', (_e, paths: string[]) => { const r = getRoot(); if (r) return stage(r, paths) })
-  ipcMain.handle('git:unstage', (_e, paths: string[]) => unstage(getRoot(), paths))
+  ipcMain.handle('git:unstage', (_e, paths: string[]) => { const r = getRoot(); if (r) return unstage(r, paths) })
-  ipcMain.handle('git:commit', (_e, message: string) => commit(getRoot(), message))
+  ipcMain.handle('git:commit', (_e, message: string) => { const r = getRoot(); if (r) return commit(r, message) })
-  ipcMain.handle('git:discard', (_e, paths: string[]) => discard(getRoot(), paths))
+  ipcMain.handle('git:discard', (_e, paths: string[]) => { const r = getRoot(); if (r) return discard(r, paths) })
 
   ipcMain.handle('pty:available', () => ptyAvailable())
   ipcMain.handle('pty:create', (e, kind: 'agent' | 'shell', cols: number, rows: number) => createPty(e.sender, kind, cols, rows))
@@ -112,11 +122,11 @@ function registerIpc(): void {
   ipcMain.handle('config:get', () => getConfig())
   ipcMain.handle('config:theme', () => getThemeCss())
 
-  ipcMain.handle('recent:get', () => getRecent(getRoot()))
+  ipcMain.handle('recent:get', () => { const r = getRoot(); return r ? getRecent(r) : [] })
-  ipcMain.handle('recent:set', (_e, list: string[]) => setRecent(getRoot(), list))
+  ipcMain.handle('recent:set', (_e, list: string[]) => { const r = getRoot(); if (r) return setRecent(r, list) })
 
-  ipcMain.handle('search:content', (_e, query: string) => searchContent(getRoot(), query))
+  ipcMain.handle('search:content', (_e, query: string) => { const r = getRoot(); return r ? searchContent(r, query) : [] })
-  ipcMain.handle('search:files', () => listFiles(getRoot()))
+  ipcMain.handle('search:files', () => { const r = getRoot(); return r ? listFiles(r) : [] })
 
   ipcMain.handle('dialog:unsavedClose', async (e, path: string) => {
     const win = BrowserWindow.fromWebContents(e.sender)
@@ -169,9 +179,13 @@ app.whenReady().then(async () => {
   app.setName('Helder')
   Menu.setApplicationMenu(buildAppMenu())
   registerIpc()
-  await resolveConfig(getRoot())
+  const initialRoot = getRoot()
-  startWatcher()
+  if (initialRoot) {
-  startConfigWatcher()
+    await resolveConfig(initialRoot)
+    await addRecentProject(initialRoot)
+    startWatcher()
+    startConfigWatcher()
+  }
   createWindow()
 
   app.on('activate', () => {

src/main/project.ts

@@ -1,40 +1,43 @@
-import { basename, resolve } from 'node:path'
+import { basename, join, resolve } from 'node:path'
 import { existsSync, statSync } from 'node:fs'
-import { dialog, BrowserWindow } from 'electron'
+import { readFile, writeFile } from 'node:fs/promises'
+import { app, dialog, BrowserWindow } from 'electron'
 
 /**
- * One project per window. The root is resolved (in order) from $HELDER_PROJECT,
+ * One project per window. The root is resolved (in order) from $HELDER_PROJECT or
- * a directory passed on argv, or the process working directory — then it can be
+ * a directory passed on argv; otherwise it starts as `null` — the app then shows
- * changed at runtime via the Open Folder dialog.
+ * the project launcher (Spotlight / bare launch with no folder). It can be set at
+ * runtime from the launcher or the Open Folder dialog.
  *
- * Always store an absolute path: in dev the app is launched as `electron .`, so
+ * The bare "." that `electron .` passes in dev is intentionally ignored, so dev
- * argv carries a bare "." — `basename(".")` is "." (the repo name would show as a
+ * launches land on the launcher too (and `basename(".")` never leaks as a name).
- * lone dot). `resolve()` turns it into the real directory before we name it.
  */
-function resolveInitialRoot(): string {
+function resolveInitialRoot(): string | null {
   const envRoot = process.env.HELDER_PROJECT
-  if (envRoot && existsSync(envRoot) && statSync(envRoot).isDirectory()) return resolve(envRoot)
+  if (envRoot && safeIsDir(envRoot)) return resolve(envRoot)
-  const argDir = process.argv.slice(1).find((a) => !a.startsWith('-') && existsSync(a) && safeIsDir(a))
+  const argDir = process.argv.slice(1).find((a) => a !== '.' && !a.startsWith('-') && safeIsDir(a))
   if (argDir) return resolve(argDir)
-  return process.cwd()
+  return null
 }
 
 function safeIsDir(p: string): boolean {
   try { return statSync(p).isDirectory() } catch { return false }
 }
 
-let root = resolveInitialRoot()
+let root: string | null = resolveInitialRoot()
 
-export function getRoot(): string {
+export function getRoot(): string | null {
   return root
 }
 
 export function getName(): string {
-  return root ? basename(root) || root : 'no project'
+  return root ? basename(root) || root : ''
 }
 
+/** Point the window at a project root (absolute) and remember it in recents. */
 export function setRoot(next: string): void {
   root = resolve(next)
+  addRecentProject(root).catch(() => {})
 }
 
 export async function openDialog(win: BrowserWindow | null): Promise<string | null> {
@@ -42,8 +45,41 @@ export async function openDialog(win: BrowserWindow | null): Promise<string | nu
     ? await dialog.showOpenDialog(win, { properties: ['openDirectory'] })
     : await dialog.showOpenDialog({ properties: ['openDirectory'] })
   if (!res.canceled && res.filePaths[0]) {
-    root = res.filePaths[0]
+    setRoot(res.filePaths[0])
     return root
   }
   return null
 }
+
+// ---- recent projects (global, machine-wide — stored in Electron userData) ------
+export interface RecentProject { path: string; name: string }
+const MAX_PROJECTS = 20
+
+function projectsFile(): string {
+  return join(app.getPath('userData'), 'recent-projects.json')
+}
+
+export async function getRecentProjects(): Promise<RecentProject[]> {
+  try {
+    const arr = JSON.parse(await readFile(projectsFile(), 'utf8'))
+    if (!Array.isArray(arr)) return []
+    return arr
+      .filter((p): p is RecentProject => !!p && typeof p.path === 'string')
+      .filter((p) => existsSync(p.path)) // drop projects that no longer exist
+      .slice(0, MAX_PROJECTS)
+  } catch {
+    return []
+  }
+}
+
+export async function addRecentProject(path: string): Promise<void> {
+  try {
+    const abs = resolve(path)
+    const list = await getRecentProjects()
+    const entry: RecentProject = { path: abs, name: basename(abs) || abs }
+    const next = [entry, ...list.filter((x) => x.path !== abs)].slice(0, MAX_PROJECTS)
+    await writeFile(projectsFile(), JSON.stringify(next, null, 2) + '\n')
+  } catch {
+    /* userData unwritable — recents just won't persist */
+  }
+}

src/preload/index.ts

@@ -15,6 +15,8 @@ const api = {
   project: {
     current: () => ipcRenderer.invoke('project:current'),
     open: () => ipcRenderer.invoke('project:open'),
+    openPath: (path: string) => ipcRenderer.invoke('project:openPath', path),
+    recent: (): Promise<{ path: string; name: string }[]> => ipcRenderer.invoke('projects:recent'),
   },
 
   fs: {
@@ -22,6 +24,11 @@ const api = {
     files: () => ipcRenderer.invoke('fs:files'),
     read: (path: string) => ipcRenderer.invoke('fs:read', path),
     write: (path: string, content: string): Promise<void> => ipcRenderer.invoke('fs:write', path, content),
+    delete: (path: string): Promise<void> => ipcRenderer.invoke('fs:delete', path),
+  },
+
+  shell: {
+    reveal: (path: string): void => { ipcRenderer.invoke('shell:reveal', path) },
   },
 
   git: {

src/renderer/src/App.tsx

@@ -5,7 +5,8 @@ import type { ContextTarget } from './components'
 import { Editor, SplitView } from './editor'
 import type { Cursor, Mode, Selection } from './editor'
 import { Terminal, lid } from './terminals'
-import { ContextMenu, HistoryModal, PassPopup, SearchModal, Toasts } from './overlays'
+import { ConfirmModal, ContextMenu, HelpModal, HistoryModal, PassPopup, SearchModal, Toasts } from './overlays'
+import { ProjectLauncher } from './launcher'
 import type { Menu, Toast } from './overlays'
 import type { FileNode, GitStatus } from './types'
 import { useProject, useProjectActions } from './project'
@@ -84,7 +85,8 @@ export function App(): React.ReactElement {
   const [openDirs, setOpenDirs] = useState<Set<string>>(new Set())
   const [cursor, setCursor] = useState<Cursor | null>(null)
   const [selection, setSelection] = useState<Selection | null>(null)
-  const [overlay, setOverlay] = useState<'search' | 'history' | null>(null)
+  const [overlay, setOverlay] = useState<'search' | 'history' | 'help' | null>(null)
+  const [searchInit, setSearchInit] = useState('') // seed query for ⌘F-with-selection
   // Most-recently-opened files, newest first, de-duplicated. Drives the ⌘↓/⌘↑ navigator.
   const [history, setHistory] = useState<string[]>([])
   const [histInitSel, setHistInitSel] = useState(0)
@@ -93,6 +95,7 @@ export function App(): React.ReactElement {
   const [splitFor, setSplitFor] = useState<string | null>(null)
   const [commitMsg, setCommitMsg] = useState('')
   const [passPopup, setPassPopup] = useState<{ x: number; y: number; ref: string } | null>(null)
+  const [confirm, setConfirm] = useState<{ title: string; body?: string; confirmLabel: string; onConfirm: () => void } | null>(null)
   // Brief full-screen "branch - repository" flash whenever the window gains focus
   // (handy when juggling several project windows).
   const [showFlash, setShowFlash] = useState(false)
@@ -258,6 +261,35 @@ export function App(): React.ReactElement {
     setCommitMsg('')
   }
 
+  function revealInFinder(path: string): void {
+    window.helder?.shell.reveal(path)
+  }
+  // Delete a file or folder from disk, then drop anything inside it from the UI.
+  async function deleteEntry(path: string, isDir: boolean): Promise<void> {
+    const bridge = window.helder
+    if (bridge) {
+      try { await bridge.fs.delete(path) } catch { toast('Delete failed', path); return }
+    }
+    const inside = (p: string): boolean => p === path || (isDir && p.startsWith(path + '/'))
+    setHistory((h) => h.filter((p) => !inside(p)))
+    setBuffers((b) => {
+      const keys = Object.keys(b).filter(inside)
+      if (!keys.length) return b
+      const n = { ...b }; keys.forEach((k) => delete n[k]); return n
+    })
+    if (active && inside(active)) setActive(null)
+    actions.refresh()
+    toast(isDir ? 'Deleted folder' : 'Deleted file', path)
+  }
+  function askDelete(path: string, isDir: boolean): void {
+    setConfirm({
+      title: isDir ? 'Delete folder?' : 'Delete file?',
+      body: isDir ? `${path}/ and everything inside it will be permanently deleted.` : `${path} will be permanently deleted.`,
+      confirmLabel: 'Delete',
+      onConfirm: () => deleteEntry(path, isDir),
+    })
+  }
+
   const defaultMode: Mode = proj.config.git.defaultDiffMode
   function stageGuarded(p: string): void {
     if (proj.config.git.confirmStage && !window.confirm(`Stage ${p}?`)) return
@@ -280,18 +312,33 @@ export function App(): React.ReactElement {
     setTabMode((m) => ({ ...m, [path]: openMode }))
     reveal(path)
     if (opts.line) {
-      // show the current/updated file so line numbers map to search hits
+      // The updated/code views render in the CodeEditor (a textarea over a <pre>),
+      // so scroll its container to centre the target line. Line height is 20px with
+      // a 6px top pad; retry across a few frames until the content has rendered (the
+      // file may still be loading for a freshly-opened unchanged file).
       setSplitFor(null)
       setTabMode((m) => ({ ...m, [path]: changed ? 'updated' : 'code' }))
       setCursor({ path, line: opts.line, col: 1 })
       setSelection(null)
-      setTimeout(() => {
+      scrollEditorToLine(opts.line)
-        const row = document.querySelector('.editor .ln-row[data-line="' + opts.line + '"]') as HTMLElement | null
-        if (row) { const ed = row.closest('.editor') as HTMLElement; const er = ed.getBoundingClientRect(), rr = row.getBoundingClientRect(); ed.scrollTop += (rr.top - er.top) - ed.clientHeight / 2 }
-      }, 70)
     }
   }
 
+  function scrollEditorToLine(line: number): void {
+    const top = 6 + (line - 1) * 20
+    let tries = 0
+    const place = (): void => {
+      const sc = document.querySelector<HTMLElement>('.ce-scroll')
+      if (sc) {
+        sc.scrollTop = Math.max(0, top - sc.clientHeight / 2)
+        // stop once the content is tall enough to actually reach the line
+        if (sc.scrollHeight >= top + 4 || tries >= 40) return
+      }
+      if (tries++ < 40) requestAnimationFrame(place)
+    }
+    requestAnimationFrame(place)
+  }
+
   // Close the current file view (no tabs anymore — the recent-files list replaces
   // them). The file stays in history; ⌘W just clears the editor after a dirty check.
   async function closeTab(path: string): Promise<void> {
@@ -343,38 +390,137 @@ export function App(): React.ReactElement {
           items.push({ icon: Icon.discard(), label: 'Discard changes', onClick: () => doDiscard(target.path) })
         }
         items.push({ icon: Icon.file(), label: 'Open file', onClick: () => openFile(target.path) })
-        items.push({ icon: Icon.reveal(), label: 'Reveal in Explorer', onClick: () => reveal(target.path) })
+      }
+      // Show in Finder + delete — for explorer files and folders (not git rows).
+      if (isDir || target.kind === 'file') {
+        items.push({ sep: true })
+        items.push({ icon: Icon.finder(), label: 'Show in Finder', onClick: () => revealInFinder(target.path) })
+        items.push({ icon: Icon.trash(), label: isDir ? 'Delete folder' : 'Delete file', onClick: () => askDelete(target.path, isDir) })
       }
       setMenu({ x: e.clientX, y: e.clientY, note: ref, items })
     }
   }
 
+  // ⌘M cycles the active changed file through the four view modes.
+  function cycleMode(): void {
+    if (!active || !proj.diffs[active]) return
+    const order: (Mode | 'split')[] = ['updated', 'original', 'diff', 'split']
+    const cur = splitFor === active ? 'split' : (tabMode[active] || defaultMode)
+    const next = order[(order.indexOf(cur) + 1) % order.length]
+    if (next === 'split') setSplitFor(active)
+    else { setTabMode((m) => ({ ...m, [active]: next as Mode })); setSplitFor(null) }
+  }
+  function focusCommit(): void {
+    document.querySelector<HTMLTextAreaElement>('.commit-input')?.focus()
+  }
+  // Current selection as a single-line search seed (textarea selection or DOM selection).
+  function selectedSearchText(): string {
+    const ae = document.activeElement as HTMLTextAreaElement | null
+    const raw = (ae && (ae.tagName === 'TEXTAREA' || ae.tagName === 'INPUT') && ae.selectionStart !== ae.selectionEnd)
+      ? ae.value.slice(ae.selectionStart, ae.selectionEnd)
+      : (window.getSelection()?.toString() ?? '')
+    return raw.split('\n')[0].trim()
+  }
+  // ⌘→ with a selection: open Pass-on-to-Agent for the selected line range.
+  // Returns true when a selection was found (so we can swallow the key).
+  function passSelection(): boolean {
+    if (!active) return false
+    const ae = document.activeElement as HTMLTextAreaElement | null
+    // CodeEditor (updated / code) — the live selection lives in the textarea.
+    if (ae && ae.classList.contains('ce-ta') && ae.selectionStart !== ae.selectionEnd) {
+      const v = ae.value
+      const s = v.slice(0, ae.selectionStart).split('\n').length
+      const en = v.slice(0, ae.selectionEnd).split('\n').length
+      const ref = s === en ? `${active}:${s}` : `${active}:${s}-${en}`
+      const r = ae.getBoundingClientRect()
+      setPassPopup({ x: r.left + 60, y: r.top + 70, ref })
+      return true
+    }
+    // Diff / Original (PaneView) — line range tracked in `selection` state.
+    if (selection && selection.path === active && selection.start !== selection.end) {
+      const ref = `${active}:${selection.start}-${selection.end}`
+      const dom = window.getSelection()
+      let x = window.innerWidth / 2, y = 150
+      if (dom && dom.rangeCount && !dom.isCollapsed) {
+        const rr = dom.getRangeAt(0).getBoundingClientRect()
+        if (rr.width || rr.height) { x = rr.left; y = rr.bottom + 6 }
+      }
+      setPassPopup({ x, y, ref })
+      return true
+    }
+    return false
+  }
+  function hasSelection(): boolean {
+    if ((window.getSelection()?.toString() ?? '') !== '') return true
+    const ae = document.activeElement as HTMLInputElement | HTMLTextAreaElement | null
+    return !!ae && (ae.tagName === 'TEXTAREA' || ae.tagName === 'INPUT') && ae.selectionStart !== ae.selectionEnd
+  }
+
   // ---- shortcuts ----
   useEffect(() => {
     function onKey(e: KeyboardEvent): void {
+      if (!proj.root) return // launcher screen owns its own keyboard
+      if (confirm) return // the confirm dialog owns the keyboard while open
       const meta = e.metaKey || e.ctrlKey
+      const ae = document.activeElement as HTMLElement | null
+      const inField = !!ae && (ae.tagName === 'INPUT' || ae.tagName === 'TEXTAREA')
       // The history navigator owns the keyboard while open (it listens in capture phase).
       if (overlay === 'history') return
+      if (e.key === 'Escape') {
+        if (splitFor) setSplitFor(null)
+        else if (overlay) setOverlay(null)
+        else setMenu(null)
+        return
+      }
+      // Search / help modals own the keyboard while open (they handle their own keys).
+      if (overlay) return
+
       // ⌘↓/⌘↑ from the file viewer opens the recent-files navigator.
       if (meta && (e.key === 'ArrowDown' || e.key === 'ArrowUp') && focusZone === 'editor' && history.length > 0) {
         e.preventDefault()
         setHistInitSel(e.key === 'ArrowDown' ? Math.min(1, history.length - 1) : 0)
         setOverlay('history')
       }
-      // ⌘F and ⌘P both open the unified search (it covers file names too).
+      // ⌘F and ⌘P both open the unified search (it covers file names too), seeded
-      else if (meta && (e.key.toLowerCase() === 'f' || e.key.toLowerCase() === 'p')) { e.preventDefault(); setOverlay('search') }
+      // with the current selection when there is one.
+      else if (meta && (e.key.toLowerCase() === 'f' || e.key.toLowerCase() === 'p')) { e.preventDefault(); setSearchInit(selectedSearchText()); setOverlay('search') }
       else if (meta && e.key.toLowerCase() === 's') { e.preventDefault(); saveActive() }
       else if (meta && e.key.toLowerCase() === 'w') { e.preventDefault(); if (active) closeTab(active) }
-      else if (e.key === 'Escape') { if (splitFor) setSplitFor(null); else { setOverlay(null); setMenu(null) } }
+      // ⌘D deletes the current file (with confirmation).
+      else if (meta && e.key.toLowerCase() === 'd') { e.preventDefault(); if (active) askDelete(active, false) }
+      else if (meta && e.key.toLowerCase() === 'm') { e.preventDefault(); cycleMode() }
+      // ⌘→ with a text selection passes that selection to the agent (else native nav).
+      else if (meta && e.key === 'ArrowRight') { if (passSelection()) e.preventDefault() }
+      // ⌘↵ commits the staged files (unless the commit box has focus — it handles ⇧/⌘↵ itself).
+      else if (meta && e.key === 'Enter') {
+        if (ae && ae.classList.contains('commit-input')) return
+        e.preventDefault()
+        if (commitMsg.trim() && proj.changes.some((c) => proj.staged.has(c.path))) commit()
+      }
+      // ⌘C focuses the commit message (but let native copy run when there's a selection).
+      else if (meta && e.key.toLowerCase() === 'c') {
+        if (hasSelection()) return
+        e.preventDefault(); focusCommit()
+      }
+      // ⌘A toggles auto-fit (but let native select-all run inside text fields).
+      else if (meta && e.key.toLowerCase() === 'a') {
+        if (inField) return
+        e.preventDefault(); setAutoResize((v) => !v)
+      }
     }
     window.addEventListener('keydown', onKey)
     return () => window.removeEventListener('keydown', onKey)
-  }, [active, splitFor, overlay, focusZone, history])
+  }, [active, splitFor, overlay, focusZone, history, tabMode, commitMsg, proj, selection, confirm])
 
   const mode: Mode = (active && tabMode[active]) || (active && proj.diffs[active] ? defaultMode : 'code')
 
   const crumb = active ? active.split('/') : []
 
+  // No project yet (launched via Spotlight / bare) → show the project launcher.
+  if (proj.ready && !proj.root) {
+    return <ProjectLauncher onOpenNew={() => actions.openFolder()} onOpenPath={(p) => actions.openProjectPath(p)} />
+  }
+
   return (
     <div className="app">
       {/* title bar */}
@@ -395,11 +541,12 @@ export function App(): React.ReactElement {
         </div>
         <div className="tb-spacer" />
         <div className="tb-actions">
-          <button className="tb-btn" onClick={() => setOverlay('search')}>{Icon.search()} Search <kbd>⌘F</kbd></button>
+          <button className="tb-btn" onClick={() => { setSearchInit(''); setOverlay('search') }}>{Icon.search()} Search <kbd>⌘F</kbd></button>
           <button className={'tb-btn tb-toggle' + (autoResize ? ' on' : '')} onClick={() => setAutoResize((v) => !v)}
             title={autoResize ? 'Auto-fit panels: on — columns re-fit on resize/focus. Click to lock current sizes.' : 'Auto-fit panels: off — sizes locked. Click to re-enable.'}>
             {Icon.layout()} Auto-fit <span className="tb-state">{autoResize ? 'On' : 'Off'}</span>
           </button>
+          <button className="tb-btn tb-icon" onClick={() => setOverlay('help')} title="Keyboard shortcuts">{Icon.help()}</button>
         </div>
       </div>
 
@@ -463,8 +610,10 @@ export function App(): React.ReactElement {
           toast('Passed to agent', passPopup.ref)
         }}
         onCancel={() => setPassPopup(null)} />}
-      {overlay === 'search' && <SearchModal onOpen={openFile} onOpenAt={(p, n) => openFile(p, { line: n })} onClose={() => setOverlay(null)} changeSet={changeSet} />}
+      {overlay === 'search' && <SearchModal initialQuery={searchInit} onOpen={openFile} onOpenAt={(p, n) => openFile(p, { line: n })} onClose={() => setOverlay(null)} changeSet={changeSet} />}
       {overlay === 'history' && <HistoryModal history={history} initialSel={histInitSel} onOpen={openFile} onClose={() => setOverlay(null)} changeSet={changeSet} />}
+      {overlay === 'help' && <HelpModal onClose={() => setOverlay(null)} />}
+      {confirm && <ConfirmModal title={confirm.title} body={confirm.body} confirmLabel={confirm.confirmLabel} danger onConfirm={confirm.onConfirm} onClose={() => setConfirm(null)} />}
       {menu && <ContextMenu menu={menu} onClose={() => setMenu(null)} />}
       <Toasts toasts={toasts} />
     </div>

src/renderer/src/components.tsx

@@ -21,6 +21,9 @@ export const Icon: Record<string, (p?: SvgProps) => React.ReactElement> = {
   check: (p) => (<svg width="13" height="13" viewBox="0 0 14 14" fill="none" {...p}><path d="M2.5 7.5l2.8 3L11.5 3.5" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" /></svg>),
   discard: (p) => (<svg width="13" height="13" viewBox="0 0 16 16" fill="none" {...p}><path d="M12.5 5.5A5 5 0 1 0 13 9" stroke="currentColor" strokeWidth="1.3" fill="none" strokeLinecap="round" /><path d="M12.5 2.5v3h-3" stroke="currentColor" strokeWidth="1.3" fill="none" strokeLinecap="round" strokeLinejoin="round" /></svg>),
   layout: (p) => (<svg width="13" height="13" viewBox="0 0 16 16" fill="none" {...p}><rect x="2" y="3" width="12" height="10" rx="1.5" stroke="currentColor" strokeWidth="1.3" /><path d="M6 3v10M10 3v10" stroke="currentColor" strokeWidth="1.3" /></svg>),
+  help: (p) => (<svg width="14" height="14" viewBox="0 0 16 16" fill="none" {...p}><circle cx="8" cy="8" r="6.2" stroke="currentColor" strokeWidth="1.3" /><path d="M6.3 6.2a1.7 1.7 0 1 1 2.3 1.6c-.5.25-.8.6-.8 1.2v.3" stroke="currentColor" strokeWidth="1.3" fill="none" strokeLinecap="round" /><circle cx="8" cy="11.4" r=".75" fill="currentColor" /></svg>),
+  trash: (p) => (<svg width="13" height="13" viewBox="0 0 16 16" fill="none" {...p}><path d="M3 4.5h10M6.5 4.5V3h3v1.5M4.5 4.5l.6 8.5h5.8l.6-8.5" stroke="currentColor" strokeWidth="1.2" fill="none" strokeLinecap="round" strokeLinejoin="round" /></svg>),
+  finder: (p) => (<svg width="13" height="13" viewBox="0 0 16 16" fill="none" {...p}><rect x="2" y="3.5" width="12" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.2" /><path d="M9 7l3-3M12 4v2.6M12 4H9.4" stroke="currentColor" strokeWidth="1.2" fill="none" strokeLinecap="round" strokeLinejoin="round" /></svg>),
 }
 
 export const Chevron = ({ open }: { open: boolean }): React.ReactElement => (

src/renderer/src/env.d.ts

@@ -15,12 +15,18 @@ interface HelderBridge {
   project: {
     current: () => Promise<{ root: string | null; name: string }>
     open: () => Promise<{ root: string | null; name: string }>
+    openPath: (path: string) => Promise<{ root: string | null; name: string }>
+    recent: () => Promise<{ path: string; name: string }[]>
   }
   fs: {
     tree: () => Promise<FileNode | null>
     files: () => Promise<Record<string, string>>
     read: (path: string) => Promise<string>
     write: (path: string, content: string) => Promise<void>
+    delete: (path: string) => Promise<void>
+  }
+  shell: {
+    reveal: (path: string) => void
   }
   git: {
     load: () => Promise<{ branch: string; changes: GitChangeRaw[] } | null>

src/renderer/src/launcher.tsx

@@ -0,0 +1,78 @@
+/* Project launcher — shown when Helder starts without a project (Spotlight / bare
+ * launch). Lists the recent projects (max 20, newest first); the first row opens a
+ * folder picker for a new project. Keyboard: ⌘↑/⌘↓ (or plain arrows) move the
+ * selection, ↵ opens it — same model as the recent-files navigator. */
+import React, { useEffect, useRef, useState } from 'react'
+import { Icon } from './components'
+
+interface RecentProject { path: string; name: string }
+
+export function ProjectLauncher({ onOpenNew, onOpenPath }: {
+  onOpenNew: () => void
+  onOpenPath: (path: string) => void
+}): React.ReactElement {
+  const [recents, setRecents] = useState<RecentProject[]>([])
+  const [sel, setSel] = useState(0)
+  const selRef = useRef(sel); selRef.current = sel
+  const listRef = useRef<HTMLDivElement>(null)
+
+  // rows = [new project, ...recents]; total selectable count
+  const count = recents.length + 1
+
+  useEffect(() => {
+    const bridge = window.helder
+    if (bridge) bridge.project.recent().then(setRecents).catch(() => setRecents([]))
+  }, [])
+
+  function activate(i: number): void {
+    if (i <= 0) onOpenNew()
+    else if (recents[i - 1]) onOpenPath(recents[i - 1].path)
+  }
+
+  useEffect(() => {
+    function onKey(e: KeyboardEvent): void {
+      if (e.key === 'ArrowDown') { e.preventDefault(); setSel((s) => Math.min(s + 1, count - 1)) }
+      else if (e.key === 'ArrowUp') { e.preventDefault(); setSel((s) => Math.max(s - 1, 0)) }
+      else if (e.key === 'Enter') { e.preventDefault(); activate(selRef.current) }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [count, recents])
+
+  useEffect(() => {
+    const el = listRef.current && listRef.current.querySelector('.lp-row.sel')
+    if (el) el.scrollIntoView({ block: 'nearest' })
+  }, [sel])
+
+  return (
+    <div className="launcher">
+      <div className="launcher-drag" />
+      <div className="launcher-card">
+        <div className="lp-head">
+          {Icon.spark({ width: 22, height: 22, style: { color: 'var(--accent)' } })}
+          <div className="lp-title"><b>Helder</b><span>Open a project to begin</span></div>
+        </div>
+        <div className="lp-list" ref={listRef}>
+          <div className={'lp-row lp-new' + (sel === 0 ? ' sel' : '')}
+            onMouseEnter={() => setSel(0)} onClick={() => activate(0)}>
+            <span className="lp-ic">{Icon.plus()}</span>
+            <div className="lp-txt"><span className="lp-name">Open new project…</span><span className="lp-path">Choose a folder</span></div>
+            <kbd>↵</kbd>
+          </div>
+          {recents.length > 0 && <div className="lp-sec">Recent</div>}
+          {recents.map((p, i) => {
+            const idx = i + 1
+            return (
+              <div key={p.path} className={'lp-row' + (sel === idx ? ' sel' : '')} title={p.path}
+                onMouseEnter={() => setSel(idx)} onClick={() => activate(idx)}>
+                <span className="lp-ic">{Icon.reveal()}</span>
+                <div className="lp-txt"><span className="lp-name">{p.name}</span><span className="lp-path">{p.path}</span></div>
+              </div>
+            )
+          })}
+        </div>
+        <div className="lp-foot"><kbd>⌘↓</kbd> <kbd>⌘↑</kbd> navigate · <kbd>↵</kbd> open</div>
+      </div>
+    </div>
+  )
+}

src/renderer/src/overlays.tsx

@@ -24,7 +24,8 @@ function Highlight({ text, idx }: { text: string; idx: number[] | null }): React
   return <span>{text.split('').map((ch, i) => set.has(i) ? <b key={i}>{ch}</b> : <Fragment key={i}>{ch}</Fragment>)}</span>
 }
 
-export function SearchModal({ onOpen, onOpenAt, onClose, changeSet }: {
+export function SearchModal({ initialQuery, onOpen, onOpenAt, onClose, changeSet }: {
+  initialQuery?: string
   onOpen: OpenFile
   onOpenAt: (path: string, line: number) => void
   onClose: () => void
@@ -32,15 +33,18 @@ export function SearchModal({ onOpen, onOpenAt, onClose, changeSet }: {
 }): React.ReactElement {
   const PROJECT = useProject()
   const bridge = window.helder
-  const [q, setQ] = useState('')
+  const [q, setQ] = useState(() => initialQuery ?? '')
   const [sel, setSel] = useState(0)
+  const [fileSel, setFileSel] = useState(0)
+  const [col, setCol] = useState<'content' | 'files'>('content') // active result column (⌘← / ⌘→)
   const inputRef = useRef<HTMLInputElement>(null)
   const leftRef = useRef<HTMLDivElement>(null)
+  const rightRef = useRef<HTMLDivElement>(null)
 
   // file-name list: ripgrep `--files` when available, else the in-memory index keys
   const [allPaths, setAllPaths] = useState<string[]>(() => (bridge ? [] : Object.keys(PROJECT.files)))
   useEffect(() => {
-    if (inputRef.current) inputRef.current.focus()
+    if (inputRef.current) { inputRef.current.focus(); inputRef.current.select() } // select seed so typing replaces it
     if (bridge) bridge.search.files().then((f) => setAllPaths(f.length ? f : Object.keys(PROJECT.files))).catch(() => setAllPaths(Object.keys(PROJECT.files)))
   }, [])
 
@@ -95,19 +99,37 @@ export function SearchModal({ onOpen, onOpenAt, onClose, changeSet }: {
   }, [content])
 
   const totalHits = flat.length
-  useEffect(() => { setSel(0) }, [q])
+  const fileCount = Math.min(files.length, 40)
+  useEffect(() => { setSel(0); setFileSel(0) }, [q])
   useEffect(() => {
     const el = leftRef.current && leftRef.current.querySelector('.sr-line.sel')
     if (el) el.scrollIntoView({ block: 'nearest' })
   }, [sel])
+  useEffect(() => {
+    const el = rightRef.current && rightRef.current.querySelector('.fres.sel')
+    if (el) el.scrollIntoView({ block: 'nearest' })
+  }, [fileSel])
 
   function onKey(e: React.KeyboardEvent): void {
-    if (e.key === 'ArrowDown') { e.preventDefault(); setSel((s) => Math.min(s + 1, flat.length - 1)) }
+    if ((e.metaKey || e.ctrlKey) && e.key === 'ArrowLeft') { e.preventDefault(); setCol('content'); return }
-    else if (e.key === 'ArrowUp') { e.preventDefault(); setSel((s) => Math.max(s - 1, 0)) }
+    if ((e.metaKey || e.ctrlKey) && e.key === 'ArrowRight') { e.preventDefault(); setCol('files'); return }
-    else if (e.key === 'Enter') {
+    if (e.key === 'ArrowDown') {
       e.preventDefault()
-      if (flat[sel]) { onOpenAt(flat[sel].path, flat[sel].no); onClose() }
+      if (col === 'files') setFileSel((s) => Math.min(s + 1, fileCount - 1))
-      else if (files[0]) { onOpen(files[0].path); onClose() }
+      else setSel((s) => Math.min(s + 1, flat.length - 1))
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      if (col === 'files') setFileSel((s) => Math.max(s - 1, 0))
+      else setSel((s) => Math.max(s - 1, 0))
+    } else if (e.key === 'Enter') {
+      e.preventDefault()
+      if (col === 'files') {
+        if (files[fileSel]) { onOpen(files[fileSel].path); onClose() }
+        else if (flat[sel]) { onOpenAt(flat[sel].path, flat[sel].no); onClose() }
+      } else {
+        if (flat[sel]) { onOpenAt(flat[sel].path, flat[sel].no); onClose() }
+        else if (files[0]) { onOpen(files[0].path); onClose() }
+      }
     } else if (e.key === 'Escape') { e.preventDefault(); onClose() }
   }
 
@@ -129,8 +151,8 @@ export function SearchModal({ onOpen, onOpenAt, onClose, changeSet }: {
           <span className="mode-chip">{totalHits} hit{totalHits === 1 ? '' : 's'} · {files.length} file{files.length === 1 ? '' : 's'}</span>
         </div>
         <div className="search-cols">
-          <div className="sc-left" ref={leftRef}>
+          <div className={'sc-left' + (col === 'content' ? ' active' : '')} ref={leftRef}>
-            <div className="sc-head">Content {totalHits > 0 && <span className="sc-ct">{totalHits}</span>}</div>
+            <div className="sc-head">Content {totalHits > 0 && <span className="sc-ct">{totalHits}</span>} <kbd className="col-kbd">⌘←</kbd></div>
             {term.length < 2 && <div className="pempty">Type at least 2 characters</div>}
             {term.length >= 2 && content.length === 0 && <div className="pempty">No content matches</div>}
             {content.map((g) => (
@@ -144,8 +166,8 @@ export function SearchModal({ onOpen, onOpenAt, onClose, changeSet }: {
                   flatIx++
                   const me = flatIx
                   return (
-                    <div key={h.no} className={'sr-line' + (me === sel ? ' sel' : '')}
+                    <div key={h.no} className={'sr-line' + (me === sel && col === 'content' ? ' sel' : '')}
-                      onMouseEnter={() => setSel(me)}
+                      onMouseEnter={() => { setCol('content'); setSel(me) }}
                       onClick={() => { onOpenAt(g.path, h.no); onClose() }}>
                       <span className="no">{h.no}</span>
                       {renderLine(h.ln, h.ix, term.length)}
@@ -155,15 +177,17 @@ export function SearchModal({ onOpen, onOpenAt, onClose, changeSet }: {
               </Fragment>
             ))}
           </div>
-          <div className="sc-right">
+          <div className={'sc-right' + (col === 'files' ? ' active' : '')} ref={rightRef}>
-            <div className="sc-head">Files {files.length > 0 && <span className="sc-ct">{files.length}</span>}</div>
+            <div className="sc-head">Files {files.length > 0 && <span className="sc-ct">{files.length}</span>} <kbd className="col-kbd">⌘→</kbd></div>
             {!term && <div className="pempty sm">Start typing…</div>}
             {term && files.length === 0 && <div className="pempty sm">No file names match</div>}
-            {files.slice(0, 40).map((r) => {
+            {files.slice(0, 40).map((r, i) => {
               const name = r.path.split('/').pop() as string
               const dir = r.path.split('/').slice(0, -1).join('/')
               return (
-                <div key={r.path} className="fres" onClick={() => { onOpen(r.path); onClose() }} title={r.path}>
+                <div key={r.path} className={'fres' + (col === 'files' && i === fileSel ? ' sel' : '')}
+                  onMouseEnter={() => { setCol('files'); setFileSel(i) }}
+                  onClick={() => { onOpen(r.path); onClose() }} title={r.path}>
                   <FileIcon path={r.path} />
                   <div className="fres-txt">
                     <span className="fn"><Highlight text={name} idx={r.idx} /></span>
@@ -242,6 +266,82 @@ export function HistoryModal({ history, initialSel, onOpen, onClose, changeSet }
   )
 }
 
+/* Keyboard-shortcuts reference (opened from the title-bar ? button). */
+const SHORTCUTS: { keys: string[]; label: string }[] = [
+  { keys: ['⌘', 'F'], label: 'Search contents & names (seeded by selection)' },
+  { keys: ['⌘', '↑'], label: 'Navigate a list up' },
+  { keys: ['⌘', '↓'], label: 'Navigate a list down' },
+  { keys: ['↵'], label: 'Open the selected list item' },
+  { keys: ['⌘', '←'], label: 'Search: focus the content results' },
+  { keys: ['⌘', '→'], label: 'Search: focus the file-name results' },
+  { keys: ['⌘', '→'], label: 'Pass the selected text to the agent' },
+  { keys: ['⌘', 'M'], label: 'Cycle view: Updated · Original · Diff · Split' },
+  { keys: ['⌘', 'C'], label: 'Focus the commit message' },
+  { keys: ['⌘', '↵'], label: 'Commit the staged files' },
+  { keys: ['⌘', 'A'], label: 'Toggle auto-fit panels' },
+  { keys: ['⌘', 'S'], label: 'Save the current file' },
+  { keys: ['⌘', 'W'], label: 'Close the current file' },
+  { keys: ['⌘', 'D'], label: 'Delete the current file (confirm)' },
+  { keys: ['⌘', 'O'], label: 'Open a project folder' },
+  { keys: ['Esc'], label: 'Close an overlay / split view' },
+]
+
+export function HelpModal({ onClose }: { onClose: () => void }): React.ReactElement {
+  return (
+    <div className="scrim" onMouseDown={onClose}>
+      <div className="help-modal" onMouseDown={(e) => e.stopPropagation()}>
+        <div className="pi">
+          {Icon.help({ style: { color: 'var(--fg-3)' } })}
+          <span className="hist-title">Keyboard shortcuts</span>
+          <span className="mode-chip"><kbd>esc</kbd></span>
+        </div>
+        <div className="help-list">
+          {SHORTCUTS.map((s, i) => (
+            <div key={i} className="help-row">
+              <span className="help-keys">{s.keys.map((k, j) => <kbd key={j}>{k}</kbd>)}</span>
+              <span className="help-label">{s.label}</span>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/* Generic confirm dialog — ↵ confirms, Esc cancels. Listens in capture phase so
+ * it owns the keyboard while open. */
+export function ConfirmModal({ title, body, confirmLabel, danger, onConfirm, onClose }: {
+  title: string
+  body?: string
+  confirmLabel?: string
+  danger?: boolean
+  onConfirm: () => void
+  onClose: () => void
+}): React.ReactElement {
+  useEffect(() => {
+    function onKey(e: KeyboardEvent): void {
+      if (e.key === 'Enter') { e.preventDefault(); e.stopPropagation(); onConfirm(); onClose() }
+      else if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); onClose() }
+    }
+    window.addEventListener('keydown', onKey, true)
+    return () => window.removeEventListener('keydown', onKey, true)
+  }, [])
+  return (
+    <div className="scrim" onMouseDown={onClose}>
+      <div className="confirm-modal" onMouseDown={(e) => e.stopPropagation()}>
+        <div className="cf-title">{title}</div>
+        {body && <div className="cf-body">{body}</div>}
+        <div className="cf-actions">
+          <button className="cf-btn" onClick={onClose}>Cancel <kbd>esc</kbd></button>
+          <button className={'cf-btn cf-yes' + (danger ? ' danger' : '')} onClick={() => { onConfirm(); onClose() }} autoFocus>
+            {confirmLabel ?? 'Confirm'} <kbd>↵</kbd>
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
 export function ContextMenu({ menu, onClose }: { menu: Menu | null; onClose: () => void }): React.ReactElement | null {
   const ref = useRef<HTMLDivElement>(null)
   useEffect(() => {

src/renderer/src/project.tsx

@@ -35,6 +35,7 @@ function applyTheme(css: string): void {
 
 export interface ProjectActions {
   openFolder: () => void
+  openProjectPath: (path: string) => void
   refresh: () => void
   stage: (path: string) => void
   unstage: (path: string) => void
@@ -49,7 +50,8 @@ const MOCK_STAGED = ['src/Service/PaymentService.php', 'config/app.json']
 
 function mockData(): ProjectData {
   return {
-    name: MOCK.name, root: null, branch: MOCK.branch,
+    // non-null root so browser-preview shows the workbench, not the launcher
+    name: MOCK.name, root: '/mock/' + MOCK.name, branch: MOCK.branch,
     tree: MOCK.tree, files: MOCK.files, changes: MOCK.changes, diffs: MOCK.diffs,
     staged: new Set(MOCK_STAGED), config: DEFAULT_CONFIG, isRepo: true, ready: true,
   }
@@ -129,6 +131,7 @@ export function ProjectProvider({ children }: { children: React.ReactNode }): Re
         setData((d) => ({ ...d, staged: fn(new Set(d.staged)) }))
       return {
         openFolder: () => {},
+        openProjectPath: () => {},
         refresh: () => setData(mockData()),
         stage: (p) => setStaged((s) => (s.add(p), s)),
         unstage: (p) => setStaged((s) => (s.delete(p), s)),
@@ -152,6 +155,7 @@ export function ProjectProvider({ children }: { children: React.ReactNode }): Re
     const after = (op: Promise<unknown>): void => { op.then(() => loadReal()).catch(() => {}) }
     return {
       openFolder: () => { bridge.project.open().then(() => loadReal()).catch(() => {}) },
+      openProjectPath: (path) => { bridge.project.openPath(path).then(() => loadReal()).catch(() => {}) },
       refresh: () => { loadReal().catch(() => {}) },
       stage: (p) => after(bridge.git.stage([p])),
       unstage: (p) => after(bridge.git.unstage([p])),

src/renderer/src/styles.css

@@ -439,3 +439,62 @@ body {
 @media (prefers-reduced-motion: reduce) {
   * { animation-duration: 0.001ms !important; animation-iteration-count: 1 !important; transition-duration: 0.001ms !important; }
 }
+
+/* ============ project launcher (no project open) ============ */
+.launcher { position:fixed; inset:0; background:var(--bg-0); display:flex; align-items:center; justify-content:center; }
+.launcher-drag { position:absolute; top:0; left:0; right:0; height:40px; -webkit-app-region:drag; }
+.launcher-card { width:560px; max-width:92vw; max-height:80vh; display:flex; flex-direction:column; background:var(--bg-2); border:1px solid var(--border-2); border-radius:14px; box-shadow:0 28px 80px rgba(0,0,0,.55); overflow:hidden; -webkit-app-region:no-drag; }
+.lp-head { display:flex; align-items:center; gap:12px; padding:18px 20px; border-bottom:1px solid var(--border); }
+.lp-title { display:flex; flex-direction:column; line-height:1.3; }
+.lp-title b { font-size:16px; color:var(--fg-0); font-weight:600; }
+.lp-title span { font-size:12px; color:var(--fg-3); }
+.lp-list { overflow:auto; padding:6px; flex:1; min-height:0; }
+.lp-sec { padding:10px 10px 4px; font-size:10px; letter-spacing:.07em; text-transform:uppercase; color:var(--fg-3); }
+.lp-row { display:flex; align-items:center; gap:11px; padding:9px 10px; border-radius:8px; cursor:pointer; }
+.lp-row:hover { background:var(--hover); }
+.lp-row.sel { background:var(--accent-soft); box-shadow:inset 2px 0 0 var(--accent); }
+.lp-ic { flex:0 0 auto; width:22px; height:22px; display:flex; align-items:center; justify-content:center; color:var(--fg-2); }
+.lp-new .lp-ic { color:var(--accent); }
+.lp-txt { min-width:0; display:flex; flex-direction:column; line-height:1.3; flex:1; }
+.lp-name { font-size:13px; color:var(--fg-0); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.lp-path { font-size:11px; color:var(--fg-3); font-family:var(--mono); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; direction:rtl; text-align:left; }
+.lp-row kbd { font-family:var(--mono); font-size:10px; color:var(--fg-3); border:1px solid var(--border-2); border-radius:4px; padding:1px 5px; flex:0 0 auto; }
+.lp-foot { padding:10px 20px; border-top:1px solid var(--border); font-size:10.5px; color:var(--fg-3); }
+.lp-foot kbd { font-family:var(--mono); font-size:10px; color:var(--fg-2); border:1px solid var(--border-2); border-radius:4px; padding:0 5px; }
+
+/* ============ keyboard-shortcuts (help) modal ============ */
+.help-modal { width:520px; max-width:92vw; background:#212429; border:1px solid var(--border-2); border-radius:11px; box-shadow:0 24px 70px rgba(0,0,0,.55); overflow:hidden; display:flex; flex-direction:column; }
+.help-modal .pi { display:flex; align-items:center; gap:10px; padding:12px 15px; border-bottom:1px solid var(--border); }
+.help-modal .pi svg { flex:0 0 auto; }
+.help-modal .hist-title { flex:1; min-width:0; color:var(--fg-1); font-size:14px; }
+.help-modal .mode-chip { flex:0 0 auto; font-family:var(--mono); font-size:10px; color:var(--fg-3); border:1px solid var(--border-2); border-radius:5px; padding:2px 7px; }
+.help-list { max-height:62vh; overflow:auto; padding:8px 6px; }
+.help-row { display:flex; align-items:center; gap:14px; padding:6px 12px; border-radius:7px; }
+.help-row:hover { background:var(--hover); }
+.help-keys { flex:0 0 96px; display:flex; gap:4px; justify-content:flex-end; }
+.help-keys kbd { font-family:var(--mono); font-size:11px; color:var(--fg-1); background:var(--bg-1); border:1px solid var(--border-2); border-radius:5px; padding:2px 7px; min-width:20px; text-align:center; }
+.help-label { font-size:12.5px; color:var(--fg-2); }
+
+/* title-bar icon-only button (help ?) */
+.tb-icon { padding:5px 7px; }
+
+/* confirm dialog (delete, etc.) */
+.confirm-modal { width:420px; max-width:92vw; background:#23272d; border:1px solid var(--border-2); border-radius:12px; box-shadow:0 24px 70px rgba(0,0,0,.55); padding:18px 20px; }
+.cf-title { font-size:14px; font-weight:600; color:var(--fg-0); }
+.cf-body { margin-top:8px; font-size:12.5px; line-height:1.45; color:var(--fg-2); font-family:var(--mono); word-break:break-all; }
+.cf-actions { margin-top:18px; display:flex; justify-content:flex-end; gap:9px; }
+.cf-btn { display:flex; align-items:center; gap:7px; font-size:12.5px; color:var(--fg-1); background:var(--bg-2); border:1px solid var(--border-2); border-radius:7px; padding:7px 13px; cursor:pointer; }
+.cf-btn:hover { background:var(--hover); color:var(--fg-0); }
+.cf-btn kbd { font-family:var(--mono); font-size:10px; color:var(--fg-3); border:1px solid var(--border-2); border-radius:4px; padding:0 5px; }
+.cf-yes { background:var(--accent); color:#201608; border-color:transparent; font-weight:600; }
+.cf-yes:hover { background:#f6b35f; color:#201608; }
+.cf-yes kbd { color:#201608; border-color:rgba(0,0,0,.25); }
+.cf-yes.danger { background:var(--del); color:#fff; }
+.cf-yes.danger:hover { background:#e8797a; }
+.cf-yes.danger kbd { color:#fff; border-color:rgba(255,255,255,.4); }
+
+/* search: active result column + file-name selection */
+.sc-head .col-kbd { margin-left:auto; font-family:var(--mono); font-size:9.5px; color:var(--fg-3); border:1px solid var(--border-2); border-radius:4px; padding:0 4px; opacity:.55; }
+.sc-left.active .sc-head, .sc-right.active .sc-head { color:var(--accent); }
+.sc-left.active .sc-head .col-kbd, .sc-right.active .sc-head .col-kbd { color:var(--accent); border-color:var(--accent-line); opacity:1; }
+.fres.sel { background:var(--accent-soft); box-shadow:inset 2px 0 0 var(--accent); }

sync_helder.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# sync_helder.sh — build Helder (arm64), install it into ~/Applications, and
+# drop a stable-named Helder.dmg alongside it.
+#
+#   ./sync_helder.sh
+#
+set -euo pipefail
+
+# Run from the repo root (where this script lives), whatever the caller's cwd is.
+cd "$(dirname "$0")"
+
+APPS_DIR="$HOME/Applications"
+APP_DEST="$APPS_DIR/Helder.app"
+DMG_DEST="$APPS_DIR/Helder.dmg"
+
+echo "▶ Building Helder (arm64)…"
+npm run dist:mac
+
+# Locate the freshly built artifacts.
+APP_SRC="dist/mac-arm64/Helder.app"
+DMG_SRC="$(ls -t dist/Helder-*-arm64.dmg 2>/dev/null | head -n1 || true)"
+
+[ -d "$APP_SRC" ] || { echo "✗ Build output not found: $APP_SRC"; exit 1; }
+[ -n "$DMG_SRC" ] && [ -f "$DMG_SRC" ] || { echo "✗ No built .dmg found in dist/"; exit 1; }
+
+mkdir -p "$APPS_DIR"
+
+# Quit a running copy so we can replace the bundle cleanly.
+osascript -e 'tell application "Helder" to quit' >/dev/null 2>&1 || true
+sleep 1
+
+echo "▶ Installing app → $APP_DEST"
+rm -rf "$APP_DEST"
+cp -R "$APP_SRC" "$APP_DEST"
+# Unsigned ad-hoc build: clear the quarantine flag so it launches without the
+# Gatekeeper "unidentified developer" prompt.
+xattr -dr com.apple.quarantine "$APP_DEST" 2>/dev/null || true
+
+echo "▶ Copying installer → $DMG_DEST"
+cp -f "$DMG_SRC" "$DMG_DEST"
+
+echo "✓ Done."
+echo "  • Installed: $APP_DEST  (launch from Spotlight)"
+echo "  • Installer: $DMG_DEST  (renamed from $(basename "$DMG_SRC"))"