Replace the @jrichman/ink fork with upstream ink: decision and phased migration

[acoliver]

What would you like to be added?

A decision on, and a phased migration for, replacing the @jrichman/ink fork pinned in this repository ("ink": "npm:@jrichman/ink@6.4.8", root package.json:333 and packages/cli/package.json:90) with upstream ink, plus the porting work that requires.

Proposed sequence:

• P0, inventory and spike. Build a spike branch against one pinned upstream release (7.1.1 as of 2026-08-25), catalog every compile failure and behavior gap, and publish the list. No mainline dependency change. P0 must also validate the P1 inventory below: it was assembled by source inspection during the Every completed shell tool call permanently retains its child process and ~2.56 MB of output buffers #3329 investigation and may be missing further render-option, type, or behavior differences. P0 must additionally evaluate whether any community viewport package (ink-scroll-view, ink-scroll-list, ink-virtual-list; all exist on npm and declare Ink 7 compatibility) can supply clipping, translation, or scrollbar primitives before we build a full viewport layer; record the specific missing contracts if all are rejected.
• Selection go/no-go gate. After P0 and the selection design note below, maintainers approve or reject the interim selection architecture before P1 implementation begins. A valid outcome is to stop the migration, patch the current fork instead, or wait for a released upstream selection bridge if the proposed implementation requires broad UI rewrites or private Ink internals.
• P1, isolate fork-only surfaces while still building on the fork. Replace or wrap each confirmed fork-only dependency so production code no longer imports it:
  • selection model and hit testing: Range, comparePoints, hitTest, DOMNode, and useApp().selection are imported from ink in packages/cli/src/ui/hooks/useMouseSelection.ts; clipboard text comes from Selection.toString(); scroll targeting reads internal_scrollState and fork internals from the same file;
  • sticky headers: the sticky, stickyChildren, and opaque Box props in StickyHeader.tsx (used for tool message headers in ToolMessage.tsx) do not exist upstream;
  • scroll plumbing: VirtualizedList.tsx already owns scroll state but pushes translation, clipping, and scrollbar rendering into fork core via overflowY="scroll", scrollTop, and scrollbarThumbColor; upstream core is clip-only, so this needs an app-owned viewport layer that preserves the existing anchor, stick-to-bottom, imperative scrolling, smooth-scroll, wheel, keyboard, and thumb-drag contracts, and exposes scroll-coordinate translation for selection through an app-owned interface;
  • coordinates: fork getBoundingBox (used in useMouseSelection.ts:98,129, ScrollProvider.tsx, and useMouseClick.ts) walks ancestors and subtracts their scroll offsets for scroll boxes (visible in the installed node_modules/ink/build/measure-element.js). Upstream measureElement (Cancel does not drain queued tool calls; execution continues after user cancellation #968, released in 7.1.1) returns element boxes in live-layout coordinates and expects callers to convert using the live region's viewport anchor, so the replacement is an app-owned geometry service, not a drop-in rename: it must translate live-layout coordinates into terminal mouse coordinates, account for app-owned scroll offsets, and handle the inline case where <Static> output sits above the live region. P0 must prove how the viewport anchor is obtained;
  • render-mode plumbing: the repository's useAlternateBuffer setting is passed as fork option alternateBuffer (packages/cli/src/ui/inkRenderOptions.ts:137), read by mouseEventsEnabled.ts:18-21, and logged in startup diagnostics (interactiveUI.tsx:530). Upstream names this option alternateScreen, with lifecycle differences: map the option, update mouseEventsEnabled.ts and diagnostics, and characterize startup, resize, clear, failure rollback, and teardown behavior before the swap.
• P2 + P3, one merge gate: dependency swap behind acceptance. P2 flips both manifests to the chosen upstream release, updates bun.lock and package-lock.json, audits ink-gradient, ink-spinner, and ink-testing-library for compatibility with the selected release and React 19.2, removes ink-select-input (declared in both manifests, imported nowhere), and migrates the test harness (below). P3 defines acceptance. The swap branch must not merge until every P3 check passes or the corresponding behavior change is explicitly approved.
  • Release selection: 7.1.1 is the P0 spike target, not automatically the acceptance target. Upstream's fix for the unbounded measureText/wrapText caches (commit ad9e3ea, closing Project-scoped memories saved to .llxprt/LLXPRT.md are not loaded by memory discovery #986 and Tool scheduler hangs on result publishing - race condition in publishBufferedResults #987) landed on master on 2026-08-11, after the 7.1.1 release on 2026-07-16, so 7.1.1 still contains that leak. P2 must pin a published release containing the required memory fixes, or explicitly patch the remaining defects on top of the chosen release.
  • Test harness migration: most bun tests redirect bare ink and ink-testing-library imports to a stub (packages/cli/bun-test-setup.ts and the tsconfig.bun.json paths alias), so they prove nothing about a replacement package. A smaller set already exercises the real renderer through private build paths (test-utils/real-ink.ts, test-utils/ink-testing-library.ts). The acceptance configuration must bypass both redirect mechanisms, use supported imports instead of node_modules/ink/build/... deep paths, set the intended interactive mode (our custom test Stdout exposes columns but not isTTY; confirm how upstream's renderer treats that), and run the real package.
  • Acceptance checks: typecheck and build against the real package; real-ink component tests without the stub; PTY tests for inline mode; wheel/keyboard/thumb-drag scrolling; drag selection and copy; virtualized-list anchors, resize, stick-to-bottom, and variable-height behavior; sticky tool headers or an explicitly approved replacement; wide/combining characters, wrapped and nested text, and selection across boundaries; <Static> remount, clear, and long-output cases; screen-reader mode; and a new heap regression that repeatedly commits static content and asserts retained heap stays bounded (the shell heap-threshold tests from PR Eliminate per-execution shell retention and bound secondary accumulators #3343 do not cover Ink). Also: Bun execution and bundling (not only Node >= 24), both raw-package and published prebuilt-bundle launch paths, alternate-screen entry and restoration on normal exit, startup failure, signals, and resize, custom stdout/stderr proxy compatibility, incremental rendering and render-metrics callbacks, macOS/Linux/Windows differences where CI or PTY infrastructure permits, render latency and retained heap after replacing fork-native scrolling with app rendering, and license/attribution review if fork algorithms are copied into our source.
• P4, optional simplification if upstream selection lands. Upstream PRs Shell tool can hang indefinitely when PTY output processing stalls #984 (a read-only frame controller: cell grid, ink-side setSelection() highlight, subscribe()) and Project-scoped memories saved to .llxprt/LLXPRT.md are not loaded by memory discovery #985 (copy semantics: selectable, selectionFlow, boundaries) are open and unmerged; Project-scoped memories saved to .llxprt/LLXPRT.md are not loaded by memory discovery #985 is a draft stacked on Shell tool can hang indefinitely when PTY output processing stalls #984. Their PR descriptions target applications that own their viewport and selection logic; they remain proposals whose final API or scope may change. If both merge and ship a release with semantics we need, evaluate replacing the interim selection implementation with the bridge. Until then the interim implementation stands on its own; fork removal must not depend on an unmerged upstream schedule.

Selection port design note (gated deliverable before P1 selection work). The fork's hitTest/Range/Selection.toString() provide cell-to-text hit testing and copy reconstruction. Upstream has no public mechanism for cell-to-text mapping or renderer-level highlighting as of 7.1.1. The interim implementation needs a design covering: hit testing from screen coordinates to text offsets; copy reconstruction across wrapping, nested Text, transforms, ANSI styling, wide and combining characters, and current (not aspirational) selection coverage of virtualized or scrolled-off content; and highlight painting without rewriting every text-producing component. This is the largest open design risk in the migration; the existence of #984/#985 upstream reflects the same gap.

Non-goals: carrying two UI implementations long-term (temporary migration scaffolding during P1 is acceptable and should be deleted), rewriting the UI layer, and upstreaming our code beyond feedback on #984/#985.

Why is this needed?

1. Memory. In non-CI interactive rendering, the pinned 6.4.8 fork appends each nonempty <Static> chunk to a renderer-level fullStaticOutput string with no reset during the renderer lifetime (installed copy: node_modules/ink/build/ink.js, accumulation around lines 211-275), and replays it in debug, alternate-buffer, and full-terminal-clear paths. This is the Ink-side retention found during the Every completed shell tool call permanently retains its child process and ~2.56 MB of output buffers #3329 investigation and deferred by PR Eliminate per-execution shell retention and bound secondary accumulators #3343 (REQ-3329-09) to this follow-up. Upstream contains several <Static> correctness and lifetime fixes: dangling-node cleanup (fix: prevent duplicate output for streaming tools in subagents (#898) #905), keyed-remount correctness and stale-output reset (shell tool won't cancel #948 and Difficulty referencing specific lines in large file reads #950, released in 7.0.3), and full-clear line accounting (Provider switching from OpenAI back to Anthropic improperly clears context #974, released in 7.1.1). For this repository, Difficulty referencing specific lines in large file reads #950 should let keyed static refreshes discard stale accumulated output, but boundedness under our actual history and remount pattern must be shown by the P3 heap regression rather than asserted. The unbounded text-cache leak is fixed only on unreleased master (see P2 release-selection note).
2. Fork ownership cost. This repository pins fork 6.4.8 while the fork has since published 7.1.0 (last push 2026-06-24) and has diverged from upstream master in both directions: it carries fork-only work and is missing upstream fixes, including the memory family above at our pinned version. Staying on the fork means either synchronizing work we do not currently perform, or accepting that divergence permanently.
3. The known fork-specific surface is concentrated and bounded enough to inventory in a spike. The P1 list is the complete set found by source inspection during the Every completed shell tool call permanently retains its child process and ~2.56 MB of output buffers #3329 investigation; P0 exists to validate it and may add items (the render-option mapping above was found in a later pass).

Additional context

Alternatives considered:

• Patch installed 6.4.8 via Bun patchedDependencies (option recorded in project-plans/issue3329/plan.md): the smallest repository-local mitigation for the fullStaticOutput defect. Its coverage across the published prebuilt bundle, raw package execution, and npm-installed consumers using package-lock.json must be verified, as must behavior in the redraw and clear paths; it preserves the fork API surface, not automatically every behavior, and leaves the divergence and all other upstream fixes unaddressed.
• Upgrade to the fork's current 7.x and fix the leak there: may retain the fork-only scroll, sticky, and selection APIs; requires compatibility testing and confirming which upstream fixes the fork incorporated; fork ownership risk remains either way.
• Switch to upstream ink (this proposal): resolves the memory family at its source and ends fork ownership; requires replacing everything in the P1 inventory, with the interim selection engine as the main cost.
• Defer until upstream Shell tool can hang indefinitely when PTY output processing stalls #984/Project-scoped memories saved to .llxprt/LLXPRT.md are not loaded by memory discovery #985 are released: avoids building a disposable interim selection engine; leaves the known retention in place indefinitely and depends on upstream acceptance and release timing.
• Sequence: patch now, then evaluate migration after P0 and the selection gate: contains the immediate fullStaticOutput defect without committing to an interim selection engine, while keeping a separate path to upstream once replacement cost and release contents are known. This is viable because patching and migrating are not mutually exclusive, and because 7.1.1 itself lacks the unreleased text-cache fix.

This issue recommends the switch, with P0 and the selection gate as explicit exit points. The recommendation is open to challenge on the interim-selection cost; the data above is laid out so the tradeoff can be argued either way.

Data gathered 2026-08-25 (repository source inspection; upstream GitHub and npm via API):

Capability	Published in 7.1.1	Merged, unreleased (master)	Open proposal	Replacement we must own
<Static> lifetime fixes	#905; #948, #950 (7.0.3); #974	further fixes pending	-	heap regression to verify boundedness
measureElement coordinates	#968	-	-	geometry service over measureElement (scroll and viewport-anchor translation)
Unbounded measureText/wrapText caches	not fixed in 7.1.1	fixed by ad9e3ea (#986, #987) on 2026-08-11	-	release choice or explicit patch
suspendTerminal()	#972	-	-	not used
Selection highlight, hit test, copy	none	-	#984 open; #985 draft stacked on #984	full engine (interim)
Scroll regions and scrollbar	none (clip only)	-	-	app-owned viewport; community packages to vet in P0
Sticky headers	none	-	-	sticky/stickyChildren/opaque replacement
Alternate screen	alternateScreen option	-	-	rename from fork alternateBuffer plus lifecycle characterization
Mouse input	none in core	-	-	parsing already ours (utils/mouse.ts SGR/X11 parse, MouseContext.tsx stdin buffering) and reusable; mouseEventsEnabled.ts still rides the alternateBuffer migration

Known upstream open bug to watch while migrating: #973 (tall <Static> output can overwrite its last line).

Community-package download counts were not checked and are volatile; check npm at implementation time. Phase-level issues can be split out from P0-P4 once the direction is agreed.

[github-actions]

LLxprt Issue Planner — infrastructure failure

The planner agent did not produce planner/plan.md.

[acoliver]

P0 complete: inventory, spike, and selection design note

PR #3350 publishes the P0 deliverable. Documentation only, no mainline
dependency change, as P0 requires. Four documents plus a script appendix under
project-plans/issue3345/.

Method: compiled packages/cli against an out-of-tree install of ink@7.1.1
with only compilerOptions.paths.ink redirected, then ran behavioural probes
against both packages side by side. Every claim carries an E<n> citation into
the evidence pack or a file-and-line citation into source.

Compile catalog

Against the fork: 0 errors. Against upstream 7.1.1: 26 errors across 11
files, all attributable to the swap. useMouseSelection.ts accounts for 13 of
them.

The catalog is a floor. TypeScript stops after the first incompatible attribute
per JSX element, so VirtualizedList reports only overflowY even though
scrollTop and scrollbarThumbColor are equally absent upstream. The type-level
absence lists are the authoritative inventory.

The memory rationale needs revising in both directions

This is the part that changes the argument in the issue body.

Static retention. Upstream 7.1.1 still has fullStaticOutput and still
appends to it. Measured over 300 items, both packages retained exactly 61,990
characters for the same workload. Within one <Static> identity they are
identical.

But #950's reset fires on <Static> remount, and this application remounts far
more often than I assumed when writing the issue. refreshStatic() increments
staticKey from six production sites, not one:

• useClearScreenAction.ts:29-34 (clear screen)
• slashCommandProcessorSupport.ts:214-219 (slash-command ui.clear())
• useStaticRefreshManager.ts:65-82 (300 ms debounce on terminal resize)
• useStaticRefreshManager.ts:84-92 (deferred flush when streaming goes idle)
• useStaticHistoryRefresh.ts:28-49 (history shrink, trim, or compression)
• useKeybindings.ts:189-192 (markdown toggle)

So on upstream, accumulated static output is discarded on every resize, trim,
markdown toggle, and clear. On the fork it is never discarded. Upstream is
better than the fork on this axis, not equivalent, which is stronger than
reason 1 in the issue claimed. The size of the advantage is workload dependent
and P0 did not measure a production session.

Text caches. The opposite direction. Upstream 7.1.1's measureText and
wrapText caches are unbounded (new Map() and a plain object, no eviction).
The fork bounds its full-string styled-character cache with
DataLimitedLruMap(10_000, 1_000_000) and has no full-string wrap cache, though
its character-width map is unbounded. Isolated benchmark, one ASCII string shape:

Distinct strings	upstream 7.1.1	fork 6.4.8
20,000	21.9 MB	126.9 MB
50,000	55.6 MB	126.9 MB

Upstream grows linearly; the fork plateaus. Migrating to 7.1.1 as published is a
regression here. ad9e3ea fixes it with a 4,096-entry QuickLRU, is an ancestor
of master, and is in no published release. 7.1.1 remains the newest release.
PR #987 shows merged=false, state=closed; the change landed as a separate
commit.

Viewport anchor: proven, and the answer is that it cannot be queried

The issue assigned P0 to prove how the viewport anchor is obtained. It cannot be
obtained from either package.

With two <Static> lines and one live header line above the probed box, upstream
measureElement returns {x:0, y:1, ...} and fork getBoundingBox returns
{x:0, y:1, ...}. Both count only the live region. Neither counts the static
lines. The two implementations differ in exactly one respect: the fork subtracts
ancestor scroll offsets for overflow: scroll boxes.

useMouseSelection.ts:221-222 converts mouse input as event.col - 1 /
event.row - 1 and compares directly against geometry output, so it already
assumes the anchor is terminal row 0. That holds structurally today because
AlternateBufferLayout renders no <Static> and fills the terminal, and
mouseEventsEnabled.ts gates selection on alternate buffer. The recommendation
is to force the invariant rather than derive an offset, but PTY proof of it is
not done, so this P0 obligation is recorded as partially met rather than closed.

The two packages also differ more than a rename in alternate screen. The fork
homes and clears (ESC[1;1H, ESC[2J) every frame and repaints from row 1.
Upstream appends static output inline and erases only the prior live lines.

Scroll translation turns out to be free

Under an app-owned viewport (overflow: hidden plus marginTop: -scrollOffset),
upstream measureElement already returns scroll-translated coordinates. At
scrollOffset=5, row 5 measures at the viewport's own y and row 0 measures at
y=-4. The fork's scroll-offset subtraction has no replacement to build, and a
naive port would double-subtract.

Community viewport packages

All three evaluated individually against the current contracts.
ink-scroll-view's ControlledScrollView was run on upstream 7.1.1 and supplies
working clip and translate. ink-scroll-view also measures variable item heights
and exposes imperative offset methods; ink-virtual-list genuinely windows and
has a scrollbar render hook. All three are rejected as the viewport abstraction,
with residual missing contracts recorded per package. The recommendation is to
reuse the clip-and-negative-margin technique rather than add a dependency.

P1 inventory validation

All five items confirmed, two with corrections. Surfaces the list omitted:
Text.terminalCursorFocus/terminalCursorPosition, useApp().rerender,
Instance.recalculateLayout/getSelection, the textWrap union change,
userSelect removal, Node >=22, and fork-only ResizeObserver,
getPathToRoot, StyledChar, clearStringWidthCache,
setStringWidthFunction, plus the remaining geometry, scroll, and text exports.

ink-select-input confirmed declared and imported nowhere. Installed peer ranges
for ink-gradient, ink-spinner, and ink-testing-library already admit Ink 7.

The test harness holds up better than feared: the existing shim keeps working on
upstream because it passes debug: true, and upstream's debug branch runs before
its non-interactive branch. Without debug, upstream emits no frame until
unmount, because our test Stdout has columns but no isTTY.

Licensing

selection.js, scroll.js, layout.js, and vertical-gap.js in the fork carry
Copyright 2025 Google LLC and SPDX-License-Identifier: Apache-2.0 headers
inside an MIT-declared package. Upstream ships no such headers. Recorded for the
attribution review this issue already schedules. No legal determination made.

Recommendation for the selection gate

NO-GO on the interim selection port and on an immediate switch to 7.1.1.
Take the "patch now, then evaluate after the selection gate" sequence.

Reasoning: the static-retention correction improves the case for upstream, but
7.1.1 as published still regresses text-cache boundedness, exposes no selection,
hit-test, or highlight API, and gives no terminal anchor. The design note finds
that every interim selection architecture needs private renderer data, conversion
of the text-producing components, or a terminal-frame layer, all of which the
issue named as exit conditions.

Four conditions would reverse it, listed in the report. The strongest
counterargument was raised in review and is represented in the report rather than
dropped: 7.1.1 is the P0 spike target, not the P2 acceptance target, and P1 is
meant to run while still on the fork, so upstream's defects argue for delaying P2
more directly than for stopping P1. That is a fair reading and maintainers may
prefer it.

This is a recommendation, not a decision. Phase issues can be split out from
P0-P4 once direction is agreed.

[acoliver]

Revised P0 recommendation, after measuring the fork itself

The first pass recommended NO-GO and "patch the fork, then reassess". Two inputs
were wrong or missing. Correcting them changes the recommendation. Pushed to
PR #3350 as evidence E23 through E32.

1. I never inspected fork 7.1.0. It does not fix the leak.

The fork's latest is 7.1.0, published 2026-06-24. No npm publish and no repo
push since. It contains no handleStaticChange, no onStaticChange, no
previousStaticNode, so it did not take vadimdemedes/ink#950. Measured, it
leaks exactly like 6.4.8: 20,790 then 20,790 then 22,860 across a remount.

Compiling packages/cli against fork 7.1.0 costs 3 errors in one test file,
all because RenderMetrics gained required fields. So the fork upgrade is cheap
and still does not fix anything.

Its answer to the static problem is <StaticRender>, a fork-only API. It does
zero the accumulator, because it renders ink-static-render instead of setting
internal_static. The cost is writes:

shape	fullStaticOutput	stdout bytes	amplification
<Static>	61,990	70,901	1.2x
one <StaticRender> for all history	0	2,180,449	35.5x
one <StaticRender> per item	0	409,901	6.7x

Its own doc comment says array input is unsupported and incremental invalidation
for "very large, continuously growing lists" is unsolved. That is our history.

For accuracy: gemini-cli is not dead. It was pushed 2026-08-26 and pins
@jrichman/ink@6.6.9, a different line from both our 6.4.8 and the fork's own
7.1.0. The fork is dormant; its consumer is not.

2. The default configuration does not leak

ui.useAlternateBuffer has schema default true, and schema defaults are
materialised into settings.merged (verified by executing the real
mergeSettings with empty layers, not by reading the schema). So the default
session takes AlternateBufferLayout, which mounts no <Static> anywhere in its
tree. The only <Static> in the repository is DefaultAppLayout.tsx:345, in
StandardBufferLayout.

Exactly two inputs force standard buffer: an explicit non-true
ui.useAlternateBuffer in a winning settings layer, or screen-reader mode.
Screen-reader users are renderer-safe anyway because that branch writes static
output without accumulating, as are CI runs. Non-interactive and Zed/ACP never
build an Ink tree.

So the exposed population is interactive users who explicitly opted out. For them
it is worse than linear: history is bounded to 100 items / 1 MiB, but each of the
six refreshStatic() remounts re-emits the whole history into an accumulator
that never resets. Terminal resize is one of those triggers, on a 300 ms debounce.

3. The fix is upstream's own change, backported

Eleven added lines across two files: six in reconciler.js firing
onStaticChange() when the <Static> identity changes, five in ink.js to
reset and wire it.

	after 100 items	after remount	after 10 more
pinned fork 6.4.8	20,790	20,790	22,860
pinned fork + backport	20,790	0	2,070
fork 7.1.0 + backport	20,790	0	2,070
upstream 7.1.1	20,790	0	2,070

The same anchors applied unchanged to both fork versions, so it survives a fork
bump. It also survives distribution: patched node_modules, then bundle:cli
exit 0, then handleStaticChange and previousStaticNode each appear twice in
the freshly built bundle/llxprt.js. The published bin prefers the bundle, and
patch-package is already a devDependency. The patch itself is in the
reproduction appendix.

Not yet tested, and prerequisites before it ships: terminal behavior after the
reset in a PTY, standard-buffer resize and clear, and screen-reader mode. The
patched fork matches upstream 7.1.1's structure and reset semantics rather than
inventing new ones, but that is equivalence, not measurement.

4. Recommendation

Two tracks.

Fix the leak now with the backport on the pinned fork. It needs no API
adaptation, risks nothing in selection, sticky, or scroll, and is deleted the
moment the migration lands because upstream already ships it.

Commit to upstream as the destination, not the fork. Sequence A, C, B, D:

• A, alternateBuffer to alternateScreen. Small, about 8 files. The work
  is PTY acceptance of the row-zero invariant, because the fork homes and clears
  every frame while upstream appends inline and erases prior lines.
• C, scroll plumbing. Medium, 4 to 6 production files. ScrollProvider
  already owns thumb geometry, hit testing, wheel routing, and dragging;
  VirtualizedList already owns scroll state and windowing. Clip and translate
  are overflow: hidden plus a negative margin, measured working, after which
  measureElement returns already-translated coordinates. The only missing piece
  is painting the thumb.
• B, sticky headers. Medium-high for parity, small if you accept tool headers
  scrolling away with their output.
• D, selection. The gate.

A, C, and B can each land while still building on the patched fork, since none of
them depends on selection.

5. The selection gate moves from NO-GO to conditional

I have to retract the reason my design note gave. It said a tree port needs
private Ink internals. It does not. A spike importing only public values and
types from ink walked the root ref, resolved cell (5,0) to UTF-16 offset 3
inside an ink-text box measured by public measureElement, and painted inverse
video through the public Transform. It passed tsc --noEmit and produced
ab<INV>cde</INV>f.

What upstream withholds is a renderer-final cell map, so parity work is real:
wrapping, nesting, transform ordering, ANSI composition, wide and combining
characters, and roughly 137 direct Text import sites. One fact bounds it:
selection is only enabled in alternate-buffer mode, which renders through the
windowed list, so the engine only ever maps the mounted viewport, never full
history.

The gate should be decided by a bounded prototype scoped to that viewport, not by
the earlier flat NO-GO.

[acoliver]

Scope correction: this issue does not describe the leak seen in ordinary use

Worth stating plainly, because this issue's first stated reason is memory and
that framing is misleading.

fullStaticOutput only grows when a <Static> node emits. <Static> is mounted
in exactly one place, DefaultAppLayout.tsx:345, inside StandardBufferLayout.
ui.useAlternateBuffer defaults to true and schema defaults are materialised
into settings.merged, so the default session renders AlternateBufferLayout,
which mounts no <Static> anywhere in its tree. The accumulator this issue is
built on is unreachable in the default configuration.

So growth observed in normal use is a different problem, and it already has a
history here:

Issue	State	Subject
#2852	closed	Bun/Ink memory amplification. Allocator churn root-caused to an O(N²) streaming pipeline, fixed in #2885
#2905	open	Attribute and bound native IOSurface/IOAccelerator growth. The #2852 signature that was deliberately not claimed as fixed
#3114	closed	Unbounded long-session growth. Added post-GC plateau verdicts for JSC heap, Bun external memory, and dirty WebKit Malloc
#3329 / #3343	closed / merged	Per-execution shell process and buffer retention

#2905 is the live one, and it records the signature as a 22.8 GB physical
footprint with ~13.8 GB dirty WebKit Malloc and ~8.6 GB IOAccelerator on an
image-bearing resumed session. Two constraints from #2852 that any leak claim has
to respect: RSS is not a valid leak criterion under Bun and JSC (that run
showed 190 MB RSS against a 24 MB physical footprint), and LLxprt source makes no
direct use of Metal, IOSurface, IOAccelerator, or WebGPU, so those surfaces come
from Bun, JSC, or macOS frameworks.

Tooling already exists: npm run mem:profile (see docs/memory-profiling.md) and
scripts/issue-2852-memory-{target,runner,benchmark}.ts.

One finding here that does apply in the default mode

The styled-character cache runs on every text render in every mode. Rendering
20,000 distinct strings and sampling heapUsed after forced GC, two runs each:

Ink build	heap growth
pinned fork 6.4.8	~131.9 MB
fork 7.1.0	~1.9 MB
upstream 7.1.1	~120.1 MB

The pin caches arrays of StyledChar objects bounded at 10,000 / 1,000,000. Fork
7.1.0 uses a compact StyledLine bounded at 2,000 / 100,000. Upstream 7.1.1's
equivalents are unbounded.

Two consequences that cut against what I wrote earlier in this issue:

1. On this axis the current pin is close to the worst of the three, and moving
   to upstream 7.1.1 as published would not improve it. Upstream master's
   QuickLRU change would, but it is unreleased.
2. Fork 7.1.0 is roughly 69x better here and costs 3 diagnostics in one test
   file to compile against. A 6.4.8 to 7.1.0 bump is a candidate default-mode
   memory improvement on its own terms, independent of both the static
   accumulator and the migration. It does not change the destination argument,
   since the fork is still inactive.

Limits: JS heap only, synthetic, one string shape. It measures nothing native and
says nothing about IOAccelerator.

Recorded as E33 and E34 in PR #3350, and the report now carries this scope
correction up front rather than implying it addresses ordinary-use growth.

[acoliver]

Retraction, and a reproducible Ink render-path leak

My last comment recommended a 6.4.8 to 7.1.0 bump as a default-mode memory
improvement, based on measuring the styled-character cache in isolation.
That recommendation is withdrawn. Taking it would have made memory worse.

Why the earlier measurement misled

The existing scripts/issue-2852-memory-target.ts has three modes, text,
media and reasoning. All three drive PendingResponseBuffer and the
streaming pipeline. None of them renders through Ink. So the post-GC plateau
verdicts #3114 added cannot observe an Ink render-path leak at all. I added that
missing dimension: a Bun probe rendering the alternate-buffer shape
(terminal-sized, overflow: hidden, no <Static>), 38 distinct <Text> lines
per frame, Bun.gc(true) checkpoints sampling bun:jsc heapStats() and
process.memoryUsage(), with vmmap -summary sampled against the pid.

Result, identical 18,000-frame workload per build

Post-GC JSC heap, MB:

Turn	fork 6.4.8 (pin)	fork 7.1.0	upstream 7.1.1
1	116.36	84.36	67.31
2	114.70	159.75	92.15
3	114.64	236.84	108.55
4	115.56	312.10	141.26
5	115.46	387.42	156.68
6	115.19	464.47	173.18

The pinned fork is the only one that plateaus, within 1% across turns 2 to 6.
Fork 7.1.0 grows ~76 MB per 3,000 frames and upstream 7.1.1 ~21 MB, neither
settling over six turns. Upstream also grows external linearly from 36.75 MB to
90.57 MB, consistent with its unbounded measure and wrap caches.

End-of-run native metrics:

Metric	fork 6.4.8	fork 7.1.0	upstream 7.1.1
WebKit Malloc virtual	5.0 G	5.0 G	5.4 G
WebKit Malloc dirty	198.0 MB	527.9 MB	897.8 MB
Physical footprint	230.3 MB	562.2 MB	930.8 MB
IOAccelerator dirty	19.2 MB	22.5 MB	19.3 MB

What this means

1. Both candidate upgrade targets introduce a render-path leak the current pin
   does not have. That is a constraint the migration has to answer, not an
   argument against migrating, but it cannot be waved through.
2. Ink rendering alone reproduces the WebKit Malloc high-water signature —
   ~5 GB virtual against far smaller dirty — with no streaming, no media, and no
   shell activity. That is the same allocator-churn shape Analyze and fix long-running Bun/Ink memory amplification on macOS #2852 attributed to the
   streaming pipeline, arriving from a second source that the current guards do
   not watch.
3. IOAccelerator stays flat in all three, so this does not reproduce the
   IOAccelerator half of Attribute and bound native IOSurface/IOAccelerator memory growth for image-bearing sessions (#2852 follow-up) #2905.

Caveat

The workload is adversarial: every line of every frame is distinct, the worst
case for any text cache. Real sessions repeat content. Build-to-build comparison
is sound because the workload is identical, but the absolute figures are not a
production forecast. One machine, one Bun version. It also does not attribute an
allocation site; that needs the native tooling #2905 specifies.

Suggestion

The gap worth closing regardless of the migration decision is that the memory
guards have no Ink dimension. Adding an ink mode to the issue-2852 target,
with a post-GC plateau verdict, would have caught this and would catch a
regression introduced by any future dependency swap. Recorded as E35 in
PR #3350, with the probe published in the reproduction appendix. E33 and the
report subsection built on it are marked superseded rather than deleted.