fix(ui): stop unrelated re-renders from rewriting tooltip anchors

[Astro-Han]

Summary

PR A of #2030. A streamed answer drops the desktop app from 118fps to 22fps. One contributing layer sits in @astryxdesign/core: every unrelated re-render rewrote DOM attributes on tooltip triggers that had not changed.

Tooltip attached its trigger from two layout effects that listed tooltip.ref as a dependency and never listed the element they actually read (anchorRef.current, or wrapper.firstElementChild). useTooltip composes tooltip.ref from useLayer's context ref, which is a fresh inline closure per render, so both effects tore down and re-ran on every render of every tooltip on the page. Each run unconditionally executes removeAttribute/setAttribute('aria-describedby') and removeAnchorName/addAnchorName — and the latter pair writes inline style.anchor-name, which dirties style. The cost is O(every tooltip trigger on the page) per unrelated parent re-render.

What this actually buys, in the A+B world

Every one of those writes lands on footer buttons belonging to history, not to the turn being streamed: chat-turn.tsx:590-597 renders the live turn's footer as an aria-hidden placeholder <div> with no Tooltip in it. So the write count is a product of two factors, and this PR only moves one of them:

• how many history turns re-render — what refactor(ui): stream the transcript incrementally instead of re-deriving it per token #2034 (PR B) exists to cut down
• what one such re-render costs per turn — 24 writes, which this PR takes to 0

This PR is therefore not "a fix for 44608 writes". It makes any re-render that legitimately happens free at the trigger, and it keeps being worth having after PR B lands, because PR B reduces the count rather than guaranteeing zero.

Measured, CDP, same real session and same stress each time

	no patch	useLayer half only	both halves
footer button attribute writes	44608	0	0
history turns re-rendered	22/22	24/24	23/23
p95 frame time	134.1ms	9.3ms	10.5ms

Scope note: this CDP run predates the shrink and its third column is the two-half patch. The 0-writes result carries over unchanged — it is produced entirely by the Tooltip half, and the unit guard proves the element-keyed effect writes nothing on an unrelated re-render with useLayer pristine (four-way table below). The only behavioural delta the shrink introduces is per-render listener rebinding, which cannot dirty style or layout at all (see below). The frame-time column has not been re-measured against the shrunk patch.

The fix: key each piece of state on what it is actually about

A tooltip puts two different kinds of state on its trigger, and upstream keyed both on tooltip.ref:

• The inline anchor-name and aria-describedby describe the element. They are bookkept against element identity and skipped when the trigger has not moved. This is the entire cost.

• interactionRef installs event listeners closing over current props (isEnabled, delay, hideDelay, focusTrigger, onOpenChange). removeEventListener matches only the exact function that was added, so these are bound and released by React's own per-render effect cleanup:

  constdetach=tooltip.interactionRef;detach(target);return()=>{detach(null);};

  React runs the cleanup a render created before the next render's effect body, so detach is always the very closure that added the listeners. An earlier revision maintained a boundRef{el, detach} record to guarantee the same thing by hand; that is React's guarantee, not this component's job, and the bookkeeping is gone.

Upstream was correct only by accident, and in both directions at once: because tooltip.ref changed every render, every render happened to rescan the DOM (correct, and the whole cost) and happened to rebind listeners with fresh closures (correct, and free of style/layout work). Fixing only one half breaks the other:

	unrelated re-render writes nothing	trigger replaced is adopted	late child is attached	controlled open writes nothing	disabled-after-mount suppresses hover	unmount leaves no listener
no patch	✗	✓	✓	✗	✓	✓
useLayer half only	✓	✗	✗	✗	✗	✗
Tooltip half only (this PR)	✓	✓	✓	✓	✓	✓

An element-keyed attach is not simply idempotent, and three separate corrections say why:

• Detach removes only this tooltip's own id from aria-describedby instead of restoring the attach-time snapshot. A snapshot goes stale the moment anything else writes to the attribute — two tooltips sharing a trigger, or the app updating it mid-mount — and restoring it un-describes the other writer or resurrects a value the app already replaced.
• aria-describedby is a value invariant, not an element-identity invariant. With the element unchanged, an early return skips a trigger whose aria-describedby the application rewrote from its own props: React writes the new value, this tooltip's id is gone, and nothing puts it back — the description breaks permanently and does not self-heal. The unchanged-element path now re-reads the attribute and re-asserts its own id when it is missing. Reading is not a write, so the zero-write steady state is untouched.
• Detach must not route through useLayer's ref.layer.ref(null) removes the anchor name from whatever element useLayeritself last held (useLayer.js:215) — not necessarily the element this tooltip attached to. When element children are replaced by text children, the text-only <span>'s JSX ref has already pointed useLayer at the span by the time the layout effect runs, so layer.ref(null) stripped the anchor off the element that had just acquired it. The patch now adds and removes the anchor name directly via addAnchorName/removeAnchorName with tooltip.anchorId, which is the half of layer.ref that belongs to this component; useLayer's triggerRef is used for nothing else.

Plus the change that makes them reachable: the trigger-resolving effect runs with no dependency array and returns immediately unless the resolved element differs from the one it holds, which makes TooltipProps' documented "Children refs are preserved" true for a child that is replaced (<button> → <a>), arrives late (null → <button>), or turns into text.

Why the patch shrank, and why the listeners may rebind every render

The previous revision also memoized useLayer's context ref and returned object. That half is removed:

• It never reached the DropdownMenu path it was supposed to help. usePopover (Popover/usePopover.js:113,199) does call useLayer, but returns a fresh object literal per render, and Popover's attach effects (Popover.js:222,251) depend on popover as a whole.
• It contributed nothing measurable: the Tooltip half alone already reaches 0 writes (column 3 above vs the four-way table).
• Its blast radius is wider than previously written here. Everything calling useLayer directly would change effect-firing timing: Carousel, Tokenizer, ContextMenu, useHoverCard, usePopover — but alsoDropdownMenu/DropdownMenuSubMenu.js and hooks/useKeyboardHint.js, and useKeyboardHint backs TabList, Toolbar and SegmentedControl. This repo references those at 19, 16 and 20 sites respectively, with DropdownMenu at 34. The earlier claim that only components "this repo neither uses nor tests" were affected was wrong, and the correction argues for the shrink, not against it.

Dropping it also drops a stray dist/Layer/useLayer.js.orig (392 lines, 47% of the old diff) that a patch tool left behind and patch-package captured as a new file. The patch is regenerated from a clean tree, verified file-by-file against a fresh npm pack @astryxdesign/core@0.2.0: 4 files → 2, 836 lines → 431, and nothing in node_modules/@astryxdesign/core differs from the published tarball except dist/Tooltip/Tooltip.js and src/Tooltip/Tooltip.tsx.

Without that half, interactionRef changes identity every render, so listeners unbind and rebind every render — exactly what upstream does. The reason that is affordable is an invariant, not a number: addEventListener and removeEventListener touch no style or layout state, so they cannot dirty the cascade however many of them run, while anchor-name is an inline style write that always does. A one-off Chromium measurement (22 history turns × 6 tooltip'd buttons, 110 frames ≈ 2420 turn re-renders) put the rebinds at ~11.0ms mutation / 0.0ms style+layout per streamed answer against 7.9ms / 21.2ms for the attribute writes they replace. That harness was run once and its script is not in this repo; patches/README.md now labels it as a one-off illustration rather than a maintained benchmark, because the conclusion does not depend on it.

Popover.js:222,251 has the same defect — worse, in fact: attachTrigger rewrites aria-haspopup, aria-expanded and aria-controls plus an inline style on every render, a superset of what Tooltip did. It is deliberately not fixed here: nothing in the CDP profile points at it, and it is not on the streaming hot path, so fixing it would widen the patch surface without evidence.

patches/README.md records the reason to exist, the deletion condition as an executable procedure (bump, delete the patch, rebuild @maka/ui, run the named guard, keep it deleted only if all 16 cases stay green), why Popover is left alone, and what the test harness deliberately does not model. The previously documented "inline onOpenChange" trap was wrong and has been removed: measured with the full patch, an inline arrow produces zero attribute writes on the trigger. Its real cost is toggle-listener churn on the popover element — a different mechanism, orders of magnitude smaller, and no call site passes onOpenChange at all.

This PR touches nothing in the transcript-derivation path; materialize.ts and chat-view.tsx belong to PR B.

Refs #2030

Verification

• npm run typecheck (workspace-wide), npm run format:check, npm run lint — clean.
• packages/ui: 284/284 pass, including the 16-case guard below.
• apps/desktop main suite: 1544/1544 pass.
• Fresh npm ci: patch re-applies through the root postinstall, no .orig or .rej anywhere in the tree, node_modules/@astryxdesign/core matches the published tarball except the two patched files, guard still green.
• Not run: Playwright E2E and the full root npm test — this is a dependency patch plus one test file.

The guard was validating the wrong thing; both faults are fixed

packages/ui/src/__tests__/tooltip-anchor-stability.test.tsx grew from 4 cases to 16, and two harness faults meant the old 4 were not exercising the patch's mechanism:

• It ran useEffect, not useLayoutEffect.useIsomorphicLayoutEffect resolves once, at module evaluation, from typeof window !== 'undefined'. The hoisted static import {Tooltip} evaluated before the fake DOM was installed, so it bound useEffect. Verified directly: window absent at import → === useEffect is true; window present → === useLayoutEffect is true. The patch's mechanism is a dependency-array-free layout effect. Fixed by installing the window in a before hook and importing dynamically (module-scope top-level await loses the race — node:test starts the first test as soon as evaluation yields).
• FakeElement.addEventListener/removeEventListener were empty, making the whole hover/focus/press path unreachable. They now record (type, handler) pairs, which is the only thing removeEventListener matches on, so a cleanup passing a mismatched identity leaks in the fake exactly as it would in a browser.

What the fake DOM still does not model is now recorded in the test next to class FakeElement, so the gaps are visible rather than assumed away: no showPopover/hidePopover (so useLayer.show() always takes the Safari<17 style.display fallback and neither the native popover path nor its toggle listener is reached), a no-op document.addEventListener (so Escape-to-dismiss, WCAG 1.4.13, is unreachable), a matches(':focus-visible') that always answers true (so the focus gate is never verified in the negative), and no tabIndex property (so isFocusable sees a text-only <span tabIndex={0}> as unfocusable and binds 3 of the 5 listeners a browser would). None of them touch what the patch changes: which element is written to, and which closure removes the listeners.

Mutation testing

Every mutant below was actually injected into node_modules/@astryxdesign/core/dist/Tooltip/Tooltip.js and the guard re-run. Counts are the tests that went red.

mutant	killed by
revert to unpatched upstream	5: no-write on unrelated re-render, controlled open, aria re-assertion, app-value-on-unmount, shared-trigger detach
listeners keyed on element only (freezes the closure)	4: element→text hand-off, listeners move on replacement, disabled-after-mount, unmount leak
release through the newest closure instead of the binding one	5: the four above plus net-bound-set-does-not-grow
detach the anchor through tooltip.positionRef(null)	3: trigger replaced, element→text hand-off, sibling-mode restore
drop the aria-describedby re-assertion	1: aria re-assertion
restore the attach-time aria snapshot instead of removing its own id	1: app-value-on-unmount
no unmount detach of the element-keyed half	3: sibling-mode restore, app-value-on-unmount, shared-trigger detach
ignore anchorRef sibling mode	3: unmount leak, sibling-mode restore, shared-trigger detach

The earlier table's first row said "no-write ×2, controlled open, shared-trigger detach" and read as four items; the actual count against the 13-case guard was three tests, and against the 16-case guard it is five. Counted per test from here on.

Two mutants are equivalent and disclosed rather than chased:

• Attaching the anchor with tooltip.positionRef(target) instead of addAnchorName(target, anchorId). useLayer's ref does exactly removeAnchorName(previousTrigger) + addAnchorName(el), and after the detach fix the previous trigger is already clear, so the two are observationally identical on the attach path. addAnchorName is kept because it is the half that belongs to this component, and because routing through the layer ref is what made the detach path wrong.
• Removing the textOnly term from the trigger resolution. In text-only mode the <span> carries tooltip.ref directly and wrapperRef is never attached, so wrapperRef.current?.firstElementChild ?? null is already null. Kept to mirror upstream's stated intent, not because a test guards it.

The previous revision's bound.el !== target check was also equivalent (interactionRef changes identity every render, so the closure check was unconditionally true). It no longer exists: React's per-render cleanup replaced the whole boundRef record.

Repo-wide survey: 13 production Tooltip call sites, all element children, 0 text-only, 0 anchorRef, 0 onOpenChange, 0 carrying their own aria-describedby. The element→text and application-rewrites-aria-describedby defects were therefore latent here, not live bugs — they are fixed because the patch is the thing that introduced the element keying that made them possible, and because both are cheap.