miniSCP/docs/platform-notes.md

Platform notes — macOS / Windows 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.

Seam inventory (where platform branches live)

Concern	File	mac	win	other
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
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
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	"/"

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 / 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.

• macOS splits across several "miniSCP" processes: the Bun main (~120 MB: backend + the bundled electrobun runtime + live SSH sessions — the largest and least reducible piece), the views://app WKWebView content process (~60 MB, the Angular UI), and the standard WebKit Networking / Graphics and Media helpers. All are one app; WebKit just names them per-role.
• Windows is higher because WebView2 is Chromium (multi-process: browser + GPU + renderer + utility + crashpad), vs macOS's lighter WKWebKit.
• Measure against a packaged build — bun run dev inflates the WebContent heap (ng-serve, unminified, sourcemaps, live-reload) and is not representative.
• Verified non-issues: transfers stream (no whole-file buffering), icons tree-shaken to ~33 glyphs, zoneless Angular, 364 KB prod bundle.
• Only real growth levers if this ever matters: the file list is not virtualized (a directory with tens of thousands of entries retains a DOM row each), and each open tab keeps both panels' full entries arrays; terminal transfers are retained until cleared. None affect normal use.

Windows known issues (upstream electrobun, documented not fixed)

• HiDPI blur — WebView2 renders at 1x on scaled displays (blackboardsh/electrobun#324, open). Most user-visible defect; wait for upstream DPI awareness.
• Notifications are legacy balloon style (Shell_NotifyIcon), not Windows toasts.
• Unsigned binaries — Setup.exe and the portable exe both trigger SmartScreen / Mark-of-the-Web on first run. No Authenticode support in electrobun 1.18.1 (signtool post-hook or electrobun-builder are options later). Installer unpacks to %LOCALAPPDATA%, desktop shortcut only — no Start Menu entry or uninstaller.
• hiddenInset degrades to hidden on Windows — irrelevant here because non-mac windows use the native titlebar.
• findInPage is a window.find() shim on WebView2 — irrelevant here, the editor find is custom.

First-Windows-boot smoke test

Code paths written blind (no Windows box was available); verify in order:

1. Build: bun scripts/release.ts --target win-x64 on the Windows machine — core binaries download from GitHub releases on first run; Setup.zip AND the portable zip appear under release/win-x64/ (the portable step warns instead of failing if the assembled-app folder layout differs — fix the appDir path in release.ts if so).
2. App boots, tray icon renders colored, window has a native titlebar.
3. Drives dropdown in each panel lists C:\ (+ others); navigating to a drive root hides the '..' row; the path bar shows consistent \ paths.
4. local↔remote transfers both directions; self-copy guard still blocks same-path copies.
5. External editor: default app opens via cmd /c start; the Choose… picker starts in Program Files and accepts an .exe; remote temp-edit → save → auto-upload works (directory watcher on NTFS).
6. Context menus: Show in Explorer, Move to Recycle Bin (item restorable from the bin), Copy Path; Permissions ABSENT on local rows, present on remote.
7. Ctrl+T/W/F/S and Ctrl+digit tab jumps; tooltips read "Ctrl+…".
8. connections.json ACL: icacls connections.json shows only the current user after saving a connection.
9. Editor/manager windows open, modal bounce works, About shows from the options popover.
10. Known-issue confirmation: HiDPI blur on a scaled display (expected until upstream fixes it).