domain_map.yaml

library:
  name: '@tanstack/table'
  version: 9.0.0-alpha.47
  repository: https://github.com/TanStack/table
  homepage: https://tanstack.com/table
  description:
    'Headless data-grid library: features, state, and APIs for building powerful, type-safe
    tables and datagrids while keeping full control of markup, styles, and behavior. Framework-agnostic
    core (`@tanstack/table-core`) with adapters for React, Vue, Solid, Svelte, Angular, Lit, and Preact.'
  primary_framework: framework-agnostic
  monorepo: true
meta:
  generated_by: '@tanstack/intent scaffold (Phase 3 deep-read merge)'
  date: '2026-05-17'
  status: reviewed
  maintainer_review_pending: false
  phase_4_date: '2026-05-17'
domains:
  - name: Core foundations
    slug: core-foundations
    description:
      Setup, column definitions, state management, and customization of built-in feature behavior.
      State-management is the prerequisite for every other skill.
  - name: Row-model features
    slug: row-model-features
    description:
      Features driven by entries in `_rowModels` — filtering (column+global+faceting+fuzzy),
      sorting, pagination, grouping, expanding. All have `manual<Feature>` opt-outs for server-side data.
  - name: UI-state features
    slug: ui-state-features
    description:
      Features that are pure UI state — no row model needed. Column layout (visibility/ordering/pinning/sizing/resizing),
      row pinning, row selection.
  - name: Framework adapters
    slug: framework-adapters
    description:
      Per-framework reactivity bindings and rendering integration. Each adapter has its own `table-state`
      skill; React adds Subscribe-for-React-Compiler, Angular adds structural directives, Lit adds the TableController
      pattern.
  - name: Lifecycle
    slug: lifecycle
    description:
      'End-to-end journeys that cross-cut features: getting-started, v8→v9 migration, client-to-server
      conversion, production-readiness.'
  - name: Composition
    slug: composition
    description:
      Patterns for using TanStack Table with sibling TanStack libraries (Store, Query, Virtual,
      Form, Pacer, Devtools). Per maintainer decision, no per-UI-library composition skills.
skills:
  - name: Setup
    slug: setup
    domain: core-foundations
    description:
      Install a table adapter and wire up a first working table with `_features`, `_rowModels`,
      columns, and data.
    type: core
    packages:
      - '@tanstack/table-core'
    covers:
      - tableFeatures
      - _features
      - _rowModels
      - useTable
      - constructTable
      - _createTable
      - stockFeatures
      - coreFeatures
      - storeReactivityBindings
      - FlexRender
      - flexRender
      - table.getHeaderGroups
      - table.getRowModel
    tasks:
      - Render a first read-only table from an array of objects
      - Decide between an empty `tableFeatures({})` core-only setup vs `stockFeatures` (all features) vs hand-picked
        feature imports
      - Wire up the matching adapter (`useTable` / `injectTable` / `createTable` / `constructTable`) and render
        markup with `<table.FlexRender />` or `flexRender`
      - Use `@tanstack/table-core` + `storeReactivityBindings()` directly (vanilla JS) when no framework adapter
        exists
    failure_modes:
      - mistake: Omits `_features` and `_rowModels`
        mechanism:
          v9 requires `_features` (and an `_rowModels` map, even if empty) at the top of `useTable`/`constructTable`
          options. Without `_features`, TypeScript loses feature-state inference and runtime construction
          has no feature plugins to register.
        wrong_pattern: |
          // v8-flavoured, breaks in v9
          const table = useTable({
            columns,
            data,
            getCoreRowModel: getCoreRowModel(), // v8 option name
          })
        correct_pattern: |
          // v9 minimal table
          const _features = tableFeatures({}) // empty = core features only
          const table = useTable({
            _features,
            _rowModels: {}, // core row model auto-included
            columns,
            data,
          })
        source: examples/react/basic-use-table/src/main.tsx:56-109; docs/guide/tables.md:33-47; docs/framework/react/guide/migrating.md:78-103
        priority: CRITICAL
        status: active
        version_context:
          v9 alpha; affects every user upgrading from v8 — the hook is renamed (`useReactTable`
          → `useTable`) AND new required options were introduced
      - mistake: Calls `tableFeatures({})` inside the component body
        mechanism:
          A fresh `_features` object on each render destroys the table's stable reference for feature
          registration, the same way unstable `columns`/`data` cause infinite re-renders. `_features` must
          be hoisted to module scope or memoized.
        wrong_pattern: |
          function MyTable() {
            // ❌ new object every render -> potential re-construct + state churn
            const _features = tableFeatures({ rowSortingFeature })
            const table = useTable({ _features, _rowModels: {}, columns, data })
          }
        correct_pattern: |
          // ✅ module-scoped, stable reference
          const _features = tableFeatures({ rowSortingFeature })

          function MyTable() {
            const table = useTable({ _features, _rowModels: {}, columns, data })
          }
        source:
          docs/guide/data.md:184-244; examples/react/basic-use-table/src/main.tsx:56 (defined outside
          component)
        priority: HIGH
        status: active
        version_context: v9 alpha; new in v9 because v8 had no `_features` option
        skills:
          - state-management
      - mistake: Reaches for `stockFeatures` by default
        mechanism:
          Reaching for `stockFeatures` re-introduces v8 bundle size (~15–20kb), silently negating
          v9's opt-in tree-shaking. The v9 default is hand-picked features; `stockFeatures` exists only as
          a v8 escape hatch.
        wrong_pattern: |
          // ❌ ships every feature, even unused ones
          import { useTable, stockFeatures } from '@tanstack/react-table'
          const table = useTable({
            _features: stockFeatures,
            _rowModels: {},
            columns,
            data,
          })
        correct_pattern: |
          // ✅ only the features you use
          import {
            tableFeatures,
            useTable,
            rowSortingFeature,
            rowPaginationFeature,
          } from '@tanstack/react-table'

          const _features = tableFeatures({
            rowSortingFeature,
            rowPaginationFeature,
          })
        source: docs/framework/react/guide/migrating.md:9-12,136-147; packages/table-core/src/features/stockFeatures.ts:38-53
        priority: MEDIUM
        status: active
        version_context: v9 alpha; `stockFeatures` is documented but discouraged for new code
      - mistake: Adds a row model without registering its feature
        mechanism:
          Row model factories like `createSortedRowModel` only run if the matching feature (e.g.
          `rowSortingFeature`) is also registered in `_features`. TypeScript flags this when state slices/APIs
          are accessed, but runtime silently degrades — `table.atoms.sorting` is undefined and sort handlers
          do nothing.
        wrong_pattern: |
          // ❌ rowSortingFeature missing from _features — sortedRowModel orphaned
          const _features = tableFeatures({ rowPaginationFeature })
          const table = useTable({
            _features,
            _rowModels: {
              sortedRowModel: createSortedRowModel(sortFns), // no-op
              paginatedRowModel: createPaginatedRowModel(),
            },
            columns,
            data,
          })
        correct_pattern: |
          // ✅ feature + row model registered together
          const _features = tableFeatures({
            rowSortingFeature,
            rowPaginationFeature,
          })
          const table = useTable({
            _features,
            _rowModels: {
              sortedRowModel: createSortedRowModel(sortFns),
              paginatedRowModel: createPaginatedRowModel(),
            },
            columns,
            data,
          })
        source: docs/guide/row-models.md:46-78; examples/react/basic-external-atoms/src/main.tsx:27-30,81-92
        priority: HIGH
        status: active
        version_context: v9 alpha; new failure surface since v8 had no _features/feature-row-model pairing
      - mistake: Passing empty array literal to data causes infinite rerenders
        mechanism: |
          `const data = items ?? []` creates a new `[]` reference on every render. The
          table sees a fresh `data` prop and rebuilds row models; if any callback in the
          same render also reads from the table, you get an infinite re-render loop.
        wrong_pattern: |
          // ❌ Fresh [] each render — infinite loop when items is undefined
          const table = useReactTable({
            data: items ?? [],
            columns,
            getCoreRowModel: getCoreRowModel(),
          })
        correct_pattern: |
          // ✅ Hoist the empty fallback OR memoize
          const EMPTY: MyRow[] = []
          const table = useReactTable({
            data: items ?? EMPTY,
            columns,
            getCoreRowModel: getCoreRowModel(),
          })
          // OR
          const data = useMemo(() => items ?? [], [items])
        source:
          https://github.com/TanStack/table/issues/4566 (Empty data causes infinite looping), https://github.com/TanStack/table/issues/6002
          (if data is empty array, then rendering table is causing infinite rerenders)
        priority: CRITICAL
        status: active
        version_context:
          Affects every version. Top recurring beginner issue. Maintainer (KevinVandy) explicitly
          says docs need to make stability obvious.
        skills:
          - setup
          - getting-started
          - state-management
      - mistake: Defining columns inside the render body without useMemo
        mechanism: |
          Defining `columns` inline inside the component body creates a fresh column array
          every render. Table internals see new column references and rebuild header
          groups, recalculate sizes, and lose memo caches — leading to slow renders and
          cells/components remounting on every parent state change.
        wrong_pattern: |
          // ❌ Columns recreated every render
          function MyTable({ data }) {
            const columns = [
              columnHelper.accessor('name', { header: 'Name' }),
              columnHelper.accessor('email', { header: 'Email' }),
            ]
            const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() })
            ...
          }
        correct_pattern: |
          // ✅ Hoist outside, or useMemo with stable deps
          const columns = [
            columnHelper.accessor('name', { header: 'Name' }),
            columnHelper.accessor('email', { header: 'Email' }),
          ]
          function MyTable({ data }) {
            const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() })
            ...
          }
        source:
          https://github.com/TanStack/table/issues/5141 (What props passed to useReactTable hook have
          to be stable?), https://github.com/TanStack/table/issues/4794 (unnecessary rerenders)
        priority: CRITICAL
        status: active
        version_context:
          'Top-priority pattern across v7, v8, v9. v9 makes columns/data readonly (PR #6183)
          to nudge users.'
        skills:
          - setup
          - state-management
          - production-readiness
      - mistake: Hallucinating react-table v7 / pre-v9 @tanstack/[framework]-table APIs
        mechanism:
          Every major release of TanStack Table (formerly react-table) has been a substantial upgrade.
          Agents trained on older data confidently produce v7 or v8 API shapes that no longer exist in v9
          (e.g. `useReactTable`, inline `getCoreRowModel()` as an option, `useTable` from react-table v7).
        wrong_pattern: |-
          // ❌ v7 / v8 patterns the agent invents
          import { useTable, useSortBy } from 'react-table' // v7
          const table = useTable({ columns, data }, useSortBy)

          // or v8
          import { useReactTable, getCoreRowModel } from '@tanstack/react-table'
          const table = useReactTable({ columns, data, getCoreRowModel: getCoreRowModel() })
        correct_pattern: |-
          // ✅ v9 pattern — `_features` + `_rowModels`
          import { useTable, tableFeatures, rowSortingFeature, createSortedRowModel, sortFns } from '@tanstack/react-table'
          const _features = tableFeatures({ rowSortingFeature })
          const table = useTable({
            _features,
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
        priority: CRITICAL
        version_context:
          v7→v8 and v8→v9 both shifted the API substantially; agents trained on any pre-v9
          data will produce wrong shapes.
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
      - mistake: API or state slice "missing" because the feature was not registered in `_features`
        mechanism:
          In v9, `_features` is a tree-shakeable registry. If a feature is not in `_features`, TypeScript
          hides its APIs and the runtime atom is not created. Agents who copy a snippet for `table.setColumnFilters(...)`
          without registering `columnFilteringFeature` see a TS error or `table.atoms.columnFilters` is undefined
          — and may incorrectly conclude the feature is broken or removed in v9.
        wrong_pattern: |-
          // ❌ rowSortingFeature missing — table.setSorting / state.sorting unavailable
          const _features = tableFeatures({}) // empty
          const table = useTable({ _features, _rowModels: {}, columns, data })
          table.setSorting([{ id: 'age', desc: true }]) // ❌ does not exist on this table type
        correct_pattern: |-
          // ✅ Register every feature you intend to use; pair with its row model when applicable
          const _features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
          const table = useTable({
            _features,
            _rowModels: {
              sortedRowModel: createSortedRowModel(sortFns),
              paginatedRowModel: createPaginatedRowModel(),
            },
            columns, data,
          })
        priority: CRITICAL
        version_context:
          v9-specific. This is the first version of TanStack Table where features must be declared
          for TypeScript and runtime to expose them. Expect heavy confusion from devs and agents trained on
          v8.
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
      - mistake: Bundling stockFeatures or all features when only a few are used
        mechanism:
          TanStack Table v9 is tree-shakeable specifically so you only pay for features you use.
          Registering `stockFeatures` (or every feature "just in case") forfeits the bundle benefit that motivated
          the v9 redesign.
        wrong_pattern: |-
          // ❌ Pulls in every feature even though only sorting+pagination are used
          import { stockFeatures, tableFeatures } from '@tanstack/react-table'
          const _features = tableFeatures(stockFeatures)
        correct_pattern: |-
          // ✅ Register only what this table uses
          import { tableFeatures, rowSortingFeature, rowPaginationFeature } from '@tanstack/react-table'
          const _features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
        priority: HIGH
        version_context: v9. Tree-shaking via `_features` is one of the headline reasons for the rewrite.
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
  - name: Column Definitions
    slug: column-definitions
    domain: core-foundations
    description:
      Define columns with `createColumnHelper<typeof _features, TData>()` to extract data and
      render headers/cells/footers.
    type: core
    packages:
      - '@tanstack/table-core'
    covers:
      - createColumnHelper
      - columnHelper.accessor
      - columnHelper.display
      - columnHelper.group
      - columnHelper.columns
      - ColumnDef
      - AccessorKeyColumnDef
      - AccessorFnColumnDef
      - DisplayColumnDef
      - GroupColumnDef
      - accessorKey
      - accessorFn
      - header
      - cell
      - footer
      - aggregatedCell
      - id
      - getRowId
      - DeepKeys
      - flexRender
    tasks:
      - Create a typed `columnHelper` and define accessor/display/group columns with strong inference
      - 'Pick between `accessorKey: "name.first"` (deep key with dots) and `accessorFn: row => row.name.first`
        for nested / computed values'
      - Use `getRowId` to derive stable row identifiers from data (instead of array index) so selection/expansion
        survive data updates
      - Render headers/cells/footers with `<table.FlexRender />` (or `flexRender`) so string / JSX / function
        forms all work
    failure_modes:
      - mistake: Passes only TData to `createColumnHelper`
        mechanism:
          'v9 changed the generic order: `createColumnHelper<TFeatures, TData>`. v8 code passed only
          `<TData>`, which now binds `TData` into the `TFeatures` slot and breaks every column type. The compiler
          error is noisy and not obvious.'
        wrong_pattern: |
          // ❌ v8 signature — TData ends up in the TFeatures slot
          const columnHelper = createColumnHelper<Person>()
        correct_pattern: |
          // ✅ v9 — TFeatures first, TData second; use typeof _features
          const _features = tableFeatures({ rowSortingFeature })
          const columnHelper = createColumnHelper<typeof _features, Person>()
        source:
          packages/table-core/src/helpers/columnHelper.ts:99-103; docs/framework/react/guide/migrating.md:484-499;
          examples/react/basic-external-atoms/src/main.tsx:32
        priority: CRITICAL
        status: active
        version_context: v9 alpha; breaking change vs v8 generic signature
      - mistake: Accessor function returns an object/array
        mechanism:
          The accessed value is what the table uses for sorting, filtering, faceting, and grouping.
          Returning a non-primitive value means the built-in sort/filter/aggregation functions silently misbehave
          or throw — only `displayCell` ever sees the value formatted. A primitive `string`/`number`/`Date`
          is expected unless you supply a matching `sortFn`/`filterFn`/`aggregationFn`.
        wrong_pattern: |
          // ❌ returns an object — built-in alphanumeric/text sort and includesString filter break
          columnHelper.accessor((row) => row.name, {
            id: 'name',
            cell: (info) => `${info.getValue().first} ${info.getValue().last}`,
          })
        correct_pattern: |
          // ✅ accessor returns a primitive; cell can still format it
          columnHelper.accessor((row) => `${row.name.first} ${row.name.last}`, {
            id: 'fullName',
            cell: (info) => info.getValue(),
          })
        source: docs/guide/column-defs.md:231; examples/react/basic-subscribe/src/main.tsx:103-108
        priority: HIGH
        status: active
        version_context: always present
        skills:
          - customizing-feature-behavior
      - mistake: Omits `id` on an accessorFn column
        mechanism:
          When a column uses `accessorFn` (not `accessorKey`), there is nothing to derive an id from.
          The constructor throws "coreColumnsFeature require an id when using an accessorFn" in development.
          The same applies to non-string `header` values — without `id` or a string header, construction fails.
        wrong_pattern: |
          // ❌ accessorFn + JSX header => no id can be derived
          columnHelper.accessor((row) => row.lastName, {
            header: () => <span>Last Name</span>,
            cell: (info) => info.getValue(),
          })
        correct_pattern: |
          // ✅ explicit id whenever you use accessorFn
          columnHelper.accessor((row) => row.lastName, {
            id: 'lastName',
            header: () => <span>Last Name</span>,
            cell: (info) => info.getValue(),
          })
        source:
          packages/table-core/src/core/columns/constructColumn.ts:91-100; examples/react/basic-use-table/src/main.tsx:65-70;
          docs/guide/column-defs.md:233-243
        priority: CRITICAL
        status: active
        version_context: always present (same rule as v8)
      - mistake: Defines `columns` inside the component without `useMemo`
        mechanism:
          'TanStack Table compares `columns` and `data` by reference. Re-creating either array on
          each render triggers internal recomputation that, in React, causes an infinite loop (state change
          -> render -> new `columns` -> state change). This is the #1 FAQ.'
        wrong_pattern: |
          function MyTable() {
            // ❌ new array reference every render -> infinite render loop
            const columns = [
              columnHelper.accessor('firstName', { header: 'First' }),
              columnHelper.accessor('lastName', { header: 'Last' }),
            ]
            const table = useTable({ _features, _rowModels: {}, columns, data })
          }
        correct_pattern: |
          // ✅ memoized columns or module-scoped via columnHelper.columns([...])
          function MyTable() {
            const columns = React.useMemo(
              () =>
                columnHelper.columns([
                  columnHelper.accessor('firstName', { header: 'First' }),
                  columnHelper.accessor('lastName', { header: 'Last' }),
                ]),
              [],
            )
            const table = useTable({ _features, _rowModels: {}, columns, data })
          }
        source: docs/faq.md:5-128; examples/react/basic-subscribe/src/main.tsx:51-127
        priority: CRITICAL
        status: active
        version_context: 'always present; #1 reason for infinite re-renders'
        skills:
          - setup
          - state-management
      - mistake: Uses array index `row.id` and updates data
        mechanism:
          By default, `row.id` is the row's index in `data`. When `data` is reordered, filtered,
          or items are removed, row-keyed state (selection, expansion, pinning) attaches to the wrong row.
          `getRowId` derives a stable id from the row's own data.
        wrong_pattern: |
          // ❌ no getRowId -> rowSelection survives data updates but maps to wrong rows
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            enableRowSelection: true,
          })
        correct_pattern: |
          // ✅ stable id from the row's own identifier
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            getRowId: (row) => row.id,
            enableRowSelection: true,
          })
        source: docs/guide/rows.md:48-59; examples/react/basic-subscribe/src/main.tsx:148; packages/table-core/src/core/rows/coreRowsFeature.utils.ts:215-228
        priority: HIGH
        status: active
        version_context: always present
      - mistake: Column visibility toggle on column groups produces incorrect state
        mechanism: |
          Calling `column.toggleVisibility()` on a column GROUP writes `false` to
          `columnVisibility[groupId]`, but `getIsVisible()` for a group always returns
          `true` regardless. Users wire up a checkbox to the group header thinking it
          hides children — it doesn't.
        wrong_pattern: |
          // ❌ Group-level toggle silently no-ops on visibility
          <Checkbox checked={column.getIsVisible()} onChange={column.toggleVisibility} />
        correct_pattern: |
          // ✅ Iterate leaves explicitly
          function toggleGroupVisibility(group) {
            const targetVisible = !group.getLeafColumns().every(c => c.getIsVisible())
            group.getLeafColumns().forEach(c => c.toggleVisibility(targetVisible))
          }
        source:
          https://github.com/TanStack/table/issues/5497 (Column visibility APIs do not work with column
          groups, 5 comments)
        priority: MEDIUM
        status: active
        version_context: v8 / v9
        skills:
          - column-definitions
          - column-layout
      - mistake: accessor with optional path strips undefined from getValue type
        mechanism: |
          The `DeepValue` generic in table-core walks a dotted path as `infer TBranch`/
          `infer TDeepProp`, but doesn't propagate `undefined` when an intermediate key
          is optional. `getValue()` returns `number` when it should return `number | undefined`,
          hiding real runtime errors.
        wrong_pattern: |
          // ❌ amount is inferred as `number` even though salary is optional
          columnHelper.accessor('user.salary.amount', {
            cell: (row) => {
              const amount = row.getValue()  // type: number (WRONG)
              return amount.toFixed(2)        // crashes when salary is undefined
            },
          })
        correct_pattern: |
          // ✅ Use accessorFn for paths with optional segments — type follows expression
          columnHelper.accessor((row) => row.user.salary?.amount, {
            id: 'salary',
            cell: (info) => {
              const amount = info.getValue()  // type: number | undefined
              return amount?.toFixed(2) ?? '-'
            },
          })
        source:
          https://github.com/TanStack/table/issues/6238 (accessor getValue() loses undefined for key
          paths with optional keys)
        priority: MEDIUM
        status: active
        version_context: v8 + v9 type bug
      - mistake: columnHelper.accessor inside columnHelper.group loses getValue type inference
        mechanism: |
          When an accessor is nested inside a `columnHelper.group()`, the `info.getValue()`
          return type degrades to `unknown` because the group helper's overloads don't
          thread the row-data generic through correctly.
        wrong_pattern: |
          // ❌ info.getValue() inferred as unknown
          columnHelper.group({
            id: 'name',
            columns: [
              columnHelper.accessor('firstName', {
                cell: (info) => info.getValue(),  // unknown
              }),
            ],
          })
        correct_pattern: |
          // ✅ Hoist accessor definitions out of the group
          const firstNameCol = columnHelper.accessor('firstName', {
            cell: (info) => info.getValue(),  // string
          })
          columnHelper.group({ id: 'name', columns: [firstNameCol] })
        source:
          https://github.com/TanStack/table/issues/5860 (getValue fails to infer correct type when columnHelper.accessor
          defined within columnHelper.group), https://github.com/TanStack/table/issues/5065
        priority: MEDIUM
        status: active
        version_context: v8 / v9
      - mistake: getValue cache not invalidating when accessorFn changes
        mechanism: |
          `getValue` caches per-column by ID. If you swap `accessorFn` in response to a
          state change (e.g. "Last, First" ↔ "First Last" toggle) without changing the
          column ID, cached values are returned. The new accessor never runs.
        wrong_pattern: |
          // ❌ Stale values shown after accessor switch
          const columns = useMemo(() => [
            columnHelper.accessor(
              firstFormat ? (row) => row.firstName + ' ' + row.lastName : (row) => row.lastName + ', ' + row.firstName,
              { id: 'name' }
            ),
          ], [firstFormat])
        correct_pattern: |
          // ✅ Either change the column ID (loses sort/filter state) OR move the logic
          //    into cell() which is not cached:
          columnHelper.accessor((row) => ({ first: row.firstName, last: row.lastName }), {
            id: 'name',
            cell: (info) => {
              const { first, last } = info.getValue()
              return firstFormat ? `${first} ${last}` : `${last}, ${first}`
            },
          })
        source:
          https://github.com/TanStack/table/issues/5363 (getValue cache not invalidating when accessorFn
          is updated)
        priority: MEDIUM
        status: active
        version_context: v8 / v9 — caching is fundamental, not a bug
        skills:
          - column-definitions
          - column-layout
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    maintainer_notes:
      - accessorKey + deep keys may be simplified in v10 (accessorFn + id is the maintainer's preferred long-term
        shape). For v9, accessorKey remains fully supported and the more concise option for simple keys.
  - name: State Management
    slug: state-management
    domain: core-foundations
    description:
      Coordinate table state slices (sorting, pagination, filters, selection, etc.) across `initialState`,
      `state`+`on*Change`, and external `atoms`, with awareness of v9 atom precedence.
    type: core
    packages:
      - '@tanstack/table-core'
    covers:
      - baseAtoms
      - atoms
      - store
      - state
      - initialState
      - on[State]Change
      - setOptions
      - reset
      - resetSorting
      - resetPagination
      - resetColumnFilters
      - resetGlobalFilter
      - resetRowSelection
      - manualFiltering
      - manualSorting
      - manualPagination
      - manualExpanding
      - manualGrouping
      - autoResetPageIndex
      - autoResetAll
      - TableState
      - SortingState
      - PaginationState
      - RowSelectionState
      - ColumnFiltersState
      - GroupingState
      - storeReactivityBindings
      - createAtom
      - useCreateAtom
      - useSelector
      - Subscribe
      - table.Subscribe
      - useTable selector (second argument)
    tasks:
      - Decide which state ownership pattern fits — internal (default) vs `state`+`on*Change` (v8 controlled)
        vs external `atoms` (v9 preferred) vs `initialState` (starting value only)
      - Promote a slice to external state when the app needs to share it with a server query, persistence,
        or another component
      - Toggle a feature to a "manual" server-side mode (`manualSorting`, `manualFiltering`, `manualPagination`)
        — sort/filter/paginate happen server-side and the table just renders the page
      - Reset state with feature reset APIs (`resetSorting()`, `resetPagination(true)`) and understand why
        `table.reset()` is unsafe when slices are externally owned
    failure_modes:
      - mistake: Passes both `state.pagination` and `atoms.pagination`
        mechanism:
          When both are supplied for the same slice, the external atom wins silently. `state.pagination`
          is then dead config — UI values written to React state never reach the table, leading to "I called
          setPagination but nothing updated" bugs.
        wrong_pattern: |
          // ❌ both ownership paths for the same slice
          const paginationAtom = useCreateAtom<PaginationState>({ pageIndex: 0, pageSize: 10 })
          const [pagination, setPagination] = React.useState(...)

          const table = useTable({
            _features, _rowModels: {...}, columns, data,
            state: { pagination },       // ignored
            onPaginationChange: setPagination,
            atoms: { pagination: paginationAtom }, // wins
          })
        correct_pattern: |
          // ✅ pick one ownership path per slice — here, external atoms
          const paginationAtom = useCreateAtom<PaginationState>({ pageIndex: 0, pageSize: 10 })

          const table = useTable({
            _features, _rowModels: {...}, columns, data,
            atoms: { pagination: paginationAtom },
            // no state.pagination, no onPaginationChange needed
          })
        source:
          docs/framework/react/guide/table-state.md:315-316; docs/framework/react/guide/migrating.md:465-481;
          packages/table-core/src/core/table/constructTable.ts:93-103 (atom precedence)
        priority: CRITICAL
        status: active
        version_context: v9 alpha; new ownership-conflict surface introduced by the `atoms` option
      - mistake: Uses external `state` without the matching `on*Change` callback
        mechanism:
          External `state.sorting` syncs into the table's base atom, but without `onSortingChange`
          the table has no way to update React state — every sort toggle appears to do nothing. v9 silently
          keeps reading from `state` so the UI looks "stuck".
        wrong_pattern: |
          // ❌ state without callback — sort toggles never reach setSorting
          const [sorting, setSorting] = React.useState<SortingState>([])
          const table = useTable({
            _features, _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
            state: { sorting }, // no onSortingChange
          })
        correct_pattern: |
          // ✅ state + on*Change must be paired
          const [sorting, setSorting] = React.useState<SortingState>([])
          const table = useTable({
            _features, _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
            state: { sorting },
            onSortingChange: setSorting,
          })
        source: docs/framework/react/guide/table-state.md:415-435; examples/react/basic-external-state/src/main.tsx:64-94
        priority: CRITICAL
        status: active
        version_context: always present (same v8 rule)
      - mistake: Uses `initialState` to control or update state
        mechanism:
          '`initialState` is only read once at construction time to build base atoms; mutating it
          later does NOT update table state. Developers expect a React-state-like contract and watch state
          freeze in place.'
        wrong_pattern: |
          // ❌ updates to initialState are ignored after first render
          function MyTable({ defaultSort }: { defaultSort: SortingState }) {
            const table = useTable({
              _features, _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
              columns, data,
              initialState: { sorting: defaultSort }, // ❌ later changes to defaultSort never sync
            })
          }
        correct_pattern: |
          // ✅ control with state + on*Change (or an external atom)
          function MyTable({ defaultSort }: { defaultSort: SortingState }) {
            const [sorting, setSorting] = React.useState(defaultSort)
            const table = useTable({
              _features, _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
              columns, data,
              state: { sorting },
              onSortingChange: setSorting,
            })
          }
        source: docs/framework/vanilla/guide/table-state.md:142-175; docs/framework/react/guide/table-state.md:285-315
        priority: HIGH
        status: active
        version_context: always present (same v8 rule)
      - mistake: Writes to `table.baseAtoms.x.set(...)` while `atoms.x` owns the slice
        mechanism:
          When an external atom is supplied for a slice, `table.atoms.x` derives from it, not from
          `baseAtoms.x`. Writes to the base atom silently no-op for reads; the UI shows the external atom's
          value, the base atom drifts, and reset behavior gets weird.
        wrong_pattern: |
          // ❌ direct baseAtoms write while external atom owns the slice
          const paginationAtom = useCreateAtom<PaginationState>({ pageIndex: 0, pageSize: 10 })
          const table = useTable({ _features, _rowModels: {...}, columns, data, atoms: { pagination: paginationAtom } })

          // later, somewhere
          table.baseAtoms.pagination.set((old) => ({ ...old, pageIndex: 0 }))
          // ❌ baseAtom updated, but table.atoms.pagination still reads from paginationAtom
        correct_pattern: |
          // ✅ write to the external atom (or use the feature's setter API)
          paginationAtom.set((old) => ({ ...old, pageIndex: 0 }))
          // or
          table.setPageIndex(0)
        source:
          docs/framework/vanilla/guide/table-state.md:138-141; docs/framework/react/guide/table-state.md:280-283;
          packages/table-core/src/core/table/constructTable.ts:93-103
        priority: HIGH
        status: active
        version_context: v9 alpha; new pitfall introduced by atom architecture
      - mistake: Forgets `manualSorting`/`manualFiltering`/`manualPagination` when serving server-side data
        mechanism:
          'Without the `manual*` flag, the table re-applies its client-side row models on top of
          already-sorted/filtered/paginated server data — rows get re-sorted, re-filtered, or sliced into
          another page. Symptoms: wrong rows shown, broken page math, blank pages.'
        wrong_pattern: |
          // ❌ data is already paginated server-side, but table still slices it
          const dataQuery = useQuery({ queryKey: ['data', pagination], queryFn: fetchPage })
          const table = useTable({
            _features, _rowModels: { paginatedRowModel: createPaginatedRowModel() },
            columns,
            data: dataQuery.data?.rows ?? [],
            rowCount: dataQuery.data?.rowCount,
            atoms: { pagination: paginationAtom },
            // ❌ missing manualPagination: true
          })
        correct_pattern: |
          // ✅ tell the table the server handles pagination
          const table = useTable({
            _features, _rowModels: {}, // can drop paginatedRowModel if fully server-side
            columns,
            data: dataQuery.data?.rows ?? [],
            rowCount: dataQuery.data?.rowCount,
            atoms: { pagination: paginationAtom },
            manualPagination: true,
          })
        source:
          docs/framework/vanilla/guide/table-state.md:197-228; docs/framework/react/guide/table-state.md:336-378;
          packages/table-core/src/features/row-pagination/rowPaginationFeature.types.ts:20-23
        priority: CRITICAL
        status: active
        version_context: always present (same v8 rule)
      - mistake: Uses `table.reset()` to clear externally owned state
        mechanism:
          '`table.reset()` only resets the internal `baseAtoms` to `initialState`; slices owned by
          external atoms or external `state` are untouched. Developers expect "reset everything" and end up
          with half-reset state (visible state from external atom, hidden state in baseAtom drifts).'
        wrong_pattern: |
          // ❌ external atom keeps its current value; only baseAtoms reset
          const sortingAtom = useCreateAtom<SortingState>([])
          const table = useTable({
            _features, _rowModels: {...}, columns, data,
            atoms: { sorting: sortingAtom },
          })
          // ...
          table.reset() // sortingAtom is NOT cleared
        correct_pattern: |
          // ✅ feature-specific reset writes through the slice's updater (atom-aware)
          table.resetSorting() // works whether sorting is internal or external
          // or, if you specifically want to clear the external atom:
          sortingAtom.set([])
        source:
          docs/framework/vanilla/guide/table-state.md:177-188; docs/framework/react/guide/table-state.md:317-328;
          packages/table-core/src/core/table/coreTablesFeature.utils.ts:42-65
        priority: HIGH
        status: active
        version_context: v9 alpha; the atom split makes `reset()` less safe than v8
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
      - mistake: API or state slice "missing" because the feature was not registered in `_features`
        mechanism:
          In v9, `_features` is a tree-shakeable registry. If a feature is not in `_features`, TypeScript
          hides its APIs and the runtime atom is not created. Agents who copy a snippet for `table.setColumnFilters(...)`
          without registering `columnFilteringFeature` see a TS error or `table.atoms.columnFilters` is undefined
          — and may incorrectly conclude the feature is broken or removed in v9.
        wrong_pattern: |-
          // ❌ rowSortingFeature missing — table.setSorting / state.sorting unavailable
          const _features = tableFeatures({}) // empty
          const table = useTable({ _features, _rowModels: {}, columns, data })
          table.setSorting([{ id: 'age', desc: true }]) // ❌ does not exist on this table type
        correct_pattern: |-
          // ✅ Register every feature you intend to use; pair with its row model when applicable
          const _features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
          const table = useTable({
            _features,
            _rowModels: {
              sortedRowModel: createSortedRowModel(sortFns),
              paginatedRowModel: createPaginatedRowModel(),
            },
            columns, data,
          })
        priority: CRITICAL
        version_context:
          v9-specific. This is the first version of TanStack Table where features must be declared
          for TypeScript and runtime to expose them. Expect heavy confusion from devs and agents trained on
          v8.
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
  - name: Customizing Feature Behavior
    slug: customizing-feature-behavior
    domain: core-foundations
    description:
      Override per-column `sortFn`, `filterFn`, `aggregationFn`, and table-level `globalFilterFn`
      — and chain filter→sort metadata via `addMeta`.
    type: core
    packages:
      - '@tanstack/table-core'
    covers:
      - filterFn
      - sortFn
      - aggregationFn
      - globalFilterFn
      - FilterFn
      - SortFn
      - AggregationFn
      - addMeta
      - autoRemove
      - resolveFilterValue
      - columnFiltersMeta
      - filterFns
      - sortFns
      - aggregationFns
      - FilterFnOption
      - SortFnOption
      - AggregationFnOption
      - BuiltInFilterFn
      - BuiltInSortFn
      - BuiltInAggregationFn
      - invertSorting
      - sortUndefined
      - sortDescFirst
    tasks:
      - Author a custom `filterFn` (e.g. fuzzy filter) and reference it by name from a column's `filterFn`
        option after registering it via `createFilteredRowModel({ ...filterFns, custom })`
      - 'Use the `addMeta` argument inside a `filterFn` to stash ranking info on the row, then read it from
        a custom `sortFn` via `row.columnFiltersMeta[columnId]` for filter→sort handoff (canonical: match-sorter-utils
        fuzzy)'
      - Pick a built-in `sortFn` by string name (`alphanumeric`, `text`, `datetime`, `basic`) for a column,
        then layer `invertSorting`/`sortDescFirst`/`sortUndefined` for direction control
      - Register a custom `aggregationFn` for a grouped column (e.g. weighted average) by passing it through
        `createGroupedRowModel({ ...aggregationFns, custom })`
    failure_modes:
      - mistake: References a custom filterFn by string without registering it
        mechanism:
          "String values for `filterFn` are looked up in `table._rowModelFns.filterFns`. If the custom
          fn is not passed to `createFilteredRowModel({ ...filterFns, custom: myFn })`, the lookup misses
          and `column_getFilterFn` logs `Could not find a valid 'column.filterFn' for column with the ID:
          X`. The column then falls back to a no-op and the filter silently fails."
        wrong_pattern: |
          // ❌ "fuzzy" string never registered
          const table = useTable({
            _features, columns: [
              columnHelper.accessor('fullName', { filterFn: 'fuzzy' }),
            ],
            _rowModels: {
              filteredRowModel: createFilteredRowModel(filterFns), // ❌ no fuzzy in here
            },
            data,
          })
        correct_pattern: |
          // ✅ register the custom fn AND module-augment for type safety
          declare module '@tanstack/react-table' {
            interface FilterFns {
              fuzzy: FilterFn<typeof _features, Person>
            }
          }

          const fuzzyFilter: FilterFn<typeof _features, Person> = (row, columnId, value, addMeta) => {
            const itemRank = rankItem(row.getValue(columnId), value)
            addMeta?.({ itemRank })
            return itemRank.passed
          }

          const table = useTable({
            _features,
            columns: [columnHelper.accessor('fullName', { filterFn: 'fuzzy' })],
            _rowModels: {
              filteredRowModel: createFilteredRowModel({ ...filterFns, fuzzy: fuzzyFilter }),
            },
            data,
          })
        source: examples/react/filters-fuzzy/src/main.tsx:37-80,117-127; packages/table-core/src/features/column-filtering/columnFilteringFeature.utils.ts:85-108
        priority: CRITICAL
        status: active
        version_context:
          v9 alpha; v9 made built-in fns into explicit arguments to row-model factories so
          unregistered string names fail loudly in dev but quietly in prod
      - mistake: Uses v8 `sortingFn` / `sortingFns` names in v9
        mechanism:
          'v9 renamed every sorting API: `sortingFn` → `sortFn`, `sortingFns` → `sortFns`, `SortingFn`
          type → `SortFn`, `column.getSortingFn()` → `column.getSortFn()`. The old names typecheck only if
          you accidentally pull from the legacy export and silently ignore your config.'
        wrong_pattern: |
          // ❌ v8 names — ignored in v9 column defs
          columnHelper.accessor('age', {
            sortingFn: 'alphanumeric',
          })
        correct_pattern: |
          // ✅ v9 names
          columnHelper.accessor('age', {
            sortFn: 'alphanumeric',
          })
        source: docs/framework/react/guide/migrating.md:877-908; packages/table-core/src/features/row-sorting/rowSortingFeature.types.ts:71-77
        priority: HIGH
        status: active
        version_context: v9 alpha; affects users upgrading from v8
      - mistake: Custom sortFn reads meta from a different column-filter id
        mechanism:
          '`row.columnFiltersMeta` is keyed by the column id that produced the meta (or `"__global__"`
          for the global filter). A sortFn must look up the SAME column id the filterFn used. The fuzzy filter→sort
          pattern only works when both reference the same column.'
        wrong_pattern: |
          // ❌ filter on 'fullName', sort reads meta from 'firstName'
          const fuzzySort: SortFn<typeof _features, Person> = (a, b, columnId) => {
            const meta = a.columnFiltersMeta['firstName'] // ❌ wrong key
            return meta ? compareItems(meta.itemRank, b.columnFiltersMeta['firstName'].itemRank) : 0
          }
          columnHelper.accessor('fullName', { filterFn: 'fuzzy', sortFn: fuzzySort })
        correct_pattern: |
          // ✅ sortFn uses the same columnId arg that the row's filterFn ran on
          const fuzzySort: SortFn<typeof _features, Person> = (rowA, rowB, columnId) => {
            let dir = 0
            if (rowA.columnFiltersMeta[columnId]) {
              dir = compareItems(
                rowA.columnFiltersMeta[columnId].itemRank!,
                rowB.columnFiltersMeta[columnId].itemRank!,
              )
            }
            return dir === 0 ? sortFns.alphanumeric(rowA, rowB, columnId) : dir
          }
        source:
          examples/react/filters-fuzzy/src/main.tsx:56-70; packages/table-core/src/features/column-filtering/createFilteredRowModel.ts:127-156
          (addMeta wiring)
        priority: HIGH
        status: active
        version_context: always present
      - mistake: Returns a complex value from accessor and uses a built-in sortFn
        mechanism:
          Built-in sortFns (`alphanumeric`, `text`, `basic`) coerce values via `toString()`/comparison
          operators. An accessor that returns `{first, last}` will compare `"[object Object]"` strings — every
          row ties and the original index ordering leaks through. The fix is to either return a primitive
          from the accessor OR supply a sortFn that handles the shape.
        wrong_pattern: |
          // ❌ accessor returns object; alphanumeric sort sees "[object Object]"
          columnHelper.accessor((row) => row.name, {
            id: 'name',
            sortFn: 'alphanumeric',
          })
        correct_pattern: |
          // ✅ Option A: return a primitive
          columnHelper.accessor((row) => `${row.name.first} ${row.name.last}`, {
            id: 'fullName',
            sortFn: 'alphanumeric',
          })
          // ✅ Option B: custom sortFn that knows the shape
          columnHelper.accessor((row) => row.name, {
            id: 'name',
            sortFn: (a, b, id) => {
              const av = a.getValue<{ first: string }>(id).first
              const bv = b.getValue<{ first: string }>(id).first
              return av === bv ? 0 : av > bv ? 1 : -1
            },
          })
        source: packages/table-core/src/fns/sortFns.ts:121-149; docs/guide/column-defs.md:231
        priority: MEDIUM
        status: active
        version_context: always present
        skills:
          - column-definitions
      - mistake: Confuses `aggregationFn` with `aggregatedCell`
        mechanism:
          '`aggregationFn` produces the value for a grouped row (e.g. sum, mean). `aggregatedCell`
          renders that value. New users put rendering logic inside `aggregationFn`, breaking re-renders and
          string output.'
        wrong_pattern: |
          // ❌ rendering JSX inside the aggregation function
          columnHelper.accessor('revenue', {
            aggregationFn: (id, leaves) => <b>${leaves.reduce((a, r) => a + r.getValue(id), 0)}</b>,
          })
        correct_pattern: |
          // ✅ aggregationFn returns a value; aggregatedCell renders it
          columnHelper.accessor('revenue', {
            aggregationFn: 'sum', // or a custom (id, leaves, children) => number
            aggregatedCell: (info) => <b>${info.getValue<number>().toLocaleString()}</b>,
          })
        source: packages/table-core/src/features/column-grouping/columnGroupingFeature.types.ts:53-78; packages/table-core/src/fns/aggregationFns.ts:1-242
        priority: MEDIUM
        status: active
        version_context: always present
  - slug: filtering
    type: core
    packages:
      - '@tanstack/table-core'
    domain: row-model-features
    description:
      Filter rows in TanStack Table v9 — column filters, a global filter, faceted facet values
      for filter UIs, and fuzzy ranking — using the `filteredRowModel` row-model pipeline stage.
    subsystems:
      - column-filtering
      - global-filtering
      - column-faceting
      - global-faceting
      - fuzzy-filtering
    covers:
      - columnFilteringFeature
      - globalFilteringFeature
      - columnFacetingFeature
      - createFilteredRowModel(filterFns)
      - createFacetedRowModel()
      - createFacetedUniqueValues()
      - createFacetedMinMaxValues()
      - state.columnFilters (ColumnFiltersState = Array<{ id, value }>)
      - state.globalFilter (any)
      - onColumnFiltersChange
      - onGlobalFilterChange
      - columnDef.filterFn (string name | function | "auto")
      - columnDef.enableColumnFilter
      - columnDef.enableGlobalFilter
      - manualFiltering
      - enableFilters
      - enableColumnFilters
      - enableGlobalFilter
      - globalFilterFn
      - filterFromLeafRows
      - maxLeafRowFilterDepth
      - getColumnCanGlobalFilter
      - getFacetedUniqueValues (server-side override)
      - getFacetedMinMaxValues (server-side override)
      - getGlobalFacetedUniqueValues (server-side override)
      - getGlobalFacetedMinMaxValues (server-side override)
      - table.setColumnFilters
      - table.resetColumnFilters
      - table.setGlobalFilter
      - table.resetGlobalFilter
      - table.getGlobalAutoFilterFn
      - table.getGlobalFilterFn
      - column.getFilterValue / setFilterValue / getCanFilter / getIsFiltered / getFilterIndex / getAutoFilterFn
        / getFilterFn
      - column.getCanGlobalFilter
      - column.getFacetedRowModel / getFacetedUniqueValues / getFacetedMinMaxValues
      - table.getGlobalFacetedRowModel / getGlobalFacetedUniqueValues / getGlobalFacetedMinMaxValues
      - filterFns built-in registry
      - filterFn.autoRemove
      - filterFn.resolveFilterValue
      - '@tanstack/match-sorter-utils (rankItem, compareItems, RankingInfo)'
      - row.columnFiltersMeta (FilterMeta extended via declare module)
      - addMeta callback (4th argument to FilterFn)
    tasks:
      - Wire up text/range/select per-column filters with debounced inputs (see examples/react/filters/src/main.tsx).
      - 'Add a faceted filter UI: autocomplete from `column.getFacetedUniqueValues()` and a range slider from
        `column.getFacetedMinMaxValues()` (requires `createFacetedRowModel()` PLUS the unique/minMax row models).'
      - Implement fuzzy global search with `@tanstack/match-sorter-utils` and a custom `fuzzySort` that reads
        `row.columnFiltersMeta[columnId].itemRank`.
      - 'Switch a table to manual server-side filtering: set `manualFiltering: true`, omit the `filteredRowModel`
        from `_rowModels`, and pass pre-filtered `data` from the server.'
      - 'Make a tree table filter sub-rows by enabling `filterFromLeafRows: true` so a parent stays visible
        whenever any child matches.'
    failure_modes:
      - mistake:
          Forgetting `createFacetedRowModel()` while still registering `createFacetedUniqueValues()`
          / `createFacetedMinMaxValues()`.
        mechanism: |
          `createFacetedUniqueValues` and `createFacetedMinMaxValues` both compute their results from `column.getFacetedRowModel().flatRows`. Without the base `facetedRowModel` factory in `_rowModels.facetedRowModel`, `column_getFacetedRowModel` falls back to `table.getPreFilteredRowModel()` (see column-faceting/columnFacetingFeature.utils.ts lines 44-56), so facet values are still computed but **don't exclude the column's own active filter** — meaning a select dropdown showing options for a column will collapse to only the currently selected value once the user picks one.
        wrong_pattern: |
          ```tsx
          const table = useTable({
            _features: tableFeatures({ columnFacetingFeature, columnFilteringFeature }),
            _rowModels: {
              filteredRowModel: createFilteredRowModel(filterFns),
              // BUG: missing facetedRowModel - the unique/minMax helpers will use
              // the pre-filtered model so they include every filter EXCEPT none
              facetedUniqueValues: createFacetedUniqueValues(),
              facetedMinMaxValues: createFacetedMinMaxValues(),
            },
            columns, data,
          })
          ```
        correct_pattern: |
          ```tsx
          // From examples/react/filters-faceted/src/main.tsx
          const table = useTable({
            _features: tableFeatures({
              columnFacetingFeature,
              columnFilteringFeature,
              rowPaginationFeature,
            }),
            _rowModels: {
              filteredRowModel: createFilteredRowModel(filterFns),
              paginatedRowModel: createPaginatedRowModel(),
              facetedRowModel: createFacetedRowModel(),       // REQUIRED base
              facetedMinMaxValues: createFacetedMinMaxValues(),
              facetedUniqueValues: createFacetedUniqueValues(),
            },
            columns, data,
          })
          ```
        source: packages/table-core/src/features/column-faceting/columnFacetingFeature.utils.ts
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - filtering
      - mistake:
          'Using `manualFiltering: true` without removing the `filteredRowModel` factory (works), or
          expecting `manualFiltering` to filter the row model anyway.'
        mechanism: |
          When `manualFiltering: true`, `table_getFilteredRowModel` short-circuits and returns `getPreFilteredRowModel()` (the core row model). The filter state still exists and `onColumnFiltersChange` still fires — but rows are NOT filtered client-side. Agents commonly add the filter UI, hook up `setFilterValue`, and forget to refetch server data, leaving filter UI changes invisible.
        wrong_pattern: |
          ```tsx
          // BUG: manualFiltering: true means the filteredRowModel is BYPASSED.
          // Filter state changes do nothing visible unless `data` is refetched.
          const table = useTable({
            _features: tableFeatures({ columnFilteringFeature }),
            _rowModels: {
              filteredRowModel: createFilteredRowModel(filterFns),
            },
            data,
            columns,
            manualFiltering: true,
            // ...but no useEffect to refetch when columnFilters changes
          })
          ```
        correct_pattern: |
          ```tsx
          // From docs/guide/column-filtering.md
          const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
          const { data } = useQuery(['rows', columnFilters], () =>
            fetch('/api/rows?' + serialize(columnFilters)).then(r => r.json())
          )
          const table = useTable({
            _features: tableFeatures({ columnFilteringFeature }),
            _rowModels: {}, // no filteredRowModel needed for manual filtering
            data,
            columns,
            manualFiltering: true,
            state: { columnFilters },
            onColumnFiltersChange: setColumnFilters,
          })
          ```
        source: packages/table-core/src/core/row-models/coreRowModelsFeature.utils.ts
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - filtering
      - mistake:
          'Custom fuzzy filter without merging into `filterFns`: passing only `{ fuzzy: fuzzyFilter
          }` to `createFilteredRowModel`, dropping the 10 built-in filters.'
        mechanism: |
          `createFilteredRowModel(filterFns)` accepts a `Record<keyof FilterFns, FilterFn>`. The argument is stored AS-IS at `table._rowModelFns.filterFns`, replacing the registry. If a developer writes `createFilteredRowModel({ fuzzy: fuzzyFilter })`, then any column with `filterFn: 'includesString'` will trigger `Could not find a valid 'column.filterFn' for column with the ID: ...` (warning at columnFilteringFeature.utils.ts:102) and the column won't filter.
        wrong_pattern: |
          ```tsx
          // BUG: drops the built-in registry
          filteredRowModel: createFilteredRowModel({
            fuzzy: fuzzyFilter,
          }),
          // Column with filterFn: 'includesString' now warns and never filters
          ```
        correct_pattern: |
          ```tsx
          // From examples/react/filters-fuzzy/src/main.tsx
          import { filterFns, sortFns } from '@tanstack/react-table'
          import { rankItem, compareItems } from '@tanstack/match-sorter-utils'

          declare module '@tanstack/react-table' {
            interface FilterFns { fuzzy: FilterFn<typeof _features, Person> }
            interface FilterMeta { itemRank?: RankingInfo }
          }

          const fuzzyFilter: FilterFn<typeof _features, Person> = (row, columnId, value, addMeta) => {
            const itemRank = rankItem(row.getValue(columnId), value)
            addMeta?.({ itemRank })
            return itemRank.passed
          }

          const table = useTable({
            _features,
            _rowModels: {
              filteredRowModel: createFilteredRowModel({
                ...filterFns,           // KEEP built-ins
                fuzzy: fuzzyFilter,     // ADD custom
              }),
              sortedRowModel: createSortedRowModel(sortFns),
            },
            globalFilterFn: 'fuzzy',
            columns, data,
          })
          ```
        source: examples/react/filters-fuzzy/src/main.tsx
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - filtering
          - sorting
      - mistake:
          Using `state.columnFilters` AND `initialState.columnFilters` at the same time (or same for
          globalFilter).
        mechanism: |
          When both are set, the controlled `state.columnFilters` value overrides the `initialState.columnFilters` on every render. The initial state is effectively ignored. This pattern usually signals confusion between controlled and uncontrolled state ownership — and developers often expect `initialState` to seed `state` on first render, which TanStack Table does NOT do.
        wrong_pattern: |
          ```tsx
          const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
          //                                                                       ^^ empty
          const table = useTable({
            _features, _rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
            columns, data,
            initialState: {
              columnFilters: [{ id: 'name', value: 'John' }], // IGNORED
            },
            state: { columnFilters }, // wins, starts empty
            onColumnFiltersChange: setColumnFilters,
          })
          ```
        correct_pattern: |
          ```tsx
          // Seed the controlled state at useState time, NOT in initialState.
          // From docs/guide/column-filtering.md
          const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([
            { id: 'name', value: 'John' }, // seeded here
          ])
          const table = useTable({
            _features, _rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
            columns, data,
            state: { columnFilters },
            onColumnFiltersChange: setColumnFilters,
          })
          ```
        source: docs/guide/column-filtering.md
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - filtering
      - mistake:
          Globally filtering on columns whose values aren't strings or numbers and getting silently-ignored
          search.
        mechanism: |
          `globalFilteringFeature` defaults `getColumnCanGlobalFilter` to a function that returns `typeof value === 'string' || typeof value === 'number'` from sampling the first row's cell value. Objects, arrays, booleans, dates, and undefined values fail this default check and the column is excluded from the global filter scan. There is no warning — the column just doesn't participate.
        wrong_pattern: |
          ```tsx
          // BUG: createdAt is a Date object — global filter silently skips it.
          const columns = [
            columnHelper.accessor('createdAt', { header: 'Created' }),
            columnHelper.accessor('name', { header: 'Name' }),
          ]
          // table.setGlobalFilter('2024') will never find Date rows
          ```
        correct_pattern: |
          ```tsx
          // Override getColumnCanGlobalFilter or set per-column.
          const table = useTable({
            _features: tableFeatures({ globalFilteringFeature }),
            _rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
            columns, data,
            globalFilterFn: 'includesString',
            getColumnCanGlobalFilter: (column) => true, // include every column
          })
          // Or per-column:
          columnHelper.accessor('createdAt', {
            header: 'Created',
            enableGlobalFilter: true,
          })
          ```
        source: packages/table-core/src/features/global-filtering/globalFilteringFeature.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - filtering
      - mistake: Expecting `filterFromLeafRows` to keep child rows visible when only the parent matches.
        mechanism: |
          `filterFromLeafRows: true` walks the tree bottom-up and keeps a parent if ANY descendant matches. The inverse — keeping all descendants when the parent matches — is the **default** root-down behavior (see filterRowsUtils.ts:103). The two modes are mutually exclusive. To preserve all sub-rows under a matching parent without checking children, use `maxLeafRowFilterDepth: 0` so only root-level rows are filtered.
        wrong_pattern: |
          ```tsx
          // BUG: filterFromLeafRows hides ALL children that don't match,
          // even though the parent does match.
          const table = useTable({
            _features: tableFeatures({ columnFilteringFeature, rowExpandingFeature }),
            _rowModels: { filteredRowModel: createFilteredRowModel(filterFns), expandedRowModel: createExpandedRowModel() },
            columns, data,
            getSubRows: r => r.subRows,
            filterFromLeafRows: true,
            // expectation: parent matches "John" -> all children visible
            // reality: only children that also match "John" stay visible
          })
          ```
        correct_pattern: |
          ```tsx
          // Keep parent's whole sub-tree when parent matches: filter root-only.
          const table = useTable({
            _features: tableFeatures({ columnFilteringFeature, rowExpandingFeature }),
            _rowModels: {
              filteredRowModel: createFilteredRowModel(filterFns),
              expandedRowModel: createExpandedRowModel(),
            },
            columns, data,
            getSubRows: r => r.subRows,
            maxLeafRowFilterDepth: 0, // only filter root-level rows
          })
          ```
        source: packages/table-core/src/features/column-filtering/filterRowsUtils.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - filtering
          - row-expanding
      - mistake: Column filter returns no matches when first row has null in that column
        mechanism: |
          The default `auto` filter type detects column type from the first row's value.
          If row 0 has `null`/`undefined` for the column, type detection picks the wrong
          filter and never matches.
        wrong_pattern: |
          // ❌ First row has null; column filter returns 0 results
          const data = [
            { id: 1, name: null },
            { id: 2, name: 'Alice' },
          ]
        correct_pattern: |
          // ✅ Explicitly set filterFn on the column instead of relying on auto
          columnHelper.accessor('name', {
            filterFn: 'includesString',  // or a custom fn
          })
        source:
          https://github.com/TanStack/table/issues/4711 (Column filter not working when first value
          in data is null), https://github.com/TanStack/table/issues/4919 (Filter not working if accessorFn
          returns null)
        priority: MEDIUM
        status: active
        version_context: v8 behavior
        skills:
          - filtering
          - column-definitions
      - mistake: getFilteredRowModel retains memory after filter removal
        mechanism: |
          Heap snapshots show `PerformanceMeasure`, `FiberNode`, and `Error` objects
          accumulating across filter-apply/remove cycles. The internal caching mechanism
          in `getFilteredRowModel` doesn't release filtered row arrays even after filter
          state is cleared.
        wrong_pattern: |
          // ❌ Memory grows with each filter toggle
          const table = useReactTable({
            data, columns,
            getCoreRowModel: getCoreRowModel(),
            getFilteredRowModel: getFilteredRowModel(),
          })
        correct_pattern: |
          // ✅ Manual client-side filter as workaround
          const filteredData = useMemo(() => {
            if (!columnFilters.length) return data
            return data.filter(row =>
              columnFilters.every(f => /* manual matching */ true)
            )
          }, [data, columnFilters])
          const table = useReactTable({ data: filteredData, columns, getCoreRowModel: getCoreRowModel() })
        source:
          https://github.com/TanStack/table/issues/6170 (Memory leak in getFilteredRowModel - heap not
          released after filter removal)
        priority: MEDIUM
        status: active
        version_context: v8.21.3 — relevant for long-running apps; v9 row-model API may behave differently
        skills:
          - filtering
          - production-readiness
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    reference_candidates:
      - name: built-in filterFns
        kind: function-registry
        count: 12
        source: packages/table-core/src/fns/filterFns.ts
        documented_in_guide:
          - includesString
          - includesStringSensitive
          - equalsString
          - equalsStringSensitive
          - arrIncludes
          - arrIncludesAll
          - arrIncludesSome
          - equals
          - weakEquals
          - inNumberRange
        also_exported:
          - arrHas
          - between
          - betweenInclusive
          - greaterThan
          - greaterThanOrEqualTo
          - lessThan
          - lessThanOrEqualTo
        note:
          "Docs list the built-in filterFn registry but the registry actually exports 12 (adds `arrHas`,
          `between`, `betweenInclusive`). `greaterThan`, `greaterThanOrEqualTo`, `lessThan`, `lessThanOrEqualTo`
          are NOT included in the registry export but are used by the range filters. Expanding example uses
          `filterFn: 'between'` — which IS in the registry."
    gaps:
      - Docs say the built-in filterFn registry but the actual `filterFns` registry exports 12. Need authoritative
        reference for the full set.
      - '`column.getCanGlobalFilter` returns `false` for columns with first-row non-string/non-number values;
        this is the SILENT failure case. Worth a dedicated reference table for which value types pass auto-detection.'
      - "`addMeta` is optional in the FilterFn signature — fuzzy example uses `addMeta?.()`. Need clear rule
        for when meta is/isn't passed (it IS passed by `createFilteredRowModel`)."
      - No documented invariant on what happens when `filterFn` resolves to undefined; the warning is dev-mode
        only and the column silently uses no filter.
  - slug: sorting
    type: core
    packages:
      - '@tanstack/table-core'
    domain: row-model-features
    description:
      Sort rows in TanStack Table v9 with the `sortedRowModel` stage — built-in sortFns, custom
      sortFns, multi-sort, sortUndefined placement, invertSorting for "lower-is-better" scales, and manual
      server-side sorting.
    covers:
      - rowSortingFeature
      - createSortedRowModel(sortFns)
      - state.sorting (SortingState = Array<{ id, desc }>)
      - onSortingChange
      - 'columnDef.sortFn (string | function | "auto")  # v9 renamed from sortingFn'
      - columnDef.sortDescFirst
      - columnDef.sortUndefined (false | -1 | 1 | "first" | "last")
      - columnDef.invertSorting
      - columnDef.enableSorting
      - columnDef.enableMultiSort
      - manualSorting
      - enableSorting
      - enableSortingRemoval
      - enableMultiSort
      - enableMultiRemove
      - maxMultiSortColCount
      - isMultiSortEvent
      - sortDescFirst
      - table.setSorting
      - table.resetSorting
      - column.getCanSort / getIsSorted / getSortIndex / getCanMultiSort / clearSorting
      - column.getToggleSortingHandler / toggleSorting
      - column.getFirstSortDir / getNextSortingOrder / getAutoSortDir / getAutoSortFn / getSortFn
      - 'sortFns built-in registry  # v9 renamed from sortingFns'
    tasks:
      - Add clickable column-header sorting with multi-sort on Shift+click (see examples/react/sorting/src/main.tsx).
      - 'Wire a column-specific custom `sortFn` for an enum (e.g. status: single < complicated < relationship).'
      - "Sort nullable values with explicit placement using `sortUndefined: 'last'` so undefined never confuses
        the auto sortFn picker."
      - "Use `invertSorting: true` on a `rank` column so 1st ranks above 2nd even when the user clicks 'descending'."
      - 'Switch to server-side sorting: `manualSorting: true`, omit `sortedRowModel`, mirror `state.sorting`
        to the fetch URL.'
    failure_modes:
      - mistake: Using v8's `sortingFn` / `sortingFns` after upgrading to v9.
        mechanism: |
          v9 renamed `columnDef.sortingFn` -> `columnDef.sortFn`, `tableOptions.sortingFns` -> `tableOptions.sortFns`, and the exported registry from `sortingFns` -> `sortFns`. The new column option `sortFn` defaults to `'auto'` and looks up `column.table._rowModelFns.sortFns` (see rowSortingFeature.utils.ts:160-173). A column with the v8 `sortingFn: 'alphanumeric'` will silently fall through to `sortFn_basic` (via the `?? sortFn_basic` fallback at line 172).
        wrong_pattern: |
          ```tsx
          // v8-style column def — works without type error if `as any`, sorts wrong
          {
            accessorKey: 'fullName',
            sortingFn: 'alphanumeric', // v8 name
          }
          // useTable({ sortingFns: { ...sortingFns, myFn } }) // v8 option name
          ```
        correct_pattern: |
          ```tsx
          // v9 names. From examples/react/sorting/src/main.tsx
          import { sortFns, createSortedRowModel } from '@tanstack/react-table'

          columnHelper.accessor('firstName', {
            sortFn: 'alphanumeric',   // v9 name
          })

          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: {
              sortedRowModel: createSortedRowModel({   // pass registry here
                ...sortFns,
                myCustom: (a, b, id) => a.original[id] - b.original[id],
              }),
            },
            columns, data,
          })
          ```
        source: packages/table-core/src/features/row-sorting/rowSortingFeature.utils.ts
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - sorting
      - mistake: "Expecting `sortUndefined: 'first' | 'last'` to work in v8 (they only exist in v9)."
        mechanism: |
          v8 only had `sortUndefined: false | -1 | 1`. v9 added the `'first'` and `'last'` literal aliases. The createSortedRowModel switch at lines 100-110 has explicit branches: `if (sortUndefined === 'first') return aUndefined ? -1 : 1`. With `1` (the v9 default), undefined sorts ascending toward the END (lower priority); with `-1`, it sorts toward the START. The semantic difference: numeric `1`/`-1` flip when `desc: true`; `'first'`/`'last'` are absolute.
        wrong_pattern: |
          ```tsx
          // BUG: agent assumes 'first' = ascending-start. But with desc: true,
          // numeric 1 flips to "first" anyway. The literal forms are ABSOLUTE.
          { accessorKey: 'lastName', sortUndefined: -1 } // ascending-first, descending-LAST
          ```
        correct_pattern: |
          ```tsx
          // From examples/react/sorting/src/main.tsx
          columnHelper.accessor((row) => row.lastName, {
            id: 'lastName',
            sortUndefined: 'last',     // ABSOLUTE: always at end regardless of asc/desc
            sortDescFirst: false,      // nullable values can mess up auto detection
          }),
          ```
        source: packages/table-core/src/features/row-sorting/createSortedRowModel.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - sorting
      - mistake: Custom `sortFn` returns `desc`-aware values (i.e. negating inside the function).
        mechanism: |
          From sorting.md: "The comparison function does not need to take whether or not the column is in descending or ascending order into account. The row models will take of that logic." `createSortedRowModel` multiplies the return by `-1` when `isDesc`, then again by `-1` if `invertSorting` is true (lines 119-126). A custom sortFn that returns -1 for "A before B" when descending will get doubly-flipped.
        wrong_pattern: |
          ```tsx
          // BUG: takes sort direction into account, breaks toggle
          const customSort: SortFn<any, any> = (a, b, id, desc) => {
            // desc isn't even a parameter — but agents try to detect via state
            const cmp = a.original[id] - b.original[id]
            return desc ? -cmp : cmp
          }
          ```
        correct_pattern: |
          ```tsx
          // From examples/react/sorting/src/main.tsx
          // Always return ascending-order comparison; the row model handles desc.
          const sortStatusFn: SortFn<any, any> = (rowA, rowB, _columnId) => {
            const statusOrder = ['single', 'complicated', 'relationship']
            return statusOrder.indexOf(rowA.original.status) -
                   statusOrder.indexOf(rowB.original.status)
          }
          ```
        source: packages/table-core/src/features/row-sorting/createSortedRowModel.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - sorting
      - mistake:
          Using fuzzy filter on a column but not pairing it with a fuzzy-aware sortFn that reads `itemRank`
          from `columnFiltersMeta`.
        mechanism: |
          The fuzzy filter writes `{ itemRank }` into `row.columnFiltersMeta[columnId]` via the `addMeta` callback (see createFilteredRowModel.ts lines 132-136). To rank results by match quality, a custom sortFn must read this meta and call `compareItems` from `@tanstack/match-sorter-utils`. If the column uses `sortFn: 'alphanumeric'` (the default), rows are sorted alphabetically, NOT by closest match — defeating the whole point of fuzzy search.
        wrong_pattern: |
          ```tsx
          columnHelper.accessor(...{
            filterFn: 'fuzzy',
            // BUG: missing sortFn — rows sort alphabetically, not by rank
          })
          ```
        correct_pattern: |
          ```tsx
          // From examples/react/filters-fuzzy/src/main.tsx
          import { compareItems } from '@tanstack/match-sorter-utils'
          import { sortFns } from '@tanstack/react-table'

          const fuzzySort: SortFn<typeof _features, Person> = (rowA, rowB, columnId) => {
            let dir = 0
            if (rowA.columnFiltersMeta[columnId]) {
              dir = compareItems(
                rowA.columnFiltersMeta[columnId].itemRank!,
                rowB.columnFiltersMeta[columnId].itemRank!,
              )
            }
            return dir === 0 ? sortFns.alphanumeric(rowA, rowB, columnId) : dir
          }

          columnHelper.accessor(..., {
            filterFn: 'fuzzy',
            sortFn: fuzzySort,
          })
          ```
        source: examples/react/filters-fuzzy/src/main.tsx
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - sorting
          - filtering
      - mistake: getCanSort returns false with manualSorting when no accessor is set
        mechanism: |
          `getCanSort` checks for `accessorKey`/`accessorFn` even when `manualSorting: true`,
          so display columns (no accessor) can't be sorted server-side. Users with virtual
          "actions" columns or computed display-only columns hit this immediately.
        wrong_pattern: |
          // ❌ getCanSort() returns false even though manualSorting is true
          const table = useReactTable({
            manualSorting: true,
            columns: [
              { id: 'computed', header: 'Computed', cell: (info) => row.x + row.y },
            ],
            ...
          })
        correct_pattern: |
          // ✅ Provide an accessorFn even if value is unused, OR force enableSorting on the column
          columnHelper.display({
            id: 'computed',
            header: 'Computed',
            enableSorting: true,  // force-enable for manualSorting
            cell: (info) => info.row.original.x + info.row.original.y,
          })
        source:
          https://github.com/TanStack/table/issues/4136 (getCanSort returning false when manualSorting
          enabled, 14 comments)
        priority: MEDIUM
        status: active
        version_context: v8 / v9
      - mistake: Manual sorting bounces ascending→false→ascending when values tie on current page
        mechanism: |
          With `manualSorting: true`, when sort state cycles through
          asc → desc → unsorted, the table compares `row.original` references for
          determinism. If all visible values are equal (e.g. all empty strings), the
          "desc" stage produces the same order as "asc" and looks like the sort isn't
          changing — users see asc → unsorted → asc.
        wrong_pattern: |
          // ❌ User-visible: clicking sort goes asc → unsorted → asc when values tie
          const table = useReactTable({ manualSorting: true, ... })
        correct_pattern: |
          // ✅ Add a secondary stable tiebreaker server-side, and surface the actual sort
          //    direction from server-controlled state to the UI rather than relying on
          //    table.getState().sorting alone.
        source:
          https://github.com/TanStack/table/issues/5147 (Sorting direction not updating properly with
          manual sorting, 10 comments)
        priority: MEDIUM
        status: active
        version_context: v8 manual sorting
        skills:
          - sorting
          - client-to-server
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    reference_candidates:
      - name: built-in sortFns
        kind: function-registry
        count: 6
        source: packages/table-core/src/fns/sortFns.ts
        entries:
          - alphanumeric
          - alphanumericCaseSensitive
          - text
          - textCaseSensitive
          - datetime
          - basic
        note:
          'Default fallback when no sortFn matches is `sortFn_basic` (see rowSortingFeature.utils.ts:172).
          `auto` infers from sampled values: date -> datetime, mixed alphanumeric -> alphanumeric, string
          -> text, else basic.'
    gaps:
      - '`column_getAutoSortFn` samples `firstRows = getFilteredRowModel().flatRows.slice(10)` — this is `.slice(10)`,
        NOT `.slice(0, 10)`! It skips the first 10 rows and uses everything after. Likely a bug; verify with
        maintainer.'
      - "`getSelectedRowModel`, `getFilteredSelectedRowModel`, and `getGroupedSelectedRowModel` in rowSelectionFeature.utils.ts
        ALL currently call `selectRowsFn(rowModel)` against `table.getCoreRowModel()` — they appear identical.
        Either they're stubs awaiting wiring or the dispatch is missing. Worth flagging."
  - slug: pagination
    type: core
    packages:
      - '@tanstack/table-core'
    domain: row-model-features
    description:
      Paginate rows in TanStack Table v9 with the `paginatedRowModel` stage — page navigation
      APIs, total row/page count, automatic page reset on data changes, and manual server-side pagination.
    covers:
      - rowPaginationFeature
      - createPaginatedRowModel()
      - 'state.pagination ({ pageIndex, pageSize })  # defaults: { pageIndex: 0, pageSize: 10 }'
      - onPaginationChange
      - manualPagination
      - pageCount
      - rowCount
      - autoResetPageIndex
      - paginateExpandedRows
      - table.setPagination / resetPagination
      - table.setPageIndex / resetPageIndex
      - table.setPageSize / resetPageSize
      - table.nextPage / previousPage / firstPage / lastPage
      - table.getCanNextPage / getCanPreviousPage
      - table.getPageCount / getRowCount / getPageOptions
      - table.getPaginatedRowModel / getPrePaginatedRowModel
    tasks:
      - Add a pagination toolbar with `<<`, `<`, `>`, `>>` buttons, current page indicator, page size selector,
        and 'go to page' input (see examples/react/pagination/src/main.tsx).
      - 'Switch to server-side pagination: `manualPagination: true`, supply `rowCount` (or `pageCount`) from
        the server, omit `paginatedRowModel`, refetch when `state.pagination` changes.'
      - 'Stop the automatic page-index reset when filters change: `autoResetPageIndex: false` (e.g., to keep
        page 3 visible while a user types into a search box).'
      - 'Display total filtered rows even when paginated: `table.getPrePaginatedRowModel().rows.length` (see
        filters example).'
    failure_modes:
      - mistake: 'Setting `manualPagination: true` without supplying `rowCount` (or `pageCount`).'
        mechanism: |
          With `manualPagination` set, `table_getPageCount` returns `options.pageCount ?? Math.ceil(getRowCount() / pageSize)`. `table_getRowCount` returns `options.rowCount ?? getPrePaginatedRowModel().rows.length`. In manual mode, the pre-paginated row model contains only the CURRENT page's rows — so `getRowCount()` becomes the page size (e.g., 10), `getPageCount()` becomes 1, and `getCanNextPage()` returns `false`. Pagination is effectively broken.
        wrong_pattern: |
          ```tsx
          // BUG: getPageCount returns 1, next/prev buttons are disabled
          const table = useTable({
            _features: tableFeatures({ rowPaginationFeature }),
            _rowModels: {},
            data, // only 10 rows for the current page
            columns,
            manualPagination: true,
            state: { pagination },
            onPaginationChange: setPagination,
            // missing: rowCount or pageCount
          })
          ```
        correct_pattern: |
          ```tsx
          // From docs/guide/pagination.md
          const { data: dataQuery } = useQuery(['rows', pagination], () =>
            fetchPage(pagination.pageIndex, pagination.pageSize),
          )
          const table = useTable({
            _features: tableFeatures({ rowPaginationFeature }),
            _rowModels: {},
            data: dataQuery.rows,
            columns,
            manualPagination: true,
            rowCount: dataQuery.rowCount, // server tells the table the total
            // OR: pageCount: dataQuery.pageCount
            // OR: pageCount: -1 if unknown (next button always enabled)
            state: { pagination },
            onPaginationChange: setPagination,
          })
          ```
        source: packages/table-core/src/features/row-pagination/rowPaginationFeature.utils.ts
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - pagination
      - mistake: Putting `pagination` in BOTH `state.pagination` and `initialState.pagination`.
        mechanism: |
          When both are set, the controlled `state.pagination` wins on every render. `initialState.pagination` is ignored. Agents often see "my pageSize default isn't working" because they wrote `useState({ pageIndex: 0, pageSize: 10 })` AND `initialState: { pagination: { pageSize: 25 } }`. The pageSize stays at 10.
        wrong_pattern: |
          ```tsx
          // BUG: initialState ignored.
          const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })
          const table = useTable({
            initialState: { pagination: { pageSize: 25 } }, // IGNORED
            state: { pagination },                          // wins (pageSize 10)
            onPaginationChange: setPagination,
            // ...
          })
          ```
        correct_pattern: |
          ```tsx
          // Seed in useState OR use initialState only — never both.
          const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 25 })
          const table = useTable({
            _features: tableFeatures({ rowPaginationFeature }),
            _rowModels: { paginatedRowModel: createPaginatedRowModel() },
            columns, data,
            state: { pagination },
            onPaginationChange: setPagination,
          })
          ```
        source: docs/guide/pagination.md
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - pagination
      - mistake:
          'Disabling `autoResetPageIndex: false` and forgetting to clamp `pageIndex` when the data
          shrinks below the current page.'
        mechanism: |
          `autoResetPageIndex` defaults to `!manualPagination` (so true client-side, false manual). When false and data changes, `pageIndex` stays put. `table_setPageIndex` only clamps against `options.pageCount` (max safe int when pageCount is unset/-1, see rowPaginationFeature.utils.ts:123-129) — it does NOT clamp against the current row model. Result: user sees an empty page after a destructive filter.
        wrong_pattern: |
          ```tsx
          const table = useTable({
            _features, _rowModels: { paginatedRowModel: createPaginatedRowModel(), filteredRowModel: createFilteredRowModel(filterFns) },
            columns, data,
            autoResetPageIndex: false, // user on page 5, then filters down to 2 pages
            // -> page 5 is empty. No automatic clamp.
          })
          ```
        correct_pattern: |
          ```tsx
          // Either leave autoResetPageIndex at default (true)...
          const table = useTable({ /* ... */ }) // autoResetPageIndex undefined = on

          // ...or clamp manually after any data-altering effect:
          useEffect(() => {
            const lastPage = Math.max(0, table.getPageCount() - 1)
            if (table.atoms.pagination.get().pageIndex > lastPage) {
              table.setPageIndex(lastPage)
            }
          }, [data, columnFilters])
          ```
        source: packages/table-core/src/features/row-pagination/rowPaginationFeature.utils.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - pagination
      - mistake:
          Computing `getRowCount()` and expecting it to match `data.length` when grouping/filtering/expansion
          is active.
        mechanism: |
          `table_getRowCount` returns `options.rowCount ?? getPrePaginatedRowModel().rows.length`. The pre-paginated row model is the END of the pipeline before the page slice — so it reflects filtering, grouping, sorting, AND expansion. With `paginateExpandedRows: false`, expanded children are NOT in `getPrePaginatedRowModel().rows` (they're appended to the parent's page in `createPaginatedRowModel`'s expandRows call). With `paginateExpandedRows: true` (default), they ARE counted as their own paginated rows.
        wrong_pattern: |
          ```tsx
          // BUG: agent expects getRowCount() === data.length
          console.log(table.getRowCount())       // count after all transforms
          console.log(data.length)               // count of raw input
          // These will diverge under filtering, grouping, OR a flat input != tree input.
          ```
        correct_pattern: |
          ```tsx
          // Use the right model for the question being asked.
          table.getCoreRowModel().rows.length        // raw row count (flat)
          table.getPreFilteredRowModel().rows.length // before filtering
          table.getFilteredRowModel().rows.length    // after filtering
          table.getRowCount()                        // pre-paginated count (server count if rowCount option set)
          table.getRowModel().rows.length            // current page only
          ```
        source: docs/guide/row-models.md
        priority: low
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - pagination
          - filtering
          - grouping
      - mistake: getToggleAllRowsSelected behaves differently with server pagination + getRowId
        mechanism: |
          With server-side pagination, you must supply `getRowId` (so selections survive
          page changes). But once `getRowId` is set, `getToggleAllRowsSelectedHandler` only
          selects the current page's rows (because the table only knows about current-page
          rows — it can't enumerate all server-side rows). Users expect "select all" to
          mean truly all, identical to client-side mode.
        wrong_pattern: |
          // ❌ Mismatched expectations — header checkbox only affects current page
          <input
            checked={table.getIsAllRowsSelected()}
            onChange={table.getToggleAllRowsSelectedHandler()}
          />
        correct_pattern: |
          // ✅ Use page-aware APIs explicitly with server pagination
          <input
            checked={table.getIsAllPageRowsSelected()}
            onChange={table.getToggleAllPageRowsSelectedHandler()}
          />
          // For "select all server-side rows", implement an explicit out-of-band
          // selection mode — track a boolean "all rows mode" alongside the row map.
        source: https://github.com/TanStack/table/issues/4781 (Pagination and Row Selection, 10 comments)
        priority: HIGH
        status: active
        version_context:
          Fundamental UX consequence of server pagination; not a bug but a recurring confusion
          point
        skills:
          - pagination
          - row-selection
          - client-to-server
      - mistake: autoResetPageIndex resets to initialState.pageIndex instead of 0
        mechanism: |
          `_autoResetPageIndex` calls `table.resetPageIndex()` without `true`, so when data
          shrinks (e.g. after applying a filter) the page resets to whatever
          `initialState.pagination.pageIndex` was — typically a deep-linked page restored
          from a URL — leaving the user on an invalid page.
        wrong_pattern: |
          // ❌ Filtering data resets to the deep-linked pageIndex, not 0
          const table = useReactTable({
            data, columns,
            initialState: { pagination: { pageIndex: 5, pageSize: 10 } },
            autoResetPageIndex: true,
            ...
          })
        correct_pattern: |
          // ✅ Explicitly reset to 0 when filters change
          useEffect(() => {
            table.setPageIndex(0)
          }, [columnFilters, globalFilter])
          // Or: don't rely on autoResetPageIndex when deep-linking pageIndex
        source:
          https://github.com/TanStack/table/issues/6207 (autoResetPageIndex resets to initialState pageIndex
          instead of 0)
        priority: MEDIUM
        status: active
        version_context: v8.21.3 bug, likely inherited in v9 alpha
        skills:
          - pagination
          - state-management
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    reference_candidates: []
    gaps:
      - '`autoResetPageIndex` is silently `false` when `manualPagination` is true (see rowPaginationFeature.utils.ts:43-50).
        This is documented but easy to miss. Worth a dedicated note.'
  - slug: grouping
    type: core
    packages:
      - '@tanstack/table-core'
    domain: row-model-features
    description:
      Group rows by column values in TanStack Table v9 with the `groupedRowModel` stage — the
      built-in aggregationFn registry, custom aggregations, grouped-column placement modes, manual server-side
      grouping, and expand-grouped-rows interaction with the expanding feature.
    covers:
      - columnGroupingFeature
      - createGroupedRowModel(aggregationFns)
      - state.grouping (GroupingState = Array<string>)
      - onGroupingChange
      - columnDef.aggregationFn ("auto" | name | function)
      - columnDef.aggregatedCell
      - columnDef.getGroupingValue
      - columnDef.enableGrouping
      - manualGrouping
      - enableGrouping
      - 'groupedColumnMode (false | "reorder" | "remove")  # default "reorder"'
      - table.setGrouping / resetGrouping
      - column.toggleGrouping / getCanGroup / getIsGrouped / getGroupedIndex
      - column.getToggleGroupingHandler
      - column.getAggregationFn / getAutoAggregationFn
      - cell.getIsGrouped / getIsAggregated / getIsPlaceholder
      - row.getIsGrouped / getGroupingValue / groupingColumnId / groupingValue / leafRows
      - aggregationFns built-in registry (8 fns)
    tasks:
      - Add per-column 'group' toggles in headers and render grouped cells with subRow counts + expand icons
        (see examples/react/grouping/src/main.tsx).
      - 'Mix aggregation strategies across columns: `sum` for visits, `median` for age, `mean` for progress,
        `count` for the implicit grouping column.'
      - "Override a column's grouping key with `getGroupingValue: row => ${row.firstName} ${row.lastName}`
        so rows group on a derived value, not the column accessor value."
      - 'Pair grouping with expanding so users can drill into each group: register `rowExpandingFeature` +
        `expandedRowModel` and call `row.getToggleExpandedHandler()` on grouped cells.'
      - "Hide grouped columns from the visible column flow with `groupedColumnMode: 'remove'`, or leave
        them in place with `groupedColumnMode: false`."
    failure_modes:
      - mistake:
          Adding `columnGroupingFeature` without also registering `rowExpandingFeature` and expecting
          grouped rows to expand.
        mechanism: |
          `createGroupedRowModel` produces grouped rows with `subRows`, but those rows aren't VISIBLE until the expanded row model flattens them in. Without `rowExpandingFeature` + `createExpandedRowModel()`, `row.getToggleExpandedHandler` doesn't exist (TypeScript error). Even if you skip the handler, the grouped row is collapsed by default and there's no way to drill down. Aggregated cells appear but child rows are unreachable.
        wrong_pattern: |
          ```tsx
          // BUG: grouped rows show aggregates but can't be expanded.
          const _features = tableFeatures({ columnGroupingFeature })
          const table = useTable({
            _features,
            _rowModels: { groupedRowModel: createGroupedRowModel(aggregationFns) },
            columns, data,
          })
          // row.getToggleExpandedHandler() -> TS error or undefined
          ```
        correct_pattern: |
          ```tsx
          // From examples/react/grouping/src/main.tsx
          import {
            aggregationFns,
            columnGroupingFeature,
            createExpandedRowModel,
            createGroupedRowModel,
            rowExpandingFeature,
          } from '@tanstack/react-table'

          const _features = tableFeatures({
            columnGroupingFeature,
            rowExpandingFeature,
            rowPaginationFeature,
            rowSortingFeature,
            columnFilteringFeature,
          })

          const table = useTable({
            _features,
            _rowModels: {
              groupedRowModel: createGroupedRowModel(aggregationFns),
              expandedRowModel: createExpandedRowModel(),
              // + sorted, filtered, paginated as needed
            },
            columns, data,
          })

          // In cell renderer:
          {cell.getIsGrouped() && (
            <button onClick={row.getToggleExpandedHandler()}>
              {row.getIsExpanded() ? '👇' : '👉'} ({row.subRows.length})
            </button>
          )}
          ```
        source: examples/react/grouping/src/main.tsx
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - grouping
          - row-expanding
      - mistake:
          Customizing `aggregationFns` like the v8 `aggregationFns` option (passing the registry through
          `tableOptions.aggregationFns` instead of `createGroupedRowModel`).
        mechanism: |
          In v9, the aggregation function registry is passed as the first argument to `createGroupedRowModel(aggregationFns)`, which stores it at `table._rowModelFns.aggregationFns`. There is NO top-level `tableOptions.aggregationFns` like sorting/filtering have via row model factory. Agents migrating from v8 commonly try `useTable({ aggregationFns: { ... } })` and it has no effect; columns with custom `aggregationFn: 'myCustom'` resolve to `undefined`.
        wrong_pattern: |
          ```tsx
          // BUG: v8-style option that doesn't exist in v9
          const table = useTable({
            _features: tableFeatures({ columnGroupingFeature }),
            _rowModels: { groupedRowModel: createGroupedRowModel(aggregationFns) },
            columns, data,
            // @ts-ignore - this property doesn't exist on TableOptions in v9
            aggregationFns: {
              myCustom: (id, leaf, child) => /* ... */,
            },
          })
          ```
        correct_pattern: |
          ```tsx
          // From docs/guide/grouping.md - register via createGroupedRowModel
          import { aggregationFns, createGroupedRowModel } from '@tanstack/react-table'

          const table = useTable({
            _features: tableFeatures({ columnGroupingFeature, rowExpandingFeature }),
            _rowModels: {
              groupedRowModel: createGroupedRowModel({
                ...aggregationFns,
                myCustomAggregation: (columnId, leafRows, childRows) => {
                  return /* aggregated value */
                },
              }),
              expandedRowModel: createExpandedRowModel(),
            },
            columns, data,
          })

          // Then on a column:
          { accessorKey: 'sales', aggregationFn: 'myCustomAggregation' }
          ```
        source: packages/table-core/src/features/column-grouping/createGroupedRowModel.ts
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - grouping
      - mistake: 'Confusing `aggregationFn` signature: `(columnId, leafRows, childRows)` vs filter/sort signatures.'
        mechanism: |
          Aggregation functions have a DIFFERENT signature than filterFns and sortFns. They receive `(columnId: string, leafRows: Array<Row>, childRows: Array<Row>)`. `leafRows` = ALL descendant non-grouped rows (recursive flatten). `childRows` = immediate children of the current grouped row (which may themselves be grouped sub-aggregates at deeper levels). Built-ins use `childRows` (sum, min, max, extent) for nested aggregation reuse, but `leafRows` (mean, median, unique, uniqueCount, count) when the math requires raw values.
        wrong_pattern: |
          ```tsx
          // BUG: wrong arg names - first arg is columnId, not row
          aggregationFn: (rowA, rowB, columnId) => /* ... */
          // BUG: averaging via childRows includes already-aggregated sub-group sums
          aggregationFn: (id, leaf, child) => child.reduce((a, r) => a + r.getValue(id), 0) / child.length
          ```
        correct_pattern: |
          ```tsx
          // From packages/table-core/src/fns/aggregationFns.ts
          // For pure leaf averages, use leafRows:
          const aggregationFn_mean: AggregationFn<any, any> = (columnId, leafRows) => {
            let count = 0, sum = 0
            leafRows.forEach((row) => {
              const value = row.getValue(columnId)
              if (typeof value === 'number') { count++; sum += value }
            })
            return count ? sum / count : undefined
          }

          // For nestable sums (reuse sub-aggregates), use childRows:
          const aggregationFn_sum: AggregationFn<any, any> = (columnId, _leafRows, childRows) => {
            return childRows.reduce((acc, next) => {
              const v = next.getValue(columnId)
              return acc + (typeof v === 'number' ? v : 0)
            }, 0)
          }
          ```
        source: packages/table-core/src/fns/aggregationFns.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - grouping
      - mistake:
          "Expecting grouped columns to appear in their original position — and missing the default
          `groupedColumnMode: 'reorder'`."
        mechanism: |
          `columnGroupingFeature.getDefaultTableOptions` sets `groupedColumnMode: 'reorder'`. When grouping is active, the column ordering function in `columnOrderingFeature.utils.ts::orderColumns` moves grouped columns to the START of the leaf-column list. Agents who manually set `columnOrder` and group by 'status' will see 'status' jump to position 0 with no warning. Set `groupedColumnMode: false` to disable this, or `'remove'` to drop grouped columns from the visible flow entirely.
        wrong_pattern: |
          ```tsx
          // BUG: column order is overridden by reorder mode
          const table = useTable({
            _features,
            _rowModels: { groupedRowModel: createGroupedRowModel(aggregationFns) },
            columns, data,
            initialState: {
              columnOrder: ['firstName', 'lastName', 'age', 'status'], // explicit
              grouping: ['status'],
            },
            // status jumps to position 0, columnOrder is "overridden"
          })
          ```
        correct_pattern: |
          ```tsx
          const table = useTable({
            _features,
            _rowModels: { groupedRowModel: createGroupedRowModel(aggregationFns) },
            columns, data,
            initialState: {
              columnOrder: ['firstName', 'lastName', 'age', 'status'],
              grouping: ['status'],
            },
            groupedColumnMode: false, // keep columnOrder intact
          })

          // Or accept the reorder and let grouped columns lead:
          groupedColumnMode: 'reorder', // (default)

          // Or hide grouped columns entirely:
          groupedColumnMode: 'remove',
          ```
        source: packages/table-core/src/features/column-ordering/columnOrderingFeature.utils.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - grouping
          - column-ordering
      - mistake: Calling `getSelectedRowModel()` on a grouped table and expecting it to include grouped rows.
        mechanism: |
          Three selected-row APIs exist: `table.getSelectedRowModel()` (built off core), `table.getFilteredSelectedRowModel()` (built off filtered), `table.getGroupedSelectedRowModel()` (built off grouped). They are distinct in the type system. Agents commonly want "selected rows that are currently visible after grouping" and call the wrong one — `getSelectedRowModel()` walks the core (flat) row model and won't reflect grouping changes.
        wrong_pattern: |
          ```tsx
          // BUG: returns selection from core model, not the grouped projection
          const selectedRows = table.getSelectedRowModel().rows
          // Doesn't reflect grouping — leaf rows only
          ```
        correct_pattern: |
          ```tsx
          // Pick the right model for the question:
          table.getSelectedRowModel()           // selection from raw data
          table.getFilteredSelectedRowModel()   // selection within current filters
          table.getGroupedSelectedRowModel()    // selection within current groups
          ```
        source: packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts
        priority: low
        status: warning
        version_context: v9.0.0-alpha.47
        skills:
          - grouping
          - row-selection
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    reference_candidates:
      - name: built-in aggregationFns
        kind: function-registry
        count: 8
        actual_count: 9
        source: packages/table-core/src/fns/aggregationFns.ts
        entries:
          - sum
          - min
          - max
          - extent
          - mean
          - median
          - unique
          - uniqueCount
          - count
        note:
          Docs say 'There are several built-in aggregation functions' and list 9. Phase 1+2 note said
          8 — actual count is 9 (count, extent both included).
    gaps:
      - Phase 1+2 anchor says 'the built-in aggregationFn registry' but the registry has 9 (count + 8 numeric).
        Verify with maintainer.
      - "`createGroupedRowModel` constructs new Row objects via `constructRow` for grouped rows; these rows
        have a special `getValue` override that intercepts to either return cached grouping values or call
        the column's aggregationFn (lines 139-175). The interaction with column accessors (which normally
        return per-row data) is subtle. Worth a reference note."
      - "`manualGrouping: true` exists but docs say 'There are not currently many known easy ways to do server-side
        grouping with TanStack Table.' Real-world server-side grouping support is a gap."
  - slug: row-expanding
    type: core
    packages:
      - '@tanstack/table-core'
    domain: row-model-features
    description:
      Expand and collapse rows in TanStack Table v9 with the `expandedRowModel` stage — tree
      sub-rows via `getSubRows`, detail panels via `getRowCanExpand`, filter-from-leaf-rows interaction,
      expanded rows in pagination, and manual server-side expansion.
    covers:
      - rowExpandingFeature
      - createExpandedRowModel()
      - state.expanded (ExpandedState = true | Record<string, boolean>)
      - onExpandedChange
      - 'getSubRows  # (row) => row.children | row.subRows | undefined'
      - 'getRowCanExpand  # override for detail-panel pattern'
      - getIsRowExpanded
      - 'enableExpanding  # column/row gate'
      - manualExpanding
      - 'autoResetExpanded  # auto reset when row structure changes'
      - 'paginateExpandedRows  # default true; false = expand on parent page'
      - 'filterFromLeafRows  # tree filtering interaction'
      - 'maxLeafRowFilterDepth  # default 100, set 0 to filter root-only'
      - table.setExpanded / resetExpanded / toggleAllRowsExpanded
      - table.getIsAllRowsExpanded / getIsSomeRowsExpanded / getCanSomeRowsExpand / getExpandedDepth
      - table.getToggleAllRowsExpandedHandler
      - row.toggleExpanded / getIsExpanded / getCanExpand / getIsAllParentsExpanded
      - row.getToggleExpandedHandler
      - 'row.depth  # for paddingLeft indentation in tree UIs'
      - 'row.subRows  # populated via getSubRows'
    tasks:
      - 'Render a tree table: provide nested `subRows` data, set `getSubRows: row => row.subRows`, render
        `paddingLeft: ${row.depth * 2}rem` on the first cell (see examples/react/expanding/src/main.tsx).'
      - 'Render detail panels (sub-components) for flat data: set `getRowCanExpand: () => true`, render a
        second `<tr>` with a `colSpan` cell when `row.getIsExpanded()` (see examples/react/sub-components/src/main.tsx).'
      - 'Toggle ALL rows at once with a header button: `table.getToggleAllRowsExpandedHandler()`.'
      - "Keep expanded children on their parent's page (so the page count doesn't expand): `paginateExpandedRows:
        false`."
      - 'Filter tree data and keep matching descendants visible under non-matching parents: `filterFromLeafRows:
        true`.'
    failure_modes:
      - mistake:
          'Using `getRowCanExpand: () => true` with tree data and a custom expand button — but `row.getCanExpand()`
          already auto-detects `subRows.length`, so the override may collide.'
        mechanism: |
          `row_getCanExpand` (rowExpandingFeature.utils.ts:319-327) returns `options.getRowCanExpand?.(row) ?? (enableExpanding ?? true) && !!row.subRows.length`. When `getRowCanExpand` is set, it WINS over the auto subRows check. If a developer wants both tree behavior AND detail panels (e.g., leaf rows expand to show extra info), they need `getRowCanExpand: row => true` AND `getSubRows: row => row.subRows`. But then EVERY row (including leaves with no subRows) will show an expand icon — the developer must check `row.subRows.length` themselves in the cell render.
        wrong_pattern: |
          ```tsx
          // BUG: every row gets an expander icon, including leaves
          const table = useTable({
            getRowCanExpand: () => true,
            getSubRows: r => r.subRows,
            // ...
          })
          // In cell: row.getCanExpand() always true → leaf rows show 👉 with nothing to expand
          ```
        correct_pattern: |
          ```tsx
          // For pure tree data, omit getRowCanExpand and let it auto-detect:
          // From examples/react/expanding/src/main.tsx
          const table = useTable({
            _features,
            _rowModels: { expandedRowModel: createExpandedRowModel(), /* ... */ },
            columns, data,
            getSubRows: row => row.subRows,
            // no getRowCanExpand — row.getCanExpand() is true only when subRows.length > 0
          })

          // For pure detail panels, override and skip getSubRows:
          // From examples/react/sub-components/src/main.tsx
          const table = useTable({
            _features: tableFeatures({ rowExpandingFeature }),
            _rowModels: { expandedRowModel: createExpandedRowModel() },
            columns, data,
            getRowCanExpand: (row) => true, // every row expands to show <subComponent>
          })
          ```
        source: packages/table-core/src/features/row-expanding/rowExpandingFeature.utils.ts
        priority: high
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - row-expanding
      - mistake:
          "Setting `paginateExpandedRows: false` and expecting the page size to stay 10 (it doesn't
          — more rows render)."
        mechanism: |
          `paginateExpandedRows: true` (default) lets expanded children flow naturally into pagination — each child counts toward `pageSize`. `paginateExpandedRows: false` keeps expanded children stuck under their parent on whichever page the parent appears — meaning a page of 10 parents with 5 children each renders 60 rows. From the docs guide: "This also means more rows will be rendered than the set page size." `createPaginatedRowModel` calls `expandRows({ ... })` to inflate the page slice when `paginateExpandedRows: false` (see createPaginatedRowModel.ts:57-69).
        wrong_pattern: |
          ```tsx
          // BUG: page renders 50 rows even though pageSize is 10
          const table = useTable({
            paginateExpandedRows: false,
            initialState: { pagination: { pageSize: 10 } },
            // user expands all parents → 10 parents * 5 children = 60 visible rows
          })
          ```
        correct_pattern: |
          ```tsx
          // From docs/guide/expanding.md
          // Default behavior (children flow through pagination):
          const table = useTable({
            _features,
            _rowModels: { expandedRowModel: createExpandedRowModel(), paginatedRowModel: createPaginatedRowModel() },
            columns, data,
            getSubRows: r => r.subRows,
            // paginateExpandedRows defaults to true
          })

          // OR explicitly keep children with parent:
          paginateExpandedRows: false, // accept that pageSize is a soft cap
          ```
        source: packages/table-core/src/features/row-pagination/createPaginatedRowModel.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - row-expanding
          - pagination
      - mistake: Storing `expanded` as `true` then writing into it as if it were a Record.
        mechanism: |
          `ExpandedState = true | Record<string, boolean>`. The `true` literal means "all rows expanded" — there's no need to enumerate row IDs. `row_toggleExpanded` (rowExpandingFeature.utils.ts:250-283) handles the transition: if `old === true`, it first MATERIALIZES the `true` into a real Record of all row IDs in the current row model, then applies the per-row toggle. Agents writing `setExpanded((old) => ({ ...old, [id]: true }))` against `old === true` get `{ 0: true, 1: true, ..., [id]: true }` which is a different state than they expected.
        wrong_pattern: |
          ```tsx
          // BUG: spreading `true` (a boolean) into an object gives {} - all rows collapse except [id]
          setExpanded((old) => ({ ...old, [row.id]: true }))
          // When old === true, this becomes { [row.id]: true } -- everything else collapses!
          ```
        correct_pattern: |
          ```tsx
          // Use row.toggleExpanded() / row.getToggleExpandedHandler() — they materialize properly:
          // From examples/react/expanding/src/main.tsx
          <button onClick={row.getToggleExpandedHandler()}>
            {row.getIsExpanded() ? '👇' : '👉'}
          </button>

          // Or handle the materialization yourself if you must:
          table.setExpanded((old) => {
            if (old === true) {
              const map: Record<string, boolean> = {}
              Object.keys(table.getRowModel().rowsById).forEach(id => { map[id] = true })
              return { ...map, [row.id]: !map[row.id] }
            }
            return { ...old, [row.id]: !old[row.id] }
          })
          ```
        source: packages/table-core/src/features/row-expanding/rowExpandingFeature.utils.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - row-expanding
      - mistake:
          'Setting `manualExpanding: true` and still passing `expandedRowModel: createExpandedRowModel()`
          AND expecting client-side flattening.'
        mechanism: |
          With `manualExpanding: true`, `table_getExpandedRowModel` skips the registered `expandedRowModel` factory and returns `getPreExpandedRowModel()` (sorted rows). The expanded state still tracks which rows are "expanded" in terms of UI affordance, but the row model is NOT inflated. To render manually-expanded children, you must include them in the source `data` and `getSubRows` — at which point you can just NOT use manualExpanding.
        wrong_pattern: |
          ```tsx
          // BUG: manualExpanding bypasses the expanded row model;
          // sub-rows are never flattened into view.
          const table = useTable({
            _features: tableFeatures({ rowExpandingFeature }),
            _rowModels: { expandedRowModel: createExpandedRowModel() }, // ignored
            columns, data,
            getSubRows: r => r.subRows,
            manualExpanding: true,
          })
          ```
        correct_pattern: |
          ```tsx
          // Manual expanding is for server-side patterns where the server
          // returns a pre-flattened view based on which rows are expanded.
          // From docs/guide/expanding.md
          const table = useTable({
            _features: tableFeatures({ rowExpandingFeature }),
            _rowModels: {}, // no expandedRowModel for manual mode
            columns,
            data: dataQuery.data, // server returns flattened rows when expanded
            manualExpanding: true,
            state: { expanded },
            onExpandedChange: setExpanded,
          })

          // For client-side tree, omit manualExpanding:
          const table = useTable({
            _features: tableFeatures({ rowExpandingFeature }),
            _rowModels: { expandedRowModel: createExpandedRowModel() },
            columns, data,
            getSubRows: r => r.subRows,
          })
          ```
        source: packages/table-core/src/core/row-models/coreRowModelsFeature.utils.ts
        priority: medium
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - row-expanding
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    reference_candidates: []
    gaps:
      - "`row.subRows` is initially populated by `getSubRows`; for grouped rows it's overwritten by `createGroupedRowModel`.
        The interaction between user-provided `getSubRows` and grouping-generated subRows is subtle — what
        happens if a user has tree data AND groups it?"
      - "`autoResetExpanded` exists but isn't documented in the expanding guide. The implementation schedules
        a reset (`table._reactivity.schedule`) when grouping changes (it's called from `createGroupedRowModel.onAfterUpdate`).
        Worth a note on reset interactions."
      - "`row.getIsAllParentsExpanded()` exists but isn't used in any example file I read. Its main use case
        is in conditional rendering of deeply nested rows."
  - slug: column-layout
    type: core
    domain: ui-state-features
    packages:
      - '@tanstack/table-core'
    description: |
      The five UI-state-only column features that shape how columns render: visibility (show/hide), ordering (manual sequence), pinning (left/right regions), sizing (px widths with min/max), and resizing (drag handle that commits to columnSizing). All are opt-in via `tableFeatures({ ... })`, share the consumer's state-management story (`initialState` vs hoisted `state` + `on*Change`), and combine through a fixed reorder pipeline: Column Pinning -> Manual Column Ordering -> Grouping. None of these features require a row model — they only affect layout.
    covers:
      - columnVisibilityFeature (state, getCanHide, getIsVisible, getToggleVisibilityHandler, table.getVisibleLeafColumns,
        row.getVisibleCells, getIsAllColumnsVisible)
      - columnOrderingFeature (columnOrder state, column.getIndex, getIsFirstColumn, getIsLastColumn, setColumnOrder,
        the Pinning/Ordering/Grouping reorder pipeline)
      - columnPinningFeature (left/right ColumnPinningState, column.pin, column.getIsPinned, column.getStart,
        column.getAfter, column.getIsLastColumn/'left'|'right', split-table APIs getLeftHeaderGroups/getCenterHeaderGroups/getRightHeaderGroups,
        row.getLeftVisibleCells/getCenterVisibleCells/getRightVisibleCells)
      - 'columnSizingFeature (defaultColumnSizing {size: 150, minSize: 20, maxSize: MAX_SAFE_INTEGER}, columnDef.size/minSize/maxSize,
        column.getSize, header.getSize, table.getTotalSize, table.getCenterTotalSize/getLeftTotalSize/getRightTotalSize)'
      - columnResizingFeature (columnResizeMode 'onEnd' vs 'onChange', columnResizeDirection 'ltr'|'rtl',
        header.getResizeHandler with onMouseDown + onTouchStart, column.getIsResizing, columnResizing.deltaOffset/isResizingColumn
        for resize-indicator UI, CSS-variable + memoized-tbody perf pattern)
      - Stable `columns` reference requirement (React FAQ pitfall) when these features are driving re-renders
    tasks:
      - Add a column visibility toggle panel that hides/shows columns without breaking header or cell render
        (`getVisibleLeafColumns`, `row.getVisibleCells`).
      - Pin specific columns left or right (e.g. a select column on the left, an actions column on the right)
        via `initialState.columnPinning` or an interactive pin button using `column.pin('left' | 'right' |
        false)`.
      - Wire up drag-and-drop column reordering with `@dnd-kit/core` and `setColumnOrder` (the canonical 2026
        stack — react-dnd is incompatible with React 18+ Strict Mode).
      - Build draggable column resize handles that stay 60fps with large tables (CSS variables + memoized
        TableBody during resize, per the `column-resizing-performant` example).
      - "Render a sticky-CSS pinning layout (one `<table>`, pinned columns positioned with `column.getStart('left')`
        / `getAfter('right')` and `position: sticky`)."
    subsystems:
      - name: visibility
        description: |
          `columnVisibility: Record<columnId, boolean>` where missing or `true` means visible. Driven by `enableHiding` (table-level) and `columnDef.enableHiding` (column-level), both defaulting to `true`. Rendering MUST go through `getVisibleLeafColumns` / `row.getVisibleCells` — the `getAll*` variants do not respect this state.
        key_apis:
          - table.getVisibleLeafColumns() / row.getVisibleCells()
          - column.getIsVisible / getCanHide / getToggleVisibilityHandler
          - table.getIsAllColumnsVisible / getToggleAllColumnsVisibilityHandler
      - name: ordering
        description: |
          `columnOrder: string[]` of leaf column ids. Empty array means definition order. Ordering is **scoped to unpinned (center) columns** when pinning is also active — pinned columns are sequenced inside `columnPinning.left/right` arrays, not `columnOrder`. The reorder pipeline executes in this fixed order: (1) Column Pinning splits into left/center/right, (2) `columnOrder` reorders the center, then (3) `groupedColumnMode: 'reorder' | 'remove'` may move grouped columns to the front.
        key_apis:
          - table.setColumnOrder / onColumnOrderChange
          - column.getIndex(position?) / getIsFirstColumn / getIsLastColumn
      - name: pinning
        description: |
          `columnPinning: { left: string[]; right: string[] }`. Pinning a group column pins every leaf. Two render strategies are supported: (1) **split tables** using `getLeft*/getCenter*/getRight*` header, column, and cell APIs (`column-pinning-split` example), and (2) **single table + sticky CSS** using `column.getStart('left')` / `column.getAfter('right')` + `position: sticky` plus `getIsLastColumn('left')` / `getIsFirstColumn('right')` for the shadow-edge indicator (`column-pinning-sticky` example). IMPORTANT: in v9 the table-level option is `enableColumnPinning`, not the v8 `enablePinning` — that name is now exclusively the per-column `columnDef.enablePinning`.
        key_apis:
          - column.pin('left' | 'right' | false) / column.getIsPinned / column.getCanPin
          - column.getStart(position) / column.getAfter(position) — sticky CSS offsets
          - table.getLeftHeaderGroups / getCenterHeaderGroups / getRightHeaderGroups
          - row.getLeftVisibleCells / getCenterVisibleCells / getRightVisibleCells
      - name: sizing
        description: |
          `columnSizing: Record<columnId, number>` (pixels). Static defaults live in `defaultColumnSizing` (size 150, minSize 20, maxSize Number.MAX_SAFE_INTEGER) and can be overridden globally via `tableOptions.defaultColumn` or per-column via `columnDef.size/minSize/maxSize`. `column.getSize()` clamps the committed state value (or column-def fallback) between min and max. Three layout styles work: semantic `<table>` with `width`, block divs with strict widths, and absolutely positioned cells using `getStart()` (no resize mode tied to layout — this is purely consumer choice).
        key_apis:
          - column.getSize() / header.getSize() — size lookup
          - table.getTotalSize / getCenterTotalSize / getLeftTotalSize / getRightTotalSize
          - column.resetSize() — drop committed override, fall back to column def
          - tableOptions.defaultColumn for cross-column defaults
      - name: resizing
        description: |
          Layered on top of sizing. Two modes via `columnResizeMode`: `'onEnd'` (default — commits the new size to `columnSizing` only when the drag releases; safer for large React tables) and `'onChange'` (commits live during drag; needs the CSS variable + memoized TableBody pattern). `header.getResizeHandler()` returns a single function wired to BOTH `onMouseDown` and `onTouchStart` for mobile support. The transient `columnResizing` state carries `isResizingColumn` and `deltaOffset` — the latter drives the resize-indicator translation in `onEnd` mode. `columnResizeDirection: 'rtl'` inverts the delta sign.
        key_apis:
          - header.getResizeHandler() — single handler for mouse + touch
          - column.getIsResizing / column.getCanResize
          - table.atoms.columnResizing.get() — deltaOffset, isResizingColumn
          - "columnResizeMode: 'onEnd' (default) | 'onChange'"
          - "columnResizeDirection: 'ltr' (default) | 'rtl'"
          - column.resetSize() (double-click handle) — provided by sizing subsystem
    failure_modes:
      - mistake: |
          Rendering header or body cells with `table.getAllLeafColumns()` and `row.getAllCells()` while `columnVisibilityFeature` is registered. Hidden columns still render.
        mechanism: |
          The `getAll*` accessors return every column/cell unconditionally — they do not consult `columnVisibility` state. Only the `Visible` variants (and the header-group APIs) filter by visibility. Users who copy a v8-era body loop or a non-visibility example into a visibility-enabled table will see no effect on the rendered table regardless of how they toggle the checkbox panel.
        wrong_pattern: |
          // ❌ Toggling visibility has no effect on rendered cells
          {table.getAllLeafColumns().map(column => (
            <th key={column.id}>...</th>
          ))}
          {row.getAllCells().map(cell => (
            <td key={cell.id}><table.FlexRender cell={cell} /></td>
          ))}
        correct_pattern: |
          // ✅ From examples/react/column-visibility/src/main.tsx and the guide:
          // Header groups already respect visibility; use them for headers.
          // For body cells, swap getAllCells -> getVisibleCells.
          <thead>
            {table.getHeaderGroups().map(headerGroup => (
              <tr key={headerGroup.id}>
                {headerGroup.headers.map(header => (
                  <th key={header.id} colSpan={header.colSpan}>
                    {header.isPlaceholder ? null : (
                      <table.FlexRender header={header} />
                    )}
                  </th>
                ))}
              </tr>
            ))}
          </thead>
          <tbody>
            {table.getRowModel().rows.map(row => (
              <tr key={row.id}>
                {row.getVisibleCells().map(cell => (  // <-- the fix
                  <td key={cell.id}><table.FlexRender cell={cell} /></td>
                ))}
              </tr>
            ))}
          </tbody>
        source:
          - docs/guide/column-visibility.md (Column Visibility Aware Table APIs)
          - examples/react/column-visibility/src/main.tsx
        priority: high
        status: active
        version_context: |
          v9 names unchanged from v8 (`getVisibleLeafColumns`, `getVisibleCells`). Still the #1 column-visibility footgun.
        skills:
          - column-layout
      - mistake: |
          Setting `columnResizeMode: 'onChange'` in a React table with many rows or expensive cell renders, then complaining about jittery / sub-30fps resize. Users typically call `column.getSize()` inside every `<td>` and re-render the whole body on every move event.
        mechanism: |
          In `'onChange'` mode, the resize handler commits a new `columnSizing` map on every pointer move. Each commit re-renders the entire body. With `column.getSize()` evaluated on every cell, you re-run an O(columns × rows) traversal per move event — far beyond a 16ms frame budget. The performant pattern (a) caches column widths once in a `useMemo` keyed on `columnResizing` + `columnSizing`, (b) passes those widths down as CSS variables on the table root so cells don't read from JS, and (c) wraps the TableBody in `React.memo` and uses the memoized version only while `state.columnResizing.isResizingColumn` is truthy. The guide also recommends `'onEnd'` as a sane default when this perf budget can't be met.
        wrong_pattern: |
          // ❌ Live resize + getSize() on every cell + un-memoized body
          const table = useTable({
            _features: tableFeatures({ columnSizingFeature, columnResizingFeature }),
            columnResizeMode: 'onChange',
            //...
          })
          // ...
          <td style={{ width: cell.column.getSize() }}>
            {cell.renderValue()}
          </td>
        correct_pattern: |
          // ✅ From examples/react/column-resizing-performant/src/main.tsx
          // 1. Compute every column width once, keyed on resize state
          const columnSizeVars = React.useMemo(() => {
            const headers = table.getFlatHeaders()
            const colSizes: { [key: string]: number } = {}
            for (const header of headers) {
              colSizes[`--header-${header.id}-size`] = header.getSize()
              colSizes[`--col-${header.column.id}-size`] = header.column.getSize()
            }
            return colSizes
          }, [table.state.columnResizing, table.state.columnSizing])

          // 2. Spread widths onto the table element as CSS variables
          <div className="divTable" style={{ ...columnSizeVars, width: table.getTotalSize() }}>
            <div className="thead">
              {/* header cells read width from var(--header-${id}-size) */}
            </div>

            {/* 3. Swap to memoized body only while a drag is in progress */}
            {table.store.state.columnResizing.isResizingColumn && enableMemo
              ? <MemoizedTableBody table={table} />
              : <TableBody table={table} />}
          </div>

          // Body cells use the CSS variable (no per-cell getSize() call)
          <div className="td" style={{ width: `calc(var(--col-${cell.column.id}-size) * 1px)` }}>
            {cell.renderValue()}
          </div>

          export const MemoizedTableBody = React.memo(
            TableBody,
            (prev, next) => prev.table.options.data === next.table.options.data,
          )
        source:
          - docs/guide/column-resizing.md (Advanced Column Resizing Performance)
          - examples/react/column-resizing-performant/src/main.tsx
        priority: high
        status: active
        version_context: |
          v9 surface unchanged from v8 for resize APIs. The performant pattern is now the canonical reference — Svelte/Vue/Solid adapters generally don't need it, but React does.
        skills:
          - column-layout
      - mistake: |
          Trying to control the order of pinned columns by mutating `columnOrder` state. The pinned region keeps rendering in pin-insertion order regardless of what `columnOrder` says.
        mechanism: |
          The fixed reorder pipeline is (1) Column Pinning split, (2) `columnOrder` applied, (3) Grouping. After step (1) the pinned columns are read **directly from `state.columnPinning.left` and `.right`** by `table_getLeftHeaderGroups` / `_getRightHeaderGroups`. `columnOrder` is only consulted by the unpinned center partition. To reorder a pinned column you must edit the array inside `columnPinning` itself (or unpin -> reorder -> repin).
        wrong_pattern: |
          // ❌ Won't move 'actions' relative to 'firstName' while it's pinned right
          const [columnPinning] = useState({
            left: ['select'],
            right: ['actions'],
          })
          table.setColumnOrder(['actions', 'select', 'firstName', 'lastName'])
        correct_pattern: |
          // ✅ Reorder the pinning state itself
          table.setColumnPinning(old => ({
            left: ['select'],
            right: ['summary', 'actions'],  // move 'summary' to render before 'actions'
          }))

          // Or for the unpinned center region, columnOrder works normally:
          table.setColumnOrder(['firstName', 'lastName'])  // only affects center columns
        source:
          - "docs/guide/column-ordering.md ('Note: columnOrder state will only affect unpinned columns')"
          - docs/guide/column-pinning.md (How Column Pinning Affects Column Order)
          - packages/table-core/src/features/column-pinning/columnPinningFeature.utils.ts (table_getLeftHeaderGroups
            reads from columnPinning.left directly)
        priority: medium
        status: active
        version_context: |
          Behavior unchanged from v8. The 3-stage pipeline is documented identically in both column-ordering.md and column-pinning.md in v9.
        skills:
          - column-layout
      - mistake: |
          Using the v8 table option `enablePinning` to disable column pinning in v9 — option is ignored, columns remain pinnable.
        mechanism: |
          In v9 the umbrella `enablePinning` option was split into two distinct options: `enableColumnPinning` (table level) and `enableRowPinning` (table level). The string `enablePinning` is still valid but now refers ONLY to the per-column `columnDef.enablePinning` opt-out. Any agent or human ported from v8 that writes `enablePinning: false` at the table level will see no effect — `column_getCanPin` reads `column.table.options.enableColumnPinning ?? true`.
        wrong_pattern: |
          // ❌ v8 syntax — no longer disables pinning in v9
          const table = useTable({
            _features: tableFeatures({ columnPinningFeature }),
            enablePinning: false,   // ignored at table level in v9
            //...
          })
        correct_pattern: |
          // ✅ v9: split into two table-level options
          const table = useTable({
            _features: tableFeatures({ columnPinningFeature, rowPinningFeature }),
            enableColumnPinning: false,  // turns off column pinning
            enableRowPinning: false,     // turns off row pinning (or row => row.original.locked)
            //...
          })

          // Per-column opt-out is still spelled `enablePinning`:
          columnHelper.accessor('id', {
            enablePinning: false,  // this column can't be pinned
          })
        source:
          - packages/table-core/src/features/column-pinning/columnPinningFeature.types.ts (TableOptions_ColumnPinning.enableColumnPinning)
          - packages/table-core/src/features/column-pinning/columnPinningFeature.utils.ts (column_getCanPin
            reads enableColumnPinning)
          - packages/table-core/src/features/row-pinning/rowPinningFeature.types.ts (TableOptions_RowPinning.enableRowPinning)
        priority: high
        status: active
        version_context: |
          v9 breaking change vs v8. Agents trained on the v8 surface will consistently produce `enablePinning` at the table level.
        skills:
          - column-layout
          - row-pinning
      - mistake: |
          Using `react-dnd` or `react-beautiful-dnd` for column reordering in a React 18+/Strict Mode app, or trying to wrap dnd-kit's `DndContext` directly inside a `<table>` element.
        mechanism: |
          `react-dnd` has documented incompatibilities with React 18 Strict Mode (its Provider creates effects that re-fire unpredictably) and is no longer actively maintained against the latest React internals. `react-beautiful-dnd` is in maintenance mode and has known issues with `<table>` markup. The official TanStack examples for column-dnd and row-dnd both use `@dnd-kit/core` + `@dnd-kit/sortable` because dnd-kit's provider renders `<div>` wrappers — which violates HTML if nested inside `<thead>` / `<tbody>`. The `DndContext` MUST wrap the entire table from outside.
        wrong_pattern: |
          // ❌ react-dnd in React 18 Strict Mode — flicker and stale drags
          import { DndProvider } from 'react-dnd'
          import { HTML5Backend } from 'react-dnd-html5-backend'
          // ...

          // ❌ Nesting DndContext inside <table>
          <table>
            <DndContext onDragEnd={handleDragEnd}>
              <thead>...</thead>
            </DndContext>
          </table>
        correct_pattern: |
          // ✅ From examples/react/column-dnd/src/main.tsx
          import {
            DndContext, KeyboardSensor, MouseSensor, TouchSensor,
            closestCenter, useSensor, useSensors,
          } from '@dnd-kit/core'
          import { restrictToHorizontalAxis } from '@dnd-kit/modifiers'
          import {
            SortableContext, arrayMove,
            horizontalListSortingStrategy, useSortable,
          } from '@dnd-kit/sortable'

          function handleDragEnd(event: DragEndEvent) {
            const { active, over } = event
            if (over && active.id !== over.id) {
              table.setColumnOrder(prev => {
                const oldIndex = prev.indexOf(active.id as string)
                const newIndex = prev.indexOf(over.id as string)
                return arrayMove(prev, oldIndex, newIndex)
              })
            }
          }

          // NOTE: DndContext renders divs, so it MUST wrap from outside <table>
          <DndContext
            collisionDetection={closestCenter}
            modifiers={[restrictToHorizontalAxis]}
            onDragEnd={handleDragEnd}
            sensors={useSensors(useSensor(MouseSensor), useSensor(TouchSensor), useSensor(KeyboardSensor))}
          >
            <table>
              <thead>
                {table.getHeaderGroups().map(hg => (
                  <tr key={hg.id}>
                    <SortableContext
                      items={table.store.state.columnOrder}
                      strategy={horizontalListSortingStrategy}
                    >
                      {hg.headers.map(h => <DraggableTableHeader key={h.id} header={h} />)}
                    </SortableContext>
                  </tr>
                ))}
              </thead>
              {/* ... */}
            </table>
          </DndContext>
        source:
          - docs/guide/column-ordering.md (Drag and Drop Column Reordering Suggestions)
          - "examples/react/column-dnd/src/main.tsx (the comment `// NOTE: This provider creates div elements,
            so don't nest inside of <table> elements`)"
        priority: medium
        status: active
        version_context: |
          The recommendation has been stable since v8.10. dnd-kit is the recommended stack in v9 docs.
        skills:
          - column-layout
      - mistake: |
          Forgetting to wire `header.getResizeHandler()` to BOTH `onMouseDown` AND `onTouchStart` — desktop drag resize works, mobile users tap-and-drag but the column never resizes.
        mechanism: |
          `header_getResizeHandler` returns a single function that internally branches on `isTouchStartEvent(event)`. The same function is meant to be installed on both DOM event types so the handler picks the correct branch. If a developer only wires `onMouseDown` (the common copy-paste from a desktop-only example), touch events never fire the handler at all — touch users can grab the resizer visually but no `mousedown` event is synthesized for a long drag on iOS Safari/Android Chrome. The handler installs `touchmove` / `touchend` listeners on `document` only after it receives the initial `touchstart`.
        wrong_pattern: |
          // ❌ Desktop only — mobile users can't resize
          <div
            onMouseDown={header.getResizeHandler()}
            onDoubleClick={() => header.column.resetSize()}
            className={`resizer ${header.column.getIsResizing() ? 'isResizing' : ''}`}
          />
        correct_pattern: |
          // ✅ From every column-resizing example: wire BOTH events
          <div
            onDoubleClick={() => header.column.resetSize()}
            onMouseDown={header.getResizeHandler()}
            onTouchStart={header.getResizeHandler()}
            className={`resizer ${header.column.getIsResizing() ? 'isResizing' : ''}`}
          />
        source:
          - docs/guide/column-resizing.md (Column Resize APIs section)
          - examples/react/column-resizing/src/main.tsx
          - examples/react/column-pinning-sticky/src/main.tsx
          - packages/table-core/src/features/column-resizing/columnResizingFeature.utils.ts (header_getResizeHandler
            branches on isTouchStartEvent)
        priority: medium
        status: active
        version_context: |
          v9 surface unchanged.
        skills:
          - column-layout
      - mistake: |
          Defining `columns` (or the column-helper array) inline in the render body instead of stabilizing with `useMemo`/`useState`/module scope. Triggers an infinite render loop once any of these layout features re-render on state change.
        mechanism: |
          TanStack Table treats `columns` (and `data` and `state`) as inputs that, when their reference changes, signal that the underlying table model must be rebuilt. With visibility/pinning/ ordering/sizing/resizing registered, every interaction commits a state slice; React re-runs the component; an inline `columns` literal gets a new identity; the table rebuilds; that triggers another render. The `column-pinning-split` and `column-dnd` examples both use `useMemo(() => columnHelper.columns([...]), [])` or define `defaultColumns` outside the component for exactly this reason. The FAQ flags this as Pitfall 1.
        wrong_pattern: |
          // ❌ Infinite loop once column visibility / pinning / resizing fires
          function App() {
            const columns = [
              columnHelper.accessor('firstName', { ... }),
              columnHelper.accessor('lastName', { ... }),
            ]
            const table = useTable({
              _features: tableFeatures({ columnPinningFeature, columnResizingFeature }),
              columns,
              data,
            })
          }
        correct_pattern: |
          // ✅ Stable reference via module scope (column-pinning-split pattern)
          const defaultColumns = columnHelper.columns([
            columnHelper.accessor('firstName', { ... }),
            columnHelper.accessor('lastName', { ... }),
          ])
          function App() {
            const [columns] = React.useState(() => [...defaultColumns])
            //...
          }

          // ✅ Or useMemo (column-dnd pattern)
          function App() {
            const columns = React.useMemo(
              () => columnHelper.columns([
                columnHelper.accessor('firstName', { ... }),
                columnHelper.accessor('lastName', { ... }),
              ]),
              [],
            )
            //...
          }
        source:
          - 'docs/faq.md (Pitfall 1: Creating new columns or data on every render)'
          - examples/react/column-pinning-split/src/main.tsx (defaultColumns + useState)
          - examples/react/column-dnd/src/main.tsx (useMemo)
        priority: high
        status: active
        version_context: |
          React-specific. Same FAQ entry applies across all of cluster C — listed here because layout features are usually where users first hit it.
        skills:
          - column-layout
          - row-selection
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    gaps:
      - |
        Is `column-layout` too broad as a single skill? Five subsystems with distinct config surfaces but a common pattern. Alternative: split into `column-visibility-ordering` (state-only) + `column-pinning` + `column-sizing-resizing` (interaction). Kevin approved combining — keep unless Phase 4 reveals retrieval issues.
      - |
        No Angular-specific failure mode for column resizing perf. The `angular/column-resizing-performant` example exists but I didn't deep-read it; if signals make the React pattern unnecessary, a clarifying note may belong on the resize subsystem.
      - |
        The `Table_ColumnResizing.setcolumnResizing` API name has a deliberately lowercase `c` ("matches the current generated v9 table API for the `columnResizing` state slice" per the JSDoc). This is an oddity that might warrant a typo-tolerance failure mode if it's stable enough to ship.
    name: Column Layout Features
  - slug: row-pinning
    type: core
    domain: ui-state-features
    packages:
      - '@tanstack/table-core'
    description: |
      Pin specific rows to a top region or bottom region that stays visible across pagination and filtering. State shape is `{ top: string[]; bottom: string[] }` keyed by `row.id`. Simpler pipeline than column pinning — only one reorder step happens after row pinning (sorting) and pinned rows are sorted within their region.
    covers:
      - rowPinningFeature (RowPinningState, row.pin, row.getIsPinned, row.getPinnedIndex, row.getCanPin, table.getTopRows,
        table.getBottomRows, table.getCenterRows, table.getIsSomeRowsPinned)
      - enableRowPinning option (bool or row predicate)
      - keepPinnedRows option (default true — pinned rows persist across pagination/filtering even if they'd
        otherwise be filtered out; false hides them when filtered/paginated away)
      - row.pin(position, includeLeafRows?, includeParentRows?) signature — the extra args matter for grouped/expanded
        data
      - The reorder pipeline: Row Pinning -> Sorting
    tasks:
      - Add pin-top / pin-bottom buttons to a row that persist the pinned rows even when the user paginates
        or filters the data.
      - Render pinned rows in a sticky `<tr>` with calculated `top`/`bottom` offsets based on `row.getPinnedIndex()`
        (see the example pattern).
      - Choose between (a) splitting pinned vs center rows in render (`getTopRows + getCenterRows + getBottomRows`)
        versus (b) leaving pinned rows duplicated in the main flow (the `copyPinnedRows` toggle in the example).
    failure_modes:
      - mistake: |
          Setting `getRowId: (row) => row.id` (or omitting it), pinning a row, then refetching/reordering the data — the wrong row stays pinned because `row.id` defaulted to `row.index` and indices shifted.
        mechanism: |
          `row.id` defaults to the row's positional `index` in the data array. `rowPinning.top` and `rowPinning.bottom` are arrays of string row ids. After a refetch that reorders the data, index 3 might now be a different record entirely, but the pinning state still pins index 3. This is the same root cause as the row selection ID pitfall — fix by supplying a stable `getRowId: (row) => row.uuid` (or any unique primary key from the domain data). The row-pinning example deliberately uses `makeData(1_000, 2, 2)` with `subRows` and demonstrates the `includeLeafRows`/`includeParentRows` args of `row.pin` to handle grouped data.
        wrong_pattern: |
          // ❌ row.id defaults to row.index; pin survives wrong rows after refetch
          const table = useTable({
            _features: tableFeatures({ rowPinningFeature, rowPaginationFeature }),
            data, // refetched periodically
            //...
          })
        correct_pattern: |
          // ✅ Stable row identity
          const table = useTable({
            _features: tableFeatures({ rowPinningFeature, rowPaginationFeature }),
            data,
            getRowId: row => row.userId,  // or row.uuid, row.id from API, etc.
            //...
          })

          // For grouped/expanded data, pass the include flags too:
          row.pin('top', includeLeafRows, includeParentRows)
        source:
          - docs/guide/row-selection.md (Useful Row Ids — same principle)
          - examples/react/row-pinning/src/main.tsx (uses makeData with subRows, demonstrates include flags)
        priority: high
        status: active
        version_context: |
          v9 surface unchanged.
        skills:
          - row-pinning
          - row-selection
      - mistake: |
          Leaving `keepPinnedRows: true` (the default) and being surprised that pinned rows appear on every page during pagination — or conversely, setting it to `false` and being surprised that pinned rows disappear when filtered out.
        mechanism: |
          `keepPinnedRows` controls whether `table.getTopRows()` / `table.getBottomRows()` use `table.getRow(id, true)` (which searches the full pre-pagination row set) or `visibleRows.find(...)` (which only finds rows currently in the row model). Default is `true`, so pinned rows stick across pagination and filtering and may render on every page. With `false`, pinned rows can disappear if their underlying row is filtered or paginated out. The row-pinning example exposes both via the "Keep/Persist Pinned Rows" checkbox to make the contrast visible. The behavior is deliberate — pick the one that matches the UX you want.
        wrong_pattern: |
          // ❌ Expecting pinned rows to vanish on filter, but they don't (default)
          const table = useTable({
            _features: tableFeatures({ rowPinningFeature, columnFilteringFeature }),
            //...
            // keepPinnedRows defaults to true; pinned rows survive filtering
          })
        correct_pattern: |
          // ✅ Be explicit about which UX you want
          const table = useTable({
            _features: tableFeatures({ rowPinningFeature, columnFilteringFeature }),
            keepPinnedRows: false,   // pinned rows disappear when filtered/paginated out
            //...
          })

          // Or to keep the default but render pinned rows separately from the body:
          <tbody>
            {table.getTopRows().map(row => <PinnedRow row={row} ... />)}
            {table.getCenterRows().map(row => <Row row={row} ... />)}
            {table.getBottomRows().map(row => <PinnedRow row={row} ... />)}
          </tbody>
        source:
          - docs/guide/row-pinning.md
          - 'packages/table-core/src/features/row-pinning/rowPinningFeature.utils.ts (table_getPinnedRows: const
            keepPinnedRows = table.options.keepPinnedRows ?? true)'
          - examples/react/row-pinning/src/main.tsx (keepPinnedRows toggle)
        priority: medium
        status: active
        version_context: |
          v9 default matches v8 (`true`). Same option name.
        skills:
          - row-pinning
      - mistake: |
          Iterating `table.getRowModel().rows` for the main tbody AND rendering `getTopRows()`/`getBottomRows()` separately — pinned rows render twice (once at top/bottom, once where they originally appeared in the row model).
        mechanism: |
          `getRowModel()` returns the complete current row model with pinned rows still in it (pinning doesn't remove rows from the model, it just exposes a partition). The intended pattern is to render either (a) `getTopRows + getCenterRows + getBottomRows` (three loops, pinned rows appear once) or (b) `getTopRows + getRowModel + getBottomRows` only if you explicitly want pinned rows duplicated. The example toggles between these via `copyPinnedRows` to make the difference explicit. The default choice should be `getCenterRows`.
        wrong_pattern: |
          // ❌ Pinned rows render twice
          <tbody>
            {table.getTopRows().map(row => <PinnedRow row={row} />)}
            {table.getRowModel().rows.map(row => (   // <-- still includes pinned rows
              <tr key={row.id}>...</tr>
            ))}
            {table.getBottomRows().map(row => <PinnedRow row={row} />)}
          </tbody>
        correct_pattern: |
          // ✅ From examples/react/row-pinning/src/main.tsx
          <tbody>
            {table.getTopRows().map(row => (
              <PinnedRow key={row.id} row={row} table={table} />
            ))}
            {table.getCenterRows().map(row => (
              <tr key={row.id}>
                {row.getAllCells().map(cell => (
                  <td key={cell.id}><table.FlexRender cell={cell} /></td>
                ))}
              </tr>
            ))}
            {table.getBottomRows().map(row => (
              <PinnedRow key={row.id} row={row} table={table} />
            ))}
          </tbody>
        source:
          - examples/react/row-pinning/src/main.tsx (the copyPinnedRows demo toggle)
        priority: medium
        status: active
        version_context: |
          v9 surface unchanged.
        skills:
          - row-pinning
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    gaps:
      - |
        Could fold into `column-layout` as a sixth subsystem given how small the dedicated guide is (the row-pinning.md guide is *2 sentences* long after the deprecated `pinning.md` redirect). Kept separate because Kevin approved it as its own bullet AND the failure modes are genuinely different from column-pinning (id-stability matters more, `keepPinnedRows` has no column-side analogue, render order differs). **Flag for Phase 4 review.**
      - |
        Sticky-CSS row pinning pattern (the `PinnedRow` component in the example with `position: sticky` + `top: row.getPinnedIndex() * 26 + 48px`) is non-trivial — magic numbers depend on row height + header height. Worth deciding if this becomes its own reference pattern or a callout in the existing failure mode.
  - slug: row-selection
    type: core
    domain: ui-state-features
    packages:
      - '@tanstack/table-core'
    description: |
      Track which rows are selected via `rowSelection: Record<rowId, boolean | undefined>` and derive selected-row models scoped to the current data (`getSelectedRowModel`), to filtered data (`getFilteredSelectedRowModel`), or to grouped data (`getGroupedSelectedRowModel`). Supports single-select via `enableMultiRowSelection: false`, conditional row-by-row enabling via predicates, and parent->child propagation via `enableSubRowSelection`. The row id used in the selection map defaults to `row.index` — supplying a stable `getRowId` is essentially mandatory for any real-world use.
    covers:
      - rowSelectionFeature (RowSelectionState, table.getSelectedRowModel, getFilteredSelectedRowModel, getGroupedSelectedRowModel,
        getPreSelectedRowModel, getIsAllRowsSelected, getIsSomeRowsSelected, getIsAllPageRowsSelected, getIsSomePageRowsSelected,
        toggleAllRowsSelected, toggleAllPageRowsSelected)
      - row.toggleSelected, row.getIsSelected, row.getIsSomeSelected (indeterminate), row.getIsAllSubRowsSelected,
        row.getCanSelect, row.getCanMultiSelect, row.getCanSelectSubRows, row.getToggleSelectedHandler
      - enableRowSelection (bool or row predicate) — default true
      - enableMultiRowSelection (bool or row predicate) — default true; setting to false makes it radio-style
        (single-row at a time)
      - enableSubRowSelection (bool or row predicate) — default true; controls whether parent row toggle propagates
        to subRows
      - The interaction with `getRowId`, `manualPagination`, atoms (via `useCreateAtom`), and the indeterminate-checkbox
        UI pattern
    tasks:
      - Add a select-column with header "select all" + per-row checkbox wired through `getToggleAllRowsSelectedHandler`
        / `getToggleSelectedHandler`, including the indeterminate (`getIsSomeRowsSelected`) state.
      - Hoist selection state outside the table (via `useState` or an atom from `useCreateAtom`) so the selected
        ids can be sent to an API call or used in other components.
      - 'Build single-select / radio-style selection by setting `enableMultiRowSelection: false`.'
      - 'Restrict selection conditionally (e.g. only adult records, non-archived rows) via `enableRowSelection:
        row => row.original.age > 18`.'
    failure_modes:
      - mistake: |
          Omitting `getRowId` and using `manualPagination` (server-side paging). The user pages forward, selects a row, pages back, and the wrong row appears selected — or selections evaporate on page navigation.
        mechanism: |
          With no `getRowId` provided, `row.id` defaults to the row's `index` within the data array. Under `manualPagination`, each page receives only that page's rows, so `data[0]` is always row.id "0", `data[1]` is always "1", etc. Selecting row 5 on page 1 and paging to page 2 sets `rowSelection["5"] = true`, but page 2's data also has a "5" — so a different record now appears selected. The fix is universal: supply `getRowId: row => row.someStablePrimaryKey`. The row-selection guide flags this as the "Useful Row Ids" section and a separate note covers the `manualPagination` interaction: `getSelectedRowModel` only returns rows in the current `data` array, so for cross-page totals you must read `rowSelection` state directly instead of relying on the row model.
        wrong_pattern: |
          // ❌ Server-side pagination + default row.id = row.index
          const table = useTable({
            _features: tableFeatures({ rowSelectionFeature, rowPaginationFeature }),
            data,                  // only the current page from the server
            manualPagination: true,
            rowCount,              // server-provided total
            //...
          })
          // After paging, `rowSelection: { '5': true }` is ambiguous —
          // which page's row 5? Selection appears to move with the user.
        correct_pattern: |
          // ✅ Stable row id keyed to the primary key the server uses
          const table = useTable({
            _features: tableFeatures({ rowSelectionFeature, rowPaginationFeature }),
            data,
            manualPagination: true,
            rowCount,
            getRowId: row => row.uuid,   // or row.id from your API
            //...
          })

          // ✅ For "X of Y selected" with server-side pagination, read the
          // rowSelection state directly — getSelectedRowModel only knows
          // about rows in the current page's `data`:
          const totalSelected = Object.keys(table.state.rowSelection).length

          // (The selection state can hold ids that aren't in `data` —
          // that's by design.)
        source:
          - docs/guide/row-selection.md (Useful Row Ids section; manualPagination note above Access Row Selection
            State)
          - packages/table-core/src/features/row-selection/rowSelectionFeature.types.ts (RowSelectionState =
            Record<string, boolean | undefined>)
          - 'examples/react/row-selection/src/main.tsx (uses getRowId: row => row.id)'
        priority: high
        status: active
        version_context: |
          v9 surface unchanged from v8. Still the #1 row-selection footgun, especially in any server-driven table.
        skills:
          - row-selection
      - mistake: |
          Setting `enableMultiRowSelection: false` to get radio-style single selection, but rendering checkboxes via `getToggleAllRowsSelectedHandler` and `getIsSomeRowsSelected` for an indeterminate header — leaves a non-functional "select all" UI that contradicts the single-select intent.
        mechanism: |
          When `enableMultiRowSelection` is false, the internal `mutateRowIsSelected` helper clears all other ids from the selection map before adding the new one — so "select all" is effectively no-op (it sets one row, deselects all others, then checks the next, in a fast loop that leaves only the last row selected). The header indeterminate state is meaningless because only zero or one rows can ever be selected. Use radio inputs instead, drop the toggle-all header, and treat the selection map as `{ [singleId]: true }`.
        wrong_pattern: |
          // ❌ Checkbox "select all" + single-select mode
          const table = useTable({
            _features: tableFeatures({ rowSelectionFeature }),
            enableMultiRowSelection: false,  // radio-like
            //...
          })

          // Header still renders a checkbox + indeterminate
          <Checkbox
            checked={table.getIsAllRowsSelected()}
            indeterminate={table.getIsSomeRowsSelected()}
            onChange={table.getToggleAllRowsSelectedHandler()}
          />
        correct_pattern: |
          // ✅ Radio inputs, no toggle-all header
          const table = useTable({
            _features: tableFeatures({ rowSelectionFeature }),
            enableMultiRowSelection: false,
            getRowId: row => row.id,
            //...
          })

          {
            id: 'select',
            header: '',  // no "select all" makes sense in single-select mode
            cell: ({ row }) => (
              <input
                type="radio"
                name="row-selection"
                checked={row.getIsSelected()}
                disabled={!row.getCanSelect()}
                onChange={row.getToggleSelectedHandler()}
              />
            ),
          }

          // Or conditional single-select for only the sub-rows of certain
          // parents (the guide's predicate form):
          enableMultiRowSelection: row => row.original.age > 18,
        source:
          - docs/guide/row-selection.md (Single Row Selection section)
          - 'packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts (mutateRowIsSelected:
            if (!row_getCanMultiSelect(row)) Object.keys(selectedRowIds).forEach(key => delete selectedRowIds[key]))'
        priority: medium
        status: active
        version_context: |
          v9 surface unchanged.
        skills:
          - row-selection
      - mistake: |
          Calling `table.getSelectedRowModel().flatRows` on a paginated server-side table to count or list "all selected rows" — gets only the selected rows visible on the current page, missing selections from previously visited pages.
        mechanism: |
          `getSelectedRowModel` is derived from `table.getCoreRowModel()` via `selectRowsFn`, which recurses the core row tree filtering by `isRowSelected`. Under `manualPagination`, the core row model only knows about the rows in the current `data` prop — previously-paged rows aren't materialized. The `rowSelection` state map, however, can hold ids that aren't in the current `data`. The guide says explicitly: "Row selection state, however, can contain row ids that are not present in the `data` array just fine." For server-side selection bookkeeping, read `state.rowSelection` directly; for a count UI, use `Object.keys(rowSelection).length` instead of `.getSelectedRowModel().rows.length`.
        wrong_pattern: |
          // ❌ Under manualPagination, only counts the visible page's selected rows
          const selectedCount = table.getSelectedRowModel().flatRows.length
          //  ^ this stays small because flatRows is built from data, which
          //    only contains the current page.

          const handleBulkAction = () => {
            const ids = table.getSelectedRowModel().flatRows
              .map(row => row.original.id)
            api.archive(ids)  // missing all selections from other pages!
          }
        correct_pattern: |
          // ✅ For counts and id lists under manualPagination, read state directly
          const selectedCount = Object.keys(table.state.rowSelection).length

          const handleBulkAction = () => {
            // rowSelection keys ARE the stable ids (you set getRowId: row => row.id)
            const ids = Object.keys(table.state.rowSelection)
            api.archive(ids)
          }

          // (Client-side / no manualPagination: getSelectedRowModel is fine,
          //  because data contains every row.)
        source:
          - "docs/guide/row-selection.md ('Note: If you are using manualPagination ...')"
          - packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts (selectRowsFn walks
            the supplied rowModel, can only materialize rows present in core data)
          - examples/react/row-selection/src/main.tsx (uses Object.keys(table.state.rowSelection).length for
            the count UI)
        priority: high
        status: active
        version_context: |
          v9 surface unchanged from v8. This is the most common bug after shipping a working "select rows" feature to a server-paginated table.
        skills:
          - row-selection
      - mistake: |
          Toggling a parent row in a grouped/expanded table and being surprised that all subRows also flip — or conversely, disabling the propagation but having `getIsSomeSelected` return false when only some children are selected.
        mechanism: |
          `enableSubRowSelection` defaults to `true`. The internal `mutateRowIsSelected` recurses into `row.subRows` when this option is truthy, applying the same `value` to each. This enables the "select parent => select all children" UX. To opt out, set `enableSubRowSelection: false` (or pass a row predicate). The indeterminate state on a parent comes from `row.getIsSomeSelected()` which calls `isSubRowSelected(row)` and returns `'some'` when not all selectable descendants are selected — but this only looks at subRows, so if you've disabled propagation AND have separately selected mixed subRows, the parent will correctly read "some". The UX decision is yours; pick deliberately.
        wrong_pattern: |
          // ❌ Default behavior: clicking the parent selects all children
          // (which is correct for most cases but surprising if you wanted
          //  parent-only selection for a "select this group as a whole" UX)
          const table = useTable({
            _features: tableFeatures({ rowSelectionFeature, rowExpandingFeature }),
            getSubRows: row => row.subRows,
            // enableSubRowSelection unset — defaults to true
          })
        correct_pattern: |
          // ✅ Opt out of parent->child propagation explicitly
          const table = useTable({
            _features: tableFeatures({ rowSelectionFeature, rowExpandingFeature }),
            getSubRows: row => row.subRows,
            enableSubRowSelection: false,    // toggling parent doesn't touch subRows
          })

          // ✅ Or selectively disable per row
          enableSubRowSelection: row => row.depth > 0,  // top-level rows still propagate

          // ✅ Drive an indeterminate parent checkbox from descendant state
          <Checkbox
            checked={row.getIsSelected()}
            indeterminate={row.getIsSomeSelected()}   // 'some' descendants selected
            disabled={!row.getCanSelect()}
            onChange={row.getToggleSelectedHandler()}
          />
        source:
          - docs/guide/row-selection.md (Sub-Row Selection section)
          - packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts (mutateRowIsSelected
            recursion gated by row_getCanSelectSubRows)
          - "packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts (isSubRowSelected:
            returns 'all' | 'some' | false)"
        priority: medium
        status: active
        version_context: |
          v9 surface unchanged.
        skills:
          - row-selection
      - mistake: Parent row checkbox state stuck on "unchecked" with all sub-rows selected
        mechanism: |
          `getIsAllSubRowsSelected` on a grouped parent only counts direct children, not
          nested descendants. With multi-level grouping, the parent reports "all selected"
          based on a partial count. Combined with `enableSubRowSelection: true`,
          `row.toggleSelected(false)` on a parent shortcuts to a no-op because
          `getIsSelected()` returns false even when all descendants are checked.
        wrong_pattern: |
          // ❌ Returns false even when all leaf descendants are selected
          const isParentChecked = row.getIsAllSubRowsSelected()
        correct_pattern: |
          // ✅ Walk leaves directly
          const allLeafs = row.getLeafRows()
          const allSelected = allLeafs.length > 0 && allLeafs.every(r => r.getIsSelected())
          const someSelected = allLeafs.some(r => r.getIsSelected())
        source:
          https://github.com/TanStack/table/issues/4878 (row selection not working for nested rows,
          20 comments), https://github.com/TanStack/table/issues/4759 (Cannot toggle selection of grouped
          row to deselect its children, 8 comments)
        priority: HIGH
        status: active
        version_context: v8 / v9 — deeply confusing for tree data
        skills:
          - row-selection
          - grouping
      - mistake: Row selection state persists after data is removed/refreshed
        mechanism: |
          v8 removed v7's `autoResetSelectedRows`. With server-side data updates (websockets,
          refetch), row IDs that no longer exist remain in `rowSelection` state and
          `getIsAllRowsSelected()` returns true based on stale state.
        wrong_pattern: |
          // ❌ Selection state goes stale after data refresh
          useEffect(() => {
            refreshData()  // selection still references deleted IDs
          }, [trigger])
        correct_pattern: |
          // ✅ Prune stale IDs on data change
          useEffect(() => {
            setRowSelection(prev => {
              const validIds = new Set(data.map(row => row.id))
              const next = {}
              for (const id in prev) if (validIds.has(id)) next[id] = prev[id]
              return next
            })
          }, [data])
        source:
          https://github.com/TanStack/table/issues/5850 (Row selection is not cleaned up when table
          data is removed), https://github.com/TanStack/table/issues/4498 (Row selection does not reset after
          upgrading from v7 to v8)
        priority: HIGH
        status: active
        version_context: v7 → v8 migration regression — autoResetSelectedRows was removed
        skills:
          - row-selection
          - state-management
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
    gaps:
      - |
        The `examples/angular/row-selection-signal/` example uses a signal-aware integration (`signal<RowSelectionState>({})` + manual propagation through `onRowSelectionChange`). React's `useCreateAtom` (from `@tanstack/react-store`) is shown in the React example as the modern alternative to `useState` for selection state. Worth flagging in Phase 4 whether a per-adapter atom/signal pattern variant belongs in this skill or in a framework-specific overlay.
      - |
        `getPreSelectedRowModel` exists but is rarely used in practice — it returns the same thing as `getCoreRowModel` per the source. No failure mode currently flags this as a noise API; left in `covers` only.
  - name: React Table State, Subscribe & createTableHook
    slug: table-state
    domain: framework-adapters
    description:
      Reactivity, atom subscription, useTable selector, table.Subscribe rendering, FlexRender,
      and createTableHook composition for @tanstack/react-table.
    type: framework
    packages:
      - '@tanstack/react-table'
    covers:
      - useTable
      - useTable selector second argument
      - table.state (selected state)
      - table.atoms (per-slice readonly derived atoms)
      - table.baseAtoms (writable internal atoms)
      - table.store (flat readonly store)
      - table.Subscribe with selector
      - table.Subscribe with source (atom or store)
      - Subscribe (standalone)
      - table.FlexRender
      - useCreateAtom from @tanstack/react-store
      - atoms option for external ownership
      - state plus on[State]Change option
      - initialState
      - createTableHook
      - createAppColumnHelper / useAppTable / useTableContext / useCellContext / useHeaderContext
      - table.AppTable / table.AppHeader / table.AppCell / table.AppFooter
    tasks:
      - Wire up a React table with default reactivity and decide between initialState, atoms, and external
        state.
      - Optimize re-renders with a useTable selector or table.Subscribe at a specific subtree.
      - Hoist a pagination or filter slice into an external atom that other parts of the app subscribe to.
      - Build a reusable createTableHook with shared features, row models, and cellComponents / headerComponents
        / tableComponents.
    failure_modes:
      - mistake: Reading state via table.atoms.pagination.get() inside a component and expecting it to re-render
        mechanism:
          Atom .get() and table.store.state are current-value reads, not React subscriptions. They
          do not cause the component to re-render when the atom changes.
        wrong_pattern: |
          function Pager({ table }) {
            const pagination = table.atoms.pagination.get()
            return <span>Page {pagination.pageIndex + 1}</span>
          }
        correct_pattern: |
          function Pager({ table }) {
            return (
              <table.Subscribe
                source={table.atoms.pagination}
                selector={(p) => p.pageIndex}
              >
                {(pageIndex) => <span>Page {pageIndex + 1}</span>}
              </table.Subscribe>
            )
          }
        source: docs/framework/react/guide/table-state.md (Reading State Without Subscribing); examples/react/basic-subscribe/src/main.tsx
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Passing both atoms.pagination and state.pagination for the same slice
        mechanism:
          When a slice is owned both ways, external atoms take precedence over external state. The
          on[State]Change callback may stop firing or write into a base atom whose value is shadowed by the
          external atom, producing surprising divergence.
        wrong_pattern: |
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            atoms: { pagination: paginationAtom },
            state: { pagination },
            onPaginationChange: setPagination,
          })
        correct_pattern: |
          // Pick exactly one source of truth per slice.
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            atoms: { pagination: paginationAtom },
          })
        source: docs/framework/react/guide/table-state.md (Custom Initial State Note); examples/react/basic-external-atoms
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Using table.Subscribe inside a column cell / header definition
        mechanism:
          In cell and header render contexts, the table field is typed as the core Table<TFeatures,
          TData>, not the React-extended ReactTable, so table.Subscribe is not on the object. Calling it crashes
          or fails to compile.
        wrong_pattern: |
          columnHelper.display({
            id: 'select',
            cell: ({ row, table }) => (
              <table.Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
                {(isSelected) => <input type="checkbox" checked={!!isSelected} />}
              </table.Subscribe>
            ),
          })
        correct_pattern: |
          import { Subscribe } from '@tanstack/react-table'

          columnHelper.display({
            id: 'select',
            cell: ({ row, table }) => (
              <Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
                {(isSelected) => (
                  <input
                    type="checkbox"
                    checked={!!isSelected}
                    onChange={row.getToggleSelectedHandler()}
                  />
                )}
              </Subscribe>
            ),
          })
        source: docs/framework/react/guide/table-state.md (Tips section); examples/react/basic-subscribe/src/main.tsx
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
        skills:
          - react-subscribe-compiler-compat
      - &id001
        mistake: Quadratic slowdown from nested mergeObjects on every Svelte reactive tick
        mechanism: |
          `@tanstack/svelte-table` adapter wraps `setOptions` in `$effect.pre`, calling
          `setOptions(prev => mergeObjects(prev, mergedOptions))` on every reactive tick.
          `mergeObjects` builds a getter chain referencing the previous result; after N
          ticks `table.options` is N-deep. Reads of feature-default-only keys
          (`onExpandedChange`, etc.) walk the entire chain on every row-model evaluation,
          producing O(N²) work and visible freezes while typing into a filter input.
        wrong_pattern: |
          // ❌ Default svelte-table integration — the chain grows quadratically with keystrokes
          const table = createSvelteTable({
            data, columns, state: { globalFilter },
            getCoreRowModel: getCoreRowModel(),
          })
        correct_pattern: |
          // ✅ Override mergeOptions to flatten on each tick (workaround until upstream fix)
          const table = createSvelteTable({
            data, columns,
            mergeOptions: (prev, next) => {
              const result = {}
              const allKeys = new Set([...Reflect.ownKeys(prev), ...Reflect.ownKeys(next)])
              for (const key of allKeys) {
                const fromNext = next[key]
                result[key] = fromNext !== undefined ? fromNext : prev[key]
              }
              return result
            },
          })
        source:
          'https://github.com/TanStack/table/issues/6235 (svelte-table: nested mergeObjects in setOptions
          produces quadratic slowdown)'
        priority: CRITICAL
        status: active
        version_context:
          v9.0.0-alpha.32 (svelte). Same structural risk exists in other adapters if they re-call
          setOptions per tick.
        skills:
          - table-state
          - production-readiness
  - name: Vue Table State, Subscribe & createTableHook
    slug: table-state
    domain: framework-adapters
    description:
      Vue reactivity binding, useTable selector, table.Subscribe, FlexRender, and createTableHook
      composition for @tanstack/vue-table.
    type: framework
    packages:
      - '@tanstack/vue-table'
    covers:
      - useTable
      - useTable selector second argument
      - table.state (selected reactive state)
      - table.atoms / table.baseAtoms / table.store
      - table.Subscribe with selector
      - table.Subscribe with source
      - FlexRender component
      - vueReactivity (shallowRef + computed + watch flush sync)
      - createAtom from @tanstack/vue-store
      - useSelector from @tanstack/vue-store
      - reactive data / columns (ref or computed)
      - atoms / state / on[State]Change options
      - createTableHook
    tasks:
      - Pass a Vue ref or computed as data and let useTable re-sync via setOptions.
      - Choose between atoms ownership and state-plus-on[State]Change with getter wrappers for Vue refs.
      - Subscribe a small piece of the template to a single atom with table.Subscribe.
    failure_modes:
      - mistake: Passing a Vue ref directly to state.pagination without a getter
        mechanism:
          useTable reads state.pagination once when options resolve. Without a getter, the raw ref
          object is captured and the table never sees subsequent ref.value changes.
        wrong_pattern: |
          const pagination = ref<PaginationState>({ pageIndex: 0, pageSize: 10 })
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            state: { pagination },
            onPaginationChange: (u) => {
              pagination.value = u instanceof Function ? u(pagination.value) : u
            },
          })
        correct_pattern: |
          const pagination = ref<PaginationState>({ pageIndex: 0, pageSize: 10 })
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            state: {
              get pagination() { return pagination.value },
            },
            onPaginationChange: (u) => {
              pagination.value = u instanceof Function ? u(pagination.value) : u
            },
          })
        source: docs/framework/vue/guide/table-state.md (External State); examples/vue/basic-external-state
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Reading table.atoms.pagination.get() outside a reactive context and expecting Vue updates
        mechanism:
          Atom .get() is a current-value read. It only participates in Vue tracking when called inside
          a reactive scope such as a template, computed, or watch. From plain script setup top-level code
          it is a one-shot read.
        wrong_pattern: |
          const pagination = table.atoms.pagination.get() // read once, never updates
        correct_pattern: |
          const pagination = computed(() => table.atoms.pagination.get())
          // or
          // table.state.pagination via useTable selector
        source: docs/framework/vue/guide/table-state.md (Reading State Without Subscribing)
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Using the v8 useVueTable name
        mechanism:
          v9 renamed the adapter creator to useTable for every framework. useVueTable is no longer
          exported.
        wrong_pattern: |
          import { useVueTable } from '@tanstack/vue-table'
        correct_pattern: |
          import { useTable } from '@tanstack/vue-table'
        source: docs/framework/vue/vue-table.md; packages/vue-table/src/useTable.ts
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - *id001
  - name: Solid Table State, Subscribe & createTableHook
    slug: table-state
    domain: framework-adapters
    description:
      Solid reactivity binding, createTable selector, table.state() accessor, table.Subscribe,
      FlexRender, and createTableHook composition for @tanstack/solid-table.
    type: framework
    packages:
      - '@tanstack/solid-table'
    covers:
      - createTable
      - createTable selector second argument
      - table.state() (Solid accessor)
      - table.atoms / table.baseAtoms / table.store
      - table.Subscribe with selector
      - table.Subscribe with source (accessor children)
      - FlexRender component
      - solidReactivity (createSignal + createMemo)
      - createAtom from @tanstack/solid-store
      - useSelector from @tanstack/solid-store
      - reactive get data() getter pattern
      - atoms / state / on[State]Change options
      - createTableHook
    tasks:
      - Wire reactive Solid data via a get data() getter on the options object.
      - Read table.state() as an accessor inside JSX and computations.
      - Subscribe per-row UI to a single atom with table.Subscribe and an accessor child.
    failure_modes:
      - mistake: Reading table.state as a value instead of calling table.state() as an accessor
        mechanism:
          The Solid adapter returns table.state as a function accessor so reads can participate in
          Solid tracking. table.state.pagination accesses a property on the function and is undefined.
        wrong_pattern: |
          const page = table.state.pagination.pageIndex // undefined
        correct_pattern: |
          const page = table.state().pagination.pageIndex
        source: docs/framework/solid/guide/table-state.md (Reading Reactive State with createTable)
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Passing data as a plain reactive accessor value instead of a getter
        mechanism:
          Solid loses fine-grained reactivity once a signal value is destructured into a plain object.
          Without a get data() getter, createTable never re-syncs setOptions when the underlying signal changes.
        wrong_pattern: |
          const [data] = createSignal(makeData(100))
          const table = createTable({
            _features,
            _rowModels: {},
            columns,
            data: data(),
          })
        correct_pattern: |
          const [data] = createSignal(makeData(100))
          const table = createTable({
            _features,
            _rowModels: {},
            columns,
            get data() { return data() },
          })
        source: docs/framework/solid/guide/table-state.md (Reading Reactive State with createTable); examples/solid/basic-use-table/src/App.tsx
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Using table.Subscribe child callback as a raw value
        mechanism:
          In Solid, table.Subscribe child receives an accessor function. Treating it as a value renders
          the function reference, not the selected state.
        wrong_pattern: |
          <table.Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
            {(isSelected) => <input type="checkbox" checked={!!isSelected} />}
          </table.Subscribe>
        correct_pattern: |
          <table.Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
            {(isSelected) => (
              <input
                type="checkbox"
                checked={!!isSelected()}
                onChange={row.getToggleSelectedHandler()}
              />
            )}
          </table.Subscribe>
        source: docs/framework/solid/guide/table-state.md (Fine-grained Updates with table.Subscribe)
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - *id001
    maintainer_notes:
      - 'Signal-based adapter: TanStack Store atoms and native framework state are equally supported. Most
        developers prefer native state (Solid signals, Angular signals, Svelte runes). The skill should lead
        with native-state patterns and treat atoms as the alternative for cross-app state sharing.'
  - name: Svelte Table State, subscribeTable & createTableHook
    slug: table-state
    domain: framework-adapters
    description:
      Svelte 5 rune reactivity, createTable selector, table.state, subscribeTable .current pattern,
      FlexRender, and createTableHook composition for @tanstack/svelte-table.
    type: framework
    packages:
      - '@tanstack/svelte-table'
    covers:
      - createTable
      - createTable selector second argument
      - table.state (selected rune-tracked state)
      - table.atoms / table.baseAtoms / table.store
      - subscribeTable (atom or store source)
      - subscribeTable .current accessor
      - FlexRender Svelte component
      - svelteReactivity ($state + $derived.by + $effect.pre)
      - createAtom / useSelector from @tanstack/svelte-store
      - reactive get data() getter pattern
      - atoms / state / on[State]Change options with $state getters
      - createTableHook
    tasks:
      - Bind table data to a Svelte 5 $state variable through a get data() getter.
      - Use subscribeTable to expose a per-slice rune-friendly reactive value with .current.
      - Control sorting or pagination via $state + getter + on[State]Change updater pattern.
    failure_modes:
      - mistake: Using subscribeTable result as a value instead of reading .current
        mechanism:
          subscribeTable returns a rune-friendly wrapper whose selected value lives behind .current.
          Treating the wrapper itself as the value renders an object, not the page index.
        wrong_pattern: |
          const pageIndex = subscribeTable(
            table.atoms.pagination,
            (p) => p.pageIndex,
          )
          // template
          // <span>Page {pageIndex + 1}</span>
        correct_pattern: |
          const pageIndex = subscribeTable(
            table.atoms.pagination,
            (p) => p.pageIndex,
          )
          // template
          // <span>Page {pageIndex.current + 1}</span>
        source: docs/framework/svelte/guide/table-state.md (Fine-grained Updates with subscribeTable)
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47; Svelte 5+ only
      - mistake: Passing $state values directly to options.state without getters
        mechanism:
          createTable resolves options once and reads state.pagination as a snapshot. Without a getter,
          runes do not surface the latest value to the table, and the controlled slice falls out of sync.
        wrong_pattern: |
          let pagination = $state({ pageIndex: 0, pageSize: 10 })
          const table = createTable({
            _features,
            _rowModels: {},
            columns,
            data,
            state: { pagination },
            onPaginationChange: (u) => {
              pagination = u instanceof Function ? u(pagination) : u
            },
          })
        correct_pattern: |
          let pagination = $state({ pageIndex: 0, pageSize: 10 })
          const table = createTable({
            _features,
            _rowModels: {},
            columns,
            get data() { return data },
            state: {
              get pagination() { return pagination },
            },
            onPaginationChange: (u) => {
              pagination = u instanceof Function ? u(pagination) : u
            },
          })
        source: docs/framework/svelte/guide/table-state.md (External State); examples/svelte/basic-external-state
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47; Svelte 5+ only
      - mistake: Using the legacy createSvelteTable name from Svelte 4 era
        mechanism:
          v9 is Svelte 5+ only and exports createTable. Older codebases referencing createSvelteTable
          will fail to import.
        wrong_pattern: |
          import { createSvelteTable } from '@tanstack/svelte-table'
        correct_pattern: |
          import { createTable } from '@tanstack/svelte-table'
        source: packages/svelte-table/src/createTable.svelte.ts; docs/framework/svelte/svelte-table.md
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47; Svelte 5+ only
      - *id001
    maintainer_notes:
      - 'Signal-based adapter: TanStack Store atoms and native framework state are equally supported. Most
        developers prefer native state (Solid signals, Angular signals, Svelte runes). The skill should lead
        with native-state patterns and treat atoms as the alternative for cross-app state sharing.'
  - name: Angular Table State & injectTable
    slug: table-state
    domain: framework-adapters
    description:
      Angular signal reactivity binding, injectTable lazy initializer, atom-as-signal reads,
      computed selection with shallow equality, and createTableHook composition for @tanstack/angular-table.
    type: framework
    packages:
      - '@tanstack/angular-table'
    covers:
      - injectTable
      - injectTable initializer function form
      - table.atoms / table.baseAtoms / table.store
      - angularReactivity(injector) (signal + computed + toObservable)
      - shallow equality helper
      - computed selectors with equal option
      - signal-based state ownership via state plus on[State]Change
      - atoms option (core re-export, advanced)
      - initialState
      - createTableHook
    tasks:
      - Convert v8 createAngularTable usage to injectTable lazy initializer with signal reads.
      - Select a state slice with computed(...) and the shallow equality helper to avoid extra change detection.
      - Control sorting and pagination via signal + state + on[State]Change update/set pattern.
    failure_modes:
      - mistake: Calling injectTable with a plain options object instead of an initializer function
        mechanism:
          injectTable expects a () => options factory and reruns it when read signals change. Passing
          a plain object skips signal tracking and the table never resyncs when source signals update.
        wrong_pattern: |
          readonly table = injectTable({
            _features,
            _rowModels: {},
            columns,
            data: this.data(),
          })
        correct_pattern: |
          readonly table = injectTable(() => ({
            _features,
            _rowModels: {},
            columns,
            data: this.data(),
          }))
        source:
          docs/framework/angular/guide/table-state.md (Feature-based State); packages/angular-table/src/injectTable.ts;
          examples/angular/basic-inject-table
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47; Angular >=19 with signals
      - mistake: Using the v8 createAngularTable name
        mechanism:
          v9 renamed the adapter creator to injectTable to match Angular DI conventions. createAngularTable
          is no longer exported.
        wrong_pattern: |
          import { createAngularTable } from '@tanstack/angular-table'
        correct_pattern: |
          import { injectTable } from '@tanstack/angular-table'
        source: docs/framework/angular/angular-table.md; packages/angular-table/src/injectTable.ts
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Selecting object slices with computed without shallow equality
        mechanism:
          'Object/array slice references change on every store update even when their contents are
          unchanged. Without { equal: shallow }, downstream computeds and templates re-run unnecessarily,
          defeating fine-grained signal performance.'
        wrong_pattern: |
          readonly pagination = computed(() => this.table.store.state.pagination)
        correct_pattern: |
          import { shallow } from '@tanstack/angular-table'

          readonly pagination = computed(
            () => this.table.store.state.pagination,
            { equal: shallow },
          )
        source: docs/framework/angular/guide/table-state.md (Selecting State with Angular computed)
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - *id001
    maintainer_notes:
      - 'Signal-based adapter: TanStack Store atoms and native framework state are equally supported. Most
        developers prefer native state (Solid signals, Angular signals, Svelte runes). The skill should lead
        with native-state patterns and treat atoms as the alternative for cross-app state sharing.'
  - name: Lit Table State & createTableHook
    slug: table-state
    domain: framework-adapters
    description:
      Lit TableController reactive controller, atom subscription, table.state selector, table.Subscribe
      render, FlexRender, and createTableHook composition for @tanstack/lit-table.
    type: framework
    packages:
      - '@tanstack/lit-table'
    covers:
      - TableController
      - tableController.table(options, selector?)
      - table.state (selected state)
      - table.atoms / table.baseAtoms / table.store
      - table.Subscribe with selector or source
      - table.FlexRender
      - litReactivity
      - createAtom from @tanstack/store
      - atoms / state / on[State]Change options
      - ReactiveControllerHost integration with requestUpdate
      - createTableHook
    tasks:
      - Instantiate one TableController per LitElement host and call .table(...) inside render.
      - Use table.state with a selector to keep render output focused on needed slices.
      - Control sorting via Lit @state and pass state + onSortingChange updater.
    failure_modes:
      - mistake: Creating a new TableController inside render() on every update
        mechanism:
          TableController owns the underlying table instance and subscriptions. Constructing it in
          render creates fresh subscriptions and discards prior state every cycle, causing data loss and double-subscribed
          host updates.
        wrong_pattern: |
          protected render() {
            const tableController = new TableController<typeof _features, Person>(this)
            const table = tableController.table({
              _features,
              _rowModels: {},
              columns,
              data: this._data,
            })
            return html`...`
          }
        correct_pattern: |
          private tableController = new TableController<typeof _features, Person>(this)

          protected render() {
            const table = this.tableController.table({
              _features,
              _rowModels: {},
              columns,
              data: this._data,
            })
            return html`...`
          }
        source: packages/lit-table/src/TableController.ts; docs/framework/lit/guide/table-state.md; examples/lit/basic-table-controller/src/main.ts
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Expecting source-only host invalidation from table.Subscribe with a source prop
        mechanism:
          TableController currently wires host requestUpdate through the full table.store and optionsStore
          subscriptions. table.Subscribe with a source is render-time selection sugar, not a per-source invalidation
          guarantee.
        wrong_pattern: |
          // assuming this avoids host invalidation when other slices change
          ${table.Subscribe({
            source: table.atoms.rowSelection,
            selector: (s) => s[row.id],
            children: (isSelected) => html`<input type="checkbox" .checked=${!!isSelected} />`,
          })}
        correct_pattern: |
          // accept that the host updates on any store change; use Subscribe for cleaner render code
          ${table.Subscribe({
            selector: (state) => state.pagination,
            children: (pagination) => html`<span>Page ${pagination.pageIndex + 1}</span>`,
          })}
        source: packages/lit-table/src/TableController.ts (LitTable Subscribe note); docs/framework/lit/guide/table-state.md
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Reading atom.get() in render and never seeing UI update
        mechanism:
          Atom .get() reads a value but does not register with the controller. Host invalidation
          is wired through the full table.store subscription, so updates that change the read slice still
          trigger render, but state from a non-controller-bound atom that is not part of table.store will
          not invalidate the host.
        wrong_pattern: |
          // separate atom not passed via atoms option
          const externalAtom = createAtom({ count: 0 })

          protected render() {
            return html`<span>${externalAtom.get().count}</span>`
          }
        correct_pattern: |
          // wire external atoms through table.atoms or maintain a separate subscription
          private tableController = new TableController<typeof _features, Person>(this)
          private _externalAtom = createAtom({ count: 0 })
          private _unsub?: () => void

          connectedCallback() {
            super.connectedCallback()
            this._unsub = this._externalAtom.subscribe(() => this.requestUpdate())
          }

          disconnectedCallback() {
            super.disconnectedCallback()
            this._unsub?.()
          }
        source: docs/framework/lit/guide/table-state.md (Reading State Without Subscribing); packages/lit-table/src/TableController.ts
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47
      - *id001
    maintainer_notes:
      - Lit adapter is scheduled for a rewrite with TanStack Lit Store during beta. Treat the current API
        as v9-alpha; expect refinements in beta.
  - name: Preact Table State, Subscribe & createTableHook
    slug: table-state
    domain: framework-adapters
    description:
      Preact reactivity binding mirroring React, useTable selector, table.Subscribe rendering,
      FlexRender, and createTableHook composition for @tanstack/preact-table.
    type: framework
    packages:
      - '@tanstack/preact-table'
    covers:
      - useTable
      - useTable selector second argument
      - table.state (selected state)
      - table.atoms / table.baseAtoms / table.store
      - table.Subscribe with selector or source
      - Subscribe (standalone)
      - table.FlexRender
      - useCreateAtom from @tanstack/preact-store
      - useSelector from @tanstack/preact-store
      - atoms / state / on[State]Change options
      - initialState
      - createTableHook (createAppColumnHelper, useAppTable, useTableContext, useCellContext, useHeaderContext)
    tasks:
      - Set up useTable in Preact with stable references for data, columns, and _features.
      - Optimize a large Preact table by passing () => null as the selector and subscribing lower in the tree.
      - Build reusable component registries with createTableHook in Preact.
    failure_modes:
      - mistake: Recreating columns or _features on every render
        mechanism:
          Preact relies on stable references for table options. New columns or _features arrays each
          render force useTable to call setOptions and rebuild derived state, undoing the work selectors and
          Subscribe are meant to save.
        wrong_pattern: |
          function App({ data }) {
            const columns = [
              { accessorKey: 'firstName', header: 'First name' },
            ]
            const _features = tableFeatures({})
            const table = useTable({
              _features,
              _rowModels: {},
              columns,
              data,
            })
            return null
          }
        correct_pattern: |
          const _features = tableFeatures({})
          const columns = [
            { accessorKey: 'firstName', header: 'First name' },
          ]

          function App({ data }) {
            const table = useTable({
              _features,
              _rowModels: {},
              columns,
              data,
            })
            return null
          }
        source: docs/framework/preact/preact-table.md; examples/preact/basic-use-table/src/main.tsx
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Using table.Subscribe inside a cell or header render context
        mechanism:
          The cell and header table field is typed as the core Table<TFeatures, TData> and does not
          expose Subscribe. Import the standalone Subscribe and pass source={table.store}.
        wrong_pattern: |
          cell: ({ row, table }) => (
            <table.Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
              {(isSelected) => <input type="checkbox" checked={!!isSelected} />}
            </table.Subscribe>
          )
        correct_pattern: |
          import { Subscribe } from '@tanstack/preact-table'

          cell: ({ row, table }) => (
            <Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
              {(isSelected) => (
                <input
                  type="checkbox"
                  checked={!!isSelected}
                  onChange={row.getToggleSelectedHandler()}
                />
              )}
            </Subscribe>
          )
        source:
          docs/framework/preact/guide/table-state.md (Optimizing Re-renders with Selectors and table.Subscribe);
          packages/preact-table/src/Subscribe.ts
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Passing useTable both atoms.pagination and state.pagination for the same slice
        mechanism:
          External atoms take precedence over external state. Mixing them silently hides on[State]Change-driven
          setState writes and leaves React-style state stale.
        wrong_pattern: |
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            atoms: { pagination: paginationAtom },
            state: { pagination },
            onPaginationChange: setPagination,
          })
        correct_pattern: |
          // Pick exactly one source of truth per slice.
          const table = useTable({
            _features,
            _rowModels: {},
            columns,
            data,
            atoms: { pagination: paginationAtom },
          })
        source: docs/framework/preact/guide/table-state.md (Custom Initial State Note); examples/preact/basic-external-atoms
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - *id001
  - name: React Subscribe for React Compiler Compatibility
    slug: react-subscribe-compiler-compat
    domain: framework-adapters
    description:
      Use Subscribe / table.Subscribe to keep nested header and cell components correct under
      React Compiler memoization.
    type: framework
    packages:
      - '@tanstack/react-table'
    covers:
      - Subscribe (standalone import)
      - table.Subscribe (from useTable result)
      - source prop (atom or store)
      - selector prop
      - render-prop children
      - useSelector under the hood
      - table.store
      - table.atoms.rowSelection / columnPinning / etc.
    tasks:
      - Wrap row-selection or pin-button JSX inside nested header/cell components in Subscribe to prevent
        React Compiler from memoizing stale state reads.
      - Choose between subscribing to table.store with a selector vs subscribing to a single atom for per-row
        UI.
      - Audit a table for builder-pattern reads inside custom component boundaries that are likely memoization
        risks.
    failure_modes:
      - mistake:
          Reading column.getIsPinned() / row.getIsSelected() / cell.getIsAggregated() inside a custom
          child component and not wrapping in Subscribe
        mechanism:
          React Compiler memoizes the child's JSX against the stable column / row / cell reference
          it receives. The state-dependent builder method hides its atom dependency from the compiler, so
          the memoized JSX never re-runs when the underlying atom changes.
        wrong_pattern: |
          function DraggableHeader({ header }) {
            const isPinned = header.column.getIsPinned()
            return <th data-pinned={isPinned}>{header.column.id}</th>
          }
        correct_pattern: |
          import { Subscribe } from '@tanstack/react-table'

          function DraggableHeader({ header, table }) {
            return (
              <Subscribe
                source={table.store}
                selector={(s) => s.columnPinning}
              >
                {() => {
                  const isPinned = header.column.getIsPinned()
                  return <th data-pinned={isPinned}>{header.column.id}</th>
                }}
              </Subscribe>
            )
          }
        source:
          docs/framework/react/guide/table-state.md (Subscribe for React Compiler Compatibility); examples/react/basic-subscribe/src/main.tsx;
          packages/react-table/src/Subscribe.ts
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47; React Compiler enabled
      - mistake:
          Using table.Subscribe from inside a cell or header definition where table is the core Table
          type
        mechanism:
          Cell and header render contexts type table as Table<TFeatures, TData>, not ReactTable.
          table.Subscribe is undefined. The fix is to import the standalone Subscribe and pass source={table.store}
          or source={table.atoms.X}.
        wrong_pattern: |
          cell: ({ row, table }) => (
            <table.Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
              {(isSelected) => <input type="checkbox" checked={!!isSelected} />}
            </table.Subscribe>
          )
        correct_pattern: |
          import { Subscribe } from '@tanstack/react-table'

          cell: ({ row, table }) => (
            <Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
              {(isSelected) => (
                <input
                  type="checkbox"
                  checked={!!isSelected}
                  onChange={row.getToggleSelectedHandler()}
                />
              )}
            </Subscribe>
          )
        source: docs/framework/react/guide/table-state.md (Tips); packages/react-table/src/Subscribe.ts
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Wrapping every cell in Subscribe by default
        mechanism:
          Subscribe is overhead. For inline JSX in the parent component, the compiler always re-evaluates
          when the parent re-renders, so wrapping is unnecessary. Over-wrapping adds subscription churn without
          correctness benefit.
        wrong_pattern: |
          // Inline cell that already re-runs each parent render
          {row.getVisibleCells().map((cell) => (
            <Subscribe source={table.store} selector={(s) => s.rowSelection}>
              {() => <td>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>}
            </Subscribe>
          ))}
        correct_pattern: |
          {row.getVisibleCells().map((cell) => (
            <td key={cell.id}>
              <table.FlexRender cell={cell} />
            </td>
          ))}
        source: docs/framework/react/guide/table-state.md (Subscribe for React Compiler Compatibility)
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Subscribing to the whole table.store for one row's selection checkbox
        mechanism:
          Every store change re-renders the Subscribe child. Subscribing to table.atoms.rowSelection
          (or a per-row selector returning s[row.id]) limits re-renders to actual selection changes for that
          row.
        wrong_pattern: |
          <Subscribe source={table.store} selector={(s) => s.rowSelection[row.id]}>
            {(isSelected) => <input type="checkbox" checked={!!isSelected} />}
          </Subscribe>
        correct_pattern: |
          <Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
            {(isSelected) => (
              <input
                type="checkbox"
                checked={!!isSelected}
                onChange={row.getToggleSelectedHandler()}
              />
            )}
          </Subscribe>
        source: docs/framework/react/guide/table-state.md (Tips bullets); examples/react/basic-subscribe/src/main.tsx
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Reading raw v8 state on v9 ReactTable instead of using Subscribe
        mechanism: |
          v9 ReactTable returns an object whose state slices live on `table.atoms.*` / `table.store`.
          Reading `table.getState().rowSelection` directly during render does not subscribe the
          component — the table only re-renders when its top-level state ref changes, so checkbox
          visuals, sort indicators, and pagination text go stale unless you use `<table.Subscribe>`
          or a state selector.
        wrong_pattern: |
          // ❌ Reads state during render — does NOT subscribe in v9 alpha
          function Toolbar({ table }) {
            const { rowSelection, sorting } = table.getState()
            return <div>{Object.keys(rowSelection).length} selected</div>
          }
        correct_pattern: |
          // ✅ Use table.Subscribe to opt into reactive updates
          function Toolbar({ table }) {
            return (
              <table.Subscribe
                selector={(s) => ({ count: Object.keys(s.rowSelection).length })}
              >
                {({ count }) => <div>{count} selected</div>}
              </table.Subscribe>
            )
          }
        source:
          'PR #6246 "feat: change default state selectors to all"; PR #6244 (options store refactor);
          useTable.ts JSDoc examples'
        priority: CRITICAL
        status: active
        version_context:
          v9 alpha pattern. Agents trained on v8 will reach for table.getState() and never
          subscribe. Default selector now subscribes to ALL state slices since alpha.47, but selectors are
          the documented pattern.
        skills:
          - react-subscribe-compiler-compat
          - table-state
          - customizing-feature-behavior
      - mistake: setOptions in render body causing SubscribeBound warning
        mechanism: |
          Since alpha.20, `useTable` calls `table.setOptions()` during render instead of in
          `useEffect`. That synchronously flushes store subscribers — including `SubscribeBound`
          — so React warns "Cannot update a component (SubscribeBound) while rendering a
          different component (Table)". The warning trips even on a single state change to a
          parent prop because `optionsStore.setState() → atom.set() → propagate() → flush()`
          all run synchronously inside the parent's render phase.
        wrong_pattern: |
          // ❌ Common v9 alpha setup — surfaces SubscribeBound warning on every parent rerender
          function MyTable({ globalFilter }) {
            const table = useTable({ _features, data, columns, state: { globalFilter } })
            return (
              <table.Subscribe selector={s => ({ globalFilter: s.globalFilter })}>
                {() => <span>...</span>}
              </table.Subscribe>
            )
          }
        correct_pattern: |
          // ✅ Until the upstream fix lands, drive controlled state through onChange handlers
          //    so `state` doesn't change on every parent render, or wait for the post-alpha.47 fix.
          //    See PR #6244 / #6246 — KevinVandy's WIP refactor of the optionsStore for react/preact.
          function MyTable() {
            const [globalFilter, setGlobalFilter] = useState('')
            const table = useTable({
              _features, data, columns,
              state: { globalFilter },
              onGlobalFilterChange: setGlobalFilter,
            })
            return <table.Subscribe selector={s => ({ globalFilter: s.globalFilter })}>
              {() => <span>...</span>}
            </table.Subscribe>
          }
        source:
          'https://github.com/TanStack/table/issues/6224 (alpha: useTable causes "Cannot update a component
          (SubscribeBound)")'
        priority: CRITICAL
        status: active
        version_context:
          'v9.0.0-alpha.20+ regression. Owner discussion in comments shows PR #6244 attempts
          a fix by removing optionsStore from react/preact adapters.'
        skills:
          - react-subscribe-compiler-compat
          - composable-tables
      - mistake: Trying to subscribe to table.options.meta
        mechanism: |
          `table.Subscribe` subscribes to `table.store` / atoms — not to `table.options`.
          Putting external state into `meta` and trying to subscribe to it via a selector
          will never fire updates because options aren't part of the reactive state graph.
        wrong_pattern: |
          // ❌ meta lives on options, not store — Subscribe will never re-fire
          const table = useTable({ ..., meta: { foo: someState } })
          <table.Subscribe selector={(s) => s.options?.meta?.foo}>
            {(foo) => <span>{foo}</span>}
          </table.Subscribe>
        correct_pattern: |
          // ✅ Keep external reactive data outside the table or push it into a real state slice.
          //    For values needed inside cells, close over them in the columns array (recreate
          //    columns when the value changes) or pass them via React context.
          const ExternalContext = React.createContext(null)
          <ExternalContext.Provider value={foo}>
            <TableUI table={table} />
          </ExternalContext.Provider>
        source: https://github.com/TanStack/table/issues/6236 (Unable to subscribe to table.options.meta)
        priority: HIGH
        status: active
        version_context:
          v9 alpha; subtle because meta worked as a stash bucket in v8 and people assume Subscribe
          covers it
        skills:
          - react-subscribe-compiler-compat
          - table-state
      - mistake: Input loses focus inside composable AppTable on every keystroke
        mechanism: |
          In v9 alpha.12 (and via store v0.9 update in PR #6180), keying off a state-driven
          selector inside `<table.AppTable>` caused inputs nested in toolbars/cells to lose
          focus after each keypress because the entire subtree re-mounted. The fix landed
          between alpha.12 → alpha.32 via the atoms refactor (PR #6234), but the underlying
          lesson — Subscribe-driven children must NOT cause input remounts — is still load-bearing.
        wrong_pattern: |
          // ❌ Selecting a frequently-changing slice from the top-level table.AppTable boundary
          //    can remount everything under it.
          <table.AppTable selector={(s) => ({ globalFilter: s.globalFilter })}>
            <TableToolbar>
              <input value={globalFilter} onChange={...} />  {/* loses focus */}
            </TableToolbar>
          </table.AppTable>
        correct_pattern: |
          // ✅ Push the Subscribe boundary as close to the consumer as possible
          <table.AppTable>
            <TableToolbar>
              {/* keep input outside Subscribe; subscribe only inside the bit that needs it */}
              <input value={globalFilter} onChange={...} />
              <table.Subscribe selector={(s) => s.globalFilter}>
                {(filter) => <span>filter: {filter}</span>}
              </table.Subscribe>
            </TableToolbar>
          </table.AppTable>
        source:
          'https://github.com/TanStack/table/issues/6199 (Bug[v9]: broken inputs inside a composable
          table)'
        priority: HIGH
        status: fixed-but-legacy-risk
        version_context: v9 alpha.12 regression, fixed by alpha.32. Pattern lesson still applies.
        skills:
          - react-subscribe-compiler-compat
          - composable-tables
      - mistake: Using v8 useReactTable with React Compiler skips memoization
        mechanism: |
          React Compiler emits "Use of incompatible library" warning when it sees
          `useReactTable()` because the returned table instance has mutable methods whose
          references change. Compiler bails out and skips memoization for that component,
          defeating the optimization. The v9 alpha Subscribe pattern is the answer — agents
          should NOT add `'use no memo'` pragmas as a workaround.
        wrong_pattern: |
          // ❌ React Compiler skips this entire component
          'use client'
          import { useReactTable, getCoreRowModel } from '@tanstack/react-table'
          export function DataTable({ columns, data }) {
            const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() })
            return <Table table={table} />
          }
        correct_pattern: |
          // ✅ Move to v9 alpha useTable + Subscribe; opt-in subscription model is React-Compiler-friendly
          'use client'
          import { useTable, tableFeatures, rowSelectionFeature } from '@tanstack/react-table'
          const _features = tableFeatures({ rowSelectionFeature })
          export function DataTable({ columns, data }) {
            const table = useTable({ _features, data, columns })
            return (
              <table.Subscribe selector={(s) => ({ rowSelection: s.rowSelection })}>
                {() => <Table table={table} />}
              </table.Subscribe>
            )
          }
        source:
          https://github.com/TanStack/table/issues/6137 (React Compiler skips memoization), https://github.com/TanStack/table/issues/5567
          (Table doesn’t re-render with new React Compiler + React 19)
        priority: CRITICAL
        status: active
        version_context:
          v8 fundamental limitation. The whole v9 alpha redesign exists to fix this. Agents
          trained on v8 will keep producing the broken pattern.
      - mistake: Table does not re-render when data changes under React Compiler
        mechanism: |
          With React Compiler enabled and React 19, mutating an array used as `data` and
          then setting the state doesn't cause the table body to re-render because the
          compiler memoizes `table.getRowModel().rows` based on the (unchanged) table
          reference. The v8 row-model output is a method call, so the compiler can't tell
          it depends on `data` identity.
        wrong_pattern: |
          // ❌ data updates but rows don't refresh
          const [data, setData] = useState([])
          const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() })
          function addRow() {
            setData([...data, newRow])  // table.getRowModel().rows is memoized stale
          }
        correct_pattern: |
          // ✅ Use v9 alpha — table.Subscribe drives re-renders explicitly
          const table = useTable({ _features, data, columns })
          <table.Subscribe selector={(s) => s.rowSelection}>
            {() => (
              <tbody>
                {table.getRowModel().rows.map(row => <Row row={row} />)}
              </tbody>
            )}
          </table.Subscribe>
        source: https://github.com/TanStack/table/issues/5567 (29 comments)
        priority: CRITICAL
        status: active
        version_context:
          v8 + React Compiler — top-engagement open issue with 29 comments; v9 alpha designed
          specifically to address this
        skills:
          - react-subscribe-compiler-compat
          - state-management
      - mistake: Premature Subscribe / custom selector optimization on small tables
        mechanism:
          Subscribe and narrow selectors are designed for large or expensive tables where full re-renders
          measurably hurt. On small tables (a few hundred rows, simple features), default selector + inline
          rendering is fine and the Subscribe boundaries add complexity without measurable benefit.
        wrong_pattern: |-
          // ❌ Wraps every header and cell in Subscribe on a 50-row table
          header: ({ table }) => (
            <Subscribe source={table.store} selector={(s) => s.sorting}>
              {() => <SortHeader header={header} />}
            </Subscribe>
          )
        correct_pattern: |-
          // ✅ Default useTable selector, inline rendering — Subscribe only when measured perf demands it
          const table = useTable({ _features, _rowModels, columns, data })
          // reach for Subscribe later, scoped to the actual hotspot
        priority: MEDIUM
        version_context: 'Maintainer guidance: advanced state-management patterns are for advanced cases.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
  - name: Angular Rendering Directives & DI Context
    slug: angular-rendering-directives
    domain: framework-adapters
    description:
      Structural directives flexRender / flexRenderCell / flexRenderHeader / flexRenderFooter
      plus context tokens for prop-drill-free Angular rendering.
    type: framework
    packages:
      - '@tanstack/angular-table'
    covers:
      - FlexRender (tuple export of FlexRenderDirective and FlexRenderCell)
      - '*flexRender structural directive'
      - '*flexRenderCell shorthand'
      - '*flexRenderHeader shorthand'
      - '*flexRenderFooter shorthand'
      - flexRenderProps input
      - flexRenderComponent(component, options)
      - inputs / outputs / bindings / directives / injector options
      - inputBinding / outputBinding / twoWayBinding (Angular v20+)
      - injectFlexRenderContext
      - TanStackTable directive + injectTableContext / TanStackTableToken
      - TanStackTableHeader directive + injectTableHeaderContext / TanStackTableHeaderToken
      - TanStackTableCell directive + injectTableCellContext / TanStackTableCellToken
      - TemplateRef rendering with implicit context
    tasks:
      - Render cells and headers with the shorthand structural directives, falling back to *flexRender for
        custom props.
      - Pass dynamic inputs and outputs to a cell component with flexRenderComponent.
      - Eliminate input drilling by applying tanStackTableCell / tanStackTableHeader / tanStackTable directives
        and injecting context tokens in descendants.
    failure_modes:
      - mistake: Forgetting to import FlexRender in a standalone component
        mechanism:
          FlexRender is exported as a tuple of directives. Angular standalone components only see
          directives that are listed in imports, so without the import, *flexRender and *flexRenderCell silently
          do nothing or fail template compilation.
        wrong_pattern: |
          @Component({
            imports: [],
            templateUrl: './app.html',
          })
          export class AppComponent {}
        correct_pattern: |
          import { FlexRender } from '@tanstack/angular-table'

          @Component({
            imports: [FlexRender],
            templateUrl: './app.html',
          })
          export class AppComponent {}
        source: docs/framework/angular/guide/rendering.md (FlexRender import)
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47; Angular >=19
      - mistake:
          Returning a component class but expecting all CellContext properties to be visible without
          input signals
        mechanism:
          FlexRender wires render context onto the component via ComponentRef.setInput, but only
          declared input() / input.required() properties receive values. Undeclared properties are silently
          ignored.
        wrong_pattern: |
          @Component({ template: `{{ cell.getValue() }}` })
          export class MyCellComponent {
            cell: any // not declared as input
          }
        correct_pattern: |
          import { Component, input } from '@angular/core'
          import type { CellContext } from '@tanstack/angular-table'

          @Component({ template: `{{ cell().getValue() }}` })
          export class MyCellComponent {
            readonly cell = input.required<CellContext<any, any, any>>()
          }
        source: docs/framework/angular/guide/rendering.md (Returning a component class)
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47; Angular >=19
      - mistake: Mixing bindings with inputs / outputs on the same property in flexRenderComponent
        mechanism:
          bindings are applied at component creation, inputs / outputs are applied post-creation.
          Combining them on the same property causes double initialization or conflicting values.
        wrong_pattern: |
          flexRenderComponent(EditableCell, {
            inputs: { value: 'a' },
            bindings: [inputBinding('value', this.name)],
          })
        correct_pattern: |
          flexRenderComponent(EditableCell, {
            bindings: [
              inputBinding('value', this.name),
              outputBinding('valueChange', (v) => console.log(v)),
            ],
          })
        source: docs/framework/angular/guide/rendering.md (bindings API note)
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47; Angular v20+ for bindings
      - mistake: Drilling cell or header through input() in nested presentational components
        mechanism:
          Using FlexRender + context directives makes injectTableCellContext / injectTableHeaderContext
          / injectTableContext available to any descendant of the [tanStackTableCell] / [tanStackTableHeader]
          / [tanStackTable] host. Drilling defeats the DI pattern and complicates refactors.
        wrong_pattern: |
          <td [tanStackTableCell]="cell">
            <app-cell-actions [cell]="cell" />
          </td>
        correct_pattern: |
          <td [tanStackTableCell]="cell">
            <app-cell-actions />
          </td>

          // app-cell-actions.ts
          import { injectTableCellContext } from '@tanstack/angular-table'

          @Component({ template: `<button (click)=\"onAction()\">Act</button>` })
          export class CellActionsComponent {
            readonly cell = injectTableCellContext()
            onAction() { console.log(this.cell()) }
          }
        source: docs/framework/angular/guide/rendering.md (Context directives)
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47; Angular >=19
      - mistake:
          Calling injectFlexRenderContext outside a *flexRender rendered subtree without applying the
          corresponding context directive
        mechanism:
          Tokens are only provided in the child injector that FlexRender creates, or where the [tanStackTable]
          / [tanStackTableHeader] / [tanStackTableCell] directives are applied. Components outside both scopes
          throw a NullInjectorError.
        wrong_pattern: |
          // Sibling component in the same <td> as a *flexRenderCell-rendered cell
          <td>
            <ng-container *flexRenderCell=\"cell\" />
            <app-cell-actions />
          </td>
        correct_pattern: |
          <td [tanStackTableCell]=\"cell\">
            <ng-container *flexRenderCell=\"cell\" />
            <app-cell-actions />
          </td>
        source: docs/framework/angular/guide/rendering.md (Automatic token injection in FlexRender)
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47; Angular >=19
      - mistake: Defining columns inside createAngularTable signal causes flexRender remount on every tick
        mechanism: |
          When the `columns` array is defined inside the `createAngularTable` options
          function, Angular recreates the array on every reactive update. `FlexRenderComponent`
          sees new references and remounts components, running `ngOnInit` every time —
          tanking performance.
        wrong_pattern: |
          // ❌ Columns recreated inside the signal scope
          table = createAngularTable(() => ({
            data: this.data(),
            columns: [
              { id: 'name', header: 'Name', cell: flexRenderComponent(NameCell) },
            ],
            getCoreRowModel: getCoreRowModel(),
          }))
        correct_pattern: |
          // ✅ Hoist columns out of the options function
          private columns = [
            { id: 'name', header: 'Name', cell: flexRenderComponent(NameCell) },
          ]
          table = createAngularTable(() => ({
            data: this.data(),
            columns: this.columns,
            getCoreRowModel: getCoreRowModel(),
          }))
        source: https://github.com/TanStack/table/issues/6159 ([Angular Table] poor performance of flexRenderComponent)
        priority: CRITICAL
        status: active
        version_context:
          v8.21.3 angular, also affects v9. Doc gap acknowledged by maintainers in the closed-as-docs
          label.
        skills:
          - angular-rendering-directives
          - rendering
      - mistake: createAngularTable in library project emits ɵSIGNAL TS4023
        mechanism: |
          When `createAngularTable` is used in a buildable Angular library, the inferred
          return type references internal `@angular/core` symbols (`SIGNAL`, `ɵSIGNAL`)
          that can't be named from outside. Build fails with TS4023.
        wrong_pattern: |
          // ❌ In a library file; build fails
          @Component(...)
          export class MyTable {
            table = createAngularTable(() => ({ data, columns, getCoreRowModel: getCoreRowModel() }))
          }
        correct_pattern: |
          // ✅ Explicitly type or wrap with helper to break the inferred reference
          import type { AngularTable } from '@tanstack/angular-table'
          @Component(...)
          export class MyTable {
            table: AngularTable<MyRow> = createAngularTable(() => ({ ... }))
          }
        source:
          https://github.com/TanStack/table/issues/5774 (createAngularTable in monorepo causes ɵSIGNAL
          error)
        priority: HIGH
        status: fixed-but-legacy-risk
        version_context:
          v8.20.5 angular + Angular 18; closed after Angular update but library pattern is
          common
  - name: Lit TableController Pattern
    slug: lit-table-controller
    domain: framework-adapters
    description:
      TableController ReactiveController pattern for hosting a TanStack Table instance inside
      a LitElement.
    type: framework
    packages:
      - '@tanstack/lit-table'
    covers:
      - TableController class
      - TableController constructor(host) addController side effect
      - tableController.table(options, selector?)
      - table.state (selected state)
      - table.Subscribe ({ source, selector, children })
      - table.FlexRender (cell / header / footer rendering)
      - litReactivity
      - hostConnected / hostDisconnected lifecycle
      - table.store and table.optionsStore subscriptions driving requestUpdate
    tasks:
      - Create a single TableController per LitElement and call .table(...) each render.
      - Pass a selector to .table(...) to reduce work in the render method.
      - Render headers and cells via table.FlexRender or table.Subscribe in lit-html templates.
    failure_modes:
      - mistake: Instantiating TableController inside render() instead of as a class field
        mechanism:
          TableController.addController and store subscriptions run in the constructor. Recreating
          it per render leaks subscriptions, drops the prior table instance (losing state), and double-triggers
          host updates.
        wrong_pattern: |
          protected render() {
            const controller = new TableController<typeof _features, Person>(this)
            const table = controller.table({ _features, _rowModels: {}, columns, data: this._data })
            return html`...`
          }
        correct_pattern: |
          private tableController = new TableController<typeof _features, Person>(this)

          protected render() {
            const table = this.tableController.table({
              _features,
              _rowModels: {},
              columns,
              data: this._data,
            })
            return html`...`
          }
        source: packages/lit-table/src/TableController.ts; examples/lit/basic-table-controller/src/main.ts
        priority: CRITICAL
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Using table.FlexRender as a Lit directive instead of a function call
        mechanism:
          table.FlexRender is a function that returns a TemplateResult. It is invoked inside ${...}
          interpolation with a header / cell / footer argument, not used as a custom element.
        wrong_pattern: |
          html`<td><table.FlexRender cell=${cell}></table.FlexRender></td>`
        correct_pattern: |
          html`<td>${table.FlexRender({ cell })}</td>`
        source: packages/lit-table/src/TableController.ts (FlexRender attached); docs/framework/lit/lit-table.md
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake: Calling table.Subscribe children outside a template interpolation
        mechanism:
          table.Subscribe returns a TemplateResult or string. It must be embedded with ${...} inside
          an html`` template. Calling it as a statement produces a value that the renderer never sees.
        wrong_pattern: |
          protected render() {
            table.Subscribe({
              selector: (s) => s.pagination,
              children: (p) => html`<span>${p.pageIndex + 1}</span>`,
            })
            return html`<div></div>`
          }
        correct_pattern: |
          protected render() {
            return html`
              <div>
                ${table.Subscribe({
                  selector: (s) => s.pagination,
                  children: (p) => html`<span>Page ${p.pageIndex + 1}</span>`,
                })}
              </div>
            `
          }
        source: packages/lit-table/src/TableController.ts (Subscribe shape); docs/framework/lit/guide/table-state.md
        priority: HIGH
        status: active
        version_context: v9.0.0-alpha.47
      - mistake:
          Forgetting that host update is wired through table.store, so source-only Subscribe does not
          skip host updates
        mechanism:
          TableController subscribes the host to the full table.store and optionsStore. table.Subscribe
          with a source prop reads source.get() at render time but does not currently install an independent
          host subscription, so the host still updates on any store change.
        wrong_pattern: |
          // expecting only rowSelection changes to invalidate the host
          ${table.Subscribe({
            source: table.atoms.rowSelection,
            selector: (s) => s[row.id],
            children: (isSelected) => html`<input type=\"checkbox\" .checked=${!!isSelected} />`,
          })}
        correct_pattern: |
          // accept host updates on any store change; reach for an explicit manual subscription only if you measure a real bottleneck
          ${table.Subscribe({
            source: table.atoms.rowSelection,
            selector: (s) => s[row.id],
            children: (isSelected) => html`
              <input
                type="checkbox"
                .checked=${!!isSelected}
                @change=${row.getToggleSelectedHandler()}
              />
            `,
          })}
        source:
          packages/lit-table/src/TableController.ts (LitTable Subscribe note); docs/framework/lit/guide/table-state.md
          (Selecting State with table.Subscribe)
        priority: MEDIUM
        status: active
        version_context: v9.0.0-alpha.47
    maintainer_notes:
      - The Lit adapter is scheduled to be rewritten with TanStack Lit Store during the v9 beta cycle. Current
        contracts (TableController, store-level invalidation) may change. Skill content should describe the
        current shape but note that beta may bring an API revision.
  - slug: getting-started
    type: lifecycle
    domain: lifecycle
    status: ready
    description: |
      End-to-end first-table journey: install the framework adapter, declare `_features` via `tableFeatures()`, declare `_rowModels` factories with their *Fns parameters, create a column helper with both `TFeatures` and `TData` generics, instantiate `useTable` / `injectTable` / `createTable`, and render headers + cells with `table.FlexRender` (or `*flexRender*` directives on Angular). New users land here, not on `useLegacyTable`.
    covers:
      - Picking the right adapter package (`@tanstack/react-table`, `@tanstack/vue-table`, `@tanstack/angular-table`,
        `@tanstack/solid-table`, `@tanstack/svelte-table` (Svelte 5+), `@tanstack/preact-table`, `@tanstack/lit-table`).
      - 'Declaring the minimum-viable v9 table (no features) — must still pass `_features: tableFeatures({})`
        and `_rowModels: {}`. Core row model is automatic; you only register filtered/sorted/paginated/etc.
        when you use them.'
      - "`createColumnHelper<typeof _features, TData>()` and the new `columnHelper.columns([...])` variadic
        wrapper for preserving each column's `TValue` in nested/group columns."
      - Rendering with `<table.FlexRender header={header} />` / `<table.FlexRender cell={cell} />` (preferred)
        or the standalone `<FlexRender />` import. `flexRender(def, ctx)` still works.
      - 'Angular variant: `injectTable(() => ({ ... }))` returning a signal- backed instance; render via `*flexRenderHeader`,
        `*flexRenderCell`, `*flexRenderFooter`. Cell/header render fns run inside an Angular injection context
        — `inject()` is safe.'
      - Default `useTable` selector is `(state) => state` — full re-render on any state change, mirroring
        v8 ergonomics. Narrow it later only when you measure a problem.
      - 'Where to go next: `migrate-v8-to-v9` if upgrading, `production- readiness` once it works.'
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/lit-table'
    tasks:
      - Render a basic v9 table with 3 columns and an in-memory array.
      - 'Add sorting: register `rowSortingFeature` in `_features` and `sortedRowModel: createSortedRowModel(sortFns)`
        in `_rowModels`.'
      - Add pagination + filtering on top of sorting without touching the rest of the setup.
      - Type a `ColumnDef<typeof _features, TData>[]` array outside the component for stable references.
    correct_pattern: |
      // React — minimum viable v9 table
      import {
        useTable,
        tableFeatures,
        rowSortingFeature,
        createSortedRowModel,
        sortFns,
        createColumnHelper,
      } from '@tanstack/react-table'

      type Person = { firstName: string; lastName: string; age: number }

      // Define OUTSIDE the component for stable identity.
      const _features = tableFeatures({ rowSortingFeature })
      const columnHelper = createColumnHelper<typeof _features, Person>()

      const columns = columnHelper.columns([
        columnHelper.accessor('firstName', { header: 'First' }),
        columnHelper.accessor('lastName',  { header: 'Last' }),
        columnHelper.accessor('age',       { header: 'Age' }),
      ])

      function PeopleTable({ data }: { data: Person[] }) {
        const table = useTable({
          _features,
          _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
          columns,
          data,
        })

        return (
          <table>
            <thead>{table.getHeaderGroups().map(hg => (
              <tr key={hg.id}>{hg.headers.map(h => (
                <th key={h.id} onClick={h.column.getToggleSortingHandler()}>
                  <table.FlexRender header={h} />
                </th>
              ))}</tr>
            ))}</thead>
            <tbody>{table.getRowModel().rows.map(row => (
              <tr key={row.id}>{row.getAllCells().map(cell => (
                <td key={cell.id}><table.FlexRender cell={cell} /></td>
              ))}</tr>
            ))}</tbody>
          </table>
        )
      }
    wrong_pattern: |
      // BAD: agents trained on v8 will produce this and it will not compile.
      // (1) `useReactTable` was removed in favor of `useTable`.
      // (2) `getCoreRowModel: getCoreRowModel()` is no longer accepted —
      //     core is implicit; everything else moved to `_rowModels`.
      // (3) `createColumnHelper<Person>()` is missing the TFeatures generic.
      // (4) No `_features` => "Property '_features' is missing in type".
      import { useReactTable, getCoreRowModel, createColumnHelper, flexRender }
        from '@tanstack/react-table'

      const columnHelper = createColumnHelper<Person>()  // wrong arity
      const table = useReactTable({                       // wrong hook
        columns,
        data,
        getCoreRowModel: getCoreRowModel(),               // removed option
      })
    failure_modes:
      - "Forgetting `_features: tableFeatures({})` — the option is required even for a 'no features' table.
        Type error: '_features' is missing."
      - 'Skipping `_rowModels: {}` — same as above. Core is automatic but the option key itself must be present.'
      - Calling `createColumnHelper<Person>()` instead of `createColumnHelper<typeof _features, Person>()`.
        The generic order changed in v9 and the old shape doesn't compile.
      - Defining `_features` / `columns` / `data` literals inside the render body — every render produces
        a new reference and busts table-internal memoization. Always declare these outside the component or
        wrap in `useMemo`.
      - Importing `useReactTable` (v8) or `createAngularTable` (v8 Angular) — both were renamed. v9 uses `useTable`
        / `injectTable` / `createTable` consistently across adapters.
      - Reaching for `useLegacyTable` for a new project. It's deprecated and ships every feature in the bundle.
        New code must use `useTable` with explicit `_features`.
      - mistake: Reimplementing what TanStack Table's built-in APIs already provide
        mechanism:
          TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
          transition (`table.setSorting`, `row.toggleSelected`, `table.nextPage`, `table.setColumnFilters`,
          `column.toggleVisibility`, …). Agents often write their own setState logic, click handlers, or sort/filter
          loops rather than using the built-ins, producing more code that is also less correct (skips internal
          invariants, breaks reset APIs).
        wrong_pattern: |-
          // ❌ Reimplements sorting state manually instead of using the API
          const [sorting, setSorting] = useState([])
          const sortedData = useMemo(() => [...data].sort((a,b) => /* …custom… */), [data, sorting])
          // then uses sortedData directly, bypassing the table
        correct_pattern: |-
          // ✅ Use the built-in APIs — table handles state, reset, multi-sort, etc.
          const table = useTable({
            _features: tableFeatures({ rowSortingFeature }),
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
          // then: table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
        priority: CRITICAL
        version_context:
          'Always present. The maintainer flags this as the #1 tell that "an AI wrote this."
          See `setSorting`/`setColumnFilters`/`toggleSelected`/`nextPage`/etc.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
      - mistake: API or state slice "missing" because the feature was not registered in `_features`
        mechanism:
          In v9, `_features` is a tree-shakeable registry. If a feature is not in `_features`, TypeScript
          hides its APIs and the runtime atom is not created. Agents who copy a snippet for `table.setColumnFilters(...)`
          without registering `columnFilteringFeature` see a TS error or `table.atoms.columnFilters` is undefined
          — and may incorrectly conclude the feature is broken or removed in v9.
        wrong_pattern: |-
          // ❌ rowSortingFeature missing — table.setSorting / state.sorting unavailable
          const _features = tableFeatures({}) // empty
          const table = useTable({ _features, _rowModels: {}, columns, data })
          table.setSorting([{ id: 'age', desc: true }]) // ❌ does not exist on this table type
        correct_pattern: |-
          // ✅ Register every feature you intend to use; pair with its row model when applicable
          const _features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
          const table = useTable({
            _features,
            _rowModels: {
              sortedRowModel: createSortedRowModel(sortFns),
              paginatedRowModel: createPaginatedRowModel(),
            },
            columns, data,
          })
        priority: CRITICAL
        version_context:
          v9-specific. This is the first version of TanStack Table where features must be declared
          for TypeScript and runtime to expose them. Expect heavy confusion from devs and agents trained on
          v8.
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
  - slug: migrate-v8-to-v9
    type: lifecycle
    domain: lifecycle
    status: ready
    description: |
      Mechanical breaking-change migration from TanStack Table v8 to v9 across every adapter. Every old-shaped option, type, or method an agent will try to reproduce from v8 muscle memory has a v9 equivalent enumerated below. For React projects that cannot migrate every table at once, `useLegacyTable` from `@tanstack/react-table/legacy` accepts the v8 API shape on top of the v9 engine — deprecated, ships every feature, no `table.Subscribe`, but lets you upgrade incrementally.
    covers:
      - Hook rename per adapter (React, Angular, Solid, Vue, Preact, Svelte 5+, Lit, vanilla).
      - '`_features` + `_rowModels` becoming required options; row-model factories now take their *Fns set
        as a parameter.'
      - '`createColumnHelper<TData>()` → `createColumnHelper<typeof _features, TData>()` (generic order +
        arity change).'
      - 'State surface: `table.getState()` → `table.store.state` (full) or `table.state` (selector output)
        or `table.atoms.<slice>.get()`.'
      - '`flexRender(def, ctx)` still works; new preferred forms are `<table.FlexRender header|cell|footer={...}
        />` and the standalone `<FlexRender />`.'
      - 'Sorting renames: `sortingFn` → `sortFn`, `sortingFns` → `sortFns`, `getSortingFn()` → `getSortFn()`,
        etc.'
      - '`enablePinning` split into `enableColumnPinning` + `enableRowPinning`.'
      - '`ColumnSizing` feature split into `columnSizingFeature` + `columnResizingFeature`; `columnSizingInfo`
        → `columnResizing`; `onColumnSizingInfoChange` → `onColumnResizingChange`.'
      - '`_`-prefixed internal APIs removed (`row._getAllCellsByColumnId()` → `row.getAllCellsByColumnId()`,
        `table._getFacetedRowModel()` → public form, etc.).'
      - 'Type generics now carry `TFeatures` first: `Column<TFeatures, TData, TValue>`, `Table<TFeatures,
        TData>`, `Row<TFeatures, TData>`, `ColumnMeta<TFeatures, TData, TValue>`.'
      - '`RowData` tightened from `unknown | object | any[]` to `Record<string, any> | Array<any>`.'
      - Angular has no legacy adapter — Angular projects must migrate directly. Svelte v9 supports Svelte
        5+ only; stay on v8 for Svelte 3/4.
      - 'The escape hatch: `useLegacyTable` (React) + `legacyCreateColumnHelper` + `getCoreRowModel`/`getSortedRowModel`/etc.
        from `@tanstack/react-table/legacy` — same call shape as v8, no fine-grained subscriptions, larger
        bundle.'
      - 'The other escape hatch: `stockFeatures` to opt into "everything" without listing features explicitly.'
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/lit-table'
      - '@tanstack/table-core'
    tasks:
      - 'Upgrade a v8 React table to v9 by renaming `useReactTable` → `useTable`, moving `getCoreRowModel`/`getFilteredRowModel`/`getSortedRowModel`/`getPaginationRowModel`
        options into `_rowModels`, and adding `_features: tableFeatures({...})`.'
      - Bridge a v8 React table to v9 via `useLegacyTable` from `@tanstack/react-table/legacy` so the rest
        of the app can upgrade incrementally.
      - Rename `table.getState()` reads throughout the codebase to `table.store.state` (full read) or `table.state`
        (typed selector output) or `table.atoms.<slice>.get()` (single-slice atom read).
      - Update all `createColumnHelper<TData>()` call sites to `createColumnHelper<typeof _features, TData>()`
        and adjust `ColumnDef<TData>` / `Column<TData>` / `Row<TData>` / `Cell<TData, TValue>` type annotations
        to the new `TFeatures`-first generic order.
    correct_pattern: |
      // === v9 (correct) ===
      import {
        useTable,
        tableFeatures,
        rowSortingFeature,
        rowPaginationFeature,
        columnFilteringFeature,
        columnSizingFeature,
        columnResizingFeature,
        createColumnHelper,
        createSortedRowModel,
        createFilteredRowModel,
        createPaginatedRowModel,
        sortFns,
        filterFns,
      } from '@tanstack/react-table'
      import type { ColumnDef } from '@tanstack/react-table'

      const _features = tableFeatures({
        rowSortingFeature,
        rowPaginationFeature,
        columnFilteringFeature,
        columnSizingFeature,
        columnResizingFeature, // explicit — formerly part of ColumnSizing
      })

      const columnHelper = createColumnHelper<typeof _features, Person>()

      const columns: ColumnDef<typeof _features, Person>[] = columnHelper.columns([
        columnHelper.accessor('name', {
          header: 'Name',
          sortFn: 'alphanumeric',        // renamed from sortingFn
        }),
      ])

      const table = useTable({
        _features,
        _rowModels: {
          sortedRowModel:    createSortedRowModel(sortFns),
          filteredRowModel:  createFilteredRowModel(filterFns),
          paginatedRowModel: createPaginatedRowModel(),
        },
        columns,
        data,
        enableColumnPinning: true,        // split from enablePinning
        enableRowPinning:    true,
      })

      // State reads:
      const all      = table.store.state                 // full snapshot
      const sorting  = table.atoms.sorting.get()         // per-slice atom
      const cells    = row.getAllCellsByColumnId()       // no underscore

      // Rendering:
      // <table.FlexRender header={header} />
      // <table.FlexRender cell={cell} />
    wrong_pattern: |
      // === v8 muscle memory — an agent will produce all of this, and ALL of it
      // is broken in v9. Each line is a specific failure mode. ===

      import {
        useReactTable,               // (1) renamed → useTable
        getCoreRowModel,             // (2) no longer accepted as an option;
        getFilteredRowModel,         //     move to `_rowModels` as factories
        getSortedRowModel,           //     created via `createSortedRowModel(sortFns)` etc.
        getPaginationRowModel,
        createColumnHelper,          // (3) needs <TFeatures, TData> now
        sortingFns,                  // (4) renamed → sortFns
        filterFns,
        flexRender,                  // still exists, but prefer table.FlexRender
      } from '@tanstack/react-table'
      import type { ColumnDef, Row } from '@tanstack/react-table'

      const columnHelper = createColumnHelper<Person>()  // wrong generic arity

      const columns: ColumnDef<Person>[] = [               // (5) ColumnDef<TFeatures, TData, TValue> now
        {
          accessorKey: 'name',
          header: 'Name',
          sortingFn: 'alphanumeric',                       // (6) renamed → sortFn
        },
      ]

      const table = useReactTable({
        columns,
        data,
        getCoreRowModel:        getCoreRowModel(),         // (2) move into `_rowModels`
        getFilteredRowModel:    getFilteredRowModel(),
        getSortedRowModel:      getSortedRowModel(),
        getPaginationRowModel:  getPaginationRowModel(),
        filterFns,                                         // (7) no longer a root option — passed to factories
        sortingFns,                                        // (4)+(7) renamed AND no longer a root option
        enablePinning: true,                               // (8) split → enableColumnPinning / enableRowPinning
        onColumnSizingInfoChange: setInfo,                 // (9) renamed → onColumnResizingChange
      })

      // (10) BAD reads:
      const all = table.getState()                         // → table.store.state (or table.state with a selector)
      const cells = row._getAllCellsByColumnId()           // underscore removed → row.getAllCellsByColumnId()

      // (11) Module augmentation
      declare module '@tanstack/react-table' {
        interface ColumnMeta<TData, TValue> {              // (11) v9 adds TFeatures as first generic
          customProp: string
        }
      }

      // === Quick-bridge alternative (DEPRECATED, but compiles): ===
      // Move just THIS file to `useLegacyTable` and keep the v8 shape; migrate
      // it to the modern v9 shape later. Imports come from `/legacy`.
      import { useLegacyTable, getCoreRowModel, legacyCreateColumnHelper }
        from '@tanstack/react-table/legacy'
      const legacyHelper = legacyCreateColumnHelper<Person>()
      const legacyTable  = useLegacyTable({
        columns, data,
        getCoreRowModel: getCoreRowModel(),
      })
    failure_modes:
      - Importing `useReactTable` / `createAngularTable` / `createSolidTable` (v8 names). All adapters consolidated
        to `useTable` / `injectTable` / `createTable` in v9. The v8 imports will not exist and will fail at
        module-resolution time.
      - 'Passing `getCoreRowModel: getCoreRowModel()` / `getSortedRowModel: getSortedRowModel()` as root options.
        These were removed — sortedRowModel/filteredRowModel/etc. now live under `_rowModels` and are produced
        by `createSortedRowModel(sortFns)`-style factories. Core is automatic.'
      - Calling `createSortedRowModel()` without passing `sortFns`. The factories now REQUIRE their *Fns parameter
        for tree-shaking — `createFilteredRowModel(filterFns)`, `createSortedRowModel(sortFns)`, `createGroupedRowModel(aggregationFns)`.
      - "Omitting `_features` entirely. The option is required even for a no-features table — pass `_features:
        tableFeatures({})` or `_features: stockFeatures` if you want v8-like 'everything on'."
      - Calling `createColumnHelper<Person>()` (v8 arity). v9 requires `createColumnHelper<typeof _features,
        Person>()`. `typeof _features` is the standard idiom — declare features once at module scope and reuse
        the type.
      - Reading state via `table.getState()`. The method was removed. Use `table.store.state` for a flat snapshot,
        `table.state` if you passed a `useTable` selector, or `table.atoms.<slice>.get()` for a single slice.
      - 'Renaming misses: `sortingFn` (column def) → `sortFn`, `sortingFns` → `sortFns`, `getSortingFn()`
        → `getSortFn()`, `getAutoSortingFn()` → `getAutoSortFn()`, `SortingFn`/`SortingFns` types → `SortFn`/`SortFns`.
        TypeScript will surface these but the agent will try the v8 names first.'
      - 'Using `enablePinning: true`. It was split into `enableColumnPinning` and `enableRowPinning`. Pick
        one (or both).'
      - 'Treating column resizing as part of column sizing. v9 splits them: pass `columnSizingFeature` for
        fixed widths and ALSO `columnResizingFeature` for drag-to-resize. State key `columnSizingInfo` is
        now `columnResizing`; option `onColumnSizingInfoChange` is `onColumnResizingChange`.'
      - 'Calling underscore-prefixed APIs: `row._getAllCellsByColumnId()`, `table._getFacetedRowModel()`,
        `table._getFacetedMinMaxValues()`, `table._getFacetedUniqueValues()`, `table._getPinnedRows()`. All
        became public — drop the underscore.'
      - "`declare module '@tanstack/react-table' { interface ColumnMeta<TData, TValue> }` — v9 added `TFeatures`
        as the first generic, so this becomes `ColumnMeta<TFeatures, TData, TValue>`. Module augmentation
        silently widens types if the generic arity is wrong."
      - Reaching for `useLegacyTable` on NEW code or in Angular. It's React-only, deprecated, bundles every
        feature, and doesn't support `table.Subscribe`. It exists to unblock incremental migration, not to
        be a long-term API.
      - mistake: TS error "Property filterFns is missing" using useReactTable
        mechanism: |
          The `useReactTable` generic signature requires the filter functions registry to
          be declared via `declare module` augmentation, otherwise `filterFns` appears
          "required" in the props object. Without the augmentation in their project,
          users with strict TS get red squigglies on a basic 3-prop call.
        wrong_pattern: |
          // ❌ TS error: Property 'filterFns' is missing in type ...
          const table = useReactTable({
            data, columns,
            getCoreRowModel: getCoreRowModel(),
          })
        correct_pattern: |
          // ✅ Either (a) cast the column types so the inferred constraint relaxes:
          const columns: ColumnDef<User, any>[] = [/* ... */]
          // OR (b) augment the module to register custom filterFns:
          declare module '@tanstack/react-table' {
            interface FilterFns { myFn: FilterFn<any> }
          }
        source:
          https://github.com/TanStack/table/issues/5005 (Property filterFns is missing using useReactTable,
          14 comments)
        priority: HIGH
        status: active
        version_context: v8 — long-standing top question; v9 cleans this up via tableFeatures registry
        skills:
          - migrate-v8-to-v9
          - setup
          - getting-started
      - mistake: Using useReactTable in v9 alpha when useTable is the new entry point
        mechanism: |
          v9 alpha renames `useReactTable` → `useTable` (and adds a `useLegacyTable` shim).
          Agents trained on v8 will reach for `useReactTable`. The signature also changes —
          `_features` and `_rowModels` are now mandatory configuration, not pre-bundled
          defaults. `useReactTable` still exists for back-compat but produces v8-style
          tables that don't have `.Subscribe`, `.atoms`, or feature composition.
        wrong_pattern: |
          // ❌ v8 entry point — won't have v9 Subscribe / atoms APIs
          import { useReactTable, getCoreRowModel } from '@tanstack/react-table'
          const table = useReactTable({
            data, columns,
            getCoreRowModel: getCoreRowModel(),
          })
        correct_pattern: |
          // ✅ v9 entry — explicit features + row models
          import {
            useTable, tableFeatures,
            sortingFeature, columnFilteringFeature, rowPaginationFeature,
          } from '@tanstack/react-table'
          const _features = tableFeatures({
            sortingFeature, columnFilteringFeature, rowPaginationFeature,
          })
          const table = useTable({ _features, data, columns })
        source: 'PR #6202 (fix useLegacyTable infinite rerender), useTable.ts source, CHANGELOG history'
        priority: CRITICAL
        status: active
        version_context: v9 alpha rename; v8 patterns dominate training data
      - mistake: Importing pre-bundled getCoreRowModel etc. in v9
        mechanism: |
          In v8, `getCoreRowModel()`, `getSortedRowModel()`, `getFilteredRowModel()` etc.
          were standalone factories. In v9, row models are opt-in through `_rowModels` on
          the table options or auto-installed by features in `tableFeatures()`. Agents
          will keep emitting v8 imports that either don't exist or aren't wired correctly.
        wrong_pattern: |
          // ❌ v8 pattern — won't drive v9 row models
          const table = useTable({
            _features,
            data, columns,
            getCoreRowModel: getCoreRowModel(),
            getSortedRowModel: getSortedRowModel(),
          })
        correct_pattern: |
          // ✅ v9 — row models opt-in via _rowModels or feature inclusion
          import {
            useTable, tableFeatures,
            sortingFeature, coreRowModelsFeature, sortedRowModelsFeature,
          } from '@tanstack/react-table'
          const _features = tableFeatures({
            sortingFeature,
            coreRowModelsFeature,
            sortedRowModelsFeature,
          })
          const table = useTable({ _features, data, columns })
        source: 'PR #6234 (atoms refactor), v9 alpha package exports'
        priority: CRITICAL
        status: active
        version_context: v9 alpha — fundamental restructure of the API surface
        skills:
          - migrate-v8-to-v9
          - customizing-feature-behavior
      - mistake: data/columns are mutable in v8 but readonly in v9
        mechanism: |
          PR #6183 makes `data` and `columns` `readonly` in v9 to force users to flow
          changes through React state rather than mutating arrays in place. Code that
          pushes to `data.push(...)` or splices columns will break at the TypeScript
          level on v9, but agents will produce v8-style mutation patterns.
        wrong_pattern: |
          // ❌ v8 pattern, breaks at TS layer in v9
          const data = []
          function addRow(row) { data.push(row); rerender() }
        correct_pattern: |
          // ✅ Use React state / setState
          const [data, setData] = useState([])
          function addRow(row) { setData(prev => [...prev, row]) }
        source: 'PR #6183 (make data and columns readonly)'
        priority: MEDIUM
        status: active
        version_context: v9 alpha
        skills:
          - migrate-v8-to-v9
          - setup
      - mistake: Hallucinating react-table v7 / pre-v9 @tanstack/[framework]-table APIs
        mechanism:
          Every major release of TanStack Table (formerly react-table) has been a substantial upgrade.
          Agents trained on older data confidently produce v7 or v8 API shapes that no longer exist in v9
          (e.g. `useReactTable`, inline `getCoreRowModel()` as an option, `useTable` from react-table v7).
        wrong_pattern: |-
          // ❌ v7 / v8 patterns the agent invents
          import { useTable, useSortBy } from 'react-table' // v7
          const table = useTable({ columns, data }, useSortBy)

          // or v8
          import { useReactTable, getCoreRowModel } from '@tanstack/react-table'
          const table = useReactTable({ columns, data, getCoreRowModel: getCoreRowModel() })
        correct_pattern: |-
          // ✅ v9 pattern — `_features` + `_rowModels`
          import { useTable, tableFeatures, rowSortingFeature, createSortedRowModel, sortFns } from '@tanstack/react-table'
          const _features = tableFeatures({ rowSortingFeature })
          const table = useTable({
            _features,
            _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
            columns, data,
          })
        priority: CRITICAL
        version_context:
          v7→v8 and v8→v9 both shifted the API substantially; agents trained on any pre-v9
          data will produce wrong shapes.
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
  - slug: client-to-server
    type: lifecycle
    domain: lifecycle
    status: ready
    description: |
      Convert a client-side table to server-side (a.k.a. manual modes). Pattern: pass server data, set `manualSorting` / `manualFiltering` / `manualPagination` / `manualGrouping` / `manualExpanding` for whatever the server now owns, supply `rowCount` (and/or `pageCount`) so the table can paginate without seeing all rows, and remove the corresponding `_rowModels` entries (you don't need `paginatedRowModel` if pagination is server-side). State for the server-managed slices is best owned EITHER via external TanStack Store atoms (passed via `options.atoms`) OR via classic `state` + `on*Change` controlled state — both work. With Query, the atom pattern lets you key your query on the atom and let the table write directly to it without `on*Change` plumbing.
    covers:
      - Setting `manualSorting`, `manualFiltering`, `manualPagination`, `manualGrouping`, `manualExpanding`
        so the table stops trying to slice rows it doesn't have.
      - Removing the matching `_rowModels` keys so unused factories don't ship (don't register `paginatedRowModel`
        if the server paginates).
      - Providing `rowCount` (and optionally `pageCount`) so `table.getPageCount()` / `getCanNextPage()` work
        without local rows.
      - 'State ownership: external atoms via `useCreateAtom` + `options.atoms` (cleanest with Query, no `on*Change`
        needed) OR classic `state` + `on*Change` controlled state. Both are documented patterns.'
      - 'Cache key strategy: include the relevant atom value (or controlled state) in `queryKey`. Use `placeholderData:
        keepPreviousData` to avoid the "0 rows flash" while paging.'
      - "Invalidation: call `queryClient.invalidateQueries({ queryKey: [...] })` on writes — TanStack Table
        doesn't invalidate for you."
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
    tasks:
      - Convert a sorting+pagination table that operates on a 50k local array to one that requests `/api/people?pageIndex=&pageSize=&sort=`
        and renders the response.
      - Wire pagination via an external TanStack Store atom (`useCreateAtom<PaginationState>(...)`) + the
        `atoms` option so the query auto-refetches without an explicit `onPaginationChange` handler.
      - Wire the same conversion via classic `state` + `onPaginationChange` controlled state when you already
        have signal/useState plumbing.
      - Combine server-side sort + pagination + filter while keeping client-side column visibility / ordering
        / pinning — those features still work locally because they don't depend on the row model.
    correct_pattern: |
      // React + TanStack Query + external pagination atom
      import { useTable, tableFeatures, rowPaginationFeature, createColumnHelper }
        from '@tanstack/react-table'
      import { useQuery, keepPreviousData } from '@tanstack/react-query'
      import { useCreateAtom, useSelector } from '@tanstack/react-store'
      import type { PaginationState } from '@tanstack/react-table'

      const _features = tableFeatures({ rowPaginationFeature })

      function ServerTable({ columns }) {
        // 1) Own pagination in an external atom.
        const paginationAtom = useCreateAtom<PaginationState>({
          pageIndex: 0,
          pageSize:  10,
        })
        const pagination = useSelector(paginationAtom)

        // 2) Key the query on the atom value. Query refetches automatically
        //    when the table calls table.setPageIndex(...) / setPageSize(...)
        //    because those writes flow into the atom.
        const dataQuery = useQuery({
          queryKey: ['people', pagination],
          queryFn:  () => fetchPeople(pagination),
          placeholderData: keepPreviousData,
        })

        // 3) Manual pagination + `rowCount` for getPageCount(). Note: no
        //    `paginatedRowModel` in `_rowModels` — server paginates.
        const table = useTable({
          _features,
          _rowModels: {},                        // core only
          columns,
          data: dataQuery.data?.rows ?? [],
          rowCount: dataQuery.data?.rowCount,
          atoms: { pagination: paginationAtom }, // own the slice externally
          manualPagination: true,
        })
        // No onPaginationChange needed — writes go to paginationAtom.
        // ...
      }
    wrong_pattern: |
      // BAD #1: kept `paginatedRowModel` even though the server paginates.
      // This makes the table try to slice the (already-sliced) `data` array
      // a second time, producing rows that don't exist.
      const table = useTable({
        _features,
        _rowModels: { paginatedRowModel: createPaginatedRowModel() },
        columns,
        data: serverPage.rows,
        // missing: manualPagination + rowCount
      })

      // BAD #2: forgot `rowCount`. `table.getPageCount()` returns
      // `Math.ceil(rows.length / pageSize)` which is the page size, not the
      // total — the pager shows "Page 1 of 1" forever.
      const table = useTable({
        _features,
        _rowModels: {},
        columns,
        data: serverPage.rows,
        manualPagination: true,
        // missing: rowCount: serverPage.totalRowCount
      })

      // BAD #3: keyed Query on the wrong thing. `queryKey: ['people']` never
      // changes, so pagination button clicks update the atom but Query
      // doesn't refetch — the table stays on page 1's data.
      useQuery({ queryKey: ['people'], queryFn: () => fetch(pagination) })

      // BAD #4: classic controlled state but the table writes go nowhere
      // because there's no `on*Change`. Either pass `atoms` OR pass
      // `state + on*Change`. Don't pass `state` without `on*Change`.
      const [pagination, setPagination] = useState<PaginationState>({...})
      useTable({
        _features, _rowModels: {}, columns, data,
        state: { pagination },
        // missing: onPaginationChange: setPagination
        manualPagination: true,
      })
    failure_modes:
      - 'Forgetting `manualPagination: true` (or `manualSorting` / `manualFiltering`). The table will re-sort/re-filter/re-paginate
        the already-server-processed rows, producing visually incorrect or duplicated results.'
      - 'Leaving `paginatedRowModel: createPaginatedRowModel()` registered when the server paginates. The
        factory ships in your bundle for no reason AND the table slices server-sliced data. Drop it from `_rowModels`.'
      - Omitting `rowCount`. Without it, `getPageCount()` is computed from `data.length / pageSize` — which
        equals 1 if the server returned a single page. Pager UIs lock at 'Page 1 of 1'.
      - Passing `state.pagination` without `onPaginationChange`. The library treats `state` as controlled;
        without a writeback handler, `table.setPageIndex(2)` is a no-op. Either pass both, or pass `atoms.pagination`
        (which is its own writeback).
      - Mixing `state.pagination` AND `atoms.pagination` for the SAME slice. Precedence is `options.atoms[key]`
        > `options.state[key]` > internal — `state` is silently ignored. Pick one mechanism per slice.
      - Not including pagination/sort/filter in the Query `queryKey`. The query won't refetch when the user
        pages or sorts because Query has no way to know its inputs changed.
      - 'Forgetting `placeholderData: keepPreviousData` (or equivalent) when paging. The table renders zero
        rows during the fetch, which collapses the height and jumps the scroll position.'
  - slug: production-readiness
    type: lifecycle
    domain: lifecycle
    status: ready
    description: |
      Ship-ready optimizations for v9: tree-shake the bundle by registering ONLY the `_features` you actually use; memoize `_features`, `data`, and `columns` for stable identity; replace `(state) => state` with narrow selectors or per-slice `useSelector(table.atoms.<slice>)` subscriptions; and push state-driven re-renders down the tree with `<table.Subscribe>` (or the standalone `<Subscribe>` import) so the expensive table body doesn't re-render every time you toggle a sort indicator. Production builds of the table devtools are also a `/production` import flip — see `compose-with-tanstack-devtools`.
    covers:
      - "Tree-shaking: list features explicitly in `tableFeatures({...})` rather than `stockFeatures`. A sort-only
        table is ~6–7kb vs ~15–20kb for v8's all-in approach."
      - 'Reference stability: `_features`, `_rowModels`, `columns`, and `data` should NOT be redefined on
        every render. Declare at module scope or memoize with `useMemo` / Angular `signal()` / Solid memo.'
      - "Default selector trade-off: `(state) => state` matches v8 behavior but forces a re-render on any
        state change. Narrow it (`(state) => ({ sorting: state.sorting })`) once you've profiled."
      - '`<table.Subscribe selector={...}>` (or `<Subscribe source={table.store}>`) for moving the re-render
        boundary down to a sub-tree.'
      - 'Per-slice atom subscriptions: `useSelector(table.atoms.pagination)` in a leaf component re-renders
        only when pagination changes — narrower than `table.Subscribe`, which still selects from the full
        state object.'
      - "React Compiler interaction: `<Subscribe>` is the React-Compiler-safe way to read table state in nested
        components — the compiler can't see through the table closure on its own."
      - 'Angular: prefer `computed(() => table.atoms.<slice>.get(), { equal: shallow })` to debounce object-identity
        re-runs.'
      - "Stress patterns: virtualize rows/columns with TanStack Virtual (see `compose-with-tanstack-virtual`),
        keep the row virtualizer in the deepest possible component, and use `Subscribe` walls around column
        DnD / pinning UIs that don't need to participate in row updates."
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
    tasks:
      - Audit a project's `_features` declarations and remove any feature whose imports aren't actually wired
        up in column defs / state.
      - Replace `useTable(opts, (state) => state)` with a narrowed selector when only a subset of state is
        rendered at the table level.
      - 'Wrap a noisy pagination footer (re-renders on every keystroke in a filter) in `<table.Subscribe selector={s
        => ({ pagination: s.pagination })}>` so it only re-renders on pagination changes.'
      - Move a `RowSelectionCount` component from reading `table.state.rowSelection` to `useSelector(table.atoms.rowSelection)`
        for the narrowest subscription surface.
    correct_pattern: |
      // === Tree-shake by feature ===
      import {
        useTable,
        tableFeatures,
        rowSortingFeature,      // ✓ ship sort code
        rowPaginationFeature,   // ✓ ship pagination code
        createSortedRowModel,
        createPaginatedRowModel,
        sortFns,
      } from '@tanstack/react-table'

      // Module-scope, stable identity:
      const _features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
      const _rowModels = {
        sortedRowModel:    createSortedRowModel(sortFns),
        paginatedRowModel: createPaginatedRowModel(),
      }

      function MyTable({ data, columns }) {
        // ✓ narrow selector — re-renders only when these slices change
        const table = useTable(
          { _features, _rowModels, columns, data },
          (state) => ({
            sorting:    state.sorting,
            pagination: state.pagination,
          }),
        )

        return (
          <>
            <TableBody table={table} /> {/* heavy — keep stable */}
            {/* ✓ Re-render wall: footer only re-renders on pagination changes,
                not on sort changes that affect TableBody */}
            <table.Subscribe selector={(s) => ({ pagination: s.pagination })}>
              {({ pagination }) => <PageFooter pagination={pagination} />}
            </table.Subscribe>
          </>
        )
      }

      // === Narrowest subscription — per-slice atom ===
      import { useSelector } from '@tanstack/react-store'

      function SelectedCount({ table }) {
        // re-renders ONLY when rowSelection changes, not sorting/pagination/etc.
        const selection = useSelector(table.atoms.rowSelection)
        return <span>{Object.keys(selection).length} selected</span>
      }
    wrong_pattern: |
      // BAD #1: stockFeatures in a sort-only table.
      // Ships filtering, faceting, grouping, pinning, expanding, sizing,
      // resizing, visibility, ordering, row-selection, row-pinning code
      // none of which is used. ~3x the necessary bundle for `_features`.
      import { useTable, stockFeatures } from '@tanstack/react-table'
      const table = useTable({ _features: stockFeatures, /* ... */ })

      // BAD #2: unstable references — every render is a new identity.
      function MyTable({ data, columns }) {
        const _features = tableFeatures({ rowSortingFeature })  // new every render
        const opts = {                                           // new every render
          _features,
          _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
          columns,                                               // hopefully stable
          data,
        }
        const table = useTable(opts)
        // ...
      }

      // BAD #3: default selector + deep re-render tree.
      function MyTable() {
        // (state) => state means every keystroke in a filter input re-renders
        // every cell in the body unless you memo manually.
        const table = useTable(opts) // implicit (state) => state
        return <DeeplyNestedTable table={table} />
      }

      // BAD #4: reading state in a way React Compiler can't track.
      function PageFooter({ table }) {
        // The compiler can't reason through the table closure — it may either
        // bail out of optimization OR cache a stale read.
        const { pagination } = table.state
        return <div>{pagination.pageIndex + 1}</div>
        // ✓ Fix: <Subscribe source={table.store} selector={s => s.pagination}>
        //   or useSelector(table.atoms.pagination).
      }
    failure_modes:
      - Using `stockFeatures` in production without auditing which features are actually rendered. Defeats
        the whole reason tree-shaking exists in v9. Replace with an explicit `tableFeatures({...})` listing
        only what your UI uses.
      - Declaring `_features`, `_rowModels`, or `columns` inside the component body without `useMemo`. Internal
        memoization keys off identity, so a new object every render forces full recomputation.
      - Putting `data` in `useState` and never memoizing the array literal that produces it. `setData(rows.filter(...))`
        returns a new array each call — that's fine; the FAQ pitfall is `data={[]}` or `data={rows ?? []}`
        in JSX, which creates a new identity each render.
      - Leaving `(state) => state` as the selector when only one component cares about one slice. The whole
        tree re-renders on every state change. Narrow the selector and/or use `<table.Subscribe>` boundaries.
      - Forgetting that `<table.Subscribe>` still selects from `table.store.state` (the full state). For a
        single-slice subscription, `useSelector(table.atoms.<slice>)` is narrower and skips even constructing
        a state snapshot.
      - Hoisting heavy table state reads above virtualizers. The TanStack Virtual rule of thumb is to keep
        `useVirtualizer` in the deepest component possible; pulling `table.state` into a parent re-renders
        the virtualizer and kills scroll perf.
      - Reading `table.state` in deeply-nested React-Compiler-compiled components instead of `<Subscribe>`
        or `useSelector`. The compiler doesn't see through the table closure, so it can't determine the dependency
        edges correctly.
      - mistake: Next.js warns about Date.now() in client component
        mechanism: |
          `table-core` uses `Date.now()` inside `getMemoOptions` for cache freshness tracking.
          Next.js (v16+) flags this in client components as a hydration risk because server
          and client times differ. The warning is inert at runtime but noisy. Workaround is
          pending a switch to `performance.now()`.
        wrong_pattern: |
          // ❌ Next.js dev warnings on basic v8 setup
          'use client'
          const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() })
        correct_pattern: |
          // ✅ No code-level fix yet — track issue #6127 / wait for upstream patch.
          //    Workaround: silence the rule for the table file or move table construction
          //    into a custom hook to localize.
        source:
          'https://github.com/TanStack/table/issues/6127 (DX: Next.JS complain about using Date.now()
          inside a Client Component)'
        priority: LOW
        status: active
        version_context: v8.21.3 + Next 16
        skills:
          - production-readiness
          - setup
      - mistake: Bundling stockFeatures or all features when only a few are used
        mechanism:
          TanStack Table v9 is tree-shakeable specifically so you only pay for features you use.
          Registering `stockFeatures` (or every feature "just in case") forfeits the bundle benefit that motivated
          the v9 redesign.
        wrong_pattern: |-
          // ❌ Pulls in every feature even though only sorting+pagination are used
          import { stockFeatures, tableFeatures } from '@tanstack/react-table'
          const _features = tableFeatures(stockFeatures)
        correct_pattern: |-
          // ✅ Register only what this table uses
          import { tableFeatures, rowSortingFeature, rowPaginationFeature } from '@tanstack/react-table'
          const _features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
        priority: HIGH
        version_context: v9. Tree-shaking via `_features` is one of the headline reasons for the rewrite.
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
      - mistake: Premature Subscribe / custom selector optimization on small tables
        mechanism:
          Subscribe and narrow selectors are designed for large or expensive tables where full re-renders
          measurably hurt. On small tables (a few hundred rows, simple features), default selector + inline
          rendering is fine and the Subscribe boundaries add complexity without measurable benefit.
        wrong_pattern: |-
          // ❌ Wraps every header and cell in Subscribe on a 50-row table
          header: ({ table }) => (
            <Subscribe source={table.store} selector={(s) => s.sorting}>
              {() => <SortHeader header={header} />}
            </Subscribe>
          )
        correct_pattern: |-
          // ✅ Default useTable selector, inline rendering — Subscribe only when measured perf demands it
          const table = useTable({ _features, _rowModels, columns, data })
          // reach for Subscribe later, scoped to the actual hotspot
        priority: MEDIUM
        version_context: 'Maintainer guidance: advanced state-management patterns are for advanced cases.'
        source: maintainer interview (Phase 4, 2026-05-17)
        status: active
  - slug: compose-with-tanstack-store
    type: composition
    domain: composition
    status: ready
    description: |
      v9 is built on TanStack Store. Each state slice (sorting, pagination, rowSelection, columnFilters, ...) is a separate atom. The table exposes three read surfaces — `table.atoms.<slice>` (per-slice readonly), `table.store` (flat readonly view), and `table.state` (selector output from `useTable`) — and two write paths — internal `table.baseAtoms.<slice>` OR YOUR `options.atoms[slice]` if you opt to own the slice. The `atoms` option lets a slice be shared across components, persisted, or wired to a non-table subscriber. Use `useCreateAtom` to create the atom in React; `useSelector` to read it in any component without going through the table; the table writes to your atom directly when you call `table.setSorting(...)` etc.
    covers:
      - "The three read surfaces and what they're for: `table.atoms.<slice>` (narrowest), `table.store.state`
        (full snapshot), `table.state` (typed selector output)."
      - 'Precedence: `options.atoms[key]` > `options.state[key]` > internal `baseAtoms[key]`. Mixing `state`
        + `atoms` for the same slice — `atoms` wins and `state` is ignored.'
      - 'When external atoms beat `state` + `on*Change`: cross-component subscriptions, persistence (writing
        the atom to localStorage from outside the table), atom-based integrations, sharing one slice across
        multiple tables.'
      - '`useCreateAtom<SliceState>(initial)` for stable atom identity inside a React component (replacement
        for the manual `useRef(createAtom(...))` pattern).'
      - '`useSelector(table.atoms.<slice>)` / `useSelector(myAtom)` for fine-grained reactivity.'
      - '`table.reset()` does NOT clear external atoms — you own them, so you reset them yourself with `myAtom.set(default)`.'
      - 'Angular: atoms are signal-backed under the hood. Read them through `computed(() => table.atoms.<slice>.get(),
        { equal: shallow })`.'
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/store'
      - '@tanstack/react-store'
    tasks:
      - Move a row-selection slice to an external `useCreateAtom<RowSelectionState>({})` and pass it through
        `options.atoms.rowSelection` so a sibling sidebar can `useSelector` the same atom.
      - Replace classic `state.sorting` + `onSortingChange` controlled state with an external `sortingAtom`
        for atom-based ergonomics — the table writes to the atom directly, no `on*Change` plumbing.
      - Persist a column-visibility slice by subscribing the atom to localStorage outside the table render
        path.
      - Read `table.atoms.pagination` in a deeply-nested footer with `useSelector` so the rest of the table
        doesn't re-render on page changes.
    correct_pattern: |
      // External atoms for sorting + pagination — owned by you, shared anywhere.
      import { useCreateAtom, useSelector } from '@tanstack/react-store'
      import {
        useTable, tableFeatures, rowSortingFeature, rowPaginationFeature,
        createSortedRowModel, createPaginatedRowModel, sortFns,
      } from '@tanstack/react-table'
      import type { PaginationState, SortingState } from '@tanstack/react-table'

      const _features = tableFeatures({ rowSortingFeature, rowPaginationFeature })

      function MyTable({ columns, data }) {
        const sortingAtom    = useCreateAtom<SortingState>([])
        const paginationAtom = useCreateAtom<PaginationState>({
          pageIndex: 0, pageSize: 10,
        })

        // Fine-grained reads — these components re-render independently.
        const sorting    = useSelector(sortingAtom)
        const pagination = useSelector(paginationAtom)

        const table = useTable({
          _features,
          _rowModels: {
            sortedRowModel:    createSortedRowModel(sortFns),
            paginatedRowModel: createPaginatedRowModel(),
          },
          columns,
          data,
          atoms: {
            sorting:    sortingAtom,
            pagination: paginationAtom,
          },
          // NOTE: no onSortingChange / onPaginationChange needed —
          // table.setSorting / table.setPageIndex write through to the atoms.
        })

        // Reset is your job for owned atoms:
        const resetMyState = () => {
          sortingAtom.set([])
          paginationAtom.set({ pageIndex: 0, pageSize: 10 })
        }
      }
    wrong_pattern: |
      // BAD #1: passing the SAME slice via both `state` and `atoms`. Atoms
      // win silently and the `state` value is ignored — confusing to debug.
      useTable({
        _features, _rowModels: {},
        columns, data,
        state: { sorting: localSorting },           // ignored
        onSortingChange: setLocalSorting,           // ignored
        atoms: { sorting: sortingAtom },            // wins
      })

      // BAD #2: creating the atom inside render without `useCreateAtom`.
      // A new atom every render → the table re-binds every render → state
      // resets to initial. (The same trap as `useState(createAtom(...))`.)
      function MyTable() {
        const sortingAtom = createAtom<SortingState>([])  // wrong: unstable
        useTable({ _features, _rowModels: {}, columns, data,
                   atoms: { sorting: sortingAtom } })
      }

      // BAD #3: expecting `table.reset()` to clear an external atom. It
      // doesn't — you own the atom. Call sortingAtom.set([]) yourself.
      <button onClick={() => table.reset()}>Reset</button>
      // ✓ Fix: <button onClick={() => { sortingAtom.set([]); table.reset() }}>
    failure_modes:
      - Creating atoms with `createAtom(...)` inside a component body. Use `useCreateAtom(initial)` (React)
        or framework equivalents for stable identity. A fresh atom every render unbinds the table from the
        slice and resets the state.
      - Passing the same slice key in both `options.state` and `options.atoms`. `options.atoms` wins; `state`
        is ignored silently. Pick one mechanism.
      - Expecting `table.reset()` to clear externally-owned atoms. The library only resets slices it manages
        internally — your atoms are yours to reset (call `myAtom.set(default)`).
      - Reading via `table.state.sorting` in a deeply-nested component when only that component cares about
        sorting. Use `useSelector(table.atoms.sorting)` or `useSelector(mySortingAtom)` for the narrowest
        re-render surface.
      - Pairing external atoms with `on*Change` handlers. You don't need them — the table writes directly
        to your atom via the atom's `set()`. Adding an `onSortingChange` does nothing useful and can confuse
        readers.
  - slug: compose-with-tanstack-query
    type: composition
    domain: composition
    status: ready
    description: |
      Server-side / async data flow with TanStack Query. Key the query on the table state that drives the request (pagination + sort + filters), pass `placeholderData: keepPreviousData` to avoid a "0 rows flash" between pages, set `manualPagination` / `manualSorting` / `manualFiltering` so the table doesn't re-process server-processed rows, and pass `rowCount` so `getPageCount()` works without all rows in memory. The cleanest wiring uses an external pagination atom + `options.atoms.pagination` so table writes auto-trigger Query refetches — no `onPaginationChange` handler required. Examples for React, Vue, Solid, Svelte, and Preact all live in `examples/<framework>/with-tanstack-query`. Angular uses `rxResource` instead of Query in `examples/angular/remote-data`.
    covers:
      - "Pattern: external atom OR classic `state` + `on*Change`. With atoms, `queryKey: ['key', useSelector(atom)]`
        is enough — the table writes to the atom, the atom updates the selector, Query refetches."
      - '`manualPagination`, `manualSorting`, `manualFiltering` flags.'
      - '`rowCount` (preferred) or legacy `pageCount` so the pager UI shows accurate totals.'
      - '`placeholderData: keepPreviousData` to keep the previous page visible during fetches.'
      - Infinite scroll via `useInfiniteQuery` + flatten pages + `manualSorting` so a new query fires per
        sort change.
      - Invalidation on writes — call `queryClient.invalidateQueries(...)` in your mutation `onSuccess`; the
        table picks up the new data automatically via Query's normal flow.
      - Angular `rxResource` is the idiomatic equivalent; `linkedSignal` keeps previous response visible while
        a new one loads.
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/react-query'
      - '@tanstack/query-core'
    tasks:
      - Wire a paginated server table with `useQuery` + `useCreateAtom<PaginationState>` + `options.atoms.pagination`
        — no `onPaginationChange` handler.
      - Build an infinite-scroll table with `useInfiniteQuery` + `manualSorting`, flattening `data.pages`
        and triggering `fetchNextPage` when the scroll container nears the bottom.
      - "On a mutation that adds a row, call `queryClient.invalidateQueries({ queryKey: ['people'] })` so
        the table re-renders with the new row without manual state updates."
      - 'Angular: replicate the same shape using `rxResource({ params, stream })` keyed on `signal()`-backed
        `pagination`/`sorting`/`globalFilter` state, with `linkedSignal` keeping the previous response visible
        during loading.'
    correct_pattern: |
      // React: useQuery + external pagination atom + manualPagination
      import { QueryClientProvider, useQuery, keepPreviousData } from '@tanstack/react-query'
      import { useCreateAtom, useSelector } from '@tanstack/react-store'
      import { useTable, tableFeatures, rowPaginationFeature, createColumnHelper }
        from '@tanstack/react-table'
      import type { PaginationState } from '@tanstack/react-table'

      const _features = tableFeatures({ rowPaginationFeature })

      function ServerTable({ columns }) {
        const paginationAtom = useCreateAtom<PaginationState>({
          pageIndex: 0, pageSize: 10,
        })
        const pagination = useSelector(paginationAtom)

        const dataQuery = useQuery({
          queryKey: ['people', pagination],
          queryFn:  () => fetchPeople(pagination),
          placeholderData: keepPreviousData,
        })

        const table = useTable({
          _features,
          _rowModels: {},                               // server paginates
          columns,
          data: dataQuery.data?.rows ?? EMPTY,          // EMPTY is module-scope
          rowCount: dataQuery.data?.rowCount,
          atoms: { pagination: paginationAtom },
          manualPagination: true,
        })
        // table.nextPage() → atom updates → query refetches. No on*Change.
      }
    wrong_pattern: |
      // BAD: a v8-shaped server table the agent will reproduce by reflex.
      // (1) v8 hook name. (2) get*RowModel options. (3) NO manualPagination,
      // so the table tries to slice the already-sliced server page locally.
      // (4) Missing `rowCount` so the pager shows "Page 1 of 1".
      // (5) queryKey doesn't include the pagination state, so the query
      // never refetches when the user pages.
      const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })

      const { data } = useQuery({
        queryKey: ['people'],                       // (5)
        queryFn:  () => fetchPeople(pagination),
      })

      const table = useReactTable({                 // (1)
        columns,
        data: data?.rows ?? [],                     // new identity each render
        getCoreRowModel:       getCoreRowModel(),   // (2)
        getPaginationRowModel: getPaginationRowModel(), // (2)+(3): also paginates locally
        state:                 { pagination },
        onPaginationChange:    setPagination,
        // missing (4): rowCount
        // missing (3): manualPagination: true
      })
    failure_modes:
      - Omitting `manualPagination` / `manualSorting` / `manualFiltering`. The table double-processes server-processed
        rows. If your server returned a 10-row page, the table will paginate that 10-row 'dataset' again and
        probably show a single page.
      - Missing `rowCount`. `getPageCount()` falls back to `Math.ceil(data.length / pageSize)` which is 1
        if the server already paginated. Pager UIs lock at 'Page 1 of 1'.
      - Forgetting to include pagination/sort/filter state in `queryKey`. Query has no other way to know its
        inputs changed; clicks on the pager update state but the query never refetches.
      - 'Skipping `placeholderData: keepPreviousData`. Between pages the table collapses to 0 rows, the row
        container collapses, and the scroll position jumps.'
      - 'Keeping `paginatedRowModel: createPaginatedRowModel()` registered in `_rowModels` for a server-paginated
        table. The factory ships in your bundle for nothing AND it competes with `manualPagination`.'
      - Mixing `state.pagination` + `onPaginationChange` AND `atoms.pagination` for the same slice. `atoms`
        wins; the `state` plumbing is silently dead. Pick one.
      - Forgetting `queryClient.invalidateQueries(...)` after mutations. The table is a downstream consumer
        — it has no way to know the server data changed unless Query tells it.
      - 'Recreating `data: dataQuery.data?.rows ?? []` in JSX. The `?? []` produces a new array identity on
        every render — wrap with a module-scope `const EMPTY: Row[] = []` or `useMemo`.'
    canonical_pattern:
      example_path: examples/react/with-tanstack-query/src/main.tsx
      summary:
        'External pagination atom via useCreateAtom + atoms option (NOT state+onChange). Pagination
        object is part of queryKey. manualPagination: true. placeholderData: keepPreviousData avoids 0-rows
        flash. defaultData = useMemo(() => [], []) keeps data ref stable between fetches.'
  - slug: compose-with-tanstack-virtual
    type: composition
    domain: composition
    status: ready
    description: |
      TanStack Table does NOT include virtualization — pair with TanStack Virtual (`@tanstack/<fw>-virtual`). The standard pattern: get the row array from `table.getRowModel().rows`, feed `rows.length` to `useVirtualizer({ count, estimateSize, getScrollElement, ... })`, iterate `rowVirtualizer.getVirtualItems()` instead of `rows.map`, absolute-position each row with `transform: translateY(virtualRow.start)px`, and render the `<tbody>` as a CSS grid with a fixed total height. The virtualizer MUST live in the lowest possible component so it doesn't re-run when unrelated state changes. Column virtualization uses the same shape but with `horizontal: true` and padding-left/padding-right placeholder `<th>`/`<td>` cells. Infinite scroll combines this with `useInfiniteQuery` + a `fetchMoreOnBottomReached` callback. The experimental examples (`virtualized-rows-experimental`, `virtualized-columns-experimental`) show next-gen patterns using `rowVirtualizer.measureElement` + manual style application for max perf.
    covers:
      - Row virtualization (`useVirtualizer`/`createVirtualizer`/`injectVirtualizer`).
      - Column virtualization (`horizontal: true`, padding-left/right placeholder cells).
      - Infinite scroll via `useInfiniteQuery` + scroll-to-bottom callback.
      - Dynamic row heights via `measureElement` (skip in Firefox — it measures border height incorrectly).
      - "Critical perf rule: keep the virtualizer in the DEEPEST component possible (e.g. `TableBody`, not
        `App`) so unrelated state changes don't re-run it."
      - '`display: grid` on `<table>` / `<thead>` / `<tbody>` is required for dynamic row heights — semantic
        table tags still work, just styled as grid.'
      - "Experimental pattern: keep a `rowRefsMap`, apply transforms via the virtualizer's `onChange` callback
        to avoid touching React state at all on scroll."
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/lit-table'
      - '@tanstack/react-virtual'
      - '@tanstack/virtual-core'
    tasks:
      - Add row virtualization to a 200k-row table by isolating the virtualizer in a `TableBody` component
        that consumes the table instance as a prop.
      - 'Implement column virtualization with `horizontal: true` plus virtualPaddingLeft/Right placeholder
        cells in both `<thead>` row and `<tbody>` rows.'
      - 'Build an infinite-scroll table by combining `useInfiniteQuery({ keepPreviousData })` with a scroll-event
        handler that calls `fetchNextPage()` when within 500px of the bottom, plus `manualSorting: true` so
        a new query fires on sort changes.'
      - "Skip dynamic row measurement in Firefox via `measureElement: navigator.userAgent.indexOf('Firefox')
        === -1 ? (el) => el.getBoundingClientRect().height : undefined`."
    correct_pattern: |
      // React row virtualization — virtualizer in deepest possible component.
      import { useVirtualizer } from '@tanstack/react-virtual'

      function App() {
        const tableContainerRef = useRef<HTMLDivElement>(null)
        const table = useTable({
          _features: { rowSortingFeature, columnSizingFeature },
          _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
          columns, data,
        })
        return (
          <div ref={tableContainerRef} style={{ overflow: 'auto', height: 800 }}>
            <table style={{ display: 'grid' }}>
              <thead>{/* sticky header */}</thead>
              {/* ✓ virtualizer in TableBody, not in App */}
              <TableBody table={table} tableContainerRef={tableContainerRef} />
            </table>
          </div>
        )
      }

      function TableBody({ table, tableContainerRef }) {
        const { rows } = table.getRowModel()

        const rowVirtualizer = useVirtualizer({
          count:           rows.length,
          estimateSize:    () => 33,
          getScrollElement: () => tableContainerRef.current,
          measureElement:  typeof window !== 'undefined' &&
                           navigator.userAgent.indexOf('Firefox') === -1
            ? (el) => el.getBoundingClientRect().height
            : undefined,
          overscan: 5,
        })

        return (
          <tbody style={{
            display: 'grid',
            height: `${rowVirtualizer.getTotalSize()}px`,
            position: 'relative',
          }}>
            {rowVirtualizer.getVirtualItems().map((virtualRow) => {
              const row = rows[virtualRow.index]
              return (
                <tr
                  key={row.id}
                  data-index={virtualRow.index}
                  ref={(node) => rowVirtualizer.measureElement(node)}
                  style={{
                    display: 'flex',
                    position: 'absolute',
                    transform: `translateY(${virtualRow.start}px)`,
                    width: '100%',
                  }}
                >
                  {row.getAllCells().map((cell) => (
                    <td key={cell.id}
                        style={{ display: 'flex', width: cell.column.getSize() }}>
                      <table.FlexRender cell={cell} />
                    </td>
                  ))}
                </tr>
              )
            })}
          </tbody>
        )
      }
    wrong_pattern: |
      // BAD #1: virtualizer at the App level. Every state change in App
      // (filter input, sort toggle, anything) re-runs the virtualizer,
      // which loses scroll position and measurement cache.
      function App() {
        const rowVirtualizer = useVirtualizer({...})    // wrong scope
        const table = useTable(...)
        return <TableBody table={table} virtualizer={rowVirtualizer} />
      }

      // BAD #2: rendering rows.map directly when the dataset is large.
      // No virtualization, 200k DOM rows, browser crashes.
      <tbody>{rows.map(row => <tr key={row.id}>...</tr>)}</tbody>

      // BAD #3: missing `display: grid` + absolute positioning. Without the
      // grid layout + translateY, virtual rows stack incorrectly and dynamic
      // row height measurement fails because the rows are still flowing.
      <tbody>
        {rowVirtualizer.getVirtualItems().map(vr => (
          <tr key={vr.key}>{/* no transform, no absolute */}</tr>
        ))}
      </tbody>

      // BAD #4: `measureElement` on Firefox. Firefox measures table-row
      // border height inconsistently — dynamic-height rows jitter on
      // every scroll. Detect and disable measureElement on Firefox.
    failure_modes:
      - Putting `useVirtualizer` in the same component as `useTable`. Any state change in that component re-runs
        the virtualizer, blowing away scroll position and re-measuring everything. Always isolate the virtualizer
        in the deepest body/cell component.
      - 'Forgetting `display: grid` on `<table>` / `<thead>` / `<tbody>`. The semantic table layout collides
        with absolute positioning + `transform: translateY`, producing stacked or overlapping rows.'
      - 'Missing the `translateY(virtualRow.start)` transform. Rows render but all at `top: 0`, so only the
        last few are visible.'
      - Using `measureElement` in Firefox. Firefox returns inconsistent row heights for table rows, causing
        flicker. Guard with `navigator.userAgent.indexOf('Firefox') === -1`.
      - Calling `rowVirtualizer.measureElement(node)` on a stale ref. The pattern is `ref={(node) => rowVirtualizer.measureElement(node)}`
        — passing a stored ref means the virtualizer can't remeasure when the row content changes height.
      - "For column virtualization: forgetting the left/right padding placeholder cells (`virtualPaddingLeft`/`virtualPaddingRight`).
        Without them the visible columns slide left as you scroll, because the unrendered columns aren't
        taking up scroll space."
      - 'For infinite scroll: not setting `manualSorting: true`. The table re-sorts the already-fetched pages
        every time a new page arrives, scrambling the order.'
    experimental_variant:
      examples:
        - examples/react/virtualized-rows-experimental
        - examples/react/virtualized-columns-experimental
      description:
        'Newer pattern: mutate styles on refs directly to skip React reconciliation, yielding
        ~10% rendering perf improvement. Not yet widely used but considered valid. Teach standard pattern
        as default; reference experimental as advanced opt-in.'
  - slug: compose-with-tanstack-form
    type: composition
    domain: composition
    status: ready
    description: |
      Editable cells with TanStack Form. The table is the layout primitive; the form owns the state. Use `createFormHook` to register reusable field components (`TextField`, `NumberField`, `SelectField`), then in each column's `cell` renderer return `<form.AppField name={`data[${row.index}].field`}>{(field) => <field.TextField />}</form.AppField>`. Important typing gotcha: if your row type has a recursive `subRows`, `Omit<Row, 'subRows'>` to a flat shape before passing to the form — TanStack Form's `DeepKeys` chases the recursion and hits TS2589 ("type instantiation is excessively deep"). Subscribe to `form.state.values.data.length` (not the whole array) to trigger re-renders for row add/remove without infinite loops. Pair with TanStack Pacer for debounced filter inputs on the same screen.
    covers:
      - '`createFormHook` + field components attached via `formContext`.'
      - 'Cell renderer pattern: `<form.AppField name={`data[${row.index}].col`}>`.'
      - '`data: form.state.values.data` to feed the table.'
      - Recursive-row TS2589 pitfall — `Omit<Person, 'subRows'>` for the form row type.
      - '`useStore(form.store, (state) => state.values.data.length)` for row add/remove re-renders.'
      - "`form.pushFieldValue('data', newRow)` for add row; `form.reset({ data })` for replace."
      - This pattern is officially the answer to "TanStack Table has no built-in editing" — Kevin explicitly
        scoped editing OUT of v9 core in favor of this composition.
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/react-form'
    tasks:
      - Build an editable people-table where each cell is a `<form.AppField>` bound to `data[${row.index}].firstName`
        etc., with Zod validators per field.
      - "Add an 'Add Row' button using `form.pushFieldValue('data', { firstName: '', ... })` plus subscribe
        to `form.state.values.data.length` so the table re-renders with the new row."
      - Type rows as `Omit<Person, 'subRows'>` to avoid `DeepKeys` recursion (TS2589).
      - Combine with debounced column filters via `useDebouncedCallback` from `@tanstack/react-pacer/debouncer`
        so editing one cell doesn't refilter the table on every keystroke.
    correct_pattern: |
      // 1. Define field components and a form hook (form.tsx)
      const { useAppForm } = createFormHook({
        fieldComponents: { TextField, NumberField, SelectField },
        formComponents:  { SubmitButton, FormStateIndicator },
        fieldContext, formContext,
      })

      // 2. Critical: flatten row type for form path-keys (avoids TS2589)
      type FormRow = Omit<Person, 'subRows'>

      const _features = tableFeatures({ rowPaginationFeature, columnFilteringFeature })
      const columnHelper = createColumnHelper<typeof _features, FormRow>()

      function App() {
        const form = useAppForm({
          defaultValues: { data: makeData(100) as FormRow[] },
          onSubmit: ({ value }) => save(value.data),
        })

        // 3. Bind each cell to a form field
        const columns = useMemo(() => columnHelper.columns([
          columnHelper.accessor('firstName', {
            header: 'First',
            cell: ({ row }) => (
              <form.AppField
                name={`data[${row.index}].firstName`}
                validators={{ onChange: z.string().min(1) }}
              >
                {(field) => <field.TextField />}
              </form.AppField>
            ),
          }),
          // ...
        ]), [form])

        // 4. Subscribe to length only — avoids re-render loops on every keystroke
        const dataLength = useStore(form.store, (s) => s.values.data.length)
        void dataLength

        const table = useTable({
          _features,
          _rowModels: {
            filteredRowModel:  createFilteredRowModel(filterFns),
            paginatedRowModel: createPaginatedRowModel(),
          },
          columns,
          data: form.state.values.data,
        })

        const addRow = () => form.pushFieldValue('data', {
          firstName: '', lastName: '', age: 0, visits: 0, progress: 0, status: 'single',
        })
        // render table + addRow button
      }
    wrong_pattern: |
      // BAD #1: typing rows as `Person` (with subRows) and feeding to
      // useAppForm. TanStack Form's DeepKeys walks subRows recursively.
      // Result: TS2589 "Type instantiation is excessively deep".
      const form = useAppForm({ defaultValues: { data: makeData(100) as Person[] } })
      //                                          ^^^^^^ should be Omit<Person, 'subRows'>

      // BAD #2: subscribing to the whole array. Every keystroke in any cell
      // re-renders App, which recreates the form, which re-binds every cell.
      const data = useStore(form.store, (s) => s.values.data)  // wrong: full array
      // ✓ Fix: useStore(form.store, (s) => s.values.data.length) and rely on
      //   `data: form.state.values.data` to read fresh values on render.

      // BAD #3: passing the table itself as form state. Don't try to mix
      // the table's internal `data` with form values — the form owns
      // editing state; the table just renders.
    failure_modes:
      - Typing rows with a recursive `subRows` field and feeding them to TanStack Form. `DeepKeys` walks the
        recursion and TypeScript reports TS2589. Always `Omit<Row, 'subRows'>` before passing to the form.
      - Subscribing to `form.state.values.data` (the full array) via `useStore`. Every keystroke triggers
        a re-render of every cell. Subscribe to `.data.length` (or a derived count) and rely on table's normal
        rendering for value reads.
      - "Putting `form` itself in `useTable`'s `data` option. The table only needs the rows array — pass
        `data: form.state.values.data`."
      - Forgetting `useMemo` around `columns` (passing `form` as a dep). The field bindings hold a reference
        to `form`, so without memoization you build new column defs every render.
      - Trying to reuse v8's `useReactTable` editable-cell pattern (manual `useState` per cell, `tableMeta.updateData`).
        That still works mechanically, but the `compose-with-tanstack-form` pattern is the v9-blessed approach
        and handles validation/dirty/submit for free.
  - slug: compose-with-tanstack-pacer
    type: composition
    domain: composition
    status: ready
    description: |
      Use `@tanstack/<fw>-pacer` to debounce/throttle the high-frequency writes that drive an interactive table: column filter inputs and column resize state. Pattern: import `useDebouncedCallback` from `@tanstack/react-pacer/debouncer`, wrap your `onChange` writer in it, and keep local state for the input value so typing feels instant. For column resizing, the equivalent is throttling `onColumnResizingChange` so a drag doesn't push 60 state updates a second through the store. Pacer is the v9 replacement for the hand-rolled `DebouncedInput` component that appears in every v8 filtering example — the new pattern keeps the input shape but replaces `setTimeout` plumbing with `useDebouncedCallback`.
    covers:
      - '`useDebouncedCallback(onChange, { wait: 300 })` for filter inputs.'
      - 'Throttling resize: wrap `onColumnResizingChange` (or write to the atom inside a throttled callback)
        so column drags batch updates.'
      - The kitchen-sink and with-tanstack-form examples both use Pacer for filter debouncing — copy that
        pattern.
      - 'When to choose debounce vs throttle: debounce for "stop typing then commit" (filters), throttle for
        "fire at most every N ms" (resize, scroll-triggered fetches).'
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/react-pacer'
      - '@tanstack/pacer'
    tasks:
      - 'Replace a v8-style `setTimeout`-based `DebouncedInput` with `useDebouncedCallback(onChange, { wait:
        300 })`.'
      - Add a 16ms throttle around `onColumnResizingChange` so a 1-second drag emits ~60 updates instead of
        every mousemove.
      - Build a global filter input that updates `state.globalFilter` debounced at 250ms while showing the
        typed value instantly in the input.
    correct_pattern: |
      // Debounced filter input — the v9 idiom
      import { useDebouncedCallback } from '@tanstack/react-pacer/debouncer'

      function DebouncedInput({
        value: initialValue,
        onChange,
        debounce = 300,
        ...props
      }: {
        value: string | number
        onChange: (value: string | number) => void
        debounce?: number
      } & Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange'>) {
        // Local state so the input feels instant even though the writer is debounced.
        const [value, setValue] = React.useState(initialValue)
        React.useEffect(() => { setValue(initialValue) }, [initialValue])
        const debouncedOnChange = useDebouncedCallback(onChange, { wait: debounce })
        return (
          <input
            {...props}
            value={value}
            onChange={(e) => {
              setValue(e.target.value)         // instant UI update
              debouncedOnChange(e.target.value) // debounced state write
            }}
          />
        )
      }

      // Usage in a column filter:
      <DebouncedInput
        value={(column.getFilterValue() ?? '') as string}
        onChange={(v) => column.setFilterValue(v)}
        placeholder="Search..."
      />
    wrong_pattern: |
      // BAD #1: writing `column.setFilterValue` on every keystroke without
      // debouncing. The full row model recomputes on each character —
      // visibly janky for any non-trivial dataset.
      <input onChange={(e) => column.setFilterValue(e.target.value)} />

      // BAD #2: rolling your own setTimeout-based debounce. v8 examples
      // shipped this and v9 explicitly moves it to Pacer.
      function DebouncedInput({ value, onChange, debounce = 300 }) {
        const [v, setV] = useState(value)
        useEffect(() => {
          const t = setTimeout(() => onChange(v), debounce)
          return () => clearTimeout(t)
        }, [v])
        // works, but reinvents what `useDebouncedCallback` already provides
        // with proper cleanup, ref tracking, and consistent API.
      }

      // BAD #3: debouncing the cell render itself instead of the writer.
      // Don't debounce `setFilterValue` AND `setLocalInput` — only the
      // expensive store write needs debouncing.
    failure_modes:
      - Writing filter values directly on every keystroke without debouncing. The whole filtered row model
        recomputes per character — fine for 100 rows, miserable for 10k+.
      - Hand-rolling a `setTimeout`-based debounce instead of `useDebouncedCallback`. Pacer's hook handles
        ref stability, cleanup, and trailing-edge semantics correctly; the hand-rolled version often leaks
        timers on unmount.
      - 'Using `wait: 0` (or omitting `wait`) and expecting debouncing. The default is meaningful — explicit
        `{ wait: 300 }` is the typical sweet spot for filter inputs.'
      - Debouncing the local input state instead of the store write. The user sees stale characters in the
        input box. Local state should be instant; only the store write should debounce.
      - Throttling at 250ms for column resize. Too long — drag feels laggy. Use a 16ms throttle (roughly one
        frame) for resize.
      - Wrapping `column.setFilterValue` directly in `useDebouncedCallback` without a local input state. The
        input becomes uncontrolled-feeling because React renders go through the slow debounced path.
  - slug: compose-with-tanstack-devtools
    type: composition
    domain: composition
    status: ready
    description: |
      Install the framework's TanStack Devtools host + the matching table adapter, mount `<TanStackDevtools plugins={[tableDevtoolsPlugin()]} />` once at the app root, and call `useTanStackTableDevtools(table, name?)` immediately after each `useTable`. Devtools shows registered tables (with a selector if multiple are named), live state, options, rows, columns, and features. By default devtools are dev-mode only — the framework adapter ships no-op exports when `process.env.NODE_ENV !== 'development'`. If you need live devtools in production, import from the `/production` entrypoint instead (`@tanstack/react-table-devtools/production`, `/vue-table-devtools/production`, `/solid-table-devtools/production`, `/preact-table-devtools/production`). Only React, Vue, Solid, and Preact ship dedicated table devtools adapters — Angular, Svelte, Lit, and vanilla do not.
    covers:
      - Installing host + adapter (`@tanstack/<fw>-devtools` + `@tanstack/<fw>-table-devtools`).
      - Mounting `<TanStackDevtools plugins={[tableDevtoolsPlugin()]} />` once.
      - '`useTanStackTableDevtools(table, name?)` per table. Multi-table selector activates when you pass
        distinct names.'
      - "Dev/prod gating: `process.env.NODE_ENV !== 'development'` swaps the entire module to no-op exports
        automatically."
      - '`/production` entrypoints for opting devtools into production.'
      - 'Where to expect them: React in `examples/react/row-selection`, Preact in `examples/preact/sorting`,
        Solid in `examples/solid/row-selection`, Vue in `examples/vue/row-selection`.'
      - 'Frameworks WITHOUT a table devtools adapter: Angular, Svelte, Lit, vanilla. They have to either ship
        a generic devtools or wait for adapter coverage.'
    packages:
      - '@tanstack/react-table-devtools'
      - '@tanstack/vue-table-devtools'
      - '@tanstack/solid-table-devtools'
      - '@tanstack/preact-table-devtools'
      - '@tanstack/table-devtools'
    tasks:
      - Install `@tanstack/react-devtools` + `@tanstack/react-table-devtools`, mount `<TanStackDevtools plugins={[tableDevtoolsPlugin()]}
        />` at the root, and register a single table with `useTanStackTableDevtools(table, 'Users')`.
      - Register multiple tables (`Users`, `Orders`, `Products`) so the devtools shows a selector — pass distinct
        names to each `useTanStackTableDevtools` call.
      - Enable devtools in a production build by importing from `@tanstack/react-table-devtools/production`
        instead of the default entrypoint.
      - "Conditionally disable a registration with the `options.enabled` flag: `useTanStackTableDevtools(table,
        'Users', { enabled: showDevtools })`."
    correct_pattern: |
      // React setup (production-safe by default — no-op outside dev)
      import { TanStackDevtools } from '@tanstack/react-devtools'
      import {
        tableDevtoolsPlugin,
        useTanStackTableDevtools,
      } from '@tanstack/react-table-devtools'

      function App() {
        const usersTable = useTable({...})
        useTanStackTableDevtools(usersTable, 'Users')

        const ordersTable = useTable({...})
        useTanStackTableDevtools(ordersTable, 'Orders')

        return <AppContent />
      }

      ReactDOM.createRoot(rootElement).render(
        <React.StrictMode>
          <App />
          {/* Mounted ONCE at the root */}
          <TanStackDevtools plugins={[tableDevtoolsPlugin()]} />
        </React.StrictMode>,
      )

      // === Vue setup ===
      // <script setup>
      // const table = useTable({...})
      // useTanStackTableDevtools(table, 'Users')
      // </script>
      // Then in main.ts mount <TanStackDevtools plugins={[tableDevtoolsPlugin()]} />
      // at the root Component via h() or a wrapping defineComponent.
    wrong_pattern: |
      // BAD #1: forgetting `<TanStackDevtools ... />` at the root.
      // `useTanStackTableDevtools(table)` registers the table but there's
      // no plugin host to render the panel — devtools appears to do
      // nothing. The host MUST be mounted.

      // BAD #2: mounting `<TanStackDevtools ... />` inside a route component
      // that unmounts when navigating. The plugin host disappears; all
      // table registrations stop being visible.

      // BAD #3: calling useTanStackTableDevtools(table) BEFORE useTable
      // returns. The order is `const table = useTable(...)` then
      // `useTanStackTableDevtools(table, 'Name')`.

      // BAD #4: importing from `@tanstack/react-table-devtools` (default
      // entrypoint) and expecting it to work in production. The default
      // entrypoint swaps to no-op when NODE_ENV !== 'development'.
      // For prod, import from `/production`:
      import { tableDevtoolsPlugin, useTanStackTableDevtools }
        from '@tanstack/react-table-devtools/production'

      // BAD #5: trying to import `@tanstack/angular-table-devtools` or
      // `@tanstack/svelte-table-devtools`. Those don't exist — only React,
      // Vue, Solid, Preact ship table devtools adapters.
    failure_modes:
      - Forgetting to mount `<TanStackDevtools plugins={[tableDevtoolsPlugin()]} />` at the root. The hook
        registers tables but there's no panel host to render them.
      - Mounting the devtools host inside a route-scoped component that unmounts on navigation. The panel
        disappears whenever the user leaves that route.
      - Importing from the default entrypoint and expecting prod visibility. The default swaps to no-op exports
        outside `development` — use `@tanstack/<fw>-table-devtools/production` for prod.
      - Calling `useTanStackTableDevtools` before `useTable` returns. Order matters — declare the table first,
        then register it.
      - Trying to use this skill in Angular / Svelte / Lit / vanilla. No table devtools adapter exists for
        those frameworks yet; only React, Vue, Solid, and Preact are covered.
      - Skipping the `name` argument with multiple tables. Anonymous tables get auto-assigned labels like
        `Table 1`, `Table 2`, which are useless when debugging. Always pass a meaningful name.
  - slug: compose-with-tanstack-hotkeys
    type: composition
    domain: composition
    status: deferred-to-v1.1
    gap: true
    description: |
      Accessible keyboard navigation for table interactions (cell focus, row selection, sort/filter triggers, pagination, etc.) via TanStack Hotkeys. *** STATUS: GAP — Phase 4 question for Kevin. *** There is no documented integration pattern for `@tanstack/hotkeys` + TanStack Table v9 in this repo at the time of writing (no docs, no examples, no grep hits for "hotkeys" anywhere under `examples/`, `packages/`, or `docs/`). Kevin needs to supply: (a) the canonical key map expectations (arrow-key cell nav? space/enter to toggle row selection? home/end to jump to first/last row? alt+arrow to change sort?), (b) which surface owns the key handlers (the `<table>` element, the row, the cell?), and (c) how focus management interacts with `table.Subscribe` re-renders and TanStack Virtual's `getVirtualItems()` reordering.
    covers:
      - PLACEHOLDER — pending pattern from Kevin.
    packages:
      - '@tanstack/react-table'
      - '@tanstack/vue-table'
      - '@tanstack/angular-table'
      - '@tanstack/solid-table'
      - '@tanstack/svelte-table'
      - '@tanstack/preact-table'
      - '@tanstack/hotkeys'
    tasks:
      - '[GAP] Wire arrow-key cell navigation across a virtualized table without losing focus when rows are
        recycled by the virtualizer.'
      - '[GAP] Bind space/enter to toggle row selection via `row.getToggleSelectedHandler()` while respecting
        `enableRowSelection` per-row predicates.'
      - '[GAP] Provide alt+arrow shortcuts to change column sort direction equivalent to clicking the header.'
    correct_pattern: |
      // PLACEHOLDER — Kevin needs to supply the canonical pattern.
      // Open questions:
      //   1. Where do hotkey handlers attach? `<table>`, `<tr>`, or a wrapping div?
      //   2. How is "active cell" represented? Add a new state slice? Use existing focus?
      //   3. How does focus survive a virtualizer recycling the focused row?
      //   4. Does `<table.Subscribe>` cause focus loss on re-render? (Likely yes
      //      if the focused element is re-keyed.)
    wrong_pattern: |
      // PLACEHOLDER — without canonical guidance, agents will reach for ad-hoc
      // `useEffect(() => document.addEventListener('keydown', ...))` patterns
      // which:
      //   - leak listeners on remount,
      //   - conflict with row-virtualizer focus management,
      //   - bypass accessibility expectations (no roving tabindex, etc.).
      // None of those are the answer; Kevin needs to bless the right shape.
    failure_modes:
      - '[GAP] No documented v9 pattern exists at the time of skill authoring — `@tanstack/hotkeys` has no
        integration guide, examples, or tests with TanStack Table v9. This skill is a placeholder.'
      - "[GAP] Without canonical guidance, agents will reach for `useEffect(() => document.addEventListener('keydown',
        ...))` which conflicts with virtualization, leaks listeners, and bypasses accessibility expectations
        (roving tabindex, ARIA grid semantics)."
      - '[GAP] Open question: how does keyboard focus survive virtualized row recycling? The focused row may
        scroll out of view and be unmounted; the hotkey state needs to be decoupled from DOM focus.'
    open_questions:
      - Which key bindings are 'standard'? (arrow nav, space/enter selection, home/end, alt+arrow sort, esc
        to clear filter, /-key to focus filter?)
      - Does focus live in the table store (as a new slice) or stay in DOM focus only?
      - How does the pattern interact with TanStack Virtual — specifically, what happens when the focused
        row is recycled?
      - Are there per-framework differences in how hotkeys integrate? (Angular has its own focus-management
        primitives; Svelte 5 has runes; Lit has its own event system.)
      - Should there be a `hotkeysFeature` plugin-style feature that other features can hook into, similar
        to how `rowSelectionFeature` exposes `getToggleSelectedHandler()`?
    deferral_reason:
      Maintainer (Kevin Vandy) is preparing a with-tanstack-hotkeys example. Skill will ship
      in v1.1 once the canonical wiring is documented.
tensions:
  - name: getting-started simplicity vs production correctness
    skills:
      - getting-started
      - production-readiness
    description:
      The first-table tutorial uses the default `(state) => state` selector and no Subscribe
      wrappers, which is correct for small tables but causes whole-table re-renders on any state change.
    implication:
      Agents copy the getting-started pattern verbatim into 10k-row tables and ship slow code,
      blaming the library rather than the selector. Conversely, agents loading production-readiness first
      add Subscribe boundaries to trivial tables that never needed them.
  - name: client-side feature richness vs server-side correctness
    skills:
      - filtering
      - sorting
      - pagination
      - client-to-server
    description:
      TanStack Table supports both fully-client and fully-server pipelines per feature via `manual<Feature>`
      flags. Half-converted tables (server-side pagination + client-side filtering) silently produce wrong
      results because the server returns a paginated subset that the client then filters again.
    implication:
      Agents converting a working client table to use a server endpoint flip `manualPagination`
      without auditing filtering/sorting consistency. End-user sees correct rows but wrong totals, or vice
      versa.
  - name: atomic-state granularity vs API simplicity
    skills:
      - state-management
      - compose-with-tanstack-store
      - getting-started
    description:
      External atoms (`useCreateAtom` + `options.atoms`) are the lowest-friction integration
      for server-side state, but force the developer to learn TanStack Store concepts. Classic `state` +
      `on*Change` is familiar but coarser-grained and harder to share with other parts of the app.
    implication:
      Agents default to `state` + `on*Change` because it looks like the v8 idiom, then hit re-render
      storms or sync issues with Query and patch around them, when the v9 atoms option would have been cleaner.
  - name: React Compiler safety vs render-cost simplicity
    skills:
      - react-subscribe-compiler-compat
      - production-readiness
      - getting-started
    description:
      Without React Compiler, inline header/cell rendering works without `<Subscribe>`. Once
      React Compiler is enabled, nested header/cell components that read state through builder APIs (column.getIsPinned,
      row.getIsSelected, etc.) get memoized incorrectly, producing stale UI.
    implication:
      'Agents either over-wrap every component in Subscribe (verbose, slow to author) or under-wrap
      and ship tables that look fine in dev but break under React Compiler in prod. Symptoms: stale checkboxes,
      frozen sort indicators, broken pin buttons.'
  - name: tree-shaking via _features vs ergonomic useLegacyTable
    skills:
      - setup
      - production-readiness
      - migrate-v8-to-v9
    description:
      '`useLegacyTable` (from `@tanstack/react-table/legacy`) lets v8 code keep working without
      declaring `_features`/`_rowModels`, but bundles every feature regardless of use.'
    implication:
      Agents reach for `useLegacyTable` on v8→v9 migrations and never circle back to declare
      `_features`, sacrificing the bundle wins that motivated the v9 redesign.
cross_references:
  - from: setup
    to: state-management
    reason:
      state-management is the prerequisite for every other skill; setup users will need it as soon
      as they touch initialState or controlled state
  - from: state-management
    to: compose-with-tanstack-store
    reason: external atoms are the recommended state ownership pattern for server-side work
  - from: state-management
    to: migrate-v8-to-v9
    reason:
      state model is the biggest v8→v9 shift; migration explanation depends on the v9 atom mental
      model
  - from: filtering
    to: sorting
    reason: filter→sort handoff via addMeta + columnFiltersMeta (e.g. itemRank for fuzzy)
  - from: filtering
    to: customizing-feature-behavior
    reason: custom filterFn / globalFilterFn
  - from: sorting
    to: customizing-feature-behavior
    reason: custom sortFn — especially when combined with fuzzy filter rank
  - from: grouping
    to: customizing-feature-behavior
    reason: custom aggregationFn
  - from: grouping
    to: row-expanding
    reason: grouped rows expand via the row-expanding feature; both are required together
  - from: grouping
    to: row-selection
    reason: getGroupedSelectedRowModel + selection state interpretation inside groups
  - from: row-expanding
    to: filtering
    reason: filterFromLeafRows + maxLeafRowFilterDepth interactions
  - from: row-expanding
    to: pagination
    reason: paginateExpandedRows controls whether expanded rows respect page boundaries
  - from: pagination
    to: row-selection
    reason:
      manualPagination + selection state — getSelectedRowModel only returns rows in current page when
      manual
  - from: column-layout
    to: grouping
    reason: groupedColumnMode reorders columns; affects column layout precedence
  - from: row-selection
    to: column-definitions
    reason: tristate parent checkbox patterns + getRowId requirement for stable selection
  - from: client-to-server
    to: compose-with-tanstack-query
    reason: Query is the canonical server-side fetch layer; client-to-server skill expects it
  - from: client-to-server
    to: state-management
    reason:
      external atoms via atoms option is the cleanest pattern for sharing pagination/sort/filter with
      Query
  - from: production-readiness
    to: react-subscribe-compiler-compat
    reason: Subscribe boundaries are a top perf optimization on React
  - from: production-readiness
    to: setup
    reason: '`_features` tree-shaking is decided at setup'
  - from: compose-with-tanstack-virtual
    to: row-expanding
    reason: virtualized + expanding requires careful measurer + getSubRows interaction
  - from: compose-with-tanstack-virtual
    to: column-layout
    reason: virtualized columns interact with sizing and pinning
  - from: compose-with-tanstack-form
    to: row-selection
    reason: editable rows + selection — common together
  - from: compose-with-tanstack-devtools
    to: state-management
    reason: devtools surface the atoms model; understanding state-management makes devtools readable
  - from: migrate-v8-to-v9
    to: setup
    reason: v9 setup IS the migration target
  - from: migrate-v8-to-v9
    to: column-definitions
    reason: createColumnHelper generic order changed in v9
  - from: migrate-v8-to-v9
    to: filtering
    reason: sortingFn → sortFn rename; filterFn registry semantics
  - from: react-subscribe-compiler-compat
    to: column-definitions
    reason: header/cell render fns are the main location where Subscribe is needed
  - from: angular-rendering-directives
    to: table-state
    reason: Angular rendering depends on the signal-backed state model unique to that adapter
  - from: lit-table-controller
    to: table-state
    reason: Lit reactivity is owned by TableController; table-state mental model relies on that
reference_candidates:
  - skill: customizing-feature-behavior
    topic: Built-in filter/sort/aggregation function registry
    rationale:
      Twelve built-in filterFns, six sortFns, and nine aggregationFns are documented with subtle
      semantics (autoRemove, resolveFilterValue, leaf vs child rows for aggregation). A single reference
      table comparing input shape, comparison operator, falsy handling, and resolveFilterValue mapping would
      save agents from picking the wrong name.
    source:
      packages/table-core/src/fns/filterFns.ts:394-407; packages/table-core/src/fns/sortFns.ts:209-218;
      packages/table-core/src/fns/aggregationFns.ts:249-261
gaps:
  - skill: state-management
    question:
      When `atoms.x` is registered, does calling `table.resetX()` reset the external atom or only
      the baseAtom? Docs say "Slice reset APIs ... can update an externally owned atom" but the precise
      dispatch path is not source-cited.
    context:
      Need a definitive snippet from the rowSorting/columnFiltering reset utils confirming external-atom-aware
      resets, otherwise the failure mode for `table.reset()` needs sharper distinction from per-feature
      reset.
    status: open
  - skill: state-management
    question:
      Is there a runtime warning when `state.x` and `atoms.x` are both supplied? Source shows silent
      precedence (atom wins) — should an agent emit a dev-mode warning in their generated code, or is that
      the library's job?
    context:
      CRITICAL failure mode for "both ownership paths". If Kevin plans to add a dev warning soon,
      the failure mode wording should hedge ("future versions may warn").
    status: open
  - skill: setup
    question:
      For vanilla JS (`@tanstack/table-core` direct), is `storeReactivityBindings()` strictly required,
      or is there a no-reactivity path? `constructTable` reads `tableOptions._features.coreReativityFeature`
      unconditionally — implies required, but want to confirm.
    context:
      Affects the vanilla failure mode set. Currently I have not added a failure mode for "uses constructTable
      without storeReactivityBindings" — would do so if confirmed required.
    status: open
  - skill: customizing-feature-behavior
    question:
      Are `filterFn.autoRemove` and `filterFn.resolveFilterValue` part of the recommended public
      surface for custom fns, or implementation detail? Built-ins use them heavily but no narrative doc
      walks through writing them.
    context:
      If they're recommended, the "Customizing Feature Behavior" skill should cover them. If implementation-detail,
      they should be reference-only.
    status: open
  - skill: column-definitions
    question:
      For deep keys like `"name.first"`, does dev-mode warning on undefined ever fire in production
      builds? Source shows guarded by `process.env.NODE_ENV === 'development'` — confirm tree-shaken in
      prod.
    context: Want to be precise about debug-only warnings in skill text.
    status: resolved
    resolution: '4b-G9: as designed'
  - issue: Phase 1+2 anchor inaccuracies
    detail:
      "Phase 1+2 notes say '10 built-in filterFns', '6 built-in sortFns', '8 built-in aggregationFns'.
      Actual counts from source registry: 12 filterFns (registry includes arrHas, between, betweenInclusive
      beyond the 10 documented), 6 sortFns ✓, 9 aggregationFns. Need maintainer review."
  - issue: v9 sortFn auto-detection samples flatRows.slice(10)
    detail:
      packages/table-core/src/features/row-sorting/rowSortingFeature.utils.ts:94
      reads `getFilteredRowModel().flatRows.slice(10)` — note this is `.slice(10)` not `.slice(0, 10)`.
      It skips the first 10 rows. Likely a bug or oversight. Worth flagging.
  - issue: Three selected-row-model APIs appear functionally identical in source
    detail:
      '`table_getSelectedRowModel`, `table_getFilteredSelectedRowModel`, and `table_getGroupedSelectedRowModel`
      all call `selectRowsFn(table.getCoreRowModel())` (rowSelectionFeature.utils.ts:173-244). The function
      bodies are the same except for comments. Per docs row-models.md they should dispatch on filtered/grouped
      models. Either documentation is aspirational or implementation is stubbed.'
  - issue: v9 createColumnHelper signature change
    detail:
      v9 requires `createColumnHelper<typeof _features, TData>()` — TFeatures FIRST. v8 was `createColumnHelper<TData>()`.
      Every cluster-B example confirms this pattern (filters, filters-faceted, filters-fuzzy, sorting, pagination,
      grouping, expanding, sub-components all use `<typeof _features, Person>`).
  - issue: 'Framework variation: Vue/Svelte/Solid/Angular use signal/reactive data getter'
    detail: |
      React: `useTable({ data, columns, ... })` — data is a value.
      Vue: `useTable({ get columns() { return columns.value }, data, ... })` — getter for reactivity.
      Solid: `createTable({ get data() { return data() }, columns, ... })` — getter against signal.
      Svelte: `createTable({ get data() { return data }, ... })` — getter against $state rune.
      Angular: `injectTable(() => ({ data: this.data(), columns, ... }))` — whole config is a factory.
      All use the same `tableFeatures({ ... })` and `_rowModels` shapes. The reactive plumbing differs.
  - issue: Faceting requires THREE row models in lockstep
    detail:
      createFacetedRowModel() is the base; createFacetedUniqueValues() and createFacetedMinMaxValues()
      both depend on it (column_getFacetedUniqueValues / column_getFacetedMinMaxValues both call column_getFacetedRowModel
      internally for the memoDep). Phase 1+2 note flagged this as 'agents commonly forget the base faceted
      row model'. Confirmed by reading source.
  - issue: fuzzy filter and addMeta parameter is optional
    detail:
      "FilterFn signature: `(row, columnId, filterValue, addMeta?: (meta: FilterMeta) => void) =>
      boolean`. The 4th arg is OPTIONAL (`addMeta?:`). The fuzzy filter example uses `addMeta?.({ itemRank
      })` with optional chaining. But createFilteredRowModel ALWAYS passes a real addMeta function (createFilteredRowModel.ts:131-135
      and 150-154). So in practice the `?.` is unnecessary defensiveness — but it's idiomatic in examples."
  - issue: manual* flags are mutually independent — agents try to combine them
    detail:
      "manualFiltering, manualSorting, manualGrouping, manualExpanding, manualPagination can each
      be set independently. They each cause the corresponding row model to be SKIPPED (the pre-* model is
      returned instead). Order still applies: manualFiltering doesn't skip grouping. Agents sometimes think
      'manual everything' means 'use raw data as-is' — but if you set manualFiltering + manualSorting
      but NOT manualPagination, the table still paginates the raw data."
  - skill: table-state (Angular)
    question:
      Is there a recommended pattern for using TanStack Store external atoms with Angular signals
      end-to-end, or do users always go through state + on[State]Change with signals?
    context:
      The Angular guide explicitly downplays atoms in favor of signals, but does not show an atoms+useSelector-equivalent
      flow. Maintainers may want a clearer recommendation.
    status: open
  - skill: lit-table-controller
    question:
      Should TableController.Subscribe with a source eventually wire independent host invalidation,
      or is the docs note the long-term contract?
    context:
      TableController.ts comments call this out as 'can be added later'. Without a decision, Lit
      users cannot rely on source-only invalidation for perf optimization.
    status: resolved
    resolution: '4b-G8: Lit adapter being rewritten during beta'
  - skill: react-subscribe-compiler-compat
    question: When the agent emits `table.getState().X` in render, is that wrong?
    context: |
      Across issues #5567, #6137, #6224, and #6230, the recurring failure mode is reading
      table state directly during render in v9 alpha and not subscribing. The skill MUST
      teach: in v9, prefer `<table.Subscribe selector={...}>` for any state the UI
      depends on; `table.getState()` reads are point-in-time and don't trigger re-renders.
      Also: cell/header contexts currently type `table` as the base `Table` (issue #6230),
      so any cell using Subscribe needs to cast to ReactTable until upstream is fixed.
    status: open
  - skill: migrate-v8-to-v9
    question: How do v8 `getCoreRowModel()` / `getSortedRowModel()` etc. map to v9?
    context: |
      No issue yet asks this verbatim because v9 is alpha and adoption is small, but
      every adoption issue shows the same disorientation. The skill needs a 1:1 mapping
      table from v8 imports to v9 feature/row-model imports, plus a "minimum boilerplate"
      example showing _features and the tableFeatures registry.
    status: open
  - skill: migrate-v8-to-v9
    question: How do I convert a v8 useReactTable site to v9 useTable + Subscribe?
    context: |
      Issues #6199, #6224, #6230, #6236 all show users porting v8 patterns and hitting
      Subscribe-flavored gotchas. A side-by-side migration recipe (basic table → server
      table → row selection → editable cells) would absorb most of these.
    status: open
  - skill: composable-tables
    question: When should I use createTableHook vs useTable directly?
    context: |
      v9 adds `createTableHook` (React/Solid) for ergonomic composition: `<table.AppTable>`,
      pre-configured `_features`, etc. Issues #6199 and #6244 reference it but no skill
      content covers the trade-offs vs the bare `useTable` API. Agents won't know when
      `createTableHook` is appropriate.
    status: open
  - skill: angular-rendering-directives
    question: How do I correctly render Angular components from cells / handle signals?
    context: |
      Issues #6159, #5767, #5774 collectively reveal the Angular reactivity story is
      fragile. The skill should: (a) require columns be hoisted outside `createAngularTable`
      options to avoid remounts, (b) document `injectFlexRenderContext` reactive semantics,
      (c) cover library/monorepo TS4023 type leakage.
    status: open
  - skill: rendering
    question: How do I write a performant Svelte 5 table without mergeObjects chain growth?
    context: |
      Issue #6235 is open in alpha.32 with a detailed root-cause analysis. Until upstream
      fix lands the skill MUST teach the `mergeOptions` override workaround. Also Svelte 5
      reactivity gotchas: function-form options, $derived for pageCount, etc.
    status: open
  - skill: compose-with-tanstack-virtual
    question: How do I combine TanStack Table v9 with TanStack Virtual safely?
    context: |
      Issues #4929, #5162, #6243 show infinite loops and freezes when combining row models
      with virtual scrolling / Suspense. The skill needs a tested baseline recipe for the
      common combo: virtual rows + filter + sort. Server pagination + virtual is a
      separate (and even thornier) case.
    status: open
  - skill: state-management
    question: What is the "controlled vs uncontrolled" model in v9?
    context: |
      Issue #4764 ("controlled / uncontrolled state the treatment of undefined") and many
      pagination issues hinge on whether `state.X` being `undefined` means uncontrolled vs
      explicitly cleared. v9 alpha changes how state slices are stored (atoms vs single
      store) but the controlled/uncontrolled contract isn't documented for the new API.
    status: open
  - skill: row-selection
    question: How do I implement "tristate parent + selectable leaves" UX?
    context: |
      Issues #4878 (20 comments), #4759 (8 comments), #4349 — the "indeterminate parent /
      check all children" pattern is the most-asked row-selection question and the docs
      don't have a worked example. Skill needs a copy-pasteable recipe using
      `getLeafRows()` + manual tristate.
    status: open
  - skill: pagination
    question: How do I avoid the autoResetPageIndex + deep-linking trap?
    context: |
      Issue #6207 documents a real bug: `_autoResetPageIndex` calls `resetPageIndex()`
      without `true`, so after filtering the page resets to whatever `initialState.pageIndex`
      was (often a URL-restored value). Skill should warn users deep-linking pageIndex.
    status: open
  - skill: setup
    question: What stability requirements do v9 options have?
    context: |
      Issue #5141 asks this for v8; nothing answers it for v9. v9 makes `data`/`columns`
      readonly (PR #6183) but the agent-facing skill needs to declare the stability
      matrix explicitly: `data`, `columns`, `state.X`, `onXChange`, `meta` —
      memoize-required vs no-need vs irrelevant.
    status: open
  - skill: customizing-feature-behavior
    question: How do I author or extend a custom TableFeature in v9?
    context: |
      Issue #6220 shows users hitting TS4023 trying to compose features. No agent-facing
      skill exists for "create a custom feature" or "extend an existing feature behavior"
      — yet this is the core v9 design pivot. We need a skill specifically for feature
      authoring.
    status: open
  - skill: compose-with-tanstack-form
    question: How do I put editable form inputs in cells without losing focus?
    context: |
      Issues #4794 (20 comments), #6229, #6199 — editable cells with React form state are
      the long-tail UX. The skill should compose Table + Form to give users a non-remount
      pattern. v9 Subscribe enables this; v8 needed elaborate React.memo gymnastics.
    status: open
  - skill: production-readiness
    question: What memory / performance guardrails should I check before shipping?
    context: |
      Issue #6170 (memory leak in getFilteredRowModel), #6235 (Svelte quadratic), #4794
      (editable rerenders), #6243 (Suspense freeze) — multiple pre-prod gotchas. Skill
      should include a checklist: stable refs, memoized columns, row-key strategy,
      virtual scroll cutover thresholds, devtools profiling steps.
    status: resolved
    resolution: '4b-G9: as designed'
issue_findings_summary:
  count: 32
  top_themes:
    - Which props need to be stable / when to memoize
    - How do I migrate from v8 useReactTable to v9 useTable?
    - Row selection with grouped/nested rows is unintuitive
    - Server pagination + row selection state management
    - createColumnHelper TypeScript fights
    - Cell components lose focus / remount on every keystroke
    - Angular flexRender remount + signal interop
    - Svelte 5 reactivity + Svelte versions
    - Infinite loops when combining virtual scrolling and other features
    - Global and column filter edge cases (null, objects, types)
maintainer_interview:
  date: '2026-05-17'
  interview_style: single consolidated pass (per maintainer preference)
  answers:
    4a-DR1: Rename column-layout display name to "Column Layout Features". Keep slug.
    4a-DR2: Nothing further on failure modes.
    4a-DR3: Tensions look good.
    4b-G1:
      docs are out of date. New filterFns added recently and more may follow. Skills should NOT cite
      a number.
    4b-G2: Same — do not cite a number of aggregationFns. List is open-ended.
    4b-G3:
      column_getAutoSortFn .slice(10) is likely a bug; will fix later. Note in gaps; not a failure
      mode.
    4b-G4: Three selectedRowModel APIs dispatching to the same internal fn is as designed.
    4b-G5: 'useLegacyTable: stays in v9 as deprecated through entire v9 line. Removed in v10.'
    4b-G6:
      with-tanstack-hotkeys example is coming. Defer the compose-with-tanstack-hotkeys skill to v1.1;
      do not ship in v1.
    4b-G7:
      Signal-based adapters (Solid, Angular, Svelte) support BOTH native framework state and TanStack
      Store atoms equally. Most developers will prefer native state in signal frameworks; skill content
      should accommodate and encourage native-state patterns over atoms in those frameworks.
    4b-G8:
      Lit adapter will be rewritten with TanStack Lit Store during beta. Lit-specific skills should
      note "subject to change in beta" rather than over-specify current contract.
    4b-G9: Devtools production pattern is as designed.
    4b-G10:
      Non-React adapter docs are intentionally thinner. React Compiler is what made React complicated.
      Subscribe matters less in signal-based adapters because they re-evaluate dependent reads.
    4c-AI1:
      'TOP failure mode: AI agents hallucinate "react-table v7" patterns or earlier @tanstack/[framework]-table
      API names. Every major version has been a substantial upgrade. Migration skill MUST be loud about
      NOT using v7/v8 API shapes.'
    4c-AI2:
      'TOP failure mode: AI agents write too much code and reimplement what TanStack Table already
      provides. TanStack Table IS a state-management coordinator with built-in APIs for nearly every state
      transition (setSorting, toggleSelected, nextPage, etc.). Agents should USE these instead of writing
      their own.'
    4c-AI3:
      state + on*Change is intentionally redundant with atoms — kept as backward-compat for what
      users expect. Some duplication is intentional, not misleading.
    4c-AI4: No specific concern.
    4d-IK1:
      Do NOT prematurely optimize re-renders with custom selectors for small tables. Advanced state-management
      patterns are for advanced use cases.
    4d-IK2:
      'Including unused features (or all stockFeatures) and unused client-side row models is wasteful.
      Skills should teach: register only what you use.'
    4d-IK3-a:
      Stable `data` and `columns` references — most-asked confusion despite docs coverage in FAQ
      + data guide.
    4d-IK3-b:
      'v9-SPECIFIC HIGH-FREQUENCY confusion: missing APIs / state slices when `_features` does
      not include the relevant feature. v9 is the first version where this matters for TypeScript inference
      and runtime API exposure.'
    4d-IK4:
      Would like to drop accessorKey in favor of accessorFn + id, but accessorKey with deep keys
      is too widely loved. Possible v10 simplification.
    4e-C1:
      'examples/react/with-tanstack-query EXISTS — canonical pattern uses useCreateAtom for pagination,
      atoms option, manualPagination, queryKey including pagination, placeholderData: keepPreviousData,
      defaultData memoized empty fallback.'
    4e-C2:
      Experimental virtualization examples eke out ~10% by mutating styles on refs directly, skipping
      React reconciliation. New pattern; not widely used yet but valid.
    4e-C3:
      'TanStack Pacer in Table context: debouncing and throttling — those two are the main uses.
      Apply where you need them.'