Merge main into feat/7css-skin + give the HTML context menu an Aero skin

main retired electrobun's native context menu (a documented no-op on Linux) in
favour of an HTML one on every platform. Merging that here needs the menu to
look right under the Win7 skin as well.

Conflicts, all resolved by keeping both sides:
- src/bun/index.ts — createAppRPC keeps the branch's mainWindow getter, drops
  main's removed contextMenu dep.
- ui/src/app/app.ts — imports both TitleBar and ContextMenu.
- ui/src/app/platform.ts — kept the branch's version (its IS_MAC_CHROME accounts
  for the frameless win7 chrome, and MOD_LABEL correctly keys on the real
  platform rather than the chrome), plus exporting IS_MAC and adding IS_LINUX
  for the menu's per-OS shell wording.

Aero menu (branch-only): 7.css has no menu component, so it is hand-authored
across both layers — the row <button>s shed their push-button slab in `skin`
(revert-layer only reaches `utilities` from there), and the square-cornered
slab, hairline border and gradient selection band are stated in `skinfix`.
Built strictly from existing --w7-* vars, never literal hex, so the
hand-written dark Win7 palette recolours it for free. Hover and the keyboard
cursor share one band (the component marks the cursor with `bg-accent`, which
is overridden alongside :hover) as a real Win7 menu does.

Also answers a question the merge raised: frameless windows DO work on Linux.
The GTK wrapper honours titleBarStyle "hidden" — it calls
gtk_window_set_decorated(false) and logs "GTK: Created window without
decorations (custom titlebar)". Verified on GNOME/Wayland and documented in
architecture.md.

Verified: backend `tsc --noEmit` clean, `bun run build:ui` clean (492.52 kB
initial, still under the 500 kB budget), app launches with the skin active,
frameless, no console errors and no GBM failures.

Co-Authored-By: Claude <noreply@anthropic.com>

docs/architecture.md

@@ -10,7 +10,8 @@ Dense reference for development and debugging. Companion files:
   its native launcher. Owns every privileged capability: filesystem, SSH,
   window management, native menus/dialogs/tray, the connection/settings stores.
 - **Webviews** (`ui/` Angular): one per window, system WebKit on macOS /
-  WebView2 on Windows. Zero privileged access — everything goes through RPC.
+  WebView2 on Windows / WebKitGTK on Linux. Zero privileged access — everything
+  goes through RPC.
 - **RPC transport**: one WebSocket server in the bun process, multiplexed by
   `webviewId` (each webview auto-connects using natively injected globals).
   Requests are typed by the `AppRPC` schema in `src/shared/rpc.ts`.
@@ -148,10 +149,6 @@ would float over editor windows).
 - `store/connections.ts` — plaintext-passwords JSON (deliberate v1 choice),
   atomic tmp+rename, 0600 + win32 `icacls` ACL. `store/settings.ts` — defaults
   spread-merge on load, so NEW SETTINGS KEYS need no backend change.
-- `context-menu.ts` — native row/empty-space menus + the column picker.
-  Local shell actions (reveal/open/copy-path) run bun-side via Utils; others
-  forward through `menuAction` and the UI applies them to the row it
-  remembered (`FileActionsService.menuTarget`). Labels are per-platform.
 - `menu.ts` — macOS-only app menu, rebuilt on every connections change (the
   Connect submenu mirrors the store). ⌘W is intercepted by the menu, so bun
   routes `close-tab` to the focused editor window first. Labels go through
@@ -161,7 +158,8 @@ would float over editor windows).
   locale (from `settings.locale`, `system` via `Intl…resolvedOptions().locale`);
   `t(key, params)` shares the same `src/shared/i18n` dictionaries as the UI.
   Wired in index.ts on boot and on `settingsChanged` (relocalizes + rebuilds
-  the app menu). `context-menu.ts` labels resolve through `t()` at show-time.
+  the app menu). The context menu no longer needs this — it is Angular and reads
+  `I18nService` directly.
 - `tray.ts` — static icon, click = activate main. macOS template image;
   Windows colored icon. No `setImage` calls ever (they lose the template
   treatment) and no menu (clicks arrive directly).
@@ -220,12 +218,24 @@ would float over editor windows).
   boot and on the `settingsChanged` broadcast (so editor/manager windows follow).
 - `file-actions.service.ts` — toolbar/keyboard/context-menu file ops, always
   against an explicit panel; `menuTarget` remembers the right-clicked row.
+- `context-menu.service.ts` + `context-menu.ts` — the panel right-click menus,
+  in HTML. Electrobun's native `showContextMenu` is a no-op on Linux, so it was
+  retired on ALL platforms rather than kept as a second code path (see
+  platform-notes.md). The service builds the item list (row / empty-space menu,
+  and the header column picker) and holds the open request as a signal; the
+  component renders it at the pointer with edge-flip clamping, arrow/Enter/Escape
+  keys, and close-on-blur/resize/scroll. Picked items are emitted verbatim as
+  `ctx-*` / `col:*` strings through `RpcService.emitMenuAction`, so they land in
+  the SAME `App.handleMenuAction` dispatcher the macOS app menubar uses — one
+  handler, two sources. The three shell actions the webview cannot perform
+  (reveal, open-with-default, copy path) go back to bun via the `shellItemAction`
+  RPC, which is all that remains of the old native menu.
 - `file-icons.ts` — extension → category map driving glyphs, colors
   (fixed `--icon-*` tokens, never accent-tinted) and the Kind column.
 - `platform.ts` — preload-global readers (`PLATFORM`, `APP_MODE`,
-  `EDITOR_CONTEXT`, `IS_MAC_CHROME`, `IS_WINDOWS`, `MOD_LABEL`/`ALT_LABEL`)
-  + `blockNativeContextMenu` (kills WebKit's Reload/Inspect menu outside
-  text fields).
+  `EDITOR_CONTEXT`, `IS_MAC`/`IS_MAC_CHROME`, `IS_WINDOWS`, `IS_LINUX`,
+  `MOD_LABEL`/`ALT_LABEL`) + `blockNativeContextMenu` (kills WebKit's
+  Reload/Inspect menu outside text fields — the app draws its own menu instead).
 - `updater.service.ts` — auto-updater state for the tab-bar pill. Signals
   `state` (`idle→available→downloading→ready`|`error`), `version`, `progress`.
   Subscribes the `updateStatus` push (backend `Updater.checkForUpdate` on
@@ -298,7 +308,18 @@ still scales and 7.css's `pt` shorthand stops resetting weight/line-height.
 (+aria) on the transfer bars, `has-scrollbar` on scroll containers (7.css only
 styles `::-webkit-scrollbar` under that class), `w7-toolbar` on the three
 header rows (their buttons go flat — Explorer's command bar was flat, unlike
-dialog push buttons), `w7-btn` on the 10 dialog action buttons.
+dialog push buttons), `w7-btn` on the 10 dialog action buttons, `w7-menu` (+
+`w7-menu-sep`) on the HTML context menu.
+
+**Context menu**: 7.css ships no menu component, so the Aero menu is
+hand-authored across both layers — the row `<button>`s lose their push-button
+slab in `skin` (needs `revert-layer`), and the slab/border/selection-band paint
+is stated in `skinfix`. It is built ONLY from existing `--w7-*` vars (never
+literal hex), so the hand-written dark Win7 palette recolours it for free —
+the same constraint the dark block documents for itself. The hover and
+keyboard-cursor highlights are deliberately given the same band: the component
+marks the keyboard cursor with `bg-accent`, which is overridden alongside
+`:hover` so the two are indistinguishable, as in a real Win7 menu.
 
 **Font**: Segoe UI is absent off Windows and not redistributable. Noto Sans —
 the substitute 7.css itself names — is vendored (OFL-1.1, from
@@ -309,7 +330,10 @@ so esbuild emits it hashed into `media/` and rewrites the `url()`.
 place either skin's frame is decided, spread by both the main window and
 `openSecondaryWindow`. `win7` uses `titleBarStyle: "hidden"` on **every**
 platform — that clears `Titled` from the Cocoa style mask, which is also the
-only way to remove the macOS traffic lights. The webview then draws the whole
+only way to remove the macOS traffic lights. **Linux honours it too**: the GTK
+wrapper calls `gtk_window_set_decorated(false)` and logs "GTK: Created window
+without decorations (custom titlebar)" (verified on GNOME/Wayland), so the
+frameless Aero chrome is not a mac/win-only feature. The webview then draws the whole
 frame via `ui/src/app/title-bar/title-bar.ts` (7.css's `.title-bar` >
 `.title-bar-text` + `.title-bar-controls`, buttons keyed by `aria-label`),
 mounted by all three window roots. Because `titleBarStyle` is fixed at

docs/build-and-release.md

@@ -25,7 +25,8 @@ semver-shaped (`0.1.<n>`) for electrobun's config/updater; `BRANDING.buildLabel`
 
 ## Release builds
 
-`bun scripts/release.ts [--target mac-arm64|mac-x64|win-x64]` (default: host).
+`bun scripts/release.ts [--target mac-arm64|mac-x64|win-x64|linux-x64]`
+(default: host).
 Steps: gen-version → gen-icons → Angular build → `electrobun build
 --env=stable` → copy/rename artifacts into
 `release/<target>/miniSCP-Build<n>-<target>.*`.
@@ -37,7 +38,8 @@ Facts the script encodes:
 - **No OS cross-compile.** The CLI builds for its host (its `targets` config
   field is unread in 1.18.1); packaging needs host tools (codesign/hdiutil on
   macOS, rcedit/PowerShell on Windows). Hence one script run per artifact, on
-  the matching machine; `win-x64` on a non-Windows host errors out.
+  the matching machine; `win-x64` on a non-Windows host and `linux-x64` on a
+  non-Linux host both error out.
 - **mac-x64 from the arm64 Mac (Rosetta)**: the script downloads electrobun's
   x64 CLI binary once (`electrobun-cli-darwin-x64.tar.gz` from the GitHub
   release matching the installed version, cached at
@@ -56,7 +58,16 @@ Facts the script encodes:
   (self-extracting installer → `%LOCALAPPDATA%`) plus the script's own
   **portable zip** made from the assembled app folder under
   `build/stable-win-x64/` (layout to confirm on the first real Windows build —
-  the step warns instead of failing).
+  the step warns instead of failing); Linux → only
+  `stable-linux-x64-miniSCP.tar.zst` + `update.json`, i.e. the updater feed and
+  nothing installable, so the script's **`.tar.gz` of the assembled app folder**
+  under `build/stable-linux-x64/` IS the release artifact (same best-effort
+  warn). No AppImage/.deb/.desktop — unpack and run the `miniSCP.sh` wrapper the
+  script writes beside `bin/launcher` (it applies the NVIDIA/DMABUF workaround,
+  which the app cannot set for itself — see gotchas.md).
+- **Linux builds need the AppIndicator dev libraries present to RUN** (not to
+  build) — see platform-notes.md; a packaged tarball started on a machine
+  without them dies at `dlopen`.
 - The script filters artifacts by app name, so stale artifacts from older
   brandings don't get collected.
 

docs/gotchas.md

@@ -63,7 +63,46 @@ touching the adjacent code.
 - Tray: never call `setImage` after construction on macOS — the template
   treatment is lost and the icon renders black on dark menu bars.
 - `ApplicationMenu` is macOS-only in our usage; accelerators on Windows are
-  single-character only. ContextMenu exists on macOS+Windows, not Linux.
+  single-character only.
+- **`ContextMenu.showContextMenu` is a silent no-op on Linux** (electrobun's own
+  `dist/api/bun/proc/linux.md` says so; the app also prints "Application menus are
+  not supported on Linux" at boot). Because the UI suppresses the webview's own
+  right-click menu, that left EVERY panel context menu dead on Linux — no error,
+  nothing happens. The menu is plain HTML now (`ui/src/app/context-menu.ts`) on
+  every platform; don't reintroduce the native one for "nativeness" on mac/win
+  without keeping a Linux path.
+
+## Linux
+
+- **`ERR_DLOPEN_FAILED` on `bun run start`** means a missing system library, not
+  broken app code. `libNativeWrapper.so` links `libayatana-appindicator3.so.1`
+  *hard* (for the tray), so the app cannot start at all without it — even though
+  the tray is a minor feature. Diagnose with
+  `ldd build/dev-linux-x64/*/bin/libNativeWrapper.so | grep 'not found'`; the
+  `libasar.so => not found` line in that output is a red herring (it ships beside
+  the wrapper and resolves at load). Install list per distro is in
+  [platform-notes.md](platform-notes.md).
+- **Black window on NVIDIA + `Failed to create GBM buffer of size WxH: Invalid
+  argument`** (usually with `X11 Error: GLXBadWindow (code 170)`). The app boots,
+  logs "miniSCP started", reports no error — and paints nothing. WebKitGTK's
+  DMABUF renderer can't allocate buffers on the NVIDIA proprietary driver;
+  `WEBKIT_DISABLE_DMABUF_RENDERER=1` is the upstream workaround.
+  - **The app cannot apply this to itself.** WebKit reads the variable when it
+    forks its web process, and **Bun's `process.env` writes do not propagate to
+    child processes** (verified: a spawned child sees it unset). Setting it in
+    `src/bun/index.ts` — even in a module imported before `electrobun/bun` —
+    does nothing. It must be in the environment before the app process starts.
+  - Hence every launch path injects it: `scripts/linux-gpu.ts` (`launchEnv()`)
+    for `bun run dev` / `bun run start`, and the `miniSCP.sh` wrapper that
+    `release.ts` writes beside `bin/launcher` in the tarball. **A new launch
+    path must call `launchEnv()` or it will render black on NVIDIA.**
+  - Gated on `/proc/driver/nvidia` so Intel/AMD keep hardware compositing, and
+    an explicit `WEBKIT_DISABLE_DMABUF_RENDERER` from the user always wins.
+  - A "does it boot?" log check does NOT catch this — grep for the GBM line, or
+    look at the window.
+- Benign startup noise on Linux — non-fatal, the app runs normally:
+  `libayatana-appindicator is deprecated. Please use libayatana-appindicator-glib`
+  (upstream electrobun's choice, not ours).
 - **Window-open flash prevention is three-layer** — remove any one and the
   white/inverted blink returns: (1) windows are created `hidden: true` and
   revealed by `showWhenReady` on the webview's first `dom-ready` (800 ms
@@ -122,9 +161,10 @@ touching the adjacent code.
   single-quoted entries** (`'…c'est…'`). Use double quotes for any value
   containing an apostrophe. Plurals are `{ one, other }` maps (not ICU strings);
   zh/ja supply only `other`.
-- **Native menus can't use the Angular service** — `menu.ts`/`context-menu.ts`
-  go through backend `i18n.ts`, and the app menu must be rebuilt when the locale
-  changes (wired in index.ts `settingsChanged`), or it keeps the old language.
+- **Native menus can't use the Angular service** — `menu.ts` goes through backend
+  `i18n.ts`, and the app menu must be rebuilt when the locale changes (wired in
+  index.ts `settingsChanged`), or it keeps the old language. The context menu no
+  longer has this problem: it is Angular now and reads `I18nService` directly.
 - `eu`/`zh`/`ja` are AI drafts pending native review (see the i18n README).
 - **Silent auto-refresh must snapshot sessionId+cwd and discard a mismatched
   result.** A normal `refresh()` is masked by `busy` (input blocked), but the

docs/platform-notes.md

@@ -1,35 +1,41 @@
-# Platform notes — macOS / Windows behavior matrix
+# Platform notes — macOS / Windows / Linux behavior matrix
 
-macOS is the primary target; Windows 11+ x64 is a **beta** target (win-arm64
-deferred; Linux untargeted — electrobun lacks menus/context menus there).
-Every platform seam carries a `PORTABILITY:` comment at the branch site.
+macOS is the primary target; Windows 11+ x64 and Linux x64 are **beta** targets
+(win-arm64 and linux-arm64 deferred). Every platform seam carries a
+`PORTABILITY:` comment at the branch site.
 
 ## Seam inventory (where platform branches live)
 
-| Concern | File | mac | win | other |
+| Concern | File | mac | win | linux |
 |---|---|---|---|---|
 | Window chrome | `src/bun/windows.ts`, `index.ts` | hiddenInset + traffic-light offset, UI drag header | native titlebar, compact header | same as win |
 | External editor launch | `src/bun/edits.ts launchEditor` | `open [-a app]` | `cmd /c start "" [app] file` | app directly / `xdg-open` |
 | Editor app picker | `rpc-handlers.ts pickEditorApp` | /Applications, `.app` | %ProgramFiles%, `.exe` | home, any |
 | Owner/group names | `fs/local.ts resolveId` | `id -nu` + `dscacheutil` | undefined → "—" | `id -nu` + `getent` |
 | Drive roots | `fs/local.ts listLocalDrives` | empty | `fsutil fsinfo drives` | empty |
-| chmod/Permissions | context-menu.ts, file-panel, file-actions | full | hidden for LOCAL panels (only flips read-only); SFTP unaffected | full |
-| Shell wording | `context-menu.ts` | Reveal in Finder / Move to Trash | Show in Explorer / Move to Recycle Bin | Show in File Manager |
+| chmod/Permissions | context-menu.service.ts, file-panel, file-actions | full | hidden for LOCAL panels (only flips read-only); SFTP unaffected | full |
+| Shell wording | `ui context-menu.service.ts` | Reveal in Finder / Move to Trash | Show in Explorer / Move to Recycle Bin | Show in File Manager |
 | Shortcut labels | `ui platform.ts MOD_LABEL/ALT_LABEL` | ⌘ / ⌥ | Ctrl+ / Alt+ | Ctrl+ / Alt+ |
-| Tray | `src/bun/tray.ts` | 22 pt template PNG | 16 px colored PNG | colored |
-| App menu | `src/bun/menu.ts` | full menu incl. About | none (early return) — About lives in the options popover | none |
+| Tray | `src/bun/tray.ts` | 22 pt template PNG | 16 px colored PNG | colored (needs AppIndicator, see below) |
+| App menu | `src/bun/menu.ts` | full menu incl. About | none (early return) — About lives in the options popover | none (unsupported upstream) |
 | connections.json protection | `store/connections.ts` | chmod 0600 | `icacls` current-user ACL (0600 is meaningless) | 0600 |
 | App data dir | `store/paths.ts` | ~/Library/Application Support | %APPDATA% | $XDG_CONFIG_HOME/.config |
 | ssh-agent | `fs/sftp.ts` | $SSH_AUTH_SOCK | `\\.\pipe\openssh-ssh-agent` fallback | $SSH_AUTH_SOCK |
 | Paths in UI | `ui format.ts joinPath/isRootPath` | "/" | separator detected from the dir string; drive-root regex | "/" |
 
+The **context menu is HTML on every platform** (`ui/src/app/context-menu.ts` +
+`context-menu.service.ts`), not a native electrobun menu — see the Linux section
+below for why. Only the three shell actions it can't do itself (reveal, open with
+the default app, copy path) cross to bun, via the `shellItemAction` RPC.
+
 Remote (SFTP) paths are ALWAYS POSIX regardless of host or server OS
 (`path.posix` throughout `fs/sftp.ts`).
 
 ## Memory footprint (expected, not a bug)
 
 Investigated 2026-07 — packaged build. Roughly **~200 MB macOS / ~300 MB
-Windows**, which is normal for a Bun + system-WebView app (30 MB is native /
+Windows** (Linux sits near macOS: WebKitGTK, like WKWebView, is lighter than
+Chromium), which is normal for a Bun + system-WebView app (30 MB is native /
 no-web-engine territory; Tauri-class apps run ~80–200 MB, Electron 150–400 MB).
 Not reducible to tens of MB without dropping the web UI.
 
@@ -49,6 +55,83 @@ Not reducible to tens of MB without dropping the web UI.
   each), and each open tab keeps both panels' full `entries` arrays; terminal
   transfers are retained until cleared. None affect normal use.
 
+## Linux runtime dependencies (REQUIRED — the app will not start without them)
+
+electrobun's `libNativeWrapper.so` links AppIndicator *hard* for the tray, so a
+missing library is a hard boot failure (`ERR_DLOPEN_FAILED` out of `bun:ffi`
+`dlopen`), not a degraded tray. The transitive deps (`libdbusmenu-glib`,
+`libdbusmenu-gtk3`, `libayatana-indicator3`, `libayatana-ido3`) come in as
+package dependencies:
+
+| Distro | Install |
+|---|---|
+| Arch / CachyOS | `sudo pacman -S libayatana-appindicator` |
+| Debian / Ubuntu | `sudo apt install libayatana-appindicator3-1` |
+| Fedora | `sudo dnf install libayatana-appindicator-gtk3` |
+
+GTK/WebKit itself comes from the distro too — electrobun uses the system webview
+(`bundleCEF: false`), so `webkit2gtk` must be present.
+
+Diagnosing a boot failure:
+
+```sh
+ldd build/dev-linux-x64/*/bin/libNativeWrapper.so | grep 'not found'
+```
+
+`libasar.so => not found` in that output is **expected and harmless** — it ships
+in the same `bin/` folder and resolves at load time; only an unresolved
+`libayatana-appindicator3.so.1` is fatal.
+
+**Tray visibility** is a separate matter from linking: GNOME 3.26+ hides the
+legacy tray, so the icon needs the
+[AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/).
+KDE Plasma, XFCE, MATE and Cinnamon show it out of the box. The app runs fine
+either way — the tray is a convenience, and every action it offers exists in-app.
+
+## Linux known issues (upstream electrobun)
+
+- **No native menus of any kind.** Application menus and `showContextMenu` are
+  both no-ops (electrobun's `dist/api/bun/proc/linux.md`; the app logs
+  "Application menus are not supported on Linux" at boot). The app menubar was
+  already macOS-only, and the panel context menus are now HTML on every platform,
+  so nothing is missing at the UI level — but do not add a feature that depends
+  on a native menu.
+- **NVIDIA renders black without the DMABUF workaround.** WebKitGTK can't
+  allocate GBM buffers on the proprietary driver, so the window paints nothing
+  while the log looks perfectly healthy. Every launch path sets
+  `WEBKIT_DISABLE_DMABUF_RENDERER=1` when `/proc/driver/nvidia` exists —
+  `scripts/linux-gpu.ts` for dev, the `miniSCP.sh` wrapper in the tarball for
+  releases. The app can't do it itself (Bun's `process.env` writes don't reach
+  child processes); see [gotchas.md](gotchas.md#linux).
+- **Benign startup noise**: a deprecation warning pointing at
+  `libayatana-appindicator-glib`. Not fatal.
+- **Unsigned, unpackaged**: the release artifact is a portable tarball — no
+  AppImage, `.deb`, `.desktop` entry or icon installation. Unpack and run
+  `miniSCP.sh` (which execs `bin/launcher`).
+
+## First-Linux-boot smoke test
+
+1. Install the AppIndicator package for your distro (table above), then
+   `bun run start`. The window opens **and actually renders the UI** (a black
+   window on NVIDIA means the DMABUF workaround didn't apply — check for
+   `Failed to create GBM buffer` in the log), and the tray icon appears (or
+   doesn't, on bare GNOME — that's the extension caveat, not a failure).
+2. Right-click a file row: menu appears at the pointer, Send to Other Panel is
+   first, Permissions is present, Escape / click-outside / arrow keys + Enter all
+   work, and a right-click near the bottom-right flips the menu instead of
+   overflowing.
+3. Right-click empty panel space (New Folder / New File / Refresh / Show in File
+   Manager) and a column header (checkmarks toggle columns live).
+4. Copy Path puts the path on the clipboard; Show in File Manager opens the
+   distro's file manager; Open (local file) launches the default app via
+   `xdg-open`.
+5. local↔remote transfers both directions; external editor round-trip
+   (temp download → save → auto-upload) with the inotify watcher.
+6. Move to Trash lands the item in the desktop's trash; connections.json is 0600.
+7. `bun scripts/release.ts --target linux-x64` produces
+   `release/linux-x64/miniSCP-Build<N>-linux-x64.tar.gz`; unpack it elsewhere and
+   run `miniSCP.sh`.
+
 ## Windows known issues (upstream electrobun, documented not fixed)
 
 - **HiDPI blur** — WebView2 renders at 1x on scaled displays