Developer documentation: architecture, build/release, platforms, gotchas

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

docs/platform-notes.md

@@ -0,0 +1,71 @@
+# 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).