Migrate to Electrobun 2.0.2 (Hutch)

Electrobun 2.x replaces the vendored CLI with Hutch: the npm package is now a
bootstrap whose exports are a throwing stub, and the SDK is projected into
.hutch/devkit. The app stays on the Bun main process — `mainProcess: "bun"` is
load-bearing, since the 2.x default (Cottontail) ignores build.bun and with it
the ssh2 externals — and the bundle now ships the pinned Bun 1.4.0.

- electrobun 2.0.2 as an exact devDependency. `electrobun prepare` takes the
  old CLI re-sign step's slot in postinstall and every dev/build/start/release
  script: tsc (root tsconfig extends the devkit's) and the Angular build
  (electrobun/view mapped into the devkit) resolve the SDK there.
- Imports move to electrobun/main. The CLI re-sign script and the v1 "three"
  type shim are gone (Hutch's binaries are validly signed).
- UI: Electroview's bunSocket is hostSocket; noImplicitReturns is off because
  the devkit's raw-TS browser SDK compiles inside the UI program.
- Updater.applyUpdate() now consults before-quit, so the transfers/unsaved
  guard's "Quit Anyway" re-runs the apply instead of quitting without it.
- 2.x applies trafficLightOffset from macOS's default button position (1.18.1
  clamped it inside the titlebar); {12, 4} centres the lights in the header.
- Releases: mac-x64 dropped (2.x publishes no macOS x64 core, so no Rosetta
  path). artifacts/ is emptied before each build and published verbatim.
  Installers lost the stable- prefix (the update feed kept it), so release.ts,
  deploy.sh and the site links follow. Linux ships Electrobun's Setup
  installer instead of the portable tarball and its miniSCP.sh wrapper.
- Docs cover all of the above, plus re-checks against 2.0.2: still no native
  modal windows; window close is now cancellable through will-close.

Verified: tsc, build:ui, a stable mac-arm64 release (dmg + the v1-compatible
stable-macos-arm64 feed) and dev launches (RPC, Settings window, traffic
lights). Windows/Linux builds and the v1 -> 2.x Windows update bridge still
need their first run on native machines.

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

docs/architecture.md

@@ -6,15 +6,21 @@ Dense reference for development and debugging. Companion files:
 
 ## Process model
 
-- **Bun main process** (`src/bun/`): electrobun runs it inside a WebWorker of
-  its native launcher. Owns every privileged capability: filesystem, SSH,
-  window management, native menus/dialogs/tray, the connection/settings stores.
+- **Bun main process** (`src/bun/`): the native launcher runs electrobun's
+  `main.js` on the Bun the 2.x devkit pins (1.4.0, shipped in the bundle —
+  `build.mainProcess: "bun"`), which starts our bundle in a Worker. Imports the
+  SDK as `electrobun/main` (projected into `.hutch/devkit/`). 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 / 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`.
+  `webviewId` (each webview auto-connects using natively injected globals;
+  packets AES-GCM-encrypted per webview). 2.x Electroview queues sends while
+  its `hostSocket` connects and falls back to a native bridge when the socket
+  is unavailable. Requests are typed by the `AppRPC` schema in
+  `src/shared/rpc.ts`.
 
 ### The one-schema rule
 
@@ -39,7 +45,9 @@ Settings window). `rpc.send.*` on an instance targets exactly its own webview.
 exist until after construction). `AppDeps.events` is a mutable object of
 no-op functions, reassigned in `src/bun/index.ts` after everything exists:
 `sessionClosed`, `connectionsChanged`, `openEditor`, `settingsChanged`,
-`openConnectionManager`, `openSettings`, `showAbout`.
+`openConnectionManager`, `openSettings`, `showAbout`, `applyUpdate` (the
+update restart lives in index.ts beside the before-quit guard it must get past —
+see build-and-release.md "Auto-updater").
 
 ## Window kinds
 
@@ -50,9 +58,9 @@ scale so the first paint is already right. `ui/src/main.ts` picks the root
 component from `APP_MODE`; all four roots use selector `app-root` (index.html
 hosts only that tag). `chromeOptions()` is the ONLY place the native frame is
 decided, spread by the main window and `openSecondaryWindow`: macOS `hiddenInset` +
-`trafficLightOffset {x:12,y:13}` (the UI renders an `h-10 pl-24` drag-region
-header via `IS_MAC_CHROME`); other platforms keep the native titlebar and a
-compact `h-9` non-drag header.
+`trafficLightOffset {x:12,y:4}` (2.x semantics — see gotchas; the UI renders an
+`h-10 pl-24` drag-region header via `IS_MAC_CHROME`); other platforms keep the
+native titlebar and a compact `h-9` non-drag header.
 
 `WindowRegistry<Rec>` (same file): keyed window map with dedupe/activate,
 cascade placement off an anchor frame, focus tracking. electrobun's emitter
@@ -67,8 +75,9 @@ through a concrete session, and `local` is one shared session anyway).
 Re-opening focuses the existing window. The webview fetches its own content
 (`readFile`) — `openEditor` just creates the window with ctx in the preload.
 
-**Close safety** (electrobun window `close` is NOT cancellable — verified, no
-`allow` response like `before-quit` has):
+**Close safety** (designed when electrobun window `close` was NOT cancellable —
+1.18.1 had no `allow` response like `before-quit`; 2.x adds a cancellable
+`will-close` for the titlebar close, not used yet — see gotchas):
 1. ⌘W (routed via the app menu → `editorCloseRequest`) / Close button →
    styled in-window Save/Don't Save/Cancel; the confirm path calls
    `editorClose` which sets `suppressPrompt` before `win.close()`.
@@ -92,7 +101,9 @@ not `findInPage`, which is a shim on WebView2).
 ### Connection-manager window (`src/bun/manager-window.ts`)
 
 Single instance, centered over main, **modal to main only** (editors stay
-usable). No native modality exists, so three layers approximate it: bun
+usable). No native modality exists (re-checked on 2.0.2: no parent/owner/sheet
+option or input lock in any SDK or the core's exports; `styleMask.DocModalWindow`
+is only the cosmetic NSWindow bit), so three layers approximate it: bun
 bounces main's `focus` event back to the manager; the main webview renders a
 click-swallowing overlay (`managerState` message); main drops its keyboard
 shortcuts and bun drops main-targeted menu actions while open. Connect /
@@ -208,8 +219,9 @@ component; tokens → `ui/src/styles.css`.
   through plain callback registries, never signals**: a signal consumed from
   an effect that also writes signals re-triggers itself (this froze the whole
   app once), and signal coalescing drops progress snapshots. All requests are
-  gated on the socket-open promise — calls fired during boot would otherwise
-  be silently lost. `request` and `send` are ready-gated Proxies.
+  gated on the socket-open promise (`electroview.hostSocket`) — on 1.18.1 calls
+  fired during boot were silently lost; 2.x Electroview queues them itself, so
+  the gate is belt-and-braces now. `request` and `send` are ready-gated Proxies.
 - `panels.service.ts` — `PanelState` (per panel): sessionId, fsKey, cwd,
   entries, sort, cursor, selection, type-to-filter. `sorted` computed:
   filter → dirs-first sort (name/size/mtime numeric, kind/rights/owner/group

docs/build-and-release.md

@@ -14,81 +14,101 @@ semver-shaped (`0.1.<n>`) for electrobun's config/updater; `BRANDING.buildLabel`
 
 ## Dev loop
 
-- `bun run dev` — gen-version → scripts/dev.ts: starts `ng serve` (HMR) and
-  `electrobun dev --watch`, with `DEV_SERVER_URL` pointing the webviews at the
-  dev server (only honored on the dev channel and only if the server answers).
-- `bun run build` — gen-version → Angular build → `electrobun build`
-  (**dev channel** — fine for boot checks, NOT a release).
+- `bun run dev` — gen-version → `electrobun prepare` → scripts/dev.ts: starts
+  `ng serve` (HMR) and `electrobun dev --watch`, with `DEV_SERVER_URL` pointing
+  the webviews at the dev server (only honored on the dev channel and only if
+  the server answers).
+- `bun run build` — gen-version → `electrobun prepare` → Angular build →
+  `electrobun build` (**dev channel** — fine for boot checks, NOT a release).
 - `scripts/node-version-shim.ts` (preloaded via `bunfig.toml`, root AND ui/)
   fakes a Node version the Angular CLI accepts under Bun. Both preloads are
   load-bearing.
-- `scripts/fix-electrobun-cli.ts` re-signs electrobun's prebuilt CLI binary,
-  whose upstream ad-hoc signature is invalid — macOS SIGKILLs it and the app
-  silently never launches, with exit code 0 (see [gotchas.md](gotchas.md)). It
-  runs from `postinstall` **and** at the start of `dev`/`start`/`build`/
-  `release`, because the CLI is downloaded lazily on first use rather than at
-  install time; when the binary is missing it provokes that download first, so
-  a fresh checkout self-heals. Equally load-bearing — removing it means
-  `bun run start` does nothing at all.
+- **Electrobun 2.x is driven by Hutch.** The `electrobun` devDependency (exact
+  `2.0.2`) is only a bootstrap: its first command downloads the paired Hutch
+  (0.27.1) from the Electrobun GitHub release, checks its SHA-256 against
+  `hutch-artifacts.json`, caches it under `~/.hutch/npm/electrobun/<ver>/`, and
+  forwards every `electrobun …` to `hutch electrobun …`. Hutch then fetches the
+  Electrobun core, its build-time Cottontail and the pinned Bun 1.4.0 (the
+  runtime the app ships) into `~/.hutch` (~200 MB on a fresh machine) and
+  projects the SDK into the gitignored `.hutch/devkit/` (plus a gitignored
+  `.cottontail-tmp/` scratch dir). The devDependency version IS the toolchain
+  pin: moving Electrobun = bump it + `bun install`. No Node needed — the
+  bootstrap's `#!/usr/bin/env node` runs under `bunx`.
+- `bunx electrobun prepare` (re)projects `.hutch/devkit`. It runs from
+  `postinstall` **and** at the start of `dev`/`start`/`build`/`release` (~0.5 s
+  when current — the slot the v1 CLI re-sign step held; that step is gone,
+  Hutch's binaries carry valid signatures). tsc (the root tsconfig extends
+  `.hutch/devkit/tsconfig.json`) and the Angular build / `ng serve` (the
+  `electrobun/view` path in `ui/tsconfig.json`) resolve the SDK there *before*
+  any electrobun command would project it; without it both fail on unresolved
+  `electrobun/*` imports. Bun stays the package manager: Hutch's own resolver
+  (`hutch.lock`, no lifecycle scripts) only runs on `hutch install`, which
+  nothing calls — hence no `hutch.config.ts`.
 
 ## Release builds
 
-`bun scripts/release.ts [--target mac-arm64|mac-x64|win-x64|linux-x64]`
+`bun scripts/release.ts [--target mac-arm64|win-x64|linux-x64]`
 (default: host).
-Steps: gen-version → fix-electrobun-cli → gen-icons → Angular build →
-`electrobun build --env=stable` → copy/rename artifacts into
+Steps: gen-version → electrobun prepare → gen-icons → Angular build → empty
+`artifacts/` → `electrobun build --env=stable` → copy/rename the installers into
 `release/<target>/miniSCP-Build<n>-<target>.*`.
 
 Facts the script encodes:
 
-- **`--env=stable` is mandatory for releases** — the CLI defaults to the dev
-  channel (different app name `miniSCP-dev`, no distributable artifacts).
-- **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 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
-  `~/.cache/miniscp/electrobun-cli-x64-<ver>/`) and runs it directly —
-  Rosetta translates it, the CLI sees `process.arch === "x64"`, downloads the
-  `dist-macos-x64` core into the electrobun package dir on first use, and
-  packages a genuine x64 app. Note: Bun's `fetch`→`Bun.write` streaming hung
-  on the GitHub redirect chain; the script uses `curl -fsSL` deliberately.
-- **Both CLI binaries need re-signing.** The x64 CLI fetched for the Rosetta
-  path carries the same broken upstream signature as the arm64 one, so
-  `x64Cli()` re-signs it after download *and* on cache reuse; the native path
-  is covered by the `fix-electrobun-cli.ts` step up front.
-- **Core binary downloads**: the installed npm package ships mac-arm64
-  binaries only; other `dist-<os>-<arch>` cores are fetched from
-  `github.com/blackboardsh/electrobun/releases` at build time — network to
-  GitHub is a build-time requirement on every fresh machine/runner.
-- **Artifact shapes** (stable channel, in `artifacts/`): macOS →
-  `stable-macos-<arch>-miniSCP.dmg` + `.app.tar.zst` + `update.json`
-  (updater feed); Windows → `stable-win-x64-miniSCP-Setup.zip`
-  (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); 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).
+- **`--env=stable` is mandatory for releases** — `electrobun build` defaults to
+  the dev channel (different app name `miniSCP-dev`, no distributable artifacts).
+- **No cross-compile, and no Intel Mac.** Hutch builds for its host OS *and*
+  arch only; 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 and `linux-x64` on a
+  non-Linux host both error out. **Electrobun 2.x publishes no macOS x64 core
+  (nor an x64 Hutch)**, so mac-x64 was dropped — the v1 trick of running the x64
+  CLI under Rosetta has nothing left to run. `--target mac-x64`, and any build
+  on an Intel Mac, fail with that message.
+- **Runtime downloads**: on first use per Electrobun version Hutch fetches the
+  platform core from `github.com/blackboardsh/electrobun/releases`
+  (SHA-256-checked against `electrobun-artifacts.json`), plus Cottontail and the
+  pinned Bun, into `~/.hutch` — network is a build-time requirement on every
+  fresh machine/runner.
+- **`artifacts/` is emptied before the build** — `site/deploy.sh` publishes it
+  verbatim, so it must hold exactly this build (stale files, e.g. v1-named
+  installers, would otherwise ship).
+- **Artifact shapes** (stable channel, in `artifacts/`): 2.x installers carry
+  **no channel prefix**; only the updater feed keeps `stable-<os>-<arch>-` (the
+  names v1.18.1+ clients request). macOS → `macos-arm64-miniSCP.dmg` +
+  `stable-macos-arm64-miniSCP.app.tar.zst` + `stable-macos-arm64-update.json`
+  (verified); Windows → `win-x64-miniSCP-Setup.zip` (setup exe + hidden payload)
+  + the `stable-win-x64-*` feed, plus the script's own **portable zip** of
+  `build/stable-win-x64/miniSCP` (warns instead of failing if that folder is
+  missing); Linux → `linux-x64-miniSCP-Setup.tar.gz` (a self-extracting
+  `installer` + README) + the `stable-linux-x64-*` feed. The official Linux
+  installer IS the release artifact — the v1 portable tarball and its
+  `miniSCP.sh` NVIDIA wrapper are gone, so an installed build on NVIDIA needs
+  `WEBKIT_DISABLE_DMABUF_RENDERER=1` from the user (see gotchas.md). The
+  Windows/Linux names come from the 2.x docs — confirm on the first real 2.x
+  build there. A build that can reach the previous release at
+  `release.baseUrl` also emits `stable-<os>-<arch>-<previous-hash>.patch`.
 - **Linux builds need the AppIndicator dev libraries present to RUN** (not to
-  build) — see platform-notes.md; a packaged tarball started on a machine
+  build) — see platform-notes.md; an installed build 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.
+- **v1 → 2.x bridge**: Windows users on 0.1.78 (the only feed live on
+  miniscp.com/dl) update through their v1 updater because `app.name`,
+  `app.identifier` and `release.baseUrl` are unchanged, the build is
+  `--env=stable`, and `artifacts/` is published unrenamed. 2.x keeps the v1
+  top-level `update.json` fields (`version`/`hash`/`platform`/`arch`) and the
+  physical `stable` state root, so user data stays put. Unverified until the
+  first 2.x Windows release reaches a v1 install.
 
 ## CI (Gitea Actions)
 
-`.gitea/workflows/release.yml` — tag-triggered (`build-*`), macos + windows
-runner matrix, each running the same release script; inert until act_runners
-with those labels are registered. Needs `fetch-depth: 0` (the build number is
-the commit count). Runner prereqs are commented in the workflow file.
+`.gitea/workflows/release.yml` — tag-triggered (`build-*`), macos (mac-arm64) +
+windows (win-x64) runner matrix, each running the same release script; inert
+until act_runners with those labels are registered. Needs `fetch-depth: 0` (the
+build number is the commit count); `bun install --frozen-lockfile` already
+prepares the devkit (postinstall). Runner prereqs are commented in the workflow
+file.
 
 ## Download host (`site/` + Caddy)
 
@@ -96,27 +116,31 @@ the commit count). Runner prereqs are commented in the workflow file.
 internal box (plain HTTP `:80`, no domain/TLS). Deploys to `/srv/miniscp/`.
 
 - `site/index.html` — pure static, no JS, tinygrad-minimal. Download buttons link to **fixed
-  stable filenames** (`/dl/stable-macos-arm64-miniSCP.dmg`, …) so the page never changes per
-  release. Logo/screenshot `<img>` slots are commented in, images live in `site/assets/`.
+  stable filenames** (`/dl/macos-arm64-miniSCP.dmg`, `/dl/win-x64-miniSCP-Setup.zip`, the portable
+  zip) so the page never changes per release. 2.x dropped the `stable-` prefix from installer
+  names (the feed kept it), so the v1 `stable-…-Setup.zip`/`.dmg` installers still on the server
+  are stale — delete them by hand. Logo/screenshot `<img>` slots are commented in, images live in
+  `site/assets/`.
 - `site/Caddyfile` — one flat `/dl/*` folder with `file_server browse` + range requests, and
   per-type `Cache-Control`: `*.patch` immutable (unique hashed names), `*update.json` `no-cache`
-  (updater must see new versions), installers (`*.dmg *.zip *.tar.zst`) `max-age=300` (stable
-  names overwritten each release). Landing page has **no** SPA fallback → unknown paths 404.
+  (updater must see new versions), installers (`*.dmg *.zip *.tar.zst *.tar.gz`) `max-age=300`
+  (stable names overwritten each release). Landing page has **no** SPA fallback → unknown paths 404.
   Path matcher gotcha: use suffix globs like `*update.json`, not `*/*update.json`.
 - **One flat folder, no per-build dirs** — this layout IS electrobun's `artifacts/` feed, so it
-  doubles as the (future) updater `baseUrl`. Publishing = drop this machine's `artifacts/stable-*`
-  into `/dl/`; installers overwrite in place, `.patch` files accumulate (never delete them, or
-  older installs lose their incremental-update trail). **Tradeoff:** only the latest full
+  doubles as the updater `baseUrl`. Publishing = drop this machine's whole `artifacts/` into
+  `/dl/`, unrenamed; installers overwrite in place, `.patch` files accumulate (never delete them,
+  or older installs lose their incremental-update trail). **Tradeoff:** only the latest full
   installer is downloadable; old full versions are overwritten.
-- `site/deploy.sh` — run per build machine after `scripts/release.ts`; copies `artifacts/stable-*`
-  and renames the build-numbered win portable zip to the stable `stable-win-x64-miniSCP-portable.zip`.
-  `MINISCP_DL_DIR` overrides the target (stage locally, then rsync to the server).
+- `site/deploy.sh` — run per build machine after `scripts/release.ts`; copies `artifacts/*`
+  verbatim and renames the build-numbered win portable zip to the stable
+  `stable-win-x64-miniSCP-portable.zip`. `MINISCP_DL_DIR` overrides the target (stage locally,
+  then rsync to the server).
 - `release.baseUrl = https://miniscp.com/dl` is set in `electrobun.config.ts`; `miniscp.com` is
   fronted by an external proxy for TLS (Caddy itself stays on `:80` behind it). The value is baked
   into `version.json` at build time, so only builds made after it was added check for updates.
-  With `generatePatch` (default true), release builds now need **build-time network to
-  `miniscp.com/dl`** so electrobun can fetch the currently-published version to diff a `.patch`
-  (the first build after enabling it has nothing to diff and just ships the full artifacts).
+  With `generatePatch` (default true), release builds need **build-time network to
+  `miniscp.com/dl`** so Hutch can fetch the currently-published version to diff a `.patch` (a
+  target with no published feed yet — currently mac and Linux — just ships the full artifacts).
 
 ## Auto-updater (app side)
 
@@ -128,16 +152,21 @@ Wired on top of the download host above. See the "Auto-updater" section in
   `Updater.onStatusChange` streams `download-progress` (0–100) → `updateStatus{downloading}`.
   `checkForUpdate` self-guards the `dev` channel, so `bun run dev` never shows the pill.
 - **RPC** ([src/shared/rpc.ts](../src/shared/rpc.ts)): requests `checkForUpdate` / `downloadUpdate` /
-  `applyUpdate` (handlers in [rpc-handlers.ts](../src/bun/rpc-handlers.ts) call the electrobun `Updater`);
-  push message `updateStatus`.
+  `applyUpdate` (handlers in [rpc-handlers.ts](../src/bun/rpc-handlers.ts) call the electrobun `Updater`;
+  `applyUpdate` goes through `events.applyUpdate` in index.ts); push message `updateStatus`.
+- **`applyUpdate()` asks the before-quit guard first (2.x).** With transfers running or dirty
+  editors the guard vetoes and shows its Quit Anyway / Cancel box. `events.applyUpdate` marks the
+  quit as update-initiated, so Quit Anyway re-runs `Updater.applyUpdate()` (a plain `Utils.quit()`
+  would drop the downloaded update); Cancel leaves the pill at "Restart to apply".
 - **UI**: `UpdaterService` ([ui/src/app/core/updater.service.ts](../ui/src/app/core/updater.service.ts)) holds signals
   (`state`/`version`/`progress`); the tab-bar "update pill" ([tab-bar.ts](../ui/src/app/skins/shadlike/tab-bar/tab-bar.ts))
   is one accent (`bg-primary`) control that announces → fills as a progress bar while downloading →
   "Restart to apply". `state` is `available → downloading → ready` (ready derived from the
   `downloadUpdate` response). App-menu "Check for Updates…" ([menu.ts](../src/bun/menu.ts)) routes a
   `check-for-updates` menu action into `UpdaterService.check()`.
-- **Unsigned is fine:** `applyUpdate()` strips the macOS quarantine xattr before relaunch, so the
-  swapped bundle isn't Gatekeeper-blocked.
+- **Unsigned was fine on 1.18.1:** `applyUpdate()` stripped the macOS quarantine xattr before
+  relaunch. 2.x hands the swap to a native post-exit helper (transactional replace, restores the
+  old app on failure) — re-check Gatekeeper on the first unsigned 2.x mac update.
 
 ## Icons
 
@@ -149,8 +178,13 @@ Rerun after touching either SVG; outputs are committed (build inputs).
 
 ## electrobun config notes
 
-`electrobun.config.ts`: app identity comes from `BRANDING`; `build.bun.external`
-must keep `["cpu-features", "*.node"]` (ssh2's optional native accelerators —
-bundling them breaks the build; runtime falls back to pure JS);
-`build.copy` ships the Angular dist and tray assets into `views://`;
-`bundleCEF: false` everywhere (system WebKit / WebView2).
+`electrobun.config.ts`: app identity comes from `BRANDING`; **`build.mainProcess:
+"bun"` is load-bearing** — 2.x defaults to Cottontail, which ignores the whole
+`build.bun` block (verified: without the line, `bunx electrobun config
+--env=stable` resolves `mainProcess: "cottontail"` with no externals);
+`build.bun.external` must keep `["cpu-features", "*.node"]` (ssh2's optional
+native accelerators — bundling them breaks the build; runtime falls back to pure
+JS; a 2.x stable bundle keeps both as runtime `require`s); `build.copy` ships the
+Angular dist and tray assets into `views://`; `bundleCEF: false` everywhere
+(system WebKit / WebView2). `bunx electrobun config --env=stable` prints the
+merged config Hutch will build with.

docs/gotchas.md

@@ -87,6 +87,8 @@ touching the adjacent code.
   `webviewGetPageZoom` returns a hardcoded `1.0` from `.rodata`, so the failure
   is unobservable through the API — set 2.0, read back "1.0 = success". The
   JSDoc's "(WebKit only)" means macOS WKWebView. This is why the scale is CSS.
+  (Disassembled on 1.18.1; 2.0.2's zoom fixes are CEF-only — re-check the
+  native Linux wrapper before trusting it.)
 - **Everything the UI sizes with must be rem.** The scale works by setting the
   root font-size, so a px value freezes while everything around it grows. The
   px reservoirs were the panel-chrome tokens (`--row-h` etc.) and 93
@@ -101,25 +103,39 @@ touching the adjacent code.
 
 ## Electrobun
 
-- **The prebuilt CLI binary ships with a broken ad-hoc signature**, so macOS
-  SIGKILLs it at exec and `bun run start` prints nothing and exits **0** —
-  `bin/electrobun.cjs` spawns the real binary and forwards
-  `process.exit(code || 0)`, and a signal death has `code === null`. The binary
-  is a Bun single-file executable whose payload is appended *after* the linker
-  signed it, so `codesign -v` reports "code or signature have been modified";
-  the arm64 and x64 CLI tarballs are both affected upstream (confirmed by
-  hashing a fresh download against the shipped copy — it is not local
-  corruption, and re-installing does not help). `scripts/fix-electrobun-cli.ts`
-  re-seals it with `codesign --force --sign -`. It runs from `postinstall`
-  **and** ahead of every electrobun invocation, because the wrapper downloads
-  the binary **lazily on first use**, not at install time — postinstall alone
-  would no-op on a fresh checkout. It also fixes `.cache/electrobun`, which the
-  wrapper restores `bin/` from. Never read a silent `exit 0` from the
-  electrobun CLI as "nothing happened": run `codesign -v` on it first.
-- **Window `close` is not cancellable** (response type `{}`; only the
-  app-level `before-quit` supports `event.response = {allow:false}`). All
-  unsaved-state guards must either intercept app-controlled close paths
-  (⌘W, buttons) or survive the close (editor draft mirroring).
+- **The `electrobun` npm package (2.x) is a bootstrap whose every export is a
+  throwing stub** ("Electrobun 2.x APIs come from the Hutch devkit, not
+  node_modules"). Every `electrobun/*` import must resolve through the
+  projected `.hutch/devkit/`: the root tsconfig extends
+  `.hutch/devkit/tsconfig.json`, and `ui/tsconfig.json` maps `electrobun/view`
+  to `../.hutch/devkit/api/browser/index.ts` (the exact export-map target). Let
+  an import fall through to `node_modules/electrobun` and the webview throws at
+  load. tsc and the UI build fail on unresolved `electrobun/*` imports until
+  `bunx electrobun prepare` has run (postinstall and every dev/build script do
+  it). Never point anything into `~/.hutch` — that store is Hutch-owned.
+- **`build.mainProcess` defaults to Cottontail in 2.x**, and Cottontail ignores
+  the whole `build.bun` block — the ssh2 externals included, silently (verified
+  with `bunx electrobun config --env=stable`). `mainProcess: "bun"` in
+  `electrobun.config.ts` is load-bearing.
+- **The browser SDK is raw TS compiled inside the Angular program**, so the UI's
+  strictness flags apply to upstream code: 2.0.2's `createTransport().send`
+  returns on one path only, which is why `ui/tsconfig.json` has
+  `noImplicitReturns: false`. Its `import "./global.d.ts"` also prints "File
+  '…/global.d.ts' not found in TypeScript compilation" on every build — benign,
+  and adding the file to the program does not silence it.
+- **Window `close` is not cancellable, but 2.x added `will-close`.** The `close`
+  event's response type is `{}`; `will-close` (fired by the titlebar/traffic-light
+  close and `win.requestClose()`) honors `event.response = {allow:false}`, and
+  `win.close()` skips it. The editor close safety predates this: all
+  unsaved-state guards still intercept app-controlled close paths (⌘W, buttons)
+  or survive the close (editor draft mirroring) — a `will-close` prompt is a
+  possible follow-up.
+- **`Updater.applyUpdate()` asks the `before-quit` handlers first (2.x)**, so the
+  transfers/unsaved guard can veto an update restart. Its "Quit Anyway" must
+  re-run `Updater.applyUpdate()` (`events.applyUpdate` flags the quit as
+  update-initiated) — a plain `Utils.quit()` there quits without installing.
+  `Utils.quit()` runs the same approval, which is why the guard checks
+  `quitConfirmed` first.
 - **⌘W in any secondary window arrives as the MAIN window's `close-tab`
   menu action** (macOS: the app menu intercepts it before the webview sees
   the key). bun must check the focused secondary window first — the Settings
@@ -127,8 +143,10 @@ touching the adjacent code.
   check makes ⌘W close a main-window tab behind it.
 - **One rpc instance per window** — BrowserView binding steals the rpc's
   transport; a shared instance silently sends to the wrong webview.
-- **RPC before socket open is silently lost.** Everything gates on the
-  socket-open promise (RpcService `ready`).
+- **RPC before socket open was silently lost on 1.18.1.** 2.x Electroview queues
+  sends while its `hostSocket` (v1: `bunSocket`) is CONNECTING and falls back to
+  the native bridge; RpcService still gates everything on the socket-open
+  promise (`ready`) as belt-and-braces.
 - The emitter has no `off()`. Window event closures must not capture records
   you want garbage collected.
 - `electrobun build` defaults to the **dev** channel; release builds need
@@ -140,12 +158,13 @@ touching the adjacent code.
 - `ApplicationMenu` is macOS-only in our usage; accelerators on Windows are
   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/skins/shadlike/context-menu.ts`) on
-  every platform; don't reintroduce the native one for "nativeness" on mac/win
-  without keeping a Linux path.
+  `.hutch/devkit/api/sdks/main/proc/linux.md` says so, still in 2.0.2; 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/skins/shadlike/context-menu.ts`) on every platform;
+  don't reintroduce the native one for "nativeness" on mac/win without keeping
+  a Linux path.
 - **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
@@ -161,7 +180,8 @@ touching the adjacent code.
   URL, never hardcode `views://`.
 - Upstream Bun panic (`FFI_Callback_threadsafe_call` → `web_worker.spin`):
   rare segfault under long sessions; upstream electrobun×Bun issue, restart
-  recovers, nothing app-side to fix.
+  recovers, nothing app-side to fix. Seen on Bun 1.3.13 (Electrobun 1.18.1);
+  2.0.2 ships Bun 1.4.0 — unconfirmed whether that fixed it.
 - **Preloads and frames are construction-time only.** The preload is a
   persistent `WebKitUserScript` at DOCUMENT_START, frozen at webview
   construction — `webview.loadURL()` re-runs the OLD one
@@ -171,13 +191,25 @@ touching the adjacent code.
   correct live over RPC. Recreating the main window is not an escape hatch:
   `exitOnLastWindowClosed`, push closures and the tray capture it, and there
   is no `off()`.
+- **`trafficLightOffset` changed meaning in 2.x.** 1.18.1 nudged the buttons
+  by the offset but clamped them inside the stock titlebar, so `{12, 13}` really
+  meant "as low as the titlebar allows" (left 21 / top 18 on macOS 26). 2.x adds
+  the full offset to macOS's default position (9/9 in the 32pt Tahoe titlebar)
+  and grows the titlebar to fit — the same numbers dropped the lights 4pt.
+  `chromeOptions()` now passes `{12, 4}`: left 21 / top 13, the 14pt buttons
+  vertically centred in the 40px `h-10` header (1.18.1's clamped spot, top 18,
+  was 5pt low). The default shifts with macOS's titlebar metrics (28pt / 7
+  before macOS 26), so re-check after an OS release. `win.setWindowButtonPosition(x, top)` is the absolute
+  alternative (re-applied on resize/fullscreen) if per-version drift matters.
 - **Drag regions ignore `preventDefault`.** The preload starts a window move
   from a bubble-phase `mousedown` on `document` and never reads
   `defaultPrevented`; a `pointerdown` handler doesn't stop it either (the
-  compat `mousedown` still fires). `isAppRegionDrag` checks
-  `.electrobun-webkit-app-region-no-drag` first — that class on the element is
-  the only reliable suppressor (`dist/api/bun/preload/dragRegions.ts`).
-- **No resize, maximize-event or double-click-maximize primitives (1.18.1).**
+  compat `mousedown` still fires). `isAppRegionDragTarget` lets a `no-drag`
+  region win — the `.electrobun-webkit-app-region-no-drag` class (or, since
+  2.x, `app-region: no-drag` CSS) on the element is the only reliable
+  suppressor (`.hutch/devkit/api/preload/dragRegions.ts`; re-checked on 2.0.2).
+- **No resize, maximize-event or double-click-maximize primitives (1.18.1, still
+  absent from 2.0.2's `BrowserWindow`).**
   `titleBarStyle: "hidden"` drops the whole frame (Cocoa `Titled` — the only
   way to remove the traffic lights; `gtk_window_set_decorated(false)` on
   Linux) and with it the WM resize borders; nothing restores them (no
@@ -204,12 +236,15 @@ touching the adjacent code.
   - **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` —
+    `src/bun/index.ts` — even in a module imported before `electrobun/main` —
     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.**
+  - Only the dev launch paths inject it: `scripts/linux-gpu.ts` (`launchEnv()`)
+    for `bun run dev` / `bun run start`. **A new dev launch path must call
+    `launchEnv()` or it will render black on NVIDIA.** The release is the
+    official 2.x Setup installer now (the v1 portable tarball and its
+    `miniSCP.sh` wrapper are gone), so an installed build on NVIDIA needs the
+    user to launch it with `WEBKIT_DISABLE_DMABUF_RENDERER=1` (e.g. in the
+    desktop entry's `Exec`).
   - 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
@@ -296,7 +331,14 @@ touching the adjacent code.
   breaks `ng`.
 - ssh2's optional native deps must stay `external: ["cpu-features", "*.node"]`
   in `electrobun.config.ts` — bundling them breaks the build; ssh2 falls back
-  to pure JS at runtime.
+  to pure JS at runtime. (Inert without `mainProcess: "bun"` — see Electrobun.)
+- **2.x installers dropped the `stable-` prefix; the updater feed kept it.**
+  `macos-arm64-miniSCP.dmg` / `win-x64-miniSCP-Setup.zip` /
+  `linux-x64-miniSCP-Setup.tar.gz` next to `stable-<os>-<arch>-update.json`,
+  `.tar.zst` and `.patch`. Anything that globs `artifacts/stable-*` misses the
+  installers — release.ts collects by `<os>-<arch>-`, deploy.sh publishes
+  `artifacts/*` verbatim (release.ts empties `artifacts/` first), and the site
+  links the new names.
 - `bun run --cwd ui build` (flag order matters; `bun --cwd ui run build` does
   not do what you want).
 - `version.gen.ts` is gitignored and regenerated by postinstall + every build

docs/platform-notes.md

@@ -1,8 +1,9 @@
 # Platform notes — macOS / Windows / Linux behavior matrix
 
-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.
+macOS (Apple Silicon) is the primary target; Windows 11+ x64 and Linux x64 are
+**beta** targets (win-arm64 and linux-arm64 deferred). **Intel Macs were
+dropped** with the move to Electrobun 2.x, which publishes no macOS x64 core.
+Every platform seam carries a `PORTABILITY:` comment at the branch site.
 
 ## Seam inventory (where platform branches live)
 
@@ -81,7 +82,8 @@ 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.
+`libayatana-appindicator3.so.1` is fatal. (Hard link and path verified on
+1.18.1 — re-check both on the first 2.x Linux build.)
 
 **Tray visibility** is a separate matter from linking: GNOME 3.26+ hides the
 legacy tray, so the icon needs the
@@ -92,23 +94,26 @@ either way — the tray is a convenience, and every action it offers exists in-a
 ## 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
+  both no-ops (electrobun's `.hutch/devkit/api/sdks/main/proc/linux.md`, still in
+  2.0.2; 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).
+  while the log looks perfectly healthy. The dev launches
+  (`scripts/linux-gpu.ts`) set `WEBKIT_DISABLE_DMABUF_RENDERER=1` when
+  `/proc/driver/nvidia` exists; an installed build (the official Setup
+  installer) does not — launch it with that variable set (e.g. in the desktop
+  entry's `Exec`). 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`).
+- **Unsigned; Electrobun's own installer**: the release artifact is
+  `linux-x64-miniSCP-Setup.tar.gz` — a self-extracting `installer` + README
+  (2.x does the desktop-entry packaging and ships an uninstaller); no AppImage
+  or `.deb`. Layout unverified until the first 2.x Linux build.
 
 ## First-Linux-boot smoke test
 
@@ -130,21 +135,24 @@ either way — the tray is a convenience, and every action it offers exists in-a
    (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`.
+   `release/linux-x64/miniSCP-Build<N>-linux-x64-Setup.tar.gz`; unpack it
+   elsewhere, run its `installer`, then launch the installed app (on NVIDIA with
+   `WEBKIT_DISABLE_DMABUF_RENDERER=1`).
 
 ## 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.
+  (blackboardsh/electrobun#324, seen on 1.18.1). Most user-visible defect; 2.x
+  lists per-monitor DPI setup among its Windows fixes — re-check on the first
+  2.x Windows build.
 - **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.
+  SmartScreen / Mark-of-the-Web on first run. No Authenticode support (2.x:
+  "Windows release signing is not currently part of Hutch's packaging
+  pipeline"; a signtool post-hook is an option later). Installer unpacks to
+  `%LOCALAPPDATA%`, desktop shortcut only; 2.x installer builds add an
+  uninstaller (`%LOCALAPPDATA%\<identifier>\<install-root>\uninstall.exe`).
 - `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
@@ -155,10 +163,11 @@ either way — the tray is a convenience, and every action it offers exists in-a
 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).
+   Hutch, the core and the pinned Bun download into `~/.hutch` 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). A v1 0.1.78 install must pick up
+   the published 2.x build through its updater (the bridge release).
 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.
@@ -175,5 +184,5 @@ Code paths written blind (no Windows box was available); verify in order:
    user after saving a connection.
 9. Editor/manager/Settings windows open, modal bounce works, Ctrl+, opens
    Settings and About shows from its About section.
-10. Known-issue confirmation: HiDPI blur on a scaled display (expected until
-    upstream fixes it).
+10. Known-issue check: HiDPI blur on a scaled display (seen on 1.18.1 — 2.x's
+    per-monitor DPI setup may have fixed it).