Desktop release build optimization: size, time, and one false lead

[radroid]

Context

The fork now builds and publishes a macOS + Windows desktop bundle on every green merge to main
(.github/workflows/t3x-release.yml, design: docs/superpowers/specs/2026-08-03-update-delivery-design.md).
Because that runs on every merge and ships to users over the update relay, both the size of what we
ship and the wall-clock of the build are now recurring costs rather than one-off ones.

Baseline from run 31215844454, the first
fully green release build:

Metric	Value
macOS arm64 build leg	7m14s (warm-ish runner)
macOS staged artifact (zipped dmg + descriptor)	149,875,427 B (~143 MiB)
Packaged prod node_modules	~200 modules

This issue collects the optimization surface. No action is urgent — the pipeline works. Filing so
it is not re-derived from scratch next time someone reads a build log.

---

1. "duplicate dependency references" is a false lead — do not chase it

electron-builder prints this in every build:

• duplicate dependency references dependencies=["@clerk/electron-passkeys@0.0.3",
 "effect@4.0.0-beta.102","debug@4.4.3","cross-spawn@7.0.6","shiki@4.4.2", ...]

It reads like a dependency-duplication problem. It is not. Verified against the actual implementation
in app-builder-lib@26.15.6:

• out/node-module-collector/pnpmNodeModulesCollector.js:100 pushes PKG_DUPLICATE_REF when a node in
  the pnpm list --prod --json --depth Infinity tree has dedupedDependenciesCount > 0 — i.e. when
  pnpm itself elided a subtree it had already printed elsewhere — and then re-resolves it from the
  full entry it already parsed.
• out/node-module-collector/moduleManager.js:21 classifies it as level info, not warn.

So the message means "this package is referenced by more than one parent", which is the normal, healthy
shape of any dependency graph. Measured on this workspace:

Package	References in the prod graph	Physical copies of that version
effect@4.0.0-beta.102	37	1
debug@4.4.3	33	1
@types/hast@3.0.4	29	1

One copy, many referrers — that is deduplication working.

The line that would actually matter is unresolved duplicate dependency references
(PKG_DUPLICATE_REF_UNRESOLVED, level warn), emitted when electron-builder cannot re-resolve the
elided subtree — that silently drops dependencies from the packaged app. It does not appear in our
builds. If it ever does, treat it as a release blocker.

2. Genuine duplicate installs (real, but trivial)

Three packages really are installed twice in the shipped bundle, via version conflicts:

Package	Copies	Cost
semver	7.8.5 (top level) + 7.7.4 (under electron-updater)	~51 files
onetime	5.1.2 (top level) + 7.0.0 (under restore-cursor)	~3 files
mimic-fn	3.1.0 (top level) + 2.1.0 (under onetime)	~3 files

Fixable with pnpm.overrides, but the payoff is a few dozen KB against a ~143 MiB artifact, and each
override is a root-package.json edit — i.e. a recurring sync-conflict cost. Recommend not doing
this unless we are already touching overrides for another reason.

3. The actual size surface

Measured package sizes in the install tree, with the chain that pulls each into the desktop app's
production graph:

Package	Size	Pulled in by
core-js	15 MB (3,684 files)	@clerk/electron → @clerk/clerk-js
playwright-core	12 MB	direct dep of @t3tools/desktop
@shikijs/langs	9.9 MB (724 files)	shiki language set
@pierre/diffs	8.7 MB (584 files)	diff rendering
@clerk/shared	6.6 MB (764 files)	@clerk/electron
lodash	4.9 MB	@clerk/clerk-js → browser-tabs-lock
shiki	3.8 MB	syntax highlighting
crypto-js, @stripe/stripe-js, @zxcvbn-ts/*	~4 MB combined	@clerk/electron → @clerk/clerk-js

The single largest cluster is @clerk/clerk-js's transitive tree (core-js + lodash +
crypto-js + @stripe/stripe-js + @zxcvbn-ts/* ≈ 25 MB). clerk-js is the browser bundle and
ships prebuilt dist files; the hypothesis worth testing is that none of that tree is reachable through
Node resolution at runtime in the Electron main process, in which case it is pure dead weight.

There is already precedent for exactly this fix. DESKTOP_FILE_EXCLUSIONS in
scripts/build-desktop-artifact.ts:630 is a fork-owned constant that already excludes one such tree:

export const DESKTOP_FILE_EXCLUSIONS = [
 // T3 Code always passes the user's installed Claude executable to the SDK,
 // so the SDK's optional platform packages (each a ~200MB bundled executable)
 // are dead weight. The trailing dash keeps the SDK's own JS package.
 "!**/node_modules/@anthropic-ai/claude-agent-sdk-*/**/*",
] as const;

Adding entries here is cheap and already on the seam ledger.

Suggested order of work

1. Instrument first — get a per-module size breakdown of the actual app.asar, not the install tree
   (npx asar list-size, or electron-builder's own size report). The numbers above are from the dev
   tree and are an upper bound, not the shipped cost.
2. Test the @clerk/clerk-js hypothesis by excluding the tree and running
   apps/desktop's smoke-test plus a real sign-in. Biggest win if it holds.
3. Check whether @shikijs/langs is genuinely reachable from the desktop graph or only from
   @t3tools/mobile — the trace was ambiguous, and the web client already ships its own per-language
   chunks (dist/assets/typescript-*.js etc.), so we may be shipping the grammar set twice.

4. Build time

• Build desktop bundle (serialised) now genuinely runs at --concurrency-limit 1 (it was silently a
  no-op before 8e3af08a1). That is the mitigation for the Windows STATUS_DLL_INIT_FAILED
  (0xC0000142) crashes in Windows desktop build intermittently fails with STATUS_DLL_INIT_FAILED (0xC0000142) in parallel vp tasks #47, and it costs wall-clock on both platforms. Worth revisiting whether
  the limit can be raised to 2, or scoped to Windows only, once we have a few green runs as a baseline.
• The mac leg spends real time on a cold pnpm store. Cache cargo and setup-vp's cache are already
  in place; a pnpm store cache is not.

Non-goals / traps

• Do not "fix" the other build-log warning by adding platform binaries to optionalDependencies:

  ⚠ platform-specific optional dependencies not bundled — add them to your project's optionalDependencies …
   dependencies=["@clerk/electron-passkeys-win32-x64-msvc@0.0.3","@ff-labs/fff-bin-linux-x64-gnu@0.9.4", …]
  

  Every package it names is for a different platform than the one being built. Acting on this advice
  would bundle Windows and Linux binaries into the macOS dmg. The arm64 binaries the mac build actually
  needs were all resolved and packed. This warning is correct behaviour and should be ignored.
• Do not drop playwright-core despite its 12 MB. It is loaded at runtime by
  apps/desktop/src/preview/PlaywrightInjectedRuntime.ts, which resolves playwright-core/package.json
  and injects its runtime source for the preview browser.
• Any change to root package.json / pnpm-workspace.yaml carries a per-sync rebase cost. Prefer
  DESKTOP_FILE_EXCLUSIONS, which is already fork-owned, over dependency-resolution changes.