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
3 changed files with 150 additions and 62 deletions

View file

@ -121,28 +121,60 @@ choice decides which React instance it gets at runtime, and getting it wrong
crashes the TUI in a way nothing in this repo can see.
An external package's `import "react"` resolves from wherever npm placed **that
package** — and npm places it next to a React satisfying its own peer range.
`ink-form` and `ink-scroll-view` both accept `react: ">=18"`, so a project that
installs the Inspector alongside its own React 18 satisfies them: they hoist to
that project's root while the Inspector's React 19 nests underneath. The bundle
then renders through React 19 while those two call hooks on React 18, whose
dispatcher is null — so opening a tool test form (or any scroll view) dies with
package** — and npm places it beside a React satisfying *its* peer range, which
is looser than ours in every case here:
| Package | Its `react` peer | Placed beside a different React when… |
| --- | --- | --- |
| `ink-form`, `ink-scroll-view` | `">=18"` | the consumer has React 18 |
| `ink` | `">=19"` | the consumer pins React 19.0 (our `^19.2.4` then nests) |
Either way the bundle renders through one React while the external package calls
hooks on another, whose dispatcher is null — so opening a tool test form (or any
scroll view, or in `ink`'s case simply starting the TUI) dies with
`TypeError: Cannot read properties of null (reading 'useState')`.
Bundling them removes npm from the decision: their `import "react"` is emitted
into `build/index.js`, so it resolves from the build directory exactly like the
bundle's own. It also pins their transitive deps to what *this* install
resolved — notably `ink-select-input@6` via the `overrides` entry, since npm
ignores a dependency's `overrides` and a consumer install would otherwise pull
the React-18-era v5 that `ink-form` asks for.
`ink-form` and `ink-scroll-view` are therefore **inlined**, which removes npm
from the decision: an inlined package's `import "react"` is emitted into
`build/index.js`, so it resolves from the build directory exactly like the
bundle's own. Inlining also pins transitive deps to what *this* install
resolved, notably `ink-select-input@6` via the `overrides` entry — npm ignores a
dependency's `overrides`, so a consumer install would otherwise pull the
React-18-era v5 that `ink-form` asks for.
`ink` itself stays external: it can't be bundled (its CJS `signal-exit@3`
dependency fails ESM interop with `Dynamic require of "assert" is not
supported`), and it doesn't need to be — its `react` peer is `">=19"`, which
keeps npm from hoisting it next to a React the Inspector couldn't also use.
#### Why `ink` itself is the exception
`__tests__/tsupConfig.test.ts` enforces this: every dependency declaring a
`react` peer must be in `noExternal` unless it is listed as external by design.
`ink` is external for **cost**, not because its `">=19"` peer makes it safe — it
does not, and an earlier revision of this section wrongly claimed it did.
Bundling `ink` works (it was built and verified against both consumer repros)
but adds ~1.4 MB, since `react-reconciler` and `yoga-layout` come with it, plus
a `createRequire` banner: inlined CJS calls `require` at runtime
(`react-reconciler` for `"react"`, `signal-exit@3` for `"assert"`) and esbuild's
interop shim throws `Dynamic require of "x" is not supported` without a real
`require` in scope. A 602 KB bundle beat a 2 MB one.
What makes the exemption tolerable is a **separate lever**: the root manifest
declares `react: "^19.0.0"` — open to the whole major, rather than pinned at the
version we happen to develop against. That lets npm satisfy our React and a
consumer's pinned React 19.x with a single copy, so an external `ink` resolves
*ours*. Verified against a consumer pinning `react@19.0.0` alongside `ink@6.8.0`
— the case that splits under a narrower range:
```
bundle react node_modules/react/index.js
ink -> react node_modules/react/index.js # same copy
```
Narrow that range and the exemption turns straight back into #1952, one level
up — breaking TUI startup rather than just its forms. `tsupConfig.test.ts` pins
the root range to `ink`'s own peer floor so it can't drift silently. The
residual after all this is a React **20**-era consumer that also depends on
`ink`; that gets revisited when the Inspector moves to React 20.
`__tests__/tsupConfig.test.ts` enforces the whole split: every dependency
declaring a `react` peer must be in `noExternal` unless it is listed as external
by design, each exempt package must also be a root dependency (external means
consumers install it), and the root `react` range must stay open to the major.
Add a React-rendering dependency, and that test tells you to bundle it.
### The `ink-form` label patch

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

View file

@ -81,27 +81,38 @@ export default defineConfig({
sourcemap: false,
target: "node22",
platform: "node",
// Every package here renders React components, so it MUST share the one
// React instance the bundle imports. Bundling them is what guarantees that:
// an inlined package's `import "react"` is emitted into build/index.js and so
// resolves from *this* directory, exactly like the bundle's own — no consumer
// install layout can point it somewhere else (#1952). Left external, npm is
// free to hoist them next to a *different* React: `ink-form` and
// `ink-scroll-view` declare a loose `react` peer (">=18"), so a consumer
// project holding React 18 satisfies it and gets them hoisted to its own root
// while the Inspector's React 19 nests under it — two React copies, and the
// Every package here renders React components, so it MUST share the one React
// instance the bundle imports. Bundling is what guarantees that: an inlined
// package's `import "react"` is emitted into build/index.js, so it resolves
// from *this* directory exactly like the bundle's own, and no consumer install
// layout can point it elsewhere (#1952).
//
// Left external, npm is free to place a package beside a *different* React,
// because it places one beside a version satisfying that package's own peer
// range — looser than ours in every case here. `ink-form` and
// `ink-scroll-view` accept ">=18", so a consumer's React 18 satisfies them
// while the Inspector's React 19 nests underneath: two React copies, and the
// first hook they call reads a null dispatcher ("Cannot read properties of
// null (reading 'useState')") the moment a tool test form or a scroll view
// mounts. `__tests__/tsupConfig.test.ts` guards this list.
// mounts. That is the reported crash, and inlining them is its fix.
//
// `__tests__/tsupConfig.test.ts` guards this list.
noExternal: [/^@inspector\/core/, "ink-form", "ink-scroll-view"],
external: [
// `react` is deliberately external — it is the single instance everything
// above resolves to, from this build directory.
// `react` is deliberately external — the single instance every inlined
// package above resolves to, from this build directory.
"react",
// `ink` stays external too: it cannot be bundled (its CJS `signal-exit@3`
// dependency fails ESM interop with "Dynamic require of \"assert\""), and
// it does not need to be — its `react` peer is ">=19", which keeps npm
// from hoisting it next to a React the Inspector could not also use.
// `ink` is external by a deliberate trade-off, NOT because a ">=19" peer
// makes it safe — it does not, and that claim was wrong here once already.
// Bundling it works (verified) but costs ~1.4MB, since react-reconciler and
// yoga-layout come with it, plus a `createRequire` banner for the inlined
// CJS. The smaller tarball won.
//
// What makes that tolerable is the root manifest's `react: ^19.0.0`: being
// open to the whole major lets npm satisfy our React and a consumer's
// pinned one with a single copy, so an external `ink` resolves *ours*. Narrow
// that range and this exemption turns back into the #1952 crash, one level
// up — `__tests__/tsupConfig.test.ts` guards it.
"ink",
"open",
"commander",