Split utils into core and platform

[droplister]

utils/ was 139 files and 32,332 lines — 42% of the codebase, and every security-critical module lived in it. The name said "small helpers"; the contents were the domain.

That mis-naming isn't cosmetic. It's why my own review ranking went wrong earlier: sorting by directory or by direct import count put an icon barrel at the top and buried the modules everything depends on. api-status.ts has two direct importers and 290 files transitively depending on it — sitting unfiled at the root of "utils".

Why this split, on its own merits

The argument is a security property made enforceable, not a folder preference.

For a wallet, the code that derives keys, builds transactions and verifies them should be unable to depend on browser or session state. That's what lets it be audited in isolation, tested without mocking a browser, and reasoned about without asking "what was the extension doing at the time?"

I measured whether that property already held: every file checked for whether it — or anything it transitively imports — touches chrome.*, browser.*, wxt or webext-bridge.

	coupled	total
blockchain/	0	77	portable
validation/	0	14	portable
encryption/, qr-code/, hardware/	0	9	portable
storage/	9	10	platform
auth/	2	2	platform

100 of 139 files are fully portable, and exactly one file violated the boundary. So the property was already true by accident. This makes it true on purpose:

• core/ — cannot reach the extension runtime: message packing and unpacking, signing, key derivation, encryption, validation, formatting, the API client and its cache
• platform/ — is the extension: chrome storage, the session keychain, the dapp bridge, analytics, popup and proxy plumbing

The secondary benefit is ergonomic: "where does this new file go?" becomes an objective question — does it need chrome? — instead of a matter of taste. That's what stops a utils/ forming again.

One file crossed the line

walletManager.ts, the orchestrator, which reaches for session storage. Moving that single file took core's dependencies on platform from three to zero. Nothing else needed splitting; every other folder moved whole.

The rule is enforced, not documented

core/__tests__/layering.test.ts asserts platform may call into core but core may not reach back, and that no file under core touches chrome.* or imports webext-bridge / #imports / wxt/. An editor auto-import would otherwise undo this silently, and the entire value is in the direction holding.

Alternatives considered

• Rename utils/ → core/ and just file the loose root files. Less churn, fixes the naming, but creates no enforceable boundary — the thing that stops this drifting back.
• Feature/vertical slices (wallet/, transactions/, dapp/). Popular, and already how pages/ is organised — but wrong here. blockchain/bitcoin/psbt.ts isn't owned by one feature; this layer is genuinely shared infrastructure, and slicing it would duplicate or scatter it.
• Leave it and only file the root files. Cheapest, and legitimate if the churn isn't wanted. It leaves the 42%-named-"utils" problem in place.

Scope

534 files, +1227 / −1176 — but 269 are renames, and the edits are import specifiers plus Biome reordering them. No logic changed.

Verification

• tsc --noEmit clean
• biome check src clean (679 files)
• vitest run src — 4049 passed, 49 skipped, 217 files (up 3: the new layering test)
• wxt build succeeds, bundle unchanged at 2.46 MB
• playwright test on compose and dapp-approval paths — 20 passed
• CI caught one thing the local sweep missed: workflow YAML still referenced src/utils/hardware. Fixed in a follow-up commit.

Note on in-flight work

#232 (Trezor Connect 10, draft) touches utils/hardware/trezorAdapter.ts, now core/hardware/. It will need rebasing whenever v10 stabilises.

[droplister]

Squashed into #249.