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

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