ESM migration: convert lib batch 2 (ballot-interpreter group)

[eventualbuddha]

Overview

Library batch 2: the ballot-interpreter group — the two native/Rust libraries plus the two fixture/rendering libraries they depend on. One commit per library, in top-down order so that every intermediate commit is itself valid (ballot-interpreter first, since it is the only remaining CommonJS importer of hmpb and bmd-ballot-fixtures), plus a fifth commit regenerating some design-backend snapshots (explained below).

• ballot-interpreter (napi-rs native addon)
• pdi-scanner (cargo binary)
• hmpb
• bmd-ballot-fixtures

Every other importer of these four was already converted in the app stack, so the batch is importer-closed: central-scan-backend, scan-backend, mark-scan-backend, mark-backend, print-backend, design-backend, design-frontend, dev-dock-backend, integration-test-utils, fixture-generators, test-decks and scan-integration-testing are all ESM already.

Reviewer's main focus

Three things here are more than codemod output.

1. The napi-rs native binding. build:rust-addon now passes --esm, so napi-rs generates the root index.js binding as ESM (it reaches the .node file through createRequire) instead of CommonJS. That matters because index.js sits at the package root, where a nested package.json can't scope it back to CommonJS — and under "type": "module" node would otherwise parse it as ESM and it would die on its own require calls. napi.ts now re-exports that binding instead of require()-ing it by path, which also puts the addon in the module graph rather than loading it out of band.

2. styled-components interop in hmpb. styled-components v5 ships CommonJS only, so under node's ESM interop import styled from 'styled-components' evaluates to module.exports rather than styled — styled.div is undefined, and each template literal throws at import time. Vitest and Vite hand back styled itself instead (vitest applies its own interopDefault; Vite resolves the package's ESM build), so a fix that only satisfies one of them breaks the other. libs/hmpb/src/styled.ts normalizes it once, and the six modules that used the default import take styled from there. Named imports (css, ServerStyleSheet) need nothing — node's CJS named-export detection handles those.

This one is worth knowing about beyond this PR: libs/ui has the same default import many times over, and it renders server-side inside backends, so it will need the same treatment when its batch comes up.

3. The bin/ dev CLIs. These are extensionless files with a node shebang, so node picks their module system from the package's package.json — the moment "type": "module" lands they are parsed as ESM. They used to install the esbuild-runner require hook and require TypeScript sources directly, which now fails twice over: the hook is CommonJS-only, and it resolves .js specifiers literally so it cannot find the .ts files those specifiers now point at. All five (ballot-interpreter's interpret, diagnostic, scoring-report; hmpb's generate-fixtures, generate-vxprint-test-print; and pdi-scanner's demo) now import the compiled output instead. hmpb's two package scripts run build:self first, so pnpm generate-fixtures still works as one command and can no longer run against a stale build.

4. A fifth commit updates 64 design-backend PDF snapshots. apps/design/backend/src/test_decks.test.ts mocks formatBallotHash to '0000000' so its snapshots are deterministic, but that mock only ever applied to design-backend's own code: hmpb was CommonJS, so its built modules reached @votingworks/types through require() in a dependency vitest treats as external, which bypasses the mock registry. The committed snapshots had a real hash (dc2aa66) baked into the ballot footer. Now that hmpb is ESM the mock reaches it too, and the footer renders what the test asked for.

Comparing every regenerated snapshot against its predecessor pixel by pixel, all differences fall in rows 2120-2142 of 2200 — the footer line, nothing else. The metadata QR code is byte-identical, which confirms metadata.ballotHash itself did not change (formatBallotHash is display formatting; the QR encodes the raw hash). This is a change in test-mock scope, not in behavior — vi.mock does not exist outside tests. Worth expecting more of this as libraries with heavily-mocked APIs (types, utils) convert.

Also worth a look: ballot-interpreter's cli.ts imported once from node:stream, which does not export it. Under CommonJS that quietly produced undefined and would only have thrown if a write buffer ever filled; ESM's static named-export check turns it into an immediate load error. It now comes from node:events, which is where it lives and matches the call.

Demo Video or Screenshot

N/A — module-system change, no user-facing behavior change.

Testing Plan

Per library, locally:

	ballot-interpreter	pdi-scanner	hmpb	bmd-ballot-fixtures
tsc --build	clean	clean	clean	clean
eslint (+ stylelint)	clean	clean	clean	clean
vitest run	155/155	27/27	144/144	7/7
built output imports under plain node	yes, incl. native addon	yes	yes, incl. a styled-components template	yes
CLIs	all three print usage	—	—	—

The node import checks matter more than usual here: the unit tests run under vitest, which resolves modules the way Vite does, so they exercise the other side of every interop question in this PR. Importing the built output under plain node is what actually covers the way backends load these libraries — and it is what caught the styled-components breakage, which was invisible to both tsc (before the conversion) and vitest.

Repo-wide, on this branch: type-check passes for all 16 dependent packages (every app frontend and backend plus the dependent libs), and script/validate-monorepo is clean. CI covers the rest, including the integration tests that render ballots through hmpb in a real backend.

Checklist

• I have prefixed my PR title with "VxDesign: ", "VxPollBook: ", or "HWTA: " if my change is specific to one of those products.
• I have added logging where appropriate for any new user actions.
• I have added the "user-facing-change" label to this PR, if relevant, to automate an announcement in #machine-product-updates.

🤖 Generated with Claude Code