From 2ca27ee66ae2a60f039b541c942f0cfeb0795893 Mon Sep 17 00:00:00 2001
From: Lukas Harbarth <lukas.harbarth@sap.com>
Date: Tue, 19 May 2026 09:37:10 +0200
Subject: [PATCH] chore(skills): add `analytical-table` maintainer skill

---
 skills/README.md                              |  11 +-
 skills/maintainer/analytical-table/SKILL.md   | 200 ++++++++++++
 .../analytical-table/evals/evals.json         |  35 ++
 .../references/HOOK-REFERENCE.md              | 220 +++++++++++++
 .../references/PERFORMANCE-PATTERNS.md        | 158 +++++++++
 .../references/REACT-TABLE-PIPELINE.md        | 306 ++++++++++++++++++
 .../references/STATE-MANAGEMENT.md            | 151 +++++++++
 7 files changed, 1078 insertions(+), 3 deletions(-)
 create mode 100644 skills/maintainer/analytical-table/SKILL.md
 create mode 100644 skills/maintainer/analytical-table/evals/evals.json
 create mode 100644 skills/maintainer/analytical-table/references/HOOK-REFERENCE.md
 create mode 100644 skills/maintainer/analytical-table/references/PERFORMANCE-PATTERNS.md
 create mode 100644 skills/maintainer/analytical-table/references/REACT-TABLE-PIPELINE.md
 create mode 100644 skills/maintainer/analytical-table/references/STATE-MANAGEMENT.md

diff --git a/skills/README.md b/skills/README.md
index 71e8f668481..cf3e1c78723 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -6,9 +6,10 @@ This directory contains agent skills for working with this repository.
 
 Currently, only **internal skills** for maintainers of this repository are offered.
 
-| Skill           | Description                                                                                                                                                                                         | Invocation              |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| `ui5wc-upgrade` | Guides a complete `@ui5/webcomponents` version upgrade — updates dependencies, regenerates wrappers, syncs theming parameters, detects new components and breaking changes, and verifies the build. | `/ui5wc-upgrade 2.25.0` |
+| Skill              | Description                                                                                                                                                                                                                                          | Invocation                                                                                        |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `ui5wc-upgrade`    | Guides a complete `@ui5/webcomponents` version upgrade — updates dependencies, regenerates wrappers, syncs theming parameters, detects new components and breaking changes, and verifies the build.                                                  | `/ui5wc-upgrade 2.25.0`                                                                           |
+| `analytical-table` | Deep expertise on AnalyticalTable internals: vendored react-table v7 plugin pipeline, hook architecture, performance traps, state machine, and accessibility wiring. Closes the gap that the public ui5wc MCP `get_component_api` tool cannot cover. | Auto-triggers when reading or editing files under `packages/main/src/components/AnalyticalTable/` |
 
 ### Installing Internal Skills
 
@@ -24,6 +25,10 @@ Alternatively, install from a local checkout:
 INSTALL_INTERNAL_SKILLS=1 npx skills add ./skills --skill ui5wc-upgrade
 ```
 
+### Evaluating Skills
+
+The `analytical-table` skill ships an `evals/evals.json` file with behavioral test prompts. To run those evaluations against the skill, use the [`skill-creator` skill from Anthropic](https://www.skills.sh/anthropics/skills/skill-creator) (referred to internally as `skill-validator` after a local rename).
+
 ## Requesting New Skills
 
 If you use an AI coding agent with UI5 Web Components for React and feel a skill would improve your workflow — whether for component usage, migration, styling, testing, or anything else — we'd love to hear about it.
diff --git a/skills/maintainer/analytical-table/SKILL.md b/skills/maintainer/analytical-table/SKILL.md
new file mode 100644
index 00000000000..1d719ea10b1
--- /dev/null
+++ b/skills/maintainer/analytical-table/SKILL.md
@@ -0,0 +1,200 @@
+---
+name: analytical-table
+description: Use ALWAYS for AnalyticalTable internals — react-table v7 plugin architecture, vendored react-table code at packages/main/src/components/AnalyticalTable/react-table/, tableHooks, AnalyticalTableHooks, useDynamicColumnWidths, useColumnResizing, useRowSelect, useF2CellEdit, useManualRowSelect, useIndeterminateRowSelection, useOnColumnResize, selectionMode, selectionBehavior, onRowSelect, onRowClick, onRowContextMenu, scaleWidthMode, infiniteScroll, isTreeTable, renderRowSubComponent, columnResizing, dynamic column widths, row virtualization, scroll-to-row freezes, deferred selection events, ARIA roles on grid/treegrid, aria-rowindex under virtualization, custom Cell/Header/Filter/Popover render-prop columns. Apply on ANY task that reads or modifies files under packages/main/src/components/AnalyticalTable/. SKIP for plain prop / event / ref-method / column-property lookups — those are in the ui5-wcr MCP `get_component_api`.
+---
+
+# AnalyticalTable Expert
+
+Start with **Key Behaviors** below; jump to a reference file only when its topic comes up.
+
+## react-table v7 is vendored, not a dependency
+
+react-table v7 lives at `packages/main/src/components/AnalyticalTable/react-table/` — in-tree, not a node_modules dependency. Imports are relative (`./react-table/index.js`). Grepping `node_modules/react-table` returns nothing — search the vendored tree. For the re-export list, the structure of the vendored copy, and the upstream-fallback path when the in-tree copy doesn't answer a question, see [REACT-TABLE-PIPELINE.md](references/REACT-TABLE-PIPELINE.md).
+
+---
+
+## Key Behaviors
+
+### autoReset Defaults
+
+react-table defaults all `autoReset*` options to `true`. Most reset on `data` changes: `autoResetSelectedRows`, `autoResetSortBy`, `autoResetFilters`, `autoResetGlobalFilter`, `autoResetGroupBy`, `autoResetExpanded`, `autoResetHiddenColumns`. The exception is `autoResetResize`, which resets on `columns` changes (not `data`).
+
+**Not used by AnalyticalTable:** `autoResetPage` (no `usePagination` plugin) and `autoResetRowState` (no `useRowState` plugin) have no effect.
+
+Hooks that need stable state across data changes (e.g., `useManualRowSelect`) must set `autoResetSelectedRows = false` on the instance. The main `stateReducer` also handles `SET_SELECTED_ROW_IDS` for programmatic overrides.
+
+### Selection Mechanics
+
+**UI5 tag blocklist:** `useSingleRowStateSelection` checks `tagNamesWhichShouldNotSelectARow` — a Set of UI5 Web Component tag names (Button, Link, Input, CheckBox, Select, etc.) defined at `util/index.ts:21-56`. Clicking these inside a cell does NOT trigger row selection. The check uses `getTagNameWithoutScopingSuffix(e.target.tagName)` (`packages/main/src/internal/utils.ts:52-55`) so scoped tag names like `ui5-button-foo123` still match.
+
+**`markerAllowTableRowSelection`:** Checked on both `e` and `e.nativeEvent`. When `true`, overrides the blocklist and allows the click to trigger selection.
+
+**Native HTML elements** are NOT in the blocklist. A `<button>`, `<input>`, or `<a>` inside a cell WILL trigger row selection unless `e.stopPropagation()` is called.
+
+**`onRowSelect` is deferred, not synchronous.** `useSingleRowStateSelection` and `useRowSelectionColumn` store `instance.pendingSelectEvent` and a `useEffect` in `useSelectionChangeCallback` consumes it after `selectedRowIds` actually changes (`hooks/useSingleRowStateSelection.ts:53`, `hooks/useSelectionChangeCallback.ts:21-67`, `hooks/useRowSelectionColumn.tsx:70`). Two consequences: (1) `e.preventDefault()`/`e.stopPropagation()` inside `onRowClick` does **not** suppress `onRowSelect`; (2) `onRowSelect` is **skipped entirely** if the click did not actually change `selectedRowIds` (e.g., re-clicking the already-selected row in single-select mode).
+
+**`onRowClick` always fires before `onRowSelect`.** The sole exception is clicking the checkbox itself (`e.target?.dataset?.name === 'internal_selection_column'`). Cell-level `data-selection-cell="true"` does NOT suppress `onRowClick` (`hooks/useSingleRowStateSelection.ts:29-31`). `data-selection-cell` is also a string, so compare `=== 'true'`, never just truthy.
+
+### Keyboard Navigation Pattern
+
+Keyboard nav splits across two hooks:
+
+- **`useKeyboardNavigation`** (always on) — Arrow keys, Home, End, PageUp, PageDown. Uses `findParentCell()` recursion (`hooks/useKeyboardNavigation.ts:41`) and `currentlyFocusedCell.current` to track focus, NOT a `currentTarget !== target` guard.
+- **`useF2CellEdit`** (opt-in via `tableHooks`) — F2, Tab/Shift+Tab. Gates with the **positive** form `e.currentTarget === e.target` (`pluginHooks/useF2CellEdit.ts:87,97,105,129,156`) to detect cell-level events vs. interactive-child events.
+
+**End/Home:** Uses `data-column-index` (absolute) to find the target cell. If the cell is already in DOM, focus is synchronous. Only when the cell is outside the virtualization window does the handler scroll `tableRef.current.scrollLeft` and focus after `requestAnimationFrame` (`hooks/useKeyboardNavigation.ts:66-79,199-228`).
+
+**onKeyDown is short-circuited during F2 edit mode:** When `state.cellContentTabIndex === 0`, the table's main `onKeyDown` skips arrow/Home/End/PageUp/PageDown and only forwards to user-supplied `tableProps.onKeyDown` (`hooks/useKeyboardNavigation.ts:352-366`). Don't add nav-key handlers expecting them to coexist with edit mode.
+
+**PageUp/PageDown** read `[data-component-name="AnalyticalTableBody"].children[0].children.length` (`hooks/useKeyboardNavigation.ts:237-238`). PageDown jumps to the last _currently rendered virtual_ row, not the last data row.
+
+**Cell data attributes:** Each cell has two column index attributes:
+
+- `data-column-index` — **absolute** index (`virtualColumn.index`). Use this for `querySelector`.
+- `data-visible-column-index` — **relative** index within currently rendered virtual items. Never use this for `querySelector` after scrolling.
+
+Sibling row attrs: `data-row-index` (header = 0, body = `virtualRow.index + 1`), `data-visible-row-index` (1-based viewport index, header = 0). Sub-component cells use `data-row-index-sub` / `data-column-index-sub`; sub-component wrappers must carry `data-subcomponent`; interactive elements inside need `data-subcomponent-active-element` to bypass focus stealing (`hooks/useKeyboardNavigation.ts:31-39,290-340`).
+
+**`tableRef` vs user-facing ref:** `tableRef` (from `webComponentsReactProperties`) is the inner scroll container div — use `tableRef.current.scrollLeft` for direct scroll manipulation. The user-facing DOM ref (`<AnalyticalTable ref={...}>`) is the root wrapper div, extended with imperative scroll methods via `useScrollToRef`. **Programmatic `ref.scrollTo*()` calls dispatch `TRIGGER_PROG_SCROLL` and are processed via `state.triggerScroll`** (`index.tsx:401-409`, `tableReducer/stateReducer.ts:80-81`) — back-to-back calls within one render coalesce because the effect observes the final state value.
+
+### `AnalyticalTableHooks` namespace
+
+User-facing plugins ship under one namespace import:
+
+```tsx
+import { AnalyticalTable, AnalyticalTableHooks } from '@ui5/webcomponents-react';
+
+const tableHooks = useMemo(() => [AnalyticalTableHooks.useManualRowSelect('selected')], []);
+<AnalyticalTable tableHooks={tableHooks} columns={columns} data={data} />;
+```
+
+The namespace is the only public way to reach the plugin functions. `tableHooks` is typed opaquely as `((hooks) => void)[]` in MCP, but the namespace itself carries proper types — import it and TypeScript will infer the rest.
+
+Available members (all set `pluginName`):
+
+- **`useManualRowSelect(manualRowSelectedKey = 'isSelected')`** — Syncs selection from a data property. Registers on `hooks.useInstanceAfterData`. Sets `autoResetSelectedRows = false` on instance **only if not already defined**. Skips `toggleRowSelected` when `shouldBeSelected === isSelected` (perf fix; `pluginHooks/useManualRowSelect.ts:24-32`).
+- **`useOrderedMultiSort(orderedIds: string[])`** — Reorders `sortBy` by priority. Registers on `hooks.stateReducers`.
+- **`useIndeterminateRowSelection(callback?: (rowsById, instance) => void)`** — Marks parent rows indeterminate when some children selected. **No-op unless `isTreeTable && selectionMode === 'Multiple' && selectionBehavior !== 'RowOnly'`** (`pluginHooks/useIndeterminateRowSelection.tsx:167-173`). Auto-selects parents when all siblings selected (mutates `selectedRowIds` in `stateReducer`, lines 110-130) — `onRowSelect.detail.selectedRowIds` then differs from the clicked row.
+- **`useF2CellEdit`** — F2 cell editing **plus header↔body Tab/Shift+Tab navigation**. Registers on `getTableProps` (adds `aria-description` "Press F2 to move to content"), `getCellProps`, `getHeaderProps`, `stateReducers` (`CELL_CONTENT_TAB_INDEX`), `useInstanceBeforeDimensions`. Tab from header lands on the body cell at `lastFocusedBodyRowRef`/row 1 same column; Shift+Tab from body returns to the header. F2 only fires when `e.currentTarget === e.target && interactiveElementName` is set (`pluginHooks/useF2CellEdit.ts:87`).
+  - **`AnalyticalTableHooks.useF2CellEdit.useCallbackRef<T>(props)`** is mandatory for every interactive element in a cell with `interactiveElementName` — it manages `tabindex` 0/-1 from `state.cellContentTabIndex` and walks `getFocusDomRefAsync()` to reach the focusable node inside UI5 web components (`pluginHooks/useF2CellEdit.ts:214-244`). Wrapping the input in a div and attaching the callback ref to the wrapper sets the wrapper's `tabindex`, not the input's — attach it directly to the focusable element.
+  - **`interactiveElementName` overrides `aria-label`** — when set, the cell's `aria-label` becomes `"Includes <name> <previous label>"` and `aria-labelledby` is dropped (`pluginHooks/useF2CellEdit.ts:75-79,141`; `hooks/useA11y.ts:90-97`).
+- **`useRowDisableSelection(accessor: string | (row) => boolean)`** — Disables selection on specific rows. **Deprecated; no replacement.** Don't suggest a swap-in for new code; either keep using it as-is or implement disable logic in `useManualRowSelect` callbacks.
+- **`useOnColumnResize(callback, { liveUpdate?: boolean; wait?: number = 100 })`** — Fires callback on column resize. Registers on `hooks.useFinalInstance`. With `liveUpdate: true`, also registers on `hooks.getResizerProps` to fire continuously during drag (debounced by `wait`).
+- **`useAnnounceEmptyCells`** — Appends `cellEmptyDescId` to **`aria-labelledby`** (not `aria-label`) on cells whose value is `''`/`null`/`undefined`/`false`. `0` is **not** treated as empty. Falsy JSX returned from a custom `Cell` is announced as empty (`pluginHooks/useAnnounceEmptyCells.ts:22-23`).
+
+---
+
+## Key Rules
+
+1. **Never cause cascading re-renders** — Returning new objects from `hooks.columns` triggers the full react-table pipeline (`columns → allColumns → rows → visibleColumns → headers`). With 1000+ rows this causes freezes/OOM in dev mode. Mutate in `hooks.useInstanceBeforeDimensions` instead.
+
+2. **Two-hook sandwich pattern** — Capture original values in `hooks.columns` (before `decorateColumn` mutates), then mutate `header.width`/`header.originalWidth` in `hooks.useInstanceBeforeDimensions`. This is how `useDynamicColumnWidths` works. The instance Map is `instance.rawColumnSizing` (no leading underscores).
+
+3. **Deferred rendering during drag** — Column resize uses CSS `transform` during drag with a single state dispatch on `mouseup`. Zero renders during drag.
+
+4. **Selection mode handling** — When `selectionMode === 'None'`, `useRowSelect` returns stable noop references and skips all computation (incl. `prepareRow` short-circuiting `row.toggleRowSelected`/`row.getToggleRowSelectedProps`/`row.isSomeSelected`). When selection IS enabled, `selectedFlatRows` is memoized via `useMemo` with deps `[rows, selectSubRows, selectedRowIds, getSubRows, isSelectionEnabled]`. `isAllRowsSelected` is NOT memoized (O(keys), acceptable cost). `useSingleRowStateSelection` registers on `hooks.getRowProps` and adds click/keyboard handlers across all selection modes; it checks grouped rows, the UI5 tag blocklist, `markerAllowTableRowSelection`, fires `onRowClick` synchronously, and `toggleRowSelected` (which then triggers the deferred `onRowSelect` via `pendingSelectEvent`).
+
+5. **`originalWidth` must stay in sync** — `useColumnResizing.useInstanceBeforeDimensions` reads `header.originalWidth` as fallback (via `??`). Always set both `header.width` and `header.originalWidth` when mutating.
+
+6. **Plugin order matters** — Plugins in `useTable()` run in registration order. `pluginName` is required (not just convention) — `ensurePluginOrder` throws if missing. User `tableHooks` are appended LAST (`index.tsx:333`), so a custom hook writing `header.width` in `useInstanceBeforeDimensions` overwrites `useDynamicColumnWidths`. See [HOOK-REFERENCE.md](references/HOOK-REFERENCE.md).
+
+## Synthetic Columns
+
+Three internal columns are injected by hooks:
+
+| Column ID                              | Hook                       | Position  |
+| -------------------------------------- | -------------------------- | --------- |
+| `__ui5wcr__internal_selection_column`  | useRowSelectionColumn      | Prepended |
+| `__ui5wcr__internal_highlight_column`  | useRowHighlight            | Prepended |
+| `__ui5wcr__internal_navigation_column` | useRowNavigationIndicators | Appended  |
+
+These columns are not in user-provided `columnOrder`; react-table handles unknown columns gracefully (appends them). `useA11y.setHeaderProps` keys off this `__ui5wcr__internal_*` prefix to inject translated header `aria-label`s — custom hooks must not reuse the prefix or they'll inherit those branches.
+
+The selection column reads its width from CSS variable `--_ui5wcr-AnalyticalTable-SelectionColumnWidth` (44px fallback, `util/index.ts:8,64-75`). Setting it via `reactTableOptions.columns` won't stick because the column is re-injected at `hooks/useRowSelectionColumn.tsx:128-143`.
+
+## High-Impact Gotchas
+
+Non-obvious behaviors. Every entry has a code reference.
+
+### Width / resize
+
+- **`useDynamicColumnWidths` skips ALL recalculation while `columnResizing.columnWidths` is non-empty** — A single double-click `AUTO_RESIZE` writes one entry and disables dynamic widths for **every** column until `actions.resetResize` fires (only on `columns` reference change) or container resizes >20px. Newly-shown columns won't get dynamic widths. Code: `hooks/useDynamicColumnWidths.ts:494-507`, `hooks/useAutoResize.tsx:34-37`, `hooks/useColumnResizing.ts:287-291`.
+- **`useDynamicColumnWidths` early-returns when `fontsReady` is false** — Width calc is gated on `document.fonts.ready` resolving. Environments without `document.fonts` keep columns at the react-table default of 150. Tests must `await` font ready or stub. Code: `hooks/useDynamicColumnWidths.ts:494-501`, `index.tsx:200`.
+- **Horizontal column virtualization is OFF in Smart/Grow scaleWidthMode and in RTL** — `overscan: Infinity` (i.e. all columns rendered) when `isRtl || scaleWidthMode !== Default`. The "default 10" overscan only applies to `Default` mode in LTR. Don't assume the table column-virtualizes uniformly. Code: `index.tsx:377`.
+- **`scaleWidthMode: Smart`/`Grow` ignores columns without `accessor`** — Width sampling reads `item.values?.[id]`; missing accessor collapses to header-only width or ~60px if header is also empty. Workaround: `scaleWidthModeOptions.cellString`. Code: `hooks/useDynamicColumnWidths.ts:97-105,272-283`.
+- **`TABLE_RESIZE` 20px dead zone** — Sub-20px container shrinks (e.g., a scrollbar appearing) keep stale resized widths when `retainColumnWidth` is off. Code: `tableReducer/stateReducer.ts:36-43`.
+- **`autoResetResize` resets on `columns` reference, not data** — In addition to the standard "memoize columns" rule, an unstable `columns` reference also nukes resize state. Code: `hooks/useColumnResizing.ts:283-291`.
+
+### Selection / events
+
+- **Header indeterminate uses `selectedFlatRows.length`, NOT `selectedRowIds`** — Filtered-out selected rows do NOT trigger indeterminate (UI5WCR fork divergence from upstream). Code: `hooks/useRowSelect.ts:86`.
+- **`onRowContextMenu`'s `column` is undefined on right-clicks landing in row padding** — The handler walks `closest('[data-column-index]')`; right-click on whitespace yields `undefined`. Code: `hooks/useSingleRowStateSelection.ts:90-96`.
+- **`useToggleRowExpand`'s click handler stops propagation by default** — `noPropagation = true` means clicking the chevron does NOT bubble to `onRowClick`. F4 and Space/Enter pass `false`, so keyboard expansion DOES fire `onRowClick`. Code: `hooks/useToggleRowExpand.ts:18-21,49,56`.
+- **`useExpanded` runs before `useRowSelect`, and `selectSubRows` defaults to `false`** — Toggling a parent does not cascade selection to children. Set `reactTableOptions={{ selectSubRows: true }}` for cascading. Code: `index.tsx:252,315-316`.
+- **`onAutoResize` is cancelable** — `if (e.defaultPrevented) return;` skips the dispatch. Use `e.preventDefault()` for custom auto-resize logic. Code: `hooks/useAutoResize.tsx:31-37`.
+- **`onLoadMore`/`onTableScroll`'s `rowElements` is a live `HTMLCollection`** — Storing it across renders surfaces different DOM nodes after virtual scroll. Code: `TableBody/VirtualTableBodyContainer.tsx:83`.
+- **`subRowsKey` falls back to BOTH user key AND `'subRows'`** — `getSubRowsByString` returns `row.subRows || row[subRowsKey]` for non-dotted keys. Data with both `children` (custom key) and an unrelated `subRows` field uses `subRows`. Dotted keys (e.g., `'values.subRows'`) skip the fallback. Code: `util/index.ts:138-143`.
+
+### State / refs
+
+- **`tableInstance` prop is mutated synchronously during render** — `index.tsx:418-423` checks `hasOwnProperty(tableInstance, 'current')` and assigns during render, not in an effect. Reading the instance inside a `useEffect` captures a stale snapshot — read it inline or via a ref synced each render.
+- **Switching `visibleRowCountMode` from Auto to Fixed dispatches an extra `VISIBLE_ROWS` action with `undefined`** — Tests asserting render counts trip on this. Code: `index.tsx:545-552`, `tableReducer/stateReducer.ts:48-52`.
+- **Loading overlay swaps the keyboard target** — When `showOverlay`, the overlay div takes `tabIndex={0} role="region"` and the grid drops to `tabIndex={-1}`; `useKeyboardNavigation` no-ops. Code: `index.tsx:776-794`, `hooks/useKeyboardNavigation.ts:90-95,348-350`.
+- **`alwaysShowBusyIndicator` is irrelevant when `rows.length === 0`** — Without it set, an empty data array shows the skeleton placeholder, not the busy indicator. Code: `index.tsx:768,835-840`.
+
+### Pipeline / hooks
+
+- **`useColumnsDeps` re-runs the column pipeline on selection/highlight prop flips** — Toggling `selectionMode`, `selectionBehavior`, `withRowHighlight`, `highlightField`, `withNavigationHighlight`, or (tree only) `updateOnSortClear` forces `hooks.columns` to re-run. Code: `hooks/useColumnsDeps.ts:10-19`.
+- **`renderRowSubComponent` silently disables grouping in Expandable mode** — `disableGroupBy = isTreeTable || (!alwaysShowSubComponent && renderRowSubComponent)`. With `subComponentsBehavior` `Visible`/`IncludeHeight`, grouping stays enabled. Code: `index.tsx:251`.
+- **Table-wide `disableSortBy: !sortable` overrides per-column `disableSortBy: false`** — react-table OR-s these flags, so individual columns cannot re-enable sorting when `sortable={false}`. Same for `filterable`. Code: `index.tsx:249-250`.
+- **There is no global drag-and-drop disable knob** — Drag wiring is unconditional; only per-column `column.disableDragAndDrop` is honored. To "lock all columns", annotate every column. Code: `hooks/useDragAndDrop.ts:84-87`, `ColumnHeader/ColumnHeaderContainer.tsx:75`.
+
+## Accessibility
+
+### ARIA roles
+
+- Root: `role="grid"` (`role="treegrid"` when `isTreeTable`), `aria-rowcount={rows.length}`, `aria-colcount={visibleColumns.length}`, `aria-multiselectable={selectionMode === 'Multiple'}` (`index.tsx:794-798`). Counts reflect post-pipeline shape — popped-in columns reduce `aria-colcount`; group rows count as ordinary rows.
+- **Tree-grid omits `aria-level`/`aria-setsize`/`aria-posinset`** — Depth is communicated only by visual padding plus `aria-expanded` on the first user cell. Authors of tree-table cells should not assume hierarchy attrs are emitted (`index.tsx:794`, `defaults/Column/Expandable.tsx:14-27`).
+- `aria-rowindex` is **data-row position**, not DOM position. Body rows get `virtualRow.index + 2` (header is row 1). With virtualization the rendered DOM is sparse; never derive position from DOM order. Code: `TableBody/VirtualTableBody.tsx:163`, `hooks/useA11y.ts:157-159`.
+
+### Cell labelling
+
+Cell `aria-label` is **not** set by `useA11y`. Instead, `useA11y` builds an `aria-labelledby` ID chain referencing the cell value `<span id="${uniqueId}${columnId}${rowId}">` and (under VoiceOver via `useCanUseVoiceOver`) the column header span (`hooks/useA11y.ts:34-36,53-65`). Two implications:
+
+1. Custom `Cell` renderers must keep that value `<span id=…>` discoverable, OR pass `cellLabel: (cell) => string` on the column to populate `aria-label` (which then nulls `aria-labelledby`).
+2. Setting `interactiveElementName` on a column makes the cell `aria-label = "Includes ${name} ${prevLabel}"` and drops `aria-labelledby` entirely.
+
+**Pop-in cells** require stable IDs `popin-h-${id}-${rowId}` / `popin-v-${id}-${rowId}` on the header and value spans. `useA11y` extends the first user cell's `aria-labelledby` with these IDs. Custom `PopInHeader` or `Cell` renderers that drop the IDs produce empty announcements. Pop-in wrappers themselves are `aria-hidden="true"`, but `aria-labelledby` references _IDs_ and traverses `aria-hidden`. Code: `defaults/Column/PopIn.tsx:80-91`, `hooks/useA11y.ts:51-65`.
+
+### Selection ARIA — what is and isn't there
+
+- **No `role="checkbox"`/`aria-checked` on the selection cell.** The inner `CheckBox` web component is `aria-hidden="true"`. Selection state is exposed solely via `aria-selected` on the cell + `aria-multiselectable` on the grid. Code: `hooks/useRowSelectionColumn.tsx:23-32,41-47`.
+- **No `aria-checked="mixed"`.** `useIndeterminateRowSelection` only toggles the visual `indeterminate` attribute on the inner CheckBox; there is no ARIA mapping. Code: `pluginHooks/useIndeterminateRowSelection.tsx:97-104`.
+- **`aria-expanded` and `aria-selected` are mutually exclusive on the first cell** — `useA11y` uses `if/else if`, so a row that is both expandable and selected won't announce its selection state on the first cell. Code: `hooks/useA11y.ts:67-89`.
+
+### Keyboard / focus
+
+`tabIndex` on cells is mutated imperatively by `useKeyboardNavigation.setFocus` / `getFirstVisibleCell`, NOT by `useA11y`. `role="row"` is set by `useStyling.getRowProps` and the default plugin hook. Sort/filter/group popovers use `accessibleRole={ListAccessibleRole.Menu}` on the inner `List` and `accessibleRole={PopupAccessibleRole.None}` on the wrapping `Popover`, with `aria-haspopup="menu"` / `aria-expanded` / `aria-controls` on the header cell (`defaults/Column/ColumnHeaderModal.tsx:190-262`, `ColumnHeader/index.tsx:203-205`). Custom column `Popover`s bypass this and must be authored with menu semantics manually.
+
+Header sort/filter/group annotations: `useA11y` mutates `column.headerLabel ??= ''` and appends i18n strings. `aria-sort` is `"ascending"`/`"descending"` only when sorted; the unsorted state has no `aria-sort` (no `"none"`). Code: `hooks/useA11y.ts:108-138`.
+
+### Live regions
+
+The only live-region announcement is row expand/collapse — `useToggleRowExpand` calls `InvisibleMessage.announce(text, 'Polite')` debounced 200ms. There is no announcement for sort, filter, group, loading, or selection changes. Code: `hooks/useToggleRowExpand.ts:1-8,42-44`.
+
+`useF2CellEdit` adds `aria-description` to the table announcing the F2 affordance. Multiple registrations compound. Code: `pluginHooks/useF2CellEdit.ts:180-189`.
+
+`useAnnounceEmptyCells` extends `aria-labelledby` (NOT `aria-label`) on cells whose value is `''`/`null`/`undefined`/`false`. `0` is non-empty.
+
+### Empty state
+
+`NoDataComponent` uses `accessibleRole="gridcell"`, wrapped in `<div role="row" tabIndex={0}>` so the table stays focusable. Custom NoDataComponents must render `role={accessibleRole}`. Code: `index.tsx:827-852`, `defaults/NoDataComponent/index.tsx:1-12`.
+
+## Reference Files
+
+Loaded on demand. Pick by topic:
+
+- [REACT-TABLE-PIPELINE.md](references/REACT-TABLE-PIPELINE.md) — Read when authoring or debugging anything that returns from `hooks.columns`/`visibleColumns`, when you need the exact hook execution order, when modifying the vendored `react-table/` files, or when you need the safe two-hook mutation pattern.
+- [HOOK-REFERENCE.md](references/HOOK-REFERENCE.md) — Read when adding a new internal hook or `tableHooks` plugin, when you need a hook's exact registration points, or when looking up which hook owns a given behavior.
+- [PERFORMANCE-PATTERNS.md](references/PERFORMANCE-PATTERNS.md) — Read when investigating render storms / scroll jank / dev-mode freezes, working on virtualization, or debugging selection performance.
+- [STATE-MANAGEMENT.md](references/STATE-MANAGEMENT.md) — Read when working with the table reducer, custom action types, controlled state, or `selectedRowIds`/`columnResizing`/`expanded` persistence.
diff --git a/skills/maintainer/analytical-table/evals/evals.json b/skills/maintainer/analytical-table/evals/evals.json
new file mode 100644
index 00000000000..e53c2d6fa8c
--- /dev/null
+++ b/skills/maintainer/analytical-table/evals/evals.json
@@ -0,0 +1,35 @@
+{
+  "skill_name": "analytical-table",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our AnalyticalTable freezes the dev tab when we feed it ~1500 rows. The columns and data props are both memoized with useMemo. Profiling shows the table re-rendering many thousands of times during scroll. Where should we look first, and what is the most likely cause?",
+      "expected_output": "Identifies that returning new objects from hooks.columns triggers the cascading react-table pipeline (the #1 perf trap). References the two-hook sandwich pattern (capture in hooks.columns, mutate in hooks.useInstanceBeforeDimensions) used by useDynamicColumnWidths. Mentions the safe mutation pattern in REACT-TABLE-PIPELINE.md.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I want to add a custom plugin hook that fires a callback whenever a column's filter changes, similar to useOnColumnResize. How do I register it via tableHooks, and what's the minimum I need to know about the AnalyticalTable plugin architecture to do this safely? Use AnalyticalTableHooks where appropriate.",
+      "expected_output": "Explains AnalyticalTableHooks namespace import, the factory pattern for plugin hooks, where to register (hooks.stateReducers vs hooks.useInstance), pluginName requirement, ensurePluginOrder for ordering against built-in useFilters, and that user tableHooks run last so they can clobber prior hooks. Should NOT duplicate prop docs from get_component_api.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "We have selectionMode='SingleSelect' on our AnalyticalTable and onRowClick prevents default. But onRowSelect still fires sometimes and not other times. Re-clicking the already-selected row never calls onRowSelect. What's going on?",
+      "expected_output": "Explains that onRowSelect is deferred via instance.pendingSelectEvent and consumed by useSelectionChangeCallback's useEffect after selectedRowIds actually changes. Two consequences: (1) preventDefault/stopPropagation in onRowClick does NOT suppress onRowSelect; (2) onRowSelect is skipped if selectedRowIds didn't actually change. References hooks/useSingleRowStateSelection.ts and hooks/useSelectionChangeCallback.ts.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I'm authoring a custom Cell renderer for an AnalyticalTable column. It needs to render a UI5 Input for inline editing, and the input must be reachable via F2 from keyboard navigation. What do I need to wire up so F2 actually works?",
+      "expected_output": "Mentions: (1) opt into useF2CellEdit via tableHooks; (2) set interactiveElementName on the column definition; (3) use AnalyticalTableHooks.useF2CellEdit.useCallbackRef on the Input element directly (not on a wrapper div); (4) caveat that interactiveElementName overrides aria-label and drops aria-labelledby; (5) onKeyDown is short-circuited during F2 edit mode. Cites pluginHooks/useF2CellEdit.ts:214-244.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "After adding scaleWidthMode='Smart' to our AnalyticalTable, I'm noticing the horizontal scrollbar shows but column virtualization seems to be off — every column renders even when 30+ are off-screen. Is this a bug in our setup or expected behavior?",
+      "expected_output": "Identifies this as expected behavior: index.tsx:377 sets overscan: Infinity when scaleWidthMode !== Default OR isRtl, so all columns render. The 'default 10' overscan only applies to Default scaleWidthMode in LTR. References the High-Impact Gotchas section.",
+      "files": []
+    }
+  ]
+}
diff --git a/skills/maintainer/analytical-table/references/HOOK-REFERENCE.md b/skills/maintainer/analytical-table/references/HOOK-REFERENCE.md
new file mode 100644
index 00000000000..b43ae385372
--- /dev/null
+++ b/skills/maintainer/analytical-table/references/HOOK-REFERENCE.md
@@ -0,0 +1,220 @@
+# AnalyticalTable Hook Reference
+
+Companion docs: [REACT-TABLE-PIPELINE.md](REACT-TABLE-PIPELINE.md) for hook execution order, prop-getter accumulation, and the safe two-hook mutation pattern; [STATE-MANAGEMENT.md](STATE-MANAGEMENT.md) for the actions each hook dispatches; [PERFORMANCE-PATTERNS.md](PERFORMANCE-PATTERNS.md) for the perf rationale behind `useDynamicColumnWidths` / `useColumnResizing` / `useRowSelect`.
+
+## Plugin Order in `useTable()`
+
+`useTable.ts:53` auto-prepends `useColumnVisibility` to whatever plugin list is passed. The full effective order is:
+
+```typescript
+useTable(
+  config,
+  // --- Auto-prepended by useTable itself ---
+  // useColumnVisibility (vendored: react-table/hooks/useColumnVisibility.ts)
+
+  // --- Vendored react-table plugins (must come first) ---
+  useFilters, // 1. Column filtering
+  useGlobalFilter, // 2. Global search
+  useColumnOrder, // 3. Column reorder state
+  useGroupBy, // 4. Row grouping
+  useSortBy, // 5. Column sorting
+  useExpanded, // 6. Row expand/collapse
+
+  // --- UI5WCR fork (replaces upstream useRowSelect) ---
+  useRowSelect, // 7. UI5WCR fork — no upstream useRowSelect is vendored
+
+  // --- UI5WCR internal hooks (order matters) ---
+  useColumnResizing, // 8. Deferred column resize (replaces react-table's)
+  useColumnsDeps, // 9. Column dependency tracking
+  useRowSelectionColumn, // 10. Adds selection checkbox column
+  useAutoResize, // 11. Double-click auto-resize
+  useSingleRowStateSelection, // 12. Click/keyboard row selection (all modes)
+  useSelectionChangeCallback, // 13. Fires onRowSelect callback (deferred)
+  useRowHighlight, // 14. Status indicator column
+  useRowNavigationIndicators, // 15. Navigation arrow column
+  useDynamicColumnWidths, // 16. Smart/Grow width calculation
+  useStyling, // 17. CSS classes and inline styles
+  useToggleRowExpand, // 18. Row expand tracking + callback + InvisibleMessage
+  useA11y, // 19. ARIA attributes
+  usePopIn, // 20. Responsive column pop-in
+  useVisibleColumnsWidth, // 21. Total visible width calculation
+  useKeyboardNavigation, // 22. Arrow/Home/End/PageUp/PageDown navigation
+  useColumnDragAndDrop, // 23. Column drag-and-drop reorder
+  ...tableHooks, // 24+. User-provided plugins (LAST — can clobber prior hooks)
+);
+```
+
+**`pluginName` is required.** `ensurePluginOrder` (vendored at `react-table/publicUtils.tsx:92-123`) throws if a plugin lacks it. Examples in source: `hooks/useDynamicColumnWidths.ts:489` ensures `useColumnResizing` runs first; `hooks/useSelectionChangeCallback.ts:14` ensures `useRowSelect` runs first. Future plugins can use `ensurePluginOrder` against any internal hook by name.
+
+## Internal Hooks (22 files in `hooks/`)
+
+### Column & Layout Hooks
+
+| Hook                       | Registration Points                                                                                                | Notes                                                                                                                                                                                                                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **useDynamicColumnWidths** | `hooks.columns`, `hooks.useInstanceBeforeDimensions`                                                               | Two-hook sandwich: captures raw sizing into `instance.rawColumnSizing` (Map; no leading underscore), then mutates header widths. Three modes: Default, Smart, Grow. Canvas-based text measurement, samples first 20 rows. Calls `ensurePluginOrder(['useColumnResizing'])`. Gated on `fontsReady`. |
+| **useColumnResizing**      | `hooks.getResizerProps` (creates), `hooks.stateReducers`, `hooks.useInstance`, `hooks.useInstanceBeforeDimensions` | Deferred resize with CSS transforms during drag, single dispatch on mouseup. 3px dead zone. RTL delta inversion. Clamps to minWidth/maxWidth. `getResizerProps` is **created** here (not in defaults).                                                                                             |
+| **useColumnsDeps**         | `hooks.columnsDeps`, `hooks.visibleColumnsDeps`                                                                    | Adds `webComponentsReactProperties` slice (`selectionMode`, `selectionBehavior`, `withRowHighlight`, `highlightField`, `withNavigationHighlight`, `updateOnSortClear`) as column dependency so columns re-run when these flip.                                                                     |
+| **useVisibleColumnsWidth** | `hooks.useInstance`                                                                                                | Computes `instance.visibleColumnsWidth` array for layout calculations.                                                                                                                                                                                                                             |
+| **usePopIn**               | `hooks.visibleColumns`, `hooks.visibleColumnsDeps`                                                                 | Filters columns by `responsiveMinWidth` vs `tableClientWidth`. Hidden columns pop into first column (Block/Inline display). Updates `popInColumns` state.                                                                                                                                          |
+| **useAutoResize**          | `hooks.getResizerProps`, `hooks.getCellProps`                                                                      | Handles double-click on column resizer to auto-fit content width. Dispatches `AUTO_RESIZE` action. Adds `data-column-id-cell` via `getCellProps` for DOM measurement. Cancelable via `onAutoResize` `e.preventDefault()`.                                                                          |
+
+### Row & Selection Hooks
+
+| Hook                           | Registration Points                                                                                                                                                                                               | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **useRowSelect**               | `hooks.getToggleRowSelectedProps` (creates), `hooks.getToggleAllRowsSelectedProps` (creates), `hooks.getToggleAllPageRowsSelectedProps` (creates), `hooks.stateReducers`, `hooks.useInstance`, `hooks.prepareRow` | UI5WCR **fork** of react-table's `useRowSelect` (no upstream copy is vendored). `selectedFlatRows` is memoized via `useMemo` (deps: `[rows, selectSubRows, selectedRowIds, getSubRows, isSelectionEnabled]`). Stable noop references when disabled (`emptyArray`, `noopToggle`, `noopGetProps`). Indeterminate uses `selectedFlatRows.length` (visible only) — diverges from upstream which counts all selected rows including filtered. `isAllRowsSelected` NOT memoized. |
+| **useRowSelectionColumn**      | `hooks.columns`, `hooks.visibleColumns`, `hooks.getHeaderProps`, `hooks.getCellProps`                                                                                                                             | Adds selection checkbox column. Width from CSS variable `--_ui5wcr-AnalyticalTable-SelectionColumnWidth`. Header CheckBox stores `pendingSelectEvent` for the deferred `onRowSelect` callback.                                                                                                                                                                                                                                                                             |
+| **useSingleRowStateSelection** | `hooks.getRowProps`                                                                                                                                                                                               | Click/keyboard handlers across **all** selection modes (not just single). Calls `toggleRowSelected` directly, stores `pendingSelectEvent` on instance for `useSelectionChangeCallback`. Fires `onRowContextMenu` from `onContextMenu` prop. Tag blocklist uses `getTagNameWithoutScopingSuffix`.                                                                                                                                                                           |
+| **useSelectionChangeCallback** | `hooks.useInstance`                                                                                                                                                                                               | Fires `onRowSelect` callback in a `useEffect` watching `selectedRowIds`. Consumes `instance.pendingSelectEvent`. **Skipped if `selectedRowIds` did not actually change.** Calls `ensurePluginOrder(['useRowSelect'])`.                                                                                                                                                                                                                                                     |
+| **useRowHighlight**            | `hooks.columns`, `hooks.visibleColumns`                                                                                                                                                                           | Adds a highlight/status indicator column (colored bar).                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **useRowNavigationIndicators** | `hooks.columns`, `hooks.visibleColumns`                                                                                                                                                                           | Adds navigation arrow column for row-level navigation indication.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| **useToggleRowExpand**         | `hooks.getToggleRowExpandedProps`                                                                                                                                                                                 | Tracks expand/collapse and fires `onRowExpandChange` callback. Also calls `InvisibleMessage.announce()` (debounced 200ms; the only live-region announcement in the table). Default `noPropagation: true` — chevron click does NOT bubble to `onRowClick`; F4/Space/Enter pass `false`.                                                                                                                                                                                     |
+
+### Styling & Accessibility Hooks
+
+| Hook                      | Registration Points                                                                            | Notes                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **useStyling**            | `hooks.getHeaderGroupProps`, `hooks.getHeaderProps`, `hooks.getRowProps`, `hooks.getCellProps` | CSS classes for alignment, borders, selection state, group headers. Sets `role="row"` on rows. Firefox-specific layout tweaks. NOT an a11y hook.                                                                                                                                                                                                                                                                  |
+| **useA11y**               | `hooks.getHeaderProps`, `hooks.getCellProps`, `hooks.getHeaderGroupProps`                      | Builds `aria-labelledby` ID chain for cells (NOT `aria-label`); appends pop-in IDs and VoiceOver header IDs. Sets `aria-selected` (cell) / `aria-expanded` (first cell of expandable rows) — these are **mutually exclusive** (`if/else if`). Sets `aria-rowindex: 1` on header group only. Does NOT set `tabIndex` on cells (keyboard nav does, imperatively) and does NOT set `role="row"` (`useStyling` does). |
+| **useKeyboardNavigation** | `hooks.getTableProps`, `hooks.getHeaderProps`                                                  | Arrow keys, Home, End, PageUp, PageDown. Does **NOT** handle F2 or Tab/Shift+Tab — those are in `useF2CellEdit` (opt-in). `getHeaderProps` adds Shift+Arrow column resize (dispatches `columnStartResizing`/`columnResizing` ±16px/`columnDoneResizing` — `headerIdWidths` is `[id, width, min, max]`). Short-circuits when `state.cellContentTabIndex === 0`.                                                    |
+
+### Drag & Drop
+
+| Hook                                         | Registration Points    | Notes                                                                                                                                                                                   |
+| -------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **useColumnDragAndDrop** (useDragAndDrop.ts) | `hooks.getHeaderProps` | Column reorder via drag-and-drop. Uses `dispatch` for `COLUMN_DND_START`/`COLUMN_DND_END` + `setColumnOrder`. No global disable knob — only per-column `disableDragAndDrop` is honored. |
+
+### Utility Hooks (no `useTable` plugin registration)
+
+| Hook                   | Notes                                                                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **useScrollToRef**     | Provides imperative scrolling API on the user-facing ref. Routes through dispatched `TRIGGER_PROG_SCROLL` state — back-to-back calls in one render coalesce. |
+| **useSyncScroll**      | Syncs vertical scrollbar position with table body via `useEffect`.                                                                                           |
+| **useFontsReady**      | Detects when fonts finish loading. `useDynamicColumnWidths` is gated on this — without `document.fonts`, columns stay at the 150 default.                    |
+| **useCanUseVoiceOver** | Detects macOS/iOS VoiceOver. `useA11y` appends column header IDs to cell `aria-labelledby` when true.                                                        |
+| **useIsFirefox**       | Browser detection. Drives layout/scroll tweaks only — NOT an a11y branch.                                                                                    |
+
+## Plugin Hooks (7 in `pluginHooks/` plus the `AnalyticalTableHooks` namespace export)
+
+User-facing plugins passed via `tableHooks`. Imported as `AnalyticalTableHooks.<name>` from `@ui5/webcomponents-react`.
+
+| Plugin                           | Factory                                  | Registration                                                                                                                               | Notes (beyond MCP)                                                                                                                                                                                                                                                       |
+| -------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **useManualRowSelect**           | `useManualRowSelect(key = 'isSelected')` | `hooks.useInstanceAfterData`                                                                                                               | Sets `autoResetSelectedRows = false` **only if not already defined** on instance. Skips `toggleRowSelected` when state would not change.                                                                                                                                 |
+| **useOrderedMultiSort**          | `useOrderedMultiSort(orderedIds)`        | `hooks.stateReducers`                                                                                                                      | Reorders `sortBy` array by priority on `toggleSortBy`.                                                                                                                                                                                                                   |
+| **useIndeterminateRowSelection** | `useIndeterminateRowSelection(callback)` | `hooks.getToggleRowSelectedProps`, `hooks.stateReducers`, `hooks.useInstanceAfterData`                                                     | No-op unless `isTreeTable && Multiple && selectionBehavior !== RowOnly`. Auto-selects parents when all siblings selected. Callback signature: `(rowsById, instance) => void`.                                                                                            |
+| **useF2CellEdit**                | Direct plugin (not a factory)            | `hooks.getTableProps`, `hooks.getCellProps`, `hooks.getHeaderProps`, `hooks.stateReducers`, `hooks.useInstanceBeforeDimensions`            | Adds `aria-description` "Press F2 to move to content" on the table. Tab from header → body cell same column at `lastFocusedBodyRowRef`/row 1; Shift+Tab body → header. Static method `useF2CellEdit.useCallbackRef<T>(props)` is mandatory for interactive cell content. |
+| **useRowDisableSelection**       | `useRowDisableSelection(accessor)`       | `hooks.getHeaderProps`, `hooks.getRowProps`, `hooks.columns`, `hooks.columnsDeps`, `hooks.getCellProps`, `hooks.getToggleRowSelectedProps` | `accessor: string \| (row) => boolean`. **Deprecated.**                                                                                                                                                                                                                  |
+| **useOnColumnResize**            | `useOnColumnResize(callback, opts?)`     | `hooks.useFinalInstance`, conditionally `hooks.getResizerProps`                                                                            | Options: `{ liveUpdate?: boolean; wait?: number = 100 }`. `getResizerProps` registration is gated on `liveUpdate: true`.                                                                                                                                                 |
+| **useAnnounceEmptyCells**        | Direct plugin                            | `hooks.getCellProps`                                                                                                                       | Appends `cellEmptyDescId` to **`aria-labelledby`** (not `aria-label`). Treats `0` as non-empty; `''`/`null`/`undefined`/`false` as empty.                                                                                                                                |
+
+## Factory Pattern for Plugin Hooks
+
+Plugin hooks that accept configuration use a factory pattern:
+
+```typescript
+// Factory: returns the actual plugin function
+export const useManualRowSelect = (manualRowSelectedKey = 'isSelected') => {
+  const useInstanceAfterData = (instance) => { /* uses manualRowSelectedKey */ };
+  const manualRowSelect = (hooks) => {
+    hooks.useInstanceAfterData.push(useInstanceAfterData);
+  };
+  manualRowSelect.pluginName = 'useManualRowSelect';
+  return manualRowSelect;
+};
+
+// Usage in tableHooks prop (memoize for stable closures):
+const tableHooks = useMemo(() => [useManualRowSelect('selected')], []);
+<AnalyticalTable tableHooks={tableHooks} />
+```
+
+The factory call returns a new function reference each time, but react-table rebuilds hook arrays from scratch every render (`makeDefaultPluginHooks()` + `plugin(hooks)` loop). Unmemoized factory plugins do NOT cause state resets or cascading re-renders — plugin functions are never in `useMemo` dependency arrays. Memoize only to keep closure-captured args stable.
+
+## Creating a New Internal Hook
+
+Canonical real-world references:
+
+- **Two-hook sandwich (capture + mutate):** `hooks/useDynamicColumnWidths.ts`
+- **Custom prop-getter chain replacing react-table defaults:** `hooks/useColumnResizing.ts` (`getResizerProps`) and `hooks/useRowSelect.ts` (`getToggleRowSelectedProps`)
+- **`useEffect`-based callback firing:** `hooks/useSelectionChangeCallback.ts`
+- **Factory plugin (user-facing via `tableHooks`):** `pluginHooks/useManualRowSelect.ts`
+
+Skeleton below — replace placeholder names with real ones from your hook.
+
+### 1. Create the hook file
+
+Place it in `packages/main/src/components/AnalyticalTable/hooks/` (internal) or `pluginHooks/` (consumer-facing via `tableHooks`).
+
+Real-world skeleton (excerpted from `hooks/useSelectionChangeCallback.ts` — a `useInstance`-only hook that fires a callback when state changes):
+
+```typescript
+import { useEffect, useRef } from 'react';
+import { ensurePluginOrder } from '../react-table/index.js';
+import type { ReactTableHooks, TableInstance } from '../types/index.js';
+
+const useInstance = (instance: TableInstance) => {
+  const { webComponentsReactProperties, state, plugins } = instance;
+  const { selectedRowIds } = state;
+  const { onRowSelect } = webComponentsReactProperties;
+
+  // Order requirement — throws at registration if violated.
+  ensurePluginOrder(plugins, ['useRowSelect'], 'useSelectionChangeCallback');
+
+  const prevSelectedRowIdsRef = useRef(selectedRowIds);
+
+  // Hook callbacks are called every render in stable order — useEffect/useRef are safe here.
+  useEffect(() => {
+    if (prevSelectedRowIdsRef.current !== selectedRowIds) {
+      onRowSelect?.(/* ... */);
+    }
+    prevSelectedRowIdsRef.current = selectedRowIds;
+  }, [selectedRowIds, onRowSelect]);
+};
+
+export const useSelectionChangeCallback = (hooks: ReactTableHooks) => {
+  hooks.useInstance.push(useInstance);
+};
+useSelectionChangeCallback.pluginName = 'useSelectionChangeCallback'; // required
+```
+
+For prop-getter callbacks (`getRowProps`, `getCellProps`, etc.), the signature is `(accumulatedProps, { instance, row, ... }) => props | [props, extraProps]`. See `hooks/useStyling.ts` for a hook that pushes to four prop-getter chains.
+
+### 2. Register in `useTable()` (internal hooks only)
+
+Add the hook to the `useTable()` call in `packages/main/src/components/AnalyticalTable/index.tsx`. **Order matters** — hooks that depend on state/instance set by earlier hooks must come after them. See the plugin order block above. User `tableHooks` are appended LAST, so internal hooks cannot block a user hook from clobbering them.
+
+### 3. Understand the invocation patterns
+
+react-table has two ways of calling hook callbacks. See [REACT-TABLE-PIPELINE.md](REACT-TABLE-PIPELINE.md) for full details.
+
+- **`reduceHooks`** (pipeline hooks: `columns`, `visibleColumns`, `stateReducers`, etc.) — callback receives previous result, MUST return next value. Returning `undefined` throws.
+- **`loopHooks`** (side-effect hooks: `useInstance`, `useInstanceAfterData`, `useInstanceBeforeDimensions`, `prepareRow`, `useFinalInstance`) — callback receives the instance, must NOT return a value. Returning anything throws in dev mode.
+- **Prop getters** (`getRowProps`, `getCellProps`, etc.) — callback receives `(accumulatedProps, meta)`, returns a props object or `[props, extraProps]` tuple. Props are accumulated via reduce; `style` is deep-merged, `className` is concatenated.
+
+### 4. Performance constraints
+
+- **Never return new objects from `hooks.columns` or `hooks.visibleColumns`** — this triggers the full cascading pipeline. Use the two-hook sandwich: capture in `hooks.columns`, mutate in `hooks.useInstanceBeforeDimensions`. See [REACT-TABLE-PIPELINE.md](REACT-TABLE-PIPELINE.md).
+- **Side-effect hooks must not return a value.**
+- **`hooks.someArray = [fn]` initializes a chain that has no defaults** (e.g., `useColumnResizing` does this for `getResizerProps`, `useRowSelect` for `getToggleRowSelectedProps`/`getToggleAllRowsSelectedProps`/`getToggleAllPageRowsSelectedProps`). Use `hooks.someArray.push(fn)` to add to an existing chain.
+
+### 5. Accessing AnalyticalTable configuration
+
+All AT-specific UI config lives on `instance.webComponentsReactProperties`:
+
+```typescript
+const { selectionMode, isTreeTable, tableRef, onRowClick } = instance.webComponentsReactProperties;
+```
+
+This bag keeps AT options separate from react-table's. Hooks that need react-table-level options (e.g., `autoResetSelectedRows`, `manualFilters`) add those directly to the `useTable` options as normal.
+
+### Available hook points (full list)
+
+**Pipeline hooks** (transform data, must return value):
+`useOptions`, `columns`, `columnsDeps`, `allColumns`, `allColumnsDeps`, `visibleColumns`, `visibleColumnsDeps`, `headerGroups`, `headerGroupsDeps`, `materializedColumns` (declared but never invoked by vendored `useTable`), `materializedColumnsDeps` (same), `accessValue` (per-cell during row materialization), `stateReducers`, `useControlledState`
+
+**Side-effect hooks** (must NOT return value):
+`useInstanceAfterData`, `useInstanceBeforeDimensions`, `useInstance`, `useFinalInstance`, `prepareRow`
+
+**Prop getter hooks** (return props or `[props, extraProps]`):
+`getTableProps`, `getTableBodyProps`, `getHeaderGroupProps`, `getFooterGroupProps`, `getHeaderProps`, `getFooterProps`, `getRowProps`, `getCellProps`, `getResizerProps`, `getToggleRowSelectedProps`, `getToggleAllRowsSelectedProps`, `getToggleAllPageRowsSelectedProps`, `getToggleRowExpandedProps`, `getToggleAllRowsExpandedProps`, `getSortByToggleProps`, `getGroupByToggleProps`, `getToggleHiddenProps`, `getToggleHideAllColumnsProps`
diff --git a/skills/maintainer/analytical-table/references/PERFORMANCE-PATTERNS.md b/skills/maintainer/analytical-table/references/PERFORMANCE-PATTERNS.md
new file mode 100644
index 00000000000..60fc95582f6
--- /dev/null
+++ b/skills/maintainer/analytical-table/references/PERFORMANCE-PATTERNS.md
@@ -0,0 +1,158 @@
+# AnalyticalTable Performance Patterns
+
+Companion docs: [REACT-TABLE-PIPELINE.md](REACT-TABLE-PIPELINE.md) for the cascading-pipeline trap and safe mutation pattern; [HOOK-REFERENCE.md](HOOK-REFERENCE.md) for hook registration points; [STATE-MANAGEMENT.md](STATE-MANAGEMENT.md) for actions referenced below.
+
+## Virtualization
+
+### Row Virtualization (`@tanstack/react-virtual`)
+
+- Only visible rows + overscan are rendered
+- Overscan configurable via `overscanCount` prop (default: `Math.floor(visibleRows / 2)`)
+- `estimateSize` callback for dynamic heights (subcomponents)
+- `measureElement` for precise row measurement
+- Virtualizer range stored on `tableInstanceRef.current.virtualRowsRange`
+
+### Column Virtualization (`@tanstack/react-virtual`)
+
+- Separate horizontal virtualizer
+- Default overscan: 10 columns (`overscanCountHorizontal`) — but see SKILL.md "High-Impact Gotchas" for when virtualization is disabled (`scaleWidthMode !== Default` or RTL forces `overscan: Infinity`).
+- RTL handled via `translateX` transforms
+
+## Deferred Column Resize (Zero Renders During Drag)
+
+The `useColumnResizing` hook uses a deferred pattern:
+
+1. **mousedown**: Record start position, set `isDragging` (3px dead zone)
+2. **mousemove**: Apply CSS `transform: translateX(deltaX)` to resizer element. **No state dispatch. No React render.**
+3. **mouseup**: Single `dispatch({ type: 'columnDoneResizing', columnWidths })`. One render.
+
+### RTL Resize
+
+Delta sign is inverted for RTL: `const deltaX = isRtl ? -rawDeltaX : rawDeltaX`. Inlined in the resize reducer.
+
+## Selection Performance
+
+### `selectedFlatRows` Memoization
+
+The `selectedFlatRows` computation is wrapped in `useMemo` with deps `[rows, selectSubRows, selectedRowIds, getSubRows, isSelectionEnabled]`. `useInstance` fires on **every render** (via `loopHooks` at `react-table/hooks/useTable.ts:304`), including renders from `TABLE_RESIZE`, scroll events, layout changes, and parent re-renders that don't change `rows` or `selectedRowIds`.
+
+All deps are referentially stable during scroll-only re-renders:
+
+- `rows`: memoized through the pipeline (`useFilters` → `useGlobalFilter` → `useGroupBy` → `useSortBy` → `useExpanded`, each wrapped in `useMemo`)
+- `selectedRowIds`: part of `useReducer` state, only changes on selection actions
+- `getSubRows`: wrapped in `useCallback` with `[subRowsKey]` dep at `index.tsx:224`
+- `selectSubRows`: boolean option, stable
+- `isSelectionEnabled`: derived from `selectionMode` prop, stable
+
+Without this memoization, each scroll frame would iterate all rows (O(n)) AND produce a new array reference that cascades re-renders through child components (Header, ColumnHeaderContainer, CheckBox).
+
+### Disabled Fast Path
+
+When `selectionMode === 'None'`:
+
+- `selectedFlatRows` returns **stable empty array** via useMemo (cached `emptyArray` reference)
+- `toggleRowSelected` returns **stable noop function**
+- `isAllRowsSelected` computation skipped entirely
+- `prepareRow` sets `row.isSelected = false`, `row.isSomeSelected = false`, `row.toggleRowSelected = noopToggle`, `row.getToggleRowSelectedProps = noopGetProps` — all without computing (`hooks/useRowSelect.ts:338-344`)
+
+### Indeterminate State (Visible-Only)
+
+The fork's select-all indeterminate check uses `selectedFlatRows?.length` (visible/filtered rows only) instead of the original react-table's `Object.keys(selectedRowIds).length` (all selected rows including filtered-out ones). Prevents the select-all checkbox from showing indeterminate state due to rows that are selected but hidden by filters.
+
+### `isAllRowsSelected` Is NOT Memoized
+
+The `isAllRowsSelected` computation runs bare on every render when selection is enabled — `Object.keys(nonGroupedRowsById).every(...)`. O(keys) not O(rows), and `nonGroupedRowsById` is itself memoized via `useGroupBy`.
+
+### Single-Select Optimization
+
+`useSingleRowStateSelection` registers on `hooks.getRowProps` and calls `toggleRowSelected` directly from click/keyboard handlers. It does not use a state reducer.
+
+## Mutation Patterns
+
+### Row Property Mutation
+
+`prepareRow` mutates row objects directly:
+
+```typescript
+row.isSelected = !!isSelected;
+row.isSomeSelected = isSelected === null;
+row.toggleRowSelected = (...) => {...};
+```
+
+Avoids creating new row objects per render cycle.
+
+### Header Width Mutation
+
+`useInstanceBeforeDimensions` hooks mutate `header.width` and `header.originalWidth` directly on the existing header objects in `flatHeaders`. No new objects created.
+
+### Instance Property Mutation
+
+Hooks attach properties directly to `instance`:
+
+```typescript
+instance.virtualRowsRange = rowVirtualizer.range;
+instance.rawColumnSizing = new Map(); // see REACT-TABLE-PIPELINE.md "Safe Mutation Pattern"
+instance.visibleColumnsWidth = [...];
+instance.pendingSelectEvent = { event, row }; // consumed by useSelectionChangeCallback's useEffect
+```
+
+## Canvas-Based Text Measurement
+
+`useDynamicColumnWidths` uses a singleton `<canvas>` for measuring text width:
+
+- Avoids DOM layout thrashing
+- Canvas element cached at module level; `getComputedStyle` calls run fresh each invocation
+- Samples only first 20 rows per column (`ROW_SAMPLE_SIZE = 20`)
+- Triggered by `useFontsReady` hook when web fonts finish loading; the entire `adjustColumnWidths` callback is gated on `fontsReady` (see SKILL.md "High-Impact Gotchas").
+
+## Subcomponent Rendering
+
+`renderRowSubComponent(row)` is called for every visible row. The result is passed as `children` to the `<RowSubComponent>` wrapper which returns `null` for collapsed rows — the JSX is never mounted. The wrapper must always mount so its `useIsomorphicLayoutEffect` can dispatch `subComponentHeight: 0` on collapse. Do not short-circuit the `renderRowSubComponent` call.
+
+## Dead Zones & Thresholds
+
+| Component           | Threshold                                              | Purpose                                                    |
+| ------------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
+| Column resizer      | 3px                                                    | Prevents accidental drag; allows double-click detection    |
+| TABLE_RESIZE action | 20px delta                                             | Prevents column width reset when scrollbar briefly appears |
+| Infinite scroll     | `infiniteScrollThreshold` remaining rows (default: 20) | Fires `onLoadMore`                                         |
+
+## Anti-Patterns to Avoid
+
+### 1. New Objects in `hooks.columns`
+
+Returning new objects from `hooks.columns` triggers the cascading pipeline (see [REACT-TABLE-PIPELINE.md](REACT-TABLE-PIPELINE.md)). Mutate in `hooks.useInstanceBeforeDimensions` instead:
+
+```typescript
+// WRONG - triggers full cascade
+hooks.columns.push((columns) => columns.map((col) => ({ ...col, width: 200 })));
+
+// CORRECT - mutate in useInstanceBeforeDimensions; keep originalWidth in sync (Key Rule #5)
+hooks.useInstanceBeforeDimensions.push((instance) => {
+  instance.flatHeaders.forEach((h) => {
+    h.width = 200;
+    h.originalWidth = 200;
+  });
+});
+```
+
+### 2. Dispatching State During Drag
+
+```typescript
+// WRONG - causes render per mousemove frame
+onMouseMove: () => dispatch({ type: 'resize', width: newWidth });
+
+// CORRECT - CSS transform only, dispatch on mouseup
+onMouseMove: () => {
+  resizerEl.style.transform = `translateX(${delta}px)`;
+};
+onMouseUp: () => dispatch({ type: 'columnDoneResizing', columnWidths });
+```
+
+## Debugging Performance Issues
+
+1. **Check `hooks.columns` first** - Are any hooks returning new column objects?
+2. **Check render count** - Use React DevTools Profiler. More than 1-2 renders per interaction is suspicious.
+3. **Check `flatRows.length`** - Is it the full dataset or just visible rows? Iterating all rows in a render-path hook is O(n).
+4. **Check `useEffect` dependencies** - `flatRows` as a dependency triggers on every data change. Consider debouncing.
+5. **Check memoization** - Are `columns` and `data` memoized by the consumer? (`tableHooks` memoization is recommended but not performance-critical — react-table rebuilds hook arrays every render regardless.)
diff --git a/skills/maintainer/analytical-table/references/REACT-TABLE-PIPELINE.md b/skills/maintainer/analytical-table/references/REACT-TABLE-PIPELINE.md
new file mode 100644
index 00000000000..127f9b0227c
--- /dev/null
+++ b/skills/maintainer/analytical-table/references/REACT-TABLE-PIPELINE.md
@@ -0,0 +1,306 @@
+# Vendored react-table v7 Pipeline & Hook Architecture
+
+react-table v7 is in-tree at `packages/main/src/components/AnalyticalTable/react-table/`, not a node_modules dependency. All references below point to the in-tree copy.
+
+## Contents
+
+- [Vendored layout](#vendored-layout) — directory structure of the in-tree copy + public re-exports
+- [The Cascading Pipeline](#the-cascading-pipeline) — diagram + why it matters
+- [Core Patterns (Not Typical React)](#core-patterns-not-typical-react) — plugins-aren't-hooks, reduceHooks vs loopHooks, prop-getter accumulation, single mutable instance, dynamic dependency injection
+- [Hook Points (Execution Order)](#hook-points-execution-order) — every hook point in the order `useTable.ts` invokes them
+- [`decorateColumn` Behavior](#decoratecolumn-behavior) — what gets mutated when
+- [The Safe Mutation Pattern](#the-safe-mutation-pattern) — the two-hook sandwich (THE canonical example)
+- [Plugin Registration](#plugin-registration) — `pluginName` requirement; initialize-vs-append semantics
+- [`webComponentsReactProperties`](#webcomponentsreactproperties) — the AT config bag passed through `useTable` options
+- [Last resort: consult upstream react-table v7](#last-resort-consult-upstream-react-table-v7) — escalation path when the in-tree copy + this skill genuinely don't answer the question
+
+## Vendored layout
+
+```
+packages/main/src/components/AnalyticalTable/react-table/
+├── index.ts                     # public re-exports
+├── aggregations.ts
+├── filterTypes.ts
+├── makeDefaultPluginHooks.ts    # the canonical list of hook arrays
+├── publicUtils.tsx              # makePropGetter, ensurePluginOrder, mergeProps, reduceHooks/loopHooks impls
+├── sortTypes.ts
+├── utils.ts                     # decorateColumn, getBy, flattenBy, expandRows, makeHeaderGroups, etc.
+├── hooks/
+│   ├── useColumnVisibility.ts   # auto-prepended to plugins by useTable
+│   └── useTable.ts              # the orchestration entry point
+└── plugin-hooks/
+    ├── useColumnOrder.ts
+    ├── useExpanded.ts
+    ├── useFilters.ts
+    ├── useGlobalFilter.ts
+    ├── useGroupBy.ts
+    └── useSortBy.ts
+```
+
+Public re-exports from `react-table/index.ts` include `actions`, `defaultColumn`, `makePropGetter`, `useGetLatest`, `ensurePluginOrder`, `decorateColumn`, `getFirstDefined`, `flexRender`, `useAsyncDebounce`, `safeUseLayoutEffect`, `getBy`, `flattenBy`, `expandRows`, `getElementDimensions`, `assignColumnAccessor`, `makeHeaderGroups`. Absent (relative to upstream react-table): `useRowSelect` — UI5WCR has a fork at `hooks/useRowSelect.ts` registered directly in `index.tsx`. See [HOOK-REFERENCE.md](HOOK-REFERENCE.md) for the full plugin list.
+
+## The Cascading Pipeline
+
+react-table v7 builds its instance in fixed order. Each stage depends on the previous — **returning new objects from an early stage re-runs the entire downstream pipeline.**
+
+Stages (data structures and hook fire points, in order):
+
+1. `columns` — input transformed by `hooks.columns`
+2. `allColumns` — flattened via `hooks.allColumns`
+3. `rows` — data materialized (most expensive stage; O(n) allocations)
+4. ↳ `hooks.useInstanceAfterData` fires
+5. `visibleColumns` — filtered/reordered by `hooks.visibleColumns`. `decorateColumn` runs inside this `useMemo` and mutates each column in place — sets `width=150` from `defaultColumn` on any column without an explicit width
+6. `headerGroups` — built via `makeHeaderGroups(visibleColumns, ...)`
+7. `headers` — `headerGroups[0].headers`
+8. `flatHeaders` — all header-group headers flattened
+9. ↳ `hooks.useInstanceBeforeDimensions` fires (mutate `header.width`/`header.originalWidth` here)
+
+### Why This Matters
+
+If a `hooks.columns` callback returns **new column objects** (even with identical data), react-table treats them as changed and re-runs the entire pipeline. With 1000+ rows, step 3 (`rows` materialization) is the dominant cost.
+
+**The #1 performance trap** in AnalyticalTable development. The fix is the [Safe Mutation Pattern](#the-safe-mutation-pattern) — capture in `hooks.columns` (step 1), mutate in `hooks.useInstanceBeforeDimensions` (step 9). For pre-decoration widths, capture them in step 1 before the pipeline reaches step 5.
+
+## Core Patterns (Not Typical React)
+
+react-table v7 uses several patterns that contradict standard React conventions. Understanding these explains why things work the way they do and why common React intuitions lead to bugs.
+
+### Plugins Are NOT React Hooks (But Their Callbacks Can Use Them)
+
+Despite the `use*` naming, plugin registration functions are **plain functions** called in a `forEach` loop. Each plugin receives the `hooks` object and pushes callbacks into its arrays.
+
+```javascript
+// Pseudocode equivalent of react-table/hooks/useTable.ts:70-72
+plugins.filter(Boolean).forEach((plugin) => {
+  plugin(getInstance().hooks);
+});
+```
+
+However, the callbacks pushed into side-effect hooks (`useInstance`, `useInstanceAfterData`, `useInstanceBeforeDimensions`, `useFinalInstance`) **are called during React's render phase** (inside `useTable`) in stable order via `loopHooks`. Because the call order is stable across renders, these callbacks **can use React hooks** (`useEffect`, `useRef`, `useState`, etc.) — and many internal hooks do (e.g., `useSelectionChangeCallback` uses `useEffect` inside its `useInstance` callback).
+
+### Two Invocation Patterns: `reduceHooks` vs `loopHooks`
+
+react-table has exactly two ways to invoke hook callbacks. Using the wrong return convention causes errors.
+
+**`reduceHooks`** — Pipeline/fold pattern. Each callback receives the previous result and MUST return the next value:
+
+```javascript
+// Pseudocode (real impl: react-table/publicUtils.tsx:69-90):
+// hooks.reduce((prev, next) => next(prev, meta), initial)
+// Used by: columns, allColumns, visibleColumns, headerGroups, stateReducers, useOptions, etc.
+```
+
+If a callback returns `undefined`, react-table throws in dev mode: _"A reducer hook just returned undefined!"_
+
+**`loopHooks`** — Side-effect pattern. Each callback receives the same context and must NOT return anything:
+
+```javascript
+// Pseudocode (real impl: react-table/publicUtils.tsx:69-90):
+// hooks.forEach(hook => hook(context, meta))
+// Used by: useInstance, useInstanceAfterData, useInstanceBeforeDimensions, useFinalInstance, prepareRow
+```
+
+If a callback returns a value, react-table throws in dev mode: _"A loop-type hook just returned a value!"_ In production the return is silently ignored.
+
+**Exception:** `stateReducers` uses its own reduce pattern with a falsy fallback: `handler(s, action, state, getInstance()) || s`. If a reducer returns `undefined`/falsy, the previous state is preserved instead of throwing.
+
+### Prop Getter Accumulation (`makePropGetter`)
+
+Prop getters (`getRowProps`, `getCellProps`, etc.) are NOT simple functions. They are **reduce pipelines** that accumulate props from multiple hooks:
+
+```javascript
+// Inside makePropGetter:
+return (userProps = {}) => [...hooks, userProps].reduce((prev, next) => handlePropGetter(prev, next, meta), {});
+```
+
+Each hook callback receives `(accumulatedProps, meta)` and returns either:
+
+- A **props object** — merged via shallow spread (except `style` which is deep-merged, and `className` which is concatenated with spaces)
+- A **`[props, extraProps]` tuple** — both elements are merged sequentially
+
+User-supplied props (from `row.getRowProps({ className: 'foo' })`) are always the **last** item in the reduce, so they win for simple properties. For `style`, user styles merge on top; for `className`, user classes are appended.
+
+### Single Mutable Instance
+
+The table instance is a **single object** created once via `useRef({})` and never recreated:
+
+```javascript
+const instanceRef = React.useRef({})
+const getInstance = useGetLatest(instanceRef.current)
+
+// Throughout useTable:
+Object.assign(getInstance(), { columns, rows, ... })
+```
+
+Plugins in `useInstance` overwrite properties directly — e.g., `useSortBy` replaces `instance.rows` with sorted rows. The next plugin in the chain sees the modified data. This is the opposite of React's immutability principle, but it works because:
+
+- The render is synchronous — all mutations happen in predictable order within a single `useTable` call
+- Change detection uses `useMemo` on specific values (the `columns` array, the `data` prop), not on the instance object itself
+- Column objects are shared across `allColumns`, `visibleColumns`, `flatHeaders`, and cells — mutation ensures all references see the same decorated state without rebuilding every data structure
+
+### Dynamic Dependency Injection
+
+Plugins can inject additional dependencies into `useMemo` arrays via `*Deps` hooks:
+
+```javascript
+// Inside useTable:
+const columns = React.useMemo(
+  () => reduceHooks(getHooks().columns, userColumns, meta),
+  [userColumns, ...reduceHooks(getHooks().columnsDeps, [], meta)],
+  //            ^^^ deps hooks are evaluated EVERY render to produce the dependency array
+);
+```
+
+If a `columnsDeps` hook returns `[instance.state.hiddenColumns]`, the `columns` memo recomputes whenever `hiddenColumns` changes. This is how plugins extend the reactivity system without modifying core memoization logic. The `useColumnsDeps` internal hook uses this to add `webComponentsReactProperties` as a dependency.
+
+## Hook Points (Execution Order)
+
+Order in `react-table/hooks/useTable.ts` (line refs are approximate):
+
+### Setup phase
+
+0. **`useColumnVisibility`** — auto-prepended at `useTable.ts:53` before user plugins run.
+1. **`hooks.useOptions`** — runs at `useTable.ts:80`. Reduce-style; transforms the options bag.
+2. **`hooks.useControlledState`** — runs at `useTable.ts:119`. Reduce-style; lets plugins override state per render.
+
+### Column phase
+
+3. **`hooks.columns`** — Transform column definitions. Receives `(columns, meta)`. Must return columns array.
+4. **`hooks.columnsDeps`** — Add dependencies that trigger column recalculation.
+5. **`hooks.allColumns`** — Transform flattened column list.
+6. **`hooks.allColumnsDeps`** — Dependencies for allColumns.
+
+### Data phase
+
+7. **Rows materialize** (`useTable.ts:168-191`).
+8. **`hooks.useInstanceAfterData`** — runs at `useTable.ts:200`, **before** visibleColumns. Safe for data-dependent logic.
+9. **`hooks.accessValue`** — reduce-style, called per-cell during row materialization (`useTable.ts:549-558`); receives `{ row, column, instance }`.
+
+### Visible columns phase
+
+10. **`hooks.visibleColumns`** — runs in a `useMemo` at `useTable.ts:205-221`. Filter/reorder. `decorateColumn` runs inside this useMemo on each column.
+11. **`hooks.visibleColumnsDeps`** — Dependencies for visibleColumns.
+12. **`hooks.headerGroups` / `hooks.headerGroupsDeps`** — runs at `useTable.ts:254-278`. Builds headerGroups + flatHeaders.
+
+### Instance phase (after dimensions are knowable)
+
+13. **`hooks.useInstanceBeforeDimensions`** — runs at `useTable.ts:280`, **after** flatHeaders. **This is where you mutate header widths.**
+14. **`hooks.useInstance`** — runs at `useTable.ts:304`. Instance setup. Add methods, compute derived state.
+15. **`hooks.useFinalInstance`** — runs at `useTable.ts:421`. After all other instance hooks.
+
+### Render-time
+
+16. **`hooks.prepareRow`** — Called per-row during render. Mutate row properties here.
+17. **Prop getters**: `getTableProps`, `getTableBodyProps`, `getHeaderGroupProps`, `getHeaderProps`, `getRowProps`, `getCellProps`, `getFooterGroupProps`, `getFooterProps`, `getResizerProps`, `getToggleRowSelectedProps`, `getToggleAllRowsSelectedProps`, `getToggleAllPageRowsSelectedProps`, `getToggleRowExpandedProps`, `getToggleAllRowsExpandedProps`, `getSortByToggleProps`, `getGroupByToggleProps`, `getToggleHiddenProps`, `getToggleHideAllColumnsProps`.
+
+### State
+
+18. **`hooks.stateReducers`** — Array of reducer functions. Each receives `(currentReducedState, action, originalState, instance)`. The `originalState` arg is the pre-reduce baseline (not the previous reducer's output). Falsy return preserves the previous state (no throw, unlike other reduceHooks).
+
+**Note on `materializedColumns` / `materializedColumnsDeps`:** declared in `makeDefaultPluginHooks` but **never invoked** inside the vendored `useTable.ts`. Don't rely on them.
+
+## `decorateColumn` Behavior
+
+The vendored `decorateColumn` (at `react-table/utils.ts:69-87`) runs inside the `visibleColumns` useMemo (after `hooks.visibleColumns`, before headerGroups are built). It **mutates columns in place**:
+
+```javascript
+// Actual decorateColumn implementation (Object.assign with spread):
+Object.assign(column, {
+  Header: emptyRenderer,
+  Footer: emptyRenderer,
+  ...defaultColumn, // library defaults: { Cell: defaultRenderer, width: 150, minWidth: 0, maxWidth: MAX_SAFE_INTEGER }
+  ...userDefaultColumn, // consumer-provided defaults
+  ...column, // column-specific properties win (highest priority)
+});
+Object.assign(column, { originalWidth: column.width });
+```
+
+This means: after `visibleColumns` are computed, any column without explicit `width` gets `width: 150`. If you need the **original** width (before decoration), you must capture it in `hooks.columns` — which runs well before `decorateColumn`.
+
+## The Safe Mutation Pattern
+
+```typescript
+// Step 1: Capture raw values in hooks.columns (BEFORE decorateColumn)
+const captureRawValues = (columns, { instance }) => {
+  instance.rawColumnSizing = new Map(); // NOTE: actual property name on the instance
+  for (const col of columns) {
+    instance.rawColumnSizing.set(col.id ?? col.accessor, {
+      width: col.width,
+      minWidth: col.minWidth,
+      maxWidth: col.maxWidth,
+    });
+  }
+  return columns; // UNCHANGED — no cascade
+};
+
+// Step 2: Mutate in useInstanceBeforeDimensions (AFTER decoration)
+const applyCalculatedWidths = (instance) => {
+  const { flatHeaders, rawColumnSizing } = instance;
+  for (const header of flatHeaders) {
+    const raw = rawColumnSizing.get(header.id);
+    // ... calculate new width ...
+    header.width = calculatedWidth;
+    header.originalWidth = calculatedWidth; // MUST keep in sync
+  }
+};
+
+hooks.columns.push(captureRawValues);
+hooks.useInstanceBeforeDimensions.push(applyCalculatedWidths);
+```
+
+## Plugin Registration
+
+Plugins are functions that receive `hooks` and push into hook arrays:
+
+```typescript
+const myPlugin = (hooks: ReactTableHooks) => {
+  hooks.stateReducers.push(myReducer);
+  hooks.useInstance.push(myInstanceHook);
+  hooks.getCellProps.push(myCellProps);
+};
+myPlugin.pluginName = 'myPlugin'; // REQUIRED — ensurePluginOrder throws without it
+```
+
+**Initialize vs append:**
+
+- `hooks.someArray.push(fn)` — APPENDS to the chain (most common).
+- `hooks.someArray = [fn]` — INITIALIZES a chain that has no defaults. Used by `useColumnResizing` for `getResizerProps` and by `useRowSelect` for `getToggleRowSelectedProps`/`getToggleAllRowsSelectedProps`/`getToggleAllPageRowsSelectedProps` — these prop-getter chains are NOT created by `makeDefaultPluginHooks`. The `=` assignment creates a new chain so later plugins (`useAutoResize`, `useOnColumnResize`) can `.push` onto it.
+
+## `webComponentsReactProperties`
+
+UI5WCR passes a custom config bag through useTable options:
+
+```typescript
+webComponentsReactProperties: {
+  // Selection & interaction
+  selectionMode, selectionBehavior, tagNamesWhichShouldNotSelectARow,
+  onRowSelect, onRowClick, onRowExpandChange, onAutoResize, onColumnsReorder,
+  onGroup, onSort, onFilter,
+  // Structure
+  isTreeTable, subRowsKey, renderRowSubComponent, alwaysShowSubComponent,
+  // Layout & display
+  scaleWidthMode, alternateRowColor, loading, showOverlay,
+  withRowHighlight, highlightField, withNavigationHighlight, markNavigatedRow,
+  // Environment
+  isFirefox, canUseVoiceOver, fontsReady,
+  // Internals
+  tableRef, uniqueId, classes,
+  a11yElementIds: { /* 5 element IDs */ },
+  translatableTexts: { /* 13 i18n text keys */ },
+}
+```
+
+**Note:** `isRtl` is NOT in `webComponentsReactProperties`. It is obtained via `useIsRTL(analyticalTableRef)` at the component level, dispatched to state via `IS_RTL` action, and accessed by hooks through `instance.state.isRtl`.
+
+All internal hooks access this via `instance.webComponentsReactProperties`.
+
+## Last resort: consult upstream react-table v7
+
+Only when reading the in-tree copy plus this skill plus its references genuinely doesn't answer the question — e.g., you need an example consumer not present in this repo, want to confirm a vendoring divergence, or are tracking down an upstream issue thread.
+
+- **Use the npm package `react-table`.** That npm name is v7 — the version this codebase forked from.
+- **It's acceptable to install it as a devDependency at the monorepo root** for local source access (grep, jump-to-definition) — `react-table` is not currently in any `package.json` here. This is a Yarn-workspaces monorepo, so install at the root (e.g., `yarn add -D -W react-table`), not inside `packages/main` or any other workspace — the dep is for investigation tooling, not part of any package's runtime/build. Remove it again after the investigation, and never import it at runtime — runtime imports stay relative to the in-tree `react-table/` copy.
+- **Do NOT consult `@tanstack/react-table`.** That is v8+, a complete rewrite under a different package name with a different API (`createColumnHelper`, `useReactTable`, no `hooks.*` plugin pipeline, different prop-getter conventions). v8 docs and source will actively mislead an agent debugging v7-based code.
+- **Upstream source:** `https://github.com/TanStack/table` — check the `v7` branch / tag.
+- **Upstream docs:** `https://react-table-v7.tanstack.com/`.
+- **Conflict resolution:** when upstream contradicts the in-tree copy, **the in-tree copy wins**. UI5WCR forks plugins (e.g., `useRowSelect` at `hooks/useRowSelect.ts` has no upstream counterpart in the vendored tree because it diverged); divergences are deliberate.
diff --git a/skills/maintainer/analytical-table/references/STATE-MANAGEMENT.md b/skills/maintainer/analytical-table/references/STATE-MANAGEMENT.md
new file mode 100644
index 00000000000..9697221af5e
--- /dev/null
+++ b/skills/maintainer/analytical-table/references/STATE-MANAGEMENT.md
@@ -0,0 +1,151 @@
+# AnalyticalTable State Management
+
+Companion docs: [HOOK-REFERENCE.md](HOOK-REFERENCE.md) for hook registration points; [REACT-TABLE-PIPELINE.md](REACT-TABLE-PIPELINE.md) for `stateReducers` invocation semantics.
+
+## State Shape
+
+```typescript
+interface AnalyticalTableState {
+  // --- react-table built-in ---
+  columnOrder: string[]; // Column display order
+  columnResizing: {
+    isResizingColumn: string | null; // Column ID being resized
+    columnWidths: Record<string, number>; // User-resized widths (persisted)
+    columnWidth?: number; // Singular — width snapshot at resize start (`useColumnResizing.ts:204`)
+    headerIdWidths?: [string, number, number, number][]; // [id, width, min, max] during drag
+    startX?: number; // Drag start X coordinate
+  };
+  expanded: Record<string | number, any>; // Expanded row IDs
+  filters: Filter[]; // Column filter state
+  groupBy: string[]; // Grouped column IDs
+  hiddenColumns: string[]; // Hidden column IDs
+  selectedRowIds: Record<string | number, any>; // Selected row IDs (values typically boolean)
+  sortBy: Record<string | number, any>[]; // Sort state (typically { id: string; desc: boolean })
+
+  // --- UI5WCR custom ---
+  tableClientWidth?: number; // Table container width (Math.floor'd)
+  popInColumns?: PopInColumnsState[]; // Responsive pop-in columns
+  interactiveRowsHavePopIn?: boolean; // Flag for interactive row pop-in
+  isRtl?: boolean; // Right-to-left mode
+  isScrollable?: boolean; // Whether table can scroll
+  subComponentsHeight?: Record<string, { rowId: string; subComponentHeight?: number }>;
+  visibleRows?: number; // Number of visible rows
+  bodyHeight?: number; // Read in `index.tsx` but no reducer writes it (legacy/dead).
+  triggerScroll?: TriggerScrollState; // Programmatic scroll target
+  tableColResized?: true; // User has manually resized a column (set to `true` or cleared to `undefined`)
+  rowCollapsed?: boolean; // Flag to prevent scroll-to-top on collapse
+  dndColumn?: string; // Column being dragged
+  cellContentTabIndex?: number; // Tab index for cell content (used by useF2CellEdit plugin)
+  indeterminateRows?: Record<string, boolean>; // Set by useIndeterminateRowSelection's INDETERMINATE_ROW_IDS action
+
+  // --- react-table built-in (vendored) — listed here because the type lives in the same shape ---
+  globalFilter?: string; // Managed by vendored useGlobalFilter, not custom
+}
+```
+
+## Custom Action Types
+
+### Container & Layout
+
+| Action                    | Payload                | Effect                                                                                                                                                                                                                             | Notes                                                                                                                           |
+| ------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `TABLE_RESIZE`            | `{ tableClientWidth }` | `Math.floor`-normalizes width. Early-returns when `nextWidth === state.tableClientWidth` (`stateReducer.ts:28-31`). Updates `tableClientWidth`. Clears `columnResizing.columnWidths` if delta > 20px AND `!state.tableColResized`. | 20px dead zone prevents reset on scrollbar flicker. Sub-20px shrinks keep stale resized widths when `retainColumnWidth` is off. |
+| `VISIBLE_ROWS`            | `{ visibleRows }`      | Updates `visibleRows`.                                                                                                                                                                                                             |                                                                                                                                 |
+| `TABLE_SCROLLING_ENABLED` | `{ isScrollable }`     | Updates `isScrollable`.                                                                                                                                                                                                            | Tracks whether vertical scrollbar is active.                                                                                    |
+| `IS_RTL`                  | `{ isRtl }`            | Updates `isRtl`.                                                                                                                                                                                                                   | Used by resize delta inversion.                                                                                                 |
+
+### Selection
+
+| Action                  | Payload              | Effect                                   | Notes                                                      |
+| ----------------------- | -------------------- | ---------------------------------------- | ---------------------------------------------------------- |
+| `SET_SELECTED_ROW_IDS`  | `{ selectedRowIds }` | Replaces `selectedRowIds`.               | For programmatic/controlled selection.                     |
+| `toggleRowSelected`     | (built-in)           | Updates `selectedRowIds`.                | Handled by `useRowSelect` reducer. Recursive for sub-rows. |
+| `toggleAllRowsSelected` | (built-in)           | Selects/deselects all non-grouped rows.  | Only considers `nonGroupedRowsById`.                       |
+| `resetSelectedRows`     | (built-in)           | Resets to `initialState.selectedRowIds`. |                                                            |
+
+### Column Resize
+
+| Action                | Payload                                 | Effect                                                                                                                                               | Notes                                                                                                                                                                                                             |
+| --------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `columnStartResizing` | `{ clientX, columnId, headerIdWidths }` | Sets `startX`, `headerIdWidths`, `isResizingColumn`.                                                                                                 | Records [id, width, minWidth, maxWidth] per header.                                                                                                                                                               |
+| `columnResizing`      | `{ clientX }`                           | Updates `columnWidths` via `getProjectedWidth`.                                                                                                      | Clamps to min/max. RTL inversion applied here.                                                                                                                                                                    |
+| `columnDoneResizing`  | —                                       | Clears `isResizingColumn` and `startX`; keeps `columnWidths`, `headerIdWidths`, and `columnWidth`.                                                   |                                                                                                                                                                                                                   |
+| `resetResize`         | —                                       | `useColumnResizing`'s reducer clears the `columnResizing` state slice. The **main** `stateReducer.ts:70-72` clears `tableColResized` on this action. | Fired by `useColumnResizing` when `columns` change (if `autoResetResize` is `true`). Also imperative via `instance.resetResizing()`. The two-reducer split makes `retainColumnWidth` recompute on column changes. |
+| `AUTO_RESIZE`         | `{ [columnId]: width }`                 | Merges into `columnResizing.columnWidths`.                                                                                                           | From double-click auto-resize. `useDynamicColumnWidths` short-circuits ALL recalculation while `columnResizing.columnWidths` is non-empty.                                                                        |
+| `TABLE_COL_RESIZED`   | boolean                                 | Sets `tableColResized`.                                                                                                                              | Prevents TABLE_RESIZE from clearing user widths.                                                                                                                                                                  |
+
+### Row Expand
+
+| Action                  | Payload     | Effect                                                                                                                                                                                                 | Notes                                                       |
+| ----------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| `toggleRowExpanded`     | `{ id }`    | Built-in expand logic. The **main `stateReducer.ts:18-26`** intercepts this action and additionally sets `rowCollapsed: true` (the `useToggleRowExpand` hook itself only handles props/announcements). | `rowCollapsed` flag prevents scroll-to-top when collapsing. |
+| `ROW_COLLAPSED_FLAG`    | boolean     | Sets `rowCollapsed`.                                                                                                                                                                                   | Reset after scroll adjustment.                              |
+| `SUB_COMPONENTS_HEIGHT` | height data | Updates `subComponentsHeight`.                                                                                                                                                                         | For virtualization height estimation.                       |
+
+### F2 Cell Edit
+
+| Action                   | Payload     | Effect                         | Notes                                                                                                                                                                                |
+| ------------------------ | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `CELL_CONTENT_TAB_INDEX` | `0` \| `-1` | Updates `cellContentTabIndex`. | Handled by `useF2CellEdit` reducer (`pluginHooks/useF2CellEdit.ts:249-250`). When `0`, `useKeyboardNavigation` disables nav-key handlers so interactive elements receive arrow keys. |
+
+### Indeterminate Selection (tree tables)
+
+| Action                  | Payload                   | Effect                       | Notes                                                                                                           |
+| ----------------------- | ------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `INDETERMINATE_ROW_IDS` | `Record<string, boolean>` | Updates `indeterminateRows`. | Handled by `useIndeterminateRowSelection` reducer (`pluginHooks/useIndeterminateRowSelection.tsx:133,174-176`). |
+
+### Responsive & Pop-In
+
+| Action                        | Payload       | Effect                              | Notes                                     |
+| ----------------------------- | ------------- | ----------------------------------- | ----------------------------------------- |
+| `SET_POPIN_COLUMNS`           | columns array | Updates `popInColumns`.             | Tracks which columns are in pop-in state. |
+| `INTERACTIVE_ROWS_HAVE_POPIN` | boolean       | Updates `interactiveRowsHavePopIn`. |                                           |
+
+### Drag & Drop
+
+| Action             | Payload   | Effect                      | Notes                                 |
+| ------------------ | --------- | --------------------------- | ------------------------------------- |
+| `COLUMN_DND_START` | column id | Sets `dndColumn`.           | Used for visual feedback during drag. |
+| `COLUMN_DND_END`   | —         | Clears `dndColumn` to `''`. |                                       |
+
+### Scrolling
+
+| Action                | Payload       | Effect                | Notes                                  |
+| --------------------- | ------------- | --------------------- | -------------------------------------- |
+| `TRIGGER_PROG_SCROLL` | scroll target | Sets `triggerScroll`. | For programmatic scroll-to-row/column. |
+
+### Filtering
+
+| Action      | Payload                     | Effect                                                                                                                              | Notes                                                                                                           |
+| ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `setFilter` | `{ filterValue, columnId }` | Built-in `useFilters` reducer updates `state.filters`. Custom stateReducer fires `onFilter` callback without further state changes. | The filter state change happens in the built-in reducer; the custom reducer only adds the callback side-effect. |
+
+## State Reducer Chain
+
+Reducers run in registration order (`useTable.ts:106-110`). The order in `index.tsx:310-333` is:
+
+**Internal hooks (in `useTable()`):**
+
+1. **Vendored react-table built-in reducers** (`useFilters`, `useGlobalFilter`, `useColumnOrder`, `useGroupBy`, `useSortBy`, `useExpanded`).
+2. **`useRowSelect`** reducer (registered BEFORE `useColumnResizing`) — selection actions; visible-only `selectedFlatRows`.
+3. **`useColumnResizing`** reducer — column resize actions (`columnStartResizing`, `columnResizing`, `columnDoneResizing`, `resetResize` clearing only the `columnResizing` slice).
+
+**Plugin hooks (user-provided, via `tableHooks`, appended LAST in registration order):**
+
+4. **`useOrderedMultiSort`** reducer — Reorders `sortBy` by priority on `toggleSortBy`.
+5. **`useIndeterminateRowSelection`** reducer — Handles `INDETERMINATE_ROW_IDS`; mutates `selectedRowIds` to auto-select parents on `toggleRowSelected` when all siblings selected.
+6. **`useF2CellEdit`** reducer — Handles `CELL_CONTENT_TAB_INDEX`.
+
+**Main table reducer (passed as the `useTable` `stateReducer` option, runs after all `hooks.stateReducers`):**
+
+7. **`stateReducer` (`tableReducer/stateReducer.ts`)** — Handles all custom UI5WCR actions (`TABLE_RESIZE`, `SET_SELECTED_ROW_IDS`, `COLUMN_DND_START`/`END`, `IS_RTL`, `VISIBLE_ROWS`, `TABLE_SCROLLING_ENABLED`, `SET_POPIN_COLUMNS`, `INTERACTIVE_ROWS_HAVE_POPIN`, `SUB_COMPONENTS_HEIGHT`, `TRIGGER_PROG_SCROLL`, `AUTO_RESIZE`, `TABLE_COL_RESIZED`); intercepts `toggleRowExpanded` to dispatch `rowCollapsed`; clears `tableColResized` on `resetResize`; calls `setFilter` callback as side-effect.
+
+**Note:** `useSingleRowStateSelection`, `useSelectionChangeCallback`, `useToggleRowExpand`, and `useColumnDragAndDrop` do NOT have state reducers — they work through props getters or `useInstance`/`useEffect`.
+
+## State Persistence Gotchas
+
+1. **`selectedRowIds` uses string keys** — Row IDs are stringified. `{ '0': true }` not `{ 0: true }`.
+2. **`autoResetSelectedRows`** — Defaults to `true` in react-table (clears selection on data change). [`useManualRowSelect`](HOOK-REFERENCE.md#plugin-hooks-7-in-pluginhooks-plus-the-analyticaltablehooks-namespace-export) sets it to `false` automatically. Without that hook, consumers using the controlled `selectedRowIds` prop must set `autoResetSelectedRows: false` in `reactTableOptions` — the `useEffect` in `index.tsx` that dispatches `SET_SELECTED_ROW_IDS` won't re-fire on `data` change because its dep is the `selectedRowIds` prop reference, not `data`.
+3. **`columnOrder` reconciliation** — Both vendored `useColumnOrder.visibleColumns` AND `useDragAndDrop.handleOnDrop` reconcile stale IDs. The DnD handler uses the same algorithm: iterates `columnOrder`, keeps only IDs that exist in current columns, appends new columns at end.
+
+(For `columnWidths` retention, `tableColResized` gating, and `rowCollapsed` semantics, see the action tables above.)