Design pooled-grid animation substrate for TreeGrid transitions

Context

#9409 is stale in its original CSS shape. The requested TreeGrid expand/collapse animation cannot be treated as a TreeGrid-only class toggle over pooled rows.

Fresh evidence from 2026-06-14:

• Live latest-open sweep checked the current top open queue and found no equivalent successor ticket.
• Targeted open-issue search for TreeGrid animation / AnimateRows / pooled grid animation / delayed permutation / snapshot overlay found only #9409 as the active open owner.
• KB lookup found row pooling and TreeStore projection mechanics documented, but no explicit architecture contract for animating TreeGrid expand/collapse under virtual row pooling.
• A temporary experiment enabled animatedRowSorting: true in both tree examples. GridTree.spec.mjs and GridTreeBigData.spec.mjs finished 6 passed / 2 failed; both failures were in GridTreeBigData.spec.mjs around expand toggles failing to reach is-expanded. The experiment was reverted.

This means #9409 should not close as delivered by the existing AnimateRows plugin, and should not grow a parallel animateTreeNodes CSS shim.

Problem

Virtual row pooling intentionally recycles a fixed DOM row pool. CSS row-enter / row-leave transitions depend on stable physical DOM identities at the visual row positions being animated. Those two models conflict under non-trivial TreeGrid structural changes.

The current renderer and plugin evidence points at the mismatch:

• src/grid/Body.mjs keeps VDOM children aligned to the full pool and avoids row removal/reordering.
• src/grid/Body.mjs maps logical rows onto pool items via modulo indexing.
• src/grid/Body.mjs derives row ids from rowIndex % poolSize.
• src/grid/plugin/AnimateRows.mjs maps existing VDOM rows by id, creates/pushes inserted row VDOM nodes, fades leftover old-map rows, and later forces owner.createViewData().
• src/data/TreeStore.mjs expand/collapse mutates the flat visible projection via splice after traversing visible descendants.

Those assumptions are incompatible enough that a simple enablement path destabilizes the big-data TreeGrid flow.

Fix

Design and implement a shared pooled-grid animation substrate for TreeGrid structural transitions. The chosen approach must explicitly preserve virtual row pooling invariants and decide whether AnimateRows is repaired, replaced, or narrowed behind a guard.

The design must evaluate at least these two architecture candidates:

• delayed permutation: TreeStore exposes mutation intent, the view animates a gap/closure, then the store commits the structural splice.
• snapshot/overlay: TreeStore mutates immediately, while a temporary visual overlay owns the transition and the pooled row layer remains stable.

A third approach is acceptable only if the PR body and tests demonstrate why it is safer than both.

Contract Ledger

Acceptance Criteria

• The implementation or design document selects one pooled-grid animation architecture and records why delayed permutation, snapshot/overlay, and the selected path were accepted or rejected.
• The solution does not add TreeGrid-only .neo-tree-row-entering / .neo-tree-row-leaving classes as a parallel animation substrate over pooled rows.
• The solution does not add a global row transition: transform that would animate normal virtual-scroll row recycling.
• animatedRowSorting remains off by default for TreeGrid unless the shared substrate proves it safe under TreeGrid structural flows.
• Tests or documented verification cover GridTree.spec.mjs and GridTreeBigData.spec.mjs expand/collapse behavior under the chosen animation config.
• Bulk expand/collapse, selection persistence after structural changes, and rapid toggle or scroll interaction are either green under the animation path or guarded with an explicit fallback/no-animation behavior.
• Any new data-layer hooks such as mutation intent or commit timing include JSDoc / @summary coverage and do not make TreeStore async-only for ordinary non-animated use.

Out of Scope

• Pure visual tuning of easing, duration, or stagger before the pooled-row contract exists.
• A TreeGrid-only plugin that duplicates AnimateRows semantics without resolving the shared pooling conflict.
• Enabling animatedRowSorting:true in examples as a standalone close path.

Avoided Traps

• Closing #9409 as delivered by AnimateRows; the big-data TreeGrid evidence falsifies that.
• Treating CSS classes as the architecture. They can be a rendering detail after the pooled-grid contract is solved.
• Letting AnimateRows and a new TreeGrid animation path diverge into two competing row-animation substrates.
• Animating normal virtual scrolling by accident through global transform transitions.

Related

• #9409 is the superseded CSS-shaped predecessor.
• #6563, #6564, #6565, and #6858 are older AnimateRows follow-ups and context, not sufficient owners for TreeGrid structural animation under pooling.

Release Classification

Post-release enhancement / architecture follow-up. This is not a v13.x release blocker.

Origin

Created from the @neo-gpt coordination turn after #9409 V-B-A and peer follow-up.

Handoff Retrieval Hints

Search terms: TreeGrid animation, AnimateRows, animatedRowSorting, pooled row animation, delayed permutation, snapshot overlay, GridTreeBigData, #9409.