fix(tui): widen the root react range so an external ink can't split React

Review follow-up on #1983. Copilot was right, and about a hazard this repo
had already proven and then documented away: the claim that ink's ">=19"
peer "keeps npm from hoisting it next to a React the Inspector couldn't
also use" is false. A consumer pinning React 19.0 satisfies ">=19" while
`^19.2.4` nests underneath, so ink renders through their React and the
bundle through ours — the #1952 crash, one level up, breaking TUI startup
rather than just its forms.

Bundling ink closes it (verified: with a `createRequire` banner for the
inlined CJS, since react-reconciler calls `require("react")` and
signal-exit@3 `require("assert")`), but costs ~1.4MB — react-reconciler
and yoga-layout come along. The root `react` range closes it for free
instead: `^19.0.0` is open to the whole major, so npm can satisfy our
React and a consumer's pinned React 19 with one copy, and an external ink
resolves the same copy the bundle does.

Verified against both consumer trees — the reporter's (React 18 + ink 5)
and a pinned React 19.0.0 + ink 6.8.0, which splits under `^19.2.4`.

That makes the range load-bearing while looking like an ordinary version
bump, so the tests pin it: the root range must equal ink's own declared
peer floor. They also assert each exempt package is both external and a
root dependency — external means consumers install it, the mirror image
of the inlined ones, which must not be root-declared.

The docs in all four places now say ink is exempt on cost and never on a
peer range, and name that claim as one we got wrong.

Closes #1952

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLYmVPVLdeYpE6aMTUsCks
This commit is contained in:
cliffhall 2026-08-12 00:21:43 -04:00
commit 94a227b9c1

View file

@ -58,12 +58,18 @@ function stringEntries(list: (string | RegExp)[] | undefined): string[] {
}
/**
* The one React-rendering dependency deliberately left external.
* React-rendering dependencies left external by an explicit trade-off.
*
* `ink` cannot be bundled — its CJS `signal-exit@3` dependency fails ESM
* interop ("Dynamic require of \"assert\" is not supported") — and does not
* need to be: its `react` peer is ">=19", so npm cannot hoist it next to a
* React the Inspector itself could not use.
* `ink` is here for its **cost**, not because its peer range makes it safe.
* Bundling it works (verified against both consumer repros) but adds ~1.4MB —
* react-reconciler and yoga-layout come with it — plus a `createRequire` banner
* for the inlined CJS. The smaller tarball won.
*
* The exemption is only tolerable because the root manifest keeps `react` open
* to the whole major (`^19.0.0`), which lets npm dedupe our React with whatever
* React 19 a consumer pins — so an external `ink` resolves the same copy the
* bundle does. The test below pins that relationship: narrowing the root range
* silently reopens #1952 for the renderer itself.
*/
const EXTERNAL_BY_DESIGN = new Set(["ink"]);
@ -108,7 +114,7 @@ describe("tui tsup config", () => {
expect(reactRenderingDependencies().length).toBeGreaterThan(0);
});
it("bundles every React-rendering dependency that can be bundled", () => {
it("bundles every React-rendering dependency that is not exempt", () => {
const shouldInline = reactRenderingDependencies().filter(
(name) => !EXTERNAL_BY_DESIGN.has(name),
);
@ -123,17 +129,53 @@ describe("tui tsup config", () => {
}
});
it("keeps the root react range open to the whole major, so npm can dedupe", () => {
// This is what keeps the one exemption tolerable. `ink` is external, so it
// resolves whatever React npm placed beside it — and npm can only place it
// beside *ours* if our range admits the consumer's React too. Pinning the
// root range above the major floor (say `^19.2.4`) means a consumer holding
// React 19.0 gets a second copy: `ink` renders through theirs, the bundle
// through ours, and the TUI dies at startup on a null dispatcher.
//
// So the root range must start at the same floor `ink`'s own peer does.
const rootReact = (
JSON.parse(
readFileSync(path.join(clientDir, "..", "..", "package.json"), "utf8"),
) as { dependencies: Record<string, string> }
).dependencies.react;
const inkPeerReact = readPackageJson("ink").peerDependencies?.react ?? "";
const floor = /^>=(\d+)\.0\.0$/.exec(inkPeerReact)?.[1];
expect(floor, `unexpected ink peer range: ${inkPeerReact}`).toBeDefined();
expect(
rootReact,
`root react must be ^${floor}.0.0 so npm can dedupe with any React ${floor} a consumer pins`,
).toBe(`^${floor}.0.0`);
});
it("keeps each exempt package external, and declared for consumers", () => {
// An external package is not shipped in the bundle, so the root manifest
// has to install it — the mirror image of the inlined ones, which must NOT
// be root dependencies. Getting this backwards breaks the published TUI at
// startup with an unresolved import.
const rootDependencies = JSON.parse(
readFileSync(path.join(clientDir, "..", "..", "package.json"), "utf8"),
) as { dependencies: Record<string, string> };
for (const name of EXTERNAL_BY_DESIGN) {
expect(external, `${name} is external by design`).toContain(name);
expect(
Object.keys(rootDependencies.dependencies),
`${name} is external, so consumers must install it`,
).toContain(name);
}
});
it("keeps react itself external, as the single shared instance", () => {
expect(external).toContain("react");
expect(noExternal).not.toContain("react");
});
it("documents each React-rendering package left external", () => {
for (const name of EXTERNAL_BY_DESIGN) {
expect(external, `${name} is external by design`).toContain(name);
}
});
it("corrects ink-form's misspelled incomplete-form hint", () => {
// Read the real dependency, so an `ink-form` upgrade that fixes or rewords
// the label fails here — the patch must then be removed, not left silently